ng-firebase-table-kxp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
+
+O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
+e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/).
+
+## [Unreleased]
+
+## [0.0.1] - 2024-11-03
+
+### Adicionado
+- ✨ Componente principal de tabela (`TableComponent`)
+- 🔥 Integração completa com Firebase Firestore
+- 📊 Sistema de paginação avançado (client-side e server-side)
+- 🔍 Sistema de filtros:
+  - Filtro por texto
+  - Filtro por data
+  - Filtro por igualdade (equals)
+  - Filtros personalizados com dropdown
+  - Função de filtro customizada (filterFn)
+- ⚡ Fallback automático client-side quando índices compostos não existem
+- 📈 Rastreamento automático de índices ausentes
+- 🔗 Suporte a relações entre collections
+- 🖼️ Suporte a exibição de imagens
+- 🎯 Botões de ação customizáveis
+- 📥 Sistema de exportação de dados
+- 🎨 Interface Material Design responsiva
+- 📝 Suporte a valores calculados
+- 🔢 Suporte a arrays e propriedades aninhadas
+- 💬 Tooltips para valores longos com charLimit
+- 🎨 Customização de cores e estilos
+- 📑 Sistema de tabs
+- 🔄 Método público `reloadTable()` para atualização manual
+- 📊 Query lengths para contar documentos relacionados
+
+### Serviços
+- `TableService` com métodos:
+  - `getPaginated()` - Paginação otimizada
+  - `getItems()` - Buscar todos os itens
+  - `getItemsData()` - Buscar itens com filtros
+  - `executeClientSideQuery()` - Fallback client-side
+  - `deleteIndex()` - Deletar com reindexação
+  - `dateFormatValidator()` - Validador de data
+  - `operators` - Operadores de comparação
+
+### Tipos
+- `TableData` - Interface principal de configuração
+- `Column` - Interface de configuração de colunas
+- `Arrange` - Interface de arranjo (filtros e ordenação)
+- `Condition` - Interface de condições where
+- `Pagination` - Interface de paginação
+- `FilterableOption` - Interface de opções filtráveis
+- `Tab` e `TabData` - Interfaces para tabs
+- `Image` - Interface para imagens
+
+### Documentação
+- README.md completo com exemplos
+- USAGE_EXAMPLE.md com casos de uso detalhados
+- BUILD.md com guia de publicação
+- CHANGELOG.md
+
+### Dependências Peer
+- @angular/common ^15.0.0
+- @angular/core ^15.0.0
+- @angular/forms ^15.0.0
+- @angular/router ^15.0.0
+- @angular/material ^15.0.0
+- @angular/cdk ^15.0.0
+- @angular/fire ^7.0.0
+- firebase ^9.0.0
+- ngx-toastr ^16.0.0
+- moment ^2.29.0
+- ngx-mask ^15.0.0
+
+## Tipos de Mudanças
+
+- `Added` - para novas funcionalidades
+- `Changed` - para mudanças em funcionalidades existentes
+- `Deprecated` - para funcionalidades que serão removidas
+- `Removed` - para funcionalidades removidas
+- `Fixed` - para correção de bugs
+- `Security` - para vulnerabilidades de segurança
+
+[Unreleased]: https://github.com/adryanmmm/firebase-table-kxp-lib/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/adryanmmm/firebase-table-kxp-lib/releases/tag/v0.0.1
+
+

package/README.md

@@ -0,0 +1,476 @@
+# 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+)
+
+```bash
+npm install ng-firebase-table-kxp
+```
+
+✅ **Pronto!** Todas as dependências necessárias serão instaladas automaticamente pelo npm 7+.
+
+### Se você usa npm 6 ou anterior
+
+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!
+```
+
+## 🔧 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`:
+
+```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';
+
+@NgModule({
+  declarations: [
+    AppComponent
+  ],
+  imports: [
+    BrowserModule,
+    BrowserAnimationsModule,
+    AngularFireModule.initializeApp(environment.firebase),
+    AngularFirestoreModule,
+    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;
+```
+
+## 💻 Uso Básico
+
+### No seu componente TypeScript:
+
+```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"
+      [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[];
+  };
+}
+```
+
+### 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;
+  };
+  
+  // Arrays
+  arrayField?: string;             // Campo para exibir de arrays de objetos
+  
+  // Métodos customizados
+  method?: (row: any, event?: any) => any;
+}
+```
+
+## 🎯 Exemplos Avançados
+
+### Exemplo com Filtros Personalizados
+
+```typescript
+this.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
+    }
+  ],
+  filterableOptions: [
+    {
+      title: 'Status',
+      items: [
+        { property: 'status', value: 'active', label: 'Ativo' },
+        { property: 'status', value: 'inactive', label: 'Inativo' }
+      ]
+    }
+  ]
+};
+```
+
+### Exemplo com Relações
+
+```typescript
+displayedColumns: [
+  {
+    property: 'userName',
+    title: 'Usuário',
+    relation: {
+      collection: 'users',
+      property: 'userId',      // Campo na collection atual
+      newProperty: 'name'      // Campo a buscar na collection relacionada
+    }
+  }
+]
+```
+
+### Exemplo com Botões Customizados
+
+```typescript
+displayedColumns: [
+  {
+    property: 'actions',
+    title: 'Ações',
+    iconClass: [
+      {
+        class: 'fa fa-edit text-blue-500 cursor-pointer',
+        buttonMethod: (row, event) => {
+          event.stopPropagation();
+          this.editItem(row);
+        },
+        condition: (row) => row.canEdit === true
+      },
+      {
+        class: 'fa fa-trash text-red-500 cursor-pointer ml-2',
+        buttonMethod: (row, event) => {
+          event.stopPropagation();
+          this.deleteItem(row);
+        }
+      }
+    ]
+  }
+]
+```
+
+### Exemplo com Condições (Where Clauses)
+
+```typescript
+this.tableData = {
+  // ... outras configurações
+  conditions: [
+    {
+      operator: '==',
+      firestoreProperty: 'status',
+      dashProperty: 'active'
+    },
+    {
+      operator: '>=',
+      firestoreProperty: 'createdAt',
+      dashProperty: new Date('2024-01-01')
+    }
+  ]
+};
+```
+
+### Exemplo com Filtro Customizado (filterFn)
+
+```typescript
+this.tableData = {
+  // ... outras configurações
+  filterFn: (item) => {
+    // Filtro customizado no lado do cliente
+    return item.age >= 18 && item.status === 'active';
+  }
+};
+```
+
+## 🎨 Customização de Estilos
+
+A biblioteca usa Tailwind CSS e Angular Material. Você pode customizar os estilos no seu `styles.scss`:
+
+```scss
+// Customizar cores da tabela
+.mat-elevation-z8 {
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1) !important;
+}
+
+// Customizar header da tabela
+.bg-primary {
+  background-color: #your-color !important;
+}
+
+// Customizar paginador
+.mat-mdc-paginator {
+  background-color: #f9fafb;
+}
+```
+
+## ⚡ Performance e Otimização
+
+### Fallback Client-Side
+
+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.
+
+### Rastreamento de Índices Ausentes
+
+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
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Por favor, sinta-se à vontade para submeter pull requests.
+
+## 📝 Licença
+
+MIT
+
+## 👨‍💻 Autor
+
+Adryan - [@adryanmmm](https://github.com/adryanmmm)
+
+## 🐛 Reportar Bugs
+
+Se encontrar algum bug, por favor abra uma issue no GitHub.

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/ng-firebase-table-kxp",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "ng-firebase-table-kxp",
+  "version": "1.0.0",
+  "description": "Uma biblioteca Angular poderosa para criar tabelas dinâmicas com integração completa ao Firebase Firestore",
+  "keywords": [
+    "angular",
+    "firebase",
+    "firestore",
+    "table",
+    "pagination",
+    "material",
+    "data-table"
+  ],
+  "author": "Adryan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adryanmbs/firebase-table-kxp-lib"
+  },
+  "peerDependencies": {
+    "@angular/common": "^15.0.0",
+    "@angular/core": "^15.0.0",
+    "@angular/forms": "^15.0.0",
+    "@angular/router": "^15.0.0",
+    "@angular/material": "^15.0.0",
+    "@angular/cdk": "^15.0.0",
+    "@angular/fire": "^7.0.0",
+    "firebase": "^9.0.0",
+    "ngx-toastr": "^16.0.0",
+    "moment": "^2.29.0",
+    "ngx-mask": "^15.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}