forlogic-core 1.7.0 → 1.7.2

package/README.md

@@ -11,6 +11,7 @@
 ### ⚠️ TOP 3 ERROS
 
 1. **ESQUECER SCHEMA**
+
 ```typescript
 // ❌ ERRADO
 .from('table')
@@ -20,12 +21,13 @@
 ```
 
 2. **RLS COM SINTAXE INCORRETA**
+
 ```sql
 -- ❌ ERRADO
 CREATE POLICY "Users view own" ON schema.table
 FOR SELECT USING (id_user = auth.uid());
 
--- ✅ CORRETO  
+-- ✅ CORRETO
 CREATE POLICY "Users view own" ON schema.table
 FOR SELECT USING (
   ((SELECT auth.jwt()) ->> 'alias'::text) = alias
@@ -33,6 +35,7 @@ FOR SELECT USING (
 ```
 
 3. **NÃO CRIAR ÍNDICES AUTOMATICAMENTE**
+
 ```sql
 -- ❌ PROIBIDO criar índices sem aprovação
 CREATE INDEX idx_table_user ON schema.table(id_user);
@@ -47,6 +50,7 @@ CREATE INDEX idx_table_user ON schema.table(id_user);
 ### ⚠️ PADRÕES OBRIGATÓRIOS
 
 **Foreign Keys (Chaves Estrangeiras):**
+
 ```typescript
 // ❌ ERRADO
 process_id: string
@@ -58,6 +62,7 @@ id_user: string
 ```
 
 **Booleans:**
+
 ```typescript
 // ❌ ERRADO
 active: boolean
@@ -69,6 +74,7 @@ is_removed: boolean
 ```
 
 **Timestamps:**
+
 ```typescript
 // ❌ ERRADO
 creation_date: string
@@ -85,15 +91,18 @@ deleted_at: string
 ## 🚫 ÍNDICES: ABSOLUTAMENTE PROIBIDO CRIAR AUTOMATICAMENTE
 
 ### ⚠️ REGRA DE OURO
+
 **NUNCA, EM HIPÓTESE ALGUMA, criar índices automaticamente em migrations!**
 
 ### 🤔 Por Quê?
+
 1. **Custo**: Índices ocupam espaço em disco e custam dinheiro
 2. **Performance de Escrita**: Cada índice adiciona overhead em INSERTs/UPDATEs
 3. **Otimização Prematura**: 99% dos índices criados "por precaução" nunca são usados
 4. **Manutenção**: Índices desnecessários dificultam manutenção e análise de queries
 
 ### ❌ Casos PROIBIDOS (mesmo que pareçam "boas práticas")
+
 ```sql
 -- ❌ PROIBIDO: Índice em FK "porque é boa prática"
 CREATE INDEX idx_subprocess_process ON subprocesses(id_process);
@@ -108,11 +117,13 @@ CREATE INDEX idx_deliverable_status ON deliverables(id_subprocess, is_completed)
 ### ✅ Quando Criar Índices?
 
 **APENAS** quando:
+
 1. ✅ **Solicitado explicitamente** pelo usuário
 2. ✅ **Análise de performance** comprovou necessidade (EXPLAIN ANALYZE)
 3. ✅ **Aprovação prévia** do usuário para incluir na migration
 
 ### 📋 Checklist OBRIGATÓRIO Antes de Qualquer Migration
+
 ```markdown
 - [ ] A migration NÃO contém NENHUM `CREATE INDEX`?
 - [ ] Se contém, o usuário solicitou EXPLICITAMENTE?
@@ -121,6 +132,7 @@ CREATE INDEX idx_deliverable_status ON deliverables(id_subprocess, is_completed)
 ```
 
 ### 🔧 Processo Correto Para Criar Índices
+
 1. **Usuário solicita** OU problemas de performance são detectados
 2. **Rodar EXPLAIN ANALYZE** para confirmar necessidade
 3. **Perguntar ao usuário**: "Posso criar o índice X na coluna Y? Isso vai melhorar a query Z mas adiciona overhead."
@@ -128,9 +140,10 @@ CREATE INDEX idx_deliverable_status ON deliverables(id_subprocess, is_completed)
 5. **Criar migration separada** apenas com os índices aprovados
 
 ### 📝 Template de Migration de Índices (quando aprovado)
+
 ```sql
 -- Migration: [TIMESTAMP]_add_performance_indexes.sql
--- Aprovado em: [DATA] 
+-- Aprovado em: [DATA]
 -- Justificativa: [RAZÃO ESPECÍFICA]
 
 CREATE INDEX idx_processes_title ON processes.processes(title);
@@ -144,6 +157,7 @@ CREATE INDEX idx_processes_title ON processes.processes(title);
 ### ⚠️ ARQUIVOS PROIBIDOS DE CRIAR LOCALMENTE
 
 **NUNCA crie estes arquivos localmente:**
+
 ```typescript
 // ❌ PROIBIDO - Usar da lib
 src/lib/utils.ts          // cn() já existe no forlogic-core
@@ -157,6 +171,7 @@ src/components/ui/input.tsx
 ### ✅ Imports Corretos
 
 **Utils (cn):**
+
 ```typescript
 // ❌ ERRADO
 import { cn } from '@/lib/utils'
@@ -166,6 +181,7 @@ import { cn } from 'forlogic-core'
 ```
 
 **Componentes UI:**
+
 ```typescript
 // ❌ ERRADO
 import { Dialog } from '@/components/ui/dialog'
@@ -177,6 +193,7 @@ import { Button } from 'forlogic-core'
 ```
 
 ### 📋 Checklist Antes de Criar Novo Arquivo
+
 ```markdown
 - [ ] Este componente/util JÁ existe no forlogic-core?
 - [ ] Verifiquei a lista de exports disponíveis abaixo?
@@ -186,15 +203,16 @@ import { Button } from 'forlogic-core'
 ### 📦 Componentes e Utils Disponíveis no forlogic-core
 
 **🎨 Componentes UI:**
+
 ```typescript
 // Formulários
-Button, Input, Textarea, Label, Select, SelectContent, 
-SelectItem, SelectTrigger, SelectValue, Checkbox, RadioGroup, 
+Button, Input, Textarea, Label, Select, SelectContent,
+SelectItem, SelectTrigger, SelectValue, Checkbox, RadioGroup,
 RadioGroupItem, Switch
 
 // Layout
 Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle
-Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, 
+Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader,
 DialogTitle, DialogTrigger
 Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle
 Separator, ScrollArea
@@ -216,6 +234,7 @@ Table, TableBody, TableCell, TableHead, TableHeader, TableRow
 ```
 
 **🛠️ Utils e Hooks:**
+
 ```typescript
 // Utils
 cn                        // Merge classes Tailwind
@@ -246,6 +265,7 @@ errorService             // Service de erros
 ### 🔍 Como Verificar Exports Disponíveis
 
 Se não tiver certeza se algo existe no forlogic-core:
+
 1. Abra `node_modules/forlogic-core/package.json`
 2. Verifique os exports disponíveis
 3. Em caso de dúvida, pergunte ao usuário antes de criar localmente
@@ -259,6 +279,7 @@ Se não tiver certeza se algo existe no forlogic-core:
 **Quando usar?**
 
 Use o `EntitySelect` para criar dropdowns com busca e ordenação para qualquer entidade do sistema:
+
 - ✅ Seleção de processos, departamentos, categorias, etc
 - ✅ Busca em tempo real
 - ✅ Ordenação alfabética automática
@@ -292,22 +313,22 @@ function MyForm() {
 
 **Props do EntitySelect:**
 
-| Prop | Tipo | Obrigatório | Descrição |
-|------|------|-------------|-----------|
-| `items` | `T[]` | ✅ | Array de itens para seleção |
-| `getItemValue` | `(item: T) => string` | ✅ | Função que retorna o valor único do item (ex: `id`) |
-| `getItemLabel` | `(item: T) => string` | ✅ | Função que retorna o texto exibido |
-| `value` | `string` | ❌ | Valor selecionado |
-| `onChange` | `(value: string) => void` | ❌ | Callback quando valor muda |
-| `isLoading` | `boolean` | ❌ | Mostra skeleton durante carregamento |
-| `error` | `Error \| null` | ❌ | Mostra mensagem de erro |
-| `placeholder` | `string` | ❌ | Placeholder do select (padrão: "Selecionar...") |
-| `searchPlaceholder` | `string` | ❌ | Placeholder da busca (padrão: "Buscar...") |
-| `emptyMessage` | `string` | ❌ | Mensagem quando não há itens |
-| `noResultsMessage` | `string` | ❌ | Mensagem quando busca não encontra resultados |
-| `sortItems` | `(a: T, b: T) => number` | ❌ | Função customizada de ordenação (padrão: alfabético) |
-| `disabled` | `boolean` | ❌ | Desabilita o select |
-| `className` | `string` | ❌ | Classes CSS adicionais |
+| Prop                | Tipo                      | Obrigatório | Descrição                                            |
+| ------------------- | ------------------------- | ----------- | ---------------------------------------------------- |
+| `items`             | `T[]`                     | ✅          | Array de itens para seleção                          |
+| `getItemValue`      | `(item: T) => string`     | ✅          | Função que retorna o valor único do item (ex: `id`)  |
+| `getItemLabel`      | `(item: T) => string`     | ✅          | Função que retorna o texto exibido                   |
+| `value`             | `string`                  | ❌          | Valor selecionado                                    |
+| `onChange`          | `(value: string) => void` | ❌          | Callback quando valor muda                           |
+| `isLoading`         | `boolean`                 | ❌          | Mostra skeleton durante carregamento                 |
+| `error`             | `Error \| null`           | ❌          | Mostra mensagem de erro                              |
+| `placeholder`       | `string`                  | ❌          | Placeholder do select (padrão: "Selecionar...")      |
+| `searchPlaceholder` | `string`                  | ❌          | Placeholder da busca (padrão: "Buscar...")           |
+| `emptyMessage`      | `string`                  | ❌          | Mensagem quando não há itens                         |
+| `noResultsMessage`  | `string`                  | ❌          | Mensagem quando busca não encontra resultados        |
+| `sortItems`         | `(a: T, b: T) => number`  | ❌          | Função customizada de ordenação (padrão: alfabético) |
+| `disabled`          | `boolean`                 | ❌          | Desabilita o select                                  |
+| `className`         | `string`                  | ❌          | Classes CSS adicionais                               |
 
 **Ordenação Customizada:**
 
@@ -375,7 +396,7 @@ import { useProcesses } from '@/processes/processService';
 
 export function ProcessSelect({ value, onChange, disabled }: any) {
   const { data: processes = [], isLoading, error } = useProcesses();
-  
+
   return (
     <EntitySelect
       value={value}
@@ -421,7 +442,7 @@ interface DepartmentSelectProps {
 
 export function DepartmentSelect(props: DepartmentSelectProps) {
   const { data: departments = [], isLoading, error } = useDepartments();
-  
+
   return (
     <EntitySelect
       {...props}
@@ -441,13 +462,541 @@ export function DepartmentSelect(props: DepartmentSelectProps) {
 
 ---
 
+### 🎨 Campos Customizados no BaseForm
+
+O `BaseForm` suporta campos totalmente customizados através do tipo `'custom'`, permitindo usar **qualquer componente React** como campo de formulário.
+
+#### Interface do Componente Customizado
+
+Todo campo customizado deve seguir esta interface:
+
+```typescript
+interface CustomFieldProps {
+  value: any;                    // Valor atual do campo
+  onChange: (value: any) => void; // Função para atualizar o valor
+  disabled?: boolean;             // Se o campo está desabilitado
+  error?: string;                 // Mensagem de erro de validação
+  [key: string]: any;             // Props adicionais via componentProps
+}
+```
+
+#### Exemplo Completo: TagsField
+
+**1. Criar o Componente Customizado:**
+
+```typescript
+// src/components/TagsField.tsx
+import { Label, Badge } from 'forlogic-core';
+import { X } from 'lucide-react';
+
+interface TagsFieldProps {
+  value: string[];
+  onChange: (value: string[]) => void;
+  disabled?: boolean;
+  error?: string;
+  label?: string;
+  availableTags?: Array<{ id: string; name: string; color: string }>;
+}
+
+export function TagsField({
+  value = [],
+  onChange,
+  disabled = false,
+  error,
+  label = 'Tags',
+  availableTags = []
+}: TagsFieldProps) {
+  const handleToggleTag = (tagId: string) => {
+    if (disabled) return;
+
+    const newValue = value.includes(tagId)
+      ? value.filter(id => id !== tagId)
+      : [...value, tagId];
+
+    onChange(newValue);
+  };
+
+  return (
+    <div className="space-y-2">
+      <Label>{label}</Label>
+      <div className="flex flex-wrap gap-2">
+        {availableTags.map(tag => {
+          const isSelected = value.includes(tag.id);
+          return (
+            <Badge
+              key={tag.id}
+              variant={isSelected ? 'default' : 'outline'}
+              className="cursor-pointer"
+              style={isSelected ? { backgroundColor: tag.color } : {}}
+              onClick={() => handleToggleTag(tag.id)}
+            >
+              {tag.name}
+              {isSelected && <X className="ml-1 h-3 w-3" />}
+            </Badge>
+          );
+        })}
+      </div>
+      {error && <p className="text-sm text-red-500">{error}</p>}
+    </div>
+  );
+}
+```
+
+**2. Usar no FormField:**
+
+```typescript
+import { TagsField } from './components/TagsField';
+
+const formFields: FormField[] = [
+  {
+    name: 'tag_ids',
+    label: '',
+    type: 'custom',
+    component: TagsField,
+    componentProps: {
+      label: 'Tags do Artigo',
+      availableTags: [
+        { id: '1', name: 'Urgente', color: '#ef4444' },
+        { id: '2', name: 'Importante', color: '#f59e0b' }
+      ]
+    },
+    validation: (value) => {
+      if (!value?.length) return 'Selecione ao menos uma tag';
+    }
+  }
+];
+```
+
+#### Características
+
+- ✅ **Integração Total** - `value`, `onChange`, `disabled`, `error` gerenciados automaticamente
+- ✅ **Validação** - Funciona normalmente com `validation`
+- ✅ **Flexibilidade** - Props extras via `componentProps`
+- ✅ **Reatividade** - `updateField` e `onValueChange` funcionam corretamente
+
+#### Exemplos Adicionais
+
+**MultiSelect com Busca:**
+
+```typescript
+{
+  name: 'categories',
+  type: 'custom',
+  component: MultiSelectField,
+  componentProps: {
+    options: categories,
+    searchable: true
+  }
+}
+```
+
+**Rich Text Editor:**
+
+```typescript
+{
+  name: 'content',
+  type: 'custom',
+  component: RichTextEditor,
+  componentProps: {
+    toolbar: ['bold', 'italic', 'link'],
+    minHeight: 200
+  }
+}
+```
+
+#### Considerações de Segurança
+
+- ⚠️ Componentes customizados devem ser **confiáveis** (não executar código arbitrário)
+- ⚠️ Validar todas as props recebidas
+- ⚠️ Sanitizar inputs antes de enviar ao backend
+
+---
+
+### 🔘 ActionButton - Botão de Ações para Tabelas
+
+Componente otimizado para menus de ação em linhas de tabela, com design discreto e consistente.
+
+#### Características
+
+- ✅ **Fundo azul claro** (bg-primary/10) com destaque visual
+- ✅ **Tamanho compacto** (28px altura)
+- ✅ **Ícone padrão** (três pontos verticais)
+- ✅ **Hover suave** (primary/20)
+- ✅ **Integração** com `DropdownMenu`
+...
+#### Estilo Visual
+
+**Default (padrão):**
+- Fundo: `bg-primary/10` (azul claro)
+- Texto: `text-primary` (azul)
+- Borda: `border-primary/30` (azul médio)
+- Hover: `hover:bg-primary/20` (azul mais intenso)
+- Altura: `h-7` (28px)
+
+**Comparação com Button normal:**
+
+```typescript
+// ❌ EVITAR - Botão normal muito grande
+<Button size="sm">
+  <EllipsisVertical />
+</Button>
+
+// ✅ RECOMENDADO - ActionButton compacto
+<ActionButton />
+```
+
+#### Quando Usar?
+
+| Cenário | Use |
+|---------|-----|
+| Menu de ações em tabelas | ✅ `ActionButton` |
+| Ações inline (sem dropdown) | ✅ `Button` normal |
+| Formulários | ✅ `Button` normal |
+| Header de página | ✅ `Button` normal |
+
+#### Integração com CRUD
+
+O sistema CRUD usa automaticamente o `ActionButton` através do componente `TableRowActions`:
+
+```typescript
+// Gerado automaticamente pelo createCrudPage()
+<TableRowActions
+  onEdit={() => handleEdit(item)}
+  onDelete={() => handleDelete(item)}
+  onToggleStatus={() => handleToggle(item)}
+  isActive={item.is_active}
+/>
+```
+
+#### Props
+
+```typescript
+interface ActionButtonProps {
+  variant?: 'default' | 'ghost';  // Estilo do botão
+  children?: React.ReactNode;     // Ícone customizado
+  onClick?: () => void;           // Handler de click
+  disabled?: boolean;             // Desabilitar botão
+  className?: string;             // Classes adicionais
+}
+```
+
+#### Acessibilidade
+
+```typescript
+<ActionButton 
+  aria-label="Abrir menu de ações"
+  onClick={() => console.log('clicked')}
+/>
+```
+
+---
+
+### 📄 Títulos de Página com 3 Linhas
+
+O hook `usePageMetadata` suporta até **3 linhas de informação** no header através dos campos `supertitle`, `title` e `subtitle`.
+
+#### Estrutura Visual
+
+```
+[supertitle - text-xs, cinza claro]    ← Contexto/Breadcrumb
+[title - text-lg, bold, preto] [Badge] ← Título principal
+[subtitle - text-sm, cinza]            ← Metadados/Descrição
+```
+
+#### Exemplo Completo (3 Linhas)
+
+```typescript
+import { usePageMetadata } from 'forlogic-core';
+
+function KRDetailsPage() {
+  usePageMetadata({
+    supertitle: 'OKR1 Tracionar o trabalho de processos melhorando a eficácia',
+    title: 'KR1 50% dos indicadores de empreendimento e áreas de negócio atingindo a meta',
+    subtitle: '25Q4 • Ativo • 01/10/2025 - 31/12/2025 • Laura Alves Nunes Oliveira'
+  });
+
+  return <div>Conteúdo da página...</div>;
+}
+```
+
+**Resultado visual:**
+
+```
+OKR1 Tracionar o trabalho de processos melhorando a eficácia
+KR1 50% dos indicadores de empreendimento e áreas de negócio atingindo a meta [Módulo]
+25Q4 • Ativo • 01/10/2025 - 31/12/2025 • Laura Alves Nunes Oliveira
+```
+
+---
+
+#### Exemplo com 2 Linhas
+
+```typescript
+usePageMetadata({
+  title: 'Gestão de Processos',
+  subtitle: 'Visualize e gerencie todos os processos da organização'
+});
+```
+
+**Resultado visual:**
+
+```
+Gestão de Processos [Módulo]
+Visualize e gerencie todos os processos da organização
+```
+
+---
+
+#### Exemplo com Dados Dinâmicos
+
+```typescript
+import { useParams } from 'react-router-dom';
+import { usePageMetadata } from 'forlogic-core';
+
+function ProcessDetailPage() {
+  const { id } = useParams();
+  const { data: process } = useProcess(id);
+  const { data: okr } = useOKR(process?.okr_id);
+
+  usePageMetadata({
+    supertitle: okr?.name || 'Carregando...',
+    title: process?.name || 'Carregando...',
+    subtitle: [
+      process?.quarter,
+      process?.status,
+      `${process?.start_date} - ${process?.end_date}`,
+      process?.responsible_name
+    ].filter(Boolean).join(' • ')
+  });
+
+  return <div>...</div>;
+}
+```
+
+---
+
+#### Quando Usar Cada Campo?
+
+| Campo        | Uso                                          | Exemplo                                                         |
+| ------------ | -------------------------------------------- | --------------------------------------------------------------- |
+| `supertitle` | Contexto/hierarquia acima do item atual      | "OKR1 Melhorar eficácia", "Departamento → Setor"                |
+| `title`      | Nome/identificação principal do item         | "KR1 50% dos indicadores atingindo meta", "Gestão de Processos" |
+| `subtitle`   | Metadados, descrição, informações adicionais | "25Q4 • Ativo • 01/10/2025", "Visualize todos os processos"     |
+
+---
+
+#### Características
+
+✅ **Opcional** - Todos os campos são opcionais  
+✅ **Truncate automático** - Textos longos são cortados com `...`  
+✅ **Backward compatible** - Projetos antigos continuam funcionando  
+✅ **Renderização condicional** - Linhas vazias não são exibidas  
+✅ **Type-safe** - TypeScript valida os tipos automaticamente
+
+---
+
+#### Boas Práticas
+
+**✅ BOM - Hierarquia clara:**
+
+```typescript
+usePageMetadata({
+  supertitle: 'Contexto maior (departamento, categoria, OKR)',
+  title: 'Item específico atual',
+  subtitle: 'Metadados (datas, status, responsável)'
+});
+```
+
+**❌ EVITAR - Textos muito longos:**
+
+```typescript
+// Textos serão truncados, use resumos curtos
+supertitle: 'Este é um texto extremamente longo que será cortado...'
+```
+
+**✅ BOM - Separadores visuais no subtitle:**
+
+```typescript
+subtitle: '25Q4 • Ativo • 01/10/2025 - 31/12/2025 • João Silva'
+//         ^^^^^ Use • (bullet) para separar informações
+```
+
+**✅ BOM - Dados dinâmicos com fallback:**
+
+```typescript
+supertitle: okr?.name || undefined  // Não exibe se não houver dados
+title: process?.name || 'Carregando...'
+```
+
+---
+
+#### Exemplo Real: Sistema de OKRs
+
+```typescript
+import { useParams } from 'react-router-dom';
+import { usePageMetadata } from 'forlogic-core';
+import { useOKR, useKR } from './hooks';
+
+function KRDetailsPage() {
+  const { krId } = useParams();
+  const { data: kr, isLoading } = useKR(krId);
+  const { data: okr } = useOKR(kr?.okr_id);
+
+  usePageMetadata({
+    supertitle: okr?.name,
+    title: kr?.name || 'Carregando...',
+    subtitle: kr ? [
+      kr.quarter,
+      kr.status,
+      `${kr.start_date} - ${kr.end_date}`,
+      kr.responsible_name
+    ].filter(Boolean).join(' • ') : undefined
+  });
+
+  if (isLoading) return <div>Carregando...</div>;
+
+  return (
+    <div className="p-6">
+      {/* Conteúdo da página de KR */}
+    </div>
+  );
+}
+```
+
+**Resultado visual:**
+
+```
+OKR1 Tracionar o trabalho de processos melhorando a eficácia
+KR1 50% dos indicadores de empreendimento e áreas de negócio atingindo a meta [Módulo]
+25Q4 • Ativo • 01/10/2025 - 31/12/2025 • Laura Alves Nunes Oliveira
+```
+
+---
+
+### 🏢 Sistema de Gestores de Locais (Qualiex)
+
+Componentes para gerenciamento de gestores e membros de locais/sublocais integrados com a API Qualiex.
+
+#### Importação
+
+```typescript
+import {
+  PlaceManagerButton,
+  PlaceManagerBadge,
+  ManagerSelectionDialog,
+  usePlaceManagers,
+  PlaceManagerService,
+  type PlaceManager
+} from 'forlogic-core';
+```
+
+#### Componentes
+
+**PlaceManagerButton** - Botão dropdown com ações de gerenciamento:
+
+```tsx
+<PlaceManagerButton
+  placeId="abc-123"
+  placeName="Matriz São Paulo"
+  serviceConfig={{ tableName: 'place_managers' }}
+/>
+```
+
+**PlaceManagerBadge** - Badge visual com contador de gestores:
+
+```tsx
+<PlaceManagerBadge
+  placeId="abc-123"
+  userCount={15}
+/>
+```
+
+**ManagerSelectionDialog** - Diálogo completo de seleção:
+
+```tsx
+<ManagerSelectionDialog
+  open={showDialog}
+  onOpenChange={setShowDialog}
+  onSelectManager={(user) => console.log('Gestor:', user)}
+  onSelectMember={(user) => console.log('Membro:', user)}
+  currentManagerId={manager?.user_id}
+  currentMemberIds={members.map(m => m.user_id)}
+  placeName="Matriz São Paulo"
+/>
+```
+
+#### Hook: usePlaceManagers
+
+```typescript
+const {
+  managers,      // Todos (gestor + membros)
+  manager,       // Apenas o gestor
+  members,       // Apenas membros
+  setManager,    // (user: QualiexUser) => void
+  addMember,     // (user: QualiexUser) => void
+  remove,        // (userId: string) => void
+  isLoading
+} = usePlaceManagers(placeId);
+```
+
+#### Service: PlaceManagerService
+
+```typescript
+import { PlaceManagerService } from 'forlogic-core';
+
+// Instância customizada
+const service = new PlaceManagerService({
+  tableName: 'my_place_managers',
+  schemaName: 'custom_schema'
+});
+
+// Métodos disponíveis
+await service.getPlaceManagers(alias, placeId);
+await service.setManager(alias, placeId, user);
+await service.addMember(alias, placeId, user);
+await service.removePlaceUser(alias, placeId, userId);
+```
+
+> ⚠️ A configuração do banco de dados (tabelas, RLS policies) deve ser feita no projeto consumidor.
+
+#### Regras de Negócio
+
+1. **Um gestor por local** - Ao definir novo gestor, o anterior é removido automaticamente
+2. **Membros ilimitados** - Múltiplos membros podem ser adicionados
+3. **Ordenação alfabética** - Sempre ordenado por nome
+4. **Busca inteligente** - Filtra por nome ou email
+
+#### Exemplo Completo
+
+```tsx
+function PlaceTreeItem({ place }) {
+  return (
+    <div className="flex items-center gap-3">
+      <span>{place.name}</span>
+
+      <PlaceManagerBadge
+        placeId={place.id}
+        userCount={place.usersIds.length}
+      />
+
+      <PlaceManagerButton
+        placeId={place.id}
+        placeName={place.name}
+      />
+    </div>
+  );
+}
+```
+
+---
+
 ### ✅ CHECKLIST (antes de implementar)
 
 - [ ] Schema `schema` especificado em queries e service?
 - [ ] RLS usando extração JWT `((SELECT auth.jwt()) ->> 'alias'::text) = alias`?
 - [ ] **Nomenclatura correta**: `id_<entity>`, `is_<bool>`, `<action>_at`?
 - [ ] **Migration SEM índices** (ou aprovados pelo usuário)?
-- [ ] **Imports do forlogic-core** (não criar utils.ts ou ui/* localmente)?
+- [ ] **Imports do forlogic-core** (não criar utils.ts ou ui/\* localmente)?
 - [ ] Preservar `item.id` no update?
 - [ ] Config gerado com `useMemo()`?
 - [ ] `<Outlet />` no componente pai?
@@ -468,10 +1017,10 @@ graph TD
     E --> F[CrudTable<br/>Tabela]
     E --> G[BaseForm<br/>Formulário]
     E --> H[BulkActionBar<br/>Ações em Massa]
-    
+
     I[(Supabase DB)] -.->|RLS + Soft Delete| B
     J[Qualiex API] -.->|responsible_name| B
-    
+
     style A fill:#e1f5ff
     style B fill:#fff4e1
     style C fill:#ffe1f5
@@ -589,7 +1138,7 @@ import { usePageMetadataContext } from 'forlogic-core';
 
 export default function MyPage() {
   const { setMetadata } = usePageMetadataContext();
-  
+
   useEffect(() => {
     setMetadata({
       title: 'Meus Itens',
@@ -610,11 +1159,13 @@ export const SEARCH_CONFIG = {
 ```
 
 **Quando aumentar o delay:**
+
 - ✅ Muitos usuários simultâneos (reduz carga no servidor)
 - ✅ Campos de busca muito amplos (muitos registros)
 - ✅ Backend com rate limiting
 
 **Quando reduzir o delay:**
+
 - ✅ Poucos registros (resposta instantânea)
 - ✅ Busca crítica para UX (feedback imediato)
 
@@ -664,16 +1215,128 @@ graph LR
     D --> E[useCrud lê URL]
     E --> F[Supabase Query]
     F --> G[Resultados filtrados]
-    
+
     style C fill:#d4f4dd
     style F fill:#ffd4d4
 ```
 
 ---
 
+## 🎯 ARQUITETURA DE 3 NÍVEIS - CRUD COMPONENTS
+
+O sistema CRUD oferece **3 níveis de abstração**:
+
+### **📊 Quando Usar Cada Nível?**
+
+| Cenário                    | Nível              | Componentes               |
+| -------------------------- | ------------------ | ------------------------- |
+| CRUD padrão                | 🟩 Página Completa | `createCrudPage()`        |
+| CRUD customizado           | 🔶 Compostos       | `CrudTable` + `FilterBar` |
+| Dashboard/Tabelas não-CRUD | 🔷 Primitivos      | `TablePrimitive`          |
+| Kanban/Grid customizado    | 🔷 Primitivos      | `CardsPrimitive`          |
+
+### **🔷 NÍVEL 1 - Primitivos (Controle Total)**
+
+Componentes puros **sem lógica CRUD**:
+
+```typescript
+import {
+  TablePrimitive,        // Tabela reutilizável
+  ActionMenuPrimitive,   // Menu de ações
+  PaginationPrimitive,   // Paginação manual
+  FilterBarPrimitive,    // Barra de filtros
+  CardsPrimitive         // Grid de cards
+} from 'forlogic-core';
+```
+
+**Exemplo:**
+
+```typescript
+<TablePrimitive
+  data={reports}
+  columns={[
+    { key: 'date', header: 'Data', sortable: true },
+    { key: 'revenue', header: 'Receita' }
+  ]}
+  onSort={handleSort}
+  renderActions={(item) => (
+    <ActionMenuPrimitive customActions={[...]} />
+  )}
+/>
+```
+
+### **🔶 NÍVEL 2 - Compostos (CRUD Integrado)**
+
+Primitivos + lógica CRUD:
+
+```typescript
+import {
+  CrudTable,          // Tabela com CRUD
+  CrudCards,          // Cards com CRUD
+  CrudPagination,     // Paginação integrada
+  FilterBar,          // Filtros integrados
+  BulkActionBar       // Ações em massa
+} from 'forlogic-core';
+```
+
+**Exemplo:**
+
+```typescript
+<FilterBar
+  searchValue={manager.searchTerm}
+  onSearchChange={manager.handleSearch}
+  customFilters={[<StatusSelect />]}
+/>
+
+<CrudTable
+  manager={manager}
+  columns={customColumns}
+  renderActions={(item) => <CustomActions item={item} />}
+/>
+
+<CrudPagination manager={manager} />
+```
+
+### **🟩 NÍVEL 3 - Página Completa (Geração Automática)**
+
+API de alto nível:
+
+```typescript
+import {
+  createCrudPage,        // Gera página completa
+  generateCrudConfig,    // Config automática
+  createSimpleService    // Service + Hook
+} from 'forlogic-core';
+```
+
+**Exemplo:**
+
+```typescript
+const config = useMemo(() =>
+  generateCrudConfig<Product>({
+    entity: 'produto',
+    columns: [
+      { key: 'name', label: 'Nome', required: true },
+      { key: 'price', label: 'Preço', type: 'number' }
+    ]
+  }),
+[]);
+
+return createCrudPage({ config, crud: manager, saveHandler: manager.save });
+```
+
+### **🧪 Página de Demonstração**
+
+Acesse **`/demo-crud`** para ver todos os componentes em ação com exemplos práticos.
+
+---
+
+---
+
 ## 🚀 QUICK START - Criar CRUD Completo
 
 ### **1️⃣ Type**
+
 ```typescript
 // src/processes/process.ts
 export interface Process {
@@ -692,12 +1355,13 @@ export type ProcessUpdate = Partial<ProcessInsert>;
 ```
 
 ### **2️⃣ Service**
+
 ```typescript
 // src/processes/processService.ts
 import { createSimpleService } from 'forlogic-core';
 import { Process, ProcessInsert, ProcessUpdate } from './process';
 
-export const { service: processService, useCrudHook: useProcesses } = 
+export const { service: processService, useCrudHook: useProcesses } =
   createSimpleService<Process, ProcessInsert, ProcessUpdate>({
     tableName: 'processes',
     entityName: 'processo',
@@ -708,6 +1372,7 @@ export const { service: processService, useCrudHook: useProcesses } =
 ```
 
 ### **3️⃣ Save Handler (Integrado ao useCrud)**
+
 ```typescript
 // src/processes/ProcessesPage.tsx
 
@@ -731,6 +1396,7 @@ export default function ProcessesPage() {
 ```
 
 ### **4️⃣ Config (com useMemo)**
+
 ```typescript
 // src/processes/ProcessesPage.tsx
 import { useMemo } from 'react';
@@ -740,12 +1406,12 @@ export default function ProcessesPage() {
   const crud = useProcesses();
 
   // ⚠️ OBRIGATÓRIO useMemo para evitar re-renders
-  const config = useMemo(() => 
+  const config = useMemo(() =>
     generateCrudConfig<Process>({
       entity: 'processo',
       columns: [
         { key: 'title', label: 'Título', type: 'text', required: true },
-        { key: 'status', label: 'Status', type: 'select', 
+        { key: 'status', label: 'Status', type: 'select',
           options: [
             { value: 'draft', label: 'Rascunho' },
             { value: 'active', label: 'Ativo' },
@@ -754,7 +1420,7 @@ export default function ProcessesPage() {
         },
         { key: 'description', label: 'Descrição', type: 'textarea' }
       ]
-    }), 
+    }),
   []);
 
   return createCrudPage({
@@ -766,6 +1432,7 @@ export default function ProcessesPage() {
 ```
 
 ### **5️⃣ Page + Outlet (preservar estado)**
+
 ```typescript
 // src/App.tsx
 import { Outlet } from 'react-router-dom';
@@ -805,16 +1472,17 @@ npm install forlogic-core@latest
 ### **1️⃣ Migração de Tipos (Breaking Change)**
 
 #### **❌ ANTES (Versão Antiga):**
+
 ```typescript
-import { 
-  ContentEntity, 
-  VisualEntity, 
-  UserRelatedEntity, 
+import {
+  ContentEntity,
+  VisualEntity,
+  UserRelatedEntity,
   ActivableEntity,
-  FormEntity 
+  FormEntity
 } from 'forlogic-core';
 
-export interface Example extends 
+export interface Example extends
   ContentEntity,
   VisualEntity,
   UserRelatedEntity,
@@ -839,6 +1507,7 @@ export interface UpdateExamplePayload extends Partial<CreateExamplePayload> {
 ```
 
 #### **✅ DEPOIS (Nova API):**
+
 ```typescript
 import { BaseEntity } from 'forlogic-core';
 
@@ -855,7 +1524,7 @@ export interface Example extends BaseEntity {
 }
 
 export type CreateExamplePayload = Omit<
-  Example, 
+  Example,
   keyof BaseEntity | 'responsible_name'
 >;
 
@@ -863,6 +1532,7 @@ 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`
@@ -873,6 +1543,7 @@ export type UpdateExamplePayload = Partial<CreateExamplePayload>;
 ### **2️⃣ Migração de Save Handler (Breaking Change)**
 
 #### **❌ ANTES (createSimpleSaveHandler):**
+
 ```typescript
 import { createSimpleSaveHandler, useAuth } from 'forlogic-core';
 
@@ -895,6 +1566,7 @@ const handleSave = createSimpleSaveHandler(
 ```
 
 #### **✅ DEPOIS (manager.save):**
+
 ```typescript
 const handleSave = (data: any) => {
   manager.save(data, (d) => ({
@@ -910,6 +1582,7 @@ const handleSave = (data: any) => {
 ```
 
 **📝 Mudanças:**
+
 - ❌ **REMOVIDO**: `createSimpleSaveHandler`
 - ❌ **REMOVIDO**: Import de `useAuth` para pegar `alias`
 - ✅ **NOVO**: `manager.save(data, transform)`
@@ -920,6 +1593,7 @@ const handleSave = (data: any) => {
 ### **3️⃣ Migração de Campos de Formulário**
 
 #### **❌ ANTES (Tipos Múltiplos):**
+
 ```typescript
 {
   name: 'id_user',
@@ -930,6 +1604,7 @@ const handleSave = (data: any) => {
 ```
 
 #### **✅ DEPOIS (Tipo Unificado):**
+
 ```typescript
 {
   name: 'id_user',
@@ -941,6 +1616,7 @@ const handleSave = (data: any) => {
 ```
 
 **📝 Mudanças:**
+
 - ❌ **REMOVIDO**: `'simple-qualiex-user-field'`, `'single-responsible-select'`
 - ✅ **NOVO**: Apenas `'user-select'` com parâmetro `mode`
 
@@ -949,12 +1625,14 @@ const handleSave = (data: any) => {
 ### **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';
@@ -962,6 +1640,7 @@ import { handleExternalLink } from 'forlogic-core';  // NOVO helper
 ```
 
 **📝 Mudanças:**
+
 - ❌ **REMOVIDO**: `createSimpleSaveHandler`
 - ❌ **REMOVIDO**: Helper interfaces de tipos
 - ✅ **NOVO**: `handleExternalLink` (helper de links externos)
@@ -971,11 +1650,12 @@ import { handleExternalLink } from 'forlogic-core';  // NOVO helper
 ### **5️⃣ Migração de Filtros Customizados**
 
 #### **❌ ANTES (Filtro Frontend):**
+
 ```typescript
 const [statusFilter, setStatusFilter] = useState('active');
 
 const filteredEntities = useMemo(() => {
-  return manager.entities.filter(e => 
+  return manager.entities.filter(e =>
     statusFilter === 'all' ? true : e.is_actived
   );
 }, [manager.entities, statusFilter]);
@@ -989,6 +1669,7 @@ const filteredManager = useMemo(() => ({
 ```
 
 #### **✅ DEPOIS (Filtro Backend - Recomendado):**
+
 ```typescript
 const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
 
@@ -1002,6 +1683,7 @@ 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)
@@ -1013,6 +1695,7 @@ const CrudPage = createCrudPage({ manager, config, onSave });
 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
@@ -1022,9 +1705,11 @@ Use este checklist para validar que seu projeto foi migrado corretamente:
 - [ ] 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()`
@@ -1033,6 +1718,7 @@ Use este checklist para validar que seu projeto foi migrado corretamente:
 - [ ] 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)
@@ -1053,14 +1739,17 @@ Use este checklist para validar que seu projeto foi migrado corretamente:
 ### **❓ 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
 
@@ -1137,15 +1826,18 @@ const config: CrudPageConfig<Process> = {
 ### **Comportamento**
 
 **Desktop (Tabela):**
+
 - Checkbox na primeira coluna (50px de largura)
 - Checkbox no header para "Selecionar Todos"
 - Click na linha NÃO abre o form quando bulk actions está ativo (evita edição acidental)
 
 **Mobile (Cards):**
+
 - Checkbox no canto superior esquerdo de cada card
 - Mesmo comportamento de seleção que desktop
 
 **Barra de Ações:**
+
 - Aparece automaticamente quando há itens selecionados
 - Mostra quantidade de itens selecionados
 - Botão "Limpar" para deselecionar todos
@@ -1231,25 +1923,25 @@ Este tutorial mostra como criar um CRUD completo usando o módulo **Examples** c
 
 ```typescript
 // ============= EXAMPLE MODULE TYPES =============
-import { 
+import {
   ContentEntity,      // title, description
   VisualEntity,       // color, icon_name
   UserRelatedEntity,  // id_user, responsible_name
   ActivableEntity,    // is_actived
   FormEntity,         // url_field, date_field
-  FilterState, 
-  EntitySortField 
+  FilterState,
+  EntitySortField
 } from 'forlogic-core';
 
 /**
  * Example - Entidade completa de exemplo
- * 
+ *
  * ✅ 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
@@ -1272,20 +1964,20 @@ export interface Example extends BaseEntity {
 
 /**
  * CreateExamplePayload - Dados para CRIAR novo registro
- * 
+ *
  * ⚠️ IMPORTANTE:
  * - Campo `alias` é injetado AUTOMATICAMENTE pelo manager.save()
  * - Campos opcionais devem ter `| null`
  * - NÃO incluir id, created_at, updated_at (gerados automaticamente)
  */
 export type CreateExamplePayload = Omit<
-  Example, 
+  Example,
   keyof BaseEntity | 'responsible_name'
 >;
 
 /**
  * UpdateExamplePayload - Dados para ATUALIZAR registro existente
- * 
+ *
  * 📝 Pattern:
  * - Todos os campos são opcionais (Partial)
  */
@@ -1293,6 +1985,7 @@ export type UpdateExamplePayload = Partial<CreateExamplePayload>;
 ```
 
 **📖 Explicação Detalhada:**
+
 - **Composição de Interfaces:** Ao invés de redefinir campos, herda de interfaces prontas da lib
 - **`alias` no CreatePayload:** RLS do Supabase precisa desse campo para funcionar
 - **`Partial<>` no UpdatePayload:** Permite updates parciais (só manda os campos que mudaram)
@@ -1310,7 +2003,7 @@ import type { Example, CreateExamplePayload, UpdateExamplePayload } from './exam
 
 /**
  * ExampleService - Service CRUD completo gerado automaticamente
- * 
+ *
  * ✅ O que é gerado:
  * - service.getAll(params)
  * - service.getById(id)
@@ -1318,13 +2011,13 @@ import type { Example, CreateExamplePayload, UpdateExamplePayload } from './exam
  * - service.update(id, data)
  * - service.delete(id)
  * - useCrudHook() - Hook React Query integrado
- * 
+ *
  * 🔧 Configuração:
  * - tableName: Nome da tabela no Supabase (schema: central)
  * - entityName: Nome legível para toasts ("Exemplo criado com sucesso")
  * - searchFields: Campos que serão pesquisados pelo filtro de busca
  * - enableQualiexEnrichment: true → adiciona responsible_name automaticamente
- * 
+ *
  * 📊 Estrutura de Tabela Esperada (Supabase):
  * CREATE TABLE central.examples (
  *   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -1342,7 +2035,7 @@ import type { Example, CreateExamplePayload, UpdateExamplePayload } from './exam
  *   date_field DATE
  * );
  */
-export const { service: ExampleService, useCrudHook: useExamplesCrud } = 
+export const { service: ExampleService, useCrudHook: useExamplesCrud } =
   createSimpleService<Example, CreateExamplePayload, UpdateExamplePayload>({
     tableName: 'examples',              // 🗃️ Tabela no Supabase
     entityName: 'Exemplo',              // 📣 Nome para mensagens
@@ -1353,6 +2046,7 @@ export const { service: ExampleService, useCrudHook: useExamplesCrud } =
 ```
 
 **📖 Explicação Detalhada:**
+
 - **Uma linha, tudo pronto:** `createSimpleService` gera todo o boilerplate
 - **Soft delete automático:** `deleteEntity()` marca `is_removed = true`, não deleta fisicamente
 - **RLS automático:** Filtra por `alias` automaticamente
@@ -1396,9 +2090,9 @@ import { useState, useMemo } from 'react';
 ```typescript
 /**
  * 📝 CONFIGURAÇÃO DO FORMULÁRIO
- * 
+ *
  * Organizado em seções (formSections) com campos (fields).
- * 
+ *
  * Tipos de campos suportados:
  * - 'text' - Input de texto simples
  * - 'email' - Input de email com validação
@@ -1489,6 +2183,7 @@ const formSections = [{
 Ver código completo no arquivo `src/examples/ExamplesPage.tsx` do projeto.
 
 **Estrutura básica:**
+
 1. Hooks no topo
 2. Estados de filtros com `useState`
 3. Estados derivados com `useMemo`
@@ -1572,6 +2267,7 @@ const filteredManager = useMemo(() => ({
 ```
 
 **📖 Explicação:**
+
 - **`useState`**: Armazena valor selecionado no filtro
 - **`useMemo` (filteredEntities)**: Evita re-filtrar a cada render
 - **`useMemo` (filteredManager)**: Evita re-criar objeto manager
@@ -1598,8 +2294,8 @@ const filteredManager = useMemo(() => ({
 }), [manager, filteredEntities]);
 
 const DepartmentFilter = () => (
-  <select 
-    value={deptFilter} 
+  <select
+    value={deptFilter}
     onChange={(e) => setDeptFilter(e.target.value)}
     className="px-3 py-2 border rounded-md"
   >
@@ -1624,7 +2320,7 @@ const [dateRange, setDateRange] = useState<{ from?: Date; to?: Date }>({});
 
 const filteredEntities = useMemo(() => {
   if (!dateRange.from && !dateRange.to) return manager.entities;
-  
+
   return manager.entities.filter(e => {
     const itemDate = parseISO(e.created_at);
     if (dateRange.from && isBefore(itemDate, dateRange.from)) return false;
@@ -1643,12 +2339,12 @@ const filteredManager = useMemo(() => ({
 
 ## 🪝 HOOKS REACT NO CRUD
 
-| Hook | Quando Usar | Exemplo no CRUD | ⚠️ Evitar |
-|------|-------------|-----------------|-----------|
-| **useMemo** | Cálculos pesados que dependem de props/state | • Configuração de colunas<br>• Filtros derivados<br>• Manager customizado | Valores simples (strings, números) |
-| **useState** | Valores que mudam via interação do usuário | • Filtros customizados<br>• Modal open/close<br>• Seleção temporária | Estados derivados de outros estados |
-| **useCallback** | Funções que são passadas como props e dependem de state | • Handlers que dependem de filtros<br>• Callbacks de child components | Handlers simples sem dependências |
-| **useEffect** | Side effects (fetch, subscriptions) | • Fetch inicial de dados (já feito pelo manager)<br>• Sincronização externa | Cálculos ou transformações de dados |
+| Hook            | Quando Usar                                             | Exemplo no CRUD                                                             | ⚠️ Evitar                           |
+| --------------- | ------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------- |
+| **useMemo**     | Cálculos pesados que dependem de props/state            | • Configuração de colunas<br>• Filtros derivados<br>• Manager customizado   | Valores simples (strings, números)  |
+| **useState**    | Valores que mudam via interação do usuário              | • Filtros customizados<br>• Modal open/close<br>• Seleção temporária        | Estados derivados de outros estados |
+| **useCallback** | Funções que são passadas como props e dependem de state | • Handlers que dependem de filtros<br>• Callbacks de child components       | Handlers simples sem dependências   |
+| **useEffect**   | Side effects (fetch, subscriptions)                     | • Fetch inicial de dados (já feito pelo manager)<br>• Sincronização externa | Cálculos ou transformações de dados |
 
 ### **📖 Exemplos Práticos**
 
@@ -1672,7 +2368,7 @@ const [statusFilter, setStatusFilter] = useState('active');
 const statusFilter = useMemo(() => 'active', []); // Não faz sentido!
 
 // ✅ CORRETO: useMemo para estado derivado
-const filteredEntities = useMemo(() => 
+const filteredEntities = useMemo(() =>
   manager.entities.filter(e => e.is_actived),
   [manager.entities]
 );
@@ -1703,15 +2399,15 @@ import { cn } from 'forlogic-core';
 ```typescript
 // ❌ SINTOMA: Formulário fecha/reabre sozinho, re-renders infinitos
 // ❌ CAUSA: Config recriado a cada render
-const config = { 
-  columns: exampleColumns, 
-  formSections 
+const config = {
+  columns: exampleColumns,
+  formSections
 };
 
 // ✅ SOLUÇÃO: Envolver em useMemo
-const config = useMemo(() => ({ 
-  columns: exampleColumns, 
-  formSections 
+const config = useMemo(() => ({
+  columns: exampleColumns,
+  formSections
 }), []);
 ```
 
@@ -1722,15 +2418,15 @@ const config = useMemo(() => ({
 ```typescript
 // ❌ SINTOMA: TypeError: manager.createEntity is not a function
 // ❌ CAUSA: Passou array direto
-const CrudPage = createCrudPage({ 
+const CrudPage = createCrudPage({
   manager: manager.entities,  // ← Errado!
-  config 
+  config
 });
 
 // ✅ SOLUÇÃO: Passar manager completo
-const CrudPage = createCrudPage({ 
+const CrudPage = createCrudPage({
   manager,  // ← Correto!
-  config 
+  config
 });
 ```
 
@@ -1744,7 +2440,7 @@ const CrudPage = createCrudPage({
 const filteredEntities = manager.entities.filter(e => e.is_actived);
 
 // ✅ SOLUÇÃO: Envolver em useMemo
-const filteredEntities = useMemo(() => 
+const filteredEntities = useMemo(() =>
   manager.entities.filter(e => e.is_actived),
   [manager.entities]
 );
@@ -1757,7 +2453,7 @@ const filteredEntities = useMemo(() =>
 ```typescript
 // ❌ SINTOMA: Erro de RLS no Supabase, registro não é criado
 // ❌ CAUSA: Usar createEntity/updateEntity direto sem alias
-manager.createEntity({ 
+manager.createEntity({
   title: data.title,
   email: data.email
   // ← Falta alias!
@@ -1820,9 +2516,9 @@ export const ExamplesPage = () => {
   key: 'website',
   header: 'Site',
   render: (item) => (
-    <a 
-      href={item.website} 
-      target="_blank" 
+    <a
+      href={item.website}
+      target="_blank"
       rel="noopener noreferrer"
       className="text-blue-600 hover:underline"
     >
@@ -1899,6 +2595,7 @@ const CrudPage = createCrudPage({
 ### 🔗 Integração Qualiex (opcional)
 
 **Auto-enrichment** (já configurado no BaseService):
+
 ```typescript
 // ✅ Automático - dados enriquecidos com nome do usuário
 const processes = await processService.getAll();
@@ -1906,17 +2603,19 @@ const processes = await processService.getAll();
 ```
 
 **Componentes prontos:**
+
 ```typescript
 import { QualiexUserField, QualiexResponsibleSelectField } from 'forlogic-core';
 
 // Select de usuários Qualiex
-<QualiexResponsibleSelectField 
+<QualiexResponsibleSelectField
   value={form.watch('id_user')}
   onChange={(userId) => form.setValue('id_user', userId)}
 />
 ```
 
 **Componentes em formulários CRUD:**
+
 ```typescript
 // Para seleção de usuário (modo unificado)
 {
@@ -1945,6 +2644,7 @@ Você pode criar e usar componentes customizados nos formulários para necessida
 > **Nota:** Componentes customizados devem ser registrados no `BaseForm.tsx` para funcionarem corretamente nos formulários CRUD.
 
 **⚠️ CRÍTICO:** Requests Qualiex exigem header `un-alias`:
+
 ```typescript
 // ✅ Já configurado no BaseService automaticamente
 headers: { 'un-alias': 'true' }
@@ -2006,7 +2706,7 @@ import { useAuth, placeService } from 'forlogic-core';
 
 function MyComponent() {
   const { alias } = useAuth();
-  
+
   const { data: places = [], isLoading, error } = useQuery({
     queryKey: ['places', alias],
     queryFn: () => placeService.getPlaces(alias),
@@ -2036,7 +2736,7 @@ import { useAuth, placeService } from 'forlogic-core';
 
 export function usePlaces() {
   const { alias } = useAuth();
-  
+
   return useQuery({
     queryKey: ['places', alias],
     queryFn: () => placeService.getPlaces(alias),
@@ -2081,7 +2781,7 @@ export function PlaceSelect({ value, onChange, disabled }: {
   disabled?: boolean;
 }) {
   const { data: places = [], isLoading } = usePlaces();
-  
+
   // Achatar hierarquia para o select
   const flatPlaces = useMemo(() => {
     const flatten = (items: Place[], level = 0): any[] => {
@@ -2092,7 +2792,7 @@ export function PlaceSelect({ value, onChange, disabled }: {
     };
     return flatten(places);
   }, [places]);
-  
+
   return (
     <EntitySelect
       value={value}
@@ -2136,7 +2836,7 @@ const { service, useCrudHook } = createSimpleService({
 // Hook para buscar nome do place
 function usePlaceName(placeId: string) {
   const { data: places = [] } = usePlaces();
-  
+
   return useMemo(() => {
     const findPlace = (items: Place[]): Place | undefined => {
       for (const place of items) {
@@ -2178,6 +2878,7 @@ const placeName = userPlace?.name;
 ```
 
 **Fluxo de dados:**
+
 1. Token JWT contém `alias` e `companyId`
 2. `placeService.getPlaces(alias)` busca os Places da API Qualiex
 3. Cada `Place` contém `usersIds` (array de IDs de usuários)
@@ -2210,13 +2911,13 @@ function PlaceTree({ places, level = 0 }: {
 
 ### 🛠️ Troubleshooting
 
-| Erro | Causa | Solução |
-|------|-------|---------|
-| `CompanyId não encontrado no token` | Token não validado corretamente | Verificar edge function `validate-token` |
-| `Alias da unidade é obrigatório` | `alias` não disponível no `useAuth()` | Aguardar carregamento do auth com `isLoading` |
-| `Token Qualiex não encontrado` | Variável de ambiente faltando | Verificar `VITE_QUALIEX_API_URL` no `.env` |
-| Places retorna array vazio `[]` | Empresa sem places cadastrados | Verificar cadastro no Qualiex admin |
-| Hierarquia quebrada | `parentId` incorreto nos dados | Verificar integridade dos dados na API Qualiex |
+| Erro                                | Causa                                 | Solução                                        |
+| ----------------------------------- | ------------------------------------- | ---------------------------------------------- |
+| `CompanyId não encontrado no token` | Token não validado corretamente       | Verificar edge function `validate-token`       |
+| `Alias da unidade é obrigatório`    | `alias` não disponível no `useAuth()` | Aguardar carregamento do auth com `isLoading`  |
+| `Token Qualiex não encontrado`      | Variável de ambiente faltando         | Verificar `VITE_QUALIEX_API_URL` no `.env`     |
+| Places retorna array vazio `[]`     | Empresa sem places cadastrados        | Verificar cadastro no Qualiex admin            |
+| Hierarquia quebrada                 | `parentId` incorreto nos dados        | Verificar integridade dos dados na API Qualiex |
 
 ### 📦 Exemplo Completo: Dashboard por Local
 
@@ -2237,7 +2938,7 @@ function PlacesDashboard() {
     <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
       {places.map(place => {
         const placeMetrics = metrics.filter(m => m.place_id === place.placeId);
-        
+
         return (
           <Card key={place.id}>
             <CardHeader>
@@ -2288,6 +2989,7 @@ function PlacesDashboard() {
 ## 🗃️ MIGRATIONS + RLS
 
 ### Template SQL Completo
+
 ```sql
 -- 1️⃣ Criar tabela
 CREATE TABLE central.processes (
@@ -2335,10 +3037,11 @@ EXECUTE FUNCTION public.set_updated_at();
 ```
 
 ### ❌ Sintaxes Proibidas RLS
+
 ```sql
 -- ❌ ERRADO - Sintaxes simplificadas que não funcionam
 id_user = auth.uid()           -- ❌ Campo errado
-id = auth.uid()                -- ❌ Campo errado  
+id = auth.uid()                -- ❌ Campo errado
 alias = auth.uid()             -- ❌ Função errada
 
 -- ✅ CORRETO - Extração completa do JWT
@@ -2356,6 +3059,7 @@ alias = auth.uid()             -- ❌ Função errada
 5. **`= alias`**: Compara com a coluna `alias` da tabela
 
 **Estrutura do JWT:**
+
 ```json
 {
   "sub": "user-uuid",
@@ -2366,11 +3070,13 @@ alias = auth.uid()             -- ❌ Função errada
 ```
 
 **Fluxo de Autenticação Multi-tenant:**
+
 ```
 Login → Validação Externa → JWT com alias → RLS Policy → Filtragem por empresa
 ```
 
 **⚠️ Erros Comuns:**
+
 - `alias = auth.uid()` → Compara alias com UUID (tipos incompatíveis)
 - `id_user = auth.uid()` → Compara com usuário, não com empresa
 - `auth.jwt().alias` → Sintaxe JavaScript, não SQL
@@ -2380,6 +3086,7 @@ Login → Validação Externa → JWT com alias → RLS Policy → Filtragem por
 ## 🐛 TROUBLESHOOTING
 
 ### 1️⃣ "relation does not exist"
+
 ```typescript
 // Causa: Schema ausente
 .from('processes') // ❌
@@ -2389,6 +3096,7 @@ Login → Validação Externa → JWT com alias → RLS Policy → Filtragem por
 ```
 
 ### 2️⃣ RLS retorna vazio
+
 ```sql
 -- Causa: Sintaxe incorreta
 USING (id_user = auth.uid())  -- ❌ ERRADO
@@ -2401,6 +3109,7 @@ USING (
 ```
 
 ### 3️⃣ Duplicação de registros
+
 ```typescript
 // Causa: ID ausente no update
 await service.save({ title: 'Novo' }); // ❌ Cria duplicado
@@ -2410,6 +3119,7 @@ await service.save({ id: item.id, title: 'Novo' }); // ✅
 ```
 
 ### 4️⃣ Página recarrega ao editar
+
 ```typescript
 // Causa: Config sem useMemo
 const config = generateCrudConfig(...); // ❌ Re-render infinito
@@ -2419,6 +3129,7 @@ const config = useMemo(() => generateCrudConfig(...), []); // ✅
 ```
 
 ### 5️⃣ Estado reseta ao navegar
+
 ```typescript
 // Causa: Outlet ausente
 <Route path="/processes" element={<ProcessesPage />} /> // ❌
@@ -2431,6 +3142,7 @@ const config = useMemo(() => generateCrudConfig(...), []); // ✅
 ```
 
 ### 6️⃣ Qualiex retorna 401
+
 ```typescript
 // Causa: Header ausente
 fetch(url); // ❌
@@ -2447,6 +3159,7 @@ fetch(url, { headers: { 'un-alias': 'true' } }); // ✅
 ### **Por que Filtros no Backend?**
 
 Filtrar dados no **backend** é a abordagem recomendada porque:
+
 - ✅ **Paginação correta**: Total de itens reflete os dados filtrados
 - ✅ **Performance**: Menos dados trafegados pela rede
 - ✅ **Escalabilidade**: Funciona com milhares de registros
@@ -2463,9 +3176,9 @@ Para filtros simples e estáticos, use `additionalFilters` no service:
 import { createSimpleService } from 'forlogic-core';
 import { Subprocess, SubprocessInsert, SubprocessUpdate } from './types';
 
-export const { 
-  service: subprocessService, 
-  useCrudHook: baseUseCrudHook 
+export const {
+  service: subprocessService,
+  useCrudHook: baseUseCrudHook
 } = createSimpleService<Subprocess, SubprocessInsert, SubprocessUpdate>({
   tableName: 'subprocesses',
   entityName: 'subprocesso',
@@ -2489,9 +3202,9 @@ import { useMemo } from 'react';
 import { createSimpleService } from 'forlogic-core';
 
 // Service base
-export const { 
-  service: subprocessService, 
-  useCrudHook: baseUseCrudHook 
+export const {
+  service: subprocessService,
+  useCrudHook: baseUseCrudHook
 } = createSimpleService<Subprocess, SubprocessInsert, SubprocessUpdate>({
   tableName: 'subprocesses',
   entityName: 'subprocesso',
@@ -2507,7 +3220,7 @@ export function useSubprocessesCrud(filters?: {
   // Transforma filtros em additionalFilters
   const additionalFilters = useMemo(() => {
     const filterList: any[] = [];
-    
+
     // Filtro de status (ativo/inativo)
     if (filters?.is_actived !== undefined) {
       filterList.push({
@@ -2516,7 +3229,7 @@ export function useSubprocessesCrud(filters?: {
         value: filters.is_actived
       });
     }
-    
+
     // Filtro de processo (incluindo "sem processo")
     if (filters?.id_process) {
       if (filters.id_process === 'none') {
@@ -2533,10 +3246,10 @@ export function useSubprocessesCrud(filters?: {
         });
       }
     }
-    
+
     return filterList;
   }, [filters?.is_actived, filters?.id_process]);
-  
+
   // Chama hook base com filtros dinâmicos
   return baseUseCrudHook({ additionalFilters });
 }
@@ -2551,16 +3264,16 @@ import { useSubprocessesCrud } from './SubprocessService';
 
 export default function SubprocessesPage() {
   const [searchParams, setSearchParams] = useSearchParams();
-  
+
   // Ler filtros da URL
   const filters = useMemo(() => ({
     is_actived: searchParams.get('is_actived') === 'true',
     id_process: searchParams.get('id_process') || undefined
   }), [searchParams]);
-  
+
   // Manager com filtros aplicados no backend
   const manager = useSubprocessesCrud(filters);
-  
+
   // Config com filtros de UI
   const config = useMemo(() => generateCrudConfig<Subprocess>({
     entityName: 'Subprocesso',
@@ -2599,7 +3312,7 @@ export default function SubprocessesPage() {
     ],
     columns: [...]
   }), [searchParams]);
-  
+
   return <CrudPage />;
 }
 ```
@@ -2608,17 +3321,17 @@ export default function SubprocessesPage() {
 
 O `BaseService` suporta os seguintes operadores em `additionalFilters`:
 
-| Operador | Descrição | Exemplo |
-|----------|-----------|---------|
-| `eq` | Igual a | `{ field: 'status', operator: 'eq', value: 'active' }` |
-| `neq` | Diferente de | `{ field: 'status', operator: 'neq', value: 'archived' }` |
-| `gt` | Maior que | `{ field: 'price', operator: 'gt', value: 100 }` |
-| `gte` | Maior ou igual | `{ field: 'price', operator: 'gte', value: 100 }` |
-| `lt` | Menor que | `{ field: 'stock', operator: 'lt', value: 10 }` |
-| `lte` | Menor ou igual | `{ field: 'stock', operator: 'lte', value: 10 }` |
-| `in` | Em lista | `{ field: 'category', operator: 'in', value: ['A', 'B'] }` |
-| `contains` | Contém texto | `{ field: 'name', operator: 'contains', value: 'test' }` |
-| `is_null` | É nulo | `{ field: 'deleted_at', operator: 'is_null' }` |
+| Operador   | Descrição      | Exemplo                                                    |
+| ---------- | -------------- | ---------------------------------------------------------- |
+| `eq`       | Igual a        | `{ field: 'status', operator: 'eq', value: 'active' }`     |
+| `neq`      | Diferente de   | `{ field: 'status', operator: 'neq', value: 'archived' }`  |
+| `gt`       | Maior que      | `{ field: 'price', operator: 'gt', value: 100 }`           |
+| `gte`      | Maior ou igual | `{ field: 'price', operator: 'gte', value: 100 }`          |
+| `lt`       | Menor que      | `{ field: 'stock', operator: 'lt', value: 10 }`            |
+| `lte`      | Menor ou igual | `{ field: 'stock', operator: 'lte', value: 10 }`           |
+| `in`       | Em lista       | `{ field: 'category', operator: 'in', value: ['A', 'B'] }` |
+| `contains` | Contém texto   | `{ field: 'name', operator: 'contains', value: 'test' }`   |
+| `is_null`  | É nulo         | `{ field: 'deleted_at', operator: 'is_null' }`             |
 
 ### **Exemplo Completo: Filtro de Status e Processo**
 
@@ -2630,7 +3343,7 @@ export function useSubprocessesCrud(filters?: {
 }) {
   const additionalFilters = useMemo(() => {
     const filterList: any[] = [];
-    
+
     if (filters?.is_actived !== undefined) {
       filterList.push({
         field: 'is_actived',
@@ -2638,7 +3351,7 @@ export function useSubprocessesCrud(filters?: {
         value: filters.is_actived
       });
     }
-    
+
     if (filters?.id_process) {
       if (filters.id_process === 'none') {
         filterList.push({
@@ -2653,10 +3366,10 @@ export function useSubprocessesCrud(filters?: {
         });
       }
     }
-    
+
     return filterList;
   }, [filters?.is_actived, filters?.id_process]);
-  
+
   return baseUseCrudHook({ additionalFilters });
 }
 
@@ -2675,10 +3388,11 @@ const manager = useSubprocessesCrud(filters);
 ### **⚠️ Filtros Frontend vs Backend**
 
 **❌ Filtros no Frontend (EVITAR):**
+
 ```typescript
 // Problema: Paginação incorreta
-const filteredEntities = useMemo(() => 
-  manager.entities.filter(e => e.is_actived), 
+const filteredEntities = useMemo(() =>
+  manager.entities.filter(e => e.is_actived),
   [manager.entities]
 );
 
@@ -2688,10 +3402,11 @@ const filteredEntities = useMemo(() =>
 ```
 
 **✅ Filtros no Backend (CORRETO):**
+
 ```typescript
 // Backend retorna apenas dados filtrados
-const manager = useSubprocessesCrud({ 
-  is_actived: true 
+const manager = useSubprocessesCrud({
+  is_actived: true
 });
 
 // manager.totalCount = 43 (correto!)
@@ -2706,7 +3421,9 @@ const manager = useSubprocessesCrud({
 O `forlogic-core` oferece três formas de definir larguras de colunas nas tabelas CRUD:
 
 ### **1️⃣ Via `className` (Recomendado)**
+
 Use classes do Tailwind para larguras fixas ou responsivas:
+
 ```typescript
 const columns = [
   {
@@ -2723,7 +3440,9 @@ const columns = [
 ```
 
 ### **2️⃣ Via `width` (Fixo em pixels)**
+
 Especifique largura fixa diretamente:
+
 ```typescript
 {
   key: 'order',
@@ -2734,7 +3453,9 @@ Especifique largura fixa diretamente:
 ```
 
 ### **3️⃣ Via `minWidth` + `weight` (Flexível)**
+
 Para colunas que crescem proporcionalmente:
+
 ```typescript
 {
   key: 'description',
@@ -2745,11 +3466,13 @@ Para colunas que crescem proporcionalmente:
 ```
 
 ### **⚠️ Importante**
+
 - A tabela usa `table-auto` para respeitar essas configurações
 - Para truncar textos longos, use: `className: "max-w-[200px] truncate"`
 - Combine `whitespace-nowrap` com largura fixa para evitar quebras
 
 ### **📋 Exemplo Completo**
+
 ```typescript
 const columns: CrudColumn<MyEntity>[] = [
   {
@@ -2788,13 +3511,14 @@ const columns: CrudColumn<MyEntity>[] = [
 ## 📚 REFERÊNCIA RÁPIDA
 
 ### Imports Essenciais
+
 ```typescript
 // CRUD
-import { 
-  createSimpleService, 
-  createCrudPage, 
+import {
+  createSimpleService,
+  createCrudPage,
   generateCrudConfig,
-  createSimpleSaveHandler 
+  createSimpleSaveHandler
 } from 'forlogic-core';
 
 // UI
@@ -2808,6 +3532,7 @@ import { QualiexUserField, useQualiexUsers } from 'forlogic-core';
 ```
 
 ### Estrutura de Arquivos
+
 ```
 src/
 ├── processes/
@@ -2820,4 +3545,4 @@ src/
 
 ## 📝 Licença
 
-MIT License - ForLogic © 2025
+MIT License - ForLogic © 2025