ngx-opalbytes-components 1.25.1 → 1.27.0

package/README.md

@@ -238,12 +238,15 @@ src/
         |   ├── base-input/
         |   ├── base-time-range/
         |   ├── base-toggle/
+        |   ├── checkbox/
         |   ├── drop-down/
         |   ├── footer/
         |   ├── kpi/
         |   ├── links-button/
         |   ├── paginator/
+        |   ├── radio/
         |   ├── skeleton/
+        |   ├── slide-toggle/
         |   ├── stepper/
         |   ├── tab-group/
         |   ├── tab-panel/
@@ -928,6 +931,500 @@ Um componente de alternância (toggle switch) que funciona com `ngModel` ou `for
 
 ---
 
+### `CaoSlideToggleComponent`
+
+Um switch (slide toggle) acessível e customizável, com suporte a `ngModel` e formulários reativos via `ControlValueAccessor`. O visual é construído com trilho e thumb animados, sem depender do Material em runtime.
+
+**Seletor:** `<cao-slide-toggle>`
+
+**Interface `ICaoSlideToggleChangeEvent`**
+
+| Propriedade | Tipo | Descrição |
+| --- | --- | --- |
+| `checked` | `boolean` | Novo estado do switch. |
+| `source` | `CaoSlideToggleComponent` | Instância que originou o evento. |
+
+**Atributos (Inputs)**
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `checked` | `boolean` | `false` | Estado inicial/atual do switch. |
+| `isDisabled` | `boolean` | `false` | Desabilita o componente. |
+| `disabled` | `boolean` | `false` | Alias de `isDisabled` (mesmo comportamento). |
+| `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 switch. |
+| `name` | `string` | `''` | Atributo `name` do input nativo. |
+| `id` | `string` | `''` | Atributo `id` do input nativo. |
+| `ariaLabel` | `string` | `''` | Atributo `aria-label` do switch. |
+| `required` | `boolean` | `false` | Marca o input como obrigatório. |
+| `dataCy` | `string` | `''` | Atributo para testes E2E com Cypress. |
+| `trackColor` | `string` | `#d1d5db` | Cor do trilho desligado. |
+| `trackCheckedColor` | `string` | `#4f46e5` | Cor do trilho ligado. |
+| `thumbColor` | `string` | `#ffffff` | Cor do thumb desligado. |
+| `thumbCheckedColor` | `string` | `#ffffff` | Cor do thumb ligado. |
+| `disabledTrackColor` | `string` | `#e5e7eb` | Cor do trilho desabilitado. |
+| `disabledThumbColor` | `string` | `#f3f4f6` | Cor do thumb 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. |
+| `trackWidth` | `string` | `36px` | Largura do trilho. |
+| `trackHeight` | `string` | `20px` | Altura do trilho. |
+| `thumbSize` | `string` | `16px` | Tamanho do thumb. |
+| `animationDuration` | `string` | `200ms` | Duração da animação. |
+| `thumbIcon` | `string` | `''` | Ícone exibido no thumb desligado. Pode ser um nome Lucide ou uma URL de imagem. |
+| `thumbCheckedIcon` | `string` | `''` | Ícone exibido no thumb ligado. Se vazio, usa `thumbIcon`. |
+| `isLucideThumbIcon` | `boolean` | `false` | Interpreta os ícones do thumb como nomes Lucide. Quando `false`, usa `<img>`. |
+| `thumbIconColor` | `string` | `''` | Cor do ícone Lucide no estado desligado. |
+| `thumbCheckedIconColor` | `string` | `''` | Cor do ícone Lucide no estado ligado. Se vazio, usa `thumbIconColor`. |
+| `thumbIconSize` | `string \| number` | `12` | Tamanho do ícone do thumb. |
+| `thumbIconStrokeWidth` | `string \| number` | `2` | Espessura do traço do ícone Lucide. |
+
+**Eventos (Outputs)**
+
+| Evento | Tipo | Descrição |
+| --- | --- | --- |
+| `checkedChange` | `EventEmitter<boolean>` | Emitido quando o estado muda. |
+| `toggleChange` | `EventEmitter<ICaoSlideToggleChangeEvent>` | 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)` | Define o estado programaticamente, se não estiver desabilitado. |
+| `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-slide-toggle-track` | `#d1d5db` | Cor do trilho desligado. |
+| `--cao-slide-toggle-track-checked` | `#4f46e5` | Cor do trilho ligado. |
+| `--cao-slide-toggle-thumb` | `#ffffff` | Cor do thumb desligado. |
+| `--cao-slide-toggle-thumb-checked` | `#ffffff` | Cor do thumb ligado. |
+| `--cao-slide-toggle-track-disabled` | `#e5e7eb` | Cor do trilho desabilitado. |
+| `--cao-slide-toggle-thumb-disabled` | `#f3f4f6` | Cor do thumb desabilitado. |
+| `--cao-slide-toggle-label` | `#111827` | Cor do label. |
+| `--cao-slide-toggle-label-disabled` | `#9ca3af` | Cor do label desabilitado. |
+| `--cao-slide-toggle-focus-ring` | `rgba(79, 70, 229, 0.35)` | Cor do anel de foco. |
+| `--cao-slide-toggle-track-width` | `36px` | Largura do trilho. |
+| `--cao-slide-toggle-track-height` | `20px` | Altura do trilho. |
+| `--cao-slide-toggle-thumb-size` | `16px` | Tamanho do thumb. |
+| `--cao-slide-toggle-duration` | `200ms` | Duração da animação. |
+
+**Exemplo com `ngModel`:**
+
+```html
+<cao-slide-toggle
+  label="Ativar notificações"
+  [(ngModel)]="notificacoesAtivas"
+  (checkedChange)="onCheckedChange($event)">
+</cao-slide-toggle>
+```
+
+**Exemplo com formulário reativo e cores customizadas:**
+
+```html
+<cao-slide-toggle
+  label="Modo escuro"
+  [formControl]="modoEscuro"
+  trackCheckedColor="#16a34a"
+  thumbCheckedColor="#ffffff"
+  trackColor="#fca5a5"
+  labelColor="#166534"
+  labelPosition="before">
+</cao-slide-toggle>
+```
+
+**Exemplo com ícones Lucide no thumb:**
+
+```html
+<cao-slide-toggle
+  label="Notificações"
+  [(ngModel)]="notificacoesAtivas"
+  thumbIcon="x"
+  thumbCheckedIcon="check"
+  [isLucideThumbIcon]="true"
+  thumbIconColor="#6b7280"
+  thumbCheckedIconColor="#16a34a"
+  [thumbIconSize]="12"
+  [thumbIconStrokeWidth]="2.5">
+</cao-slide-toggle>
+```
+
+**Exemplo com imagem no thumb:**
+
+```html
+<cao-slide-toggle
+  label="Ícone customizado"
+  [(ngModel)]="ativo"
+  thumbIcon="assets/icone-desligado.svg"
+  thumbCheckedIcon="assets/icone-ligado.svg"
+  [isLucideThumbIcon]="false"
+  [thumbIconSize]="10">
+</cao-slide-toggle>
+```
+
+Se `thumbCheckedIcon` não for informado, o componente reutiliza `thumbIcon` no estado ligado.
+
+**Exemplo desabilitado programaticamente:**
+
+```typescript
+@ViewChild(CaoSlideToggleComponent)
+slideToggle!: CaoSlideToggleComponent;
+
+bloquear(): void {
+  this.slideToggle.disable();
+}
+
+liberar(): void {
+  this.slideToggle.enable();
+}
+```
+
+**Observações:**
+
+- Usa um `input type="checkbox"` com `role="switch"`, com suporte a `Espaço`, `Enter`, foco visível e leitores de tela.
+- Funciona com `ngModel`, `formControlName` e `FormControl.disable()`.
+- As cores podem ser definidas por inputs ou por CSS custom properties.
+
+---
+
+### `CaoRadioGroupComponent` e `CaoRadioButtonComponent`
+
+Sistema de radio buttons no estilo do Material, com navegação por teclado, suporte a formulários e customização de cores. O grupo é o dono do valor selecionado; os botões apenas declaram seu `value` e o label.
+
+**Seletores:**
+- `<cao-radio-group>` — container do grupo
+- `<cao-radio-button>` — opção individual (deve ficar dentro do grupo)
+
+**Interface `ICaoRadioChangeEvent`**
+
+| Propriedade | Tipo | Descrição |
+| --- | --- | --- |
+| `value` | `unknown` | Valor recém-selecionado. |
+| `source` | `CaoRadioButtonComponent` | Botão que originou o evento. |
+
+#### Atributos do `CaoRadioGroupComponent` (Inputs)
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `value` | `any` | `undefined` | Valor selecionado. Também funciona via `ngModel`/`formControlName`. |
+| `name` | `string` | gerado automaticamente | Nome compartilhado pelos inputs nativos do grupo. |
+| `isDisabled` | `boolean` | `false` | Desabilita todas as opções. |
+| `disabled` | `boolean` | `false` | Alias de `isDisabled`. |
+| `required` | `boolean` | `false` | Marca o grupo como obrigatório. |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Direção do layout. |
+| `labelPosition` | `'before' \| 'after'` | `'after'` | Posição padrão dos labels. |
+| `color` | `string` | `#4f46e5` | Cor da opção selecionada (borda e ponto). |
+| `unselectedColor` | `string` | `#6b7280` | Cor da borda da opção não selecionada. |
+| `disabledColor` | `string` | `#d1d5db` | Cor da opção desabilitada. |
+| `labelColor` | `string` | `#111827` | Cor dos labels. |
+| `disabledLabelColor` | `string` | `#9ca3af` | Cor dos labels desabilitados. |
+| `focusRingColor` | `string` | `rgba(79, 70, 229, 0.35)` | Cor do anel de foco. |
+| `size` | `string` | `20px` | Tamanho do círculo. |
+| `animationDuration` | `string` | `200ms` | Duração das animações. |
+| `gap` | `string` | `8px` | Espaçamento entre as opções. |
+| `compareWith` | `(option, value) => boolean` | `===` | Comparador customizado de valores. |
+| `ariaLabel` | `string` | `''` | Atributo `aria-label` do grupo. |
+| `ariaLabelledBy` | `string` | `''` | Atributo `aria-labelledby` do grupo. |
+| `dataCy` | `string` | `''` | Atributo para testes E2E. |
+
+#### Eventos do `CaoRadioGroupComponent` (Outputs)
+
+| Evento | Tipo | Descrição |
+| --- | --- | --- |
+| `valueChange` | `EventEmitter<any>` | Emitido quando o valor selecionado muda. |
+| `selectionChange` | `EventEmitter<ICaoRadioChangeEvent>` | Emitido com o valor e o botão de origem. |
+
+#### Métodos do `CaoRadioGroupComponent`
+
+| Método | Descrição |
+| --- | --- |
+| `enable()` | Habilita o grupo e todas as opções. |
+| `disable()` | Desabilita o grupo e todas as opções. |
+| `isValueSelected(value)` | Verifica se um valor está selecionado usando `compareWith`. |
+| `markAsTouched()` | Marca o controle como tocado. |
+| `writeValue(value)` | Implementação de `ControlValueAccessor`. |
+| `setDisabledState(isDisabled)` | Implementação de `ControlValueAccessor`. |
+
+#### Atributos do `CaoRadioButtonComponent` (Inputs)
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `value` | `any` | `undefined` | **Obrigatório.** Valor único da opção dentro do grupo. |
+| `label` | `string` | `''` | Texto do label. Também aceita conteúdo projetado. |
+| `isDisabled` | `boolean` | `false` | Desabilita apenas esta opção. |
+| `disabled` | `boolean` | `false` | Alias de `isDisabled`. |
+| `labelPosition` | `'before' \| 'after'` | herda do grupo | Posição do label desta opção. |
+| `name` | `string` | herda do grupo | Sobrescreve o nome do grupo para esta opção. |
+| `id` | `string` | gerado automaticamente | Atributo `id` do input. |
+| `ariaLabel` | `string` | `''` | Atributo `aria-label` da opção. |
+| `ariaLabelledBy` | `string` | `''` | Atributo `aria-labelledby` da opção. |
+| `dataCy` | `string` | `''` | Atributo para testes E2E. |
+| `color` | `string` | herda do grupo | Cor da opção selecionada. |
+| `unselectedColor` | `string` | herda do grupo | Cor da borda não selecionada. |
+| `disabledColor` | `string` | herda do grupo | Cor da opção desabilitada. |
+| `labelColor` | `string` | herda do grupo | Cor do label. |
+| `disabledLabelColor` | `string` | herda do grupo | Cor do label desabilitado. |
+| `focusRingColor` | `string` | herda do grupo | Cor do anel de foco. |
+| `size` | `string` | herda do grupo | Tamanho do círculo. |
+| `animationDuration` | `string` | herda do grupo | Duração das animações. |
+
+#### Métodos do `CaoRadioButtonComponent`
+
+| Método | Descrição |
+| --- | --- |
+| `select()` | Seleciona a opção no grupo, se estiver habilitada. |
+| `enable()` | Habilita apenas esta opção. |
+| `disable()` | Desabilita apenas esta opção. |
+
+**CSS Custom Properties**
+
+| Propriedade | Padrão | Descrição |
+| --- | --- | --- |
+| `--cao-radio-color` | `#4f46e5` | Cor da opção selecionada. |
+| `--cao-radio-unselected` | `#6b7280` | Cor da borda não selecionada. |
+| `--cao-radio-disabled` | `#d1d5db` | Cor da opção desabilitada. |
+| `--cao-radio-label` | `#111827` | Cor do label. |
+| `--cao-radio-label-disabled` | `#9ca3af` | Cor do label desabilitado. |
+| `--cao-radio-focus-ring` | `rgba(79, 70, 229, 0.35)` | Cor do anel de foco. |
+| `--cao-radio-size` | `20px` | Tamanho do círculo. |
+| `--cao-radio-duration` | `200ms` | Duração das animações. |
+| `--cao-radio-gap` | `8px` | Espaçamento entre opções. |
+
+**Exemplo com `ngModel`:**
+
+```html
+<cao-radio-group [(ngModel)]="planoSelecionado" ariaLabel="Escolha um plano">
+  <cao-radio-button value="basico" label="Básico"></cao-radio-button>
+  <cao-radio-button value="profissional" label="Profissional"></cao-radio-button>
+  <cao-radio-button value="empresarial" label="Empresarial"></cao-radio-button>
+</cao-radio-group>
+```
+
+**Exemplo com formulário reativo, layout horizontal e cores customizadas:**
+
+```html
+<cao-radio-group
+  [formControl]="periodo"
+  orientation="horizontal"
+  gap="16px"
+  color="#16a34a"
+  unselectedColor="#94a3b8"
+  labelColor="#166534">
+  <cao-radio-button value="manha" label="Manhã"></cao-radio-button>
+  <cao-radio-button value="tarde" label="Tarde"></cao-radio-button>
+  <cao-radio-button value="noite" label="Noite"></cao-radio-button>
+</cao-radio-group>
+```
+
+**Exemplo com disabled geral e por opção:**
+
+```html
+<cao-radio-group [(ngModel)]="opcao" [isDisabled]="formularioBloqueado">
+  <cao-radio-button value="a" label="Disponível"></cao-radio-button>
+  <cao-radio-button value="b" label="Indisponível" [isDisabled]="true"></cao-radio-button>
+</cao-radio-group>
+```
+
+**Exemplo com `compareWith` para valores objetos:**
+
+```html
+<cao-radio-group [(ngModel)]="usuarioSelecionado" [compareWith]="compararUsuarios">
+  @for (usuario of usuarios; track usuario.id) {
+    <cao-radio-button [value]="usuario" [label]="usuario.nome"></cao-radio-button>
+  }
+</cao-radio-group>
+```
+
+```typescript
+compararUsuarios(a: Usuario | null, b: Usuario | null): boolean {
+  return a?.id === b?.id;
+}
+```
+
+**Observações:**
+
+- Cada `<cao-radio-button>` deve estar dentro de um `<cao-radio-group>`.
+- O grupo usa `role="radiogroup"` e inputs nativos `type="radio"` com o mesmo `name`, garantindo navegação por setas, foco e leitores de tela.
+- `FormControl.disable()` desabilita o grupo inteiro, assim como `isDisabled`/`disabled`.
+- Cores e tamanhos podem ser definidos no grupo (herdados por todas as opções) ou individualmente em cada botão.
+- Métodos `enable()`/`disable()` permitem controlar o estado programaticamente.
+
+---
+
+### `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`.