@dev-tcloud/tcloud-ui 6.15.0 → 6.18.0

package/docs/tcloud-ui-pagination.md

@@ -0,0 +1,579 @@
+# TCloud UI Pagination
+
+Componente Angular standalone para paginação com suporte a múltiplas instâncias independentes e detecção automática de mudanças de dados.
+
+## Características
+
+- ✅ **Múltiplas instâncias independentes** - Cada paginação funciona isoladamente
+- ✅ **Detecção automática de filtros** - Reseta para página 1 quando dados mudam
+- ✅ **ChangeDetection OnPush** - Otimizado para performance
+- ✅ **Pipe para fatiar dados** - `TCloudUiPagination` pipe integrado
+- ✅ **Serviço reativo** - Baseado em RxJS Subjects
+
+## Instalação
+
+O componente já está disponível no módulo `TCloudUiModule`:
+
+```typescript
+import { TCloudUiModule } from 'projects/tcloud-ui/src/public-api';
+
+@NgModule({
+  imports: [TCloudUiModule]
+})
+export class MyModule { }
+```
+
+Ou importar direto o componente (standalone):
+
+```typescript
+import { TCloudUiPaginationComponent } from 'projects/tcloud-ui/src/lib/_modules/tcloud-ui-pagination/tcloud-ui-pagination.component';
+import { TCloudUiPaginationPipe } from 'projects/tcloud-ui/src/lib/_modules/tcloud-ui-pagination/pipes/tcloud-ui-pagination.pipe';
+
+@Component({
+  imports: [TCloudUiPaginationComponent, TCloudUiPaginationPipe]
+})
+```
+
+## Uso Básico
+
+### 1. Exemplo Simple - Uma Paginação
+
+```typescript
+// Componente TypeScript
+export class MyComponent {
+  items = [
+    { name: "Item 1", value: 100 },
+    { name: "Item 2", value: 200 },
+    // ...
+  ];
+  
+  currentPage: number = 1;
+  itemsPerPage: number = 5;
+  
+  onPageChange(newPage: number) {
+    this.currentPage = newPage;
+  }
+}
+```
+
+```html
+<!-- Template HTML -->
+<table>
+  <tr *ngFor="let item of items | TCloudUiPagination: { 
+    currentPage: currentPage, 
+    itemsPerPage: itemsPerPage, 
+    id: 'my-pagination' 
+  }">
+    <td>{{ item.name }}</td>
+    <td>{{ item.value }}</td>
+  </tr>
+</table>
+
+<tcloud-ui-pagination 
+  [id]="'my-pagination'"
+  [currentPage]="currentPage"
+  (pageChange)="onPageChange($event)">
+</tcloud-ui-pagination>
+```
+
+### 2. Exemplo Avançado - Múltiplas Paginações Independentes
+
+```typescript
+export class MyComponent {
+  // Primeira tabela
+  items: any[] = [/* dados */];
+  currentPage: number = 1;
+  itemsPerPage: number = 4;
+  
+  // Segunda tabela (com filtro)
+  resultItems: any[] = [];
+  currentPage2: number = 1;
+  itemsPerPage2: number = 3;
+  
+  onPageChange(newPage: number) {
+    this.currentPage = newPage;
+  }
+  
+  onPageChange2(newPage: number) {
+    this.currentPage2 = newPage;
+  }
+  
+  searchInItems(event: any) {
+    const search = event?.target?.value;
+    // Filtrar dados
+    this.resultItems = this.items.filter(item => 
+      item.name.toLowerCase().includes(search.toLowerCase())
+    );
+    // currentPage2 será resetado automaticamente pelo pipe
+  }
+}
+```
+
+```html
+<!-- Primeira Tabela -->
+<table>
+  <tr *ngFor="let item of items | TCloudUiPagination: { 
+    currentPage: currentPage, 
+    itemsPerPage: itemsPerPage, 
+    id: 'pagination-1' 
+  }">
+    <td>{{ item.name }}</td>
+  </tr>
+</table>
+
+<tcloud-ui-pagination 
+  [id]="'pagination-1'"
+  [currentPage]="currentPage"
+  (pageChange)="onPageChange($event)">
+</tcloud-ui-pagination>
+
+<hr>
+
+<!-- Filtro -->
+<input type="text" placeholder="Buscar..." (input)="searchInItems($event)">
+
+<!-- Segunda Tabela (com Filtro) -->
+<table>
+  <tr *ngFor="let item of resultItems | TCloudUiPagination: { 
+    currentPage: currentPage2, 
+    itemsPerPage: itemsPerPage2, 
+    id: 'result-pagination' 
+  }">
+    <td>{{ item.name }}</td>
+  </tr>
+</table>
+
+<tcloud-ui-pagination 
+  [id]="'result-pagination'"
+  [currentPage]="currentPage2"
+  (pageChange)="onPageChange2($event)">
+</tcloud-ui-pagination>
+```
+
+## API
+
+### Componente: `tcloud-ui-pagination`
+
+#### Inputs
+
+| Propriedade | Tipo | Padrão | Descrição | Obrigatório |
+|-----------|------|--------|-----------|---|
+| `id` | `string` | Auto-gerado se não fornecido | ID único para sincronização entre pipe e componente | ❌ |
+| `currentPage` | `number` | `1` | Página atual (1-based index: 1, 2, 3...) | ❌ |
+
+#### Outputs
+
+| Propriedade | Tipo | Descrição |
+|-----------|------|-----------|
+| `pageChange` | `EventEmitter<number>` | Emitido quando a página muda |
+
+#### Propriedades Públicas (Getters)
+
+| Propriedade | Tipo | Descrição | Writable |
+|-----------|------|-----------|---|
+| `totalPages` | `number` | Total de páginas calculado pelo serviço | ❌ |
+| `pageInputError` | `boolean` | Indica erro na entrada do campo 'ir para página' | ❌ |
+
+#### Métodos
+
+| Método | Descrição |
+|--------|-----------|
+| `previous(): void` | Navega para a página anterior (se não estiver na página 1) |
+| `next(): void` | Navega para a próxima página (se não estiver na última) |
+| `goToPage(event: Event): void` | Extrai page do input e navega; valida limites (1 até totalPages) |
+| `formatPage(page: number): string` | Formata com zero à esquerda (ex: 05, 10, 25) |
+| `getTotal(): IPagination` | Retorna objeto com dados de paginação desta instância do serviço |
+
+### Pipe: `TCloudUiPagination`
+
+Fatia um array baseado na paginação.
+
+#### Parâmetro
+
+```typescript
+TCloudUiPagination: {
+  currentPage: number;      // Página atual
+  itemsPerPage: number;     // Itens por página
+  id?: string;              // ID único (opcional, padrão: '1')
+}
+```
+
+#### Retorno
+
+Array com os itens paginados.
+
+### Serviço: `TCloudUiPaginationService`
+
+Gerencia o estado de paginação de múltiplas instâncias de forma centralizada usando Map(id → estado).
+
+#### Propriedades Públicas
+
+| Propriedade | Tipo | Descrição | Uso |
+|-----------|------|-----------|---|
+| `stateTotal$` | `BehaviorSubject<IPagination[]>` | Emite array de estados de paginação sempre que houver mudanças; subscribers recebem histórico | Pipe e componente escutam |
+| `collectionChanged$` | `Subject<string>` | Emite ID da coleção que mudou (detectado pelo pipe) | Notificação de mudança de dados |
+
+#### Métodos
+
+| Método | Descrição |
+|--------|-----------|
+| `set_total(args: {id?, currentPage, itemsPerPage}, total: number): void` | Cria ou atualiza entrada no Map de paginações; emite via `stateTotal$` |
+| `get_total(): IPagination[]` | Retorna array de todas as paginações armazenadas |
+| `resetToFirstPage(id: string): void` | Reseta página específica para 1 e emite |
+| `notifyCollectionChange(id: string): void` | Emite via `collectionChanged$` para notificar mudança de tamanho |
+
+## Comportamento Detalhado
+
+### 1. Fluxo de Detecção Automática (Quando Filtro é Aplicado)
+
+```
+Filtro: this.resultItems = items.filter(...)
+  ↓
+Pipe detecta: array.length diferente
+  ↓
+Pipe reseta: args.currentPage = 1
+  ↓
+Pipe chama: service.notifyCollectionChange(id)
+  ↓
+Serviço emite: collectionChanged$ → {id}
+  ↓
+Componente escuta: markForCheck() ativado
+  ↓
+Template renderiza: página 1 dos novos dados
+```
+
+**Função do Map no Pipe:**
+```typescript
+private _previousLengths: Map<string, number> = new Map();
+
+// Detecta se tamanho mudou:
+if (previousLength !== currentLength && previousLength > 0) {
+  args.currentPage = 1;  // Reset automático
+  service.notifyCollectionChange(args.id);  // Notifica
+}
+```
+
+### 2. Sincronização de Múltiplas Instâncias
+
+Cada instância precisa de um `id` único, que é o mesmo tanto no pipe quanto no componente:
+
+```typescript
+// Primeira instância
+items | TCloudUiPagination: { currentPage: currentPage, itemsPerPage: 4, id: 'pagination-1' }
+<tcloud-ui-pagination [id]="'pagination-1'" ...></tcloud-ui-pagination>
+
+// Segunda instância (independente) 
+resultItems | TCloudUiPagination: { currentPage: currentPage2, itemsPerPage: 3, id: 'result-pagination' }
+<tcloud-ui-pagination [id]="'result-pagination'" ...></tcloud-ui-pagination>
+```
+
+**Armazenamento no Serviço:**
+```
+TCloudUiPaginationService
+  ├─ Map<'pagination-1', {total: 3, current: 1, ...}>
+  └─ Map<'result-pagination', {total: 2, current: 1, ...}>
+```
+
+**Resultado:**
+- ✅ Navegação independente em cada tabela
+- ✅ Filtro de uma não afeta a outra
+- ✅ Cada instance pode ter itemsPerPage diferente
+- ✅ Resets automáticos funcionam isoladamente
+
+## Performance e ChangeDetection
+
+### OnPush Strategy
+
+O componente usa `ChangeDetectionStrategy.OnPush` para otimização:
+
+```typescript
+@Component({
+  selector: 'tcloud-ui-pagination',
+  changeDetection: ChangeDetectionStrategy.OnPush,  // ← Apenas detecta quando @Input muda
+  standalone: true,
+})
+export class TCloudUiPaginationComponent { }
+```
+
+**Comportamento:**
+- Só detecta mudanças quando `@Input` é alterado
+- Quando serviço emite, componente chama `markForCheck()` manualmente
+- Promove performance em listas grandes
+- Requer cuidado ao emitir eventos (use `Promise.resolve().then()`)
+
+**Emissão de Eventos com Segurança:**
+```typescript
+// ❌ Causa ExpressionChangedAfterItHasBeenCheckedError
+this.pageChange.emit(1);
+
+// ✅ Seguro - Deferred to next microtask
+Promise.resolve().then(() => {
+  this.pageChange.emit(1);
+});
+```
+
+## Exemplo Completo com Tipos
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { TCloudUiPaginationComponent, TCloudUiPaginationPipe } from 'projects/tcloud-ui/src/public-api';
+
+interface Item {
+  id: number;
+  name: string;
+  value: number;
+}
+
+@Component({
+  selector: 'app-pagination-demo',
+  standalone: true,
+  imports: [CommonModule, TCloudUiPaginationComponent, TCloudUiPaginationPipe],
+  template: `
+    <div class="container">
+      <h2>Tabela Principal</h2>
+      <table>
+        <thead>
+          <tr>
+            <th>#</th>
+            <th>Nome</th>
+            <th>Valor</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr *ngFor="let item of items | TCloudUiPagination: paginationConfig1; let i = index">
+            <td>{{ (currentPage - 1) * paginationConfig1.itemsPerPage + i + 1 }}</td>
+            <td>{{ item.name }}</td>
+            <td>{{ item.value }}</td>
+          </tr>
+        </tbody>
+      </table>
+      
+      <tcloud-ui-pagination 
+        [id]="'table-1'"
+        [currentPage]="currentPage"
+        (pageChange)="onPageChange1($event)">
+      </tcloud-ui-pagination>
+
+      <hr>
+
+      <h2>Tabela com Filtro</h2>
+      <input 
+        type="text" 
+        placeholder="Filtrar..." 
+        (input)="onFilter($event)">
+
+      <table>
+        <thead>
+          <tr>
+            <th>#</th>
+            <th>Nome</th>
+            <th>Valor</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr *ngFor="let item of filteredItems | TCloudUiPagination: paginationConfig2; let i = index">
+            <td>{{ (currentPage2 - 1) * paginationConfig2.itemsPerPage + i + 1 }}</td>
+            <td>{{ item.name }}</td>
+            <td>{{ item.value }}</td>
+          </tr>
+        </tbody>
+      </table>
+      
+      <tcloud-ui-pagination 
+        [id]="'table-2'"
+        [currentPage]="currentPage2"
+        (pageChange)="onPageChange2($event)">
+      </tcloud-ui-pagination>
+    </div>
+  `
+})
+export class PaginationDemoComponent implements OnInit {
+  items: Item[] = [
+    { id: 1, name: 'Protheus', value: 154 },
+    { id: 2, name: 'RM', value: 33 },
+    // ... mais itens
+  ];
+
+  filteredItems: Item[] = [];
+  currentPage: number = 1;
+  currentPage2: number = 1;
+
+  paginationConfig1 = { 
+    currentPage: this.currentPage, 
+    itemsPerPage: 4, 
+    id: 'table-1' 
+  };
+
+  paginationConfig2 = { 
+    currentPage: this.currentPage2, 
+    itemsPerPage: 3, 
+    id: 'table-2' 
+  };
+
+  ngOnInit() {
+    this.filteredItems = [...this.items]; // Cópia inicial
+  }
+
+  onPageChange1(newPage: number) {
+    this.currentPage = newPage;
+    this.paginationConfig1 = { ...this.paginationConfig1, currentPage: newPage };
+  }
+
+  onPageChange2(newPage: number) {
+    this.currentPage2 = newPage;
+    this.paginationConfig2 = { ...this.paginationConfig2, currentPage: newPage };
+  }
+
+  onFilter(event: any) {
+    const searchTerm = event.target.value.toLowerCase();
+    this.filteredItems = this.items.filter(item =>
+      item.name.toLowerCase().includes(searchTerm)
+    );
+    // Pipe detectará mudança de tamanho e resetará automaticamente para página 1
+  }
+}
+```
+
+## Boas Práticas
+
+1. **Sempre use IDs únicos** quando houver múltiplas paginações
+   ```typescript
+   [id]="'pagination-1'"  // ✅ Especificado
+   // Sem [id] → ❌ Auto-gerado aleatorily, pode causar conflitos
+   ```
+
+2. **Use o mesmo ID no pipe e no componente**
+   ```html
+   <!-- ✅ Correto -->
+   *ngFor="let item of items | TCloudUiPagination: { ..., id: 'list-1' }"
+   <tcloud-ui-pagination [id]="'list-1'" ...></tcloud-ui-pagination>
+   
+   <!-- ❌ Errado -->
+   *ngFor="let item of items | TCloudUiPagination: { ..., id: 'list-1' }"
+   <tcloud-ui-pagination [id]="'list-2'" ...></tcloud-ui-pagination>
+   ```
+
+3. **Não manipule `currentPage` diretamente**
+   ```typescript
+   // ❌ Evitar
+   this.currentPage = 2;  // Pode causar dessincronização
+   
+   // ✅ Preferir
+   onPageChange(newPage: number) {
+     this.currentPage = newPage;
+   }
+   ```
+
+4. **Mantenha dados imutáveis** para melhor performance com OnPush
+   ```typescript
+   // ❌ Modificação in-place
+   this.items.pop();
+   
+   // ✅ Novo array
+   this.items = this.items.filter(...);
+   this.items = [...this.items];
+   ```
+
+5. **Use `trackBy` em `*ngFor`** para grandes listas
+   ```typescript
+   trackByFn(index: number, item: any) {
+     return item.id;  // Usa propriedade única
+   }
+   
+   *ngFor="let item of items; trackBy: trackByFn"
+   ```
+
+## Troubleshooting
+
+### ❌ Total não aparece no início do componente
+
+**Cause:** Timing do binding antes do serviço emitir
+
+**Solução:**
+```typescript
+// ✅ Agora tem binding direto no template
+get totalPages(): number {
+  return this.getTotal().total;  // Getter sempre sincronizado
+}
+```
+
+### ❌ Paginação 2 afeta Paginação 1
+
+**Verify:**
+- Confirme que os `id` são realmente diferentes no HTML
+- Certifique-se de passar `id` tanto no **pipe** quanto no **componente**
+
+```html
+<!-- ✅ Correto -->
+<ng-container *ngFor="let item of items | TCloudUiPagination: { ..., id: 'p1' }"> ... </ng-container>
+<tcloud-ui-pagination [id]="'p1'" ...></tcloud-ui-pagination>
+
+<ng-container *ngFor="let item of items | TCloudUiPagination: { ..., id: 'p2' }"> ... </ng-container>
+<tcloud-ui-pagination [id]="'p2'" ...></tcloud-ui-pagination>
+```
+
+### ❌ Página não reseta ao filtrar
+
+**Cause:** O pipe detecta mudanças apenas se o tamanho do array muda
+
+**Verificar:**
+1. Array está realmente mudando? Verifique `console.log(items.length)`
+2. Se modificar inline:
+   ```typescript
+   // ❌ Não cria novo array, pipe não detecta
+   this.items.splice(0, 5);
+   
+   // ✅ Cria novo array, pipe detecta
+   this.items = this.items.filter(...);
+   this.items = this.items.slice();
+   this.items = [...this.items];
+   ```
+
+### ❌ ExpressionChangedAfterItHasBeenCheckedError
+
+**Cause:** Emit durante change detection cycle
+
+**Solução:** Use Promise deferred:
+```typescript
+// ✅ Resolvido internamente no componente
+Promise.resolve().then(() => {
+  this.pageChange.emit(1);
+});
+```
+
+## Integração com Serviços Customizados
+
+Você pode integrar o serviço em seus próprios serviços:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class MyDataService {
+  constructor(private pagination: TCloudUiPaginationService) {}
+
+  filterData(term: string, allItems: any[]): any[] {
+    const filtered = allItems.filter(item =>
+      item.name.toLowerCase().includes(term.toLowerCase())
+    );
+    
+    // Notifique o serviço de paginação
+    this.pagination.notifyCollectionChange('my-list-id');
+    
+    // Resete para página 1
+    this.pagination.resetToFirstPage('my-list-id');
+    
+    return filtered;
+  }
+}
+```
+
+## Versionamento
+
+| Versão | Data | Mudanças |
+|--------|------|----------|
+| 1.0.0 | 2026-02-11 | Versão inicial com múltiplas instâncias independentes |
+| 1.0.1 | 2026-02-12 | ✅ Documentação atualizada com detalhes de implementação, Change Detection OnPush, troubleshooting expandido |
+
+## Licença
+
+Parte do TCloud UI Component Library

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

@@ -0,0 +1,65 @@
+# Progress Bar
+
+## Características
+- Barra de progresso standalone com modos de cor (primário, danger, warning, info, success, gray e gradientes).
+- Suporte a diferentes alturas (`normal`, `slim`, `fat`, `very-fat`) e exibição opcional do valor (`showValue`).
+- Aceita limite customizado (`limit`) para escalar percentuais acima de 100% (exibe marcador de 100%).
+- Pode usar ou não o background padrão (`useDefaultBackground`).
+
+## Instalação
+```ts
+import { TCloudUiProgressBarComponent } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiProgressBarComponent],
+  template: `<tcloud-ui-progress-bar status="50"></tcloud-ui-progress-bar>`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+### Inputs
+| Nome | Tipo | Descrição | Valor Default |
+| --- | --- | --- | --- |
+| status | string \| number | Valor percentual exibido (0-100 ou maior quando usado com `limit`). | '0' |
+| limit | string \| number | Limite superior para reescalar o `status` (ex.: 200 escala 200 para 100%). | undefined |
+| mode | string | Tema de cor: `primary`, `danger`, `warning`, `info`, `success`, `gray`, `gradient-success`, `gradient-danger`, `gradient-warning`, `gradient-info`. | 'primary' |
+| height | string | Altura: `normal`, `slim`, `fat`, `very-fat`. | 'normal' |
+| useDefaultBackground | boolean | Aplica fundo padrão da barra. | true |
+| showValue | boolean | Exibe o valor percentual como label quando altura permite. | false |
+
+### Outputs
+| Nome | Tipo de Evento | Descrição |
+| --- | --- | --- |
+| (não possui) | - | Componente não emite eventos. |
+
+## Exemplos de Uso
+### Uso Básico
+```html
+<tcloud-ui-progress-bar status="70"></tcloud-ui-progress-bar>
+```
+
+### Modos e alturas
+```html
+<tcloud-ui-progress-bar status="50" mode="warning" height="fat"></tcloud-ui-progress-bar>
+<tcloud-ui-progress-bar status="30" mode="danger"></tcloud-ui-progress-bar>
+<tcloud-ui-progress-bar status="45" mode="gradient-success" height="very-fat"></tcloud-ui-progress-bar>
+```
+
+### Exibir valor
+```html
+<tcloud-ui-progress-bar status="50" mode="gray" [showValue]="true"></tcloud-ui-progress-bar>
+```
+
+### Usando limite para valores > 100%
+```html
+<!-- Se limit=130 e status=24, o componente recalcula percentuais -->
+<tcloud-ui-progress-bar [status]="24" limit="130" mode="gradient-danger" height="slim"></tcloud-ui-progress-bar>
+```
+
+### Sem background padrão
+```html
+<tcloud-ui-progress-bar [status]="60" [useDefaultBackground]="false" mode="success" height="slim"></tcloud-ui-progress-bar>
+```