@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/object-card/README.md

@@ -0,0 +1,158 @@
+# ObjectCard
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de card para exibição de um objeto de análise com cabeçalho principal, campos adicionais e painel expansível. Distribui automaticamente os campos visíveis conforme a largura disponível e suporta nível de severidade visual.
+
+## Quando usar
+
+- Listar entidades de negócio (funcionários, contratos, produtos, servidores) com atributos estruturados
+- Painéis de detalhes de registros que precisam exibir múltiplas informações de forma compacta e responsiva
+- Dashboards com indicadores de status ou alertas visuais em entidades
+
+## Quando não usar
+
+- Para exibir apenas métricas numéricas — use `StatsCard`
+- Para containers genéricos de conteúdo sem estrutura de campos — use `Card` ou `Panel`
+- Quando os dados são tabulares — use `Table`
+
+## Instalação
+
+```typescript
+import { ObjectCardModule } from '@seniorsistemas/angular-components/object-card';
+
+@NgModule({ imports: [ObjectCardModule] })
+export class MeuModulo {}
+```
+
+## Uso básico
+
+```html
+<s-object-card>
+  <s-object-card-main
+    label="Senior Sistemas"
+    description="Tecnologia para Gestão Empresarial"
+    iconClass="fa fa-building"
+  ></s-object-card-main>
+  <s-object-card-field label="Fundação" description="1988"></s-object-card-field>
+  <s-object-card-field label="Cidade" description="Blumenau - SC"></s-object-card-field>
+</s-object-card>
+```
+
+## API
+
+### Inputs (`s-object-card`)
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `id` | `string` | `'s-object-card-{n}'` | Não | Identificador do componente no DOM. Gerado automaticamente se omitido |
+| `expanded` | `boolean` | `false` | Não | Define se o painel expansível está aberto |
+| `expandTooltip` | `string` | `'Abrir painel'` | Não | Tooltip do botão de expandir |
+| `collapseTooltip` | `string` | `'Fechar painel'` | Não | Tooltip do botão de colapsar |
+| `fieldsMinWidth` | `number` | `200` | Não | Largura mínima em pixels de cada campo visível |
+| `severity` | `Severities` | `'default'` | Não | Nível de severidade que altera o estilo da borda |
+| `borderButtonOptions` | `BorderButtonOptions` | `undefined` | Não | Configuração do botão animado na borda lateral |
+
+### Outputs (`s-object-card`)
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `expandedChange` | `EventEmitter<boolean>` | Emitido quando o estado de expansão muda |
+
+### Inputs (`s-object-card-main`)
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `label` | `string` | `undefined` | Não | Texto principal do cabeçalho |
+| `description` | `string` | `undefined` | Não | Subtítulo do cabeçalho |
+| `imageSource` | `string` | `undefined` | Não | URL da imagem do thumbnail |
+| `imageAlt` | `string` | `undefined` | Não | Texto alternativo da imagem |
+| `imageFallback` | `string` | `undefined` | Não | URL de imagem de fallback |
+| `iconClass` | `string` | `'fa fa-picture-o'` | Não | Classe de ícone exibido quando não há imagem |
+| `hasThumbnail` | `boolean` | `true` | Não | Exibe ou oculta a área de thumbnail |
+| `hasDescription` | `boolean` | `true` | Não | Exibe ou oculta a descrição |
+| `isBrand` | `boolean` | `false` | Não | Modo logo/marca — altera proporção do thumbnail |
+| `buttonLabel` | `string` | `undefined` | Não | Label do botão de ações |
+| `buttonModel` | `TieredMenuItemData[]` | `[]` | Não | Itens do menu de ações |
+
+### Inputs (`s-object-card-field`)
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `label` | `string` | `undefined` | Não | Rótulo do campo |
+| `description` | `string` | `undefined` | Não | Valor textual do campo |
+| `iconClass` | `string` | `undefined` | Não | Classe de ícone exibido no campo |
+| `buttonLabel` | `string` | `undefined` | Não | Label de botão no campo (ex: link) |
+| `buttonModel` | `TieredMenuItemData[]` | `[]` | Não | Itens do menu do botão do campo |
+| `badge` | `string` | `''` | Não | Texto do badge colorido |
+| `badgeColor` | `BadgeColors` | `'blue'` | Não | Cor do badge |
+
+### Tipos
+
+```typescript
+type Severities = 'default' | 'info' | 'warn' | 'error' | 'success';
+
+interface BorderButtonOptions {
+  visible?: (severity: Severities) => boolean;
+  label?: (severity: Severities) => string;
+  tooltip?: (severity: Severities) => string;
+  icon?: (severity: Severities) => string;
+  onClick?: () => void;
+}
+```
+
+## Exemplos
+
+### Com botão de ações e campos
+
+```html
+<s-object-card [expanded]="false" [fieldsMinWidth]="200">
+  <s-object-card-main
+    label="Colaborador"
+    description="Departamento de TI"
+    iconClass="far fa-user"
+    buttonLabel="Ações"
+    [buttonModel]="actionMenu"
+  ></s-object-card-main>
+  <s-object-card-field label="Cargo" description="Desenvolvedor Frontend"></s-object-card-field>
+  <s-object-card-field label="E-mail" buttonLabel="contato@empresa.com" iconClass="fa fa-envelope"></s-object-card-field>
+  <s-object-card-field label="Status" badge="Ativo" badgeColor="green"></s-object-card-field>
+</s-object-card>
+```
+
+### Com severidade visual
+
+```html
+<s-object-card [severity]="'error'">
+  <s-object-card-main
+    label="Servidor de Produção"
+    description="Infraestrutura"
+    iconClass="fa fa-server"
+  ></s-object-card-main>
+  <s-object-card-field label="CPU" description="87%"></s-object-card-field>
+  <s-object-card-field label="Status" badge="Crítico" badgeColor="red"></s-object-card-field>
+</s-object-card>
+```
+
+### Com template customizado no label
+
+```html
+<s-object-card-main description="Empresa parceira" iconClass="fa fa-building">
+  <span labelTemplate style="color: #2d7d46; font-weight: 600;">
+    <i class="fa fa-check-circle"></i> Senior Sistemas
+  </span>
+</s-object-card-main>
+```
+
+## Acessibilidade
+
+- O botão de expandir/colapsar possui tooltip acessível via `expandTooltip` e `collapseTooltip`
+- Campos ocultos são acessíveis via teclado após expandir o painel
+- Responsivo: em telas pequenas (≤ SM), todos os campos ficam ocultos e acessíveis via expansão
+- Suporta navegação por teclado no botão de ações e no chevron de expansão
+
+## Componentes relacionados
+
+- [`Card`](../card/README.md) — container genérico de conteúdo
+- [`StatsCard`](../stats-card/README.md) — exibição de métricas numéricas
+- [`Thumbnail`](../thumbnail/README.md) — exibição de imagem em miniatura

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seniorsistemas/angular-components",
-  "version": "19.3.3",
+  "version": "19.3.4",
   "peerDependencies": {
     "@angular/cdk": "^18.2.14",
     "@angular/common": "^18.2.0",

package/paginator/README.md

@@ -0,0 +1,121 @@
+# Paginator
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente standalone de paginação que exibe botões de navegação de páginas, seletor de itens por página e atalhos para a primeira e última página. Emite o evento `pageChange` a cada mudança de página ou de tamanho de página.
+
+## Quando usar
+
+- Listagens e tabelas com dados paginados no servidor ou no cliente
+- Sempre que o volume de registros tornar impraticável exibir tudo de uma vez
+- Quando o usuário precisa controlar quantos itens são exibidos por página
+
+## Quando não usar
+
+- Para listas com poucos itens que cabem em uma única tela — exiba todos sem paginação
+- Quando a navegação é por rolagem infinita (infinite scroll) — use um mecanismo de scroll virtual
+
+## Instalação
+
+```typescript
+import { PaginatorComponent } from '@seniorsistemas/angular-components/paginator';
+
+@Component({
+  standalone: true,
+  imports: [PaginatorComponent],
+})
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<s-paginator
+  [totalRecords]="total"
+  [(rows)]="tamanhoPagina"
+  (pageChange)="onPaginaMudou($event)"
+/>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `totalRecords` | `number` | — | Sim | Número total de registros disponíveis para paginação |
+| `rows` | `number` | `10` | Não | Número de itens por página. Suporta two-way binding via `[(rows)]` |
+| `rowsPerPageOptions` | `number[]` | `[10, 20, 50, 100, 200]` | Não | Opções disponíveis no seletor de itens por página |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `pageChange` | `OutputEmitterRef<PageChange>` | Emitido sempre que a página atual ou o número de itens por página muda |
+
+### Tipos
+
+```typescript
+interface PageChange {
+  page: number;       // Índice da página atual (base 0)
+  pageCount: number;  // Total de páginas
+  rows: number;       // Número de itens por página
+  first: number;      // Índice do primeiro registro da página atual
+}
+```
+
+## Exemplos
+
+### Paginação básica
+
+```html
+<s-paginator
+  [totalRecords]="120"
+  [rows]="10"
+  [rowsPerPageOptions]="[10, 20, 50, 100, 200]"
+  (pageChange)="onPageChange($event)"
+></s-paginator>
+```
+
+### Com two-way binding nas linhas
+
+```html
+<s-paginator
+  [totalRecords]="totalRegistros"
+  [(rows)]="itensPorPagina"
+  (pageChange)="carregarPagina($event)"
+></s-paginator>
+```
+
+### Grande volume de dados
+
+```html
+<s-paginator
+  [totalRecords]="1000"
+  [rows]="20"
+  [rowsPerPageOptions]="[10, 20, 50, 100, 200]"
+  (pageChange)="onPageChange($event)"
+></s-paginator>
+```
+
+### Com opções personalizadas de itens por página
+
+```html
+<s-paginator
+  [totalRecords]="80"
+  [rows]="10"
+  [rowsPerPageOptions]="[5, 10, 25]"
+  (pageChange)="onPageChange($event)"
+></s-paginator>
+```
+
+## Acessibilidade
+
+- Os botões de navegação (primeira página, anterior, próxima, última) são elementos `<button>` nativos com estados desabilitados declarados via `disabled`
+- Os botões de número de página são clicáveis via teclado (Tab + Enter/Space)
+- O seletor de itens por página usa o componente `Select` com suporte a navegação por teclado
+
+## Componentes relacionados
+
+- [`Table`](../table/README.md) — tabela de dados que integra o Paginator para navegação entre páginas
+- [`Select`](../select/README.md) — componente de seleção usado internamente para o seletor de itens por página

package/panel/README.md

@@ -0,0 +1,147 @@
+# Panel
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente container com cabeçalho, corpo e rodapé opcionais. Suporta colapso com animação, diferentes níveis de severidade visual na borda e templates customizáveis para cada seção via `sTemplate`.
+
+## Quando usar
+
+- Agrupar seções de conteúdo relacionado com título em formulários ou dashboards
+- Seções opcionais que podem ser ocultadas pelo usuário (modo colapsável)
+- Destacar áreas com estado de alerta, erro ou sucesso via severidade visual
+
+## Quando não usar
+
+- Para múltiplas seções expansíveis e exclusivas — use `Accordion`
+- Para agrupamento de campos de formulário com borda — use `Fieldset`
+- Para containers sem necessidade de cabeçalho ou severidade — use `Card`
+
+## Instalação
+
+```typescript
+import { PanelModule } from '@seniorsistemas/angular-components/panel';
+
+@NgModule({ imports: [PanelModule] })
+export class MeuModulo {}
+```
+
+## Uso básico
+
+```html
+<s-panel header="Título do Painel">
+  <p>Conteúdo do painel via ng-content.</p>
+</s-panel>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `header` | `string` | `undefined` | Não | Texto exibido no cabeçalho. Quando omitido, o cabeçalho não é renderizado |
+| `toggleable` | `boolean` | `false` | Não | Exibe botão +/- no cabeçalho para colapsar/expandir o conteúdo |
+| `collapsed` | `boolean` | `false` | Não | Define o estado inicial como colapsado. Requer `toggleable: true` |
+| `severity` | `Severities` | `'default'` | Não | Aplica uma borda colorida lateral ao painel |
+| `borderButtonOptions` | `BorderButtonOptions` | `undefined` | Não | Configuração do botão animado exibido na borda quando `severity` não é `'default'` |
+| `class` | `string` | `''` | Não | Classes CSS adicionais aplicadas ao elemento raiz |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `collapsedChange` | `EventEmitter<boolean>` | Emitido ao colapsar ou expandir o painel. Emite o novo estado booleano |
+
+### Tipos
+
+```typescript
+type Severities = 'default' | 'info' | 'warn' | 'error' | 'success';
+
+type PanelTemplateTypes = 'header' | 'body' | 'footer';
+
+interface BorderButtonOptions {
+  visible?: (severity: Severities) => boolean;
+  label?: (severity: Severities) => string;
+  tooltip?: (severity: Severities) => string;
+  icon?: (severity: Severities) => string;
+  disabled?: (severity: Severities) => boolean;
+  onClick?: () => void;
+}
+```
+
+## Exemplos
+
+### Painel básico com cabeçalho
+
+```html
+<s-panel header="Informações Gerais">
+  <p>Conteúdo do painel via ng-content.</p>
+</s-panel>
+```
+
+### Painel colapsável
+
+```html
+<s-panel
+  header="Dados Adicionais"
+  [toggleable]="true"
+  [collapsed]="false"
+  (collapsedChange)="onColapsou($event)"
+>
+  <p>Clique no +/- para colapsar ou expandir.</p>
+</s-panel>
+```
+
+### Painel com severidade
+
+```html
+<s-panel header="Atenção" severity="warn">
+  <p>Painel com borda de aviso.</p>
+</s-panel>
+
+<s-panel header="Erro Crítico" severity="error">
+  <p>Painel com borda de erro.</p>
+</s-panel>
+```
+
+### Com template customizado no cabeçalho
+
+```html
+<s-panel [toggleable]="true">
+  <ng-template sTemplate="header">
+    <div style="display: flex; justify-content: space-between; align-items: center; width: 100%;">
+      <span style="font-weight: 600;">Header Customizado</span>
+      <span class="badge">Novo</span>
+    </div>
+  </ng-template>
+  <p>Conteúdo do painel.</p>
+</s-panel>
+```
+
+### Com template de body e footer
+
+```html
+<s-panel header="Painel com Footer">
+  <ng-template sTemplate="body">
+    <p>Conteúdo via sTemplate="body".</p>
+  </ng-template>
+  <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="Salvar" priority="primary"></s-button>
+    </div>
+  </ng-template>
+</s-panel>
+```
+
+## Acessibilidade
+
+- O botão de toggle (+/-) é um elemento `<button>` nativo, acessível via teclado e leitores de tela
+- A animação de colapso usa Angular Animations e não afeta a navegação por teclado
+- O cabeçalho customizado via `sTemplate="header"` deve garantir contraste e semântica adequados pelo implementador
+
+## Componentes relacionados
+
+- [`Accordion`](../accordion/README.md) — painéis expansíveis com múltiplos itens mutuamente exclusivos
+- [`Card`](../card/README.md) — container com suporte a banner e templates
+- [`Fieldset`](../fieldset/README.md) — agrupamento de campos de formulário

package/password-strength/README.md

@@ -0,0 +1,144 @@
+# PasswordStrength
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Diretiva Angular que adiciona um indicador visual de força de senha a qualquer campo de input. Ao receber foco ou a cada tecla digitada, exibe um popover com três barras coloridas e um título indicando o nível de força: fraca, média ou forte. Desaparece ao perder o foco.
+
+## Quando usar
+
+- Formulários de cadastro e alteração de senha onde o feedback de segurança é importante
+- Qualquer campo de senha que precise orientar o usuário sobre a complexidade mínima exigida
+
+## Quando não usar
+
+- Para validação de senha no servidor — esta diretiva é apenas feedback visual no cliente
+- Quando as regras de senha são exibidas de forma estática (lista de requisitos) — use texto informativo diretamente no formulário
+- Em campos que não sejam de senha — use outros mecanismos de feedback
+
+## Instalação
+
+```typescript
+import { PasswordStrengthModule } from '@seniorsistemas/angular-components/password-strength';
+
+@NgModule({ imports: [PasswordStrengthModule] })
+export class MeuModulo {}
+```
+
+## Uso básico
+
+```html
+<input
+  type="password"
+  [sPasswordStrength]="true"
+  passwordStrengthDescription="A senha deve conter letras maiúsculas, números e caracteres especiais."
+/>
+```
+
+## API
+
+### Inputs (diretiva `sPasswordStrength`)
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `sPasswordStrength` | `boolean` | `true` | Não | Habilita ou desabilita o indicador de força |
+| `passwordStrengthDescription` | `string` | — | Sim | Texto de orientação exibido no indicador |
+| `passwordStrengthPosition` | `PasswordStrengthPositions` | `'right'` | Não | Posição preferencial do indicador em relação ao campo |
+| `passwordStrengthWeakTitle` | `string` | Tradução padrão | Não | Texto customizado para o nível fraco |
+| `passwordStrengthMediumTitle` | `string` | Tradução padrão | Não | Texto customizado para o nível médio |
+| `passwordStrengthStrongTitle` | `string` | Tradução padrão | Não | Texto customizado para o nível forte |
+| `passwordStrengthValidation` | `(content: string) => PasswordStrengths` | Validação padrão | Não | Função customizada para calcular a força da senha |
+
+### Tipos
+
+```typescript
+type PasswordStrengthPositions = 'top' | 'right' | 'left';
+
+type PasswordStrengths = 'veryWeak' | 'weak' | 'medium' | 'strong';
+```
+
+### Validação padrão
+
+A função padrão avalia os seguintes critérios (1 ponto cada):
+
+- Comprimento mínimo de 6 caracteres
+- Contém pelo menos um número
+- Contém pelo menos uma letra minúscula
+- Contém pelo menos uma letra maiúscula
+- Contém pelo menos um caractere especial (`!@#$%&*.\\=+^~-`)
+
+| Pontos | Nível |
+|--------|-------|
+| 0 | `veryWeak` |
+| 1–3 | `weak` |
+| 4 | `medium` |
+| 5 | `strong` |
+
+## Exemplos
+
+### Campo padrão com validação padrão
+
+```html
+<div style="display: flex; flex-direction: column; gap: 8px;">
+  <label>Senha</label>
+  <input
+    type="password"
+    [sPasswordStrength]="true"
+    passwordStrengthDescription="A senha deve ter letras maiúsculas, números e caracteres especiais."
+  />
+</div>
+```
+
+### Com validação customizada
+
+```html
+<input
+  type="password"
+  [sPasswordStrength]="true"
+  passwordStrengthDescription="A senha deve ter no mínimo 8 caracteres."
+  [passwordStrengthValidation]="meuValidador"
+/>
+```
+
+```typescript
+meuValidador(content: string): PasswordStrengths {
+  if (content.length < 4) return 'veryWeak';
+  if (content.length < 6) return 'weak';
+  if (content.length < 8) return 'medium';
+  return 'strong';
+}
+```
+
+### Com títulos customizados
+
+```html
+<input
+  type="password"
+  [sPasswordStrength]="true"
+  passwordStrengthDescription="Use letras, números e símbolos."
+  passwordStrengthWeakTitle="Insegura"
+  passwordStrengthMediumTitle="Razoável"
+  passwordStrengthStrongTitle="Segura"
+/>
+```
+
+### Posicionado à esquerda
+
+```html
+<input
+  type="password"
+  [sPasswordStrength]="true"
+  passwordStrengthDescription="Requisitos da senha."
+  passwordStrengthPosition="left"
+/>
+```
+
+## Acessibilidade
+
+- O indicador é exibido ao focar o campo (`focus`) e a cada tecla digitada (`keyup`)
+- O indicador desaparece ao perder o foco (`blur`)
+- O componente reposiciona automaticamente entre `right`, `left` e `top` conforme o espaço disponível na viewport
+- O texto de `passwordStrengthDescription` orienta o usuário sobre os requisitos da senha
+
+## Componentes relacionados
+
+- [`PinCodeField`](../pin-code-field/README.md) — campo de código PIN com navegação entre dígitos