@seniorsistemas/angular-components 19.3.1 → 19.3.2

package/pin-code-field/README.md

@@ -1,366 +0,0 @@
-# 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/spotlight/README.md

@@ -1,311 +0,0 @@
-# Spotlight
-
-## Descrição
-
-O Spotlight é uma biblioteca para criação de **tours guiados** (onboarding com múltiplos passos) e **destaques simples** (dicas únicas sobre um elemento). O posicionamento do popover é gerenciado automaticamente pelo Angular CDK, com fallbacks inteligentes para manter o popover sempre visível.
-
-Dois modos de operação:
-
-- **Tour**: sequência de passos com navegação Próximo / Voltar / Concluído, contador de progresso, focus trap e bloqueio de scroll.
-- **Destaque simples**: popover único com botão "Entendi" e opção de "Não mostrar novamente".
-
-## Instalação
-
-```bash
-npm install @seniorsistemas/angular-components/spotlight
-```
-
-## Conceitos
-
-### Diretiva `sSpotlightStep`
-
-Registra um elemento do DOM como alvo de um passo do tour. Deve ser aplicada ao elemento que receberá o destaque.
-
-```html
-<button sSpotlightStep="meu-botao">Salvar</button>
-```
-
-O valor do atributo é o `stepId`, que deve corresponder ao `stepId` definido nos passos do tour.
-Quando o valor do binding muda dinamicamente, a diretiva desregistra o ID anterior e registra o novo automaticamente.
-
-### `SpotlightTourService`
-
-Serviço singleton que controla o estado do tour. Injete-o no componente que inicia o tour.
-
----
-
-## Tour (múltiplos passos)
-
-### 1. Marque os elementos no template
-
-```html
-<input sSpotlightStep="produto-nome" ... />
-<select sSpotlightStep="produto-categoria" ... />
-<button sSpotlightStep="salvar-btn">Salvar</button>
-```
-
-### 2. Inicie o tour pelo serviço
-
-```typescript
-import { SpotlightTourService, SpotlightStep } from '@seniorsistemas/angular-components/spotlight';
-
-@Component({ ... })
-export class MeuComponent {
-  private readonly tourService = inject(SpotlightTourService);
-
-  private readonly passos: SpotlightStep[] = [
-    {
-      stepId: 'produto-nome',
-      title: 'Nome do produto',
-      message: 'Informe o nome completo do produto.',
-      position: 'bottom-center',
-    },
-    {
-      stepId: 'produto-categoria',
-      title: 'Categoria',
-      message: 'Selecione a categoria correta.',
-      position: 'bottom-end',
-      beforeNext: () => {
-        // Executado antes de avançar — útil para trocar abas, expandir seções, etc.
-        this.activeTab.set('detalhes');
-      },
-    },
-    {
-      stepId: 'salvar-btn',
-      title: 'Salvar',
-      message: 'Clique aqui para salvar as alterações.',
-      position: 'top-center',
-    },
-  ];
-
-  public iniciarTour(): void {
-    this.tourService.start(this.passos);
-  }
-}
-```
-
-### 3. Reaja aos eventos do tour
-
-```typescript
-private readonly destroyRef = inject(DestroyRef);
-
-public constructor() {
-  this.tourService.stopped$
-    .pipe(takeUntilDestroyed(this.destroyRef))
-    .subscribe((event) => {
-      // Salve o estado para persistência
-      localStorage.setItem('tour-onboarding', JSON.stringify({
-        reason: event.reason,           // 'completed' | 'interrupted'
-        doNotShowAgain: event.doNotShowAgain,
-        stepIndex: event.stepIndex,
-      }));
-    });
-}
-```
-
----
-
-## Destaque Simples
-
-Use `tourService.spotlight()` para exibir um destaque em um único elemento.
-
-```html
-<div sSpotlightStep="novo-recurso">...</div>
-```
-
-```typescript
-import { SpotlightTourService, SpotlightConfig } from '@seniorsistemas/angular-components/spotlight';
-
-@Component({ ... })
-export class MeuComponent {
-  private readonly tourService = inject(SpotlightTourService);
-
-  public mostrarDica(): void {
-    const config: SpotlightConfig = {
-      title: 'Novidade!',
-      message: 'Este recurso foi adicionado recentemente.',
-      position: 'bottom-center',
-      // showDoNotShowAgain é true por padrão — passe false para suprimir o checkbox
-      dismissible: true,
-    };
-
-    this.tourService.spotlight('novo-recurso', config);
-  }
-}
-```
-
-Ao encerrar, `stopped$` emite com `reason: 'dismissed'` (usuário fechou) ou `reason: 'completed'` (clicou em "Entendi"). Quando `doNotShowAgain` é `true`, salve essa preferência para não exibir novamente.
-
----
-
-## `SpotlightStep`
-
-| Propriedade | Tipo | Obrigatório | Descrição |
-|---|---|---|---|
-| `stepId` | `string` | ✓ | Identificador único do passo. Deve corresponder ao valor do `sSpotlightStep` no template. |
-| `title` | `string \| TemplateRef<any>` | ✓ | Título do popover (máx. recomendado: 30 caracteres). |
-| `message` | `string \| TemplateRef<any>` | ✓ | Texto descritivo (máx. recomendado: 75 caracteres). |
-| `position` | `SpotlightPosition` | — | Posição preferida do popover. Padrão: `'bottom-center'`. |
-| `content` | `TemplateRef<any> \| null` | — | Conteúdo visual customizado (imagem, gif, vídeo) exibido acima da mensagem. |
-| `actions` | `SpotlightStepAction[]` | — | Botões de ação customizados exibidos antes dos botões de navegação. |
-| `showBackdrop` | `boolean` | — | Exibe o backdrop escurecido ao redor do elemento destacado. Padrão: `true`. |
-| `dismissible` | `boolean` | — | Permite fechar o spotlight clicando fora ou pressionando Escape. Padrão: `true`. |
-| `beforeNext` | `() => void \| Promise<void>` | — | Callback executado antes de avançar para o próximo passo. Suporta async/await. |
-| `beforePrevious` | `() => void \| Promise<void>` | — | Callback executado antes de voltar ao passo anterior. Suporta async/await. |
-
-## `SpotlightConfig`
-
-Equivalente ao `SpotlightStep` sem `stepId`, `beforeNext` e `beforePrevious`. Usado exclusivamente com `tourService.spotlight()`. Inclui a propriedade adicional:
-
-| Propriedade | Tipo | Descrição |
-|---|---|---|
-| `showDoNotShowAgain` | `boolean` | Exibe o checkbox "Não mostrar novamente". Padrão: `true`. Passe `false` para suprimir. |
-
-## `SpotlightStepAction`
-
-| Propriedade | Tipo | Descrição |
-|---|---|---|
-| `label` | `string` | Texto do botão. |
-| `handler` | `() => void` | Função executada ao clicar no botão. |
-
----
-
-## `SpotlightTourService`
-
-### Propriedades
-
-| Propriedade | Tipo | Descrição |
-|---|---|---|
-| `isActive` | `Signal<boolean>` | `true` enquanto o tour estiver ativo. |
-| `currentStep` | `Signal<SpotlightStep \| undefined>` | Passo atualmente exibido. |
-| `currentIndex` | `Signal<number>` | Índice do passo atual (base 0). |
-| `totalSteps` | `Signal<number>` | Total de passos do tour. |
-| `stopped$` | `Observable<SpotlightStopEvent>` | Emite quando o tour é encerrado. |
-| `stepChanged$` | `Observable<SpotlightStepChangedEvent>` | Emite ao mudar de passo (incluindo o primeiro). |
-
-### Métodos
-
-| Método | Descrição |
-|---|---|
-| `start(steps: SpotlightStep[])` | Inicia o tour com a lista de passos fornecida. Ignora arrays vazios. Se houver um tour ativo, encerra-o (emitindo `stopped$`) antes de iniciar o novo. |
-| `spotlight(stepId, config: SpotlightConfig)` | Exibe um destaque simples em um único elemento. |
-| `next(doNotShowAgain?: boolean)` | Avança para o próximo passo ou conclui o tour. |
-| `previous()` | Volta ao passo anterior. |
-| `stop(event?: Partial<SpotlightStopEvent>)` | Encerra o tour programaticamente. |
-| `registerElement(stepId, el)` | Registra um elemento (usado internamente pela diretiva). |
-| `unregisterElement(stepId)` | Remove o registro de um elemento. |
-| `getElement(stepId)` | Retorna o `ElementRef` registrado para o `stepId`. |
-
----
-
-## Eventos (`SpotlightStopEvent`)
-
-Emitido por `stopped$` ao encerrar o tour.
-
-| Campo | Tipo | Descrição |
-|---|---|---|
-| `reason` | `SpotlightStopReason` | Razão do encerramento. |
-| `doNotShowAgain` | `boolean` | `true` se o usuário marcou "Não mostrar novamente". |
-| `stepId` | `string` | `stepId` do passo em que o tour foi encerrado. |
-| `stepIndex` | `number` | Índice (base 0) do passo em que o tour foi encerrado. |
-| `totalSteps` | `number` | Total de passos do tour. |
-
-### `SpotlightStopReason`
-
-| Valor | Quando ocorre | Comportamento recomendado |
-|---|---|---|
-| `'completed'` | Usuário clicou em "Concluído" ou "Entendi" | Nunca reexibir |
-| `'interrupted'` | Usuário fechou o tour antes de concluir (X, Escape, clique fora) | Reexibir na próxima sessão |
-| `'dismissed'` | Usuário fechou um destaque simples | Reexibir após cooldown |
-
-### `SpotlightStepChangedEvent`
-
-Emitido por `stepChanged$` a cada mudança de passo.
-
-| Campo | Tipo | Descrição |
-|---|---|---|
-| `stepId` | `string` | `stepId` do novo passo. |
-| `stepIndex` | `number` | Índice (base 0) do novo passo. |
-| `totalSteps` | `number` | Total de passos do tour. |
-
----
-
-## Posições Disponíveis (`SpotlightPosition`)
-
-| Valor | Descrição |
-|---|---|
-| `'top-start'` | Acima do elemento, alinhado à esquerda |
-| `'top-center'` | Acima do elemento, centralizado |
-| `'top-end'` | Acima do elemento, alinhado à direita |
-| `'bottom-start'` | Abaixo do elemento, alinhado à esquerda |
-| `'bottom-center'` | Abaixo do elemento, centralizado |
-| `'bottom-end'` | Abaixo do elemento, alinhado à direita |
-| `'left-start'` | À esquerda do elemento, alinhado ao topo |
-| `'left-center'` | À esquerda do elemento, centralizado |
-| `'left-end'` | À esquerda do elemento, alinhado à base |
-| `'right-start'` | À direita do elemento, alinhado ao topo |
-| `'right-center'` | À direita do elemento, centralizado |
-| `'right-end'` | À direita do elemento, alinhado à base |
-
-> O CDK ajusta automaticamente a posição quando não há espaço suficiente, garantindo que o popover sempre permaneça visível.
-
----
-
-## Persistência
-
-A persistência do estado (se o tour já foi visto, preferência "Não mostrar novamente", etc.) é responsabilidade do produto consumidor. Use os dados emitidos por `stopped$` para implementar a estratégia adequada:
-
-```typescript
-this.tourService.stopped$.subscribe((event) => {
-  const estado = {
-    reason: event.reason,
-    doNotShowAgain: event.doNotShowAgain,
-    contentVersion: 'v2', // versão do conteúdo do tour, controlada pelo produto
-  };
-  localStorage.setItem('tour-onboarding', JSON.stringify(estado));
-});
-
-// Na inicialização:
-const salvo = JSON.parse(localStorage.getItem('tour-onboarding') ?? 'null');
-const deveExibir =
-  !salvo ||
-  salvo.contentVersion !== 'v2' ||          // novo conteúdo → reexibir
-  salvo.reason === 'interrupted';            // não concluiu → reexibir
-
-if (deveExibir && !salvo?.doNotShowAgain) {
-  // Chamar tourService.start(passos) no momento adequado
-}
-```
-
----
-
-## Telemetria
-
-Use os observables do serviço para enviar eventos ao seu sistema de analytics:
-
-```typescript
-// Tour iniciado (step 0)
-this.tourService.stepChanged$
-  .pipe(filter((e) => e.stepIndex === 0 && e.totalSteps > 1))
-  .subscribe(() => analytics.track('tour_viewed'));
-
-// Tour concluído
-this.tourService.stopped$
-  .pipe(filter((e) => e.reason === 'completed' && e.totalSteps > 1))
-  .subscribe(() => analytics.track('tour_completed'));
-
-// Tour interrompido
-this.tourService.stopped$
-  .pipe(filter((e) => e.reason === 'interrupted'))
-  .subscribe(() => analytics.track('tour_interrupted'));
-
-// Destaque simples fechado
-this.tourService.stopped$
-  .pipe(filter((e) => e.reason === 'dismissed'))
-  .subscribe(() => analytics.track('spotlight_dismissed'));
-
-// "Não mostrar novamente" marcado
-this.tourService.stopped$
-  .pipe(filter((e) => e.doNotShowAgain))
-  .subscribe(() => analytics.track('spotlight_do_not_show_again_checked'));
-```