@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/checkbox/README.md

@@ -0,0 +1,108 @@
+# Checkbox
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de caixa de seleção com suporte a três estados: marcado, desmarcado e indeterminado. Implementa `ControlValueAccessor` para integração com Reactive Forms e Template-driven Forms do Angular.
+
+## Quando usar
+
+- Aceite de termos e condições
+- Seleção de múltiplos itens independentes em uma lista
+- Ativação ou desativação de funcionalidades opcionais
+- Checkbox "selecionar todos" com estado indeterminado para controlar grupos
+
+## Quando não usar
+
+- Quando apenas uma opção de um grupo pode ser selecionada — use `RadioButton` em vez disso
+- Quando o valor é um toggle visual de estado ativo/inativo — use `Switch` em vez disso
+- Para seleção hierárquica com múltiplos níveis — use `CheckboxList`
+
+## Instalação
+
+```typescript
+import { CheckboxComponent } from '@seniorsistemas/angular-components/checkbox';
+
+@Component({ standalone: true, imports: [CheckboxComponent] })
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<s-checkbox label="Aceito os termos de uso" [(checked)]="aceito" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `label` | `string` | `''` | não | Texto exibido ao lado do checkbox |
+| `checked` | `boolean` | `false` | não | Estado atual (two-way binding via `[(checked)]`) |
+| `disabled` | `boolean` | `false` | não | Desabilita o checkbox (two-way binding via `[(disabled)]`) |
+| `indeterminate` | `boolean` | `false` | não | Estado indeterminado (traço) — descartado na primeira interação |
+| `ariaLabel` | `string` | `undefined` | não | Rótulo acessível para leitores de tela |
+| `ariaLabelledBy` | `string` | `undefined` | não | ID do elemento que descreve o checkbox |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `checkedChange` | `OutputEmitterRef<boolean>` | Emitido quando o valor é alterado pelo usuário |
+
+## Exemplos
+
+### Uso com ngModel
+
+```html
+<s-checkbox label="Receber newsletter" [(checked)]="receberNewsletter"></s-checkbox>
+```
+
+### Uso com Reactive Forms
+
+```html
+<form [formGroup]="form">
+  <s-checkbox formControlName="newsletter" label="Receber newsletter"></s-checkbox>
+  <s-checkbox formControlName="termos" label="Aceito os termos de uso"></s-checkbox>
+  <s-checkbox formControlName="notificacoes" label="Ativar notificações" [disabled]="true"></s-checkbox>
+</form>
+```
+
+### Padrão "selecionar todos" com estado indeterminado
+
+```html
+<s-checkbox
+  label="Selecionar todos"
+  [checked]="todosMarcados"
+  [indeterminate]="algunsMarcados"
+  (checkedChange)="alternarTodos()">
+</s-checkbox>
+
+<div style="margin-left: 28px;">
+  @for (item of itens; track item.id) {
+    <s-checkbox
+      [label]="item.label"
+      [checked]="item.checked"
+      (checkedChange)="alternarItem(item.id)">
+    </s-checkbox>
+  }
+</div>
+```
+
+### Desabilitado (somente leitura)
+
+```html
+<s-checkbox label="Opção obrigatória" [checked]="true" [disabled]="true"></s-checkbox>
+```
+
+## Acessibilidade
+
+- O elemento recebe `role="checkbox"` com `aria-checked` (`true`, `false` ou `"mixed"` para indeterminado)
+- Totalmente navegável por teclado: **Tab** para focar, **Space** para alternar
+- Use `ariaLabel` quando não houver `label` visível (ex.: checkbox em cabeçalho de tabela)
+
+## Componentes relacionados
+
+- [`CheckboxList`](../checkbox-list/README.md) — quando a seleção é hierárquica com múltiplos níveis de pai/filho
+- [`Switch`](../switch/README.md) — alternador visual de estado ativo/inativo

package/checkbox-list/README.md

@@ -0,0 +1,149 @@
+# CheckboxList
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de lista de checkboxes com suporte a hierarquia multinível. Gerencia automaticamente os estados indeterminado e marcado do nó pai com base nos filhos selecionados. Implementa `ControlValueAccessor` para integração completa com Angular Forms.
+
+## Quando usar
+
+- Seleção múltipla de opções agrupadas por categoria (ex.: frutas, verduras, legumes)
+- Permissões agrupadas por módulo com seleção em cascata
+- Filtros com múltiplos níveis de refinamento
+- Estruturas organizacionais hierárquicas com seleção em árvore
+
+## Quando não usar
+
+- Para seleção de itens simples sem hierarquia — use `Checkbox` individual ou um grupo de checkboxes
+- Para seleção única em uma lista — use `RadioButton` ou `RadioButtonGroup`
+- Quando os dados não têm relação hierárquica entre si
+
+## Instalação
+
+```typescript
+import { CheckboxListModule } from '@seniorsistemas/angular-components/checkbox-list';
+
+@NgModule({
+  imports: [CheckboxListModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<form [formGroup]="form">
+  <s-checkbox-list [data]="estrutura" formControlName="selecao"></s-checkbox-list>
+</form>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `data` | `CheckboxListData` | — | **sim** | Estrutura de dados da árvore de checkboxes |
+
+### Tipos
+
+```typescript
+interface CheckboxListData {
+  label: string;                     // Texto do checkbox (obrigatório)
+  children?: CheckboxListData[];     // Filhos da hierarquia (opcional)
+  renderType?: 'inline' | 'block';  // Layout dos filhos — padrão: 'inline'
+}
+
+interface CheckboxListState {
+  checked: boolean;                  // Se o nó está marcado
+  indeterminate?: boolean;           // Se o nó está em estado parcial
+  disabled?: boolean;                // Se o nó está desabilitado
+  children?: CheckboxListChildren;   // Estado dos filhos (chave = label do filho)
+}
+
+type CheckboxListChildren = Record<string, CheckboxListState>;
+```
+
+## Exemplos
+
+### Lista simples com pai e filhos
+
+```typescript
+// Component
+estrutura: CheckboxListData = {
+  label: 'Opções',
+  children: [
+    { label: 'Opção 1' },
+    { label: 'Opção 2' },
+    { label: 'Opção 3' },
+  ],
+};
+
+form = new FormGroup({
+  selecao: new FormControl(null),
+});
+```
+
+```html
+<form [formGroup]="form">
+  <s-checkbox-list [data]="estrutura" formControlName="selecao"></s-checkbox-list>
+</form>
+```
+
+### Com estado inicial (todos marcados)
+
+```typescript
+estadoInicial: CheckboxListState = {
+  checked: true,
+  children: {
+    'Opção 1': { checked: true, children: {} },
+    'Opção 2': { checked: true, children: {} },
+    'Opção 3': { checked: true, children: {} },
+  },
+};
+
+form = new FormGroup({
+  selecao: new FormControl(this.estadoInicial),
+});
+```
+
+### Hierarquia de dois níveis
+
+```typescript
+estrutura: CheckboxListData = {
+  label: 'Categorias',
+  children: [
+    {
+      label: 'Frutas',
+      children: [{ label: 'Maçã' }, { label: 'Banana' }, { label: 'Laranja' }],
+    },
+    {
+      label: 'Verduras',
+      children: [{ label: 'Alface' }, { label: 'Espinafre' }],
+    },
+  ],
+};
+```
+
+### Com itens desabilitados
+
+```typescript
+estadoComDesabilitados: CheckboxListState = {
+  checked: false,
+  indeterminate: true,
+  children: {
+    'Opção 1': { checked: true, disabled: true, children: {} },
+    'Opção 2': { checked: false, children: {} },
+    'Opção 3': { checked: true, disabled: true, children: {} },
+  },
+};
+```
+
+## Acessibilidade
+
+- Cada checkbox recebe `role="checkbox"` com `aria-checked` correto (incluindo `"mixed"` para indeterminado)
+- Navegação por **Tab** entre checkboxes; **Space** para marcar/desmarcar
+- A propagação automática de estados pai/filho é refletida nos atributos ARIA em tempo real
+
+## Componentes relacionados
+
+- [`Checkbox`](../checkbox/README.md) — checkbox individual sem hierarquia, para casos simples

package/chips/README.md

@@ -0,0 +1,152 @@
+# Chips
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente para entrada de múltiplos valores em formato de chips/tags removíveis. Permite adicionar e remover itens de texto livremente, com suporte a limite de itens, prevenção de duplicatas, filtro de teclas e template personalizado. Implementa `ControlValueAccessor` para uso em formulários Angular.
+
+## Quando usar
+
+- Tags ou palavras-chave editáveis em formulários
+- Campo de destinatários de e-mail com múltiplos endereços
+- Filtros de busca onde o usuário adiciona múltiplos termos
+- Listas de valores editáveis onde cada item pode ser removido individualmente
+
+## Quando não usar
+
+- Para exibir chips não editáveis (somente leitura) — use `Badge` ou `TokenList`
+- Para seleção de opções de uma lista predefinida com busca — use `Autocomplete` com `multiple: true`
+- Quando apenas um valor é esperado — use `Input` simples
+
+## Instalação
+
+```typescript
+import { ChipsModule } from '@seniorsistemas/angular-components/chips';
+
+@NgModule({
+  imports: [ChipsModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-chips placeholder="Adicionar tag..." [(value)]="tags" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `value` | `string[] \| any[]` | `[]` | não | Lista de chips exibidos |
+| `placeholder` | `string` | `undefined` | não | Texto de placeholder do campo |
+| `field` | `string` | `''` | não | Chave do objeto para exibição quando `value` é array de objetos |
+| `disabled` | `boolean` | `false` | não | Desabilita adição e remoção de chips |
+| `max` | `number` | `Infinity` | não | Número máximo de chips permitidos |
+| `maxLength` | `number` | `Infinity` | não | Comprimento máximo do texto de cada chip |
+| `allowDuplicated` | `boolean` | `true` | não | Permite chips com valor duplicado |
+| `caseSensitiveDuplication` | `boolean` | `false` | não | Distingue maiúsculas na verificação de duplicatas |
+| `addOnTab` | `boolean` | `true` | não | Adiciona chip ao pressionar Tab |
+| `addOnBlur` | `boolean` | `true` | não | Adiciona chip ao perder o foco |
+| `separator` | `string` | `''` | não | Caractere que confirma adição de chip ao ser digitado |
+| `autofocus` | `boolean` | `false` | não | Foca automaticamente o campo ao renderizar |
+| `infoLabel` | `string` | `''` | não | Texto informativo exibido abaixo do campo |
+| `keyFilter` | `RegExp \| KeyFilterPattern` | `undefined` | não | Filtro de teclas para restringir caracteres aceitos |
+| `showTooltip` | `boolean` | `true` | não | Exibe tooltip em chips com texto truncado |
+| `maxLengthRenderWithoutTooltip` | `number` | `20` | não | Caracteres exibidos antes de truncar o chip |
+| `inputId` | `string` | `chips-{hash}` | não | ID do `<input>` interno |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `added` | `EventEmitter<ChipAddEvent>` | Emitido quando um chip é adicionado |
+| `removed` | `EventEmitter<ChipRemoveEvent>` | Emitido quando um chip é removido |
+| `chipClicked` | `EventEmitter<ChipClickEvent>` | Emitido ao clicar em um chip |
+| `focused` | `EventEmitter<FocusEvent>` | Emitido quando o campo recebe foco |
+| `focusLost` | `EventEmitter<FocusEvent>` | Emitido quando o campo perde foco |
+| `valueChange` | `EventEmitter<string[] \| any[]>` | Emitido quando a lista de chips é alterada |
+
+### Tipos
+
+```typescript
+type ChipAddEvent = { value: any };
+type ChipRemoveEvent = { originalEvent: Event; value: any };
+type ChipClickEvent = { originalEvent: Event; value: any };
+```
+
+## Exemplos
+
+### Tags básicas
+
+```html
+<s-chips
+  placeholder="Adicione países..."
+  [value]="['Brasil', 'Argentina', 'Chile']">
+</s-chips>
+```
+
+### Sem duplicatas, com separador por vírgula
+
+```html
+<s-chips
+  placeholder="Digite emails separados por vírgula..."
+  [value]="emails"
+  [allowDuplicated]="false"
+  separator=","
+  infoLabel="Adicione múltiplos emails separados por vírgula">
+</s-chips>
+```
+
+### Com limite de itens
+
+```html
+<s-chips
+  placeholder="Máximo 5 tags..."
+  [value]="tags"
+  [max]="5"
+  infoLabel="Você pode adicionar até 5 tags">
+</s-chips>
+```
+
+### Com objetos complexos
+
+```html
+<s-chips
+  placeholder="Adicione países..."
+  [value]="paises"
+  field="nome">
+</s-chips>
+```
+
+```typescript
+paises = [
+  { id: 1, nome: 'Brasil', codigo: 'BR' },
+  { id: 2, nome: 'Argentina', codigo: 'AR' },
+];
+```
+
+### Reagindo a eventos
+
+```html
+<s-chips
+  [value]="tags"
+  (added)="onAdicionado($event)"
+  (removed)="onRemovido($event)"
+  (chipClicked)="onCliqueChip($event)">
+</s-chips>
+```
+
+## Acessibilidade
+
+- O campo de entrada é um `<input>` acessível via teclado
+- **Enter** confirma adição do chip; **Tab** também pode confirmar (configurável)
+- Os botões de remoção de cada chip são acessíveis via teclado
+- Use `aria-label` ou `<label for="...">` apontando para `inputId` para associar um rótulo ao campo
+
+## Componentes relacionados
+
+- [`Autocomplete`](../autocomplete/README.md) com `multiple: true` — quando os chips devem ser selecionados de uma lista predefinida com busca
+- [`Badge`](../badge/README.md) — para exibir chips não editáveis (somente leitura)

package/code-editor/README.md

@@ -0,0 +1,149 @@
+# CodeEditor
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de editor de código com syntax highlighting, construído sobre CodeMirror 6. Suporta configuração de linguagem e tema via `editorOptions`. Implementa `ControlValueAccessor` para integração com Angular Forms.
+
+## Quando usar
+
+- Edição de configurações em formato JSON
+- Campos de script ou regra com syntax highlighting (ex.: cálculo tributário)
+- Formulários com área de código onde a validação de sintaxe é necessária
+- Visualização e edição de payloads de API ou configurações avançadas
+
+## Quando não usar
+
+- Para entrada de texto simples sem necessidade de syntax highlighting — use `TextArea`
+- Para exibição de código sem edição — use um bloco `<pre><code>` estilizado
+- Quando o ambiente não suporta o carregamento assíncrono do CodeMirror
+
+## Instalação
+
+```typescript
+import { CodeEditorModule } from '@seniorsistemas/angular-components/code-editor';
+
+@NgModule({
+  imports: [CodeEditorModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-code-editor
+  [editorOptions]="{ language: 'Json', theme: 'SDSLight' }"
+  [(code)]="codigoAtual"
+  (codeChange)="onAlteracao($event)">
+</s-code-editor>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `editorOptions` | `EditorOptions` | `undefined` | não | Configurações do editor (linguagem, tema) |
+| `code` | `string` | `''` | não | Conteúdo textual do editor (two-way binding via `[(code)]`) |
+| `isCodeValid` | `boolean` | `false` | não | Indica se o código atual é válido (two-way binding via `[(isCodeValid)]`) |
+| `payload` | `string` | `undefined` | não | Payload adicional para contexto de autocompletar ou validações específicas |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `codeChange` | `EventEmitter<string>` | Emitido a cada alteração no conteúdo |
+| `isCodeValidChange` | `EventEmitter<boolean>` | Emitido quando o estado de validade muda |
+| `onComponentFinishLoad` | `EventEmitter<void>` | Emitido quando o editor termina de carregar |
+| `onCodeChange` | `EventEmitter<string>` | **Descontinuado** — use `codeChange` em novos projetos |
+
+### Tipos
+
+```typescript
+interface EditorOptions {
+  language?: Languages; // 'Json' | 'TaxCalculation'
+  theme?: Themes;       // 'SDSLight'
+}
+
+enum Languages {
+  TaxCalculation = 'TaxCalculation',
+  Json = 'Json',
+}
+
+enum Themes {
+  SDSLight = 'SDSLight',
+}
+```
+
+## Exemplos
+
+### Editor JSON
+
+```html
+<div style="height: 300px;">
+  <s-code-editor
+    [editorOptions]="{ language: 'Json', theme: 'SDSLight' }"
+    [(code)]="json"
+    [(isCodeValid)]="jsonValido"
+    (codeChange)="onAlteracao($event)">
+  </s-code-editor>
+</div>
+```
+
+### Editor de cálculo tributário
+
+```html
+<div style="height: 300px;">
+  <s-code-editor
+    [editorOptions]="{ language: 'TaxCalculation', theme: 'SDSLight' }"
+    [(code)]="regra"
+    (codeChange)="onAlteracao($event)">
+  </s-code-editor>
+</div>
+```
+
+### Integrado com Reactive Forms
+
+```html
+<form [formGroup]="form">
+  <div style="height: 300px;">
+    <s-code-editor
+      formControlName="script"
+      [editorOptions]="editorOptions"
+      (codeChange)="onAlteracao($event)">
+    </s-code-editor>
+  </div>
+</form>
+```
+
+```typescript
+form = new FormGroup({
+  script: new FormControl(''),
+});
+
+editorOptions: EditorOptions = {
+  language: Languages.Json,
+  theme: Themes.SDSLight,
+};
+```
+
+### Reagindo ao carregamento do editor
+
+```html
+<s-code-editor
+  [editorOptions]="editorOptions"
+  [(code)]="codigo"
+  (onComponentFinishLoad)="editorPronto()">
+</s-code-editor>
+```
+
+## Acessibilidade
+
+- O editor é construído sobre CodeMirror 6, que oferece suporte a navegação por teclado dentro do código
+- Use `aria-label` ou um `<label>` associado via `id` para descrever o editor ao usuário
+- O campo aceita foco via Tab e suporta a maioria dos atalhos de edição de texto padrão do sistema operacional
+
+## Componentes relacionados
+
+- [`TextArea`](../text-area/README.md) — área de texto simples sem syntax highlighting, para casos onde formatação de código não é necessária

package/collapse-link/README.md

@@ -0,0 +1,128 @@
+# CollapseLink
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de link de expansão/recolhimento com animação suave. Exibe um botão que alterna entre recolhido e expandido, controlando a visibilidade do conteúdo projetado via `ng-content`. Suporta labels personalizados para cada estado e controle programático.
+
+## Quando usar
+
+- Seções de conteúdo extenso que podem ser ocultadas por padrão (ex.: descrição longa, detalhes adicionais)
+- FAQ com respostas que expandem ao clicar
+- Filtros avançados que ficam ocultos até o usuário solicitar
+- Formulários com campos opcionais agrupados e recolhíveis
+
+## Quando não usar
+
+- Para painéis com cabeçalho independente e múltiplos itens — use `Accordion`
+- Para ocultar/exibir conteúdo sem animação ou sem um botão de toggle visível
+- Quando o conteúdo nunca deve ser recolhido
+
+## Instalação
+
+```typescript
+import { CollapseLinkModule } from '@seniorsistemas/angular-components/collapse-link';
+
+@NgModule({
+  imports: [CollapseLinkModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-collapse-link>
+  <p>Conteúdo que será expandido ou recolhido ao clicar no link.</p>
+</s-collapse-link>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `buttonId` | `string` | `s-collapse-button-{n}` | não | ID do botão de toggle (gerado automaticamente se omitido) |
+| `expandedLabel` | `string` | `'Mostrar menos'` | não | Texto exibido quando o conteúdo está expandido |
+| `collapsedLabel` | `string` | `'Mostrar mais'` | não | Texto exibido quando o conteúdo está recolhido |
+| `disabled` | `boolean` | `false` | não | Desabilita o botão impedindo a alternância de estado |
+| `collapse` | `boolean` | `true` | não | Estado atual — `true` = recolhido, `false` = expandido |
+
+## Exemplos
+
+### Padrão (recolhido inicialmente)
+
+```html
+<s-collapse-link>
+  <p>Este conteúdo fica oculto até o usuário clicar em "Mostrar mais".</p>
+  <p>Pode conter qualquer conteúdo HTML projetado via ng-content.</p>
+</s-collapse-link>
+```
+
+### Iniciando expandido
+
+```html
+<s-collapse-link [collapse]="false">
+  <p>Este conteúdo já aparece visível ao carregar a página.</p>
+</s-collapse-link>
+```
+
+### Com labels personalizados
+
+```html
+<s-collapse-link
+  collapsedLabel="Ver detalhes completos"
+  expandedLabel="Ocultar detalhes">
+  <p>Detalhes adicionais do produto...</p>
+</s-collapse-link>
+```
+
+### Desabilitado
+
+```html
+<s-collapse-link [disabled]="true" [collapse]="false">
+  <p>Conteúdo visível, mas o botão não permite recolher.</p>
+</s-collapse-link>
+```
+
+### Controle programático
+
+```html
+<button (click)="recolhido = !recolhido">Alternar externamente</button>
+
+<s-collapse-link [collapse]="recolhido">
+  <p>Conteúdo controlado pelo componente pai.</p>
+</s-collapse-link>
+```
+
+```typescript
+recolhido = true;
+```
+
+### Em formulário com campos opcionais
+
+```html
+<form [formGroup]="form">
+  <s-collapse-link collapsedLabel="Mostrar campos opcionais" expandedLabel="Ocultar campos opcionais">
+    <div formGroupName="opcionais">
+      <label for="apelido">Apelido</label>
+      <input id="apelido" formControlName="apelido" />
+
+      <label for="site">Site pessoal</label>
+      <input id="site" formControlName="site" />
+    </div>
+  </s-collapse-link>
+</form>
+```
+
+## Acessibilidade
+
+- O botão de toggle possui `aria-expanded` refletindo o estado atual (`true` quando expandido)
+- O botão recebe `aria-controls` apontando para a região do conteúdo projetado
+- Totalmente acessível por teclado: **Tab** para focar o botão, **Enter** ou **Space** para alternar
+- Quando `disabled`, o botão recebe o atributo `disabled` nativo, impedindo interação por teclado e mouse
+- A animação de 400ms usa `cubic-bezier` para transição suave sem comprometer a acessibilidade
+
+## Componentes relacionados
+
+- [`Accordion`](../accordion/README.md) — quando há múltiplos painéis com cabeçalhos independentes e suporte a abertura múltipla ou exclusiva