@dev-tcloud/tcloud-ui 6.21.0 → 6.21.3

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

@@ -0,0 +1,186 @@
+# Dropdown Multi Level
+
+## Características
+
+O componente `tcloud-ui-dropdown-multi-level` é um componente de seleção de opção a partir de uma estrutura de dados hierárquica (menu multi-nível). Ele permite aninhamento de opções e seleção em sub-menus.
+
+## Instalação
+
+Para utilizar o componente Dropdown Multi Level, 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-level [menu]="menuOptions">Opções</tcloud-ui-dropdown-multi-level>`
+})
+export class ExampleComponent {}
+```
+
+Ou importe diretamente o componente e as interfaces de dados:
+
+```typescript
+import { TCloudUiDropdownMultiLevelComponent, MultiLevelDropdownOption, MultiLevelDropdownSize } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiDropdownMultiLevelComponent],
+  template: `<tcloud-ui-dropdown-multi-level [menu]="menuOptions">Opções</tcloud-ui-dropdown-multi-level>`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|------|------|-----------|---------------|
+| `menu` | `MultiLevelDropdownOption[]` | **Obrigatório**. Estrutura de opções (nós principais e filhos) do menu | - |
+| `subMenuPosition` | `'right' \| 'left'` | Posição de abertura do sub-menu em relação ao item pai | `'right'` |
+| `disabled` | `boolean` | Desabilita interações com o dropdown | `false` |
+| `size` | `MultiLevelDropdownSize` | Tamanho do dropdown: `'sm'` \| `'md'` \| `'lg'` | `'sm'` |
+| `initialValue` | `MultiLevelDropdownOption \| null` | Valor pré-selecionado | `null` |
+
+### Outputs
+
+| Nome | Tipo de Evento | Descrição |
+|------|----------------|-----------|
+| `optionSelected` | `{ option: MultiLevelDropdownOption, parentOption: MultiLevelDropdownOption }` | Emitido quando uma opção é selecionada (apenas para itens que não possuem filhos) |
+
+### Interfaces e Enums Exportados
+
+```typescript
+export interface MultiLevelDropdownOption {
+  id?: any;
+  value: any;
+  displayValue: string;
+  disabled?: boolean;
+  children?: MultiLevelDropdownOption[];
+}
+
+export enum MultiLevelDropdownSize {
+  sm = 'sm',
+  md = 'md',
+  lg = 'lg',
+}
+```
+
+## Características Técnicas
+
+- **Menu Hierárquico**: Suporte a opções com múltiplos níveis de aninhamento através da propriedade `children`.
+- **Posicionamento de Submenu**: Permite abrir submenus para a esquerda (`left`) ou direita (`right`).
+- **Seleção Restrita a Folhas**: Itens pai que possuem `children` não disparam evento de seleção e servem apenas para abrir submenus.
+- **Transclusão de Conteúdo (Content Projection)**: O botão de gatilho do menu utiliza `ng-content`, permitindo a customização livre do conteúdo do botão.
+- **Eventos com Contexto**: O evento `optionSelected` emite a opção final selecionada e também seu item pai direto.
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule, MultiLevelDropdownOption } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-basic-multi-level-dropdown',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <tcloud-ui-dropdown-multi-level 
+      [menu]="menuOptions"
+      (optionSelected)="onSelected($event)">
+      Ações do Usuário
+    </tcloud-ui-dropdown-multi-level>
+  `
+})
+export class BasicMultiLevelDropdownComponent {
+  menuOptions: MultiLevelDropdownOption[] = [
+    { value: 'home', displayValue: 'Início' },
+    { value: 'settings', displayValue: 'Configurações' },
+    { 
+      value: 'profile', 
+      displayValue: 'Perfil',
+      children: [
+        { value: 'view-profile', displayValue: 'Visualizar Perfil' },
+        { value: 'edit-profile', displayValue: 'Editar Perfil' }
+      ]
+    }
+  ];
+
+  onSelected(event: { option: MultiLevelDropdownOption, parentOption: MultiLevelDropdownOption }) {
+    console.log('Selecionado:', event.option);
+  }
+}
+```
+
+### Sub-menu Posicionado à Esquerda
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule, MultiLevelDropdownOption } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-left-multi-level-dropdown',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <tcloud-ui-dropdown-multi-level 
+      [menu]="menuOptions"
+      subMenuPosition="left">
+      Menu à Esquerda
+    </tcloud-ui-dropdown-multi-level>
+  `
+})
+export class LeftMultiLevelDropdownComponent {
+  menuOptions: MultiLevelDropdownOption[] = [
+    { 
+      value: 'export', 
+      displayValue: 'Exportar Dados',
+      children: [
+        { value: 'pdf', displayValue: 'Exportar como PDF' },
+        { value: 'csv', displayValue: 'Exportar como CSV' }
+      ]
+    }
+  ];
+}
+```
+
+### Tamanhos Diferentes
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule, MultiLevelDropdownOption, MultiLevelDropdownSize } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-size-multi-level-dropdown',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <tcloud-ui-dropdown-multi-level [menu]="menuOptions" [size]="sizes.sm">Pequeno</tcloud-ui-dropdown-multi-level>
+    <tcloud-ui-dropdown-multi-level [menu]="menuOptions" [size]="sizes.md">Médio</tcloud-ui-dropdown-multi-level>
+    <tcloud-ui-dropdown-multi-level [menu]="menuOptions" [size]="sizes.lg">Grande</tcloud-ui-dropdown-multi-level>
+  `
+})
+export class SizeMultiLevelDropdownComponent {
+  sizes = MultiLevelDropdownSize;
+  menuOptions: MultiLevelDropdownOption[] = [
+    { value: '1', displayValue: 'Opção 1' }
+  ];
+}
+```
+
+## Acessibilidade
+
+- O componente escuta eventos de clique no documento (`document:click`) para fechar o menu automaticamente caso o clique ocorra fora de seus limites (click-outside).
+
+## Compatibilidade
+
+- **Angular**: 17+ (suporta control flow blocks como `@if` e `@for`, além de signal inputs)
+- **Browsers**: Todos os navegadores modernos