@seniorsistemas/angular-components 19.6.2 → 19.7.0

package/input-mask/README.md

@@ -0,0 +1,183 @@
+# InputMask
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Diretiva que aplica máscara de entrada em qualquer `<input type="text">`, guiando a digitação conforme um padrão definido. Integra nativamente com Angular Forms via `ControlValueAccessor` e adiciona validação automática de máscara incompleta via `Validator`.
+
+## Quando usar
+
+- Campos com formato fixo: CPF, CNPJ, telefone, data, placa de veículo
+- Formulários que exigem validação de preenchimento completo da máscara
+- Quando o valor armazenado no model deve ser sem formatação (`unmask: true`)
+- Campos com parte opcional na máscara, como telefone fixo ou celular
+
+## Quando não usar
+
+- Para formatação de valores numéricos com separadores de milhar e decimal — use [`NumericMask`](../numeric-mask/README.md)
+- Para campos de data integrados ao `p-calendar` — use [`CalendarMask`](../calendar-mask/README.md)
+- Quando a entrada é completamente livre sem padrão — não há necessidade de máscara
+
+## Instalação
+
+```typescript
+import { InputMaskDirective } from '@seniorsistemas/angular-components/input-mask';
+
+@Component({
+    standalone: true,
+    imports: [InputMaskDirective, ReactiveFormsModule],
+})
+export class MeuComponent {
+    control = new FormControl('');
+}
+```
+
+## Uso básico
+
+```html
+<input type="text" [sInputMask]="'999.999.999-99'" [formControl]="control" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `sInputMask` | `string \| undefined` | `undefined` | Sim | Padrão da máscara. Slots: `9` (dígito), `a` (letra), `*` (alfanumérico), `?` (restante opcional). Demais caracteres são literais |
+| `slotChar` | `string` | `'_'` | Não | Caractere exibido nas posições ainda não preenchidas |
+| `unmask` | `boolean` | `false` | Não | Quando `true`, o model recebe apenas os caracteres digitados, sem os literais da máscara |
+| `characterPattern` | `string` | `'[A-Za-z]'` | Não | Expressão regular para validar o slot `a` (letra) |
+| `autoClear` | `boolean` | `true` | Não | Limpa o campo ao perder o foco se a máscara estiver incompleta |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `maskComplete` | `OutputEmitterRef<string>` | Emitido quando todos os slots obrigatórios são preenchidos. Emite o valor atual (mascarado ou não, conforme `unmask`) |
+
+### Slots da máscara
+
+| Caractere | Aceita |
+|-----------|--------|
+| `9` | Dígito (0–9) |
+| `a` | Letra (controlado por `characterPattern`, padrão `[A-Za-z]`) |
+| `*` | Alfanumérico (letra ou dígito) |
+| `?` | Tudo após esse ponto é opcional |
+| Outros | Tratados como literais (ex: `.`, `-`, `/`, `(`, `)`) |
+
+### Validação
+
+A diretiva implementa `Validator` e adiciona o seguinte erro ao `FormControl` quando a máscara está incompleta:
+
+```typescript
+{ incompleteMask: { mask: string } }
+```
+
+O erro é removido automaticamente quando o campo é preenchido por completo.
+
+## Exemplos
+
+### CPF
+
+```html
+<input type="text" [sInputMask]="'999.999.999-99'" [formControl]="cpf" />
+```
+
+### CNPJ alfanumérico (a partir de jul/2026)
+
+```html
+<!-- Base e ordem alfanuméricos; dígitos verificadores permanecem numéricos -->
+<input
+    type="text"
+    [sInputMask]="'**.***.***/****.99'"
+    style="text-transform: uppercase"
+    [formControl]="cnpj"
+/>
+```
+
+### Telefone com unmask
+
+```html
+<!-- Model recebe apenas os dígitos: "11999998888" -->
+<input
+    type="text"
+    [sInputMask]="'(99) 99999-9999'"
+    [unmask]="true"
+    [formControl]="telefone"
+/>
+```
+
+### Telefone fixo ou celular (slot opcional)
+
+```html
+<!-- Aceita 8 ou 9 dígitos após o DDD -->
+<input
+    type="text"
+    [sInputMask]="'(99) 9999?9-9999'"
+    [autoClear]="false"
+    [formControl]="telefone"
+/>
+```
+
+### Placa de veículo Mercosul
+
+```html
+<!-- 3 letras, 1 dígito, 1 alfanumérico, 2 dígitos -->
+<input
+    type="text"
+    [sInputMask]="'aaa-9*99'"
+    style="text-transform: uppercase"
+    [formControl]="placa"
+/>
+```
+
+### Reação ao preenchimento completo
+
+```html
+<input
+    type="text"
+    [sInputMask]="'999.999.999-99'"
+    [formControl]="cpf"
+    (maskComplete)="onCpfCompleto($event)"
+/>
+```
+
+```typescript
+onCpfCompleto(valor: string): void {
+    // valor = '123.456.789-01' (ou só dígitos se unmask=true)
+    this.validarCpf(valor);
+}
+```
+
+### Valor pré-preenchido via model
+
+A diretiva aceita tanto o valor mascarado quanto apenas os dígitos:
+
+```typescript
+// Ambos resultam em '123.456.789-01' exibido no campo
+control = new FormControl('123.456.789-01');
+control = new FormControl('12345678901');
+```
+
+### Somente letras maiúsculas no slot `a`
+
+```html
+<input
+    type="text"
+    [sInputMask]="'aaa-9999'"
+    characterPattern="[A-Z]"
+    [formControl]="codigo"
+/>
+```
+
+## Acessibilidade
+
+- Navegação por `ArrowLeft`, `ArrowRight`, `Home` e `End` é tratada nativamente pelo browser
+- `Tab` e atalhos de teclado (`Ctrl`/`Cmd`) não são interceptados pela diretiva
+- Paste com `Ctrl+V` é suportado — a diretiva distribui os caracteres colados nos slots válidos
+- Use `text-transform: uppercase` via CSS quando a máscara exigir letras maiúsculas, pois a diretiva não converte caixa automaticamente
+
+## Componentes relacionados
+
+- [`CalendarMask`](../calendar-mask/README.md) — máscara para campos de data integrados ao `p-calendar`
+- [`NumericMask`](../numeric-mask/README.md) — formatação de valores numéricos com separadores de milhar e decimal

package/input-mask/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@seniorsistemas/angular-components/input-mask" />
+export * from './public-api';

package/input-mask/lib/input-mask/input-mask.directive.d.ts

@@ -0,0 +1,103 @@
+import { OnChanges, OnInit, SimpleChanges } from '@angular/core';
+import { AbstractControl, ControlValueAccessor, ValidationErrors, Validator } from '@angular/forms';
+import * as i0 from "@angular/core";
+/**
+ * @description Diretiva de máscara de entrada para campos de texto.
+ *
+ * Aplique `[sInputMask]` em qualquer `<input>` para aplicar uma máscara de formatação,
+ * guiando a entrada do usuário com um padrão definido. Implementa ControlValueAccessor
+ * e Validator para integração nativa com Angular Forms.
+ *
+ * **Slots de máscara:**
+ * - `9` — dígito (0-9)
+ * - `a` — letra (conforme `characterPattern`, padrão `[A-Za-z]`)
+ * - `*` — alfanumérico (letra ou dígito)
+ * - Outros caracteres são tratados como literais (ex: `.`, `-`, `/`, `(`, `)`)
+ * - `?` — tudo após esse ponto na máscara é opcional
+ *
+ * @example
+ * ```html
+ * <!-- CPF -->
+ * <input type="text" [sInputMask]="'999.999.999-99'" [(ngModel)]="cpf" />
+ *
+ * <!-- Telefone com unmask -->
+ * <input type="text" [sInputMask]="'(99) 99999-9999'" [unmask]="true" [(ngModel)]="telefone" />
+ * ```
+ * @category Input
+ */
+export declare class InputMaskDirective implements OnInit, OnChanges, ControlValueAccessor, Validator {
+    /**
+     * Padrão da máscara. Slots: `9` (dígito), `a` (letra), `*` (alfanumérico).
+     * Demais caracteres são literais. `?` torna o restante da máscara opcional.
+     */
+    mask: import("@angular/core").InputSignal<string | undefined>;
+    /**
+     * Caractere exibido nas posições ainda não preenchidas.
+     * @default '_'
+     */
+    slotChar: import("@angular/core").InputSignal<string>;
+    /**
+     * Quando `true`, o modelo recebe apenas os caracteres digitados pelo usuário,
+     * sem os literais da máscara. Quando `false`, o modelo recebe o valor completo
+     * incluindo literais.
+     * @default false
+     */
+    unmask: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Expressão regular usada para validar o slot `a` (letra).
+     * @default '[A-Za-z]'
+     */
+    characterPattern: import("@angular/core").InputSignal<string>;
+    /**
+     * Quando `true`, limpa o campo ao perder o foco se a máscara estiver incompleta.
+     * @default true
+     */
+    autoClear: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Emitido quando todos os slots obrigatórios da máscara estão preenchidos.
+     * Emite o valor atual (mascarado ou não, conforme `unmask`).
+     */
+    maskComplete: import("@angular/core").OutputEmitterRef<string>;
+    private readonly el;
+    private readonly renderer;
+    private tokens;
+    private buffer;
+    private wasComplete;
+    private lastValue;
+    private onChange;
+    private onTouched;
+    ngOnInit(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    private buildMask;
+    private parseMask;
+    private resetBuffer;
+    private isValidChar;
+    private isEditable;
+    private nextEditablePos;
+    private prevEditablePos;
+    private setCursor;
+    private setInputValue;
+    private getDisplayValue;
+    private getBlurDisplayValue;
+    /**
+     * Returns the value that should be set on the model.
+     * Returns null when the user has not typed anything.
+     */
+    private getModelValue;
+    private clearRange;
+    private isMaskComplete;
+    private checkAndEmitComplete;
+    private dispatchInputEvent;
+    onKeyDown(event: KeyboardEvent): void;
+    onFocus(_event: FocusEvent): void;
+    onBlur(_event: Event): void;
+    onPaste(event: ClipboardEvent): void;
+    onClick(): void;
+    writeValue(value: string | null): void;
+    registerOnChange(onChange: (value: string | null) => void): void;
+    registerOnTouched(onTouched: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    validate(control: AbstractControl): ValidationErrors | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<InputMaskDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<InputMaskDirective, "input[sInputMask]", never, { "mask": { "alias": "sInputMask"; "required": false; "isSignal": true; }; "slotChar": { "alias": "slotChar"; "required": false; "isSignal": true; }; "unmask": { "alias": "unmask"; "required": false; "isSignal": true; }; "characterPattern": { "alias": "characterPattern"; "required": false; "isSignal": true; }; "autoClear": { "alias": "autoClear"; "required": false; "isSignal": true; }; }, { "maskComplete": "maskComplete"; }, never, never, true, never>;
+}

package/input-mask/lib/input-mask/input-mask.module.d.ts

@@ -0,0 +1,7 @@
+import * as i0 from "@angular/core";
+import * as i1 from "./input-mask.directive";
+export declare class InputMaskModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<InputMaskModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<InputMaskModule, never, [typeof i1.InputMaskDirective], [typeof i1.InputMaskDirective]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<InputMaskModule>;
+}

package/input-mask/public-api.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/input-mask/input-mask.directive';
+export * from './lib/input-mask/input-mask.module';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seniorsistemas/angular-components",
-  "version": "19.6.2",
+  "version": "19.7.0",
   "peerDependencies": {
     "@angular/cdk": "^18.2.14",
     "@angular/common": "^18.2.0",
@@ -96,36 +96,36 @@
       "esm": "./esm2022/accordion/seniorsistemas-angular-components-accordion.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-accordion.mjs"
     },
-    "./autocomplete": {
-      "types": "./autocomplete/index.d.ts",
-      "esm2022": "./esm2022/autocomplete/seniorsistemas-angular-components-autocomplete.mjs",
-      "esm": "./esm2022/autocomplete/seniorsistemas-angular-components-autocomplete.mjs",
-      "default": "./fesm2022/seniorsistemas-angular-components-autocomplete.mjs"
-    },
     "./alert": {
       "types": "./alert/index.d.ts",
       "esm2022": "./esm2022/alert/seniorsistemas-angular-components-alert.mjs",
       "esm": "./esm2022/alert/seniorsistemas-angular-components-alert.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-alert.mjs"
     },
+    "./autocomplete": {
+      "types": "./autocomplete/index.d.ts",
+      "esm2022": "./esm2022/autocomplete/seniorsistemas-angular-components-autocomplete.mjs",
+      "esm": "./esm2022/autocomplete/seniorsistemas-angular-components-autocomplete.mjs",
+      "default": "./fesm2022/seniorsistemas-angular-components-autocomplete.mjs"
+    },
     "./badge": {
       "types": "./badge/index.d.ts",
       "esm2022": "./esm2022/badge/seniorsistemas-angular-components-badge.mjs",
       "esm": "./esm2022/badge/seniorsistemas-angular-components-badge.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-badge.mjs"
     },
-    "./bignumber-input": {
-      "types": "./bignumber-input/index.d.ts",
-      "esm2022": "./esm2022/bignumber-input/seniorsistemas-angular-components-bignumber-input.mjs",
-      "esm": "./esm2022/bignumber-input/seniorsistemas-angular-components-bignumber-input.mjs",
-      "default": "./fesm2022/seniorsistemas-angular-components-bignumber-input.mjs"
-    },
     "./breadcrumb": {
       "types": "./breadcrumb/index.d.ts",
       "esm2022": "./esm2022/breadcrumb/seniorsistemas-angular-components-breadcrumb.mjs",
       "esm": "./esm2022/breadcrumb/seniorsistemas-angular-components-breadcrumb.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-breadcrumb.mjs"
     },
+    "./bignumber-input": {
+      "types": "./bignumber-input/index.d.ts",
+      "esm2022": "./esm2022/bignumber-input/seniorsistemas-angular-components-bignumber-input.mjs",
+      "esm": "./esm2022/bignumber-input/seniorsistemas-angular-components-bignumber-input.mjs",
+      "default": "./fesm2022/seniorsistemas-angular-components-bignumber-input.mjs"
+    },
     "./button": {
       "types": "./button/index.d.ts",
       "esm2022": "./esm2022/button/seniorsistemas-angular-components-button.mjs",
@@ -330,6 +330,12 @@
       "esm": "./esm2022/inline-edit/seniorsistemas-angular-components-inline-edit.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-inline-edit.mjs"
     },
+    "./input-mask": {
+      "types": "./input-mask/index.d.ts",
+      "esm2022": "./esm2022/input-mask/seniorsistemas-angular-components-input-mask.mjs",
+      "esm": "./esm2022/input-mask/seniorsistemas-angular-components-input-mask.mjs",
+      "default": "./fesm2022/seniorsistemas-angular-components-input-mask.mjs"
+    },
     "./insights": {
       "types": "./insights/index.d.ts",
       "esm2022": "./esm2022/insights/seniorsistemas-angular-components-insights.mjs",
@@ -444,18 +450,18 @@
       "esm": "./esm2022/pin-code-field/seniorsistemas-angular-components-pin-code-field.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-pin-code-field.mjs"
     },
-    "./product-header": {
-      "types": "./product-header/index.d.ts",
-      "esm2022": "./esm2022/product-header/seniorsistemas-angular-components-product-header.mjs",
-      "esm": "./esm2022/product-header/seniorsistemas-angular-components-product-header.mjs",
-      "default": "./fesm2022/seniorsistemas-angular-components-product-header.mjs"
-    },
     "./profile-picture-picker": {
       "types": "./profile-picture-picker/index.d.ts",
       "esm2022": "./esm2022/profile-picture-picker/seniorsistemas-angular-components-profile-picture-picker.mjs",
       "esm": "./esm2022/profile-picture-picker/seniorsistemas-angular-components-profile-picture-picker.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-profile-picture-picker.mjs"
     },
+    "./product-header": {
+      "types": "./product-header/index.d.ts",
+      "esm2022": "./esm2022/product-header/seniorsistemas-angular-components-product-header.mjs",
+      "esm": "./esm2022/product-header/seniorsistemas-angular-components-product-header.mjs",
+      "default": "./fesm2022/seniorsistemas-angular-components-product-header.mjs"
+    },
     "./progressbar": {
       "types": "./progressbar/index.d.ts",
       "esm2022": "./esm2022/progressbar/seniorsistemas-angular-components-progressbar.mjs",
@@ -600,18 +606,18 @@
       "esm": "./esm2022/thumbnail/seniorsistemas-angular-components-thumbnail.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-thumbnail.mjs"
     },
-    "./thumbnails": {
-      "types": "./thumbnails/index.d.ts",
-      "esm2022": "./esm2022/thumbnails/seniorsistemas-angular-components-thumbnails.mjs",
-      "esm": "./esm2022/thumbnails/seniorsistemas-angular-components-thumbnails.mjs",
-      "default": "./fesm2022/seniorsistemas-angular-components-thumbnails.mjs"
-    },
     "./tiered-menu": {
       "types": "./tiered-menu/index.d.ts",
       "esm2022": "./esm2022/tiered-menu/seniorsistemas-angular-components-tiered-menu.mjs",
       "esm": "./esm2022/tiered-menu/seniorsistemas-angular-components-tiered-menu.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-tiered-menu.mjs"
     },
+    "./thumbnails": {
+      "types": "./thumbnails/index.d.ts",
+      "esm2022": "./esm2022/thumbnails/seniorsistemas-angular-components-thumbnails.mjs",
+      "esm": "./esm2022/thumbnails/seniorsistemas-angular-components-thumbnails.mjs",
+      "default": "./fesm2022/seniorsistemas-angular-components-thumbnails.mjs"
+    },
     "./tile": {
       "types": "./tile/index.d.ts",
       "esm2022": "./esm2022/tile/seniorsistemas-angular-components-tile.mjs",
@@ -624,12 +630,6 @@
       "esm": "./esm2022/timeline/seniorsistemas-angular-components-timeline.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-timeline.mjs"
     },
-    "./toast": {
-      "types": "./toast/index.d.ts",
-      "esm2022": "./esm2022/toast/seniorsistemas-angular-components-toast.mjs",
-      "esm": "./esm2022/toast/seniorsistemas-angular-components-toast.mjs",
-      "default": "./fesm2022/seniorsistemas-angular-components-toast.mjs"
-    },
     "./token-list": {
       "types": "./token-list/index.d.ts",
       "esm2022": "./esm2022/token-list/seniorsistemas-angular-components-token-list.mjs",
@@ -642,6 +642,12 @@
       "esm": "./esm2022/tooltip/seniorsistemas-angular-components-tooltip.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-tooltip.mjs"
     },
+    "./toast": {
+      "types": "./toast/index.d.ts",
+      "esm2022": "./esm2022/toast/seniorsistemas-angular-components-toast.mjs",
+      "esm": "./esm2022/toast/seniorsistemas-angular-components-toast.mjs",
+      "default": "./fesm2022/seniorsistemas-angular-components-toast.mjs"
+    },
     "./topbar": {
       "types": "./topbar/index.d.ts",
       "esm2022": "./esm2022/topbar/seniorsistemas-angular-components-topbar.mjs",
@@ -654,18 +660,18 @@
       "esm": "./esm2022/tree/seniorsistemas-angular-components-tree.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-tree.mjs"
     },
-    "./utils": {
-      "types": "./utils/index.d.ts",
-      "esm2022": "./esm2022/utils/seniorsistemas-angular-components-utils.mjs",
-      "esm": "./esm2022/utils/seniorsistemas-angular-components-utils.mjs",
-      "default": "./fesm2022/seniorsistemas-angular-components-utils.mjs"
-    },
     "./workspace-switch": {
       "types": "./workspace-switch/index.d.ts",
       "esm2022": "./esm2022/workspace-switch/seniorsistemas-angular-components-workspace-switch.mjs",
       "esm": "./esm2022/workspace-switch/seniorsistemas-angular-components-workspace-switch.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-workspace-switch.mjs"
     },
+    "./utils": {
+      "types": "./utils/index.d.ts",
+      "esm2022": "./esm2022/utils/seniorsistemas-angular-components-utils.mjs",
+      "esm": "./esm2022/utils/seniorsistemas-angular-components-utils.mjs",
+      "default": "./fesm2022/seniorsistemas-angular-components-utils.mjs"
+    },
     "./common/deprecated-selector": {
       "types": "./common/deprecated-selector/index.d.ts",
       "esm2022": "./esm2022/common/deprecated-selector/seniorsistemas-angular-components-common-deprecated-selector.mjs",