Setup MkDocs (#42)

* doc : add kdoc to validables

* doc : generate markdown with dokka

* doc : add kdoc to validables

* doc : generate markdown with dokka

* doc : remove dokka

* doc : remove dokka

* doc : setup mkdocs

* doc : (wip) cardscheme

* mkdoc for all remaining validables

* mkdoc site

* remove the site folder

* remove useless dokka files

* fix detekt rule violation

.github/workflows/Build.yaml → .github/workflows/build.yaml

@@ -1,4 +1,4 @@
-name: Build
+name: build
 
 on:
   push:

.github/workflows/doc.yaml

@@ -0,0 +1,28 @@
+name: doc
+on:
+  push:
+    branches:
+      - master
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

LICENSE

@@ -1,21 +1,13 @@
-MIT License
+Copyright 2024 Devscast
 
-Copyright (c) 2021 Devscast
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+   http://www.apache.org/licenses/LICENSE-2.0
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

detekt/config.yml

@@ -578,8 +578,8 @@ style:
         value: 'FIXME:'
       - reason: 'Forbidden STOPSHIP todo marker in comment, please address the problem before shipping the code.'
         value: 'STOPSHIP:'
-      - reason: 'Forbidden TODO todo marker in comment, please do the changes.'
-        value: 'TODO:'
+#      - reason: 'Forbidden TODO todo marker in comment, please do the changes.'
+#        value: 'TODO:'
     allowedPatterns: ''
   ForbiddenImport:
     active: false

docs/coc.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

docs/index.md

@@ -0,0 +1,85 @@
+# Validable
+
+![kotlin-version](https://img.shields.io/badge/kotlin-1.9.20-blue)
+[![](https://jitpack.io/v/devscast/validable.svg)](https://jitpack.io/#devscast/validable)
+[![Build](https://github.com/devscast/validable/actions/workflows/Build.yaml/badge.svg)](https://github.com/devscast/validable/actions/workflows/build.yaml)
+
+Validating text fields when using jetpack compose can sometimes be challenging and verbose.
+
+Validable is an extensible library that allows you to validate your text fields in a simpler way while having a reusable code.
+
+```kotlin  
+@Composable  
+fun MyScreen() { 
+
+     val emailField = remember { EmailValidable() }  
+
+	TextField(  
+	    value = emailField.value,
+	    onValueChange = { emailField.value = it }, // update the text  
+	    isError = emailField.hasError(), // check if the field is not valid    
+	)  
+
+	AnimatedVisibility(visible = emailField.hasError()) {
+
+	    Text(
+                text = emailField.errorMessage ?: "",
+            	modifier = Modifier.fillMaxWidth(),
+            	style = LocalTextStyle.current.copy(color = MaterialTheme.colors.error)
+	    )
+
+	}  
+
+	Button(onClick = {  
+	    // pass all fields to the withValidable method 
+	    withValidable(emailField) {  
+
+		// will be executed if all fields are valid 		
+		Toast.makeText(context,"All fields are valid",Toast.LENGTH_SHORT).show() 
+
+		} 
+	}) { 
+		Text(text = "Submit") 
+	}  
+}  
+```
+
+## Installation
+
+**Step 1.** Add the JitPack repository to your build file
+
+Add it in your root build.gradle at the end of repositories:
+
+```groovy
+allprojects {
+    repositories {
+        ...
+        maven { url 'https://jitpack.io' }
+    }
+}
+```
+
+**Step 2.** Add the dependency
+
+```groovy
+dependencies {
+    implementation 'com.github.devscast:validable:x.y.z'
+}
+```
+
+License
+--------
+
+    Copyright 2024 Devscast Community.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.

docs/validables/cardscheme.md

@@ -0,0 +1,24 @@
+Validates that a card number belongs to a specified scheme.
+
+```kotlin  
+
+// Validate if a text is a MasterCard number
+val cardField = CardSchemeValidable(
+        CardScheme.MasterCard,
+        "Only MasterCard is supported"
+)
+
+// Supporting multiple cardScheme
+val multipleCardField = CardSchemeValidable(
+        CardScheme.MasterCard,CardScheme.Visa,
+        "Only MasterCard and Visa are supported"
+)
+
+// Merging multiple CardSchemes into one
+val mixedCardScheme = CardScheme.merge(CardScheme.MasterCard, CardScheme.Visa)
+
+val multipleCardField = CardSchemeValidable(
+    mixedCardScheme,
+    "Only MasterCard and Visa are supported"
+)
+```

docs/validables/email.md

@@ -0,0 +1,5 @@
+Validates that a value is a valid email address.
+
+```kotlin  
+val emailField = EmailValidable("invalid email")
+```

docs/validables/equal_to.md

@@ -0,0 +1,11 @@
+Validates that a value is equal to the specified value
+
+```kotlin  
+
+val comparedValue = "Hello World"
+
+val textField = EqualToValidable(
+    comparedValue,
+    "The value does not match $comparedValue"
+)
+```

docs/validables/greater_than.md

@@ -0,0 +1,10 @@
+Validates that a value is numerically greater than the specified value.
+
+```kotlin  
+val comparedValue = 10
+
+val numberField = GreaterThanValidable(
+    comparedValue,
+    "The value must be > $comparedValue"
+)
+```

docs/validables/greater_than_or_equal.md

@@ -0,0 +1,10 @@
+Validates that a value is numerically greater than or equal to the specified value.
+
+```kotlin  
+val minAge = 18
+
+val ageTextField = GreaterThanOrEqualValidable(
+    minAge,
+    "The minimum allowed age is $minAge"
+)
+```

docs/validables/host_name.md

@@ -0,0 +1,10 @@
+Validates that the given value is a valid host name
+
+```kotlin
+val domainNameField = HostnameValidable(
+    "Invalid domain name"
+)
+```
+
+> According to [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606.html), top-level domains (TLD) : `.example`, `.invalid`, `.localhost`, and `.test` are reserved
+and that's why hostnames containing them are not considered valid.

docs/validables/ip.md

@@ -0,0 +1,7 @@
+Validates that a value is a valid IP address
+
+```kotlin
+val ipTextField = IpValidable("Not a valid IP address")
+```
+
+> **Note** : Currently, IPv6 addresses are not supported.

docs/validables/less_than.md

@@ -0,0 +1,11 @@
+Validates that a value is numerically less than the specified value.
+
+```kotlin
+val limit = 18
+
+val numberTextField = LessThanValidable(
+    limit,
+    "The value must be < $limit"
+)
+
+```

docs/validables/less_than_or_equal.md

@@ -0,0 +1,10 @@
+Validates that a value is numerically less than or equal to the specified value.
+
+```kotlin
+val max = 9
+
+val numberTextField = LessThanOrEqualValidable(
+    max,
+    "The value must be <= $max"
+)
+```

docs/validables/negative.md

@@ -0,0 +1,5 @@
+Validates that a value is a negative number.
+
+```kotlin
+val numberField = NegativeValidable("The value must be < 0")
+```

docs/validables/negative_or_zero.md

@@ -0,0 +1,5 @@
+Validates that a value is a negative number or equal to zero.
+
+```kotlin
+val numberField = NegativeOrZeroValidable("The value must be <= 0")
+```

docs/validables/not_blank.md

@@ -0,0 +1,5 @@
+Validates that the value is not blank - neither empty string nor whitespace are valid
+
+```kotlin
+val textField = NotBlankValidable("This field cannot be blank")
+```

docs/validables/not_empty.md

@@ -0,0 +1,5 @@
+Validates that a value is not empty and contains some characters or whitespace characters.
+
+```kotlin
+val textField = NotBlankValidable("This field cannot be blank")
+```

docs/validables/not_equal.md

@@ -0,0 +1,10 @@
+Validates that a value is not equal to the specified value
+
+```kotlin
+val notAcceptedNumber = 7
+
+val numberTextField = NotEqualToValidable(
+    notAcceptedNumber,
+    "The value must be different from $notAcceptedNumber"
+)
+```