@seniorsistemas/angular-components 19.5.5 → 19.6.0-fix-sds-552-80a83369

package/accordion/README.md

@@ -23,7 +23,7 @@ Componente de acordeão para organizar conteúdo em painéis expansíveis e cola
 import { AccordionModule } from '@seniorsistemas/angular-components/accordion';
 
 @NgModule({
-  imports: [AccordionModule],
+    imports: [AccordionModule],
 })
 export class MeuModule {}
 ```
@@ -32,8 +32,8 @@ export class MeuModule {}
 
 ```html
 <s-accordion>
-  <s-accordion-panel header="Seção 1">Conteúdo 1</s-accordion-panel>
-  <s-accordion-panel header="Seção 2">Conteúdo 2</s-accordion-panel>
+    <s-accordion-panel header="Seção 1">Conteúdo 1</s-accordion-panel>
+    <s-accordion-panel header="Seção 2">Conteúdo 2</s-accordion-panel>
 </s-accordion>
 ```
 
@@ -41,40 +41,43 @@ export class MeuModule {}
 
 ### s-accordion — Inputs
 
-| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
-|-------------|------|--------|:-----------:|-----------|
-| `multiple` | `boolean` | `false` | não | Permite múltiplos painéis abertos ao mesmo tempo |
-| `activeIndex` | `number \| number[]` | `undefined` | não | Índice(s) do(s) painel(is) que devem iniciar abertos |
+| Propriedade   | Tipo                 | Padrão      | Obrigatório | Descrição                                            |
+| ------------- | -------------------- | ----------- | :---------: | ---------------------------------------------------- |
+| `multiple`    | `boolean`            | `false`     |     não     | Permite múltiplos painéis abertos ao mesmo tempo     |
+| `activeIndex` | `number \| number[]` | `undefined` |     não     | Índice(s) do(s) painel(is) que devem iniciar abertos |
 
 ### s-accordion-panel — Inputs
 
-| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
-|-------------|------|--------|:-----------:|-----------|
-| `header` | `string` | — | **sim** | Título exibido no cabeçalho do painel |
-| `disabled` | `boolean` | `false` | não | Impede abertura e fechamento do painel |
-| `buttons` | `AccordionButtonSettings[]` | `undefined` | não | Botões de ação exibidos no cabeçalho |
-| `switchControl` | `UntypedFormControl` | `undefined` | não | FormControl vinculado a um switch no cabeçalho |
-| `validationMessage` | `string` | `undefined` | não | Mensagem de validação exibida abaixo do cabeçalho |
-| `validationMessageIcon` | `string` | `'fas fa-exclamation-circle'` | não | Classe do ícone da mensagem de validação |
-| `validationMessageIconColor` | `ValidationMessageIconColor` | `'Red'` | não | Cor do ícone da mensagem de validação |
-| `cache` | `boolean` | `false` | não | Mantém o conteúdo no DOM quando o painel é fechado |
+| Propriedade                  | Tipo                                   | Padrão                        | Obrigatório | Descrição                                          |
+| ---------------------------- | -------------------------------------- | ----------------------------- | :---------: | -------------------------------------------------- |
+| `header`                     | `string`                               | —                             |   **sim**   | Título exibido no cabeçalho do painel              |
+| `badgeConfig`                | `{ text: string; color: BadgeColors }` | `undefined`                   |     não     | Badge exibido no cabeçalho, à direita do título    |
+| `disabled`                   | `boolean`                              | `false`                       |     não     | Impede abertura e fechamento do painel             |
+| `buttons`                    | `AccordionButtonSettings[]`            | `undefined`                   |     não     | Botões de ação exibidos no cabeçalho               |
+| `switchControl`              | `UntypedFormControl`                   | `undefined`                   |     não     | FormControl vinculado a um switch no cabeçalho     |
+| `validationMessage`          | `string`                               | `undefined`                   |     não     | Mensagem de validação exibida abaixo do cabeçalho  |
+| `validationMessageIcon`      | `string`                               | `'fas fa-exclamation-circle'` |     não     | Classe do ícone da mensagem de validação           |
+| `validationMessageIconColor` | `ValidationMessageIconColor`           | `'Red'`                       |     não     | Cor do ícone da mensagem de validação              |
+| `cache`                      | `boolean`                              | `false`                       |     não     | Mantém o conteúdo no DOM quando o painel é fechado |
 
 ### s-accordion-panel — Outputs
 
-| Evento | Tipo | Descrição |
-|--------|------|-----------|
-| `panelOpened` | `EventEmitter<void>` | Emitido quando o painel é aberto |
+| Evento        | Tipo                 | Descrição                         |
+| ------------- | -------------------- | --------------------------------- |
+| `panelOpened` | `EventEmitter<void>` | Emitido quando o painel é aberto  |
 | `panelClosed` | `EventEmitter<void>` | Emitido quando o painel é fechado |
 
 ### Tipos
 
 ```typescript
 interface AccordionButtonSettings {
-  icon: string;
-  onClick: VoidFunction;
+    icon: string;
+    onClick: VoidFunction;
 }
 
 type ValidationMessageIconColor = 'Red' | 'Orange' | 'Yellow' | 'Green' | 'Blue';
+
+type BadgeColors = 'red' | 'orange' | 'yellow' | 'blue' | 'green' | 'gray';
 ```
 
 ## Exemplos
@@ -82,30 +85,57 @@ type ValidationMessageIconColor = 'Red' | 'Orange' | 'Yellow' | 'Green' | 'Blue'
 ### Modo padrão (painel único)
 
 ```html
-<s-accordion [multiple]="false" [activeIndex]="0">
-  <s-accordion-panel header="Informações Pessoais">
-    <div class="p-4">
-      <p>Nome completo, data de nascimento, CPF e outros dados pessoais.</p>
-    </div>
-  </s-accordion-panel>
-  <s-accordion-panel header="Endereço">
-    <div class="p-4">
-      <p>Rua, número, complemento, cidade, estado e CEP.</p>
-    </div>
-  </s-accordion-panel>
+<s-accordion
+    [multiple]="false"
+    [activeIndex]="0"
+>
+    <s-accordion-panel header="Informações Pessoais">
+        <div class="p-4">
+            <p>Nome completo, data de nascimento, CPF e outros dados pessoais.</p>
+        </div>
+    </s-accordion-panel>
+    <s-accordion-panel header="Endereço">
+        <div class="p-4">
+            <p>Rua, número, complemento, cidade, estado e CEP.</p>
+        </div>
+    </s-accordion-panel>
 </s-accordion>
 ```
 
 ### Modo múltiplo
 
 ```html
-<s-accordion [multiple]="true" [activeIndex]="[0, 1]">
-  <s-accordion-panel header="Configurações Gerais">
-    <div class="p-4">Idioma, tema e notificações.</div>
-  </s-accordion-panel>
-  <s-accordion-panel header="Configurações de Privacidade">
-    <div class="p-4">Visibilidade do perfil e compartilhamento.</div>
-  </s-accordion-panel>
+<s-accordion
+    [multiple]="true"
+    [activeIndex]="[0, 1]"
+>
+    <s-accordion-panel header="Configurações Gerais">
+        <div class="p-4">Idioma, tema e notificações.</div>
+    </s-accordion-panel>
+    <s-accordion-panel header="Configurações de Privacidade">
+        <div class="p-4">Visibilidade do perfil e compartilhamento.</div>
+    </s-accordion-panel>
+</s-accordion>
+```
+
+### Com badge no cabeçalho
+
+O `badgeConfig` exibe um `BadgeComponent` à direita do título, útil para indicar contagens, status ou alertas por seção.
+
+```html
+<s-accordion>
+    <s-accordion-panel
+        header="Notificações"
+        [badgeConfig]="{ text: '3', color: 'red' }"
+    >
+        <div class="p-4">Você tem 3 notificações não lidas.</div>
+    </s-accordion-panel>
+    <s-accordion-panel
+        header="Tarefas Atribuídas"
+        [badgeConfig]="{ text: 'Novo', color: 'blue' }"
+    >
+        <div class="p-4">Novas tarefas atribuídas a você.</div>
+    </s-accordion-panel>
 </s-accordion>
 ```
 
@@ -113,16 +143,19 @@ type ValidationMessageIconColor = 'Red' | 'Orange' | 'Yellow' | 'Green' | 'Blue'
 
 ```html
 <s-accordion>
-  <s-accordion-panel header="Projeto Alpha" [buttons]="buttons">
-    <div class="p-4">Descrição e detalhes do Projeto Alpha.</div>
-  </s-accordion-panel>
+    <s-accordion-panel
+        header="Projeto Alpha"
+        [buttons]="buttons"
+    >
+        <div class="p-4">Descrição e detalhes do Projeto Alpha.</div>
+    </s-accordion-panel>
 </s-accordion>
 ```
 
 ```typescript
 buttons = [
-  { icon: 'fas fa-edit', onClick: () => this.editar() },
-  { icon: 'fas fa-trash', onClick: () => this.excluir() },
+    { icon: 'fas fa-edit', onClick: () => this.editar() },
+    { icon: 'fas fa-trash', onClick: () => this.excluir() },
 ];
 ```
 
@@ -130,14 +163,15 @@ buttons = [
 
 ```html
 <s-accordion>
-  <s-accordion-panel
-    header="Notificações por E-mail"
-    [switchControl]="switchControl"
-    validationMessage="Preencha todos os campos obrigatórios"
-    validationMessageIcon="fas fa-exclamation-circle"
-    validationMessageIconColor="Red">
-    <div class="p-4">Receba atualizações por e-mail.</div>
-  </s-accordion-panel>
+    <s-accordion-panel
+        header="Notificações por E-mail"
+        [switchControl]="switchControl"
+        validationMessage="Preencha todos os campos obrigatórios"
+        validationMessageIcon="fas fa-exclamation-circle"
+        validationMessageIconColor="Red"
+    >
+        <div class="p-4">Receba atualizações por e-mail.</div>
+    </s-accordion-panel>
 </s-accordion>
 ```
 
@@ -145,12 +179,13 @@ buttons = [
 
 ```html
 <s-accordion>
-  <s-accordion-panel header="Etapa 1 - Concluída">
-    Conteúdo disponível.
-  </s-accordion-panel>
-  <s-accordion-panel header="Etapa 2 - Bloqueada" [disabled]="true">
-    Disponível após concluir a etapa 1.
-  </s-accordion-panel>
+    <s-accordion-panel header="Etapa 1 - Concluída"> Conteúdo disponível. </s-accordion-panel>
+    <s-accordion-panel
+        header="Etapa 2 - Bloqueada"
+        [disabled]="true"
+    >
+        Disponível após concluir a etapa 1.
+    </s-accordion-panel>
 </s-accordion>
 ```
 
@@ -164,3 +199,4 @@ buttons = [
 ## Componentes relacionados
 
 - [`CollapseLink`](../collapse-link/README.md) — quando há apenas uma seção expansível simples, sem cabeçalho estruturado
+

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

@@ -2,6 +2,10 @@ import { AfterViewChecked, OnDestroy, OnInit, Renderer2 } from '@angular/core';
 import { Calendar } from 'primeng/calendar';
 import * as i0 from "@angular/core";
 /**
+ * @deprecated
+ * @since 19.6.0
+ * Favor utilizar o componente: s-datepicker, que é o calendário oficial do Design System da Senior.
+ *
  * @description Diretiva que aplica máscara de entrada a um componente `p-calendar` do PrimeNG,
  * formatando automaticamente a data conforme o formato configurado no calendário.
  * Intercepta os eventos de teclado e input do campo interno do calendar para garantir

package/datepicker/README.md

@@ -0,0 +1,175 @@
+# Datepicker
+
+![Status](https://img.shields.io/badge/status-beta-yellow)
+
+Componente completo de seleção de datas com campo de input e painel flutuante. Substituto direto do `p-datepicker` do PrimeNG, com API moderna baseada em Angular Signals e posicionamento nativo via CDK Overlay.
+
+## Quando usar
+
+- Formulários que exigem seleção de data, hora ou intervalo de datas
+- Filtros de período com seleção de data de início e fim (`mode="range"`)
+- Campos de hora isolados sem calendário (`mode="time"`)
+- Seleção de competência (mês/ano) sem necessidade de escolher o dia (`mode="month"`)
+
+## Quando não usar
+
+- Para exibir datas sem interação — use `DatePipe` do Angular diretamente
+- Para seleção de múltiplas datas avulsas — este componente não suporta `selectionMode="multiple"`
+- Quando o campo está dentro de um modal e o painel precisa escapar do `overflow: hidden` — o CDK Overlay já trata isso nativamente; não é necessário configuração extra
+
+## Instalação
+
+```typescript
+import { DatepickerComponent } from '@seniorsistemas/angular-components/datepicker';
+
+@Component({
+  standalone: true,
+  imports: [DatepickerComponent],
+})
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<s-datepicker [formControl]="dataCtrl" mode="date" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|:-----------:|---|
+| `inputId` | `string` | auto-gerado | Não | HTML `id` aplicado ao elemento `<input>`. |
+| `name` | `string` | `undefined` | Não | Atributo `name` do `<input>` nativo. |
+| `placeholder` | `string` | `undefined` | Não | Texto exibido quando nenhum valor está selecionado. |
+| `mode` | `DatePickerMode` | `'date'` | Não | Modo de seleção do componente. Ver tabela de modos abaixo. |
+| `showIcon` | `boolean` | `true` | Não | Exibe o botão de ícone ao lado do campo. |
+| `icon` | `string` | `'fas fa-calendar'` | Não | Classe CSS do ícone. No modo `time`, usa `'fas fa-clock'` automaticamente. |
+| `showOnFocus` | `boolean` | `false` | Não | Abre o painel ao focar o campo. |
+| `min` | `Date \| null` | `null` | Não | Data mínima selecionável. Dias anteriores ficam desabilitados. |
+| `max` | `Date \| null` | `null` | Não | Data máxima selecionável. Dias posteriores ficam desabilitados. |
+| `defaultDate` | `Date \| null` | `null` | Não | Data exibida ao abrir o painel quando nenhuma data está selecionada. |
+| `dateFormat` | `string` | `'dd/MM/yyyy'` | Não | Formato de exibição da data no campo. |
+| `hourFormat` | `'12' \| '24'` | `'24'` | Não | Formato de exibição das horas. |
+| `minuteStep` | `number` | `5` | Não | Incremento em minutos ao usar as setas do time picker. |
+| `showSeconds` | `boolean` | `false` | Não | Exibe o campo de segundos no time picker. |
+| `rangeSeparator` | `string` | `' — '` | Não | Separador exibido entre as datas no modo `range`. |
+| `disabled` | `boolean` | `false` | Não | Desabilita o componente (model two-way). |
+
+### Outputs
+
+| Evento | Tipo emitido | Descrição |
+|---|---|---|
+| `blur` | `Event` | Emitido quando o campo perde o foco. |
+| `focus` | `Event` | Emitido quando o campo recebe o foco. |
+| `select` | `Date \| DateRange \| null` | Emitido ao selecionar uma data, mês, horário ou intervalo. |
+| `close` | `void` | Emitido quando o painel do calendário fecha. |
+| `todayClick` | `Date` | Emitido ao clicar no botão "Hoje". |
+| `clearClick` | `void` | Emitido ao clicar no botão "Limpar". |
+| `monthChange` | `{ month: number; year: number }` | Emitido quando o mês visualizado muda. |
+| `yearChange` | `{ month: number; year: number }` | Emitido quando o ano visualizado muda. |
+
+### Tipos
+
+```typescript
+type DatePickerMode = 'date' | 'month' | 'datetime' | 'time' | 'range';
+
+interface DateRange {
+  start: Date | null;
+  end: Date | null;
+}
+```
+
+### Modos (`DatePickerMode`)
+
+| Modo | Valor emitido | Descrição |
+|---|---|---|
+| `date` | `Date` | Calendário com seleção de dia (padrão). |
+| `month` | `Date` | Seleção de mês e ano — o `Date` emitido aponta para o primeiro dia do mês. |
+| `datetime` | `Date` | Calendário + time picker. O painel só fecha ao clicar em "Confirmar". |
+| `time` | `Date` | Apenas seletor de hora, sem calendário. |
+| `range` | `DateRange` | Seleção de intervalo com data de início e fim. |
+
+## Exemplos
+
+### Com `formControl`
+
+```html
+<s-datepicker [formControl]="dataCtrl" mode="date" />
+```
+
+```typescript
+dataCtrl = new FormControl<Date | null>(null, Validators.required);
+```
+
+### Com `ngModel`
+
+```html
+<s-datepicker [(ngModel)]="dataSelecionada" mode="datetime" />
+```
+
+### Data e hora
+
+```html
+<s-datepicker [formControl]="ctrl" mode="datetime" [minuteStep]="15" [showSeconds]="true" />
+```
+
+### Intervalo de datas
+
+```html
+<s-datepicker [formControl]="periodoCtrl" mode="range" rangeSeparator=" até " />
+```
+
+```typescript
+periodoCtrl = new FormControl<DateRange | null>(null);
+```
+
+### Com limites de data
+
+```html
+<s-datepicker [formControl]="ctrl" mode="date" [min]="dataMinima" [max]="dataMaxima" />
+```
+
+### Seleção de mês
+
+```html
+<s-datepicker [formControl]="competenciaCtrl" mode="month" placeholder="Selecione a competência" />
+```
+
+### Apenas hora
+
+```html
+<s-datepicker [formControl]="horaCtrl" mode="time" [minuteStep]="1" [showSeconds]="true" />
+```
+
+### Com Dynamic Form
+
+```typescript
+const config: CalendarFieldConfig = {
+  type: 'date',
+  name: 'dataNascimento',
+  label: 'Data de nascimento',
+};
+```
+
+```html
+<s-dynamic-form [config]="config" />
+```
+
+## Acessibilidade
+
+- O trigger usa `role="combobox"` com `aria-haspopup="grid"`, `aria-expanded` e `aria-controls` apontando para o painel
+- O painel usa `role="dialog"` com `aria-label` traduzido e `cdkTrapFocus` para prender o foco dentro do popup
+- Ao abrir o painel, o foco é movido automaticamente para o primeiro botão do calendário ou para o botão de incremento de horas no modo `time`
+- Ao fechar o painel, o foco retorna ao botão de ícone do input trigger
+- Tecla `Escape` fecha o painel e devolve o foco ao trigger
+- Dias do calendário usam `role="gridcell"` com `aria-label` contendo a data por extenso, `aria-selected` e `aria-disabled`
+- Cabeçalhos dos dias da semana usam `role="columnheader"` com `aria-label`
+- Setas do time picker têm `aria-label` descritivos; as horas/minutos têm `aria-live="polite"`
+- Todos os ícones decorativos têm `aria-hidden="true"`
+
+## Componentes relacionados
+
+- [`DynamicFormComponent`](../../src/lib/dynamic-form/README.md) — usa `s-datepicker` internamente para campos do tipo `date`, `time`, `dateTime` e `localDateTime`

package/datepicker/index.d.ts

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

package/datepicker/lib/datepicker/date.utils.d.ts

@@ -0,0 +1,21 @@
+import type { DateRange } from './models';
+export type { DateRange };
+export declare function formatNativeDate(date: Date): string;
+/**
+ * Formata uma data segundo um padrão simples contendo os tokens `dd`, `MM` e `yyyy`.
+ * Usado apenas para exibição em campos `type="text"` (modo `range`), onde o browser
+ * não controla o formato. Para `type="date"` nativo o formato é definido pelo browser.
+ */
+export declare function formatWithPattern(date: Date, pattern: string): string;
+export declare function formatTime(h: number, m: number, s?: number): string;
+/** Parses yyyy-MM-dd. Returns null when invalid. */
+export declare function parseDate(raw: string): Date | null;
+export declare function isSameDay(a: Date, b: Date): boolean;
+export declare function stripTime(date: Date): number;
+export declare function parseRangeInput(raw: string, separator?: string): DateRange | null;
+export declare function parseTimeInput(raw: string, base: Date | null, maxHours: number, maxMinutes: number): Date | null;
+export declare function parseYearInput(raw: string): Date | null;
+export declare function parseMonthInput(raw: string): Date | null;
+export declare function parseDateTimeInput(raw: string): Date | null;
+export declare function parseInput(mode: string, raw: string, base: Date | null, maxHours: number, maxMinutes: number, rangeSeparator?: string): Date | DateRange | null;
+export declare function formatValueForInput(mode: string, value: Date | DateRange | Date[] | null, rangeSeparator?: string, dateFormat?: string, multipleSeparator?: string): string;