@dev-tcloud/tcloud-ui 6.15.0 → 6.17.0

package/docs/tcloud-ui-dropdown.md

@@ -0,0 +1,369 @@
+# Dropdown
+
+## Características
+
+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.
+
+## Instalação
+
+Para utilizar o componente Dropdown, 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 ...></tcloud-ui-dropdown>`
+})
+export class ExampleComponent {}
+```
+
+Ou importe diretamente o componente e a interface de dados:
+
+```typescript
+import { TCloudUiDropdownComponent, DropdownOption, DropdownSize } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiDropdownComponent],
+  template: `<tcloud-ui-dropdown ...></tcloud-ui-dropdown>`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|------|------|-----------|---------------|
+| `label` | `string` | Texto do rótulo exibido acima da opção selecionada | `''` (vazio) |
+| `disabled` | `boolean` | Desabilita interações com o dropdown | `false` |
+| `options` | `DropdownOption[]` | **Obrigatório**. Lista de opções disponíveis | - |
+| `initialValue` | `any` | Valor pré-selecionado (deprecated - use `value` instead) | `null` |
+| `size` | `DropdownSize` | Tamanho do dropdown: `'sm'` \| `'md'` \| `'lg'` | `'sm'` |
+| `width` | `string` | Largura customizada do dropdown (ex: `'300px'`, `'50%'`) | `''` (100% do pai) |
+| `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 |
+|------|------|-----------|
+| `value` | `any` | Valor selecionado - atualiza bidirecionalmente |
+
+### Outputs
+
+| Nome | Tipo de Evento | Descrição |
+|------|----------------|-----------|
+| `optionSelected` | `DropdownOption` | Emitido quando uma opção é selecionada |
+
+### Interfaces e Enums Exportados
+
+```typescript
+export interface DropdownOption {
+  id?: any;
+  value: any;
+  displayValue: string;
+  disabled?: boolean;
+}
+
+export enum DropdownSize {
+  sm = 'sm',
+  md = 'md',
+  lg = 'lg',
+}
+```
+
+## 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-dropdown',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <tcloud-ui-dropdown 
+      [options]="[
+        { value: 'opt1', displayValue: 'Opção 1' },
+        { value: 'opt2', displayValue: 'Opção 2' },
+        { value: 'opt3', displayValue: 'Opção 3' }
+      ]"
+      label="Selecione uma opção"
+    ></tcloud-ui-dropdown>
+  `
+})
+export class BasicDropdownComponent {}
+```
+
+### Uso Avançado com Two-Way Binding
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+import { signal } from '@angular/core';
+
+@Component({
+  selector: 'app-advanced-dropdown',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div>
+      <tcloud-ui-dropdown 
+        [(value)]="selectedValue"
+        [options]="options"
+        label="Escolha um usuário"
+        size="md"
+        (optionSelected)="onUserSelected($event)"
+      ></tcloud-ui-dropdown>
+      
+      <p *ngIf="selectedValue">Você selecionou: {{ selectedValue }}</p>
+    </div>
+  `
+})
+export class AdvancedDropdownComponent {
+  selectedValue = signal(null);
+  
+  options = [
+    { value: 'user1', displayValue: 'João Silva', id: 1 },
+    { value: 'user2', displayValue: 'Maria Santos', id: 2 },
+    { value: 'user3', displayValue: 'Pedro Oliveira', id: 3 },
+    { value: 'user4', displayValue: 'Ana Costa', id: 4 }
+  ];
+
+  onUserSelected(option: any): void {
+    console.log('Usuário selecionado:', option);
+  }
+}
+```
+
+### Diferentes Tamanhos
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule, DropdownSize } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-sizes-dropdown',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="container">
+      <div class="group">
+        <label>Pequeno (sm)</label>
+        <tcloud-ui-dropdown 
+          [options]="options" 
+          size="sm"
+          label="Tamanho pequeno"
+        ></tcloud-ui-dropdown>
+      </div>
+
+      <div class="group">
+        <label>Médio (md)</label>
+        <tcloud-ui-dropdown 
+          [options]="options" 
+          size="md"
+          label="Tamanho médio"
+        ></tcloud-ui-dropdown>
+      </div>
+
+      <div class="group">
+        <label>Grande (lg)</label>
+        <tcloud-ui-dropdown 
+          [options]="options" 
+          size="lg"
+          label="Tamanho grande"
+        ></tcloud-ui-dropdown>
+      </div>
+    </div>
+  `,
+  styles: [`
+    .container {
+      display: flex;
+      flex-direction: column;
+      gap: 2rem;
+    }
+    .group {
+      display: flex;
+      flex-direction: column;
+      gap: 0.5rem;
+    }
+  `]
+})
+export class SizesDropdownComponent {
+  options = [
+    { value: '1', displayValue: 'Opção 1' },
+    { value: '2', displayValue: 'Opção 2' },
+    { value: '3', displayValue: 'Opção 3' }
+  ];
+}
+```
+
+### Com Opções Desabilitadas
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-disabled-options',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <tcloud-ui-dropdown 
+      [options]="options"
+      label="Status do pedido"
+      [(value)]="selectedStatus"
+    ></tcloud-ui-dropdown>
+  `
+})
+export class DisabledOptionsComponent {
+  selectedStatus = null;
+  
+  options = [
+    { value: 'pending', displayValue: 'Pendente' },
+    { value: 'processing', displayValue: 'Processando', disabled: true },
+    { value: 'sent', displayValue: 'Enviado' },
+    { value: 'delivered', displayValue: 'Entregue', disabled: true },
+    { value: 'cancelled', displayValue: 'Cancelado' }
+  ];
+}
+```
+
+### Com Largura Customizada
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-custom-width',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="container">
+      <tcloud-ui-dropdown 
+        [options]="options"
+        label="Dropdown customizado"
+        width="400px"
+      ></tcloud-ui-dropdown>
+    </div>
+  `,
+  styles: [`
+    .container {
+      max-width: 600px;
+    }
+  `]
+})
+export class CustomWidthComponent {
+  options = [
+    { value: 'short', displayValue: 'Texto curto' },
+    { value: 'long', displayValue: 'Este é um texto bem longo que pode ser elipsado com tooltip' },
+    { value: 'verylong', displayValue: 'Um texto extremamente longo que certamente será elipsado e terá um tooltip exibindo o valor completo' }
+  ];
+}
+```
+
+### Gerenciamento de Estado Dinâmico
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+import { signal } from '@angular/core';
+
+@Component({
+  selector: 'app-dynamic-state',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="container">
+      <button (click)="toggleDisabled()">
+        {{ isDisabled() ? 'Habilitar' : 'Desabilitar' }}
+      </button>
+
+      <tcloud-ui-dropdown 
+        [options]="options"
+        [disabled]="isDisabled()"
+        [(value)]="selectedValue"
+        label="Dropdown com estado dinâmico"
+      ></tcloud-ui-dropdown>
+
+      <button (click)="resetValue()">Limpar seleção</button>
+      
+      <p *ngIf="selectedValue">Valor selecionado: {{ selectedValue }}</p>
+    </div>
+  `,
+  styles: [`
+    .container {
+      display: flex;
+      flex-direction: column;
+      gap: 1rem;
+    }
+  `]
+})
+export class DynamicStateComponent {
+  isDisabled = signal(false);
+  selectedValue = signal(null);
+  
+  options = [
+    { value: 'opt1', displayValue: 'Opção 1' },
+    { value: 'opt2', displayValue: 'Opção 2' },
+    { value: 'opt3', displayValue: 'Opção 3' }
+  ];
+
+  toggleDisabled(): void {
+    this.isDisabled.update(value => !value);
+  }
+
+  resetValue(): void {
+    this.selectedValue.set(null);
+  }
+}
+```
+
+## Comportamento Responsivo
+
+O componente detecta automaticamente o tamanho da viewport:
+
+- **Desktop**: Exibe um dropdown com menu suspenso posicionado absolutamente abaixo do botão
+- **Mobile (< 480px)**: Abre um menu fullscreen modal para melhor usabilidade em telas pequenas
+
+A detecção é feita através do serviço `TCloudUiDeviceUtilsService`.
+
+## Tooltip para Texto Elipsado
+
+Quando um texto de opção é muito longo e sofre truncamento, o componente automaticamente:
+1. Detecta o texto elipsado
+2. Exibe um tooltip com o valor completo ao passar o mouse
+
+## Estados do Componente
+
+- **Normal**: Dropdown habilitado e pronto para interação
+- **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
+- **Selecionado**: Opção com fundo destacado e ícone de check
+
+## Notas de Implementação
+
+- 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)
+- 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

package/docs/tcloud-ui-el-copy.md

@@ -0,0 +1,113 @@
+# El-Copy
+
+## Características
+- Diretiva estrutural que adiciona funcionalidade de cópia ao clipboard de forma automática.
+- Injeta um botão de ícone (Font Awesome `fa-copy`) no elemento anotado.
+- Suporta copy de `textContent` em elementos genéricos e `value` em inputs.
+- Feedback visual: ícone muda para `fa-check` durante 3 segundos após copiar.
+- Identificação única: gera um `data-el-copy` único para cada elemento.
+- Suporta elementos INPUT com classe especial `tc-form-control`.
+
+## Instalação
+```ts
+import { TCloudUiElCopyDirective } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiElCopyDirective],
+  template: `<label TCCopy>Clique para copiar</label>`
+})
+export class ExampleComponent {}
+```
+
+Ou via módulo:
+```ts
+import { TcRevComponentsLibModule } from 'projects/tcloud-ui/src/public-api';
+
+@NgModule({
+  imports: [TcRevComponentsLibModule]
+})
+export class AppModule {}
+```
+
+## Propriedades (API)
+### Inputs
+| Nome | Tipo | Descrição | Valor Default |
+| --- | --- | --- | --- |
+| TCCopy | - | Diretiva estrutural sem entrada. Aplicar como atributo. | - |
+
+### Outputs
+| Nome | Tipo de Evento | Descrição |
+| --- | --- | --- |
+| (não possui) | - | Diretiva não emite eventos. |
+
+## Exemplos de Uso
+### Uso Básico com label
+```html
+<label TCCopy>Clique aqui para copiar este texto</label>
+```
+
+### Com input padrão
+```html
+<input type="text" value="Texto para copiar" TCCopy>
+```
+
+### Com input tc-form-control
+```html
+<input type="text" class="tc-form-control" value="Valor do formulário" TCCopy>
+```
+
+### Em div
+```html
+<div TCCopy>
+  Conteúdo que será copiado ao clicar no ícone
+</div>
+```
+
+### Em span
+```html
+<span TCCopy>ID: 12345</span>
+```
+
+## Uso Avançado
+### Com binding dinâmico em input
+```html
+<input type="text" [value]="textoParaCopiar" TCCopy>
+```
+
+Componente:
+```ts
+export class ExampleComponent {
+  textoParaCopiar: string = 'Conteúdo dinâmico';
+}
+```
+
+### Em lista
+```html
+<ul>
+  <li *ngFor="let item of items">
+    <label TCCopy>{{ item.name }}</label>
+  </li>
+</ul>
+```
+
+Componente:
+```ts
+export class ListComponent {
+  items = [
+    { name: 'Item 1' },
+    { name: 'Item 2' },
+    { name: 'Item 3' }
+  ];
+}
+```
+
+### Com elementos customizados
+```html
+<div class="custom-card">
+  <p TCCopy>{{ codigoDeVerificacao }}</p>
+</div>
+```
+
+O ícone de cópia será automaticamente inserido no elemento, e ao clicar, o conteúdo textual ou value será copiado para a área de transferência.