ng-firebase-table-kxp 1.0.0 → 1.0.2

package/README.md

@@ -1,84 +1,64 @@
-# Firebase Table KXP Lib
-
-Uma biblioteca Angular poderosa para criar tabelas dinâmicas com integração completa ao Firebase Firestore. Inclui paginação avançada, filtros personalizáveis, ordenação e fallback client-side para queries sem índices.
-
-## ✨ Características
-
-- 🔥 **Integração completa com Firebase/Firestore**
-- 📊 **Paginação otimizada** (client-side e server-side)
-- 🔍 **Sistema de filtros avançado** (texto, data, equals)
-- ⚡ **Fallback automático** quando índices compostos não existem
-- 🎨 **Interface Material Design** com Angular Material
-- 📱 **Responsivo** e adaptável
-- 🔗 **Suporte a relações** entre collections
-- 📥 **Exportação de dados**
-- 🎯 **Altamente configurável**
-
-## 📦 Instalação
-
-### Instalação Simples (npm 7+ / Node 15+)
+# Firebase Table KXP Library
+
+[![npm version](https://badge.fury.io/js/%40adryanmmm%2Ffirebase-table-kxp-lib.svg)](https://www.npmjs.com/package/@adryanmmm/firebase-table-kxp-lib)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Firebase Table KXP Library is a production-ready Angular data table created by **KXP Tech** to power enterprise dashboards backed by Firebase Firestore. It wraps complex Firestore querying, pagination, filtering, and material design styling into a plug-and-play module so teams can ship data-rich experiences faster.
+
+## Table of Contents
+- [Why Firebase Table KXP](#why-firebase-table-kxp)
+- [Core Features](#core-features)
+- [Installation & Setup](#installation--setup)
+- [Configuration Overview](#configuration-overview)
+- [API Reference](#api-reference)
+  - [TableData](#tabledata)
+  - [Column](#column)
+  - [Tab & TabData](#tab--tabdata)
+  - [FilterableOption](#filterableoption)
+  - [Condition](#condition)
+  - [Arrange](#arrange)
+  - [Image](#image)
+  - [Data Export (Download)](#data-export-download)
+- [Powered by KXP Tech](#powered-by-kxp-tech)
+- [Contributing & License](#contributing--license)
+- [Support the Project](#support-the-project)
+
+## Why Firebase Table KXP
+
+- Built and battle-tested at **KXP Tech** across projects with thousands of active users
+- Eliminates weeks of custom table work; drop it in and configure
+- Handles Firestore quirks (pagination, missing indexes, fallbacks) automatically
+- Provides a strongly typed API that scales with project complexity
+- Plays nicely with Angular Material, Firebase, and Angular Fire
+
+## Core Features
+
+- Full Firestore integration with server-side and client-side pagination
+- Text, date, and custom filters with automatic index fallback when needed
+- Configurable columns for relations, custom renderers, actions, and exports
+- Built-in CSV export hooks and actionable buttons per row
+- Pagination, sorting, and filter state shared between tabs
+- Optional color theming, tabbed datasets, and custom navigation per row
+- Works seamlessly with Angular 15, Angular Material, Angular Fire, and RxJS
+
+## Installation & Setup
 
 ```bash
-npm install ng-firebase-table-kxp
+npm install @adryanmmm/firebase-table-kxp-lib
 ```
 
-✅ **Pronto!** Todas as dependências necessárias serão instaladas automaticamente pelo npm 7+.
-
-### Se você usa npm 6 ou anterior
+The host application should already depend on:
 
-Caso esteja usando npm 6 ou anterior (raro hoje em dia), você precisará instalar as peer dependencies manualmente:
-
-```bash
-npm install ng-firebase-table-kxp
-npm install @angular/fire@^15.0.0 firebase@^9.0.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0 ngx-toastr@^16.0.0 moment@^2.29.0 ngx-mask@^15.0.0
-```
-
-**Como verificar sua versão do npm:**
-```bash
-npm --version
-# Se retornar 7.x ou superior, está tudo certo!
-```
+- Angular 15 packages: `@angular/common`, `@angular/core`, `@angular/forms`, `@angular/router`, `@angular/cdk`, `@angular/material`
+- Firebase stack: `@angular/fire` (7.x) and `firebase` (9.x)
+- Utilities: `ngx-toastr` (16.x), `moment` (2.29.x), `ngx-mask` (15.x)
 
-## 🔧 Dependências
-
-A biblioteca usa as seguintes peer dependencies (instaladas automaticamente):
-
-- `@angular/fire` ^15.0.0 - Integração com Firebase
-- `firebase` ^9.0.0 - SDK do Firebase
-- `@angular/material` ^15.0.0 - Componentes Material
-- `@angular/cdk` ^15.0.0 - Component Dev Kit
-- `ngx-toastr` ^16.0.0 - Notificações toast
-- `moment` ^2.29.0 - Manipulação de datas
-- `ngx-mask` ^15.0.0 - Máscaras de input
-
-## 🚀 Configuração
-
-### 1. Importe o módulo no seu `app.module.ts`:
 
+1. **Import the module**
 ```typescript
-import { NgModule } from '@angular/core';
-import { BrowserModule } from '@angular/platform-browser';
-import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
-
-// Firebase
-import { AngularFireModule } from '@angular/fire/compat';
-import { AngularFirestoreModule } from '@angular/fire/compat/firestore';
-
-// Toastr
-import { ToastrModule } from 'ngx-toastr';
-
-// Firebase Table KXP Lib
-import { FirebaseTableKxpLibModule } from 'ng-firebase-table-kxp';
-
-// Mask
-import { NgxMaskModule } from 'ngx-mask';
-
-import { environment } from '../environments/environment';
+import { FirebaseTableKxpLibModule } from '@adryanmmm/firebase-table-kxp-lib';
 
 @NgModule({
-  declarations: [
-    AppComponent
-  ],
   imports: [
     BrowserModule,
     BrowserAnimationsModule,
@@ -87,390 +67,529 @@ import { environment } from '../environments/environment';
     ToastrModule.forRoot(),
     NgxMaskModule.forRoot(),
     FirebaseTableKxpLibModule
-  ],
-  providers: [],
-  bootstrap: [AppComponent]
+  ]
 })
-export class AppModule { }
-```
-
-### 2. Configure o Firebase no `environment.ts`:
-
-```typescript
-export const environment = {
-  production: false,
-  firebase: {
-    apiKey: "sua-api-key",
-    authDomain: "seu-projeto.firebaseapp.com",
-    projectId: "seu-projeto-id",
-    storageBucket: "seu-projeto.appspot.com",
-    messagingSenderId: "123456789",
-    appId: "seu-app-id"
-  }
-};
-```
-
-### 3. Importe os estilos do Angular Material no `styles.scss`:
-
-```scss
-@import '@angular/material/prebuilt-themes/indigo-pink.css';
-@import 'ngx-toastr/toastr';
-
-// Se estiver usando Tailwind CSS, adicione também:
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+export class AppModule {}
 ```
 
-## 💻 Uso Básico
-
-### No seu componente TypeScript:
-
+2. **Drop the component**
 ```typescript
-import { Component, OnInit } from '@angular/core';
-import { AngularFirestore } from '@angular/fire/compat/firestore';
-import { TableData, Column } from 'ng-firebase-table-kxp';
-
 @Component({
   selector: 'app-users',
   template: `
-    <lib-table 
-      [data]="tableData"
+    <lib-table
+      [data]="table"
       [downloadTable]="downloadTable">
     </lib-table>
   `
 })
-export class UsersComponent implements OnInit {
-  tableData: TableData;
-
-  constructor(private firestore: AngularFirestore) {}
-
-  ngOnInit() {
-    this.tableData = {
-      name: 'users',
-      collection: 'users',
-      collectionRef: this.firestore.collection('users').ref,
-      pagination: true,
-      download: true,
-      sortBy: {
-        field: 'createdAt',
-        order: 'desc'
-      },
-      displayedColumns: [
-        {
-          property: 'name',
-          title: 'Nome',
-          isFilterable: true,
-          isSortable: true
-        },
-        {
-          property: 'email',
-          title: 'E-mail',
-          isFilterable: true
-        },
-        {
-          property: 'createdAt',
-          title: 'Data de Criação',
-          isFilterableByDate: true,
-          isSortable: true,
-          pipe: new DatePipe('pt-BR')
-        }
-      ]
-    };
-  }
-
-  downloadTable = (arrange, conditions) => {
-    // Lógica para exportar a tabela
-    console.log('Exportando tabela...', arrange, conditions);
-  }
-}
-```
-
-## 📖 API Completa
-
-### TableData Interface
-
-```typescript
-interface TableData {
-  // Configurações básicas
-  name: string;                    // Nome da tabela
-  collection: string;              // Nome da collection no Firestore
-  collectionRef: CollectionReference;  // Referência da collection
-  pagination: boolean;             // Habilitar paginação
-  download: boolean;               // Habilitar exportação
-  
-  // Colunas
-  displayedColumns: Column[];      // Array de colunas a exibir
-  
-  // Ordenação
-  sortBy?: {
-    field: string;
-    order: 'asc' | 'desc';
-  };
-  
-  // Filtros e condições
-  conditions?: Condition[];        // Condições where do Firestore
-  filterFn?: (item: any) => boolean;  // Função de filtro customizada
-  filterableOptions?: FilterableOption[];  // Opções de filtro personalizadas
-  
-  // Aparência
-  color?: {
-    bg: string;                    // Classe CSS para fundo
-    text: string;                  // Classe CSS para texto
-  };
-  
-  // Navegação
-  isNotClickable?: boolean;        // Desabilitar clique nas linhas
-  url?: string;                    // URL base para navegação
-  
-  // Totalizadores
-  totalRef?: {
-    ref: DocumentReference;
-    field: string;
-  }[];
-  
-  // Botão de ação
-  actionButton?: {
-    label: string;
-    routerLink: string;
-    icon?: string;
-    colorClass?: string;
-    method?: (row: any, event?: any) => any;
-    condition?: (row: any) => boolean;
-  };
-  
-  // Tabs
-  tabs?: {
-    method: (tab: any, event?: any) => any;
-    tabsData: TabData[];
+export class UsersComponent {
+  table: TableData = {
+    name: 'users',
+    collection: 'users',
+    collectionRef: this.firestore.collection('users').ref,
+    pagination: true,
+    download: true,
+    displayedColumns: [
+      { property: 'name', title: 'Name', isFilterable: true, isSortable: true },
+      { property: 'email', title: 'Email', isFilterable: true }
+    ]
   };
-}
-```
-
-### Column Interface
 
-```typescript
-interface Column {
-  property: string;                // Propriedade do objeto
-  title?: string;                  // Título da coluna
-  charLimit?: number;              // Limite de caracteres (com tooltip)
-  
-  // Formatação
-  pipe?: PipeTransform;            // Pipe do Angular para formatação
-  calculateValue?: (row: any) => any;  // Função para calcular valor
-  
-  // Filtros e ordenação
-  isFilterable?: boolean;          // Permite filtrar por texto
-  isSortable?: boolean;            // Permite ordenação
-  isFilterableByDate?: boolean;    // Permite filtro por data
-  filterPredicates?: string[];     // Predicados customizados
-  
-  // Links e downloads
-  hasLink?: boolean | string;      // Tornar valor um link
-  hasDownload?: boolean | string;  // Habilitar download
-  
-  // Imagens
-  image?: {
-    class: string;
-    path?: string;
-    url?: boolean;
-    default?: string;
-  };
-  
-  // Ícones e botões
-  iconClass?: {
-    text?: string;
-    class?: string;
-    condition?: (row: any) => any;
-    buttonMethod?: (row: any, event?: any) => any;
-  }[];
-  
-  // Relações com outras collections
-  relation?: {
-    collection: string;
-    property: string;
-    newProperty: string;
-  };
-  
-  // Query lengths
-  queryLength?: {
-    collection: string;
-    property: string;
-    operator: WhereFilterOp;
-    value: string;
+  downloadTable = (arrange: any, conditions: any[]) => {
+    // export logic
   };
-  
-  // Arrays
-  arrayField?: string;             // Campo para exibir de arrays de objetos
-  
-  // Métodos customizados
-  method?: (row: any, event?: any) => any;
+
+  constructor(private firestore: AngularFirestore) {}
 }
 ```
 
-## 🎯 Exemplos Avançados
-
-### Exemplo com Filtros Personalizados
+3. **Make sure global styles include**
+```scss
+@import '@angular/material/prebuilt-themes/indigo-pink.css';
+@import 'ngx-toastr/toastr';
+```
 
+## Configuration Overview
+
+- `TableData` defines the table behavior: source collection, pagination, sorting, tabs, exported totals, and custom navigation.
+- `Column` describes each displayed column: filters, relations, custom templates, icon actions, download buttons, and data formatting.
+- `Condition` lets you predefine Firestore `where` clauses applied before any user filters.
+- Optional hooks like `filterFn`, `actionButton`, and `tabs` enable richer UX without duplicating logic.
+- Automatic client-side fallback when Firestore reports missing composite indexes, plus logging of the index link to a `missingIndexes` collection.
+- Support for joining related collections, counting related documents per row, and managing dialog-driven actions via `iconClass` or `actionButton` handlers.
+- Compatible with SSR, lazy-loaded modules, and Angular standalone components.
+
+## API Reference
+
+This section provides detailed documentation for all configuration interfaces available in the library.
+
+### TableData
+
+The main configuration object that defines the entire table behavior.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | `string` | ✅ | Unique identifier for the table. Used internally for caching and state management. |
+| `collection` | `string` | ✅ | Name of the Firestore collection to query. |
+| `collectionRef` | `CollectionReference` | ✅ | Reference to the Firestore collection. Use `firestore.collection('name').ref`. |
+| `displayedColumns` | `Column[]` | ✅ | Array of column definitions. Defines what data to display and how. See [Column](#column). |
+| `pagination` | `boolean` | ✅ | Enable or disable pagination. When `true`, data is loaded in batches. |
+| `download` | `boolean` | ✅ | Enable or disable the export/download functionality. |
+| `sortBy` | `{field: string, order: OrderByDirection}` | ❌ | Default sorting configuration. `order` can be `'asc'` or `'desc'`. |
+| `conditions` | `Condition[]` | ❌ | Array of Firestore where clauses applied before user filters. See [Condition](#condition). |
+| `filterFn` | `(item: any) => boolean` | ❌ | Custom client-side filter function. Applied after Firestore queries. |
+| `filterableOptions` | `FilterableOption[]` | ❌ | Predefined filter options displayed as buttons. See [FilterableOption](#filterableoption). |
+| `url` | `string` | ❌ | Base URL for row navigation. Row clicks navigate to `{url}/{row.id}`. |
+| `isNotClickable` | `boolean` | ❌ | When `true`, disables row click navigation. |
+| `color` | `{bg: string, text: string}` | ❌ | CSS classes for custom table theming. `bg` for background, `text` for text color. |
+| `totalRef` | `{ref: DocumentReference, field: string}[]` | ❌ | References to documents containing total counts. Displayed in the table footer. |
+| `actionButton` | `ActionButton` | ❌ | Configuration for a primary action button (e.g., "Add New"). |
+| `tabs` | `Tab` | ❌ | Configuration for tabbed data views. See [Tab & TabData](#tab--tabdata). |
+
+**ActionButton Properties:**
+- `label` (string): Button text
+- `routerLink` (string): Navigation route
+- `icon` (string): CSS class for icon (e.g., FontAwesome)
+- `colorClass` (string): CSS class for button styling
+- `method` ((row, event) => any): Custom click handler
+- `condition` ((row) => boolean): Function to conditionally show the button
+
+**Example:**
 ```typescript
-this.tableData = {
+const tableData: TableData = {
   name: 'products',
   collection: 'products',
   collectionRef: this.firestore.collection('products').ref,
   pagination: true,
   download: true,
-  displayedColumns: [
-    {
-      property: 'name',
-      title: 'Produto',
-      isFilterable: true
-    },
-    {
-      property: 'price',
-      title: 'Preço',
-      pipe: new CurrencyPipe('pt-BR'),
-      isSortable: true
-    },
-    {
-      property: 'category',
-      title: 'Categoria',
-      isFilterable: true
-    }
+  sortBy: { field: 'createdAt', order: 'desc' },
+  conditions: [
+    { operator: '==', firestoreProperty: 'active', dashProperty: true }
   ],
-  filterableOptions: [
-    {
-      title: 'Status',
-      items: [
-        { property: 'status', value: 'active', label: 'Ativo' },
-        { property: 'status', value: 'inactive', label: 'Inativo' }
-      ]
-    }
-  ]
+  displayedColumns: [/* ... */],
+  actionButton: {
+    label: 'Add Product',
+    routerLink: '/products/new',
+    icon: 'fa fa-plus',
+    colorClass: 'bg-blue-500'
+  }
 };
 ```
 
-### Exemplo com Relações
-
+---
+
+### Column
+
+Defines how each column is displayed, filtered, and interacted with.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `property` | `string` | ✅ | Name of the property in the data object to display. |
+| `title` | `string` | ❌ | Column header text. Defaults to `property` if not provided. |
+| `charLimit` | `number` | ❌ | Maximum characters to display. Shows tooltip with full text on hover. |
+| `pipe` | `PipeTransform` | ❌ | Angular pipe for formatting values (e.g., `DatePipe`, `CurrencyPipe`). |
+| `calculateValue` | `(row: any) => any` | ❌ | Function to compute the display value from the row data. |
+| `isSortable` | `boolean` | ❌ | Enable sorting for this column. |
+| `isFilterable` | `boolean` | ❌ | Enable text-based filtering for this column. |
+| `isFilterableByDate` | `boolean` | ❌ | Enable date range filtering. Shows date picker inputs. |
+| `filterPredicates` | `string[]` | ❌ | Additional properties to include when filtering this column. |
+| `hasLink` | `boolean \| string` | ❌ | Make the cell value a clickable link. If string, uses as the navigation path. |
+| `hasDownload` | `boolean \| string` | ❌ | Add download icon to the cell. If string, uses as the download URL property. |
+| `arrayField` | `string` | ❌ | When data is an array of objects, specify which field to display. |
+| `method` | `(row: any, event?: any) => any` | ❌ | Custom click handler for the cell. |
+| `image` | `Image` | ❌ | Configuration for displaying images. See [Image](#image). |
+| `iconClass` | `IconClass[]` | ❌ | Array of icon/button configurations for action buttons in the cell. |
+| `relation` | `Relation` | ❌ | Configuration for joining related collection data. |
+| `queryLength` | `QueryLength` | ❌ | Configuration for counting related documents. |
+
+**IconClass Properties:**
+- `class` (string): CSS classes for the icon/button
+- `text` (string): Text to display alongside icon
+- `condition` ((row) => any): Function to conditionally show the icon
+- `buttonMethod` ((row, event) => any): Click handler for the icon
+
+**Relation Properties:**
+- `collection` (string): Name of the related collection
+- `property` (string): Property in current row containing the related document ID
+- `newProperty` (string): Property from related document to fetch and display
+
+**QueryLength Properties:**
+- `collection` (string): Collection to count documents from
+- `property` (string): Field to match in the query
+- `operator` (WhereFilterOp): Firestore operator (e.g., `'=='`, `'>'`)
+- `value` (string): Property from current row to use as query value
+
+**Example:**
 ```typescript
-displayedColumns: [
+const columns: Column[] = [
+  {
+    property: 'name',
+    title: 'Product Name',
+    isFilterable: true,
+    isSortable: true,
+    charLimit: 50
+  },
+  {
+    property: 'price',
+    title: 'Price',
+    pipe: new CurrencyPipe('en-US'),
+    isSortable: true
+  },
   {
-    property: 'userName',
-    title: 'Usuário',
+    property: 'createdAt',
+    title: 'Created',
+    pipe: new DatePipe('en-US'),
+    isFilterableByDate: true
+  },
+  {
+    property: 'categoryName',
+    title: 'Category',
     relation: {
-      collection: 'users',
-      property: 'userId',      // Campo na collection atual
-      newProperty: 'name'      // Campo a buscar na collection relacionada
+      collection: 'categories',
+      property: 'categoryId',
+      newProperty: 'name'
     }
-  }
-]
-```
-
-### Exemplo com Botões Customizados
-
-```typescript
-displayedColumns: [
+  },
   {
     property: 'actions',
-    title: 'Ações',
+    title: 'Actions',
     iconClass: [
       {
         class: 'fa fa-edit text-blue-500 cursor-pointer',
-        buttonMethod: (row, event) => {
-          event.stopPropagation();
-          this.editItem(row);
-        },
-        condition: (row) => row.canEdit === true
+        buttonMethod: (row) => this.editProduct(row)
       },
       {
-        class: 'fa fa-trash text-red-500 cursor-pointer ml-2',
-        buttonMethod: (row, event) => {
-          event.stopPropagation();
-          this.deleteItem(row);
-        }
+        class: 'fa fa-trash text-red-500 cursor-pointer',
+        buttonMethod: (row) => this.deleteProduct(row),
+        condition: (row) => row.canDelete === true
       }
     ]
   }
-]
+];
 ```
 
-### Exemplo com Condições (Where Clauses)
+---
+
+### Tab & TabData
+
+Configure tabbed views for switching between different data sets within the same table.
 
+**Tab Interface:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `method` | `(tab: any, event?: any) => any` | ✅ | Function called when a tab is clicked. Use to switch data or apply filters. |
+| `tabsData` | `TabData[]` | ✅ | Array of tab configurations. |
+
+**TabData Interface:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `label` | `string` | ✅ | Text displayed on the tab. |
+| `counter` | `number` | ❌ | Optional counter badge displayed next to the label. |
+| `counterClass` | `string` | ❌ | CSS class for styling the counter badge. |
+
+**Example:**
 ```typescript
-this.tableData = {
-  // ... outras configurações
-  conditions: [
-    {
-      operator: '==',
-      firestoreProperty: 'status',
-      dashProperty: 'active'
+const tableData: TableData = {
+  // ... other config
+  tabs: {
+    method: (tab, event) => {
+      if (tab.label === 'Active') {
+        this.loadActiveProducts();
+      } else if (tab.label === 'Inactive') {
+        this.loadInactiveProducts();
+      }
     },
-    {
-      operator: '>=',
-      firestoreProperty: 'createdAt',
-      dashProperty: new Date('2024-01-01')
-    }
-  ]
+    tabsData: [
+      { label: 'Active', counter: 42, counterClass: 'bg-green-500' },
+      { label: 'Inactive', counter: 8, counterClass: 'bg-gray-500' },
+      { label: 'All' }
+    ]
+  }
 };
 ```
 
-### Exemplo com Filtro Customizado (filterFn)
+---
+
+### FilterableOption
+
+Predefined filter buttons that users can click to apply common filters.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `title` | `string` | ✅ | Label for the filter group. |
+| `items` | `FilterItem[]` | ✅ | Array of individual filter options. |
+
+**FilterItem Properties:**
+- `property` (string): Property to filter on
+- `value` (string \| boolean): Value to filter by
+- `label` (string): Text displayed on the filter button
+
+**Example:**
+```typescript
+const filterableOptions: FilterableOption[] = [
+  {
+    title: 'Status',
+    items: [
+      { property: 'status', value: 'active', label: 'Active' },
+      { property: 'status', value: 'pending', label: 'Pending' },
+      { property: 'status', value: 'archived', label: 'Archived' }
+    ]
+  },
+  {
+    title: 'Category',
+    items: [
+      { property: 'category', value: 'electronics', label: 'Electronics' },
+      { property: 'category', value: 'clothing', label: 'Clothing' }
+    ]
+  }
+];
+```
+
+---
+
+### Condition
+
+Firestore `where` clauses that are always applied to queries, before any user filters.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `operator` | `WhereFilterOp` | ✅ | Firestore comparison operator: `'=='`, `'!='`, `'<'`, `'<='`, `'>'`, `'>='`, `'array-contains'`, `'in'`, `'array-contains-any'`, `'not-in'`. |
+| `firestoreProperty` | `string` | ✅ | Name of the field in Firestore to filter on. |
+| `dashProperty` | `string \| string[]` | ✅ | Value or array of values to compare against. Can be a static value or a property name from your component. |
+
+**Example:**
+```typescript
+const conditions: Condition[] = [
+  {
+    operator: '==',
+    firestoreProperty: 'tenantId',
+    dashProperty: this.currentTenantId
+  },
+  {
+    operator: '>=',
+    firestoreProperty: 'createdAt',
+    dashProperty: this.startDate
+  },
+  {
+    operator: 'in',
+    firestoreProperty: 'status',
+    dashProperty: ['active', 'pending']
+  }
+];
+```
+
+---
+
+### Arrange
+
+Internal interface used for managing sort and filter state. Automatically handled by the table component.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `filters` | `FilterState[]` | Array of active filters per column. |
+| `sortBy` | `{field: string, order: OrderByDirection}` | Current sort configuration. |
+| `elementId` | `{property: string, value: string}` | Optional identifier for highlighting a specific row. |
+
+**FilterState Properties:**
+- `arrange` ('ascending' \| 'descending' \| 'filter' \| 'filterByDate' \| 'equals' \| ''): Type of filter/sort applied
+- `filter` ({property: string, filtering: string}): Text filter configuration
+- `dateFilter` ({initial: Date, final: Date}): Date range filter
 
+---
+
+### Image
+
+Configuration for displaying images in table cells.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `class` | `string` | ✅ | CSS classes for styling the image element. |
+| `path` | `string` | ❌ | Property name containing the image path/URL in the row data. |
+| `url` | `boolean` | ❌ | If `true`, treats the value as a complete URL. Otherwise, constructs path from storage. |
+| `default` | `string` | ❌ | Default image URL if the actual image is missing or fails to load. |
+
+**Example:**
 ```typescript
-this.tableData = {
-  // ... outras configurações
-  filterFn: (item) => {
-    // Filtro customizado no lado do cliente
-    return item.age >= 18 && item.status === 'active';
+const column: Column = {
+  property: 'avatar',
+  title: 'Photo',
+  image: {
+    class: 'w-10 h-10 rounded-full object-cover',
+    path: 'photoURL',
+    url: true,
+    default: '/assets/default-avatar.png'
   }
 };
 ```
 
-## 🎨 Customização de Estilos
+---
 
-A biblioteca usa Tailwind CSS e Angular Material. Você pode customizar os estilos no seu `styles.scss`:
+### Data Export (Download)
 
-```scss
-// Customizar cores da tabela
-.mat-elevation-z8 {
-  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1) !important;
+The library provides a flexible export system that allows you to download table data with the currently applied filters, sorting, and conditions.
+
+#### How It Works
+
+1. **Pass a download handler** to the table component via the `[downloadTable]` input
+2. **User clicks** the download button in the table UI
+3. **Library calls your handler** with current `arrange` (filters/sort state) and `conditions` (where clauses)
+4. **Your handler** fetches all data using `TableService.getItemsData()`, transforms it, and generates the file
+
+#### Basic Example
+
+```typescript
+import { TableService } from '@adryanmmm/firebase-table-kxp-lib';
+import * as XLSX from 'xlsx';
+import moment from 'moment';
+
+export class UsersComponent {
+  constructor(private tableService: TableService) {}
+
+  // Pass this method to [downloadTable]
+  downloadTable = async (arrange: Arrange, conditions: Condition[]) => {
+    // 1. Fetch all data with current filters
+    const rawData = await this.tableService.getItemsData(
+      'users',           // collection name
+      arrange,           // current sort/filter state
+      conditions         // optional where conditions
+    );
+
+    // 2. Transform data to desired format
+    const xlsxData = rawData.map(user => ({
+      'Name': user.fullName,
+      'Email': user.email,
+      'Phone': user.phoneNumber,
+      'Created': new Date(user.createdAt.seconds * 1000).toLocaleDateString()
+    }));
+
+    // 3. Generate Excel file
+    const worksheet = XLSX.utils.json_to_sheet(xlsxData);
+    const workbook = XLSX.utils.book_new();
+    XLSX.utils.book_append_sheet(workbook, worksheet, 'Users');
+    
+    // 4. Download file
+    const fileName = `Users_${moment().format('DD-MM-YYYY-HH-mm-ss')}.xlsx`;
+    XLSX.writeFile(workbook, fileName);
+  }
 }
+```
+
+#### Advanced Example with Totals
 
-// Customizar header da tabela
-.bg-primary {
-  background-color: #your-color !important;
+```typescript
+downloadOrdersTable = async (arrange: Arrange, conditions: Condition[]) => {
+  const rawData = await this.tableService.getItemsData(
+    'orders',
+    arrange,
+    conditions
+  );
+
+  let totalAmount = 0;
+
+  // Map data and calculate totals
+  const xlsxData = rawData.map(order => {
+    totalAmount += order.amount;
+    return {
+      'Order ID': order.id,
+      'Customer': order.customerName,
+      'Amount': order.amount,
+      'Date': new Date(order.createdAt.seconds * 1000).toLocaleDateString(),
+      'Status': order.status
+    };
+  });
+
+  // Add totals row
+  xlsxData.push({
+    'Order ID': '',
+    'Customer': '',
+    'Amount': totalAmount,
+    'Date': 'TOTAL',
+    'Status': ''
+  });
+
+  const worksheet = XLSX.utils.json_to_sheet(xlsxData);
+  const workbook = XLSX.utils.book_new();
+  XLSX.utils.book_append_sheet(workbook, worksheet, 'Orders');
+  
+  const fileName = `Orders_${moment().format('DD-MM-YYYY-HH-mm-ss')}.xlsx`;
+  XLSX.writeFile(workbook, fileName);
 }
+```
+
+#### Filtering Data Before Export
+
+You can apply additional client-side filters based on user permissions:
+
+```typescript
+downloadTable = async (arrange: Arrange, conditions: Condition[]) => {
+  const rawData = await this.tableService.getItemsData('orders', arrange, conditions);
+
+  // Filter based on user permissions
+  const filteredData = rawData.filter(order => {
+    if (this.currentUser.role === 'Admin') return true;
+    if (this.currentUser.storeId === order.storeId) return true;
+    return false;
+  });
 
-// Customizar paginador
-.mat-mdc-paginator {
-  background-color: #f9fafb;
+  // ... continue with export
 }
 ```
 
-## ⚡ Performance e Otimização
+#### Using Custom Pipes for Formatting
 
-### Fallback Client-Side
+Apply Angular pipes to format data in the export:
 
-A biblioteca detecta automaticamente quando uma query necessita de índices compostos no Firestore e usa um fallback client-side para evitar erros. Isso significa que sua aplicação continuará funcionando mesmo sem todos os índices criados.
+```typescript
+import { DatePipe, CurrencyPipe } from '@angular/common';
+
+downloadTable = async (arrange: Arrange, conditions: Condition[]) => {
+  const rawData = await this.tableService.getItemsData('products', arrange);
+  
+  const datePipe = new DatePipe('en-US');
+  const currencyPipe = new CurrencyPipe('en-US');
 
-### Rastreamento de Índices Ausentes
+  const xlsxData = rawData.map(product => ({
+    'Product': product.name,
+    'Price': currencyPipe.transform(product.price),
+    'Created': datePipe.transform(product.createdAt.toDate(), 'short'),
+    'Status': product.active ? 'Active' : 'Inactive'
+  }));
+
+  // ... continue with export
+}
+```
+
+#### CSV vs XLSX Format
+
+```typescript
+// Export as XLSX (default)
+XLSX.writeFile(workbook, 'data.xlsx');
+
+// Export as CSV
+XLSX.writeFile(workbook, 'data.csv', { bookType: 'csv', type: 'binary' });
+```
 
-O serviço `TableService` rastreia automaticamente queries que precisam de índices e salva as informações na collection `missingIndexes` do Firestore, incluindo:
-- Link direto para criar o índice no Firebase Console
-- Instruções passo a passo
-- Estrutura da query
+#### Important Notes
 
-## 🤝 Contribuindo
+- The `download` property in `TableData` must be `true` to show the download button
+- `TableService.getItemsData()` returns **all** data matching filters (ignores pagination)
+- The method is `async` because it fetches data from Firestore
+- You control the final file format, column names, and data transformations
+- The library provides the current filter/sort state; you handle the actual file generation
 
-Contribuições são bem-vindas! Por favor, sinta-se à vontade para submeter pull requests.
+## Powered by KXP Tech
 
-## 📝 Licença
+Firebase Table KXP was designed inside **KXP Tech** to accelerate data-heavy application development. If you are looking for expert consultancy on Firebase, Angular, or enterprise dashboards, reach out at [kxptech.com](https://kxptech.com).
 
-MIT
+## Contributing & License
 
-## 👨‍💻 Autor
+Contributions, feedback, and feature requests are welcome. Fork the repository, open a pull request, or start a discussion on GitHub.
 
-Adryan - [@adryanmmm](https://github.com/adryanmmm)
+This project is released under the MIT License. See the [LICENSE](LICENSE) file for details.
 
-## 🐛 Reportar Bugs
+## Support the Project
 
-Se encontrar algum bug, por favor abra uma issue no GitHub.
+If this library saves you time, please star the repository and share it with your team.