@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/breadcrumb/README.md

@@ -0,0 +1,144 @@
+# Breadcrumb
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de trilha de navegação que constrói automaticamente o caminho hierárquico de páginas a partir das rotas do Angular Router. Exibe o título da rota atual e os itens de navegação como links clicáveis.
+
+## Quando usar
+
+- Indicar ao usuário a posição atual dentro de uma hierarquia de navegação
+- Permitir que o usuário navegue rapidamente para níveis anteriores da hierarquia
+- Em aplicações com rotas aninhadas de 2 ou mais níveis
+
+## Quando não usar
+
+- Em páginas de primeiro nível sem hierarquia — o breadcrumb teria apenas o item home, sem valor de navegação
+- Quando a navegação é linear (wizard/steps) — use um componente de passos em vez de breadcrumb
+
+## Instalação
+
+```typescript
+import { BreadcrumbModule } from '@seniorsistemas/angular-components/breadcrumb';
+
+@NgModule({
+  imports: [BreadcrumbModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-breadcrumb></s-breadcrumb>
+```
+
+## Configuração de rotas
+
+O breadcrumb lê automaticamente o campo `data.routeTitle` de cada rota. Toda rota com `path` e `component` **deve** ter `routeTitle` definido, caso contrário um erro é lançado.
+
+```typescript
+const routes: Routes = [
+  {
+    path: 'dashboard',
+    component: DashboardComponent,
+    data: { routeTitle: 'Dashboard' },
+    children: [
+      {
+        path: 'relatorios',
+        component: RelatoriosComponent,
+        data: { routeTitle: 'Relatórios' },
+        children: [
+          {
+            path: 'vendas',
+            component: VendasComponent,
+            data: { routeTitle: 'Vendas' },
+          },
+        ],
+      },
+    ],
+  },
+];
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `homeUrl` | `string` | `undefined` | não | URL externa para o ícone home (quando definida, usa `<a>` externo em vez do router) |
+| `targetHomeUrl` | `'_self' \| '_blank' \| '_parent' \| '_top'` | `'_self'` | não | Atributo `target` do link home quando `homeUrl` está definido |
+
+### Tipos
+
+```typescript
+type BreadcrumbItem = {
+  routerLink?: string | string[];
+  active?: boolean;
+  disabled?: boolean;
+  disabledIcon?: boolean;
+  hideLabel?: boolean;
+  queryParams?: Params;
+  url?: string;
+  icon?: string;
+  target?: string;
+  label?: string;
+};
+```
+
+## Exemplos
+
+### Dois níveis (home + página atual)
+
+```html
+<!-- Configuração de rota -->
+<!-- { path: 'dashboard', component: DashboardComponent, data: { routeTitle: 'Dashboard' } } -->
+
+<s-breadcrumb></s-breadcrumb>
+```
+
+### Com URL de home externa (portal)
+
+```html
+<s-breadcrumb homeUrl="https://portal.empresa.com" targetHomeUrl="_blank"></s-breadcrumb>
+```
+
+### Quatro níveis de navegação
+
+```typescript
+// Configuração das rotas
+const routes: Routes = [
+  {
+    path: 'modulo',
+    data: { routeTitle: 'Módulo' },
+    children: [
+      {
+        path: 'secao',
+        data: { routeTitle: 'Seção' },
+        children: [
+          {
+            path: 'pagina',
+            component: PaginaComponent,
+            data: { routeTitle: 'Página' },
+          },
+        ],
+      },
+    ],
+  },
+];
+```
+
+```html
+<s-breadcrumb></s-breadcrumb>
+<!-- Resultado: Home > Módulo > Seção > Página (atual, não clicável) -->
+```
+
+## Acessibilidade
+
+- O breadcrumb é renderizado como `<nav>` com `aria-label` adequado
+- O item da rota atual é exibido como desabilitado (não clicável), refletindo a posição atual
+- O ícone home é acessível via teclado
+
+## Componentes relacionados
+
+- [`Topbar`](../topbar/README.md) — barra superior de navegação onde o breadcrumb costuma ser posicionado

package/button/README.md

@@ -0,0 +1,159 @@
+# Button
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de botão versátil para ações do usuário, com suporte a ícones, tooltip, menu dropdown (tiered menu), badge, animações e diferentes prioridades visuais.
+
+## Quando usar
+
+- Acionar ações do usuário: salvar, cancelar, excluir, navegar
+- Agrupar múltiplas ações relacionadas em um menu dropdown
+- Botões de refresh com animação de rotação no ícone
+- Toolbars com botões de ícone e tooltip
+
+## Quando não usar
+
+- Para navegação entre páginas — use `routerLink` em um elemento `<a>` para preservar semântica HTML
+- Para formulários com múltiplos campos de ação — avalie se um `<button type="submit">` nativo não atende melhor
+- Para exibir ícones puramente decorativos — use a tag de ícone diretamente
+
+## Instalação
+
+```typescript
+import { ButtonComponent } from '@seniorsistemas/angular-components/button';
+
+@Component({ standalone: true, imports: [ButtonComponent] })
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<s-button label="Salvar" priority="primary" (clicked)="salvar()" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `label` | `string` | `undefined` | não | Texto exibido dentro do botão |
+| `priority` | `ButtonPriority` | `'primary'` | não | Prioridade visual: `'primary'`, `'secondary'`, `'danger'`, `'default'`, `'link'` |
+| `iconClass` | `string` | `undefined` | não | Classe do ícone à esquerda do label (ex.: `'fa fa-save'`) |
+| `rightIconClass` | `string` | `undefined` | não | Classe do ícone à direita do label |
+| `disabled` | `boolean` | `false` | não | Desabilita o botão |
+| `size` | `'default' \| 'small'` | `'default'` | não | Tamanho do botão |
+| `tooltip` | `string` | `undefined` | não | Texto do tooltip ao passar o mouse |
+| `tooltipPosition` | `TooltipPositions` | `'top'` | não | Posição do tooltip |
+| `menuOptions` | `TieredMenuItemData[]` | `[]` | não | Itens do menu dropdown |
+| `caret` | `boolean` | `true` | não | Exibe seta quando há menu dropdown |
+| `animation` | `ButtonAnimations` | `undefined` | não | Animação no ícone (`'rotate'`) |
+| `slide` | `boolean` | `false` | não | Expande o label ao passar o mouse (requer `priority: 'default'` ou `'link'`) |
+| `auxiliary` | `boolean` | `false` | não | Bordas completamente arredondadas (estilo pill) |
+| `badge` | `ButtonBadgeConfig` | `undefined` | não | Badge de notificação exibido sobre o botão |
+| `iconColor` | `string` | `undefined` | não | Cor personalizada para o ícone |
+| `styleClass` | `string` | `''` | não | Classes CSS adicionais |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | não | Tipo do elemento `<button>` HTML |
+| `id` | `string` | `s-button-{hash}` | não | ID do elemento no DOM |
+| `baseZIndex` | `number` | `0` | não | Z-index base do menu dropdown |
+| `menuAriaLabel` | `string` | `undefined` | não | Rótulo ARIA do menu associado |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `clicked` | `EventEmitter<any>` | Emitido ao clicar no botão (quando não desabilitado) |
+
+### Tipos
+
+```typescript
+type ButtonPriority = 'default' | 'primary' | 'secondary' | 'link' | 'danger';
+
+type ButtonAnimations = 'rotate';
+
+interface ButtonBadgeConfig {
+  text?: string;
+  iconClass?: string;
+  color: BadgeColors; // 'red' | 'orange' | 'yellow' | 'blue' | 'green' | 'gray'
+}
+```
+
+## Exemplos
+
+### Prioridades disponíveis
+
+```html
+<s-button label="Primário" priority="primary"></s-button>
+<s-button label="Secundário" priority="secondary"></s-button>
+<s-button label="Padrão" priority="default"></s-button>
+<s-button label="Perigo" priority="danger" iconClass="fa fa-trash"></s-button>
+<s-button label="Link" priority="link"></s-button>
+```
+
+### Com ícone e tooltip
+
+```html
+<!-- Botão apenas com ícone — use sempre tooltip para acessibilidade -->
+<s-button iconClass="fa fa-trash" priority="secondary" tooltip="Excluir item"></s-button>
+
+<!-- Botão com ícone à esquerda -->
+<s-button label="Salvar" iconClass="fa fa-save" priority="primary"></s-button>
+
+<!-- Botão com ícone à direita -->
+<s-button label="Avançar" rightIconClass="fa fa-arrow-right" priority="primary"></s-button>
+```
+
+### Com menu dropdown
+
+```html
+<s-button
+  label="Ações"
+  iconClass="fa fa-ellipsis-v"
+  priority="secondary"
+  [menuOptions]="opcoes">
+</s-button>
+```
+
+```typescript
+opcoes = [
+  { label: 'Editar', iconClass: 'fa fa-edit', command: () => this.editar() },
+  { label: 'Excluir', iconClass: 'fa fa-trash', command: () => this.excluir() },
+  { divider: true },
+  { label: 'Configurações', iconClass: 'fa fa-cog', command: () => this.configurar() },
+];
+```
+
+### Com badge de notificação
+
+```html
+<s-button
+  label="Notificações"
+  iconClass="fa fa-bell"
+  priority="secondary"
+  [badge]="{ text: '5', color: 'red' }">
+</s-button>
+```
+
+### Com animação de rotação (refresh)
+
+```html
+<s-button
+  label="Recarregar"
+  iconClass="fa fa-sync"
+  animation="rotate"
+  priority="primary"
+  (clicked)="recarregar()">
+</s-button>
+```
+
+## Acessibilidade
+
+- O componente renderiza um elemento `<button>` nativo, totalmente acessível via teclado
+- Use **Tab** para focar e **Enter** ou **Space** para acionar
+- Botões com apenas ícone devem sempre ter `tooltip` definido para comunicar a ação a leitores de tela
+- O `menuAriaLabel` descreve o menu associado para tecnologias assistivas
+
+## Componentes relacionados
+
+- [`Badge`](../badge/README.md) — rótulos visuais; usado internamente pelo badge do botão

package/calendar-mask/README.md

@@ -0,0 +1,89 @@
+# CalendarMask
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Diretiva que aplica máscara de entrada ao componente `p-calendar` do PrimeNG, formatando automaticamente a data conforme o `dateFormat` configurado no calendário.
+
+> **Nota:** Esta diretiva foi desenvolvida originalmente para PrimeNG v9. Em versões mais recentes (v18+), podem ocorrer incompatibilidades no ambiente Storybook, porém o uso em aplicações Angular reais continua funcionando normalmente.
+
+## Quando usar
+
+- Campos de data onde o usuário precisa digitar a data manualmente (em vez de selecionar no calendário)
+- Formulários com `p-calendar` que exigem entrada por teclado formatada
+- Quando é necessário suporte a máscaras em intervalos de datas (`selectionMode="range"`)
+
+## Quando não usar
+
+- Quando o usuário sempre selecionará a data pelo calendário gráfico — a máscara não é necessária
+- Em novos campos de data com formatos muito diferentes de `dd/mm/yy` — teste a compatibilidade antes
+- Com `p-calendar` em modo `inline` — a máscara destina-se ao input de texto
+
+## Instalação
+
+```typescript
+import { CalendarMaskModule } from '@seniorsistemas/angular-components/calendar-mask';
+
+@NgModule({
+  imports: [CalendarMaskModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+Adicione o atributo `sCalendarMask` diretamente ao `p-calendar`:
+
+```html
+<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `slotChar` | `string` | `'_'` | não | Caractere placeholder para posições não preenchidas na máscara |
+| `autoClear` | `boolean` | `false` | não | Limpa o campo ao perder o foco se o valor for inválido |
+
+## Exemplos
+
+### Data simples
+
+```html
+<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" />
+```
+
+### Data e hora
+
+```html
+<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" [showTime]="true" />
+```
+
+### Data, hora e segundos
+
+```html
+<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" [showTime]="true" [showSeconds]="true" />
+```
+
+### Intervalo de datas
+
+```html
+<p-calendar sCalendarMask [(ngModel)]="data" dateFormat="dd/mm/yy" selectionMode="range" />
+```
+
+### Com limpeza automática de valor inválido
+
+```html
+<p-calendar sCalendarMask [autoClear]="true" [(ngModel)]="data" dateFormat="dd/mm/yy" />
+```
+
+## Acessibilidade
+
+- A diretiva altera o `type` do input interno para `tel`, exibindo teclado numérico em dispositivos móveis
+- A navegação por Tab é tratada pela diretiva para garantir o foco correto entre o input e o botão do calendário
+- Use `aria-label` ou `<label for="...">` no `p-calendar` para associar corretamente o rótulo ao campo
+
+## Componentes relacionados
+
+- [`MaskFormatter`](../mask-formatter/README.md) — pipe de formatação de strings com máscara para exibição

package/card/README.md

@@ -0,0 +1,133 @@
+# Card
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente container para agrupar conteúdo relacionado de forma visual e organizada. Suporta imagem de banner, templates personalizados para header, body e footer, ou uso simplificado com atributos.
+
+## Quando usar
+
+- Agrupar informações relacionadas em dashboards
+- Exibir itens de lista com mais estrutura visual (portfólio, catálogo, galeria)
+- Encapsular formulários ou seções de conteúdo com header e footer de ações
+- Mostrar dados com imagem contextual no topo
+
+## Quando não usar
+
+- Para agrupamento simples de campos em formulários — use `Fieldset` em vez disso
+- Quando o conteúdo precisa expandir/colapsar — use `Panel` (expansível) ou `Accordion`
+- Para exibição de texto corrido sem necessidade de separação visual — use `<section>` nativo
+
+## Instalação
+
+```typescript
+import { CardModule } from '@seniorsistemas/angular-components/card';
+import { TemplateModule } from '@seniorsistemas/angular-components/template';
+
+@NgModule({
+  imports: [CardModule, TemplateModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-card title="Título" subtitle="Subtítulo" icon="fas fa-rocket">
+  <p>Conteúdo via ng-content.</p>
+</s-card>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `title` | `string` | `''` | não | Título exibido no cabeçalho |
+| `subtitle` | `string` | `''` | não | Subtítulo exibido abaixo do título |
+| `icon` | `string` | `''` | não | Classe do ícone no cabeçalho (ex.: `'fas fa-rocket'`) |
+| `bannerImage` | `string` | `undefined` | não | URL da imagem de banner exibida no topo do card |
+| `fullWidth` | `boolean` | `false` | não | Faz o card ocupar 100% da largura disponível |
+
+### Tipos de template (via `sTemplate`)
+
+```typescript
+type CardTemplateTypes = 'header' | 'body' | 'footer';
+```
+
+## Exemplos
+
+### Card simples com ng-content
+
+```html
+<s-card>
+  <p>Conteúdo simples sem header configurado.</p>
+</s-card>
+```
+
+### Com header via inputs
+
+```html
+<s-card title="Informações do Usuário" subtitle="Dados cadastrais" icon="fas fa-user">
+  <p>Nome, e-mail e telefone.</p>
+</s-card>
+```
+
+### Com imagem de banner
+
+```html
+<s-card
+  bannerImage="https://exemplo.com/imagem.jpg"
+  title="Card com Banner"
+  subtitle="Exemplo de card com imagem">
+  <p>Conteúdo abaixo da imagem.</p>
+</s-card>
+```
+
+### Com template de footer (ações)
+
+```html
+<s-card title="Confirme a Ação" icon="fas fa-exclamation-triangle">
+  <p>Você tem certeza que deseja continuar?</p>
+
+  <ng-template sTemplate="footer">
+    <div style="display: flex; justify-content: flex-end; gap: 8px;">
+      <s-button label="Cancelar" priority="secondary"></s-button>
+      <s-button label="Confirmar" priority="danger"></s-button>
+    </div>
+  </ng-template>
+</s-card>
+```
+
+### Com templates completos (header, body e footer)
+
+```html
+<s-card [fullWidth]="true">
+  <ng-template sTemplate="header">
+    <div style="display: flex; justify-content: space-between; align-items: center;">
+      <strong>Header Customizado</strong>
+      <s-button label="Ação" priority="secondary" size="small"></s-button>
+    </div>
+  </ng-template>
+
+  <ng-template sTemplate="body">
+    <p>Corpo totalmente customizado.</p>
+  </ng-template>
+
+  <ng-template sTemplate="footer">
+    <div style="display: flex; justify-content: flex-end;">
+      <s-button label="Salvar" priority="primary"></s-button>
+    </div>
+  </ng-template>
+</s-card>
+```
+
+## Acessibilidade
+
+- Use `title` e `subtitle` com textos descritivos para que leitores de tela entendam o contexto do card
+- Quando o banner é apenas decorativo, ele não precisa de texto alternativo (é exibido como `background-image`)
+- Botões no footer devem ter `label` ou `tooltip` claros
+
+## Componentes relacionados
+
+- [`Accordion`](../accordion/README.md) — quando o conteúdo do card precisa ser expansível/colapsável

package/chat/README.md

@@ -0,0 +1,130 @@
+# Chat
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente para exibir conversas em formato de chat com mensagens enviadas e recebidas. Suporta thumbnail de usuário, timestamp, anexos e scroll automático para novas mensagens.
+
+## Quando usar
+
+- Exibir histórico de conversas entre usuários em módulos de mensageria
+- Interfaces de suporte ao cliente com troca de mensagens
+- Logs de comunicação entre sistemas ou usuários com contexto temporal
+
+## Quando não usar
+
+- Para construir um chat com campo de digitação — o componente exibe apenas o histórico; implemente o input separadamente
+- Para exibir notificações ou feeds de atividade — use componentes de timeline ou lista de eventos
+
+## Instalação
+
+```typescript
+import { ChatModule } from '@seniorsistemas/angular-components/chat';
+
+@NgModule({
+  imports: [ChatModule],
+})
+export class MeuModule {}
+```
+
+> **Dependência:** O componente usa `LocaleService` para formatar timestamps. Importe `LocaleModule` no módulo raiz:
+>
+> ```typescript
+> import { LocaleModule } from '@seniorsistemas/angular-components/locale';
+> @NgModule({ imports: [LocaleModule] })
+> export class AppModule {}
+> ```
+
+## Uso básico
+
+```html
+<s-chat [messages]="mensagens" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `messages` | `ChatMessage[]` | `[]` | não | Lista de mensagens exibidas no chat |
+
+### Tipos
+
+```typescript
+type ChatMessage = {
+  senderName: string;       // Nome do remetente (obrigatório)
+  text: string;             // Conteúdo da mensagem (obrigatório)
+  isMine: boolean;          // true para mensagens do usuário atual (obrigatório)
+  thumbnailUrl?: string;    // URL da foto do remetente (opcional)
+  sentAt?: Date;            // Data/hora de envio (opcional)
+  attachmentUrl?: string;   // URL do arquivo anexado (opcional)
+};
+```
+
+## Exemplos
+
+### Conversa básica
+
+```html
+<s-chat [messages]="mensagens"></s-chat>
+```
+
+```typescript
+mensagens: ChatMessage[] = [
+  {
+    senderName: 'João Silva',
+    text: 'Olá! Tudo bem?',
+    thumbnailUrl: 'https://exemplo.com/foto-joao.jpg',
+    isMine: false,
+    sentAt: new Date('2025-01-28T10:00:00Z'),
+  },
+  {
+    senderName: 'Você',
+    text: 'Oi João! Tudo ótimo, e você?',
+    thumbnailUrl: 'https://exemplo.com/minha-foto.jpg',
+    isMine: true,
+    sentAt: new Date('2025-01-28T10:00:30Z'),
+  },
+];
+```
+
+### Com anexo para download
+
+```typescript
+mensagens: ChatMessage[] = [
+  {
+    senderName: 'Ana Costa',
+    text: 'Segue o relatório solicitado.',
+    isMine: false,
+    sentAt: new Date(),
+    attachmentUrl: 'https://exemplo.com/relatorio.pdf',
+  },
+];
+```
+
+### Sem thumbnails e sem timestamps
+
+```typescript
+mensagens: ChatMessage[] = [
+  {
+    senderName: 'Suporte',
+    text: 'Como posso ajudar?',
+    isMine: false,
+  },
+  {
+    senderName: 'Usuário',
+    text: 'Preciso de ajuda com o sistema.',
+    isMine: true,
+  },
+];
+```
+
+## Acessibilidade
+
+- As mensagens são renderizadas em uma lista ordenada — leitores de tela anunciam o nome do remetente e o conteúdo
+- Links de anexo possuem texto descritivo para leitores de tela
+- O scroll automático é feito via `scrollIntoView` para garantir que novas mensagens sejam anunciadas
+
+## Componentes relacionados
+
+- [`Chips`](../chips/README.md) — quando a interface de chat precisa de entrada de tags/destinatários