@seniorsistemas/angular-components 18.0.4 → 18.1.0-feature-sds-276-640ecaac

package/pin-code-field/README.md

@@ -0,0 +1,366 @@
+# Pin Code Field
+
+O `PinCodeFieldComponent` é um componente customizado que encapsula múltiplos inputs para entrada de códigos de autenticação (tokens, OTP, etc.). O componente implementa `ControlValueAccessor`, tornando-o totalmente compatível com formulários reativos e template-driven do Angular.
+
+## Features
+
+- Compatível com `ngModel` e `ReactiveForms` (`ControlValueAccessor`)
+- Validação flexível delegada ao `FormControl` do usuário
+- Configuração flexível de comprimento do código
+- Suporte a caracteres alfanuméricos e especiais (opcional)
+- Navegação entre campos com setas (esquerda/direita)
+- Suporte a colar código (trunca se maior que o comprimento)
+- Suporte a backspace com navegação automática
+- Estados visuais: normal, foco, desabilitado e erro
+- Controle de estado de erro via input `invalid`
+- Help text descritivo
+- Acessibilidade completa (ARIA labels, roles, etc.)
+- Integração com `s-control-errors` para exibição de mensagens de erro
+
+## Dependências
+
+Nenhuma dependência adicional além do Angular.
+
+## Utilização
+
+**[Exemplo completo de implementação](../../../../src/app/components/pin-code-field-showcase)**
+
+- **Componente**: `PinCodeFieldComponent`
+- **Seletor do componente**: `s-pin-code-field`
+
+### Import
+
+```typescript
+import { PinCodeFieldComponent } from '@seniorsistemas/angular-components/pin-code-field';
+```
+
+## Exemplos de utilização
+
+### Exemplo básico com template-driven forms
+
+```html
+<form #myForm="ngForm">
+    <s-pin-code-field
+        name="code"
+        [(ngModel)]="code"
+        [length]="6"
+        helpText="Digite o código enviado para seu email"
+    >
+    </s-pin-code-field>
+</form>
+```
+
+### Exemplo com formulário reativo
+
+```typescript
+import { Component } from '@angular/core';
+import { FormBuilder, FormGroup, Validators } from '@angular/forms';
+
+@Component({
+    selector: 'app-auth-form',
+    template: `
+        <form [formGroup]="form">
+            <s-pin-code-field
+                formControlName="code"
+                [length]="6"
+                [alphanumeric]="false"
+                [invalid]="(form.get('code')?.invalid && form.get('code')?.dirty) || false"
+                helpText="Digite o código de 6 dígitos"
+            >
+            </s-pin-code-field>
+            <s-control-errors
+                [control]="form.get('code')"
+                [errorMessages]="errorMessages"
+                [displayErrors]="submitted"
+            >
+            </s-control-errors>
+        </form>
+    `,
+})
+export class AuthFormComponent {
+    form: FormGroup;
+    submitted = false;
+    errorMessages = {
+        required: 'Este campo é obrigatório e não foi preenchido.',
+    };
+
+    constructor(private fb: FormBuilder) {
+        this.form = this.fb.group({
+            code: ['', [Validators.required()]],
+        });
+    }
+}
+```
+
+### Exemplo com listener de preenchimento
+
+```html
+<s-pin-code-field
+    [(ngModel)]="code"
+    [length]="6"
+    (codeFilled)="onCodeFilled($event)"
+>
+</s-pin-code-field>
+```
+
+```typescript
+export class MyComponent {
+    code: string = '';
+
+    onCodeFilled(code: string) {
+        console.log('Código completado:', code);
+        // Realizar verificação do código
+    }
+}
+```
+
+### Exemplo com caracteres alfanuméricos
+
+```html
+<s-pin-code-field
+    [(ngModel)]="code"
+    [length]="8"
+    [alphanumeric]="true"
+    helpText="Código pode conter letras, números e caracteres especiais"
+>
+</s-pin-code-field>
+```
+
+## Inputs
+
+| Nome           | Tipo             | Valor Padrão | Obrigatório | Descrição                                                                                                                                      |
+| -------------- | ---------------- | ------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `length`       | `input<number>`  | 6            | Não         | Quantidade de caracteres que o código deve ter.                                                                                                |
+| `alphanumeric` | `input<boolean>` | false        | Não         | Se true, aceita letras, números e caracteres especiais. Se false, aceita apenas números.                                                       |
+| `helpText`     | `input<string>`  | ''           | Não         | Texto de ajuda exibido abaixo dos campos.                                                                                                      |
+| `invalid`      | `input<boolean>` | false        | Não         | Controla se o componente exibe estado de erro (borda vermelha). Use em conjunto com `FormControl.invalid && FormControl.dirty` para validação. |
+| `disabled`     | `model<boolean>` | false        | Não         | Desabilita todos os campos impedindo entrada de dados. Two-way binding.                                                                        |
+
+## Outputs
+
+| Nome         | Tipo                   | Descrição                                                                                          |
+| ------------ | ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `codeFilled` | `EventEmitter<string>` | Emitido quando todos os caracteres do código são preenchidos. Emite o código completo como string. |
+
+## Validators
+
+O componente exporta dois validators personalizados que trabalham como `ValidatorFn` do Angular:
+
+### `incomplete(length?: number)`
+
+Valida se o código foi totalmente preenchido. Retorna erro `incomplete` se houver preenchimento parcial.
+
+```typescript
+const control = new FormControl('', [Validators.required(), incomplete(6)]);
+```
+
+**Parâmetro:**
+
+- `length` (opcional): Comprimento esperado do código (padrão: 6)
+
+**Retorna:**
+
+- `{ incomplete: true }` se o valor parcial for preenchido
+- `null` se o código estiver completo ou vazio
+
+### `pasteError(component?: PinCodeFieldComponent)`
+
+Valida se houve erro ao colar conteúdo inválido. Retorna erro `pasteError` quando um paste inválido é detectado.
+
+```typescript
+const control = new FormControl('', [pasteError()]);
+```
+
+**Nota:** Este validator monitora o estado interno do componente para detectar tentativas de paste com conteúdo inválido.
+
+## Comportamentos
+
+### Navegação
+
+- **Seta Direita**: Move o foco para o próximo campo
+- **Seta Esquerda**: Move o foco para o campo anterior
+- **Seta Para Cima/Baixo**: Sem efeito
+
+### Entrada de Dados
+
+- A digitação automática avança para o próximo campo quando um caractere é inserido
+- No último campo, a digitação não causa mudança de foco
+- Todos os campos são preenchidos ao colar um código válido
+
+### Backspace
+
+- **Campo preenchido**: Limpa o campo atual e mantém o foco
+- **Campo vazio**: Move para o campo anterior, limpa-o e mantém o foco no anterior
+
+### Paste (Colar)
+
+- Filtra caracteres inválidos de acordo com a configuração `alphanumeric`
+- Se o texto colado é maior que o comprimento, trunca automaticamente
+- Preenche os campos disponíveis com o texto colado filtrado
+- Emite o evento `codeFilled` quando todos os campos são preenchidos
+- A validação de valores aceitáveis é responsabilidade do `FormControl` validator
+
+### Estados Visuais
+
+- **Normal**: Borda cinza, fundo branco
+- **Foco**: Borda azul com ring de foco
+- **Desabilitado**: Fundo cinza claro, texto cinza, sem interação
+- **Erro**: Borda e ring vermelhos (quando `invalid` input é true)
+
+## Validação
+
+O componente **não exporta validators pré-construídos**. A validação é responsabilidade do usuário via `FormControl.validator`.
+
+Exemplos de validators customizados:
+
+```typescript
+// Validar que o código tem exatamente 6 dígitos
+const requiredValidator = Validators.required();
+
+// Validador customizado para rejeitar valor específico
+const notBlacklisted: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
+    const value = control.value as string;
+    if (value === '123456') {
+        return { blacklisted: true };
+    }
+    return null;
+};
+
+const form = this.fb.group({
+    code: ['', [requiredValidator, notBlacklisted]],
+});
+```
+
+### Mostrando Erros de Validação
+
+Use o input `invalid` para controlar visualmente o estado de erro:
+
+```html
+<s-pin-code-field
+    formControlName="code"
+    [invalid]="(form.get('code')?.invalid && form.get('code')?.dirty) || false"
+>
+</s-pin-code-field>
+```
+
+## Acessibilidade
+
+O componente implementa padrões de acessibilidade completos:
+
+- Cada input tem um `aria-label` descritivo com sua posição no código
+- O container tem `role="group"` e associação com help text
+- `aria-invalid` é definido quando há erro
+- `aria-describedby` conecta inputs ao help text
+- `inputmode` é configurado corretamente (numeric/text)
+- `autocomplete="off"` previne preenchimento automático indesejado
+- Todos os estados visuais incluem indicadores para leitores de tela
+
+## Exemplos Completos
+
+### Integração com Reactive Forms e validação customizada
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { FormBuilder, FormGroup, Validators, AbstractControl, ValidationErrors, ValidatorFn } from '@angular/forms';
+
+// Validador customizado que rejeita um valor específico
+const notBlacklisted: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
+    const value = control.value as string;
+    if (value === '123456') {
+        return { blacklisted: true };
+    }
+    return null;
+};
+
+@Component({
+    selector: 'app-verify-code',
+    template: `
+        <form [formGroup]="verifyForm">
+            <s-pin-code-field
+                formControlName="verificationCode"
+                [length]="6"
+                [alphanumeric]="false"
+                [invalid]="(control?.invalid && control?.dirty) || false"
+                helpText="Digite o código de 6 dígitos enviado"
+                (codeFilled)="verifyCode($event)"
+            >
+            </s-pin-code-field>
+
+            <s-control-errors
+                [control]="control"
+                [errorMessages]="errorMessages"
+                [displayErrors]="submitted"
+            >
+            </s-control-errors>
+
+            <button
+                [disabled]="!verifyForm.valid"
+                (click)="submit()"
+            >
+                Verificar
+            </button>
+        </form>
+    `,
+})
+export class VerifyCodeComponent implements OnInit {
+    verifyForm!: FormGroup;
+    submitted = false;
+    errorMessages = {
+        required: 'Código obrigatório',
+        blacklisted: 'Este código não é válido',
+    };
+
+    get control() {
+        return this.verifyForm.get('verificationCode');
+    }
+
+    constructor(private fb: FormBuilder) {}
+
+    ngOnInit() {
+        this.verifyForm = this.fb.group({
+            verificationCode: ['', [Validators.required, notBlacklisted]],
+        });
+    }
+
+    verifyCode(code: string) {
+        console.log('Código completo:', code);
+        // Enviar para API de verificação
+    }
+
+    submit() {
+        this.submitted = true;
+        if (this.verifyForm.valid) {
+            this.verifyCode(this.verifyForm.value.verificationCode);
+        }
+    }
+}
+```
+
+### Com loading e desabilitação após envio
+
+```typescript
+export class VerifyCodeComponent {
+    verifyForm!: FormGroup;
+    isLoading = false;
+
+    verifyCode(code: string) {
+        this.isLoading = true;
+        // Desabilita o campo durante a requisição
+        this.verifyForm.get('verificationCode')?.disable();
+
+        this.authService.verify(code).subscribe(
+            (response) => {
+                // Sucesso
+                this.isLoading = false;
+            },
+            (error) => {
+                // Erro - reabilita o formulário
+                this.isLoading = false;
+                this.verifyForm.get('verificationCode')?.enable();
+                this.verifyForm.get('verificationCode')?.reset();
+            },
+        );
+    }
+}
+```
+

package/pin-code-field/index.d.ts

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

package/pin-code-field/lib/pin-code-field/pin-code-field.component.d.ts

@@ -0,0 +1,284 @@
+import { ElementRef } from '@angular/core';
+import { ControlValueAccessor } from '@angular/forms';
+import * as i0 from "@angular/core";
+/**
+ * Pin Code Field Component
+ *
+ * A flexible, accessible PIN code input component that implements {@link ControlValueAccessor}
+ * for seamless integration with Angular Reactive Forms and Template-driven Forms.
+ *
+ * Features:
+ * - Multiple input fields for PIN/OTP code entry
+ * - Configurable code length and character validation
+ * - Keyboard navigation (arrow keys, backspace)
+ * - Paste support with automatic truncation
+ * - Error state display via the `invalid` input
+ * - Full accessibility support (ARIA labels, semantic roles)
+ * - Signal-based state management
+ *
+ * @example
+ * ```html
+ * <form [formGroup]="form">
+ *   <s-pin-code-field
+ *     formControlName="code"
+ *     [length]="6"
+ *     [alphanumeric]="false"
+ *     [invalid]="(form.get('code')?.invalid && form.get('code')?.dirty) || false"
+ *     helpText="Enter your 6-digit code"
+ *     (codeFilled)="onCodeFilled($event)">
+ *   </s-pin-code-field>
+ * </form>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * form = this.fb.group({
+ *   code: ['', [Validators.required]],
+ * });
+ * ```
+ */
+export declare class PinCodeFieldComponent implements ControlValueAccessor {
+    private static readonly LAST_INDEX_OFFSET;
+    private static readonly EMPTY_VALUE;
+    /**
+     * Number of input fields (PIN code length).
+     * Must be at least 1.
+     *
+     * @default 6
+     */
+    length: import("@angular/core").InputSignal<number>;
+    /**
+     * Allows alphanumeric and special characters input.
+     * When false, only numeric input (0-9) is accepted.
+     *
+     * @default false
+     */
+    alphanumeric: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Help text displayed below the input fields.
+     *
+     * @default ''
+     */
+    helpText: import("@angular/core").InputSignal<string>;
+    /**
+     * Controls the error state visualization of the component.
+     * When true, displays red border on input fields.
+     * Typically bound to FormControl's invalid and dirty state.
+     *
+     * @example
+     * ```html
+     * [invalid]="(control?.invalid && control?.dirty) || false"
+     * ```
+     * @default false
+     */
+    invalid: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Two-way binding for the disabled state of the component.
+     * Disables all input fields and prevents user interaction.
+     *
+     * @default false
+     */
+    disabled: import("@angular/core").ModelSignal<boolean>;
+    /**
+     * Emitted when all PIN code fields are filled.
+     * Emits the complete PIN code as a string.
+     *
+     * @example
+     * ```html
+     * (codeFilled)="onCodeFilled($event)"
+     * ```
+     */
+    codeFilled: import("@angular/core").OutputEmitterRef<string>;
+    /**
+     * Signal containing the current values of each input field.
+     * Array length matches the `length` input value.
+     */
+    inputs: import("@angular/core").WritableSignal<string[]>;
+    /**
+     * Signal tracking whether the component has been touched by the user.
+     * Set to true when the last input field loses focus (blur event).
+     */
+    touched: import("@angular/core").WritableSignal<boolean>;
+    /**
+     * Computed signal indicating whether all PIN code fields are filled.
+     * True only when every field contains a non-empty value.
+     */
+    isComplete: import("@angular/core").Signal<boolean>;
+    /**
+     * Computed signal containing the complete PIN code as a joined string.
+     * Returns empty string if no inputs are filled.
+     */
+    currentValue: import("@angular/core").Signal<string>;
+    /**
+     * Signal tracking if the component host has the ng-invalid class from FormControl validators.
+     * Updated reactively whenever the invalid state changes.
+     */
+    private hasNgInvalidClass;
+    /**
+     * Signal tracking if the FormControl is dirty.
+     * Updated reactively whenever the dirty state changes.
+     */
+    private isControlDirty;
+    /**
+     * Computed signal indicating if the component should show error state.
+     * Returns true if:
+     * - The `invalid` input is true, OR
+     * - The component has the `ng-invalid` class AND the FormControl is dirty (touched/modified)
+     * This ensures errors are only shown to the user after they've interacted with the field.
+     */
+    hasError: import("@angular/core").Signal<boolean>;
+    /**
+     * ViewChildren reference to all input DOM elements.
+     * Used for DOM manipulation (focus, selection).
+     */
+    pinInputs: import("@angular/core").Signal<readonly ElementRef<any>[]>;
+    private readonly elementRef;
+    private readonly destroyRef;
+    private onChange;
+    private onTouched;
+    constructor();
+    /**
+     * Handles input event on PIN code fields.
+     * Validates character input, prevents multiple characters per field,
+     * auto-advances to next field when character is entered.
+     *
+     * @param index - The input field index (0-based)
+     * @param event - The input event
+     */
+    onInput(index: number, event: Event): void;
+    /**
+     * Handles keyboard events on PIN code fields.
+     * Supports arrow navigation (left/right) and backspace key.
+     *
+     * Keyboard behavior:
+     * - ArrowRight: Move focus to next field
+     * - ArrowLeft: Move focus to previous field
+     * - Backspace: Clear current or previous field and adjust focus
+     *
+     * @param index - The input field index (0-based)
+     * @param event - The keyboard event
+     */
+    onKeyDown(index: number, event: KeyboardEvent): void;
+    /**
+     * Handles paste (clipboard) events on PIN code fields.
+     * Extracts valid characters from pasted content, filters by character type,
+     * and automatically truncates to match field length.
+     *
+     * Behavior:
+     * - Filters characters based on `alphanumeric` setting
+     * - Truncates to maximum field count
+     * - Fills available fields with pasted content
+     * - Emits codeFilled event if all fields are filled
+     *
+     * @param event - The clipboard event
+     */
+    onPaste(event: ClipboardEvent): void;
+    /**
+     * Handles focus event on PIN code fields.
+     * Selects all text in the input field when focused.
+     *
+     * @param index - The input field index (0-based)
+     */
+    onFocus(index: number): void;
+    /**
+     * Handles blur event on PIN code fields.
+     * Marks the component as touched when the last input field loses focus.
+     * Also notifies the registered onTouched callback for FormControl integration.
+     *
+     * @param index - The input field index (0-based)
+     */
+    onBlur(index: number): void;
+    /**
+     * Clears the input value at specified index and adjusts focus accordingly.
+     * If current field is empty, moves to previous field and clears it.
+     *
+     * @private
+     * @param index - The input field index (0-based)
+     */
+    private handleBackspace;
+    /**
+     * Sets the value at a specific input field index and updates the form value.
+     * Updates the signal and triggers the change detection via onChange callback.
+     *
+     * @private
+     * @param index - The input field index (0-based)
+     * @param value - The value to set in the field
+     */
+    private setInputAtIndex;
+    /**
+     * Focuses on and selects text in the input field at the specified index.
+     * Uses queueMicrotask to ensure DOM is updated before focusing.
+     *
+     * @private
+     * @param index - The input field index (0-based)
+     */
+    private focusAndSelectInput;
+    /**
+     * Clears the value of an input element.
+     * Used for input validation to reject invalid characters.
+     *
+     * @private
+     * @param target - The HTML input element to clear
+     */
+    private clearInput;
+    /**
+     * Extracts valid characters from pasted content.
+     * Filters based on alphanumeric setting and limits to component's length.
+     *
+     * @private
+     * @param event - The clipboard event
+     * @returns Array of valid characters from the pasted content
+     */
+    private extractValidCharactersFromPaste;
+    /**
+     * Validates if a character is acceptable based on component configuration.
+     * For numeric mode, accepts only digits 0-9.
+     * For alphanumeric mode, accepts any non-whitespace character.
+     *
+     * @private
+     * @param char - The character to validate
+     * @returns true if character is valid, false otherwise
+     */
+    private isValidCharacter;
+    /**
+     * Updates the form value by calling the onChange callback registered by FormControl.
+     * This ensures the reactive form stays synchronized with component state.
+     *
+     * @private
+     */
+    private updateValue;
+    /**
+     * Implements ControlValueAccessor interface.
+     * Called by the FormControl to write a value to the component.
+     * Only accepts string values with length matching the component's length setting.
+     *
+     * @param value - The value to write (typically from the FormControl)
+     */
+    writeValue(value: any): void;
+    /**
+     * Implements ControlValueAccessor interface.
+     * Called by the FormControl when value changes.
+     * Registers the callback to be called when the component value changes.
+     *
+     * @param fn - Callback function to invoke when component value changes
+     */
+    registerOnChange(fn: (value: string) => void): void;
+    /**
+     * Implements ControlValueAccessor interface.
+     * Called by the FormControl to register the touched callback.
+     * The callback is invoked when the last input field loses focus.
+     *
+     * @param fn - Callback function to invoke when component is touched
+     */
+    registerOnTouched(fn: () => void): void;
+    /**
+     * Implements ControlValueAccessor interface.
+     * Called by the FormControl to set the disabled state of the component.
+     * Updates the disabled model to reflect the form's disabled state.
+     *
+     * @param isDisabled - Whether the component should be disabled
+     */
+    setDisabledState(isDisabled: boolean): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PinCodeFieldComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<PinCodeFieldComponent, "s-pin-code-field", never, { "length": { "alias": "length"; "required": false; "isSignal": true; }; "alphanumeric": { "alias": "alphanumeric"; "required": false; "isSignal": true; }; "helpText": { "alias": "helpText"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "disabled": "disabledChange"; "codeFilled": "codeFilled"; }, never, never, true, never>;
+}

package/pin-code-field/lib/pin-code-field.module.d.ts

@@ -0,0 +1,7 @@
+import * as i0 from "@angular/core";
+import * as i1 from "./pin-code-field/pin-code-field.component";
+export declare class PinCodeFieldModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<PinCodeFieldModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<PinCodeFieldModule, never, [typeof i1.PinCodeFieldComponent], [typeof i1.PinCodeFieldComponent]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<PinCodeFieldModule>;
+}

package/pin-code-field/public-api.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/pin-code-field.module';
+export * from './lib/pin-code-field/pin-code-field.component';