@dev-tcloud/tcloud-ui 6.14.3 → 6.17.0

package/docs/tcloud-ui-accordion.md

@@ -0,0 +1,345 @@
+# Accordion
+
+O componente **Accordion** fornece uma interface colapsável e expansível para organizar conteúdo em seções. Cada seção possui um título e um corpo que pode ser expandido ou contraído através de interação do usuário ou programaticamente.
+
+## Características
+
+- **Expansão/Contração suave**: Animação flu ida de altura com duração de 0.35s
+- **Controle programático**: Propriedades `show` e `disabled` para contolar o estado
+- **Estado de carregamento**: Modo loading para indicar operações assíncronas
+- **Reatividade baseada em Serviço**: Utiliza um serviço compartilhado para sincronizar estado entre componentes
+- **Composição flexível**: Estrutura de componentes filhos (title e body)
+- **Eventos emitidos**: Notifica quando o accordion é aberto ou fechado através da propriedade `onAction`
+- **Desabilitável**: Pode ser desabilitado para evitar interação do usuário
+
+## Instalação
+
+```typescript
+import { TCloudUiModule } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  imports: [TCloudUiModule],
+  // ... resto da configuração
+})
+export class MyComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|------|------|-----------|---------------|
+| `show` | `boolean` | Define se o accordion está expandido (true) ou contraído (false) | `false` |
+| `disabled` | `boolean` | Desabilita a interação com o accordion, impedindo expansão/contração | `false` |
+| `loading` | `boolean` | Ativa modo de carregamento, indicando operação assíncrona em andamento | `false` |
+
+### Outputs
+
+| Nome | Tipo de Evento | Descrição |
+|------|--------|-----------|
+| `onAction` | `'open' \| 'close'` | Emite quando o accordion é expandido (open) ou contraído (close) |
+
+## Componentes Filhos
+
+### tcloud-ui-accordion-title
+
+Representa o título/cabeçalho do accordion. Contém um botão de toggle com ícone de chevron que se rotaciona conforme o estado.
+
+```html
+<tcloud-ui-accordion-title>
+  Título do Accordion
+</tcloud-ui-accordion-title>
+```
+
+**Características:**
+- Exibe o conteúdo via `<ng-content>`
+- Botão com ícone que indica estado (chevron-right quando fechado, chevron-down quando aberto)
+- Responde a cliques para alternar estado
+- Pode ser desabilitada junto com o accordion
+
+### tcloud-ui-accordion-body
+
+Representa o corpo/conteúdo do accordion. Aplica animação de expansão/contração.
+
+```html
+<tcloud-ui-accordion-body>
+  Conteúdo do Accordion
+</tcloud-ui-accordion-body>
+```
+
+**Características:**
+- Aplica animação de altura: 0 (fechado) → auto (aberto)
+- Duração da animação: 0.35s com easing ease-in-out
+- Sincroniza automaticamente com o estado do accordion pai
+
+## Exemplos de Uso
+
+### Uso Básico
+
+Accordion simples com título e conteúdo de texto:
+
+```typescript
+@Component({
+  selector: 'app-accordion-basic',
+  imports: [TCloudUiModule],
+  template: `
+    <tcloud-ui-accordion>
+      <tcloud-ui-accordion-title>
+        Seção 1
+      </tcloud-ui-accordion-title>
+      
+      <tcloud-ui-accordion-body>
+        Conteúdo da primeira seção
+      </tcloud-ui-accordion-body>
+    </tcloud-ui-accordion>
+
+    <tcloud-ui-accordion>
+      <tcloud-ui-accordion-title>
+        Seção 2
+      </tcloud-ui-accordion-title>
+      
+      <tcloud-ui-accordion-body>
+        Conteúdo da segunda seção
+      </tcloud-ui-accordion-body>
+    </tcloud-ui-accordion>
+  `
+})
+export class AccordionBasicComponent {}
+```
+
+### Uso Avançado com Controle de Estado
+
+Accordion com controle programático e sincronização de eventos:
+
+```typescript
+@Component({
+  selector: 'app-accordion-advanced',
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="accordion-controls">
+      <button 
+        (click)="expandAll()"
+        class="tc-btn tc-btn-primary"
+      >
+        Expandir Todos
+      </button>
+
+      <button 
+        (click)="collapseAll()"
+        class="tc-btn"
+      >
+        Fechar Todos
+      </button>
+
+      <button 
+        (click)="toggleDisable()"
+        [class.active]="isDisabled"
+        class="tc-btn"
+      >
+        {{ isDisabled ? 'Habilitar' : 'Desabilitar' }}
+      </button>
+    </div>
+
+    <div class="accordion-container">
+      <tcloud-ui-accordion 
+        *ngFor="let section of sections; let i = index"
+        [show]="expandedStates[i]"
+        [disabled]="isDisabled"
+        [loading]="loadingStates[i]"
+        (onAction)="handleAction($event, i)"
+      >
+        <tcloud-ui-accordion-title>
+          {{ section.title }}
+        </tcloud-ui-accordion-title>
+        
+        <tcloud-ui-accordion-body>
+          {{ section.content }}
+        </tcloud-ui-accordion-body>
+      </tcloud-ui-accordion>
+    </div>
+
+    <div class="event-log" *ngIf="lastEvent">
+      <p>Último evento: {{ lastEvent }}</p>
+    </div>
+  `
+})
+export class AccordionAdvancedComponent {
+  sections = [
+    { title: 'Informações Pessoais', content: 'Nome, e-mail, telefone' },
+    { title: 'Endereço', content: 'Rua, número, cidade, estado' },
+    { title: 'Documentação', content: 'CPF, RG, Comprovante de residência' }
+  ];
+
+  expandedStates: boolean[] = [true, false, false];
+  loadingStates: boolean[] = [false, false, false];
+  isDisabled: boolean = false;
+  lastEvent: string = '';
+
+  expandAll() {
+    this.expandedStates = this.expandedStates.map(() => true);
+  }
+
+  collapseAll() {
+    this.expandedStates = this.expandedStates.map(() => false);
+  }
+
+  toggleDisable() {
+    this.isDisabled = !this.isDisabled;
+  }
+
+  handleAction(action: 'open' | 'close', index: number) {
+    this.lastEvent = `Seção ${index + 1} ${action === 'open' ? 'expandida' : 'contraída'}`;
+    
+    // Simular carregamento de dados
+    if (action === 'open') {
+      this.loadingStates[index] = true;
+      setTimeout(() => {
+        this.loadingStates[index] = false;
+      }, 2000);
+    }
+  }
+}
+```
+
+### Uso com Tabelas e Conteúdo Dinâmico
+
+Accordion contendo tabelas e conteúdo complexo:
+
+```typescript
+@Component({
+  selector: 'app-accordion-with-table',
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <tcloud-ui-accordion 
+      [show]="showProducts"
+      (onAction)="onProductsAction($event)"
+    >
+      <tcloud-ui-accordion-title>
+        Produtos ({{ products.length }})
+      </tcloud-ui-accordion-title>
+      
+      <tcloud-ui-accordion-body>
+        <table class="products-table">
+          <thead>
+            <tr>
+              <th>Nome</th>
+              <th>Categoria</th>
+              <th>Preço</th>
+              <th>Estoque</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr *ngFor="let product of products">
+              <td>{{ product.name }}</td>
+              <td>{{ product.category }}</td>
+              <td>{{ product.price | currency }}</td>
+              <td>
+                <span [class.low-stock]="product.stock < 10">
+                  {{ product.stock }}
+                </span>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </tcloud-ui-accordion-body>
+    </tcloud-ui-accordion>
+
+    <tcloud-ui-accordion 
+      [show]="showOrders"
+      [loading]="loadingOrders"
+      (onAction)="onOrdersAction($event)"
+    >
+      <tcloud-ui-accordion-title>
+        Pedidos Pendentes ({{ orders.length }})
+      </tcloud-ui-accordion-title>
+      
+      <tcloud-ui-accordion-body>
+        <div *ngIf="loadingOrders" class="loading">
+          Carregando pedidos...
+        </div>
+        
+        <div *ngIf="!loadingOrders" class="orders-list">
+          <div *ngFor="let order of orders" class="order-item">
+            <p><strong>Pedido #{{ order.id }}</strong> - {{ order.date | date:'dd/MM/yyyy' }}</p>
+            <p>Status: <span [class]="'status-' + order.status">{{ order.status }}</span></p>
+          </div>
+        </div>
+      </tcloud-ui-accordion-body>
+    </tcloud-ui-accordion>
+  `,
+  styles: [`
+    .products-table {
+      width: 100%;
+      border-collapse: collapse;
+    }
+    
+    .low-stock {
+      color: #d32f2f;
+      font-weight: bold;
+    }
+
+    .orders-list {
+      padding: 12px 0;
+    }
+
+    .order-item {
+      padding: 8px;
+      border-bottom: 1px solid #eee;
+    }
+
+    .status-pending {
+      color: #ff9800;
+    }
+
+    .status-confirmed {
+      color: #4caf50;
+    }
+  `]
+})
+export class AccordionWithTableComponent {
+  showProducts: boolean = true;
+  showOrders: boolean = false;
+  loadingOrders: boolean = false;
+
+  products = [
+    { name: 'Notebook', category: 'Eletrônicos', price: 2500, stock: 5 },
+    { name: 'Mouse', category: 'Periféricos', price: 50, stock: 25 },
+    { name: 'Teclado', category: 'Periféricos', price: 150, stock: 8 }
+  ];
+
+  orders: any[] = [];
+
+  onProductsAction(action: 'open' | 'close') {
+    console.log('Produtos', action);
+  }
+
+  onOrdersAction(action: 'open' | 'close') {
+    console.log('Pedidos', action);
+    
+    if (action === 'open') {
+      this.loadingOrders = true;
+      // Simular carregamento de dados
+      setTimeout(() => {
+        this.orders = [
+          { id: 'PED-001', date: new Date(), status: 'pending' },
+          { id: 'PED-002', date: new Date(), status: 'confirmed' },
+          { id: 'PED-003', date: new Date(), status: 'pending' }
+        ];
+        this.loadingOrders = false;
+      }, 1500);
+    }
+  }
+}
+```
+
+## Notas de Implementação
+
+- O componente utiliza um **serviço compartilhado** (`TCloudUiAccordionService`) fornecido no nível do componente pai
+- Todos os componentes filhos (title e body) injetam o mesmo serviço e se sincronizam através de **Observables (RxJS)**
+- A animação é implementada através de **Angular Animations** (trigger `expandAccordion`)
+- Quando `disabled` é definido como `true`, todas as operações são ignoradas e o accordion é visualmente desabilitado
+- O evento `onAction` emite apenas quando o estado é alterado dentro do componente (não quando alterado via propriedade `show`)
+- A propriedade `loading` não impede interação, apenas ativa um indicador visual
+- Múltiplas instâncias de accordion são **independentes** - cada uma tem seu próprio serviço
+- O titulo (title) também ativa alternância ao clicar, além do botão de toggle

package/docs/tcloud-ui-actions.md

@@ -0,0 +1,88 @@
+# Actions (ProductAction Pipe)
+
+## Características
+
+O `ProductActionPipe` é um pipe Angular que traduz códigos de ações de produto para descrições legíveis em português. Suporta dois modos de operação:
+
+- **single** (padrão): recebe uma string que pode conter múltiplas ações separadas por `&`. Quando há mais de uma ação, cada uma é traduzida individualmente e o resultado é unido com ` - `.
+- **bulk**: traduz diretamente uma única ação, ignorando a lógica de split por `&`.
+
+### Ações Reconhecidas
+
+| Código                              | Tradução                        |
+|-------------------------------------|---------------------------------|
+| `update-release` / `update_release` | Atualizar versão da release     |
+| `update-patch` / `update_patch`     | Atualizar versão do pacote      |
+| `update-database-dump` / `update-global-dump` / `update_global_dump` | Dump global |
+| `update-patch & update-release`     | Atualizar pacote/release        |
+
+Ações não reconhecidas são retornadas sem alteração.
+
+## Instalação
+
+Importe o `ProductActionPipe` no componente standalone:
+
+```typescript
+import { ProductActionPipe } from 'tcloud-ui';
+
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [ProductActionPipe],
+    template: '...'
+})
+export class ExemploComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs (Parâmetros do Pipe)
+
+| Nome  | Tipo                  | Descrição                                                                 | Valor Default |
+|-------|-----------------------|---------------------------------------------------------------------------|---------------|
+| value | `string`              | String contendo a(s) ação(ões) a ser(em) traduzida(s).                    | —             |
+| type  | `'bulk' \| 'single'`  | Modo de operação: `single` faz split por `&`, `bulk` traduz diretamente.  | `'single'`    |
+
+## Exemplos de Uso
+
+### Uso Básico — Ação Única
+
+```html
+<!-- Entrada: 'update-release' -->
+<!-- Saída: 'Atualizar versão da release' -->
+<span>{{ 'update-release' | productAction }}</span>
+```
+
+### Uso com Múltiplas Ações
+
+```html
+<!-- Entrada: 'update-release&update-patch' -->
+<!-- Saída: 'Atualizar versão da release - Atualizar versão do pacote' -->
+<span>{{ 'update-release&update-patch' | productAction }}</span>
+```
+
+### Uso com Tipo Bulk
+
+```html
+<!-- Entrada: 'update-database-dump' com type 'bulk' -->
+<!-- Saída: 'Dump global' -->
+<span>{{ 'update-database-dump' | productAction:'bulk' }}</span>
+```
+
+### Uso Avançado — Binding Dinâmico
+
+```typescript
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [ProductActionPipe],
+    template: `
+      <div *ngFor="let action of actions">
+        {{ action | productAction }}
+      </div>
+    `
+})
+export class ExemploComponent {
+  actions = ['update-release', 'update-patch', 'update-database-dump', 'custom-action'];
+}
+```

package/docs/tcloud-ui-alert-banner.md

@@ -0,0 +1,104 @@
+# Alert Banner
+
+## Características
+
+O `TCloudUiAlertBannerComponent` é um componente Angular standalone que exibe banners de alerta com ícone, mensagem e link opcional. Suporta diferentes tipos visuais de alerta:
+
+- **warning**: fundo e borda em tons de alerta (amarelo/laranja).
+- **danger**: fundo e borda em tons de perigo (vermelho).
+- **info**: fundo e borda em tons informativos (azul).
+- **success**: fundo e borda em tons de sucesso (verde).
+
+O banner possui uma borda lateral esquerda colorida com ícone de exclamação e suporta um link clicável dentro da mensagem, emitindo um evento ao ser clicado.
+
+## Instalação
+
+Importe o `TCloudUiAlertBannerComponent` no componente standalone:
+
+```typescript
+import { TCloudUiAlertBannerComponent } from 'tcloud-ui';
+
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [TCloudUiAlertBannerComponent],
+    template: '...'
+})
+export class ExemploComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome      | Tipo                      | Descrição                                          | Valor Default |
+|-----------|---------------------------|----------------------------------------------------|---------------|
+| alertType | `'warning' \| 'danger'`   | Define o tipo visual do alerta (cor de fundo/borda).| `'warning'`   |
+| message   | `string`                  | Texto da mensagem exibida no banner.               | `''`          |
+| linkText  | `string`                  | Texto do link exibido após a mensagem.             | `''`          |
+| linkUrl   | `string`                  | URL do link (disponível para binding).             | `''`          |
+
+### Outputs
+
+| Nome        | Tipo de Evento | Descrição                                  |
+|-------------|----------------|--------------------------------------------|
+| linkClicked | `void`         | Emitido quando o link do banner é clicado. |
+
+## Exemplos de Uso
+
+### Uso Básico — Alerta Warning com Link
+
+```html
+<tcloud-ui-alert-banner
+  [alertType]="'warning'"
+  [message]="'Atenção: esta ação não poderá ser desfeita.'"
+  [linkText]="'Saiba mais'"
+  (linkClicked)="onLinkClicked()">
+</tcloud-ui-alert-banner>
+```
+
+### Uso Básico — Alerta Danger
+
+```html
+<tcloud-ui-alert-banner
+  [alertType]="'danger'"
+  [message]="'Erro crítico detectado no sistema.'"
+  [linkText]="'Ver detalhes'"
+  (linkClicked)="onLinkClicked()">
+</tcloud-ui-alert-banner>
+```
+
+### Uso Sem Link
+
+```html
+<tcloud-ui-alert-banner
+  [alertType]="'warning'"
+  [message]="'Mensagem de alerta simples sem link.'">
+</tcloud-ui-alert-banner>
+```
+
+### Uso Avançado — Tipo Dinâmico
+
+```typescript
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [TCloudUiAlertBannerComponent],
+    template: `
+      <tcloud-ui-alert-banner
+        [alertType]="currentType"
+        [message]="currentMessage"
+        [linkText]="'Clique aqui'"
+        (linkClicked)="handleClick()">
+      </tcloud-ui-alert-banner>
+    `
+})
+export class ExemploComponent {
+  currentType: 'warning' | 'danger' = 'warning';
+  currentMessage = 'Mensagem dinâmica de alerta.';
+
+  handleClick(): void {
+    console.log('Link do banner clicado');
+  }
+}
+```