forlogic-core 1.6.13 → 1.7.0

package/README.md

@@ -220,6 +220,7 @@ Table, TableBody, TableCell, TableHead, TableHeader, TableRow
 // Utils
 cn                        // Merge classes Tailwind
 formatDate, formatDatetime // Formatação de datas
+handleExternalLink       // Helper para links externos
 
 // Auth
 useAuth                   // Hook de autenticação
@@ -237,7 +238,6 @@ TokenManager             // Gerenciamento de tokens
 createSimpleService      // Criar service CRUD
 createCrudPage           // Criar página CRUD
 generateCrudConfig       // Gerar config CRUD
-createSimpleSaveHandler  // Handler de save
 
 // Errors
 errorService             // Service de erros
@@ -466,7 +466,7 @@ graph TD
     C --> D[Page.tsx<br/>Componente Principal]
     D --> E[createCrudPage<br/>Gerador de CRUD]
     E --> F[CrudTable<br/>Tabela]
-    E --> G[CrudForm<br/>Formulário]
+    E --> G[BaseForm<br/>Formulário]
     E --> H[BulkActionBar<br/>Ações em Massa]
     
     I[(Supabase DB)] -.->|RLS + Soft Delete| B
@@ -498,18 +498,16 @@ src/
 
 ```
 ✅ OBRIGATÓRIOS:
-  □ types.ts - Definir Example extends ContentEntity + VisualEntity + ...
-  □ types.ts - CreateExamplePayload com alias: string
-  □ types.ts - UpdateExamplePayload extends Partial<CreateExamplePayload>
+  □ types.ts - Definir Example extends BaseEntity com campos explícitos
+  □ types.ts - Usar Omit<> e Partial<> para CreatePayload e UpdatePayload
   □ Service.ts - Usar createSimpleService<Example, CreatePayload, UpdatePayload>
   □ Service.ts - Configurar tableName, entityName, searchFields
   □ Page.tsx - Chamar useExamplesCrud() DENTRO do componente
   □ Page.tsx - Usar useMemo() para columns, formSections, config
-  □ Page.tsx - Importar { alias } de useAuth()
-  □ Page.tsx - Passar alias no CreatePayload
+  □ Page.tsx - Usar manager.save() ao invés de createSimpleSaveHandler
 
 🔧 OPCIONAIS:
-  □ Filtros customizados (useState + useMemo)
+  □ Filtros customizados (backend via additionalFilters recomendado)
   □ onToggleStatus para ativar/desativar
   □ Renderização customizada nas colunas
   □ Campos de formulário customizados
@@ -709,24 +707,27 @@ export const { service: processService, useCrudHook: useProcesses } =
   });
 ```
 
-### **3️⃣ Save Handler**
+### **3️⃣ Save Handler (Integrado ao useCrud)**
 ```typescript
 // src/processes/ProcessesPage.tsx
-import { createSimpleSaveHandler } from 'forlogic-core';
-import { processService } from './processService';
-
-const handleSave = createSimpleSaveHandler({
-  service: processService,
-  entityName: 'processo'
-});
 
-// ⚠️ CRÍTICO: Preservar ID no update
-const handleUpdate = async (item: Process) => {
-  await handleSave({
-    ...item,
-    id: item.id // ⚠️ OBRIGATÓRIO para update
-  });
-};
+export default function ProcessesPage() {
+  const manager = useProcesses();
+
+  const handleSave = (data: any) => {
+    manager.save(data, (d) => ({
+      title: d.title,
+      description: d.description || null,
+      status: d.status || 'draft'
+    }));
+  };
+
+  // O método save() automaticamente:
+  // ✅ Detecta se é CREATE (sem id) ou UPDATE (com id)
+  // ✅ Injeta o alias no CREATE
+  // ✅ Chama createEntity ou updateEntity
+  // ✅ Fecha o modal automaticamente após sucesso
+}
 ```
 
 ### **4️⃣ Config (com useMemo)**
@@ -789,6 +790,282 @@ function ProcessLayout() {
 
 ---
 
+## 🔄 GUIA DE MIGRAÇÃO - v2.0
+
+Se você tem projetos usando versões antigas do `forlogic-core`, siga este guia para atualizar.
+
+### **📦 Atualizar Versão**
+
+```bash
+npm install forlogic-core@latest
+```
+
+---
+
+### **1️⃣ Migração de Tipos (Breaking Change)**
+
+#### **❌ ANTES (Versão Antiga):**
+```typescript
+import { 
+  ContentEntity, 
+  VisualEntity, 
+  UserRelatedEntity, 
+  ActivableEntity,
+  FormEntity 
+} from 'forlogic-core';
+
+export interface Example extends 
+  ContentEntity,
+  VisualEntity,
+  UserRelatedEntity,
+  ActivableEntity,
+  FormEntity {}
+
+export interface CreateExamplePayload {
+  title: string;
+  description?: string | null;
+  alias: string;  // ⚠️ Obrigatório manualmente
+  color?: string;
+  icon_name?: string;
+  id_user?: string | null;
+  is_actived?: boolean;
+  url_field?: string | null;
+  date_field?: string | null;
+}
+
+export interface UpdateExamplePayload extends Partial<CreateExamplePayload> {
+  title: string;  // Override
+}
+```
+
+#### **✅ DEPOIS (Nova API):**
+```typescript
+import { BaseEntity } from 'forlogic-core';
+
+export interface Example extends BaseEntity {
+  title: string;
+  description?: string | null;
+  color?: string;
+  icon_name?: string;
+  id_user?: string | null;
+  responsible_name?: string;
+  url_field?: string | null;
+  date_field?: string | null;
+  // is_actived agora vem de BaseEntity!
+}
+
+export type CreateExamplePayload = Omit<
+  Example, 
+  keyof BaseEntity | 'responsible_name'
+>;
+
+export type UpdateExamplePayload = Partial<CreateExamplePayload>;
+```
+
+**📝 Mudanças:**
+- ❌ **REMOVIDO**: Helper interfaces (`ContentEntity`, `VisualEntity`, etc)
+- ✅ **NOVO**: Apenas `BaseEntity` + campos explícitos
+- ✅ **NOVO**: `is_actived` agora é campo padrão de `BaseEntity`
+- ✅ **NOVO**: Use `Omit<>` e `Partial<>` para Payloads
+
+---
+
+### **2️⃣ Migração de Save Handler (Breaking Change)**
+
+#### **❌ ANTES (createSimpleSaveHandler):**
+```typescript
+import { createSimpleSaveHandler, useAuth } from 'forlogic-core';
+
+const { alias: currentAlias } = useAuth();
+
+const handleSave = createSimpleSaveHandler(
+  manager,
+  // createTransform
+  (data) => ({
+    title: data.title,
+    description: data.description || null,
+    alias: currentAlias  // ⚠️ Injetar manualmente
+  }),
+  // updateTransform
+  (data) => ({
+    title: data.title,
+    description: data.description || null
+  })
+);
+```
+
+#### **✅ DEPOIS (manager.save):**
+```typescript
+const handleSave = (data: any) => {
+  manager.save(data, (d) => ({
+    title: d.title,
+    description: d.description || null
+  }));
+};
+
+// O método save() faz automaticamente:
+// ✅ Detecta CREATE vs UPDATE (baseado em data.id)
+// ✅ Injeta alias no CREATE
+// ✅ Fecha modal após sucesso
+```
+
+**📝 Mudanças:**
+- ❌ **REMOVIDO**: `createSimpleSaveHandler`
+- ❌ **REMOVIDO**: Import de `useAuth` para pegar `alias`
+- ✅ **NOVO**: `manager.save(data, transform)`
+- ✅ **NOVO**: Alias injetado automaticamente
+
+---
+
+### **3️⃣ Migração de Campos de Formulário**
+
+#### **❌ ANTES (Tipos Múltiplos):**
+```typescript
+{
+  name: 'id_user',
+  label: 'Responsável',
+  type: 'simple-qualiex-user-field',  // OU 'single-responsible-select'
+  required: true
+}
+```
+
+#### **✅ DEPOIS (Tipo Unificado):**
+```typescript
+{
+  name: 'id_user',
+  label: 'Responsável',
+  type: 'user-select',
+  mode: 'single',  // OU 'multiple'
+  required: true
+}
+```
+
+**📝 Mudanças:**
+- ❌ **REMOVIDO**: `'simple-qualiex-user-field'`, `'single-responsible-select'`
+- ✅ **NOVO**: Apenas `'user-select'` com parâmetro `mode`
+
+---
+
+### **4️⃣ Migração de Imports**
+
+#### **❌ ANTES:**
+```typescript
+import { createSimpleSaveHandler } from 'forlogic-core';
+import { ContentEntity, VisualEntity, ... } from 'forlogic-core';
+```
+
+#### **✅ DEPOIS:**
+```typescript
+// createSimpleSaveHandler removido (usar manager.save)
+import { BaseEntity } from 'forlogic-core';
+import { handleExternalLink } from 'forlogic-core';  // NOVO helper
+```
+
+**📝 Mudanças:**
+- ❌ **REMOVIDO**: `createSimpleSaveHandler`
+- ❌ **REMOVIDO**: Helper interfaces de tipos
+- ✅ **NOVO**: `handleExternalLink` (helper de links externos)
+
+---
+
+### **5️⃣ Migração de Filtros Customizados**
+
+#### **❌ ANTES (Filtro Frontend):**
+```typescript
+const [statusFilter, setStatusFilter] = useState('active');
+
+const filteredEntities = useMemo(() => {
+  return manager.entities.filter(e => 
+    statusFilter === 'all' ? true : e.is_actived
+  );
+}, [manager.entities, statusFilter]);
+
+const filteredManager = useMemo(() => ({
+  ...manager,
+  entities: filteredEntities
+}), [manager, filteredEntities]);
+
+// Passar filteredManager para createCrudPage
+```
+
+#### **✅ DEPOIS (Filtro Backend - Recomendado):**
+```typescript
+const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
+
+// Passar filtro direto para o hook
+const manager = useExamplesCrud(
+  statusFilter === 'all' ? {} : { is_actived: statusFilter }
+);
+
+// Passar manager original (já vem filtrado)
+const CrudPage = createCrudPage({ manager, config, onSave });
+```
+
+**📝 Mudanças:**
+- ✅ **RECOMENDADO**: Filtro aplicado no backend (melhor performance)
+- ✅ **NOVO**: Hook aceita `additionalFilters` como parâmetro
+- ❌ **EVITAR**: Filtro frontend (só para casos complexos)
+
+---
+
+### **6️⃣ Checklist de Migração**
+
+Use este checklist para validar que seu projeto foi migrado corretamente:
+
+#### **Types (`example.ts`):**
+- [ ] Removido imports de helper interfaces (`ContentEntity`, `VisualEntity`, etc)
+- [ ] Interface principal agora estende apenas `BaseEntity`
+- [ ] Campos explícitos declarados na interface
+- [ ] `CreatePayload` usa `Omit<Example, keyof BaseEntity | 'responsible_name'>`
+- [ ] `UpdatePayload` usa `Partial<CreatePayload>`
+- [ ] Removido `alias: string` do `CreatePayload`
+- [ ] Removido interfaces/types não usados (`ExampleFilters`, `ExampleSortField`, `ExampleInsert`, `ExampleUpdate`)
+
+#### **Service (`ExampleService.ts`):**
+- [ ] Nenhuma mudança necessária (API permanece igual)
+
+#### **Page (`ExamplesPage.tsx`):**
+- [ ] Removido import de `createSimpleSaveHandler`
+- [ ] Removido import de `useAuth` (se usado apenas para alias)
+- [ ] Substituído `createSimpleSaveHandler` por `manager.save()`
+- [ ] Campos de formulário tipo `'user-select'` ao invés de tipos antigos
+- [ ] Filtros usando backend (`useExamplesCrud(filters)`) quando possível
+- [ ] Substituído lógica de links externos por `handleExternalLink` helper
+
+#### **Testes:**
+- [ ] Build sem erros TypeScript (`npm run build`)
+- [ ] Página carrega sem erros
+- [ ] Criar novo item funciona (alias injetado corretamente)
+- [ ] Editar item funciona
+- [ ] Deletar item funciona
+- [ ] Filtros funcionam corretamente
+- [ ] Paginação funciona
+- [ ] Busca funciona
+
+---
+
+### **7️⃣ Exemplo Completo de Migração**
+
+**Ver arquivo `src/examples/ExamplesPage.tsx` do projeto para exemplo 100% atualizado.**
+
+---
+
+### **❓ Problemas na Migração?**
+
+#### **Erro: "Property 'save' does not exist on type..."**
+- ✅ **Solução**: Atualize `forlogic-core` para versão mais recente
+- ✅ **Comando**: `npm install forlogic-core@latest`
+
+#### **Erro: "Cannot find module 'ContentEntity'"**
+- ✅ **Solução**: Remova imports de helper interfaces e use `BaseEntity`
+- ✅ **Ver**: Seção "1️⃣ Migração de Tipos" acima
+
+#### **Erro: "alias is required but not provided"**
+- ✅ **Solução**: Use `manager.save()` ao invés de `createEntity` direto
+- ✅ **Ver**: Seção "2️⃣ Migração de Save Handler" acima
+
+---
+
 ## 🎯 AÇÕES EM LOTE (Bulk Actions)
 
 O sistema CRUD suporta seleção múltipla e ações em lote usando checkboxes.
@@ -967,61 +1244,52 @@ import {
 /**
  * Example - Entidade completa de exemplo
  * 
- * ✅ Composição de Interfaces:
- * - ContentEntity: fornece title, description
- * - VisualEntity: fornece color, icon_name
- * - UserRelatedEntity: fornece id_user, responsible_name (enriquecido via Qualiex)
- * - ActivableEntity: fornece is_actived (campo de status on/off)
- * - FormEntity: fornece url_field, date_field
+ * ✅ Campos Customizados:
+ * - title, description (conteúdo)
+ * - color, icon_name (visual)
+ * - id_user, responsible_name (usuário - enriquecido via Qualiex)
+ * - url_field, date_field (formulário)
  * 
  * 🔒 Campos Herdados de BaseEntity (automáticos):
  * - id: string
  * - alias: string
  * - company_id: string
+ * - is_actived: boolean
  * - is_removed: boolean
  * - created_at: string
  * - updated_at: string
  */
-export interface Example extends 
-  ContentEntity,
-  VisualEntity,
-  UserRelatedEntity,
-  ActivableEntity,
-  FormEntity {}
+export interface Example extends BaseEntity {
+  title: string;
+  description?: string | null;
+  color?: string;
+  icon_name?: string;
+  id_user?: string | null;
+  responsible_name?: string;  // Enriquecido via Qualiex
+  url_field?: string | null;
+  date_field?: string | null;
+}
 
 /**
  * CreateExamplePayload - Dados para CRIAR novo registro
  * 
  * ⚠️ IMPORTANTE:
- * - Sempre incluir `alias: string` (obrigatório para RLS)
+ * - Campo `alias` é injetado AUTOMATICAMENTE pelo manager.save()
  * - Campos opcionais devem ter `| null`
  * - NÃO incluir id, created_at, updated_at (gerados automaticamente)
  */
-export interface CreateExamplePayload {
-  title: string;                    // ✅ Obrigatório
-  description?: string | null;       // ❌ Opcional
-  alias: string;                     // ✅ OBRIGATÓRIO para RLS
-  url_field?: string | null;
-  date_field?: string | null;
-  color?: string;
-  icon_name?: string;
-  id_user?: string | null;
-  is_actived?: boolean;
-}
+export type CreateExamplePayload = Omit<
+  Example, 
+  keyof BaseEntity | 'responsible_name'
+>;
 
 /**
  * UpdateExamplePayload - Dados para ATUALIZAR registro existente
  * 
  * 📝 Pattern:
- * - Estende Partial<CreateExamplePayload> (todos os campos opcionais)
- * - MAS title é obrigatório (override)
+ * - Todos os campos são opcionais (Partial)
  */
-export interface UpdateExamplePayload extends Partial<CreateExamplePayload> {
-  title: string;  // ✅ Override: title obrigatório mesmo no update
-}
-
-export type ExampleInsert = CreateExamplePayload;
-export type ExampleUpdate = UpdateExamplePayload;
+export type UpdateExamplePayload = Partial<CreateExamplePayload>;
 ```
 
 **📖 Explicação Detalhada:**
@@ -1138,7 +1406,7 @@ import { useState, useMemo } from 'react';
  * - 'select' - Dropdown com options
  * - 'color-picker' - Seletor de cor
  * - 'icon-picker' - Seletor de ícone Lucide
- * - 'simple-qualiex-user-field' - Seletor de usuário Qualiex
+ * - 'user-select' - Seletor de usuário (com mode: 'single' | 'multiple')
  * - 'custom' - Campo completamente customizado
  * - 'group' - Agrupa campos horizontalmente
  */
@@ -1164,7 +1432,8 @@ const formSections = [{
         {
           name: 'id_user',
           label: 'Responsável',
-          type: 'simple-qualiex-user-field' as const,  // 👤 Campo especial da lib
+          type: 'user-select' as const,  // 👤 Campo unificado
+          mode: 'single',
           required: true,
           placeholder: 'Selecionar responsável',
           defaultValue: '',
@@ -1231,45 +1500,37 @@ Ver código completo no arquivo `src/examples/ExamplesPage.tsx` do projeto.
 
 ## 🎯 PADRÕES DE FILTROS CUSTOMIZADOS
 
-### **Pattern 1: Filtro de Status (Ativo/Inativo/Todos)**
+### **Pattern 1: Filtro de Status (Backend - Recomendado)**
 
 ```typescript
-// ✅ PADRÃO COMPLETO: Filtro + Estado Derivado + Manager Customizado
+// ✅ PADRÃO BACKEND: Filtro aplicado na query SQL (melhor performance)
 
 // 1) Estado do filtro
-const [statusFilter, setStatusFilter] = useState<'active' | 'inactive' | 'all'>('active');
-
-// 2) Estado derivado (filtra entities)
-const filteredEntities = useMemo(() => {
-  if (statusFilter === 'all') return manager.entities;
-  return manager.entities.filter(e => 
-    statusFilter === 'active' ? e.is_actived : !e.is_actived
-  );
-}, [manager.entities, statusFilter]);
+const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
 
-// 3) Manager customizado
-const filteredManager = useMemo(() => ({
-  ...manager,
-  entities: filteredEntities
-}), [manager, filteredEntities]);
+// 2) Passar filtro para o hook (aplica no backend)
+const manager = useExamplesCrud(
+  statusFilter === 'all' ? {} : { is_actived: statusFilter }
+);
 
-// 4) Componente do filtro
+// 3) Componente do filtro
 const StatusFilter = () => (
   <EntitySelect
-    value={statusFilter}
-    onChange={(value) => setStatusFilter(value as 'active' | 'inactive' | 'all')}
+    value={String(statusFilter)}
+    onChange={(v) => setStatusFilter(v === 'all' ? 'all' : v === 'true')}
     items={[
-      { id: 'active', name: 'Ativo' },
-      { id: 'inactive', name: 'Inativo' },
+      { id: 'true', name: 'Ativo' },
+      { id: 'false', name: 'Inativo' },
       { id: 'all', name: '[Todos]' }
     ]}
     getItemValue={(item) => item.id}
     getItemLabel={(item) => item.name}
     placeholder="Status"
+    className="w-full sm:w-[180px]"
   />
 );
 
-// 5) Usar em config.filters
+// 4) Usar em config.filters
 config: {
   filters: [
     { type: 'search' },
@@ -1277,14 +1538,39 @@ config: {
   ]
 }
 
-// 6) Passar filteredManager para createCrudPage
+// 5) Passar manager original (filtro já aplicado)
 const CrudPage = createCrudPage({
-  manager: filteredManager,  // ← Não manager original!
+  manager,  // ← Manager já vem filtrado do backend
   config,
   onSave
 });
 ```
 
+### **Pattern 1B: Filtro de Status (Frontend - Casos Específicos)**
+
+```typescript
+// Use filtro frontend APENAS se:
+// ✅ Precisa combinar múltiplas propriedades (ex: status + tipo)
+// ✅ Lógica de filtro muito complexa para SQL
+// ❌ NÃO use para filtros simples (pior performance)
+
+const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
+
+const filteredEntities = useMemo(() => {
+  if (statusFilter === 'all') return manager.entities;
+  return manager.entities.filter(e => e.is_actived === statusFilter);
+}, [manager.entities, statusFilter]);
+
+const filteredManager = useMemo(() => ({
+  ...manager,
+  entities: filteredEntities,
+  pagination: {
+    ...manager.pagination,
+    totalItems: filteredEntities.length  // ⚠️ Atualizar contador
+  }
+}), [manager, filteredEntities]);
+```
+
 **📖 Explicação:**
 - **`useState`**: Armazena valor selecionado no filtro
 - **`useMemo` (filteredEntities)**: Evita re-filtrar a cada render
@@ -1466,31 +1752,25 @@ const filteredEntities = useMemo(() =>
 
 ---
 
-### **Erro 5: Esquecer `alias` no CREATE**
+### **Erro 5: Esquecer de usar `manager.save()`**
 
 ```typescript
 // ❌ SINTOMA: Erro de RLS no Supabase, registro não é criado
-// ❌ CAUSA: Payload sem alias
-const handleSave = createSimpleSaveHandler(
-  manager,
-  (data) => ({ 
-    title: data.title,
-    email: data.email
-    // ← Falta alias!
-  })
-);
-
-// ✅ SOLUÇÃO: Incluir alias do token
-const { alias: currentAlias } = useAuth();
+// ❌ CAUSA: Usar createEntity/updateEntity direto sem alias
+manager.createEntity({ 
+  title: data.title,
+  email: data.email
+  // ← Falta alias!
+});
 
-const handleSave = createSimpleSaveHandler(
-  manager,
-  (data) => ({ 
-    title: data.title,
-    email: data.email,
-    alias: currentAlias  // ← Correto!
-  })
-);
+// ✅ SOLUÇÃO: Usar manager.save() que injeta alias automaticamente
+const handleSave = (data: any) => {
+  manager.save(data, (d) => ({
+    title: d.title,
+    email: d.email
+  }));
+  // O save() detecta CREATE vs UPDATE e injeta alias automaticamente
+};
 ```
 
 ---
@@ -1638,19 +1918,12 @@ import { QualiexUserField, QualiexResponsibleSelectField } from 'forlogic-core';
 
 **Componentes em formulários CRUD:**
 ```typescript
-// Para seleção de usuário
-{
-  name: 'responsible_id',
-  label: 'Responsável',
-  type: 'simple-qualiex-user-field' as const,
-  required: true
-}
-
-// Para seleção de responsável
+// Para seleção de usuário (modo unificado)
 {
   name: 'responsible_id',
   label: 'Responsável',
-  type: 'single-responsible-select' as const,
+  type: 'user-select' as const,
+  mode: 'single',  // ou 'multiple'
   required: true
 }
 ```