maskarajs 1.0.0 → 1.0.2

package/README.md

@@ -1,94 +1,143 @@
-# mask.js
+# maskarajs
 
-Engine de máscaras declarativo para JavaScript — framework-agnostic, zero dependências, ~4kb.
+Declarative input mask engine for JavaScript. Framework-agnostic, zero dependencies, and small enough to live close to your form fields.
 
-## Sintaxe
+## Syntax
 
-| Token | Aceita |
+| Token | Accepts |
 |---|---|
-| `#` | qualquer dígito (0–9) |
-| `@` | qualquer letra (a–z, A–Z, acentuados) |
-| `*` | qualquer caractere |
-| `[texto]` | literal fixo (inserido/removido automaticamente) |
-| `{expr}` | slot livre — testa um char contra a expressão |
+| `#` | any digit (`0-9`) |
+| `@` | any letter (`a-z`, `A-Z`, accented letters) |
+| `*` | any character |
+| `[text]` | fixed literal text, inserted and removed automatically |
+| `{expr}` | free slot: tests one character against an expression |
+
+### `{expr}` modifier
+
+```txt
+{4}         -> only the char "4"
+{0-4}       -> range: ch >= "0" && ch <= "4"
+{013}       -> set: "0", "1" or "3"
+{[0-9a-f]}  -> regex: any hexadecimal char
+{\d}        -> regex: any digit
+{[^aeiou]}  -> regex: any consonant
+```
 
-### Modificador `{expr}`
+## Install
 
+```bash
+npm install maskarajs
 ```
-{4}         → só o char '4'
-{0-4}       → intervalo: ch >= '0' && ch <= '4'
-{013}       → conjunto: '0', '1' ou '3'
-{[0-9a-f]}  → regex: qualquer char hex
-{\d}        → regex: qualquer dígito
-{[^aeiou]}  → regex: consoante
+
+```js
+import maskara from 'maskarajs'
 ```
 
 ## API
 
 ```js
-import mask from './mask.js'
-
-mask(pattern, value)               // aplica máscara → string formatada
-mask.raw(pattern, value)           // valor limpo / resultado do transform
-mask.is(pattern, value)            // padrão completo? → boolean
-mask.hint(pattern)                 // placeholder → string
-mask.format(pattern, value)        // alias semântico de mask()
-mask.rawLength(pattern, value)     // chars de input preenchidos → number
-mask.patternLength(pattern)        // tamanho mascarado completo → number
-mask.define(name, definition)      // registra máscara nomeada
-mask.undefine(name)                // remove do registry
-mask.names()                       // lista nomes registrados → string[]
-mask.defineSlot(symbol, definition)// cria/sobrescreve token de input
-mask.undefineSlot(symbol)          // remove token customizado
-mask.slots()                       // lista tokens de input disponíveis
-mask.on(input, pattern, options)   // vincula a input DOM → cleanup()
-mask.create(presets)               // instância isolada com registry próprio
+maskara(pattern, value)                // apply mask -> formatted string
+maskara.raw(pattern, value)            // clean value / transform result
+maskara.is(pattern, value)             // complete pattern? -> boolean
+maskara.hint(pattern)                  // readable placeholder -> string
+maskara.format(pattern, value)         // semantic alias for maskara()
+maskara.rawLength(pattern, value)      // filled input chars -> number
+maskara.patternLength(pattern)         // full formatted length -> number
+maskara.define(name, definition)       // register a named mask
+maskara.undefine(name)                 // remove a named mask
+maskara.names()                        // list registered names -> string[]
+maskara.defineSlot(symbol, definition) // create or override an input token
+maskara.undefineSlot(symbol)           // remove a custom token
+maskara.slots()                        // list available input tokens
+maskara.on(input, pattern, options)    // bind to a DOM input -> cleanup()
+maskara.create(presets)                // isolated instance with its own registry
 ```
 
-## Exemplos
+## React adapter
+
+The React adapter is optional and lives in `maskarajs/react`. Use `useMaskara` directly for small forms, or wrap your app with `MaskaraProvider` when you have an isolated engine created with `maskara.create()`.
+
+```tsx
+import maskara from 'maskarajs'
+import { MaskaraProvider, useMaskara } from 'maskarajs/react'
+
+const appMaskara = maskara.create({
+  cpf: { pattern: '###[.]###[.]###[-]##' },
+  phone: { pattern: ['[(]##[)] ####[-]####', '[(]##[)] #####[-]####'] },
+})
+
+function CPFInput() {
+  const cpf = useMaskara('cpf')
+
+  return (
+    <input
+      {...cpf.inputProps({ inputMode: 'numeric' })}
+      aria-label="CPF"
+    />
+  )
+}
+
+export function App() {
+  return (
+    <MaskaraProvider engine={appMaskara}>
+      <CPFInput />
+    </MaskaraProvider>
+  )
+}
+```
+
+`useMaskara` still accepts an `engine` option when a single field needs a specific instance:
+
+```tsx
+const cpf = useMaskara('cpf', { engine: appMaskara })
+```
+
+The hook stores field state. The engine stores mask configuration.
+
+## Examples
 
 ```js
-// Padrão único
-mask('###[.]###[.]###[-]##', '12345678909')
-// → '123.456.789-09'
+// Single pattern
+maskara('###[.]###[.]###[-]##', '12345678909')
+// -> '123.456.789-09'
 
-// Padrão dinâmico (array) — escolhe pelo tamanho do input
-mask(['[(]##[)] ####[-]####', '[(]##[)] #####[-]####'], '11987654321')
-// → '(11) 98765-4321'
+// Dynamic pattern array: chooses by input size
+maskara(['[(]##[)] ####[-]####', '[(]##[)] #####[-]####'], '11987654321')
+// -> '(11) 98765-4321'
 
-// Slot com restrição
-mask('{4}### #### #### ####', '4111111111111111')
-// → '4111 1111 1111 1111'  (só aceita Visa — começa com 4)
+// Restricted slot
+maskara('{4}### #### #### ####', '4111111111111111')
+// -> '4111 1111 1111 1111'
 
-// Slot com regex
-mask('{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}', '1a2b3c')
-// → '1a2b3c'
+// Regex slot
+maskara('{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}', '1a2b3c')
+// -> '1a2b3c'
 ```
 
-### Mais casos comuns
+### Common cases
 
 ```js
-// CEP
-mask('#####[-]###', '01310930')
-// → '01310-930'
+// Brazilian ZIP code
+maskara('#####[-]###', '01310930')
+// -> '01310-930'
 
 // CNPJ
-mask('##[.]###[.]###[/]####[-]##', '11222333000181')
-// → '11.222.333/0001-81'
+maskara('##[.]###[.]###[/]####[-]##', '11222333000181')
+// -> '11.222.333/0001-81'
 
-// Cartão Visa
-mask('{4}### #### #### ####', '5111111111111111')
-// → ''  (primeiro char não passou)
+// Visa card
+maskara('{4}### #### #### ####', '5111111111111111')
+// -> ''  (the first char did not pass)
 
-// Hex color com paste sujo
-mask('{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}', '1z2b3c')
-// → '12b3c'
+// Hex color with dirty paste
+maskara('{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}{[0-9a-fA-F]}', '1z2b3c')
+// -> '12b3c'
 ```
 
-## mask.define — com transform
+## `maskara.define` with `transform`
 
 ```js
-mask.define('date', {
+maskara.define('date', {
   pattern: '##[/]##[/]####',
   validate: (raw, masked, complete) => {
     if (raw.length < 4) return true
@@ -102,23 +151,21 @@ mask.define('date', {
   },
 })
 
-mask('date', '01012025')          // → '01/01/2025'
-mask.raw('date', '01/01/2025')    // → Date(2025-01-01)
-mask.raw('date', '01/01')         // → null  (incompleto — transform decidiu)
-mask.is('date', '01/01/2025')     // → true
-mask.hint('date')                 // → '00/00/0000'
-mask.rawLength('date', '01/01')   // → 4
-mask.patternLength('date')        // → 10
+maskara('date', '01012025')          // -> '01/01/2025'
+maskara.raw('date', '01/01/2025')    // -> Date(2025-01-01)
+maskara.raw('date', '01/01')         // -> null
+maskara.is('date', '01/01/2025')     // -> true
+maskara.hint('date')                 // -> '00/00/0000'
+maskara.rawLength('date', '01/01')   // -> 4
+maskara.patternLength('date')        // -> 10
 ```
 
-## validate — validação incremental
+## `validate`: incremental validation
 
-Use `validate` em máscaras nomeadas quando a regra depende do que já foi digitado.
-Isso resolve casos onde a sintaxe caractere a caractere não é suficiente, como mês
-entre `01` e `12`.
+Use `validate` on named masks when the rule depends on what has already been typed. This covers cases where character-by-character syntax is not enough, such as accepting only months from `01` to `12`.
 
 ```js
-mask.define('month', {
+maskara.define('month', {
   pattern: '{0-1}#',
   validate: (raw, masked, complete) => {
     if (!complete) return true
@@ -127,98 +174,129 @@ mask.define('month', {
   },
 })
 
-mask('month', '12') // → '12'
-mask('month', '19') // → '1'  (o 9 é recusado)
-mask.is('month', '12') // → true
-mask.is('month', '19') // → false
+maskara('month', '12') // -> '12'
+maskara('month', '19') // -> '1'
+maskara.is('month', '12') // -> true
+maskara.is('month', '19') // -> false
+```
+
+## Conditional masks
+
+Use `patterns` + `select` on a named mask when the mask must change because of the typed value, not only because of length. Arrays of strings keep the old behavior and still choose the smallest pattern that fits the input. Conditional masks live inside `define` or `create`, where product rules already belong.
+
+`select(raw, value)` receives the value without literals from all possible patterns and returns a key from `patterns`.
+
+```js
+const cpf = '###[.]###[.]###[-]##'
+const cnpj = '##[.]###[.]###[/]####[-]##'
+
+maskara.define('smartDocument', {
+  patterns: { cpf, cnpj },
+  select: raw => raw.includes('123') ? 'cnpj' : 'cpf',
+})
+
+maskara('smartDocument', '98765432100')
+// -> '987.654.321-00'
+
+maskara('smartDocument', '12345678000199')
+// -> '12.345.678/0001-99'
 ```
 
-## Slots customizados — sua própria linguagem de pattern
+It also works with isolated instances:
 
-Além de `#`, `@`, `*` e `{expr}`, você pode criar símbolos que façam sentido
-para o seu time. Isso ajuda quando o projeto quer uma linguagem mais expressiva,
-mais curta ou alinhada ao domínio do produto.
+```js
+const forms = maskara.create({
+  smartDocument: {
+    patterns: { cpf, cnpj },
+    select: raw => raw.startsWith('9') ? 'cpf' : 'cnpj',
+  },
+})
+```
+
+Prefer conditional masks for rules that depend on the value itself: prefixes, country codes, card BINs, product codes or any domain rule. Prefer a simple string array when the only difference is input size, such as phone numbers with 10 or 11 digits.
+
+## Custom slots: create your own pattern language
+
+Besides `#`, `@`, `*` and `{expr}`, you can create symbols that make sense for your team. This is useful when a project needs a shorter, more expressive language aligned with its product domain.
 
 ```js
-mask.defineSlot('N', {
+maskara.defineSlot('N', {
   test: ch => /\d/.test(ch),
   hint: '0',
 })
 
-mask('NNN[-]NN', '12345') // → '123-45'
-mask.hint('NNN[-]NN')     // → '000-00'
-mask.slots()              // → ['#', '@', '*', 'N']
+maskara('NNN[-]NN', '12345') // -> '123-45'
+maskara.hint('NNN[-]NN')     // -> '000-00'
+maskara.slots()              // -> ['#', '@', '*', 'N']
 ```
 
-Você também pode passar uma `RegExp` direta ou apenas uma função:
+You can also pass a `RegExp` or a function directly:
 
 ```js
-mask.defineSlot('H', /[0-9a-f]/i)
-mask.defineSlot('V', ch => 'AEIOUaeiou'.includes(ch))
+maskara.defineSlot('H', /[0-9a-f]/i)
+maskara.defineSlot('V', ch => 'AEIOUaeiou'.includes(ch))
 
-mask('HHHHHH', '1a2b3c') // → '1a2b3c'
-mask('VVV', 'mask')      // → 'a'
+maskara('HHHHHH', '1a2b3c') // -> '1a2b3c'
+maskara('VVV', 'mask')      // -> 'a'
 ```
 
-O registro global afeta o engine global. Para bibliotecas, design systems ou
-produtos com regras próprias, prefira uma instância isolada:
+Global slots affect the global engine. For libraries, design systems or products with their own rules, prefer an isolated instance:
 
 ```js
-const forge = mask.create()
+const forge = maskara.create()
 
 forge.defineSlot('N', { test: ch => /\d/.test(ch), hint: '0' })
 forge.defineSlot('#', { test: ch => /[1-9]/.test(ch), hint: '1' })
 
-forge('NNN[-]NN', '12345') // → '123-45'
-forge('#', '0')            // → ''   (# foi sobrescrito nesta instância)
-mask('#', '0')             // → '0'  (global continua igual)
+forge('NNN[-]NN', '12345') // -> '123-45'
+forge('#', '0')            // -> ''
+maskara('#', '0')             // -> '0'  (global stays unchanged)
 ```
 
-Se um símbolo registrado precisar aparecer como texto fixo, escape com
-colchetes:
+If a registered symbol must appear as fixed text, escape it with brackets:
 
 ```js
-mask.defineSlot('N', /\d/)
+maskara.defineSlot('N', /\d/)
 
-mask('[N]##', '45') // → 'N45'
-mask('N##', '145')  // → '145'
+maskara('[N]##', '45') // -> 'N45'
+maskara('N##', '145')  // -> '145'
 ```
 
-## mask.on — qualquer framework
+## `maskara.on`: any framework
 
 ```js
 // Vanilla JS
-const off = mask.on(inputEl, 'cpf', {
-  onValue:  raw    => setState(raw),
-  onMasked: masked => setLabel(masked),
+const off = maskara.on(inputEl, 'cpf', {
+  onValue: raw => setState(raw),
+  onMaskara: masked => setLabel(masked),
 })
-off() // remove listeners
+off()
 
 // React
 useEffect(() => {
-  return mask.on(ref.current, 'date', {
-    onValue: (date) => setValue(date), // Date | null
+  return maskara.on(ref.current, 'date', {
+    onValue: date => setValue(date), // Date | null
   })
 }, [])
 
 // Vue
 onMounted(() => {
-  mask.on(inputRef.value, 'phone', {
-    onValue: v => emit('update:modelValue', v),
+  maskara.on(inputRef.value, 'phone', {
+    onValue: value => emit('update:modelValue', value),
   })
 })
 
 // Svelte action
 function maskAction(node, pattern) {
-  const off = mask.on(node, pattern)
+  const off = maskara.on(node, pattern)
   return { destroy: off }
 }
 ```
 
-## mask.create — instâncias isoladas
+## `maskara.create`: isolated instances
 
 ```js
-export const maskBR = mask.create({
+export const maskaraBR = maskara.create({
   cpf:   { pattern: '###[.]###[.]###[-]##' },
   cnpj:  { pattern: '##[.]###[.]###[/]####[-]##' },
   phone: { pattern: ['[(]##[)] ####[-]####', '[(]##[)] #####[-]####'] },
@@ -231,53 +309,78 @@ export const maskBR = mask.create({
       return isNaN(dt) ? null : dt
     },
   },
-  money: {
-    pattern: '########[,]##',
-    transform: raw => parseInt(raw || '0', 10) / 100,
-  },
 })
 
-export const maskUS = mask.create({
+export const maskaraUS = maskara.create({
   ssn:   { pattern: '###[-]##[-]####' },
   zip:   { pattern: '#####[-]####' },
   phone: { pattern: '[(]###[)] ###[-]####' },
 })
 
-// Mesma API, registries isolados — alterações em maskBR não afetam maskUS
-maskBR('cpf', '12345678909')          // → '123.456.789-09'
-maskBR.raw('date', '01/01/2025')      // → Date
-maskBR.names()                         // → ['cpf', 'cnpj', 'phone', 'cep', 'date', 'money']
-maskUS.names()                         // → ['ssn', 'zip', 'phone']
+maskaraBR('cpf', '12345678909')     // -> '123.456.789-09'
+maskaraBR.raw('date', '01/01/2025') // -> Date
+maskaraBR.names()                   // -> ['cpf', 'cnpj', 'phone', 'cep', 'date']
+maskaraUS.names()                   // -> ['ssn', 'zip', 'phone']
 ```
 
-## rawLength e patternLength
+## Official Brazilian presets
+
+If you want common Brazilian masks ready to use, import `maskarajs/presets/br` and create an isolated engine from it.
+
+```ts
+import maskara from 'maskarajs'
+import { br, type BrazilPresetRegistry } from 'maskarajs/presets/br'
+
+const maskaraBR = maskara.create<BrazilPresetRegistry>(br)
+
+maskaraBR('cpf', '12345678909')      // -> '123.456.789-09'
+maskaraBR('cnpj', '11222333000181')  // -> '11.222.333/0001-81'
+maskaraBR('phone', '11987654321')    // -> '(11) 98765-4321'
+maskaraBR.raw('cep', '01310-930')    // -> '01310930'
+maskaraBR.raw('date', '01/12/2025')  // -> Date
+maskaraBR.raw('money', '1299,90')    // -> 1299.9
+```
+
+The preset includes:
+
+| Name | Pattern / behavior |
+|---|---|
+| `cpf` | `000.000.000-00` |
+| `cnpj` | `00.000.000/0000-00` |
+| `cep` | `00000-000`, returns `null` until complete |
+| `phone` | landline or mobile phone |
+| `date` | `DD/MM/YYYY`, rejects invalid months and returns `Date \| null` |
+| `month` | accepts only `01` to `12` |
+| `money` | decimal money value from cents |
+
+## `rawLength` and `patternLength`
 
 ```js
-const filled = mask.rawLength('cpf', value)   // chars preenchidos (sem literais)
-const total  = mask.patternLength('cpf')       // tamanho total mascarado
+const filled = maskara.rawLength('cpf', value)
+const total = maskara.patternLength('cpf')
 
-const pct    = mask('cpf', value).length / total * 100
-const ready  = mask.is('cpf', value)           // habilita submit
-const label  = `${filled} raw chars`           // "7 raw chars"
+const pct = maskara('cpf', value).length / total * 100
+const ready = maskara.is('cpf', value)
+const label = `${filled} raw chars`
 ```
 
-`patternLength` conta o tamanho final mascarado, incluindo literais. Exemplos:
+`patternLength` counts the final formatted length, including literals:
 
 ```js
-mask.patternLength('##[/]##[/]####')       // → 10
-mask.patternLength('###[.]###[.]###[-]##') // → 14
-mask.patternLength('{4}### #### #### ####') // → 19
+maskara.patternLength('##[/]##[/]####')       // -> 10
+maskara.patternLength('###[.]###[.]###[-]##') // -> 14
+maskara.patternLength('{4}### #### #### ####') // -> 19
 ```
 
-## Showcase visual
+## Visual showcase
 
-O projeto `maskforge-showcase` demonstra a lib com:
+The `maskforge-showcase` project demonstrates the library with:
 
-- playground destacado com máscara aplicada enquanto o usuário digita;
-- visualização do pattern em blocos: slot, literal e expressão;
-- exemplos para React, Vue e Vanilla;
-- receitas interativas para `validate`, `define` e `create`;
-- análise de benchmark local.
+- a playground that applies the mask while the user types;
+- a visual pattern map with slot, literal and expression blocks;
+- examples for React, Vue and Vanilla JavaScript;
+- interactive recipes for `validate`, `define`, `defineSlot` and `create`;
+- local benchmark notes.
 
 ```bash
 cd maskforge-showcase
@@ -285,54 +388,121 @@ npm install
 npm run dev
 ```
 
-## Benchmark local
+## Local benchmark
 
-Benchmark simples rodado em Node/WSL com 200.000 iterações por caso após warmup.
-Os valores variam por máquina, mas ajudam a orientar expectativas de uso em input.
+Simple benchmark executed in Node/WSL with 200,000 iterations per case after warmup. Numbers vary by machine, but they help set expectations for input-level usage.
 
-| Caso | Resultado |
+| Case | Result |
 |---|---:|
-| CPF format | 39.705 ops/s |
-| Phone dynamic | 32.455 ops/s |
-| Date validate | 64.572 ops/s |
-| Raw extraction | 44.729 ops/s |
+| CPF format | 39,705 ops/s |
+| Phone dynamic | 32,455 ops/s |
+| Date validate | 64,572 ops/s |
+| Raw extraction | 44,729 ops/s |
 
 ```js
 const iterations = 200000
 for (let i = 0; i < iterations; i++) {
-  mask('###[.]###[.]###[-]##', '12345678909')
+  maskara('###[.]###[.]###[-]##', '12345678909')
 }
 ```
 
-## transform — contrato
+## `transform` contract
 
 ```js
 // transform(raw, masked, complete) => T
 // validate(raw, masked, complete) => boolean
 //
-// raw      → string com os chars de input sem literais
-// masked   → string formatada com a máscara
-// complete → true quando todos os slots estão preenchidos
+// raw      -> input chars without literals
+// masked   -> formatted string
+// complete -> true when every slot is filled
 //
-// Sem transform → mask.raw() retorna string crua, sempre
-// Com transform → mask.raw() retorna o que transform devolver, sempre
-//   O transform decide o que fazer com input parcial
-
-mask.define('money', {
-  pattern: '########[,]##',
-  transform: raw => parseInt(raw || '0', 10) / 100,
-  // retorna number sempre — mesmo parcial
-})
+// Without transform -> maskara.raw() always returns the raw string
+// With transform    -> maskara.raw() always returns whatever transform returns
+```
 
-mask.define('date', {
-  pattern: '##[/]##[/]####',
-  transform: (raw, masked, complete) => {
-    if (!complete) return null  // null enquanto incompleto
-    return new Date(...)        // Date quando completo
-  },
+## License
+
+MIT
+
+## React hook
+
+`maskarajs/react` exports a small `useMaskara` hook. It lives in a separate entrypoint, so the core package stays framework-agnostic for users who do not use React.
+
+```tsx
+import { useMaskara } from 'maskarajs/react'
+
+export function CPFField() {
+  const cpf = useMaskara('###[.]###[.]###[-]##')
+
+  return <input {...cpf.inputProps({ inputMode: 'numeric' })} />
+}
+```
+
+### React Hook Form
+
+Use `onValue` to send the raw value to React Hook Form while the input keeps the masked value on screen.
+
+```tsx
+import { Controller, useForm } from 'react-hook-form'
+import { useMaskara } from 'maskarajs/react'
+
+type FormValues = {
+  cpf: string
+}
+
+function CPFController({ field }) {
+  const cpf = useMaskara('###[.]###[.]###[-]##', {
+    value: field.value,
+    onValue: field.onChange,
+  })
+
+  return (
+    <input
+      {...cpf.inputProps({
+        name: field.name,
+        onBlur: field.onBlur,
+        ref: field.ref,
+        inputMode: 'numeric',
+      })}
+    />
+  )
+}
+
+export function Form() {
+  const { control, handleSubmit } = useForm<FormValues>({
+    defaultValues: { cpf: '' },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(console.log)}>
+      <Controller
+        name="cpf"
+        control={control}
+        render={({ field }) => <CPFController field={field} />}
+      />
+    </form>
+  )
+}
+```
+
+### Zod
+
+Keep the form value raw and validate it normally.
+
+```ts
+import { z } from 'zod'
+
+export const schema = z.object({
+  cpf: z.string().length(11, 'CPF must contain 11 digits'),
 })
 ```
 
-## Licença
+### Yup
 
-MIT
+```ts
+import * as yup from 'yup'
+
+export const schema = yup.object({
+  cpf: yup.string().length(11, 'CPF must contain 11 digits').required(),
+})
+```