@dev-tcloud/tcloud-ui 6.19.0 → 6.19.1

package/docs/tcloud-ui-dropdown.md

@@ -4,6 +4,8 @@
 
 O componente `tcloud-ui-dropdown` é um componente de seleção versátil com suporte a opções customizáveis, two-way binding, detecção automática de viewport (desktop/mobile) e tooltip para textos elipsados. Implementa comportamento responsivo com menu dropdown em desktop e fullscreen em dispositivos móveis.
 
+Implementa a interface `ControlValueAccessor` do Angular, sendo compatível com **formulários reativos** (`formControl`, `formControlName`) e **template-driven** (`[(ngModel)]`), incluindo suporte a validadores e ao ciclo `touched`/`dirty`.
+
 ## Instalação
 
 Para utilizar o componente Dropdown, importe o módulo `TCloudUiModule`:
@@ -148,6 +150,110 @@ export class AdvancedDropdownComponent {
 }
 ```
 
+### Uso com Formulários Reativos (formControl / formControlName)
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+import { ReactiveFormsModule, FormBuilder, FormGroup, Validators } from '@angular/forms';
+
+@Component({
+  selector: 'app-reactive-dropdown',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule, ReactiveFormsModule],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()">
+      <tcloud-ui-dropdown
+        formControlName="status"
+        [options]="options"
+        label="Status"
+      ></tcloud-ui-dropdown>
+
+      <span *ngIf="form.get('status')?.invalid && form.get('status')?.touched">
+        Campo obrigatório
+      </span>
+
+      <button type="submit" [disabled]="form.invalid">Enviar</button>
+      <button type="button" (click)="form.disable()">Desabilitar formulário</button>
+      <button type="button" (click)="form.enable()">Habilitar formulário</button>
+    </form>
+  `
+})
+export class ReactiveDropdownComponent {
+  form: FormGroup;
+
+  options = [
+    { value: 'active',   displayValue: 'Ativo' },
+    { value: 'inactive', displayValue: 'Inativo' },
+    { value: 'pending',  displayValue: 'Pendente' },
+  ];
+
+  constructor(private fb: FormBuilder) {
+    this.form = this.fb.group({
+      status: [null, Validators.required],
+    });
+  }
+
+  onSubmit(): void {
+    if (this.form.valid) {
+      console.log(this.form.value); // { status: 'active' }
+    }
+  }
+}
+```
+
+> **Nota:** `form.disable()` / `form.enable()` propagam o estado para o componente via `setDisabledState`, sem interferir no input `[disabled]` externo.
+
+### Uso com Template-Driven Forms (ngModel)
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+import { FormsModule } from '@angular/forms';
+
+@Component({
+  selector: 'app-ngmodel-dropdown',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule, FormsModule],
+  template: `
+    <form #f="ngForm" (ngSubmit)="onSubmit(f)">
+      <tcloud-ui-dropdown
+        name="category"
+        [(ngModel)]="selectedCategory"
+        required
+        [options]="options"
+        label="Categoria"
+      ></tcloud-ui-dropdown>
+
+      <span *ngIf="f.controls['category']?.invalid && f.controls['category']?.touched">
+        Campo obrigatório
+      </span>
+
+      <button type="submit">Enviar</button>
+    </form>
+
+    <p>Valor atual: {{ selectedCategory }}</p>
+  `
+})
+export class NgModelDropdownComponent {
+  selectedCategory: any = null;
+
+  options = [
+    { value: 'tech',    displayValue: 'Tecnologia' },
+    { value: 'finance', displayValue: 'Finanças' },
+    { value: 'health',  displayValue: 'Saúde' },
+  ];
+
+  onSubmit(form: any): void {
+    if (form.valid) {
+      console.log(this.selectedCategory);
+    }
+  }
+}
+```
+
 ### Diferentes Tamanhos
 
 ```typescript
@@ -357,13 +463,18 @@ Quando um texto de opção é muito longo e sofre truncamento, o componente auto
 - **Hover**: Indica que o dropdown pode ser clicado
 - **Aberto (Desktop)**: Menu dropdown expandido
 - **Aberto (Mobile)**: Menu fullscreen exibido
-- **Desabilitado**: Dropdown indisponível para interação
+- **Desabilitado**: Dropdown indisponível para interação — ativado por `[disabled]="true"` ou por `form.disable()`
 - **Selecionado**: Opção com fundo destacado e ícone de check
+- **Touched**: Marcado como `touched` ao fechar o dropdown (compatível com validadores)
+- **Dirty**: Marcado como `dirty` ao selecionar uma opção via interação do usuário
 
 ## Notas de Implementação
 
-- O componente implementa OnInit e OnChanges para sincronização de valores
+- O componente implementa `OnInit` e `OnChanges` para sincronização de valores
 - Utiliza signals do Angular 16+ para reatividade
-- Suporta tanto `initialValue` (deprecated) quanto `value` (dois-way binding)
+- Suporta tanto `initialValue` (deprecated) quanto `value` (two-way binding)
 - O seletor CSS é sensível a eventos de clique no documento para fechar o dropdown
 - A largura padrão é 100% do elemento pai, podendo ser customizada
+- Implementa `ControlValueAccessor` — compatível com `formControl`, `formControlName` e `[(ngModel)]`
+- O estado `disabled` do formulário (`setDisabledState`) é gerenciado por um signal interno, sem sobrescrever o input `[disabled]` externo; ambos coexistem
+- `writeValue` não dispara `onChangeCallback`, evitando que o formulário seja marcado como `dirty` em atualizações programáticas (`patchValue`, `setValue`, `reset`)