ngx-opalbytes-components 1.26.0 → 1.28.0

package/README.md

@@ -232,12 +232,14 @@ src/
 └── lib/
     └── shared/
         └── components/
-        |   ├── autocomplete/
+        |   ├── accordion/
+        |   ├── accordion-item/
         |   ├── base-button/
         |   ├── base-icon/
         |   ├── base-input/
         |   ├── base-time-range/
         |   ├── base-toggle/
+        |   ├── checkbox/
         |   ├── drop-down/
         |   ├── footer/
         |   ├── kpi/
@@ -928,6 +930,205 @@ Um componente de alternância (toggle switch) que funciona com `ngModel` ou `for
 | `inputChange` | `EventEmitter<string>` | Emitido a cada mudança no input. |
 | `statusChanged` | `EventEmitter<CaoBaseToggleComponent>` | Emitido quando o toggle é alternado. |
 
+---
+### `CaoAccordionComponent` e `CaoAccordionItemComponent`
+
+Um accordion (painéis expansíveis) acessível e totalmente customizável, inspirado na API do `CdkAccordion`, mas **sem depender do `@angular/cdk`, do Angular Material ou de qualquer outra biblioteca externa** — usa apenas `@angular/core` e `@angular/common`. Cores, posições, textos e visibilidade são configuráveis por inputs ou por CSS custom properties. A animação de abrir/fechar é feita só com CSS e respeita `prefers-reduced-motion`.
+
+**Seletores:**
+- `<cao-accordion>` — container (controla modo único/múltiplo e o tema herdado pelos itens)
+- `<cao-accordion-item>` — painel individual (também pode ser usado isolado, como um cartão expansível)
+
+#### Atributos do `CaoAccordionComponent` (Inputs)
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `multi` | `boolean` | `false` | Permite vários itens expandidos ao mesmo tempo. No modo único, expandir um item recolhe os demais. |
+| `displayMode` | `'default' \| 'flat' \| 'separated'` | `'default'` | `default`: painéis unidos em um único contorno arredondado; `flat`: unidos, sem bordas laterais/cantos; `separated`: cada painel é um cartão separado por `gap`. |
+| `hideToggle` | `boolean` | `false` | Oculta o ícone de expandir/recolher em todos os itens. |
+| `isVisible` | `boolean` | `true` | Exibe ou oculta o accordion inteiro. |
+| `togglePosition` | `'before' \| 'after'` | `'after'` | Posição do ícone em relação ao texto do cabeçalho. |
+| `headerAlign` | `'start' \| 'center' \| 'end'` | `'start'` | Alinhamento do texto do cabeçalho. |
+| `contentAlign` | `'start' \| 'center' \| 'end'` | `'start'` | Alinhamento do texto do conteúdo. |
+| `headerBgColor` | `string` | `#ffffff` | Cor de fundo do cabeçalho. |
+| `headerTextColor` | `string` | `#111827` | Cor do texto do cabeçalho. |
+| `headerHoverBgColor` | `string` | `#f3f4f6` | Cor de fundo do cabeçalho ao passar o mouse. |
+| `headerActiveBgColor` | `string` | cor do cabeçalho | Cor de fundo do cabeçalho do item expandido. |
+| `activeColor` | `string` | `#4f46e5` | Cor do texto/ícone do cabeçalho do item expandido. |
+| `contentBgColor` | `string` | `#ffffff` | Cor de fundo do conteúdo. |
+| `contentTextColor` | `string` | `#374151` | Cor do texto do conteúdo. |
+| `borderColor` | `string` | `#e5e7eb` | Cor das bordas e divisórias. |
+| `disabledColor` | `string` | `#9ca3af` | Cor do texto de itens desabilitados. |
+| `focusRingColor` | `string` | `rgba(79, 70, 229, 0.35)` | Cor do anel de foco do teclado. |
+| `iconColor` | `string` | `currentColor` | Cor do ícone de expandir/recolher. |
+| `borderRadius` | `string` | `8px` | Raio da borda. |
+| `gap` | `string` | `8px` | Espaçamento entre os itens (modo `separated`). |
+| `headerPadding` | `string` | `12px 16px` | Padding do cabeçalho. |
+| `contentPadding` | `string` | `16px` | Padding do conteúdo. |
+| `animationDuration` | `string` | `250ms` | Duração da animação. |
+| `dataCy` | `string` | `''` | Atributo `data-cy` para testes E2E. |
+
+#### Métodos do `CaoAccordionComponent`
+
+| Método | Descrição |
+| --- | --- |
+| `openAll()` | Expande todos os itens. Só tem efeito quando `multi` está ativo. |
+| `closeAll()` | Recolhe todos os itens. |
+
+#### Atributos do `CaoAccordionItemComponent` (Inputs)
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `label` | `string` | `''` | Texto do cabeçalho. |
+| `description` | `string` | `''` | Texto secundário exibido abaixo do `label`. |
+| `expanded` | `boolean` | `false` | Estado de expansão. Suporta two-way binding: `[(expanded)]`. |
+| `isDisabled` | `boolean` | `false` | Desabilita a interação do usuário com o item. |
+| `isVisible` | `boolean` | `true` | Exibe ou oculta o item. |
+| `headingLevel` | `number` | `3` | Nível do heading (`aria-level`) do cabeçalho. |
+| `hideToggle` | `boolean` | herda do accordion | Oculta o ícone neste item. |
+| `togglePosition` | `'before' \| 'after'` | herda do accordion | Posição do ícone neste item. |
+| `headerAlign` | `'start' \| 'center' \| 'end'` | herda do accordion | Alinhamento do cabeçalho neste item. |
+| `headerBgColor` | `string` | herda do accordion | Cor de fundo do cabeçalho deste item. |
+| `headerTextColor` | `string` | herda do accordion | Cor do texto do cabeçalho deste item. |
+| `headerActiveBgColor` | `string` | herda do accordion | Cor de fundo do cabeçalho quando expandido. |
+| `activeColor` | `string` | herda do accordion | Cor do texto/ícone quando expandido. |
+| `contentBgColor` | `string` | herda do accordion | Cor de fundo do conteúdo. |
+| `contentTextColor` | `string` | herda do accordion | Cor do texto do conteúdo. |
+| `borderColor` | `string` | herda do accordion | Cor das bordas. |
+| `iconColor` | `string` | herda do accordion | Cor do ícone. |
+| `dataCy` | `string` | `''` | Atributo `data-cy` para testes E2E (veja abaixo). |
+
+#### Eventos do `CaoAccordionItemComponent` (Outputs)
+
+| Evento | Tipo | Descrição |
+| --- | --- | --- |
+| `opened` | `output<void>` | Emitido quando o item é expandido. |
+| `closed` | `output<void>` | Emitido quando o item é recolhido. |
+| `expandedChange` | `output<boolean>` | Emitido a cada mudança de estado (usado pelo `[(expanded)]`). |
+
+#### Métodos do `CaoAccordionItemComponent`
+
+| Método | Descrição |
+| --- | --- |
+| `toggle()` | Alterna o estado (ignorado se o item estiver desabilitado). |
+| `open()` | Expande o item. |
+| `close()` | Recolhe o item. |
+
+#### Projeção de conteúdo
+
+| Recurso | Descrição |
+| --- | --- |
+| Slot padrão (`<ng-content />`) | Conteúdo do painel. |
+| `[caoAccordionHeader]` | Conteúdo extra projetado no cabeçalho, abaixo do `label`/`description` (ex.: badges, status). |
+
+#### `data-cy` para testes E2E
+
+Ao informar `dataCy="faq"` em um item, são gerados automaticamente os seletores:
+
+| Elemento | Atributo |
+| --- | --- |
+| Item (host) | `data-cy="faq"` |
+| Botão do cabeçalho | `data-cy="faq-header"` |
+| Painel de conteúdo | `data-cy="faq-content"` |
+
+```typescript
+cy.get('[data-cy="faq-header"]').click();
+cy.get('[data-cy="faq-content"]').should('be.visible');
+```
+
+#### CSS Custom Properties
+
+Podem ser definidas globalmente, por accordion ou por item (têm precedência sobre os valores padrão, e os inputs equivalentes as definem automaticamente).
+
+| Propriedade | Padrão | Descrição |
+| --- | --- | --- |
+| `--cao-accordion-header-bg` | `#ffffff` | Fundo do cabeçalho. |
+| `--cao-accordion-header-text` | `#111827` | Texto do cabeçalho. |
+| `--cao-accordion-header-hover-bg` | `#f3f4f6` | Fundo do cabeçalho no hover. |
+| `--cao-accordion-header-active-bg` | `var(--cao-accordion-header-bg)` | Fundo do cabeçalho expandido. |
+| `--cao-accordion-active-color` | `#4f46e5` | Texto/ícone do cabeçalho expandido. |
+| `--cao-accordion-content-bg` | `#ffffff` | Fundo do conteúdo. |
+| `--cao-accordion-content-text` | `#374151` | Texto do conteúdo. |
+| `--cao-accordion-border-color` | `#e5e7eb` | Bordas e divisórias. |
+| `--cao-accordion-disabled-color` | `#9ca3af` | Texto desabilitado. |
+| `--cao-accordion-focus-ring` | `rgba(79, 70, 229, 0.35)` | Anel de foco. |
+| `--cao-accordion-icon-color` | `currentColor` | Cor do ícone. |
+| `--cao-accordion-radius` | `8px` | Raio da borda. |
+| `--cao-accordion-gap` | `8px` | Espaço entre itens (`separated`). |
+| `--cao-accordion-header-padding` | `12px 16px` | Padding do cabeçalho. |
+| `--cao-accordion-content-padding` | `16px` | Padding do conteúdo. |
+| `--cao-accordion-header-align` | `start` | Alinhamento do texto do cabeçalho. |
+| `--cao-accordion-content-align` | `start` | Alinhamento do texto do conteúdo. |
+| `--cao-accordion-duration` | `250ms` | Duração da animação. |
+
+**Exemplo básico:**
+
+```typescript
+import { Component } from '@angular/core';
+import { CaoAccordionComponent, CaoAccordionItemComponent } from 'ngx-opalbytes-components';
+
+@Component({
+  selector: 'app-faq',
+  imports: [CaoAccordionComponent, CaoAccordionItemComponent],
+  template: `
+    <cao-accordion dataCy="faq-accordion">
+      <cao-accordion-item label="Como funciona?" dataCy="faq-1" [expanded]="true">
+        Conteúdo da primeira pergunta.
+      </cao-accordion-item>
+      <cao-accordion-item label="Posso cancelar?" description="Sem multa" dataCy="faq-2">
+        Conteúdo da segunda pergunta.
+      </cao-accordion-item>
+    </cao-accordion>
+  `,
+})
+export class FaqComponent {}
+```
+
+**Exemplo com múltiplos itens abertos, cores, ícone antes do texto e controle externo:**
+
+```html
+<cao-accordion
+  #acc
+  [multi]="true"
+  displayMode="separated"
+  togglePosition="before"
+  headerAlign="center"
+  headerBgColor="#eef2ff"
+  headerTextColor="#312e81"
+  activeColor="#16a34a"
+  contentBgColor="#ffffff"
+  borderColor="#c7d2fe"
+  borderRadius="12px"
+  animationDuration="400ms"
+  dataCy="meu-accordion">
+
+  <cao-accordion-item label="Dados pessoais" [(expanded)]="dadosAbertos" (opened)="onAbriu()" (closed)="onFechou()">
+    ...
+  </cao-accordion-item>
+
+  <cao-accordion-item label="Pagamento" [isDisabled]="semPermissao" headerBgColor="#fef3c7">
+    <span caoAccordionHeader>Pendente</span>
+    ...
+  </cao-accordion-item>
+
+  <cao-accordion-item label="Somente admin" [isVisible]="ehAdmin" [hideToggle]="true">
+    ...
+  </cao-accordion-item>
+</cao-accordion>
+
+<cao-button buttonText="Abrir todos" (buttonClick)="acc.openAll()"></cao-button>
+<cao-button buttonText="Fechar todos" (buttonClick)="acc.closeAll()"></cao-button>
+```
+
+**Observações:**
+
+- Sem dependências externas: não usa `@angular/cdk`, `@angular/material`, `@lucide/angular` nem `ngx-mask`; o ícone é um SVG inline.
+- Acessibilidade: o cabeçalho é um `<button>` dentro de um `role="heading"`, com `aria-expanded`, `aria-controls` e painel `role="region"` com `aria-labelledby`. Painéis recolhidos ficam fora da ordem de tabulação e do leitor de tela.
+- Teclado: `Enter`/`Espaço` alternam o item; `↑`/`↓` movem o foco entre cabeçalhos; `Home`/`End` vão ao primeiro/último.
+- Itens definidos como `isDisabled` bloqueiam apenas a interação do usuário; `open()`, `close()` e `[expanded]` continuam funcionando programaticamente.
+- Os inputs do `<cao-accordion-item>` sobrescrevem os do `<cao-accordion>` apenas naquele item.
+- Fora de um `<cao-accordion>`, o item se comporta como um cartão expansível independente.
+
 ---
 
 ### `CaoSlideToggleComponent`
@@ -1256,6 +1457,174 @@ compararUsuarios(a: Usuario | null, b: Usuario | null): boolean {
 
 ---
 
+### `CaoCheckboxComponent`
+
+Um checkbox acessível e customizável no estilo do Material, com suporte a `ngModel` e formulários reativos via `ControlValueAccessor`. Possui os estados marcado, desmarcado e indeterminado, ícones customizáveis e cores configuráveis por inputs ou CSS custom properties. O visual é construído sobre um `input type="checkbox"` nativo oculto, sem depender do Angular Material em runtime.
+
+**Seletor:** `<cao-checkbox>`
+
+**Interface `ICaoCheckboxChangeEvent`**
+
+| Propriedade | Tipo | Descrição |
+| --- | --- | --- |
+| `checked` | `boolean` | Novo estado do checkbox. |
+| `source` | `CaoCheckboxComponent` | Instância que originou o evento. |
+
+**Atributos (Inputs)**
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `checked` | `boolean` | `false` | Estado inicial/atual do checkbox. |
+| `indeterminate` | `boolean` | `false` | Exibe o estado indeterminado (traço). Tem prioridade sobre `checked`. |
+| `isDisabled` | `boolean` | `false` | Desabilita o componente. |
+| `disabled` | `boolean` | `false` | Alias de `isDisabled` (mesmo comportamento). |
+| `required` | `boolean` | `false` | Marca o input nativo como obrigatório. |
+| `label` | `string` | `''` | Texto do label. Também aceita conteúdo projetado (`<ng-content>`). |
+| `labelPosition` | `'before' \| 'after'` | `'after'` | Posição do label em relação ao checkbox. |
+| `name` | `string` | `''` | Atributo `name` do input nativo. |
+| `id` | `string` | gerado automaticamente | Atributo `id` do input nativo. |
+| `ariaLabel` | `string` | `''` | Atributo `aria-label` do input. |
+| `ariaLabelledBy` | `string` | `''` | Atributo `aria-labelledby` do input. |
+| `dataCy` | `string` | `''` | Atributo para testes E2E com Cypress. |
+| `control` | `AbstractControl \| null` | `undefined` | O `FormControl` associado. Usado para exibir os estados de validação. |
+| `errorMessage` | `string` | `''` | Mensagem de erro. Quando preenchida, aplica o estilo inválido. |
+| `color` | `string` | `#4f46e5` | Cor de fundo/borda do checkbox marcado ou indeterminado. |
+| `uncheckedColor` | `string` | `#6b7280` | Cor da borda quando desmarcado. |
+| `disabledColor` | `string` | `#d1d5db` | Cor do checkbox desabilitado. |
+| `labelColor` | `string` | `#111827` | Cor do label. |
+| `disabledLabelColor` | `string` | `#9ca3af` | Cor do label desabilitado. |
+| `focusRingColor` | `string` | `rgba(79, 70, 229, 0.35)` | Cor do anel de foco. |
+| `size` | `string` | `20px` | Tamanho do checkbox. |
+| `borderRadius` | `string` | `4px` | Raio da borda do checkbox. |
+| `animationDuration` | `string` | `200ms` | Duração das animações. |
+| `checkedIcon` | `string` | `''` | Ícone exibido quando marcado. Se vazio, usa um check SVG padrão. |
+| `uncheckedIcon` | `string` | `''` | Ícone exibido quando desmarcado. Se vazio, nenhum ícone é exibido. |
+| `indeterminateIcon` | `string` | `''` | Ícone exibido no estado indeterminado. Se vazio, usa um traço SVG padrão. |
+| `isLucideIcon` | `boolean` | `false` | Interpreta os ícones como nomes Lucide. Quando `false`, usa `<img>` (URL ou data URI). |
+| `iconColor` | `string` | `''` | Cor dos ícones Lucide (fallback para todos os estados). |
+| `checkedIconColor` | `string` | `''` | Cor do ícone quando marcado. Se vazio, usa `iconColor`. |
+| `uncheckedIconColor` | `string` | `''` | Cor do ícone quando desmarcado. Se vazio, usa `iconColor`. |
+| `iconSize` | `string \| number` | `14` | Tamanho do ícone. Números são convertidos para `px`. |
+| `iconStrokeWidth` | `string \| number` | `2.5` | Espessura do traço dos ícones Lucide. |
+
+**Eventos (Outputs)**
+
+| Evento | Tipo | Descrição |
+| --- | --- | --- |
+| `checkedChange` | `EventEmitter<boolean>` | Emitido quando o estado marcado muda. |
+| `indeterminateChange` | `EventEmitter<boolean>` | Emitido quando o estado indeterminado muda. |
+| `checkboxChange` | `EventEmitter<ICaoCheckboxChangeEvent>` | Emitido com o novo estado e a origem. |
+
+**Métodos**
+
+| Método | Descrição |
+| --- | --- |
+| `toggle()` | Alterna o estado, se não estiver desabilitado. |
+| `setChecked(value: boolean, emit = true)` | Define o estado programaticamente e limpa `indeterminate`. Passe `false` em `emit` para não disparar os eventos. |
+| `setIndeterminate(value: boolean)` | Define o estado indeterminado. |
+| `enable()` | Habilita o componente. |
+| `disable()` | Desabilita o componente. |
+| `writeValue(value)` | Implementação de `ControlValueAccessor`. |
+| `setDisabledState(isDisabled)` | Implementação de `ControlValueAccessor`. |
+
+**CSS Custom Properties**
+
+| Propriedade | Padrão | Descrição |
+| --- | --- | --- |
+| `--cao-checkbox-color` | `#4f46e5` | Cor do checkbox marcado/indeterminado. |
+| `--cao-checkbox-unselected` | `#6b7280` | Cor da borda desmarcada. |
+| `--cao-checkbox-disabled` | `#d1d5db` | Cor do checkbox desabilitado. |
+| `--cao-checkbox-label` | `#111827` | Cor do label. |
+| `--cao-checkbox-label-disabled` | `#9ca3af` | Cor do label desabilitado. |
+| `--cao-checkbox-focus-ring` | `rgba(79, 70, 229, 0.35)` | Cor do anel de foco. |
+| `--cao-checkbox-size` | `20px` | Tamanho do checkbox. |
+| `--cao-checkbox-radius` | `4px` | Raio da borda. |
+| `--cao-checkbox-duration` | `200ms` | Duração das animações. |
+| `--cao-checkbox-icon-size` | `14px` | Tamanho do ícone. |
+| `--cao-checkbox-icon-color` | `#ffffff` | Cor do ícone. |
+
+**Exemplo com `ngModel`:**
+
+```html
+<cao-checkbox
+  label="Aceito os termos"
+  [(ngModel)]="aceitoTermos"
+  (checkedChange)="onCheckedChange($event)">
+</cao-checkbox>
+```
+
+**Exemplo com formulário reativo, validação e estado indeterminado:**
+
+```html
+<cao-checkbox
+  label="Selecionar todos"
+  [formControl]="selecionarTodos"
+  [indeterminate]="algunsSelecionados"
+  [control]="selecionarTodos"
+  errorMessage="Selecione ao menos uma opção">
+</cao-checkbox>
+```
+
+```typescript
+selecionarTodos = new FormControl(false, { validators: Validators.requiredTrue });
+algunsSelecionados = false;
+```
+
+**Exemplo com cores customizadas e label antes:**
+
+```html
+<cao-checkbox
+  label="Modo escuro"
+  labelPosition="before"
+  color="#16a34a"
+  uncheckedColor="#94a3b8"
+  labelColor="#166534"
+  size="24px"
+  borderRadius="6px">
+</cao-checkbox>
+```
+
+**Exemplo com ícones Lucide:**
+
+```html
+<cao-checkbox
+  label="Notificações"
+  [(ngModel)]="notificacoesAtivas"
+  checkedIcon="check"
+  indeterminateIcon="minus"
+  uncheckedIcon="x"
+  [isLucideIcon]="true"
+  iconColor="#6b7280"
+  checkedIconColor="#16a34a"
+  [iconSize]="16"
+  [iconStrokeWidth]="2.5">
+</cao-checkbox>
+```
+
+**Exemplo com imagem/data URI nos ícones:**
+
+```html
+<cao-checkbox
+  label="Ícone customizado"
+  [(ngModel)]="customizado"
+  checkedIcon="assets/icone-marcado.svg"
+  indeterminateIcon="assets/icone-indeterminado.svg"
+  [isLucideIcon]="false"
+  [iconSize]="12">
+</cao-checkbox>
+```
+
+**Observações:**
+
+- Usa um `input type="checkbox"` nativo oculto, mantendo clique no label, foco, navegação por teclado e suporte a leitores de tela.
+- O estado `indeterminate` tem prioridade visual sobre `checked`; ao alternar o checkbox, `indeterminate` é limpo e `indeterminateChange(false)` é emitido.
+- Funciona com `ngModel`, `formControlName` e `FormControl.disable()`.
+- Os estados `--invalid` e `--valid` são aplicados quando `control.touched` e o controle está inválido/válido; `errorMessage` também força o estilo inválido.
+- Para ícones Lucide, registre os ícones usados com `provideLucideIcons` (de `@lucide/angular`). Para imagens, informe uma URL ou data URI e mantenha `isLucideIcon` como `false`.
+- As cores e dimensões podem ser definidas por inputs ou sobrescritas via CSS custom properties.
+
+---
+
 ### `DropDown`
 Um menu suspenso (dropdown) com busca, que funciona com `ngModel` ou `formControlName`.