@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/star-rating/README.md

@@ -0,0 +1,127 @@
+# StarRating
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de avaliação por estrelas para coletar feedback de usuários. Permite selecionar uma nota em uma escala visual de estrelas, com suporte à integração com Reactive Forms e ngModel.
+
+## Quando usar
+
+- Avaliação de produtos em e-commerce
+- Coleta de feedback de serviços ou atendimento
+- Classificação de conteúdo (artigos, vídeos, cursos)
+- Formulários de satisfação do usuário
+
+## Quando não usar
+
+- Escalas de avaliação com texto descritivo por nível — prefira `RadioButtonGroup` com labels
+- Coleta de sentimento binário (positivo/negativo) — prefira um par de botões ou `Switch`
+- Exibição de média de avaliações sem interação — considere usar ícones estáticos
+
+## Instalação
+
+```typescript
+import { StarRatingComponent } from '@seniorsistemas/angular-components/star-rating';
+
+@Component({ standalone: true, imports: [StarRatingComponent] })
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<s-star-rating formControlName="avaliacao" [starsRange]="5" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `selectedStar` | `ModelSignal<number>` | `0` | Não | Índice da estrela selecionada (1-based). Suporta `[(selectedStar)]` |
+| `starsRange` | `InputSignal<number>` | `5` | Não | Número total de estrelas exibidas |
+| `justifyContent` | `JustifyTypes` | `'center'` | Não | Alinhamento horizontal das estrelas |
+| `disabled` | `ModelSignal<boolean>` | `false` | Não | Desabilita a seleção de estrelas. Suporta `[(disabled)]` |
+
+### Tipos
+
+```typescript
+type JustifyTypes =
+  | 'start' | 'end' | 'center'
+  | 'between' | 'around' | 'evenly'
+  | 'stretch' | 'baseline' | 'normal'
+  | 'end-safe' | 'center-safe';
+```
+
+## Exemplos
+
+### Avaliação padrão com 5 estrelas
+
+```html
+<s-star-rating
+  [selectedStar]="3"
+  [starsRange]="5"
+  justifyContent="center"
+></s-star-rating>
+```
+
+### Integração com Reactive Forms
+
+```html
+<form [formGroup]="formGroup">
+  <s-star-rating
+    formControlName="avaliacao"
+    [starsRange]="5"
+    justifyContent="center"
+  ></s-star-rating>
+  <p>Valor selecionado: {{ formGroup.get('avaliacao')?.value }} estrela(s)</p>
+</form>
+```
+
+```typescript
+formGroup = new FormGroup({
+  avaliacao: new FormControl(2),
+});
+```
+
+### Escala customizada de 10 estrelas
+
+```html
+<s-star-rating
+  [(selectedStar)]="nota"
+  [starsRange]="10"
+  justifyContent="center"
+></s-star-rating>
+```
+
+### Somente leitura (desabilitado)
+
+```html
+<s-star-rating
+  [selectedStar]="mediaAvaliacoes"
+  [starsRange]="5"
+  [disabled]="true"
+  justifyContent="start"
+></s-star-rating>
+```
+
+### Alinhamento à esquerda em listagem
+
+```html
+<s-star-rating
+  [selectedStar]="produto.avaliacao"
+  [starsRange]="5"
+  justifyContent="start"
+></s-star-rating>
+```
+
+## Acessibilidade
+
+- Cada estrela é renderizada com `role="radio"` dentro de um grupo de radiobuttons
+- Navegação por teclado: `Tab` para focar o grupo, `ArrowLeft`/`ArrowRight` para navegar entre estrelas
+- Clicar na estrela já selecionada a deseleciona (retorna o valor para `0`)
+- O estado `disabled` bloqueia totalmente a interação e é propagado via `setDisabledState` do `ControlValueAccessor`
+
+## Componentes relacionados
+
+- [`RadioButtonGroup`](../radio-button-group/README.md) — seleção única com rótulos descritivos por opção

package/stats-card/README.md

@@ -0,0 +1,135 @@
+# StatsCard
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Card de estatística que exibe um valor numérico com ícone, rótulo e animação de contagem. Suporta diferentes estilos visuais (modo claro, modo escuro, versão leve) e pode emitir evento ao ser clicado.
+
+## Quando usar
+
+- Dashboards com métricas e indicadores de performance
+- Painéis de resumo com dados numéricos relevantes (totais, contagens, KPIs)
+- Indicadores visuais que precisam destacar variações de valor com animação
+
+## Quando não usar
+
+- Exibição de dados textuais complexos — prefira `Card` ou um componente de lista
+- Navegação para outra seção — prefira `Tile`
+- Indicadores sem valor numérico central
+
+## Instalação
+
+```typescript
+import { StatsCardModule } from '@seniorsistemas/angular-components/stats-card';
+
+@NgModule({ imports: [StatsCardModule] })
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-stats-card
+  label="Vendas"
+  value="1.234"
+  iconClass="fas fa-shopping-cart"
+  color="#3399ff"
+/>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `label` | `string` | — | Sim | Rótulo descritivo da estatística exibida |
+| `value` | `string` | `'0'` | Não | Valor numérico exibido. Quando `animateNumbers` está ativo, a contagem é animada |
+| `iconClass` | `string` | `'fa fa-bar-chart'` | Não | Classe CSS do ícone (Font Awesome) |
+| `color` | `string` | `'#339966'` | Não | Cor de destaque do card em formato CSS |
+| `lightMode` | `boolean` | `true` | Não | Ativa o modo de cores claras (ícone com fundo colorido) |
+| `lightVersion` | `boolean` | `false` | Não | Ativa a versão visual leve (sem sombra e com fundo claro) |
+| `alwaysWithBorder` | `boolean` | `false` | Não | Exibe borda mesmo quando o card não está em destaque |
+| `animateNumbers` | `boolean` | `true` | Não | Habilita a animação de contagem ao atualizar o valor |
+| `clickable` | `boolean` | `false` | Não | Habilita o cursor de ponteiro e o evento de clique |
+| `tooltip` | `string` | `''` | Não | Texto do tooltip exibido ao passar o mouse sobre o card |
+| `id` | `string` | `'s-stats-card-{n}'` | Não | Identificador único do card no DOM |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `clicked` | `EventEmitter<MouseEvent>` | Emitido quando o usuário clica no card (requer `clickable = true`) |
+
+## Exemplos
+
+### Card padrão (modo claro)
+
+```html
+<s-stats-card
+  label="População"
+  value="214000000"
+  iconClass="fa fa-users"
+  color="#339966"
+  [lightMode]="true"
+></s-stats-card>
+```
+
+### Card modo escuro
+
+```html
+<s-stats-card
+  label="Área territorial"
+  value="8515767 km²"
+  iconClass="fa fa-map"
+  color="#F45B5B"
+  [lightMode]="false"
+></s-stats-card>
+```
+
+### Card clicável
+
+```html
+<s-stats-card
+  label="Estados"
+  value="27"
+  iconClass="fa fa-flag"
+  color="#4A90E2"
+  [clickable]="true"
+  [alwaysWithBorder]="true"
+  tooltip="Clique para ver detalhes"
+  (clicked)="onVerDetalhes($event)"
+></s-stats-card>
+```
+
+### Grid de múltiplos cards
+
+```html
+<div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); gap: 1rem;">
+  <s-stats-card label="Total de pedidos" value="1.234" iconClass="fa fa-shopping-cart" color="#339966" [lightMode]="true"></s-stats-card>
+  <s-stats-card label="Receita" value="R$ 45.200" iconClass="fa fa-dollar" color="#4A90E2" [lightMode]="false"></s-stats-card>
+  <s-stats-card label="Usuários ativos" value="892" iconClass="fa fa-users" color="#9B59B6" [lightMode]="true" [lightVersion]="true"></s-stats-card>
+</div>
+```
+
+### Com valor dinâmico e animação
+
+```html
+<s-stats-card
+  label="Visitantes hoje"
+  [value]="visitantesHoje.toString()"
+  iconClass="fa fa-eye"
+  color="#339966"
+  [animateNumbers]="true"
+></s-stats-card>
+```
+
+## Acessibilidade
+
+- Quando `clickable = true`, o card recebe cursor pointer; recomenda-se fornecer `tooltip` descritivo para leitores de tela
+- A animação de contagem tem duração de 200ms com steps de 20ms; não é disparada quando `animateNumbers = false`
+- O atributo `id` permite associar o card a outros elementos acessíveis na página
+
+## Componentes relacionados
+
+- [`Tile`](../tile/README.md) — card clicável para navegação
+- [`Card`](../card/README.md) — container genérico de conteúdo

package/stepper/README.md

@@ -0,0 +1,164 @@
+# Stepper
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de progresso em etapas que exibe uma linha do tempo horizontal de passos com animações. Permite ao usuário visualizar e navegar entre etapas de um fluxo sequencial. Suporta passos ocultos, desabilitados e diferentes estados visuais (sucesso, aviso).
+
+> **Nota:** O seletor `s-steps` e o pacote `steps` estão descontinuados. Use `s-stepper` e o pacote `stepper` em novos projetos. O seletor antigo será removido na versão 20.0.0.
+
+## Quando usar
+
+- Formulários multi-etapa (wizard) com progresso visível
+- Onboarding de novos usuários com passos sequenciais
+- Processos de checkout ou cadastro com etapas bem definidas
+- Fluxos onde o usuário pode navegar de volta para corrigir etapas anteriores
+
+## Quando não usar
+
+- Fluxos com apenas 2 passos — prefira botões Anterior/Próximo simples
+- Navegação geral da aplicação — prefira tabs ou breadcrumbs
+- Processos sem sequência clara entre etapas
+
+## Instalação
+
+```typescript
+import { StepperModule } from '@seniorsistemas/angular-components/stepper';
+
+@NgModule({ imports: [StepperModule] })
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-stepper
+  [steps]="etapas"
+  [activeIndex]="etapaAtiva"
+  (stepSelected)="onEtapaSelecionada($event)"
+/>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `steps` | `Step[]` | — | Sim | Lista de etapas exibidas no stepper |
+| `activeIndex` | `number` | `0` | Sim | Índice (0-based) da etapa atualmente ativa. Controlado externamente |
+| `id` | `string` | `'s-steps-{n}'` | Não | Identificador único do componente no DOM |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `stepSelected` | `EventEmitter<StepSelectionEvent>` | Emitido quando o usuário clica em uma etapa habilitada e não ativa |
+
+### Tipos
+
+```typescript
+interface Step {
+  id: any;
+  label: string;        // Texto exibido abaixo do indicador. Obrigatório.
+  state?: StepState;    // Estado visual do passo
+  disabled?: boolean;   // Impede clique e aplica estilo desabilitado
+  hidden?: boolean;     // Remove o passo da renderização
+  tooltip?: string;     // Texto do tooltip ao passar o mouse
+  ariaLabel?: string;   // Label acessível alternativo
+  ariaControls?: string; // ID do painel controlado por este passo
+}
+
+enum StepState {
+  Default = 'default',
+  Success = 'success',
+  Warning = 'warning',
+}
+
+interface StepSelectionEvent {
+  step: Step;    // Objeto Step selecionado
+  index: number; // Índice da etapa selecionada
+  event: Event;  // Evento de clique original
+}
+```
+
+## Exemplos
+
+### Fluxo básico com 4 etapas
+
+```html
+<s-stepper
+  [steps]="etapas"
+  [activeIndex]="etapaAtual"
+  (stepSelected)="onSelecionar($event)"
+></s-stepper>
+```
+
+```typescript
+etapas: Step[] = [
+  { id: '1', label: 'Dados Pessoais' },
+  { id: '2', label: 'Endereço' },
+  { id: '3', label: 'Contato' },
+  { id: '4', label: 'Confirmação' },
+];
+
+onSelecionar(event: StepSelectionEvent): void {
+  this.etapaAtual = event.index;
+}
+```
+
+### Com estados visuais
+
+```typescript
+etapas: Step[] = [
+  { id: '1', label: 'Dados Pessoais', state: StepState.Success },
+  { id: '2', label: 'Endereço', state: StepState.Warning },
+  { id: '3', label: 'Documentos', state: StepState.Success },
+  { id: '4', label: 'Confirmação' },
+];
+```
+
+### Modo linear (passos futuros bloqueados)
+
+```typescript
+etapas: Step[] = [
+  { id: '1', label: 'Concluído', state: StepState.Success },
+  { id: '2', label: 'Em Andamento' },
+  { id: '3', label: 'Bloqueado', disabled: true },
+  { id: '4', label: 'Bloqueado', disabled: true },
+];
+```
+
+### Com tooltips explicativos
+
+```typescript
+etapas: Step[] = [
+  { id: '1', label: 'Cadastro', state: StepState.Success, tooltip: 'Etapa concluída' },
+  { id: '2', label: 'Validação', tooltip: 'Valide seu e-mail e telefone' },
+  { id: '3', label: 'Aprovação', disabled: true, tooltip: 'Aguardando validação' },
+];
+```
+
+### Com botões de navegação
+
+```html
+<s-stepper [steps]="etapas" [activeIndex]="etapaAtual" (stepSelected)="onSelecionar($event)"></s-stepper>
+
+<div style="display: flex; gap: 8px; margin-top: 16px; justify-content: flex-end;">
+  <button [disabled]="etapaAtual === 0" (click)="voltar()">Voltar</button>
+  <button [disabled]="etapaAtual === etapas.length - 1" (click)="avancar()">Avançar</button>
+</div>
+```
+
+## Acessibilidade
+
+- O componente possui `role="tablist"` e `aria-orientation="horizontal"`
+- Cada passo é renderizado com `role="tab"` e `aria-selected`
+- O atributo `ariaLabel` permite fornecer um nome alternativo mais descritivo para leitores de tela
+- O atributo `ariaControls` vincula o passo ao painel de conteúdo correspondente
+- Passos visitados (índice menor que `activeIndex`) recebem ícone de check automaticamente
+- A barra de progresso entre os passos é animada ao mudar o `activeIndex`
+
+## Componentes relacionados
+
+- [`Steps`](../steps/README.md) — alias depreciado para este componente
+- [`Accordion`](../accordion/README.md) — organização de conteúdo em seções expansíveis

package/switch/README.md

@@ -0,0 +1,125 @@
+# Switch
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de chave tipo switch (liga/desliga) para alternar entre dois estados booleanos. Implementa `ControlValueAccessor` para uso em formulários Angular. Suporta rótulos personalizados para os estados verdadeiro e falso, além de modo somente leitura.
+
+## Quando usar
+
+- Ativar ou desativar funcionalidades ou configurações
+- Preferências do usuário (notificações, atualizações automáticas)
+- Qualquer contexto com decisão binária clara (ligado/desligado, ativo/inativo)
+
+## Quando não usar
+
+- Seleção de múltiplas opções — prefira `Checkbox`
+- Escolha entre mais de dois estados — prefira `RadioButtonGroup` ou `SelectButton`
+- Quando o estado precisa de confirmação antes de ser aplicado — prefira `Checkbox` com botão de submissão
+
+## Instalação
+
+```typescript
+import { SwitchModule } from '@seniorsistemas/angular-components/switch';
+
+@NgModule({ imports: [SwitchModule] })
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-switch formControlName="ativo" trueLabel="Ativo" falseLabel="Inativo" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `value` | `boolean` | `false` | Não | Estado atual do switch |
+| `trueLabel` | `string` | `'Ligado'` | Não | Rótulo exibido quando o valor é `true` |
+| `falseLabel` | `string` | `'Desligado'` | Não | Rótulo exibido quando o valor é `false` |
+| `disabled` | `boolean` | `false` | Não | Desabilita o componente, impedindo interação e alterações |
+| `readonly` | `boolean` | `false` | Não | Impede alterações pelo usuário sem desabilitar visualmente o campo |
+| `showStatusLabel` | `boolean` | `true` | Não | Controla se o label de status (trueLabel/falseLabel) é exibido |
+| `inputId` | `string` | `undefined` | Não | ID do `<input>` interno para associação com `<label>` externo |
+| `inputName` | `string` | `undefined` | Não | Atributo `name` do `<input>` interno |
+| `label` | `string` | `undefined` | Não | Nome acessível descritivo para tecnologias assistivas (`aria-label`) |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `valueChanged` | `EventEmitter<boolean>` | Emitido quando o valor do switch muda, com o novo estado booleano |
+
+## Exemplos
+
+### Switch básico sem labels
+
+```html
+<s-switch formControlName="ativo"></s-switch>
+```
+
+### Com labels customizados
+
+```html
+<s-switch
+  formControlName="notificacoes"
+  trueLabel="Notificações ativadas"
+  falseLabel="Notificações desativadas"
+></s-switch>
+```
+
+### Integração com Reactive Forms
+
+```html
+<form [formGroup]="form" (ngSubmit)="salvar()">
+  <s-switch
+    formControlName="notificacoes"
+    trueLabel="Notificações Ativadas"
+    falseLabel="Notificações Desativadas"
+  ></s-switch>
+  <s-switch
+    formControlName="marketing"
+    trueLabel="Aceito receber ofertas"
+    falseLabel="Não aceito ofertas"
+  ></s-switch>
+  <s-switch
+    formControlName="atualizacoes"
+    trueLabel="Atualizações automáticas"
+    falseLabel="Atualizações manuais"
+  ></s-switch>
+  <button type="submit">Salvar Preferências</button>
+</form>
+```
+
+### Somente leitura (readonly)
+
+```html
+<!-- Mantém aparência habilitada, mas bloqueia alterações -->
+<s-switch [value]="true" trueLabel="Ativo" falseLabel="Inativo" [readonly]="true"></s-switch>
+```
+
+### Desabilitado
+
+```html
+<s-switch
+  trueLabel="Habilitado"
+  falseLabel="Desabilitado"
+  [disabled]="true"
+></s-switch>
+```
+
+## Acessibilidade
+
+- O elemento interno é um `<input type="checkbox">` com `role="switch"`, garantindo semântica correta para leitores de tela
+- Pode ser ativado/desativado com `Espaço` quando em foco
+- O input recebe foco visual ao ser navegado por teclado (classe CSS `switch--focus` adicionada via `focusin`/`focusout`)
+- O `inputId` permite associar um `<label>` externo para melhor acessibilidade
+- O `label` define um `aria-label` descritivo quando não há label visual associado
+
+## Componentes relacionados
+
+- [`Checkbox`](../checkbox/README.md) — seleção de múltiplas opções independentes
+- [`RadioButton`](../radio-button/README.md) — seleção única entre opções mutuamente exclusivas