forlogic-core 1.7.4 → 1.7.5

package/dist/README.md

@@ -1634,6 +1634,577 @@ function ProcessLayout() {
 
 ---
 
+### **5️⃣ Ações Customizadas na Action Bar**
+
+Adicione botões customizados ao lado do botão "Novo" na barra de ações.
+
+#### **Casos de Uso Comuns:**
+- 📥 Importar dados
+- 📤 Exportar relatório
+- 🔄 Sincronizar com API externa
+- 📊 Abrir dashboard/visualizações
+
+#### **Exemplo Básico:**
+
+```typescript
+import { Download, Upload } from 'lucide-react';
+
+const config = useMemo(() => ({
+  entityName: "Processo",
+  entityNamePlural: "Processos",
+  columns: processColumns,
+  formSections,
+  
+  // ✅ Ações customizadas
+  customActions: [
+    {
+      label: 'Importar',
+      icon: Upload,
+      variant: 'outline',
+      action: () => {
+        // Abrir dialog de importação
+        setImportDialogOpen(true);
+      }
+    },
+    {
+      label: 'Exportar',
+      icon: Download,
+      variant: 'outline',
+      action: async () => {
+        // Exportar dados filtrados/selecionados
+        const data = manager.entities;
+        await exportToCSV(data);
+      }
+    }
+  ]
+}), [manager.entities]);
+```
+
+#### **Propriedades:**
+
+| Propriedade | Tipo | Obrigatório | Descrição |
+|------------|------|-------------|-----------|
+| `label` | `string` | ✅ | Texto do botão |
+| `icon` | `ComponentType` | ❌ | Ícone do lucide-react |
+| `variant` | `'default' \| 'destructive' \| 'outline' \| 'ghost'` | ❌ | Estilo do botão (default: `'outline'`) |
+| `action` | `() => void` | ✅ | Função executada ao clicar |
+
+#### **Exemplo com Estado:**
+
+```typescript
+export default function ProcessesPage() {
+  const manager = useProcesses();
+  const [importDialogOpen, setImportDialogOpen] = useState(false);
+  const [syncLoading, setSyncLoading] = useState(false);
+  
+  const handleSyncWithAPI = async () => {
+    setSyncLoading(true);
+    try {
+      await syncProcessesWithExternalAPI();
+      manager.refetch(); // Recarregar dados
+      toast({ title: 'Sincronização concluída' });
+    } catch (error) {
+      toast({ title: 'Erro na sincronização', variant: 'destructive' });
+    } finally {
+      setSyncLoading(false);
+    }
+  };
+  
+  const config = useMemo(() => ({
+    entityName: "Processo",
+    entityNamePlural: "Processos",
+    columns: processColumns,
+    formSections,
+    customActions: [
+      {
+        label: syncLoading ? 'Sincronizando...' : 'Sincronizar',
+        icon: RefreshCw,
+        variant: 'outline',
+        action: handleSyncWithAPI
+      }
+    ]
+  }), [syncLoading, handleSyncWithAPI]);
+  
+  return (
+    <>
+      <CrudPage />
+      <ImportDialog open={importDialogOpen} onOpenChange={setImportDialogOpen} />
+    </>
+  );
+}
+```
+
+#### **Integração com Bulk Actions:**
+
+```typescript
+customActions: [
+  {
+    label: 'Exportar Selecionados',
+    icon: Download,
+    variant: 'outline',
+    action: () => {
+      if (manager.selectedIds.length === 0) {
+        toast({ title: 'Selecione pelo menos um item', variant: 'destructive' });
+        return;
+      }
+      
+      const selectedItems = manager.entities.filter(
+        item => manager.selectedIds.includes(item.id)
+      );
+      exportToCSV(selectedItems);
+    }
+  }
+]
+```
+
+**Boas Práticas:**
+- ✅ Use `useMemo` para evitar recriação em cada render
+- ✅ Use `variant="outline"` para ações secundárias
+- ✅ Use ícones do `lucide-react` para consistência visual
+- ✅ Mostre feedback (loading, toasts) para ações assíncronas
+- ❌ Evite muitas ações (máximo 3-4 para não poluir a UI)
+
+---
+
+### **6️⃣ Views Customizadas (substituir Tabela/Cards)**
+
+Substitua completamente a tabela padrão por qualquer componente customizado.
+
+#### **Casos de Uso Comuns:**
+- 📅 Calendário de eventos
+- 🗺️ Mapa de localizações
+- 🎨 Galeria de imagens
+- 📊 Dashboard com widgets
+- 🌳 Árvore hierárquica (processos/subprocessos)
+- 📋 Kanban board
+
+#### **Exemplo: Kanban Board**
+
+```typescript
+import { useMemo } from 'react';
+import { DragDropContext, Droppable, Draggable } from '@dnd-kit/core';
+
+const KanbanColumn = ({ title, tasks, status }) => (
+  <div className="flex flex-col gap-2 p-4 bg-muted rounded-lg min-w-[300px]">
+    <h3 className="font-semibold text-sm text-muted-foreground uppercase">{title}</h3>
+    <Droppable droppableId={status}>
+      {tasks.map((task, index) => (
+        <Draggable key={task.id} draggableId={task.id} index={index}>
+          <div className="p-3 bg-background border rounded shadow-sm cursor-move">
+            <p className="font-medium">{task.title}</p>
+            <p className="text-xs text-muted-foreground mt-1">{task.description}</p>
+          </div>
+        </Draggable>
+      ))}
+    </Droppable>
+  </div>
+);
+
+export default function TasksPage() {
+  const manager = useTasks();
+  
+  const config = useMemo(() => ({
+    entityName: "Tarefa",
+    entityNamePlural: "Tarefas",
+    columns: taskColumns,
+    formSections,
+    
+    // ✅ View customizada (Kanban)
+    customListView: (tasks: Task[], manager: CrudManager<Task>) => {
+      const columns = {
+        todo: tasks.filter(t => t.status === 'todo'),
+        in_progress: tasks.filter(t => t.status === 'in_progress'),
+        done: tasks.filter(t => t.status === 'done')
+      };
+      
+      return (
+        <DragDropContext onDragEnd={handleDragEnd}>
+          <div className="flex gap-4 overflow-x-auto">
+            <KanbanColumn title="A Fazer" tasks={columns.todo} status="todo" />
+            <KanbanColumn title="Em Progresso" tasks={columns.in_progress} status="in_progress" />
+            <KanbanColumn title="Concluído" tasks={columns.done} status="done" />
+          </div>
+        </DragDropContext>
+      );
+    }
+  }), [manager.entities]);
+  
+  return <CrudPage />;
+}
+```
+
+#### **Exemplo: Calendário de Eventos**
+
+```typescript
+import { Calendar } from '@/components/ui/calendar';
+import { Badge } from 'forlogic-core';
+import { format } from 'date-fns';
+import { ptBR } from 'date-fns/locale';
+
+const config = useMemo(() => ({
+  entityName: "Evento",
+  entityNamePlural: "Eventos",
+  columns: eventColumns,
+  formSections,
+  
+  customListView: (events: Event[]) => {
+    const [selectedDate, setSelectedDate] = useState<Date>(new Date());
+    
+    // Agrupar eventos por data
+    const eventsByDate = events.reduce((acc, event) => {
+      const dateKey = format(new Date(event.date), 'yyyy-MM-dd');
+      if (!acc[dateKey]) acc[dateKey] = [];
+      acc[dateKey].push(event);
+      return acc;
+    }, {} as Record<string, Event[]>);
+    
+    const selectedDateKey = format(selectedDate, 'yyyy-MM-dd');
+    const eventsForSelectedDate = eventsByDate[selectedDateKey] || [];
+    
+    return (
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+        {/* Calendário */}
+        <div>
+          <Calendar
+            mode="single"
+            selected={selectedDate}
+            onSelect={(date) => date && setSelectedDate(date)}
+            locale={ptBR}
+            modifiers={{
+              hasEvents: Object.keys(eventsByDate).map(d => new Date(d))
+            }}
+            modifiersStyles={{
+              hasEvents: { fontWeight: 'bold', textDecoration: 'underline' }
+            }}
+          />
+        </div>
+        
+        {/* Lista de eventos do dia selecionado */}
+        <div>
+          <h3 className="font-semibold mb-4">
+            Eventos de {format(selectedDate, "dd 'de' MMMM", { locale: ptBR })}
+          </h3>
+          
+          {eventsForSelectedDate.length === 0 ? (
+            <p className="text-muted-foreground">Nenhum evento neste dia</p>
+          ) : (
+            <div className="space-y-3">
+              {eventsForSelectedDate.map(event => (
+                <div key={event.id} className="p-4 border rounded-lg">
+                  <div className="flex items-start justify-between">
+                    <div>
+                      <p className="font-medium">{event.title}</p>
+                      <p className="text-sm text-muted-foreground">{event.time}</p>
+                    </div>
+                    <Badge>{event.type}</Badge>
+                  </div>
+                  <p className="text-sm mt-2">{event.description}</p>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+}), [manager.entities]);
+```
+
+#### **Exemplo: Galeria de Imagens**
+
+```typescript
+import { Dialog, DialogContent, DialogTrigger } from 'forlogic-core';
+
+const config = useMemo(() => ({
+  entityName: "Foto",
+  entityNamePlural: "Fotos",
+  columns: photoColumns,
+  formSections,
+  
+  customListView: (photos: Photo[]) => (
+    <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
+      {photos.map(photo => (
+        <Dialog key={photo.id}>
+          <DialogTrigger asChild>
+            <div className="aspect-square relative rounded-lg overflow-hidden cursor-pointer group">
+              <img 
+                src={photo.thumbnail_url} 
+                alt={photo.title}
+                className="w-full h-full object-cover group-hover:scale-105 transition-transform"
+              />
+              <div className="absolute inset-0 bg-black/50 opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center">
+                <p className="text-white font-medium">{photo.title}</p>
+              </div>
+            </div>
+          </DialogTrigger>
+          
+          <DialogContent className="max-w-4xl">
+            <img src={photo.full_url} alt={photo.title} className="w-full" />
+            <div className="mt-4">
+              <h3 className="font-semibold text-lg">{photo.title}</h3>
+              <p className="text-muted-foreground">{photo.description}</p>
+            </div>
+          </DialogContent>
+        </Dialog>
+      ))}
+    </div>
+  )
+}), [manager.entities]);
+```
+
+#### **Propriedades Recebidas:**
+
+```typescript
+customListView: (items: T[], manager?: CrudManager<T>) => React.ReactNode
+```
+
+| Parâmetro | Tipo | Descrição |
+|-----------|------|-----------|
+| `items` | `T[]` | Entidades filtradas/paginadas do manager |
+| `manager` | `CrudManager<T>` | Manager completo com métodos de CRUD |
+
+**Acesso ao Manager:**
+```typescript
+customListView: (items, manager) => (
+  <div>
+    {/* Acessar estado de loading */}
+    {manager.isLoading && <Spinner />}
+    
+    {/* Acessar busca atual */}
+    <p>Busca: {manager.searchTerm}</p>
+    
+    {/* Refetch manual */}
+    <Button onClick={() => manager.refetch()}>Recarregar</Button>
+    
+    {/* Criar nova entidade */}
+    <Button onClick={() => manager.createEntity(newData)}>Criar</Button>
+  </div>
+)
+```
+
+#### **Comportamento:**
+
+✅ **Mantém todas as funcionalidades:**
+- Paginação (footer fixo)
+- Busca global
+- Filtros customizados
+- Bulk actions (se habilitado)
+- Botão "Novo" + Custom Actions
+
+❌ **Remove automaticamente:**
+- Tabela/Cards padrão
+- Ações de linha (editar/deletar inline)
+- Seleção de itens (checkbox)
+
+**💡 Dica:** Se precisar de ações inline, implemente no seu componente customizado:
+
+```typescript
+customListView: (items, manager) => (
+  <div className="space-y-2">
+    {items.map(item => (
+      <div key={item.id} className="flex justify-between items-center p-4 border rounded">
+        <span>{item.title}</span>
+        <div className="flex gap-2">
+          <Button size="sm" onClick={() => handleEdit(item)}>Editar</Button>
+          <Button size="sm" variant="destructive" onClick={() => manager.deleteEntity(item.id)}>
+            Deletar
+          </Button>
+        </div>
+      </div>
+    ))}
+  </div>
+)
+```
+
+**Boas Práticas:**
+- ✅ Use `useMemo` para evitar recriação em cada render
+- ✅ Mantenha responsividade (grid com breakpoints)
+- ✅ Implemente loading states se necessário
+- ✅ Use componentes da lib (`Dialog`, `Badge`, etc) para consistência
+- ❌ Evite lógica pesada no render (mova para useMemo/useCallback)
+
+---
+
+### **7️⃣ Customizar Comportamento de Edição (`onEdit`)**
+
+Sobrescreva o comportamento padrão ao clicar em "Editar" nas linhas.
+
+#### **Casos de Uso Comuns:**
+- 🔀 Navegação para página dedicada de edição
+- 📋 Abrir modal customizado (diferente do BaseForm)
+- 🔍 Abrir modal somente-leitura (resumo)
+- 🔄 Transformar dados antes de abrir o formulário
+
+#### **Comportamento Padrão (sem `onEdit`):**
+
+```typescript
+// Ao clicar em "Editar":
+// 1. Abre modal com BaseForm
+// 2. Preenche campos com dados da entidade
+// 3. Chama handleSave ao submeter
+```
+
+#### **Exemplo 1: Navegação para Página Dedicada**
+
+```typescript
+import { useNavigate } from 'react-router-dom';
+
+export default function ProcessesPage() {
+  const navigate = useNavigate();
+  const manager = useProcesses();
+  
+  const config = useMemo(() => ({
+    entityName: "Processo",
+    entityNamePlural: "Processos",
+    columns: processColumns,
+    formSections,
+    
+    // ✅ Navegar ao invés de abrir modal
+    onEdit: (process: Process) => {
+      navigate(`/processos/${process.id}/editar`);
+      // Retornar void = não abre modal
+    }
+  }), [navigate]);
+  
+  return <CrudPage />;
+}
+```
+
+#### **Exemplo 2: Modal Somente-Leitura para Status Específico**
+
+```typescript
+// TrainingRequestsPage.tsx
+export default function TrainingRequestsPage() {
+  const manager = useTrainingRequests();
+  const [summaryModal, setSummaryModal] = useState<{
+    isOpen: boolean;
+    request: TrainingRequest | null;
+  }>({ isOpen: false, request: null });
+  
+  const config = useMemo(() => ({
+    entityName: "Solicitação",
+    entityNamePlural: "Solicitações",
+    columns,
+    formSections,
+    
+    // ✅ Modal de resumo se aprovada, editor padrão se não
+    onEdit: (request: TrainingRequest) => {
+      if (request.status === 'approved') {
+        // Abrir modal customizado
+        setSummaryModal({ isOpen: true, request });
+        return; // void = não abre BaseForm
+      }
+      
+      // Retornar undefined = usar comportamento padrão (abrir BaseForm)
+      // Nenhum return explícito necessário
+    }
+  }), []);
+  
+  return (
+    <>
+      <CrudPage />
+      
+      {/* Modal customizado */}
+      <TrainingRequestSummaryModal
+        request={summaryModal.request}
+        isOpen={summaryModal.isOpen}
+        onClose={() => setSummaryModal({ isOpen: false, request: null })}
+      />
+    </>
+  );
+}
+```
+
+#### **Exemplo 3: Transformar Dados Antes de Editar**
+
+```typescript
+const config = useMemo(() => ({
+  entityName: "Produto",
+  entityNamePlural: "Produtos",
+  columns,
+  formSections,
+  
+  // ✅ Modificar dados antes de popular o formulário
+  onEdit: (product: Product) => {
+    // Transformar preço de centavos para reais
+    const transformedProduct = {
+      ...product,
+      price: product.price / 100, // 1999 → 19.99
+      categories: product.category_ids?.join(',') // [1,2] → "1,2"
+    };
+    
+    // Retornar entidade transformada = abre BaseForm com dados modificados
+    return transformedProduct;
+  }
+}), []);
+```
+
+#### **Assinatura:**
+
+```typescript
+onEdit?: (entity: T) => T | void
+```
+
+| Retorno | Comportamento |
+|---------|---------------|
+| `T` (entidade transformada) | Abre `BaseForm` com dados transformados |
+| `void` / `undefined` | Não abre `BaseForm` (comportamento totalmente customizado) |
+| Sem `onEdit` | Comportamento padrão (abre `BaseForm` com dados originais) |
+
+#### **Exemplo 4: Condicionalmente Bloquear Edição**
+
+```typescript
+import { toast } from 'forlogic-core';
+
+const config = useMemo(() => ({
+  entityName: "Documento",
+  entityNamePlural: "Documentos",
+  columns,
+  formSections,
+  
+  onEdit: (document: Document) => {
+    // Bloquear edição se documento arquivado
+    if (document.status === 'archived') {
+      toast({
+        title: 'Documento arquivado',
+        description: 'Não é possível editar documentos arquivados',
+        variant: 'destructive'
+      });
+      return; // void = não abre modal
+    }
+    
+    // Permitir edição normalmente (sem return = undefined = padrão)
+  }
+}), []);
+```
+
+**Boas Práticas:**
+- ✅ Use `onEdit` para casos específicos (não generalize demais)
+- ✅ Retorne `void` quando **não quer** abrir o `BaseForm`
+- ✅ Retorne entidade transformada quando **quer** abrir o `BaseForm` com dados modificados
+- ✅ Não retorne nada (undefined) para usar comportamento padrão
+- ❌ Evite lógica pesada no `onEdit` (mova para funções separadas)
+
+**Integração com `useCustomRouting`:**
+
+```typescript
+const config = useMemo(() => ({
+  entityName: "Artigo",
+  entityNamePlural: "Artigos",
+  columns,
+  formSections,
+  useCustomRouting: true, // ✅ Não renderiza BaseForm
+  onEdit: (article) => {
+    navigate(`/artigos/${article.id}`);
+  },
+  onNew: () => {
+    navigate('/artigos/novo');
+  }
+}), [navigate]);
+```
+
+---
+
 ## 🔄 GUIA DE MIGRAÇÃO - v2.0
 
 Se você tem projetos usando versões antigas do `forlogic-core`, siga este guia para atualizar.