readme updated

guilhermeasn · Nov 21, 2023 · bfddb6a · bfddb6a
1 parent 811b256
commit bfddb6a
Show file tree

Hide file tree

Showing 3 changed files with 254 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -12,12 +12,262 @@ Lightweight package with functions and hooks for masking data inputs and outputs
 
 [Examples page](https://guilhermeasn.github.io/mask-hooks/)
 
-**V3 UNDER CONSTRUCTION**
+## Installation
+
+Run the command below in the terminal to install **mask-hooks** in your project
+
+```
+npm install mask-hooks
+```
+
+Or with Yarn
+
+```
+yarn add mask-hooks
+```
+
+## Examples with React
+
+ - Custom Mask
+
+```js
+import { useMask } from "mask-hooks";
+import { useState } from "react";
+
+export function InputMask() {
+
+    const mask = useMask({
+        masks: [ 'R$ #,##' ],
+        placeholder: '0',
+        reverse: true,
+        infinity: {
+            add: '.',
+            each: 3
+        },
+        maxentries: 8
+    });
+
+    const [ value, setValue ] = useState(mask(''));
+
+    return (
+
+        <input
+            value={ value }
+            onChange={ input => setValue(mask(input.currentTarget.value)) }
+        />
+
+    );
+
+}
+```
+
+ - Custom Mask with Numerical Range
+
+```js
+import { useMask } from 'mask-hooks';
+
+export default function Time() {
+
+    const time = useMask({
+        masks: [ '[0-23]:[0-59]:[0-59]' ];
+    });
+
+    return (
+        <p>Time: { time('71900') /* print 07:19:00 */ }</p>
+    );
+
+}
+```
+
+ - Preset Mask
+
+```js
+import { useMask, presets } from 'mask-hooks';
+
+export default function MaskDocs() {
+
+    const documentMask = useMask(presets.DOCUMENT_CPF_CNPJ);
+
+    return (
+        <>
+            <p>{ documentMask('11122233345')    /* print 111.222.333-45 */     }</p>
+            <p>{ documentMask('11222333000145') /* print 11.222.333/0001-45 */ }</p>
+        </>
+    );
+
+}
+```
+
+ - Changed Preset Mask
+
+```js
+import { useMask, getPresetMask } from 'mask-hooks';
+
+export default function MaskProduct() {
+
+    const productKeyMask = useMask(getPresetMask('PRODUCT_KEY', { placeholder: '_' }));
+
+    return (
+        <div>
+            {
+                productKeyMask('h3pbvfhb27rjtgh')
+                /* print H3PBV-FHB27-RJTGH-_____-_____ */
+            }
+        <div>
+    );
+
+}
+```
+
+ - Mask verification completed
+
+```js
+import { useCompleteMask, presets } from "mask-hooks";
+import { useState } from "react";
+
+export function InputMask() {
+
+    const maskComplete = useCompleteMask(presets.DATE_STAMP);
+    const [ data, setData ] = useState(maskComplete(''));
+
+    return (
+
+        <input
+            value={ data.result }
+            onChange={ input => setData(maskComplete(input.currentTarget.value)) }
+            style={ { color: data.completed ? "#000000" : "#ff0000" } }
+            title={ `${ data.entries } entries: ${ data.cleaned }` }
+        />
+
+    );
+
+}
+```
+
+- use mask directly
+
+```js
+import { applyMask, presets } from 'mask-hooks';
+
+export default function maskColor(target) {
+    return applyMask(target, presets.COLOR_HEX);
+}
+
+```
+
+## Resources
+
+Resources exported by the **mask-hooks** package:
+
+ - **Function `useMask`**: main resource to use package. Returns a function to use the preconfigured mask.
+
+```ts
+function useMask(settings: MaskProps): <T extends Stringable>(target: T) => string
+```
+
+ - **Function `useCompleteMask`**: Returns a function to use the preconfigured mask with additional information in the result.
+
+```ts
+function useCompleteMask(settings: MaskProps): <T extends Stringable>(target: T) => { result: string, completed: boolean; entries: number; cleaned: string; }
+```
+
+ - **Function `applyMask`**: use a mask directly on the target
+
+```ts
+function applyMask<T extends Stringable>(target: T, settings: MaskProps): string
+```
+
+ - **Class `Mask`**: application mask core
+
+```ts
+class Mask {
+
+    static defaultPatterns: {
+        '#': RegExp;
+        '@': RegExp;
+        '?': RegExp;
+    };
+    static reverser(target: string): string;
+    static transform(target: string, type: Required<MaskProps>['transform']): string;
+    static padding(target: string | number, length: number, char?: string, left?: boolean): string;
+
+    constructor(props: MaskProps);
+
+    get props(): Readonly<Required<MaskProps>>;
+    get completed(): boolean;
+    get cleaned(): string;
+    get entries(): number;
+
+    apply<T extends Stringable>(target: T): string;
+
+}
+```
+
+ - **Constant `presets`**: preconfigured masks
+
+```ts
+const presets: { [key in PresetOption]: MaskProps; }
+```
+
+ - **Function `getPresetMask`**: get a preset, optionally being able to change its settings
+
+```ts
+function getPresetMask(preset: PresetOption, change: Partial<MaskProps> = {}): MaskProps
+```
+
+## MaskProps
+
+The useMask receives the settings parameter of type MaskProps. See available settings:
+
+|Prop|Type|Default|Details|
+|---|---|---|---|
+|**masks**|`Array<string>`||The masks that will be applied to the target. By default the characters `?`, `#`, `@` will be replaced by letters or numbers, numbers, letters, respectively. This character pattern can be changed. You can also use a Numerical Range to limit a numeric value to be entered using the pattern [\<number\>-\<number\>]. To escape a replacement character use `\` before it.|
+|**placeholder**|`string`|`''`|Autofill of the mask to be filled|
+|**reverse**|`boolean`|`false`|Mask fill in inverted mode|
+|**transform**|`'uppercase'`<br />`'lowercase'`<br />`'capitalize'`<br />`'capitalizeAll'`<br />`'none'`|`'none'`|Apply a transformation to the result string|
+|**infinity**|`boolean`<br />`{each:number;add:string;}`|`false`|Allows data entry indefinitely by the last mask replacement character|
+|**maxentries**|`number`<br />`null`|`null`|If specified a number will limit the amount of user entries|
+|**patterns**|`{[key in string]: RegExp}`|`{'#': /[0-9]/,'@': /[A-Za-z]/,'?': /[A-Za-z0-9]/}`|Characters to be substituted in the mask if approved by the regular expression|
+
+## Presets
+
+You can import pre-established mask configurations. See the options:
+
+- ONLY_NUMBERS
+- ONLY_LETTERS
+- ONLY_CHARS
+- DATE_STAMP
+- DATE_PTBR
+- DATETIME_STAMP
+- DATETIME_PTBR
+- DATE_STAMP_LIMITED
+- DATE_PTBR_LIMITED
+- DATETIME_STAMP_LIMITED
+- DATETIME_PTBR_LIMITED
+- PHONE_USA
+- PHONE_BR
+- CURRENCY_POINT
+- CURRENCY_COMMA
+- CURRENCY_DOLLAR
+- CURRENCY_PTBR
+- CURRENCY_DOLLAR_LIMITED
+- CURRENCY_PTBR_LIMITED
+- DOCUMENT_CPF
+- DOCUMENT_CNPJ
+- DOCUMENT_CPF_CNPJ
+- ZIPCODE_USA
+- ZIPCODE_BR
+- PRODUCT_KEY
+- COLOR_HEX
+
+## Migrating v2 to v3
+
+*The third version of the mask-hooks package now has the numerical range feature.*
 
 ## Author
 
 * **Guilherme Neves** - [github](https://github.com/guilhermeasn/) - [website](https://gn.dev.br/)
 
 ## License
 
-This project is under the MIT license - see file [LICENSE](https://github.com/guilhermeasn/mask-hooks/blob/master/LICENSE) for details.
+This project is under the MIT license - see file [LICENSE](https://github.com/guilhermeasn/mask-hooks/blob/master/LICENSE) for details.
diff --git a/bin/publish.ps1 b/bin/publish.ps1
@@ -5,7 +5,7 @@ if($LASTEXITCODE -eq 0) {
     yarn build
     yarn minify
     npm pack --pack-destination .\\packs\\
-    # npm publish
+    npm publish
 
 } else {
 

diff --git a/bin/publish.sh b/bin/publish.sh
@@ -2,7 +2,7 @@ if (yarn test); then
 
     yarn build
     npm pack --pack-destination .\\packs\\
-    # npm publish
+    npm publish
 
 else