@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/mouse-events/README.md

@@ -0,0 +1,157 @@
+# MouseEvents
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Módulo com duas diretivas para eventos de mouse avançados: `sLongPress` (pressão longa) e `sDoubleClick` (duplo clique). Permitem detectar gestos específicos que o DOM nativo não suporta nativamente de forma consistente.
+
+## Quando usar
+
+- Ações de contexto em dispositivos touch via `sLongPress` (equivalente ao clique direito)
+- Edição inline acionada por duplo clique via `sDoubleClick`
+- Seleção múltipla ao pressionar e arrastar (combinado com long press)
+- Evitar acionamentos acidentais exigindo gestos deliberados
+
+## Quando não usar
+
+- Quando o clique simples é suficiente — use `(click)` nativo
+- Quando a acessibilidade via teclado é necessária — combine com [`InteractiveContent`](../interactive-content/README.md)
+
+## Instalação
+
+```typescript
+import { MouseEventsModule } from '@seniorsistemas/angular-components/mouse-events';
+
+@NgModule({
+    imports: [MouseEventsModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<!-- Long Press -->
+<div [sLongPressDelay]="500" (sLongPress)="onLongPress($event)">
+    Pressione e segure
+</div>
+
+<!-- Double Click -->
+<div sDoubleClick (doubleClicked)="onDoubleClick($event)">
+    Clique duas vezes
+</div>
+```
+
+## API
+
+### Diretiva `sLongPress`
+
+#### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `sLongPressDelay` | `number` | `500` | Não | Tempo em milissegundos para disparar o long press após pressionar o elemento. |
+
+#### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `sLongPress` | `EventEmitter<MouseEvent>` | Emitido quando o elemento é pressionado por mais de `sLongPressDelay` ms sem soltar. |
+
+### Diretiva `sDoubleClick`
+
+#### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `doubleClicked` | `EventEmitter<PointerEvent>` | Emitido quando dois cliques ocorrem dentro de 500ms. |
+
+## Exemplos
+
+### Long Press para menu de contexto
+
+```html
+<div
+    [sLongPressDelay]="800"
+    (sLongPress)="abrirMenuContexto($event)"
+    style="padding: 16px; cursor: pointer; user-select: none;"
+>
+    Pressione e segure para opções
+</div>
+```
+
+### Long Press com delay customizado
+
+```html
+<div
+    sLongPress
+    [sLongPressDelay]="1000"
+    (sLongPress)="onLongPress()"
+    style="width: 200px; height: 100px; background: #6366f1; color: white; display: flex; align-items: center; justify-content: center; border-radius: 8px; cursor: pointer; user-select: none;"
+>
+    Segure por 1 segundo
+</div>
+```
+
+### Double Click para edição inline
+
+```html
+<div
+    sDoubleClick
+    (doubleClicked)="ativarEdicao(item)"
+    style="padding: 8px; cursor: text;"
+>
+    @if (!editando) {
+        <span>{{ item.valor }}</span>
+    } @else {
+        <input [(ngModel)]="item.valor" (blur)="salvar(item)" />
+    }
+</div>
+```
+
+### Uso combinado (long press + double click)
+
+```html
+<div
+    sDoubleClick
+    (doubleClicked)="onDoubleClick(item)"
+    [sLongPressDelay]="600"
+    (sLongPress)="onLongPress(item)"
+    style="padding: 16px; border: 1px solid #e5e7eb; border-radius: 8px; cursor: pointer; user-select: none;"
+>
+    {{ item.titulo }}
+</div>
+```
+
+### Visão geral lado a lado
+
+```html
+<div style="display: flex; gap: 24px;">
+    <div
+        sLongPress
+        [sLongPressDelay]="500"
+        (sLongPress)="longPressCount = longPressCount + 1"
+        style="padding: 16px; background: #7892a1; color: white; border-radius: 8px; cursor: pointer; user-select: none;"
+    >
+        Pressione e segure ({{ longPressCount }})
+    </div>
+
+    <div
+        sDoubleClick
+        (doubleClicked)="doubleClickCount = doubleClickCount + 1"
+        style="padding: 16px; background: #059669; color: white; border-radius: 8px; cursor: pointer; user-select: none;"
+    >
+        Clique duas vezes ({{ doubleClickCount }})
+    </div>
+</div>
+```
+
+## Acessibilidade
+
+- `sLongPress` detecta eventos `mousedown`/`mouseup` e `touchstart`/`touchend` — funciona em dispositivos touch
+- `sDoubleClick` usa intervalo de 500ms entre cliques — não conflita com o evento `dblclick` nativo
+- Para garantir acessibilidade via teclado em elementos com essas diretivas, combine com [`InteractiveContent`](../interactive-content/README.md)
+
+## Componentes relacionados
+
+- [`InteractiveContent`](../interactive-content/README.md) — acessibilidade via teclado para elementos customizados
+- [`Button`](../button/README.md) — botão nativo com acessibilidade integrada; prefira quando a semântica de botão é adequada

package/navigation-button/README.md

@@ -0,0 +1,160 @@
+# NavigationButton
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de navegação por etapas que exibe o passo atual com botões de avançar e retroceder. Ao clicar no label central, abre um dropdown (TieredMenu) para seleção direta de qualquer etapa. Implementa `ControlValueAccessor` para integração com Angular Forms.
+
+## Quando usar
+
+- Navegação entre períodos (meses, trimestres, anos) em relatórios e dashboards
+- Paginação de etapas onde o usuário pode avançar, retroceder ou pular diretamente
+- Fluxos de wizard com etapas sequenciais nomeadas
+
+## Quando não usar
+
+- Quando o usuário precisa ver o progresso visual de todas as etapas simultaneamente — prefira [`Stepper`](../stepper/README.md) ou [`Steps`](../steps/README.md)
+- Navegação por páginas numeradas — prefira paginação convencional
+
+## Instalação
+
+```typescript
+import { NavigationButtonModule } from '@seniorsistemas/angular-components/navigation-button';
+
+@NgModule({
+    imports: [NavigationButtonModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-navigation-button
+    [steps]="etapas"
+    (stepChanged)="onEtapaMudou($event)"
+></s-navigation-button>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `steps` | `NavigationButtonItem[]` | — | Sim | Lista de etapas de navegação. |
+| `defaultValue` | `unknown` | `undefined` | Não | Valor padrão a ser selecionado na inicialização. |
+| `tooltip` | `string` | `undefined` | Não | Tooltip global exibido no label central (sobrescrito pelo tooltip individual do item). |
+| `changeOnInit` | `boolean` | `false` | Não | Quando `true`, emite `stepChanged` na inicialização com a etapa inicial. |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `stepChanged` | `EventEmitter<NavigationButtonStepChangedInfo>` | Emitido quando o usuário navega para uma nova etapa, com informações da etapa anterior e atual. |
+
+### Tipos
+
+```typescript
+interface NavigationButtonItem {
+    label: string;      // Texto exibido no botão e no dropdown
+    value: unknown;     // Valor associado à etapa
+    tooltip?: string;   // Tooltip exibido ao passar o mouse no label (sobrescreve o global)
+}
+
+interface NavigationButtonStepChangedInfo {
+    previous: NavigationButtonItem | null;  // Etapa anterior (null na inicialização)
+    current: NavigationButtonItem;          // Etapa atual
+}
+```
+
+## Exemplos
+
+### Navegação entre períodos mensais
+
+```typescript
+etapas: NavigationButtonItem[] = [
+    { label: 'Janeiro', value: 'jan' },
+    { label: 'Fevereiro', value: 'feb' },
+    { label: 'Março', value: 'mar' },
+    { label: 'Abril', value: 'apr' },
+];
+```
+
+```html
+<s-navigation-button
+    [steps]="etapas"
+    (stepChanged)="onPeriodoMudou($event)"
+></s-navigation-button>
+```
+
+### Com tooltip e valor padrão
+
+```html
+<s-navigation-button
+    [steps]="etapas"
+    [defaultValue]="'apr'"
+    tooltip="Clique para selecionar um período"
+    (stepChanged)="onPeriodoMudou($event)"
+></s-navigation-button>
+```
+
+### Com tooltips individuais por etapa
+
+```typescript
+etapasComTooltip: NavigationButtonItem[] = [
+    { label: 'Etapa 1', value: 'step1', tooltip: 'Dados pessoais' },
+    { label: 'Etapa 2', value: 'step2', tooltip: 'Endereço' },
+    { label: 'Etapa 3', value: 'step3', tooltip: 'Contato' },
+    { label: 'Etapa 4', value: 'step4', tooltip: 'Revisão' },
+];
+```
+
+```html
+<s-navigation-button
+    [steps]="etapasComTooltip"
+    (stepChanged)="onEtapaMudou($event)"
+></s-navigation-button>
+```
+
+### Integração com Reactive Forms
+
+```typescript
+form = new FormGroup({
+    periodo: new FormControl('feb'),
+});
+```
+
+```html
+<form [formGroup]="form">
+    <s-navigation-button
+        formControlName="periodo"
+        [steps]="etapas"
+        tooltip="Selecione um período"
+        (stepChanged)="onPeriodoMudou($event)"
+    ></s-navigation-button>
+</form>
+<div>Valor selecionado: {{ form.get('periodo')?.value }}</div>
+```
+
+### Emitindo evento na inicialização
+
+```html
+<s-navigation-button
+    [steps]="etapas"
+    [changeOnInit]="true"
+    (stepChanged)="onEtapaMudou($event)"
+></s-navigation-button>
+```
+
+## Acessibilidade
+
+- O botão ← retrocede para a etapa anterior e é desabilitado automaticamente na primeira etapa
+- O botão → avança para a próxima etapa e é desabilitado automaticamente na última
+- Clicar no label central abre um dropdown (TieredMenu) com todas as etapas para seleção direta
+- Implementa `ControlValueAccessor` — compatível com `formControlName` e `ngModel`
+
+## Componentes relacionados
+
+- [`Stepper`](../stepper/README.md) — indicador de progresso em etapas com clique em cada passo visível
+- [`Steps`](../steps/README.md) — navegação visual entre etapas com todos os passos exibidos
+- [`GridMenu`](../grid-menu/README.md) — seleção de módulo ou contexto em formato de grade

package/numeric/README.md

@@ -0,0 +1,147 @@
+# Numeric
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Pipe e serviço Angular para formatação de valores numéricos de acordo com o locale ativo. O `NumericPipe` retorna um `Observable<string>` e deve ser usado sempre com o pipe `async`. O `NumericService` oferece o método `instant()` para formatação síncrona em TypeScript.
+
+## Quando usar
+
+- Exibir valores numéricos formatados conforme o locale do usuário (separadores de milhar e decimal)
+- Formatar valores monetários, percentuais ou números com precisão configurável em templates ou em código TypeScript
+- Quando a formatação precisa reagir automaticamente a mudanças de locale
+
+## Quando não usar
+
+- Para entrada de dados numéricos pelo usuário — use `sNumericMask` do pacote `numeric-mask`, que cuida de formatação no campo de input
+- Para manipulação aritmética de grandes números — use a biblioteca `BigNumber.js` diretamente
+
+## Instalação
+
+```typescript
+import { NumericModule } from '@seniorsistemas/angular-components/numeric';
+
+@NgModule({
+  imports: [NumericModule, AsyncPipe],
+})
+export class MeuModulo {}
+```
+
+O `NumericModule` requer `LocaleModule.forRoot()` configurado no módulo raiz da aplicação.
+
+## Uso básico
+
+```html
+<!-- Valor inteiro com locale do usuário -->
+{{ 1234567 | numeric | async }}
+
+<!-- Com opções de formatação -->
+{{ 1234567.89 | numeric:{ numberFormatOptions: { minimumFractionDigits: 2 } } | async }}
+
+<!-- Com locale fixo -->
+{{ 1234567.89 | numeric:{ locale: 'en-US', numberFormatOptions: { minimumFractionDigits: 2 } } | async }}
+
+<!-- Moeda -->
+{{ 1234.56 | numeric:{ numberFormatOptions: { style: 'currency', currency: 'BRL' } } | async }}
+```
+
+## API
+
+### NumericPipe
+
+#### Assinatura
+
+```typescript
+transform(
+  value: number | string | BigNumber,
+  options?: {
+    locale?: string;
+    numberFormatOptions?: Intl.NumberFormatOptions;
+  }
+): Observable<string>
+```
+
+| Parâmetro | Tipo | Padrão | Obrigatório | Descrição |
+|-----------|------|--------|:-----------:|-----------|
+| `value` | `number \| string \| BigNumber` | — | Sim | Valor a ser formatado |
+| `options.locale` | `string` | Locale do `LocaleService` | Não | Sobrescreve o locale para formatação |
+| `options.numberFormatOptions` | `Intl.NumberFormatOptions` | `{}` | Não | Opções de formatação da API `Intl.NumberFormat` |
+
+### NumericService
+
+#### Método `instant()`
+
+```typescript
+instant(
+  value: number | string | BigNumber,
+  options?: {
+    locale?: string;
+    numberFormatOptions?: Intl.NumberFormatOptions;
+  }
+): string | null
+```
+
+Retorna o valor formatado de forma síncrona. Deve ser chamado somente após o `LocaleService` ter sido inicializado.
+
+### Tipos
+
+```typescript
+// Aceita qualquer opção da API nativa
+type NumericOptions = {
+  locale?: string;
+  numberFormatOptions?: Intl.NumberFormatOptions;
+};
+
+// Tipos de entrada aceitos
+type NumericValue = number | string | BigNumber;
+```
+
+## Exemplos
+
+### Formatação por locale
+
+```html
+<!-- pt-BR: 1.234.567,89 -->
+{{ 1234567.89 | numeric:{ locale: 'pt-BR', numberFormatOptions: { minimumFractionDigits: 2 } } | async }}
+
+<!-- en-US: 1,234,567.89 -->
+{{ 1234567.89 | numeric:{ locale: 'en-US', numberFormatOptions: { minimumFractionDigits: 2 } } | async }}
+
+<!-- de-DE: 1.234.567,89 -->
+{{ 1234567.89 | numeric:{ locale: 'de-DE', numberFormatOptions: { minimumFractionDigits: 2 } } | async }}
+```
+
+### Formatação de moedas
+
+```html
+<!-- BRL: R$ 1.234,56 -->
+{{ 1234.56 | numeric:{ locale: 'pt-BR', numberFormatOptions: { style: 'currency', currency: 'BRL' } } | async }}
+
+<!-- USD: $1,234.56 -->
+{{ 1234.56 | numeric:{ locale: 'en-US', numberFormatOptions: { style: 'currency', currency: 'USD' } } | async }}
+```
+
+### Uso do NumericService em TypeScript
+
+```typescript
+import { inject } from '@angular/core';
+import { NumericService } from '@seniorsistemas/angular-components/numeric';
+
+const numericService = inject(NumericService);
+
+// Formatação com locale e opções
+const valor = numericService.instant(1234567.89, {
+  locale: 'pt-BR',
+  numberFormatOptions: { minimumFractionDigits: 2, maximumFractionDigits: 2 },
+});
+// Resultado: "1.234.567,89"
+```
+
+## Acessibilidade
+
+- Os valores formatados são texto puro, lidos por leitores de tela conforme o locale configurado
+- Não há componente visual; a acessibilidade depende do elemento host que exibe o valor
+
+## Componentes relacionados
+
+- [`sNumericMask`](../numeric-mask/README.md) — máscara de entrada para campos numéricos
+- [`Locale`](../locale/) — serviço e pipes de localização usados internamente

package/numeric-mask/README.md

@@ -0,0 +1,170 @@
+# NumericMask
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Diretiva Angular para formatação de valores numéricos em campos de input com suporte a internacionalização. Aplica separadores de milhar e decimal conforme o locale configurado, com controle de casas decimais, suporte a valores negativos e notação científica.
+
+## Quando usar
+
+- Campos de entrada de valores numéricos que precisam de formatação automática conforme o locale do usuário
+- Campos monetários, de quantidade ou de medidas que exijam separadores de milhar e decimal corretos
+- Formulários com validação de valor mínimo e máximo em campos numéricos
+
+## Quando não usar
+
+- Para exibição de valores formatados somente leitura — use o `NumericPipe` do pacote `numeric` com `| async`
+- Para inputs do tipo `number` do HTML — a diretiva opera sobre `<input type="text">`
+- Quando a entrada é livre (texto, datas, etc.) — use as diretivas de máscara específicas para cada tipo
+
+## Instalação
+
+```typescript
+import { NumericMaskDirective } from '@seniorsistemas/angular-components/numeric-mask';
+
+@Component({
+  standalone: true,
+  imports: [NumericMaskDirective, FormsModule],
+})
+export class MeuComponent {
+  valor: string | null = null;
+}
+```
+
+## Uso básico
+
+```html
+<input
+  type="text"
+  sNumericMask
+  [locale]="'pt-BR'"
+  [minDecimalPlaces]="2"
+  [maxDecimalPlaces]="2"
+  [(ngModel)]="valor"
+/>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `locale` | `string \| undefined` | Locale do `LocaleService` | Não | Locale para formatação (ex: `'pt-BR'`, `'en-US'`). Se omitido, usa o locale do `LocaleService` |
+| `minDecimalPlaces` | `number` | `0` | Não | Número mínimo de casas decimais a exibir |
+| `maxDecimalPlaces` | `number` | `10` | Não | Número máximo de casas decimais permitidas |
+| `allowNegative` | `boolean` | `false` | Não | Permite valores negativos. Use as teclas `+` ou `-` para alternar o sinal |
+| `allowScientificNotation` | `boolean` | `true` | Não | Habilita suporte a notação científica (ex: `1.5e10`) |
+| `min` | `number \| undefined` | `undefined` | Não | Valor mínimo permitido (validação de formulário) |
+| `max` | `number \| undefined` | `undefined` | Não | Valor máximo permitido (validação de formulário) |
+
+### Tipos
+
+```typescript
+// O valor do modelo (ngModel / FormControl) é sempre string no formato decimal internacional
+// Exemplo: "1234567.89" para o valor 1.234.567,89 em pt-BR
+type NumericMaskModelValue = string | null;
+```
+
+### Erros de validação emitidos
+
+```typescript
+// Valor negativo quando allowNegative = false
+{ negativeNotAllowed: true }
+
+// Valor abaixo do mínimo
+{ min: { min: number; actual: number } }
+
+// Valor acima do máximo
+{ max: { max: number; actual: number } }
+
+// Casas decimais acima do máximo
+{ excessiveDecimalPlaces: { max: number; actual: number } }
+```
+
+## Exemplos
+
+### Campo monetário com 2 casas decimais fixas
+
+```html
+<input
+  type="text"
+  sNumericMask
+  locale="pt-BR"
+  [minDecimalPlaces]="2"
+  [maxDecimalPlaces]="2"
+  placeholder="0,00"
+  [(ngModel)]="valorMonetario"
+/>
+```
+
+### Campo com valores negativos
+
+```html
+<input
+  type="text"
+  sNumericMask
+  locale="pt-BR"
+  [minDecimalPlaces]="2"
+  [maxDecimalPlaces]="2"
+  [allowNegative]="true"
+  placeholder="-0,00"
+  [(ngModel)]="variacao"
+/>
+<!-- Pressione + ou - para alternar entre positivo e negativo -->
+```
+
+### Campo com validação de intervalo (porcentagem)
+
+```html
+<input
+  type="text"
+  sNumericMask
+  locale="pt-BR"
+  [minDecimalPlaces]="2"
+  [maxDecimalPlaces]="2"
+  [min]="0"
+  [max]="100"
+  placeholder="0,00"
+  [(ngModel)]="percentual"
+/>
+```
+
+### Campo com locale en-US
+
+```html
+<input
+  type="text"
+  sNumericMask
+  locale="en-US"
+  [minDecimalPlaces]="2"
+  [maxDecimalPlaces]="2"
+  placeholder="0.00"
+  [(ngModel)]="valor"
+/>
+```
+
+### Campo com casas decimais variáveis
+
+```html
+<input
+  type="text"
+  sNumericMask
+  locale="pt-BR"
+  [minDecimalPlaces]="0"
+  [maxDecimalPlaces]="4"
+  placeholder="0"
+  [(ngModel)]="quantidade"
+/>
+```
+
+## Acessibilidade
+
+- Define automaticamente `inputmode="decimal"` no elemento host para exibir teclado numérico em dispositivos móveis
+- Define `autocomplete="off"` para evitar sugestões incorretas do navegador
+- Suporte a `Backspace`, `Tab`, `Enter`, `Escape`, `ArrowLeft`, `ArrowRight`, `Delete`, `Home` e `End`
+- As teclas `+` e `-` alternam o sinal quando `allowNegative` está ativo
+
+## Componentes relacionados
+
+- [`NumericPipe`](../numeric/README.md) — formatação de valores numéricos para exibição somente leitura
+- [`NumberInput`](../number-input/src/lib/number-input/README.md) — diretiva descontinuada, use `sNumericMask` em seu lugar