@dev-tcloud/tcloud-ui 6.15.0 → 6.18.0

package/docs/tcloud-ui-faq.md

@@ -0,0 +1,496 @@
+# FAQ
+
+## Características
+
+O componente `tcloud-ui-faq` é um componente de perguntas frequentes (FAQ) que permite exibir uma lista de perguntas e respostas de forma interativa. Cada pergunta pode ser expandida ou recolhida com animações suaves, criando uma experiência intuitiva para o usuário encontrar respostas.
+
+## Instalação
+
+Para utilizar o componente FAQ, 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-faq 
+      [questions]="questions"
+      [title]="'Perguntas Frequentes'">
+    </tcloud-ui-faq>
+  `
+})
+export class ExampleComponent {
+  questions = [
+    { question: 'Como fazer?', answer: 'Desta forma...' }
+  ];
+}
+```
+
+Ou importe diretamente o componente:
+
+```typescript
+import { TCloudUiFaqComponent } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiFaqComponent],
+  template: `...`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|------|------|-----------|---------------|
+| `title` | `string` | Título da seção de FAQ | `'Dúvidas frequentes'` |
+| `questions` | `{ question: string; answer: string }[]` | Array de perguntas e respostas | `[]` |
+
+### Estados Internos
+
+O componente usa um `signal` para rastrear qual pergunta está aberta:
+- `openIndex: signal<number \| null>` - Índice da pergunta aberta (null se nenhuma estiver aberta)
+
+### Métodos
+
+- `toggle(index: number): void` - Alterna entre abrir/fechar uma pergunta
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-basic-faq',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <tcloud-ui-faq 
+      [questions]="basicQuestions"
+      [title]="'Perguntas Frequentes'">
+    </tcloud-ui-faq>
+  `
+})
+export class BasicFaqComponent {
+  basicQuestions = [
+    {
+      question: 'Como criar uma conta?',
+      answer: 'Para criar uma conta, clique no botão "Registrar" e preencha o formulário com seus dados.'
+    },
+    {
+      question: 'Esqueci minha senha. O que fazer?',
+      answer: 'Clique em "Esqueci minha senha" na página de login e siga as instruções enviadas para seu email.'
+    },
+    {
+      question: 'Como contatar o suporte?',
+      answer: 'Você pode contatar o suporte através do formulário de contato ou enviando um email para support@example.com'
+    }
+  ];
+}
+```
+
+### FAQ por Categoria
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-category-faq',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="faq-categories">
+      <div class="category">
+        <h3>Conta e Login</h3>
+        <tcloud-ui-faq [questions]="accountQuestions"></tcloud-ui-faq>
+      </div>
+
+      <div class="category">
+        <h3>Pagamento</h3>
+        <tcloud-ui-faq [questions]="paymentQuestions"></tcloud-ui-faq>
+      </div>
+
+      <div class="category">
+        <h3>Envios</h3>
+        <tcloud-ui-faq [questions]="shippingQuestions"></tcloud-ui-faq>
+      </div>
+    </div>
+  `,
+  styles: [`
+    .faq-categories {
+      display: grid;
+      gap: 2rem;
+    }
+    
+    .category h3 {
+      margin: 0 0 1rem;
+      font-size: 1.5rem;
+      color: var(--c-primary-600);
+    }
+  `]
+})
+export class CategoryFaqComponent {
+  accountQuestions = [
+    {
+      question: 'Como editar meu perfil?',
+      answer: 'Acesse Configurações > Perfil para editar suas informações pessoais.'
+    },
+    {
+      question: 'Como alterar meu email?',
+      answer: 'Vá para Configurações > Segurança > Email e siga o processo de verificação.'
+    }
+  ];
+
+  paymentQuestions = [
+    {
+      question: 'Quais formas de pagamento vocês aceitam?',
+      answer: 'Aceitamos cartão de crédito, débito, PIX e boleto bancário.'
+    },
+    {
+      question: 'Meu pagamento foi recusado. O que fazer?',
+      answer: 'Verifique dados do cartão, disponibilidade de crédito ou tente outro método de pagamento.'
+    }
+  ];
+
+  shippingQuestions = [
+    {
+      question: 'Qual é o prazo de entrega?',
+      answer: 'O prazo varia de 1 a 7 dias úteis dependendo da sua localização.'
+    },
+    {
+      question: 'Como rastrear meu pedido?',
+      answer: 'Use o código de rastreamento enviado por email ou acesse sua conta > Pedidos.'
+    }
+  ];
+}
+```
+
+### FAQ com Busca
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+import { FormsModule } from '@angular/forms';
+
+@Component({
+  selector: 'app-search-faq',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule, FormsModule],
+  template: `
+    <div class="search-faq">
+      <input
+        type="text"
+        [(ngModel)]="searchTerm"
+        placeholder="Buscar pergunta..."
+        class="search-input"
+      />
+
+      <tcloud-ui-faq
+        [questions]="filteredQuestions()"
+        [title]="'Resultados da Busca'"
+      ></tcloud-ui-faq>
+
+      @if (searchTerm && filteredQuestions().length === 0) {
+        <div class="no-results">
+          Nenhuma pergunta encontrada para "{{ searchTerm }}"
+        </div>
+      }
+    </div>
+  `,
+  styles: [`
+    .search-faq {
+      max-width: 600px;
+      margin: 0 auto;
+    }
+
+    .search-input {
+      width: 100%;
+      padding: 0.75rem;
+      margin-bottom: 1.5rem;
+      border: 1px solid var(--c-neutral-300);
+      border-radius: var(--bor-radius-8);
+      font-size: 1rem;
+    }
+
+    .search-input:focus {
+      outline: none;
+      border-color: var(--c-primary-500);
+      box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+    }
+
+    .no-results {
+      padding: 2rem;
+      text-align: center;
+      color: var(--c-neutral-600);
+      background: var(--c-neutral-100);
+      border-radius: var(--bor-radius-8);
+    }
+  `]
+})
+export class SearchFaqComponent {
+  searchTerm = signal('');
+
+  allQuestions = [
+    { question: 'O que é FAQ?', answer: 'FAQ é Perguntas Frequentes' },
+    { question: 'Como usar?', answer: 'Use o componente com um array de perguntas' },
+    { question: 'É responsivo?', answer: 'Sim, é totalmente responsivo' },
+    { question: 'Posso customizar?', answer: 'Sim, você pode customizar as perguntas' }
+  ];
+
+  filteredQuestions() {
+    const term = this.searchTerm().toLowerCase();
+    if (!term) return this.allQuestions;
+
+    return this.allQuestions.filter(q =>
+      q.question.toLowerCase().includes(term) ||
+      q.answer.toLowerCase().includes(term)
+    );
+  }
+}
+```
+
+### FAQ Dinâmico
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-dynamic-faq',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="dynamic-faq">
+      <button 
+        (click)="loadMoreQuestions()"
+        class="btn-load-more"
+        [disabled]="allQuestionsLoaded()">
+        @if (!allQuestionsLoaded()) {
+          Carregar mais perguntas
+        } @else {
+          Todas as perguntas carregadas ✓
+        }
+      </button>
+
+      <tcloud-ui-faq
+        [questions]="displayedQuestions()"
+        [title]="'Perguntas Frequentes'"
+      ></tcloud-ui-faq>
+    </div>
+  `,
+  styles: [`
+    .dynamic-faq {
+      display: flex;
+      flex-direction: column;
+      gap: 1.5rem;
+    }
+
+    .btn-load-more {
+      padding: 0.75rem 1.5rem;
+      background: var(--c-primary-500);
+      color: white;
+      border: none;
+      border-radius: var(--bor-radius-8);
+      font-weight: 600;
+      cursor: pointer;
+      transition: background 200ms;
+    }
+
+    .btn-load-more:hover:not(:disabled) {
+      background: var(--c-primary-600);
+    }
+
+    .btn-load-more:disabled {
+      background: var(--c-neutral-400);
+      cursor: not-allowed;
+    }
+  `]
+})
+export class DynamicFaqComponent {
+  itemsPerPage = 3;
+  currentPage = signal(1);
+  allQuestionsLoaded = signal(false);
+
+  allQuestions = [
+    { question: 'Pergunta 1?', answer: 'Resposta 1' },
+    { question: 'Pergunta 2?', answer: 'Resposta 2' },
+    { question: 'Pergunta 3?', answer: 'Resposta 3' },
+    { question: 'Pergunta 4?', answer: 'Resposta 4' },
+    { question: 'Pergunta 5?', answer: 'Resposta 5' },
+    { question: 'Pergunta 6?', answer: 'Resposta 6' }
+  ];
+
+  displayedQuestions() {
+    return this.allQuestions.slice(
+      0,
+      this.currentPage() * this.itemsPerPage
+    );
+  }
+
+  loadMoreQuestions() {
+    this.currentPage.update(p => p + 1);
+    if (this.displayedQuestions().length >= this.allQuestions.length) {
+      this.allQuestionsLoaded.set(true);
+    }
+  }
+}
+```
+
+### FAQ com Ícones
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-faq-with-icons',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="faq-tiles">
+      @for (category of categories; track category.icon) {
+        <div class="faq-tile">
+          <div class="tile-header">
+            <i [class]="category.icon"></i>
+            <h3>{{ category.title }}</h3>
+          </div>
+          <tcloud-ui-faq [questions]="category.questions"></tcloud-ui-faq>
+        </div>
+      }
+    </div>
+  `,
+  styles: [`
+    .faq-tiles {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+      gap: 2rem;
+    }
+
+    .faq-tile {
+      border: 1px solid var(--c-neutral-200);
+      border-radius: var(--bor-radius-8);
+      padding: 1.5rem;
+      background: white;
+    }
+
+    .tile-header {
+      display: flex;
+      align-items: center;
+      gap: 1rem;
+      margin-bottom: 1.5rem;
+    }
+
+    .tile-header i {
+      font-size: 1.75rem;
+      color: var(--c-primary-500);
+    }
+
+    .tile-header h3 {
+      margin: 0;
+      font-size: 1.25rem;
+      color: var(--c-neutral-800);
+    }
+  `]
+})
+export class FaqWithIconsComponent {
+  categories = [
+    {
+      title: 'Contas',
+      icon: 'fa-light fa-user',
+      questions: [
+        { question: 'Como criar uma conta?', answer: 'Clique em Registrar...' },
+        { question: 'Como fazer login?', answer: 'Use suas credenciais...' }
+      ]
+    },
+    {
+      title: 'Compras',
+      icon: 'fa-light fa-shopping-bag',
+      questions: [
+        { question: 'Como comprar?', answer: 'Adicione itens ao carrinho...' },
+        { question: 'Posso cancelar?', answer: 'Sim, dentro de 24 horas...' }
+      ]
+    },
+    {
+      title: 'Suporte',
+      icon: 'fa-light fa-headset',
+      questions: [
+        { question: 'Como contatar suporte?', answer: 'Use o chat or email...' },
+        { question: 'Qual o horário?', answer: '24/7 durante semana...' }
+      ]
+    }
+  ];
+}
+```
+
+## Animações
+
+O componente inclui animações suaves:
+
+- **Altura**: Transição de 56px (fechado) para auto (aberto) em 0.2s
+- **Ícone**: Rotação de 180° da seta ao expandir em 0.3s
+- **Overflow**: Controle automático de overflow durante a transição
+
+## Responsividade
+
+O componente é totalmente responsivo:
+
+- **Desktop**: Layout completo com estilos otimizados
+- **Mobile**: Adaptado para telas pequenas com padding reduzido
+- **Tablet**: Escala intermediária
+
+## Estilos Padrão
+
+- **Fundo**: `var(--c-neutral-50)` (cinza muito claro)
+- **Borda**: `1px solid var(--c-neutral-300)`
+- **Texto**: `var(--c-neutral-700)` com tamanho 16px
+- **Altura fechado**: 56px
+- **Padding**: 16px
+- **Cursor**: pointer ao passar sobre a pergunta
+
+## Casos de Uso
+
+- Página de FAQ do site
+- Seção de ajuda em aplicações
+- Documentação interativa
+- Suporte ao cliente
+- Centro de conhecimento
+- Guias de troubleshooting
+- Perguntas sobre produtos
+- Informações sobre politicas
+- Instruções de uso
+- Respostas a dúvidas recorrentes
+
+## Performance
+
+- Usa `ChangeDetectionStrategy.OnPush` para melhor performance
+- Signals para reatividade eficiente
+- Renderização otimizada com `*ngFor`
+
+## Acessibilidade
+
+- Botões clicáveis com cursor pointer
+- Setas visuais indicando estado
+- Estrutura semântica clara
+- Suporta navegação por teclado (clique em qualquer pergunta)
+
+## Dicas de Customização
+
+1. **Cores**: Customize através de CSS custom properties (--c-neutral-*)
+2. **Fontes**: Use a família `var(--f-family)`
+3. **Animações**: Ajuste de duração no SCSS (0.2s e 0.3s)
+4. **Espaçamento**: Modifique padding e margin conforme necessário

package/docs/tcloud-ui-filter-bar.md

@@ -0,0 +1,86 @@
+# Filter Bar
+
+## Características
+
+O `TCloudUiFilterBarComponent` é um componente Angular standalone que exibe uma barra de filtros com um botão de ação "Filtrar". Ao ser clicado, o botão emite um evento com os parâmetros de filtro configurados.
+
+Funcionalidades principais:
+- Controle de filtro por estado de lock (`com`, `sem`, `todos`).
+- Emissão de evento `filterApply` ao aplicar o filtro.
+- Layout flexbox com espaçamento configurável.
+
+## Instalação
+
+Importe o `TCloudUiFilterBarComponent` no componente standalone:
+
+```typescript
+import { TCloudUiFilterBarComponent } from 'tcloud-ui';
+
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [TCloudUiFilterBarComponent],
+    template: '...'
+})
+export class ExemploComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+Este componente não possui `@Input()` públicos. O estado interno `lock` é gerenciado internamente.
+
+### Outputs
+
+| Nome        | Tipo de Evento                              | Descrição                                           |
+|-------------|---------------------------------------------|-----------------------------------------------------|
+| filterApply | `{ lock?: 'com' \| 'sem' \| 'todos' }`     | Emitido ao clicar no botão "Filtrar", contendo o estado atual do filtro. |
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```html
+<tcloud-ui-filter-bar (filterApply)="onFilterApply($event)"></tcloud-ui-filter-bar>
+```
+
+```typescript
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [TCloudUiFilterBarComponent],
+    template: `
+      <tcloud-ui-filter-bar (filterApply)="onFilterApply($event)"></tcloud-ui-filter-bar>
+    `
+})
+export class ExemploComponent {
+  onFilterApply(event: { lock?: 'com' | 'sem' | 'todos' }): void {
+    console.log('Filtro aplicado:', event);
+  }
+}
+```
+
+### Uso Avançado — Reagindo ao Evento de Filtro
+
+```typescript
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [CommonModule, TCloudUiFilterBarComponent],
+    template: `
+      <tcloud-ui-filter-bar (filterApply)="onFilterApply($event)"></tcloud-ui-filter-bar>
+      <div *ngIf="appliedFilter">
+        <p>Filtro aplicado: {{ appliedFilter.lock }}</p>
+      </div>
+    `
+})
+export class ExemploComponent {
+  appliedFilter: { lock?: 'com' | 'sem' | 'todos' } | null = null;
+
+  onFilterApply(event: { lock?: 'com' | 'sem' | 'todos' }): void {
+    this.appliedFilter = event;
+    // Realizar chamada HTTP ou filtragem local
+  }
+}
+```