@dev-tcloud/tcloud-ui 6.14.3 → 6.17.0

package/docs/tcloud-ui-datepicker.md

@@ -0,0 +1,186 @@
+# Datepicker
+
+## Características
+- Componente standalone de seleção de datas baseado em VanillaJS Datepicker.
+- Suporta modo inline (calendário exibido) e modo input (calendário em popup).
+- Suporta seleção de múltiplas datas com limite configurável.
+- Permite desabilitar dias da semana específicos e datas individuais.
+- Controle de intervalo de datas com minDate e maxDate.
+- Integração com ngModel (two-way binding) e ControlValueAccessor.
+- Detecção automática de layout (classic ou modern) via TCloudUiLayoutService.
+- Máscara automática no formato DD/MM/YYYY.
+- Eventos: `onChange` (mudança de seleção) e `onCheckDate` (verificação de datas em modo disabled).
+
+## Instalação
+```ts
+import { TCloudUiDatepickerComponent } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiDatepickerComponent],
+  template: `<tcloud-ui-datepicker [(ngModel)]="dateValue"></tcloud-ui-datepicker>`
+})
+export class ExampleComponent {
+  dateValue: string | undefined;
+}
+```
+
+## Propriedades (API)
+### Inputs
+| Nome | Tipo | Descrição | Valor Default |
+| --- | --- | --- | --- |
+| multiple | boolean | Permite seleção de múltiplas datas. | false |
+| maxNumberOfDates | number | Limite máximo de datas selecionáveis. 0 = sem limite. Requires `multiple=true`. | 0 |
+| daysOfWeekDisabled | number[] | Array de dias da semana desabilitados (0=Domingo até 6=Domingo). | [] |
+| minDate | string | Data mínima permitida no formato DD/MM/YYYY. | '' |
+| maxDate | string | Data máxima permitida no formato DD/MM/YYYY. | '' |
+| datesDisabled | string[] | Array de datas específicas desabilitadas no formato DD/MM/YYYY. | [] |
+| modeInput | boolean | Se true, exibe calendário em popup ao clicar em input. Se false, exibe calendário inline. | false |
+| useBorder | boolean | Se true, adiciona borda ao input no modeInput. | true |
+| childInputDateTime | boolean | Flag para uso em componentes filho tipo datepicker-time. | false |
+| startViewInMinDate | boolean | Inicia a visualização do calendário na minDate. | false |
+| startViewInMaxDate | boolean | Inicia a visualização do calendário na maxDate. | false |
+| disabled | boolean | Desabilita seleção de datas, mas emite evento `onCheckDate` ao tentar selecionar. | false |
+| ngModel | string \| string[] | Data(s) selecionada(s) no formato DD/MM/YYYY (ou separadas por vírgula em múltiplas). | undefined |
+| code | string | Identificador do componente para referência interna. | 'tcloud-ui-datepicker' |
+
+### Outputs
+| Nome | Tipo de Evento | Descrição |
+| --- | --- | --- |
+| onChange | EventEmitter<any> | Emite quando a data/datas é/são alterada(s). Retorna o valor selecionado. |
+| ngModelChange | EventEmitter<any> | Emite alteração do ngModel para two-way binding. |
+| onCheckDate | EventEmitter<any> | Emite quando há tentativa de seleção em modo disabled. Retorna `{ value, date, checked, disabled }`. |
+
+## Exemplos de Uso
+### Uso Básico - Calendário Inline
+```html
+<tcloud-ui-datepicker 
+  [(ngModel)]="dateValue"
+  (onChange)="onDateChanged($event)">
+</tcloud-ui-datepicker>
+
+<p>Data selecionada: {{ dateValue }}</p>
+```
+
+Componente:
+```ts
+export class ExampleComponent {
+  dateValue: string | undefined;
+
+  onDateChanged(event: any) {
+    console.log('Data selecionada:', event);
+  }
+}
+```
+
+### Uso Básico - Modo Input
+```html
+<tcloud-ui-datepicker 
+  [modeInput]="true"
+  [(ngModel)]="dateValue">
+</tcloud-ui-datepicker>
+```
+
+### Com Intervalo de Datas
+```html
+<tcloud-ui-datepicker 
+  [minDate]="'18/11/2021'"
+  [maxDate]="'18/12/2023'"
+  [(ngModel)]="dateValue">
+</tcloud-ui-datepicker>
+```
+
+### Desabilitar Dias da Semana
+```html
+<!-- Desabilita sábado e domingo -->
+<tcloud-ui-datepicker 
+  [daysOfWeekDisabled]="[0, 6]"
+  [(ngModel)]="dateValue">
+</tcloud-ui-datepicker>
+```
+
+### Desabilitar Datas Específicas
+```html
+<tcloud-ui-datepicker 
+  [datesDisabled]="['12/10/2022', '25/12/2022', '01/01/2023']"
+  [(ngModel)]="dateValue">
+</tcloud-ui-datepicker>
+```
+
+## Uso Avançado
+### Múltiplas Datas
+```html
+<tcloud-ui-datepicker 
+  [multiple]="true"
+  [maxNumberOfDates]="5"
+  [(ngModel)]="selectedDates"
+  (onChange)="onDatesChanged($event)">
+</tcloud-ui-datepicker>
+
+<p>Datas selecionadas: {{ selectedDates }}</p>
+```
+
+Componente:
+```ts
+export class ExampleComponent {
+  selectedDates: string[] = [];
+
+  onDatesChanged(event: any) {
+    console.log('Datas selecionadas:', event);
+  }
+}
+```
+
+### Combinação: Intervalo + Semana + Datas Desabilitadas
+```html
+<tcloud-ui-datepicker 
+  [minDate]="'01/01/2024'"
+  [maxDate]="'31/12/2024'"
+  [daysOfWeekDisabled]="[0, 6]"
+  [datesDisabled]="['25/12/2024', '01/01/2025']"
+  [modeInput]="true"
+  [(ngModel)]="dateValue">
+</tcloud-ui-datepicker>
+```
+
+### Modo Disabled com Verificação
+```html
+<tcloud-ui-datepicker 
+  [multiple]="true"
+  [disabled]="true"
+  [(ngModel)]="selectedDates"
+  (onCheckDate)="onCheckDate($event)">
+</tcloud-ui-datepicker>
+```
+
+Componente:
+```ts
+export class ExampleComponent {
+  selectedDates: string[] = ['22/01/2024', '26/01/2024'];
+
+  onCheckDate(event: any) {
+    console.log('Tentativa de seleção desabilitada:', event);
+    // event: { value: '25/01/2024', date: Date, checked: true, disabled: true }
+  }
+}
+```
+
+### Iniciar em Data Específica
+```html
+<!-- Abre o calendário exibindo a minDate -->
+<tcloud-ui-datepicker 
+  [minDate]="'15/03/2024'"
+  [startViewInMinDate]="true"
+  [(ngModel)]="dateValue">
+</tcloud-ui-datepicker>
+```
+
+### Sem Borda (Inline)
+```html
+<tcloud-ui-datepicker 
+  [useBorder]="false"
+  [modeInput]="true"
+  [(ngModel)]="dateValue">
+</tcloud-ui-datepicker>
+```

package/docs/tcloud-ui-dropdown-multi.md

@@ -0,0 +1,444 @@
+# Dropdown Multi
+
+## Características
+
+O componente `tcloud-ui-dropdown-multi` é um componente de múltipla seleção com suporte a seleção/deselção em massa, itens desabilitados, dois-way binding e visualização customizável do texto selecionado. Permite que o usuário selecione múltiplas opções de uma lista dropdown com interface intuitiva.
+
+## Instalação
+
+Para utilizar o componente Dropdown Multi, importe o módulo `TCloudUiModule`:
+
+```typescript
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `<tcloud-ui-dropdown-multi ...></tcloud-ui-dropdown-multi>`
+})
+export class ExampleComponent {}
+```
+
+Ou importe diretamente o componente e as interfaces de dados:
+
+```typescript
+import { TCloudUiDropdownMultiComponent, DropdownMultiOption, DropdownMultiSize } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiDropdownMultiComponent],
+  template: `<tcloud-ui-dropdown-multi ...></tcloud-ui-dropdown-multi>`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|------|------|-----------|---------------|
+| `label` | `string` | Texto do rótulo exibido acima do seletor | `''` (vazio) |
+| `disabled` | `boolean` | Desabilita interações com o dropdown | `false` |
+| `options` | `DropdownMultiOption[]` | **Obrigatório**. Lista de opções disponíveis | - |
+| `initialValues` | `any[]` | Valores pré-selecionados (deprecated - use `values` instead) | `[]` |
+| `size` | `DropdownMultiSize` | Tamanho do dropdown: `'sm'` \| `'md'` \| `'lg'` | `'sm'` |
+| `width` | `string` | Largura customizada do dropdown (ex: `'300px'`, `'100%'`) | `''` |
+| `placeholder` | `string` | Texto exibido quando nenhum item está selecionado | `'Selecione'` |
+| `maxDisplayItems` | `number` | Máximo de itens a exibir no botão antes de mostrar "+N" | `2` |
+| `searchable` | `string` | Habilita campo para buscar na lista de itens | `false` |
+| `searchPlaceholder` | `string` | Texto exibido quando nenhum texto de busca é exibido | `Buscar...` |
+
+### Two-Way Binding (Model)
+
+| Nome | Tipo | Descrição |
+|------|------|-----------|
+| `values` | `any[]` | Array de valores selecionados - atualiza bidirecionalmente |
+
+### Outputs
+
+| Nome | Tipo de Evento | Descrição |
+|------|----------------|-----------|
+| `optionsSelected` | `any[]` | Emitido quando opções são selecionadas/deseleccionadas |
+
+### Interfaces e Enums Exportados
+
+```typescript
+export interface DropdownMultiOption {
+  id?: any;
+  value: any;
+  displayValue: string;
+  disabled?: boolean;
+}
+
+export enum DropdownMultiSize {
+  sm = 'sm',
+  md = 'md',
+  lg = 'lg',
+}
+```
+
+## Características Técnicas
+
+- **Seleção em Massa**: Botão "Todos" para selecionar/deselecionar todas as opções de uma vez
+- **Seleção Parcial**: Indica visualmente quando apenas alguns itens estão selecionados
+- **Itens Desabilitados**: Suporte a itens que não podem ser selecionados
+- **Visualização Inteligente**: Mostra primeiros N itens com "+X" para itens restantes
+- **Two-Way Binding**: Sincronização bidirecionional de valores com [(values)]
+- **Scroll Automático**: Menu dropdown com scroll quando há muitas opções
+- **Acessibilidade**: Suporte a aria-expanded e navegação por teclado
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-basic-multi-dropdown',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <tcloud-ui-dropdown-multi 
+      [options]="items"
+      label="Selecione itens"
+      placeholder="Nenhum selecionado"
+    ></tcloud-ui-dropdown-multi>
+  `
+})
+export class BasicMultiDropdownComponent {
+  items = [
+    { value: 'item1', displayValue: 'Item 1' },
+    { value: 'item2', displayValue: 'Item 2' },
+    { value: 'item3', displayValue: 'Item 3' },
+    { value: 'item4', displayValue: 'Item 4' }
+  ];
+}
+```
+
+### Com Two-Way Binding
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-multi-dropdown-binding',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div>
+      <tcloud-ui-dropdown-multi 
+        [(values)]="selectedItems"
+        [options]="fruitOptions"
+        label="Frutas"
+        placeholder="Escolha frutas"
+        (optionsSelected)="onFruitsSelected($event)"
+      ></tcloud-ui-dropdown-multi>
+      
+      <div *ngIf="selectedItems().length > 0">
+        <h4>Frutas Selecionadas:</h4>
+        <ul>
+          <li *ngFor="let item of selectedItems()">{{ item }}</li>
+        </ul>
+      </div>
+    </div>
+  `
+})
+export class MultiDropdownBindingComponent {
+  selectedItems = signal<any[]>([]);
+  
+  fruitOptions = [
+    { value: 'apple', displayValue: 'Maçã' },
+    { value: 'banana', displayValue: 'Banana' },
+    { value: 'orange', displayValue: 'Laranja' },
+    { value: 'grape', displayValue: 'Uva' },
+    { value: 'strawberry', displayValue: 'Morango' }
+  ];
+
+  onFruitsSelected(options: any[]): void {
+    console.log('Frutas selecionadas:', options);
+  }
+}
+```
+
+### Diferentes Tamanhos
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule, DropdownMultiSize } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-multi-dropdown-sizes',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="size-examples">
+      <!-- Tamanho Pequeno -->
+      <tcloud-ui-dropdown-multi 
+        [options]="colorOptions"
+        [size]="'sm'"
+        label="Pequeno (sm)"
+        width="200px"
+      ></tcloud-ui-dropdown-multi>
+
+      <!-- Tamanho Médio -->
+      <tcloud-ui-dropdown-multi 
+        [options]="colorOptions"
+        [size]="'md'"
+        label="Médio (md)"
+        width="200px"
+      ></tcloud-ui-dropdown-multi>
+
+      <!-- Tamanho Grande -->
+      <tcloud-ui-dropdown-multi 
+        [options]="colorOptions"
+        [size]="'lg'"
+        label="Grande (lg)"
+        width="200px"
+      ></tcloud-ui-dropdown-multi>
+    </div>
+  `,
+  styles: [`
+    .size-examples {
+      display: flex;
+      flex-direction: column;
+      gap: 2rem;
+    }
+  `]
+})
+export class MultiDropdownSizesComponent {
+  colorOptions = [
+    { value: 'red', displayValue: 'Vermelho' },
+    { value: 'blue', displayValue: 'Azul' },
+    { value: 'green', displayValue: 'Verde' },
+    { value: 'yellow', displayValue: 'Amarelo' }
+  ];
+}
+```
+
+### Com Itens Desabilitados
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-multi-dropdown-disabled-items',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <tcloud-ui-dropdown-multi 
+      [options]="statusOptions"
+      label="Status"
+      placeholder="Selecione status"
+      width="250px"
+    ></tcloud-ui-dropdown-multi>
+  `
+})
+export class MultiDropdownDisabledItemsComponent {
+  statusOptions = [
+    { value: 'active', displayValue: 'Ativo' },
+    { value: 'inactive', displayValue: 'Inativo' },
+    { value: 'pending', displayValue: 'Pendente', disabled: true },
+    { value: 'archived', displayValue: 'Arquivado', disabled: true }
+  ];
+}
+```
+
+### Quantidade de Itens Exibidos
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-multi-dropdown-max-display',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="display-examples">
+      <!-- Exibe 1 item -->
+      <tcloud-ui-dropdown-multi 
+        [options]="languageOptions"
+        [maxDisplayItems]="1"
+        label="Max 1 Item"
+        width="200px"
+      ></tcloud-ui-dropdown-multi>
+
+      <!-- Exibe 3 itens (padrão) -->
+      <tcloud-ui-dropdown-multi 
+        [options]="languageOptions"
+        [maxDisplayItems]="3"
+        label="Max 3 Items"
+        width="200px"
+      ></tcloud-ui-dropdown-multi>
+
+      <!-- Exibe todos -->
+      <tcloud-ui-dropdown-multi 
+        [options]="languageOptions"
+        [maxDisplayItems]="99"
+        label="Mostrar Todos"
+        width="200px"
+      ></tcloud-ui-dropdown-multi>
+    </div>
+  `,
+  styles: [`
+    .display-examples {
+      display: flex;
+      flex-direction: column;
+      gap: 2rem;
+    }
+  `]
+})
+export class MultiDropdownMaxDisplayComponent {
+  languageOptions = [
+    { value: 'en', displayValue: 'English' },
+    { value: 'pt', displayValue: 'Português' },
+    { value: 'es', displayValue: 'Español' },
+    { value: 'fr', displayValue: 'Français' },
+    { value: 'de', displayValue: 'Deutsch' }
+  ];
+}
+```
+
+## Métodos Públicos
+
+O componente expõe os seguintes métodos que podem ser acessados via template reference variable:
+
+```typescript
+// Selecionar todas as opções (exceto desabilitadas)
+selectAll(): void
+
+// Limpar todas as seleções
+clearAll(): void
+
+// Alternar seleção de uma opção
+toggleOption(option: DropdownMultiOption): void
+
+// Abrir/fechar o dropdown
+toggleDropdown(): void
+```
+
+### Exemplo com Métodos
+
+```typescript
+import { Component, ViewChild } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-multi-dropdown-methods',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div>
+      <div class="button-group">
+        <button (click)="dropdown.selectAll()">Selecionar Todos</button>
+        <button (click)="dropdown.clearAll()">Limpar Tudo</button>
+      </div>
+
+      <tcloud-ui-dropdown-multi 
+        #dropdown
+        [options]="weekDays"
+        label="Dias da Semana"
+        placeholder="Escolha dias"
+      ></tcloud-ui-dropdown-multi>
+    </div>
+  `,
+  styles: [`
+    .button-group {
+      margin-bottom: 1rem;
+      display: flex;
+      gap: 1rem;
+    }
+    button {
+      padding: 0.5rem 1rem;
+      background: var(--c-primary-500);
+      color: white;
+      border: none;
+      border-radius: 0.25rem;
+      cursor: pointer;
+    }
+  `]
+})
+export class MultiDropdownMethodsComponent {
+  weekDays = [
+    { value: 'monday', displayValue: 'Segunda' },
+    { value: 'tuesday', displayValue: 'Terça' },
+    { value: 'wednesday', displayValue: 'Quarta' },
+    { value: 'thursday', displayValue: 'Quinta' },
+    { value: 'friday', displayValue: 'Sexta' },
+    { value: 'saturday', displayValue: 'Sábado' },
+    { value: 'sunday', displayValue: 'Domingo' }
+  ];
+}
+```
+
+## Boas Práticas
+
+1. **Use Labels Claros**: Sempre defina um label descritivo para a função do dropdown
+2. **Placeholder Útil**: Configure um placeholder que indique claramente o que deve ser selecionado
+3. **Limite de Opções**: Se tiver muitas opções (>20), considere agrupar ou usar filtro
+4. **Opções Desabilitadas**: Use para opções que não estão disponíveis no contexto atual
+5. **maxDisplayItems**: Ajuste conforme o espaço disponível e quantidade típica de seleções
+
+## Estados Visuais
+
+- **Default**: Sem seleção - exibe placeholder
+- **Hover**: Bordas destacadas em azul
+- **Selecionado Parcial**: Mostra opções selecionadas
+- **Todos Selecionados**: Exibe "Todos"
+- **Desabilitado**: Cinza, sem interação possível
+
+## Performance
+
+O componente é otimizado para listas de até 100 opções. Para listas maiores, considere:
+- Implementar virtualização (scroll virtual) no menu
+- Adicionar filter/search de opções
+- Paginar as opções
+
+## Acessibilidade
+
+- Suporte a `aria-expanded` indicando se dropdown está aberto/fechado
+- Checkboxes com suporte apropriado para leitores de tela
+- Navegação por teclado (deve ser alcançável por Tab)
+
+## Compatibilidade
+
+- **Angular**: 16+
+- **Browsers**: Todos os navegadores modernos
+- **CSS Variables**: Utiliza variáveis CSS do sistema de design
+
+## Integração com Formulários
+
+O componente funciona com `formsModule` (value-accessor pattern) e pode ser usado em formulários reativos:
+
+```typescript
+// Em seu componente
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+
+@Component({
+  imports: [ReactiveFormsModule, TCloudUiModule]
+})
+export class YourComponent {
+  selectedItems = new FormControl([]);
+  
+  // No template:
+  // <tcloud-ui-dropdown-multi [formControl]="selectedItems" ...></tcloud-ui-dropdown-multi>
+}
+```
+
+## Suporte
+
+Para reportar problemas, sugestões ou criar pull requests, visite o repositório oficial do projeto.