@dev-tcloud/tcloud-ui 6.15.0 → 6.18.0

package/docs/tcloud-ui-array-to-text.md

@@ -0,0 +1,361 @@
+# Array To Text
+
+O pipe **Array To Text** transforma um array em uma string formatada com separação por vírgulas e conjunção "e" antes do último elemento. É útil para exibir listas de valores de forma legível e gramaticalmente correta.
+
+## Características
+
+- **Formatação legível**: Converte arrays em texto com vírgulas e conjunção "e"
+- **Tratamento de listas**: Separa items com ", " (vírgula-espaço)
+- **Conjunção gramatical**: Usa "e " antes do último item
+- **Validação de entrada**: Verifica se o array tem conteúdo antes de processar
+- **Standalone**: Pode ser usado em qualquer template após importação no componente
+
+## Instalação
+
+```typescript
+import { TCloudUiModule } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  imports: [TCloudUiModule],
+  // ... resto da configuração
+})
+export class MyComponent {}
+```
+
+## Propriedades (API)
+
+### Nome do Pipe
+
+| Nome | Descrição |
+|------|-----------|
+| `toText` | Nome do pipe usado na sintaxe de template |
+
+### Transform
+
+| Parâmetro | Tipo | Descrição |
+|-----------|------|-----------|
+| `value` | `any[]` | Array de valores a serem transformados em texto |
+
+### Retorno
+
+| Tipo | Descrição |
+|------|-----------|
+| `string` | String formatada com items separados por vírgulas e "e" antes do último item |
+| `any` | Retorna o valor original se for vazio ou nulo |
+
+## Comportamento de Transformação
+
+### Regra de Formatação
+
+O pipe segue a seguinte formatação:
+- **Um item**: `valor1` → `valor1`
+- **Dois items**: `[valor1, valor2]` → `valor1 e valor2`
+- **Três ou mais items**: `[valor1, valor2, valor3]` → `valor1, valor2 e valor3`
+
+### Exemplos de Transformação
+
+| Input | Output |
+|-------|--------|
+| `['item']` | `item` |
+| `['item1', 'item2']` | `item1 e item2` |
+| `['item1', 'item2', 'item3']` | `item1, item2 e item3` |
+| `['A', 'B', 'C', 'D']` | `A, B, C e D` |
+| `[]` | `[]` |
+| `null` | `null` |
+
+## Exemplos de Uso
+
+### Uso Básico
+
+Transformação simples de um array em formato legível:
+
+```typescript
+@Component({
+  selector: 'app-array-basic',
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div>
+      <h3>Frutas Selecionadas:</h3>
+      <p>{{ fruits | toText }}</p>
+    </div>
+  `
+})
+export class ArrayBasicComponent {
+  fruits = ['Maçã', 'Banana', 'Laranja', 'Morango'];
+}
+```
+
+**Output esperado:** `Maçã, Banana, Laranja e Morango`
+
+### Uso com Listas Dinâmicas
+
+Exibição de items selecionados com pipe:
+
+```typescript
+@Component({
+  selector: 'app-array-dynamic',
+  imports: [CommonModule, ReactiveFormsModule, TCloudUiModule],
+  template: `
+    <div>
+      <h3>Permissões Concedidas:</h3>
+      
+      <div class="permissions-list">
+        <label *ngFor="let perm of availablePermissions">
+          <input 
+            type="checkbox" 
+            [value]="perm"
+            [formControl]="selectedPermissions"
+          >
+          {{ perm }}
+        </label>
+      </div>
+
+      <div *ngIf="selectedPermissions.value && selectedPermissions.value.length > 0" class="result">
+        <p><strong>Permissões ativas:</strong></p>
+        <p>{{ selectedPermissions.value | toText }}</p>
+      </div>
+
+      <div *ngIf="!selectedPermissions.value || selectedPermissions.value.length === 0" class="empty">
+        Nenhuma permissão selecionada
+      </div>
+    </div>
+  `
+})
+export class ArrayDynamicComponent {
+  availablePermissions = ['Leitura', 'Escrita', 'Exclusão', 'Exportação', 'Configuração'];
+  selectedPermissions = new FormControl([], { nonNullable: true });
+}
+```
+
+### Uso Avançado com Transformação de Dados
+
+Pipeline de transformação para exibir dados estruturados:
+
+```typescript
+@Component({
+  selector: 'app-array-advanced',
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="recipients-group">
+      <h3>Configuração de E-mails</h3>
+
+      <div class="recipient-section">
+        <h4>Destinatários Para (To):</h4>
+        <div *ngIf="emailConfig.to.length > 0" class="email-list">
+          {{ emailConfig.to.map(e => e.email) | toText }}
+        </div>
+        <div *ngIf="emailConfig.to.length === 0" class="empty-state">
+          Nenhum destinatário adicionado
+        </div>
+      </div>
+
+      <div class="recipient-section">
+        <h4>Destinatários CC:</h4>
+        <div *ngIf="emailConfig.cc.length > 0" class="email-list">
+          {{ emailConfig.cc.map(e => e.email) | toText }}
+        </div>
+        <div *ngIf="emailConfig.cc.length === 0" class="empty-state">
+          Nenhum CC adicionado
+        </div>
+      </div>
+
+      <div class="recipient-section">
+        <h4>Tópicos Relacionados:</h4>
+        <div *ngIf="topics.length > 0">
+          {{ topics | toText }}
+        </div>
+      </div>
+
+      <div class="preview">
+        <h4>Prévia do Resumo:</h4>
+        <p>Este e-mail será enviado para {{ emailConfig.to.length }} destinatário(s) {{ (emailConfig.cc.length > 0 ? 'com ' + emailConfig.cc.length + ' em cópia' : 'sem cópia') }}.</p>
+        <p *ngIf="topics.length > 0">Tópicos abordados: {{ topics | toText }}</p>
+      </div>
+    </div>
+  `
+})
+export class ArrayAdvancedComponent {
+  emailConfig = {
+    to: [
+      { email: 'user1@example.com', name: 'Usuário 1' },
+      { email: 'user2@example.com', name: 'Usuário 2' },
+      { email: 'user3@example.com', name: 'Usuário 3' }
+    ],
+    cc: [
+      { email: 'admin@example.com', name: 'Administrador' }
+    ]
+  };
+
+  topics = ['Relatório Mensal', 'Planejamento Q1', 'Performance de Vendas'];
+}
+```
+
+### Uso com Filtros e Busca
+
+Aplicar o pipe após transformar dados verificados:
+
+```typescript
+@Component({
+  selector: 'app-array-filtered',
+  imports: [CommonModule, FormsModule, TCloudUiModule],
+  template: `
+    <div>
+      <h3>Filtrar e Exibir Departamentos</h3>
+
+      <input 
+        type="text" 
+        placeholder="Buscar departamento..."
+        [(ngModel)]="searchTerm"
+        (ngModelChange)="filterDepartments()"
+      >
+
+      <div *ngIf="filteredDepartments.length > 0" class="result">
+        <p><strong>Departamentos encontrados:</strong></p>
+        <p>{{ filteredDepartments | toText }}</p>
+      </div>
+
+      <div *ngIf="filteredDepartments.length === 0 && searchTerm" class="no-results">
+        Nenhum departamento encontrado para "{{ searchTerm }}"
+      </div>
+
+      <div *ngIf="filteredDepartments.length === 0 && !searchTerm" class="info">
+        Digite para filtrar departamentos
+      </div>
+
+      <div class="all-departments">
+        <h4>Todos os Departamentos ({{ departments.length }}):</h4>
+        <p>{{ departments | toText }}</p>
+      </div>
+    </div>
+  `
+})
+export class ArrayFilteredComponent {
+  departments = [
+    'Desenvolvimento',
+    'Design',
+    'Recursos Humanos',
+    'Financeiro',
+    'Vendas',
+    'Suporte',
+    'Operações',
+    'Marketing'
+  ];
+
+  filteredDepartments: string[] = [];
+  searchTerm: string = '';
+
+  ngOnInit() {
+    this.filteredDepartments = [...this.departments];
+  }
+
+  filterDepartments() {
+    if (!this.searchTerm.trim()) {
+      this.filteredDepartments = [...this.departments];
+    } else {
+      this.filteredDepartments = this.departments.filter(dept =>
+        dept.toLowerCase().includes(this.searchTerm.toLowerCase())
+      );
+    }
+  }
+}
+```
+
+### Uso com Validação de Formulário
+
+Exibir campos com erro usando o pipe:
+
+```typescript
+@Component({
+  selector: 'app-array-validation',
+  imports: [CommonModule, ReactiveFormsModule, TCloudUiModule],
+  template: `
+    <form [formGroup]="form">
+      <div class="form-group">
+        <label>Nome:</label>
+        <input formControlName="name" type="text">
+      </div>
+
+      <div class="form-group">
+        <label>Email:</label>
+        <input formControlName="email" type="email">
+      </div>
+
+      <div class="form-group">
+        <label>Telefone:</label>
+        <input formControlName="phone" type="tel">
+      </div>
+
+      <button (click)="validate()">Validar</button>
+
+      <div *ngIf="errorFields.length > 0" class="error-summary">
+        <h4>Campos com erro:</h4>
+        <p>{{ errorFields | toText }}</p>
+        <ul>
+          <li *ngFor="let field of errorFields">
+            {{ field }}: {{ getFieldError(field) }}
+          </li>
+        </ul>
+      </div>
+
+      <div *ngIf="isValid && errorFields.length === 0" class="success">
+        ✓ Formulário válido!
+      </div>
+    </form>
+  `
+})
+export class ArrayValidationComponent {
+  form: FormGroup;
+  errorFields: string[] = [];
+  isValid: boolean = false;
+
+  constructor(private fb: FormBuilder) {
+    this.form = this.fb.group({
+      name: ['', [Validators.required, Validators.minLength(3)]],
+      email: ['', [Validators.required, Validators.email]],
+      phone: ['', Validators.required]
+    });
+  }
+
+  validate() {
+    this.errorFields = [];
+    this.isValid = false;
+
+    Object.keys(this.form.controls).forEach(fieldName => {
+      const field = this.form.get(fieldName);
+      if (field && field.invalid) {
+        this.errorFields.push(fieldName);
+      }
+    });
+
+    this.isValid = this.errorFields.length === 0;
+  }
+
+  getFieldError(fieldName: string): string {
+    const field = this.form.get(fieldName);
+    if (field?.hasError('required')) {
+      return 'Campo obrigatório';
+    }
+    if (field?.hasError('minlength')) {
+      return 'Deve conter pelo menos 3 caracteres';
+    }
+    if (field?.hasError('email')) {
+      return 'Email inválido';
+    }
+    return 'Erro de validação';
+  }
+}
+```
+
+## Notas de Implementação
+
+- O pipe é **standalone** e pode ser importado diretamente em componentes
+- A transformação ocorre no template usando a sintaxe de pipe Angular: `{{ array | toText }}`
+- Se o array estiver vazio ou nulo, retorna o valor original sem transformação
+- O pipe funciona com arrays de qualquer tipo (strings, números, objetos)
+- A formatação usa ", " (vírgula com espaço) como separador entre items
+- Usa " e " (espaço-e-espaço) como conjunção antes do último item
+- Não há limite de items - funciona com arrays de qualquer tamanho
+- O pipe é **imutável** - não modifica o array original
+- Para arrays com um único item, retorna apenas esse item sem separadores
+- A transformação responde a mudanças do array em tempo real (change detection)
+- Pode ser combinado com outros pipes (ex: `{{ items | filter:condition | toText }}`)

package/docs/tcloud-ui-breadcrumb.md

@@ -0,0 +1,103 @@
+# Breadcrumb
+
+Componente de navegação breadcrumb que exibe o caminho hierárquico da página atual, permitindo navegação rápida entre níveis.
+
+## Características
+
+- Exibe trilha de navegação hierárquica
+- Ícone de "home" com link para o dashboard
+- Separadores visuais entre itens (chevron)
+- Último item aparece como texto (sem link), indicando a página atual
+- Navegação por clique nos itens intermediários
+- Serviço injetável (`TCloudUiBreadcrumbService`) para gerenciar os itens do breadcrumb de qualquer componente
+- Suporte a adição e remoção dinâmica de níveis
+
+## Instalação
+
+```typescript
+import { TCloudUiModule } from 'tcloud-ui';
+
+@NgModule({
+  imports: [TCloudUiModule]
+})
+export class AppModule { }
+```
+
+Ou importe o componente standalone diretamente:
+
+```typescript
+import { TCloudUiBreadcrumbComponent } from 'tcloud-ui';
+
+@Component({
+  imports: [TCloudUiBreadcrumbComponent]
+})
+export class MeuComponent { }
+```
+
+## API - Serviço (`TCloudUiBreadcrumbService`)
+
+### Interface `BreadcrumbItem`
+
+| Propriedade | Tipo     | Descrição                                |
+|-------------|----------|------------------------------------------|
+| `label`     | `string` | Texto exibido no item do breadcrumb      |
+| `url`       | `string` | URL de navegação (opcional no último item)|
+
+### Métodos
+
+| Método              | Parâmetro              | Descrição                                        |
+|---------------------|------------------------|--------------------------------------------------|
+| `setBreadcrumb`     | `items: BreadcrumbItem[]` | Define a lista completa de itens do breadcrumb |
+| `addLevel`          | `item: BreadcrumbItem`    | Adiciona um novo nível ao final do breadcrumb  |
+| `removeLastLevel`   | —                         | Remove o último nível do breadcrumb            |
+| `clear`             | —                         | Limpa todos os itens do breadcrumb             |
+
+### Observable
+
+| Nome            | Tipo                          | Descrição                              |
+|-----------------|-------------------------------|----------------------------------------|
+| `breadcrumbs$`  | `Observable<BreadcrumbItem[]>`| Observable com a lista atual de itens  |
+
+## Exemplos de Uso
+
+### Uso Básico
+
+No template:
+
+```html
+<tcloud-ui-breadcrumb></tcloud-ui-breadcrumb>
+```
+
+No componente, defina os itens via serviço:
+
+```typescript
+import { TCloudUiBreadcrumbService } from 'tcloud-ui';
+
+export class MinhaPaginaComponent implements OnInit {
+
+  constructor(private breadcrumbService: TCloudUiBreadcrumbService) {}
+
+  ngOnInit(): void {
+    this.breadcrumbService.setBreadcrumb([
+      { label: 'Home', url: '/dashboard' },
+      { label: 'Produtos', url: '/produtos' },
+      { label: 'Detalhes' }
+    ]);
+  }
+}
+```
+
+### Uso Avançado
+
+Adicionando níveis dinamicamente conforme a navegação:
+
+```typescript
+// Ao entrar em um sub-nível
+this.breadcrumbService.addLevel({ label: 'Edição', url: '/produtos/editar' });
+
+// Ao voltar, remover o último nível
+this.breadcrumbService.removeLastLevel();
+
+// Limpar completamente ao sair de uma seção
+this.breadcrumbService.clear();
+```

package/docs/tcloud-ui-bytes.md

@@ -0,0 +1,109 @@
+# BytesPipe
+
+O pipe `bytes` converte valores numéricos representando tamanhos de dados em uma string legível com a unidade apropriada (Bytes, KB, MB, GB, TB, PB, EB, ZB, YB). A conversão é automática com base na magnitude do valor, utilizando potências de 1024. Aceita um parâmetro opcional para indicar que o valor de entrada já está em KB ou MB, realizando a conversão para bytes antes de formatar.
+
+## Características
+
+- Conversão automática de bytes para a unidade mais adequada (Bytes, KB, MB, GB, TB, etc.)
+- Suporte a parâmetro opcional `typeValue` para indicar a unidade de entrada (`'kb'` ou `'mb'`)
+- Precisão de 2 casas decimais por padrão
+- Retorna `'---'` para valores falsy (null, undefined, vazio)
+- Retorna `'0 Bytes'` para o valor zero
+- Pipe standalone
+
+## Instalação
+
+Importe o pipe diretamente no módulo ou componente standalone:
+
+```typescript
+import { BytesPipe } from 'tcloud-ui';
+```
+
+## API
+
+### Sintaxe do Pipe
+
+```
+{{ valor | bytes }}
+{{ valor | bytes:'kb' }}
+{{ valor | bytes:'mb' }}
+```
+
+### Parâmetros
+
+| Parâmetro   | Tipo     | Obrigatório | Descrição                                                                                   |
+|-------------|----------|-------------|----------------------------------------------------------------------------------------------|
+| `typeValue` | `string` | Não         | Unidade do valor de entrada. Valores aceitos: `'kb'` (kilobytes) ou `'mb'` (megabytes). Quando informado, o valor é convertido para bytes antes da formatação |
+
+### Tabela de Conversão
+
+| Unidade | Faixa                        |
+|---------|------------------------------|
+| Bytes   | 0 – 1.023                    |
+| KB      | 1.024 – 1.048.575            |
+| MB      | 1.048.576 – 1.073.741.823    |
+| GB      | 1.073.741.824 – 1.099.511.627.775 |
+| TB      | 1.099.511.627.776+           |
+
+## Exemplos de Uso
+
+### Básico — Conversão automática a partir de bytes
+
+```html
+<p>{{ 123456789 | bytes }}</p>
+<!-- Resultado: 117.74 MB -->
+
+<p>{{ 1024 | bytes }}</p>
+<!-- Resultado: 1 KB -->
+
+<p>{{ 0 | bytes }}</p>
+<!-- Resultado: 0 Bytes -->
+```
+
+```typescript
+import { BytesPipe } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [BytesPipe],
+  template: `
+    <p>{{ valorBytes | bytes }}</p>
+  `
+})
+export class ExemploBasicoComponent {
+  valorBytes = 123456789;
+}
+```
+
+### Avançado — Valor de entrada em KB ou MB
+
+```html
+<!-- Entrada em kilobytes -->
+<p>{{ 2048 | bytes:'kb' }}</p>
+<!-- Resultado: 2 MB (2048 KB = 2.097.152 bytes = 2 MB) -->
+
+<!-- Entrada em megabytes -->
+<p>{{ 5 | bytes:'mb' }}</p>
+<!-- Resultado: 5 MB (5 MB = 5.242.880 bytes = 5 MB) -->
+
+<!-- Entrada em megabytes com valor grande -->
+<p>{{ 2500 | bytes:'mb' }}</p>
+<!-- Resultado: 2.44 GB -->
+```
+
+```typescript
+import { BytesPipe } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [BytesPipe],
+  template: `
+    <p>{{ armazenamentoKB | bytes:'kb' }}</p>
+    <p>{{ armazenamentoMB | bytes:'mb' }}</p>
+  `
+})
+export class ExemploAvancadoComponent {
+  armazenamentoKB = 2048;
+  armazenamentoMB = 5;
+}
+```