forlogic-core 1.7.5 → 1.7.7

package/dist/README.md

@@ -208,7 +208,7 @@ import { Button } from 'forlogic-core'
 // Formulários
 Button, Input, Textarea, Label, Select, SelectContent,
 SelectItem, SelectTrigger, SelectValue, Checkbox, RadioGroup,
-RadioGroupItem, Switch
+RadioGroupItem, Switch, CreatableCombobox
 
 // Layout
 Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle
@@ -598,6 +598,349 @@ const formFields: FormField[] = [
   type: 'custom',
   component: RichTextEditor,
   componentProps: {
+    toolbar: ['bold', 'italic', 'link']
+  }
+}
+```
+
+---
+
+### 🎯 Campo Creatable Select
+
+O `CreatableCombobox` permite que usuários **selecionem de opções existentes OU criem novos itens inline** sem sair do formulário.
+
+#### Quando Usar?
+
+- ✅ Seleção de tags, categorias, labels
+- ✅ Campos onde usuários podem precisar criar valores rapidamente
+- ✅ Dropdowns com centenas de opções (busca rápida)
+- ✅ Single ou múltipla seleção
+
+#### Uso Básico no BaseForm
+
+```typescript
+import { createCrudPage } from 'forlogic-core';
+import { TagService } from './tagService';
+
+const formFields: FormSection[] = [
+  {
+    id: 'basic',
+    title: 'Informações',
+    fields: [
+      {
+        name: 'tags',
+        label: 'Tags',
+        type: 'creatable-select',
+        mode: 'multiple',
+        placeholder: 'Selecionar ou criar tags...',
+        options: tagsOptions, // [{ label: 'React', value: '1' }, ...]
+        onCreate: async (tagName) => {
+          // Criar tag no backend
+          const newTag = await TagService.create({ name: tagName });
+          // Atualizar lista de opções (refetch)
+          refetchTags();
+          return newTag.id; // Retorna ID para seleção automática
+        },
+        createLabel: (term) => `Criar "${term}"`,
+        required: true
+      },
+      {
+        name: 'category',
+        label: 'Categoria',
+        type: 'creatable-select',
+        mode: 'single',
+        placeholder: 'Selecionar categoria...',
+        options: categoriesOptions,
+        onCreate: async (categoryName) => {
+          const newCat = await CategoryService.create({ name: categoryName });
+          refetchCategories();
+          return newCat.id;
+        }
+      }
+    ]
+  }
+];
+```
+
+#### Props do Campo
+
+| Prop                  | Tipo                                       | Padrão                  | Descrição                                            |
+| --------------------- | ------------------------------------------ | ----------------------- | ---------------------------------------------------- |
+| `type`                | `'creatable-select'`                       | -                       | Tipo do campo (obrigatório)                          |
+| `mode`                | `'single' \| 'multiple'`                   | `'single'`              | Seleção única ou múltipla                            |
+| `options`             | `Array<{ label: string; value: string }>`  | `[]`                    | Opções existentes para seleção                       |
+| `onCreate`            | `(searchTerm: string) => Promise<string>`  | -                       | Callback para criar novo item (retorna ID)           |
+| `placeholder`         | `string`                                   | `'Selecionar...'`       | Texto quando nenhum item selecionado                 |
+| `searchPlaceholder`   | `string`                                   | `'Buscar...'`           | Texto da busca interna                               |
+| `createLabel`         | `(term: string) => string`                 | `'Criar "{term}"'`      | Função para gerar label do botão criar               |
+| `emptyMessage`        | `string`                                   | `'Nenhum item encontrado.'` | Mensagem quando não há opções                    |
+
+#### Exemplo Completo com React Query
+
+```typescript
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { createCrudPage } from 'forlogic-core';
+import { TagService } from './tagService';
+
+function TagsPage() {
+  const queryClient = useQueryClient();
+  
+  // Buscar tags existentes
+  const { data: tags = [], isLoading } = useQuery({
+    queryKey: ['tags'],
+    queryFn: () => TagService.getAll()
+  });
+
+  // Converter para formato do CreatableCombobox
+  const tagsOptions = tags.map(tag => ({
+    label: tag.name,
+    value: tag.id
+  }));
+
+  const formFields: FormSection[] = [
+    {
+      id: 'article',
+      title: 'Artigo',
+      fields: [
+        {
+          name: 'title',
+          label: 'Título',
+          type: 'text',
+          required: true
+        },
+        {
+          name: 'tags',
+          label: 'Tags',
+          type: 'creatable-select',
+          mode: 'multiple',
+          options: tagsOptions,
+          onCreate: async (tagName) => {
+            // Validar nome
+            if (tagName.trim().length < 2) {
+              throw new Error('Nome deve ter ao menos 2 caracteres');
+            }
+            
+            // Criar no backend
+            const newTag = await TagService.create({ 
+              name: tagName.trim() 
+            });
+            
+            // Invalidar cache para refetch automático
+            queryClient.invalidateQueries({ queryKey: ['tags'] });
+            
+            // Retornar ID para seleção automática
+            return newTag.id;
+          },
+          placeholder: 'Selecionar tags...',
+          searchPlaceholder: 'Buscar ou criar tag...',
+          createLabel: (term) => `✨ Criar tag "${term}"`,
+          required: true
+        }
+      ]
+    }
+  ];
+
+  return createCrudPage({
+    // ... config do CRUD
+    formFields
+  });
+}
+```
+
+#### Uso Standalone (Fora do BaseForm)
+
+```typescript
+import { CreatableCombobox } from 'forlogic-core/ui';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [selectedTags, setSelectedTags] = useState<string[]>([]);
+  
+  const tagsOptions = [
+    { label: 'React', value: '1' },
+    { label: 'TypeScript', value: '2' },
+    { label: 'Node.js', value: '3' }
+  ];
+
+  return (
+    <CreatableCombobox
+      mode="multiple"
+      value={selectedTags}
+      onChange={setSelectedTags}
+      options={tagsOptions}
+      onCreate={async (tagName) => {
+        const response = await fetch('/api/tags', {
+          method: 'POST',
+          body: JSON.stringify({ name: tagName })
+        });
+        const newTag = await response.json();
+        return newTag.id;
+      }}
+      placeholder="Selecionar tags..."
+      createLabel={(term) => `Criar "${term}"`}
+    />
+  );
+}
+```
+
+#### Interface TypeScript
+
+```typescript
+interface CreatableComboboxProps {
+  // Dados
+  options: Array<{ label: string; value: string }>;
+  value?: string | string[];
+  
+  // Eventos
+  onChange: (value: string | string[]) => void;
+  onCreate?: (searchTerm: string) => Promise<string | void>;
+  
+  // Config
+  placeholder?: string;
+  searchPlaceholder?: string;
+  createLabel?: (term: string) => string;
+  emptyMessage?: string;
+  
+  // Estado
+  disabled?: boolean;
+  error?: string;
+  isLoading?: boolean;
+  
+  // UI
+  className?: string;
+  mode?: 'single' | 'multiple';
+}
+```
+
+#### Fluxo de Criação
+
+```mermaid
+graph TD
+    A[Usuário digita 'Design'] --> B{Termo existe?}
+    B -->|Sim| C[Mostra opção existente]
+    B -->|Não| D[Mostra botão 'Criar Design']
+    D --> E[Usuário clica em criar]
+    E --> F[onCreate chamado]
+    F --> G{Retornou ID?}
+    G -->|Sim| H[Adiciona à seleção automaticamente]
+    G -->|Não| I[Apenas fecha dropdown]
+    H --> J[queryClient.invalidateQueries atualiza lista]
+    C --> K[Usuário seleciona]
+    K --> L[onChange chamado]
+```
+
+#### Estados Visuais
+
+**Campo Vazio (Single):**
+```
+┌────────────────────────────────┐
+│  Selecionar categoria...    ▼ │
+└────────────────────────────────┘
+```
+
+**Campo com Múltiplos Selecionados:**
+```
+┌────────────────────────────────┐
+│  [React ✕] [TypeScript ✕]  ▼  │
+└────────────────────────────────┘
+```
+
+**Dropdown com Busca (Termo Não Existe):**
+```
+┌────────────────────────────────┐
+│  🔍 design                     │
+├────────────────────────────────┤
+│  ┏━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
+│  ┃  ✨ Criar "design"        ┃ │ <- Botão azul
+│  ┗━━━━━━━━━━━━━━━━━━━━━━━━━┛ │
+└────────────────────────────────┘
+```
+
+**Dropdown com Opções Existentes:**
+```
+┌────────────────────────────────┐
+│  🔍 react                      │
+├────────────────────────────────┤
+│  ✓ React                       │ <- Selecionado
+│    React Native                │
+│    React Query                 │
+└────────────────────────────────┘
+```
+
+#### Boas Práticas
+
+1. **Sempre retornar o ID no onCreate:**
+   - Permite seleção automática do item criado
+   - Evita usuário ter que procurar o item recém-criado
+
+2. **Invalidar cache após criar:**
+   - Use `queryClient.invalidateQueries()` para refetch automático
+   - Garante que lista de opções está sempre atualizada
+
+3. **Validação no onCreate:**
+   - Valide o nome antes de criar
+   - Lance erro amigável se inválido
+   - Use `toast.error()` para feedback visual
+
+4. **Loading states:**
+   - Passe `isLoading` durante fetch inicial de opções
+   - `onCreate` já mostra loading interno automaticamente
+
+5. **Modo apropriado:**
+   - `single`: Categoria, Status, Tipo
+   - `multiple`: Tags, Skills, Departamentos
+
+#### Troubleshooting
+
+**Problema:** Opções não atualizam após criar
+```typescript
+// ❌ ERRADO - Não invalida cache
+onCreate: async (name) => {
+  await TagService.create({ name });
+  return newTag.id;
+}
+
+// ✅ CORRETO - Invalida cache
+onCreate: async (name) => {
+  const newTag = await TagService.create({ name });
+  queryClient.invalidateQueries({ queryKey: ['tags'] });
+  return newTag.id;
+}
+```
+
+**Problema:** Dropdown fica transparente
+```css
+/* Adicionar ao CSS global se necessário */
+.popover-content {
+  background-color: white;
+  z-index: 9999;
+}
+```
+
+**Problema:** onCreate não retorna ID
+```typescript
+// ✅ Sempre retornar o ID para seleção automática
+onCreate: async (name) => {
+  const response = await TagService.create({ name });
+  return response.id; // <- IMPORTANTE
+}
+```
+
+---
+
+#### Integração com FormField Types
+
+O tipo `'creatable-select'` está disponível para uso direto no `FormField`:
+
+```typescript
+type FormFieldType = 
+  | 'text' 
+  | 'textarea' 
+  | 'select' 
+  | 'creatable-select'  // <- Novo tipo
+  | 'checkbox' 
+  | 'radio' 
+  | 'date'
     toolbar: ['bold', 'italic', 'link'],
     minHeight: 200
   }
@@ -1052,9 +1395,13 @@ userFieldsMapping: [
 
 ### 🏢 Sistema de Gestores de Locais (Qualiex)
 
-Componentes para gerenciamento de gestores e membros de locais/sublocais integrados com a API Qualiex.
+Componentes reutilizáveis para gerenciamento de gestores e membros de locais/sublocais integrados com a API Qualiex.
 
-#### Importação
+> **⚠️ IMPORTANTE:** Esta funcionalidade requer configuração de tabela no banco de dados do projeto consumidor. A biblioteca fornece os componentes, mas **você deve criar e configurar a tabela e o serviço** no seu projeto.
+
+---
+
+#### 📦 Importação
 
 ```typescript
 import {
@@ -1063,110 +1410,432 @@ import {
   ManagerSelectionDialog,
   usePlaceManagers,
   PlaceManagerService,
+  type PlaceManagerServiceConfig,
   type PlaceManager
 } from 'forlogic-core';
 ```
 
-#### Componentes
+---
+
+#### 🔧 Configuração Inicial (OBRIGATÓRIO)
+
+##### **Passo 1: Criar a Tabela no Supabase**
+
+A biblioteca espera uma tabela com a seguinte estrutura:
+
+```sql
+CREATE TABLE IF NOT EXISTS public.place_managers (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  alias text NOT NULL,
+  place_id text NOT NULL,
+  user_id text NOT NULL,
+  user_name text NOT NULL,
+  user_email text NOT NULL,
+  role text NOT NULL CHECK (role IN ('manager', 'member')),
+  created_at timestamptz DEFAULT now(),
+  updated_at timestamptz DEFAULT now(),
+  
+  -- Constraint: Um usuário não pode ter múltiplas funções no mesmo local
+  UNIQUE (alias, place_id, user_id)
+);
+
+-- Índices para performance
+CREATE INDEX idx_place_managers_alias_place ON public.place_managers(alias, place_id);
+CREATE INDEX idx_place_managers_user ON public.place_managers(user_id);
+
+-- RLS Policies (exemplo - ajustar conforme necessidade)
+ALTER TABLE public.place_managers ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users view own alias managers"
+  ON public.place_managers FOR SELECT
+  USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
+
+CREATE POLICY "Users manage own alias managers"
+  ON public.place_managers FOR ALL
+  USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
+```
+
+> 💡 **Dica:** Você pode usar um nome de tabela e schema diferentes, basta configurar no próximo passo.
+
+---
+
+##### **Passo 2: Criar o Serviço no Seu Projeto**
+
+Crie um arquivo de serviço customizado no seu projeto:
+
+```typescript
+// src/services/placeManagerService.ts
+import { PlaceManagerService } from 'forlogic-core';
+
+export const placeManagerService = new PlaceManagerService({
+  tableName: 'place_managers',  // 🔧 Nome da sua tabela
+  schemaName: 'public'          // 🔧 Nome do schema
+});
+```
+
+**Configurações disponíveis:**
+
+| Propriedade  | Tipo     | Padrão             | Descrição                      |
+| ------------ | -------- | ------------------ | ------------------------------ |
+| `tableName`  | `string` | `'place_managers'` | Nome da tabela no Supabase     |
+| `schemaName` | `string` | `'public'`         | Nome do schema (geralmente 'public') |
+
+---
 
-**PlaceManagerButton** - Botão dropdown com ações de gerenciamento:
+#### 🎨 Componentes
+
+##### **PlaceManagerButton**
+
+Botão dropdown com ações de gerenciamento (trocar gestor, remover gestor).
 
 ```tsx
+import { PlaceManagerButton } from 'forlogic-core';
+import { placeManagerService } from '@/services/placeManagerService';
+
 <PlaceManagerButton
   placeId="abc-123"
   placeName="Matriz São Paulo"
-  serviceConfig={{ tableName: 'place_managers' }}
+  service={placeManagerService}  // ⚠️ OBRIGATÓRIO
 />
 ```
 
-**PlaceManagerBadge** - Badge visual com contador de gestores:
+**Props:**
+
+| Prop        | Tipo                   | Obrigatório | Descrição                        |
+| ----------- | ---------------------- | ----------- | -------------------------------- |
+| `placeId`   | `string`               | ✅          | ID do local                      |
+| `placeName` | `string`               | ✅          | Nome do local (para exibição)    |
+| `service`   | `PlaceManagerService`  | ✅          | Instância do serviço configurado |
+
+---
+
+##### **PlaceManagerBadge**
+
+Badge visual que mostra "Gestor" ou "Gestores" com contador de usuários.
 
 ```tsx
+import { PlaceManagerBadge } from 'forlogic-core';
+import { placeManagerService } from '@/services/placeManagerService';
+
 <PlaceManagerBadge
   placeId="abc-123"
   userCount={15}
+  service={placeManagerService}  // ⚠️ OBRIGATÓRIO
 />
 ```
 
-**ManagerSelectionDialog** - Diálogo completo de seleção:
+**Props:**
+
+| Prop        | Tipo                  | Obrigatório | Descrição                        |
+| ----------- | --------------------- | ----------- | -------------------------------- |
+| `placeId`   | `string`              | ✅          | ID do local                      |
+| `userCount` | `number`              | ✅          | Total de usuários do local       |
+| `service`   | `PlaceManagerService` | ✅          | Instância do serviço configurado |
+
+**Estados visuais:**
+
+- **"Gestor"** - Quando há 1 gestor definido
+- **"Gestores"** - Quando não há gestor definido (apenas membros)
+
+---
+
+##### **ManagerSelectionDialog**
+
+Diálogo completo para seleção de gestores e membros com busca integrada.
 
 ```tsx
+import { ManagerSelectionDialog } from 'forlogic-core';
+
 <ManagerSelectionDialog
   open={showDialog}
   onOpenChange={setShowDialog}
-  onSelectManager={(user) => console.log('Gestor:', user)}
-  onSelectMember={(user) => console.log('Membro:', user)}
+  onSelectManager={(user) => handleSelectManager(user)}
+  onSelectMember={(user) => handleAddMember(user)}
   currentManagerId={manager?.user_id}
   currentMemberIds={members.map(m => m.user_id)}
   placeName="Matriz São Paulo"
+  isLoading={false}
 />
 ```
 
-#### Hook: usePlaceManagers
+**Props:**
+
+| Prop               | Tipo                          | Obrigatório | Descrição                             |
+| ------------------ | ----------------------------- | ----------- | ------------------------------------- |
+| `open`             | `boolean`                     | ✅          | Controla visibilidade                 |
+| `onOpenChange`     | `(open: boolean) => void`     | ✅          | Callback de mudança de estado         |
+| `onSelectManager`  | `(user: QualiexUser) => void` | ✅          | Callback ao selecionar gestor         |
+| `onSelectMember`   | `(user: QualiexUser) => void` | ✅          | Callback ao adicionar membro          |
+| `currentManagerId` | `string`                      | ❌          | ID do gestor atual                    |
+| `currentMemberIds` | `string[]`                    | ❌          | IDs dos membros atuais                |
+| `placeName`        | `string`                      | ✅          | Nome do local (para exibição)         |
+| `isLoading`        | `boolean`                     | ❌          | Estado de loading externo (opcional)  |
+
+---
+
+#### 🔧 Hook: usePlaceManagers
+
+Hook React Query para gerenciar gestores e membros de um local.
 
 ```typescript
+import { usePlaceManagers } from 'forlogic-core';
+import { placeManagerService } from '@/services/placeManagerService';
+
 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);
-```
+  managers,          // PlaceManager[] - Todos (gestor + membros)
+  manager,           // PlaceManager | undefined - Apenas o gestor
+  members,           // PlaceManager[] - Apenas membros
+  isLoading,         // boolean - Carregando dados iniciais
+  setManager,        // (user: QualiexUser) => void
+  addMember,         // (user: QualiexUser) => void
+  remove,            // (userId: string) => void
+  isSettingManager,  // boolean - Carregando mutação de gestor
+  isAddingMember,    // boolean - Carregando mutação de membro
+  isRemoving         // boolean - Carregando mutação de remoção
+} = usePlaceManagers(placeId, placeManagerService);
+```
+
+**Parâmetros:**
+
+| Parâmetro | Tipo                  | Obrigatório | Descrição                                  |
+| --------- | --------------------- | ----------- | ------------------------------------------ |
+| `placeId` | `string`              | ✅          | ID do local                                |
+| `service` | `PlaceManagerService` | ✅          | Instância do serviço configurado           |
+| `enabled` | `boolean`             | ❌          | Habilitar/desabilitar query (default: `true`) |
+
+**Retorno:**
+
+| Propriedade        | Tipo                          | Descrição                                      |
+| ------------------ | ----------------------------- | ---------------------------------------------- |
+| `managers`         | `PlaceManager[]`              | Todos os usuários (gestor + membros)           |
+| `manager`          | `PlaceManager \| undefined`   | Apenas o gestor (se existir)                   |
+| `members`          | `PlaceManager[]`              | Apenas membros (sem o gestor)                  |
+| `isLoading`        | `boolean`                     | Carregando dados iniciais                      |
+| `setManager`       | `(user: QualiexUser) => void` | Define novo gestor (remove anterior)           |
+| `addMember`        | `(user: QualiexUser) => void` | Adiciona membro ao local                       |
+| `remove`           | `(userId: string) => void`    | Remove usuário (gestor ou membro)              |
+| `isSettingManager` | `boolean`                     | Estado da mutação de definir gestor            |
+| `isAddingMember`   | `boolean`                     | Estado da mutação de adicionar membro          |
+| `isRemoving`       | `boolean`                     | Estado da mutação de remover                   |
+
+---
+
+#### 🔧 Service: PlaceManagerService
 
-#### Service: PlaceManagerService
+Classe para operações de banco de dados relacionadas a gestores de locais.
+
+##### **Instanciação Customizada**
 
 ```typescript
 import { PlaceManagerService } from 'forlogic-core';
 
-// Instância customizada
-const service = new PlaceManagerService({
-  tableName: 'my_place_managers',
-  schemaName: 'custom_schema'
+// Configuração padrão (tabela 'place_managers' no schema 'public')
+const defaultService = new PlaceManagerService();
+
+// Configuração customizada
+const customService = new PlaceManagerService({
+  tableName: 'gestores_locais',
+  schemaName: 'gestao'
 });
+```
+
+##### **Métodos Disponíveis**
+
+```typescript
+// Buscar gestores e membros de um local
+const managers = await placeManagerService.getPlaceManagers(
+  alias: string,
+  placeId: string
+);
+// Retorna: PlaceManager[]
+
+// Definir gestor (remove anterior automaticamente)
+await placeManagerService.setManager(
+  alias: string,
+  placeId: string,
+  user: QualiexUser
+);
+// Retorna: void
+
+// Adicionar membro
+await placeManagerService.addMember(
+  alias: string,
+  placeId: string,
+  user: QualiexUser
+);
+// Retorna: void
 
-// 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);
+// Remover usuário (gestor ou membro)
+await placeManagerService.removePlaceUser(
+  alias: string,
+  placeId: string,
+  userId: string
+);
+// Retorna: void
 ```
 
-> ⚠️ A configuração do banco de dados (tabelas, RLS policies) deve ser feita no projeto consumidor.
+---
+
+#### 📘 Tipos
+
+```typescript
+interface PlaceManager {
+  id: string;
+  alias: string;
+  place_id: string;
+  user_id: string;
+  user_name: string;
+  user_email: string;
+  role: 'manager' | 'member';
+  created_at: string;
+  updated_at: string;
+}
+
+interface PlaceManagerServiceConfig {
+  tableName?: string;   // Default: 'place_managers'
+  schemaName?: string;  // Default: 'public'
+}
+```
 
-#### 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
+#### 🎯 Regras de Negócio
 
-#### Exemplo Completo
+1. ✅ **Um gestor por local**: Ao definir novo gestor, o anterior é removido automaticamente
+2. ✅ **Membros ilimitados**: Múltiplos membros podem ser adicionados ao mesmo local
+3. ✅ **Ordenação alfabética**: Usuários sempre ordenados por nome
+4. ✅ **Busca inteligente**: Filtra por nome ou email do usuário
+5. ✅ **Integração Qualiex**: Utiliza `useQualiexUsers` para listar usuários
+
+---
+
+#### 💡 Exemplo Completo
 
 ```tsx
+// 1. Criar serviço (src/services/placeManagerService.ts)
+import { PlaceManagerService } from 'forlogic-core';
+
+export const placeManagerService = new PlaceManagerService({
+  tableName: 'place_managers',
+  schemaName: 'public'
+});
+
+// 2. Usar nos componentes (src/places/PlaceTreeItem.tsx)
+import { PlaceManagerButton, PlaceManagerBadge } from 'forlogic-core';
+import { placeManagerService } from '@/services/placeManagerService';
+
 function PlaceTreeItem({ place }) {
   return (
     <div className="flex items-center gap-3">
       <span>{place.name}</span>
-
-      <PlaceManagerBadge
-        placeId={place.id}
+      
+      {/* Badge com contador */}
+      <PlaceManagerBadge 
+        placeId={place.id} 
         userCount={place.usersIds.length}
+        service={placeManagerService}
       />
-
-      <PlaceManagerButton
+      
+      {/* Botão de ações */}
+      <PlaceManagerButton 
         placeId={place.id}
         placeName={place.name}
+        service={placeManagerService}
       />
     </div>
   );
 }
+
+// 3. Uso avançado com hook (src/places/PlaceDetailsPage.tsx)
+import { usePlaceManagers } from 'forlogic-core';
+import { placeManagerService } from '@/services/placeManagerService';
+
+function PlaceDetailsPage({ placeId }) {
+  const {
+    manager,
+    members,
+    setManager,
+    addMember,
+    remove,
+    isLoading
+  } = usePlaceManagers(placeId, placeManagerService);
+
+  if (isLoading) return <LoadingState />;
+
+  return (
+    <div>
+      <h2>Gestor Atual</h2>
+      {manager ? (
+        <div>
+          <p>{manager.user_name}</p>
+          <Button onClick={() => remove(manager.user_id)}>
+            Remover Gestor
+          </Button>
+        </div>
+      ) : (
+        <p>Nenhum gestor definido</p>
+      )}
+
+      <h2>Membros ({members.length})</h2>
+      <ul>
+        {members.map(member => (
+          <li key={member.id}>
+            {member.user_name}
+            <Button onClick={() => remove(member.user_id)}>
+              Remover
+            </Button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
 ```
 
 ---
 
+#### 🔒 Segurança e RLS
+
+**Recomendações de RLS Policies:**
+
+```sql
+-- Permitir leitura para usuários do mesmo alias
+CREATE POLICY "Users view own alias managers"
+  ON public.place_managers FOR SELECT
+  USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
+
+-- Permitir gestão completa para usuários do mesmo alias
+CREATE POLICY "Users manage own alias managers"
+  ON public.place_managers FOR ALL
+  USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
+```
+
+> ⚠️ **Importante:** Ajuste as policies conforme as regras de negócio do seu projeto.
+
+---
+
+#### ❓ Troubleshooting
+
+**Erro: "relation 'place_managers' does not exist"**
+- ✅ Verifique se a tabela foi criada no Supabase
+- ✅ Confirme o nome correto da tabela e schema no `PlaceManagerService`
+
+**Erro: "No rows returned"**
+- ✅ Verifique as RLS policies da tabela
+- ✅ Confirme que o usuário tem permissão para ler a tabela
+- ✅ Verifique se o `alias` está correto
+
+**Componente não atualiza após adicionar/remover**
+- ✅ O hook usa React Query com invalidação automática de cache
+- ✅ Verifique se está usando a mesma instância do `service` em todos os componentes
+
+**Dropdown não abre ou está vazio**
+- ✅ Verifique se a integração com Qualiex está configurada
+- ✅ Confirme que `useQualiexUsers` está retornando usuários
+- ✅ Verifique console do navegador para erros de API
+
+---
+
 ### ✅ CHECKLIST (antes de implementar)
 
 - [ ] Schema `schema` especificado em queries e service?
@@ -1766,6 +2435,327 @@ customActions: [
 
 ---
 
+### **🔍 TUTORIAL COMPLETO: FILTROS E EXPORTAÇÃO**
+
+Este tutorial mostra como implementar filtros customizados e botão de exportação em páginas CRUD.
+
+---
+
+#### **📋 Cenário: Página de Exemplos com Filtro de Status e Exportação**
+
+Vamos criar uma página que:
+1. ✅ Filtra exemplos por status (Ativo/Inativo/Todos)
+2. ✅ Exporta todos os dados para CSV (não apenas da página atual)
+3. ✅ Mantém filtros aplicados ao exportar
+
+---
+
+#### **Passo 1: Configurar o Service**
+
+```typescript
+// src/examples/ExampleService.ts
+import { createSimpleService } from 'forlogic-core';
+import type { Example, CreateExamplePayload, UpdateExamplePayload } from './example';
+
+export const { service: ExampleService, useCrudHook: useExamplesCrud } = 
+  createSimpleService<Example, CreateExamplePayload, UpdateExamplePayload>({
+    tableName: 'examples',
+    entityName: 'Exemplo',
+    searchFields: ['title', 'description'],
+    schemaName: 'central',
+    enableQualiexEnrichment: true
+  });
+```
+
+**✅ Por que exportar o `service`?**
+- Permite chamar `ExampleService.getAll()` diretamente para exportação
+- Busca todos os registros sem depender do manager paginado
+
+---
+
+#### **Passo 2: Criar Componente de Filtro**
+
+```typescript
+// src/examples/ExamplesPage.tsx
+
+// 1️⃣ Estado do filtro (padrão: true = apenas Ativos)
+const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
+
+// 2️⃣ Manager com filtro aplicado no backend
+const manager = useExamplesCrud(
+  statusFilter === 'all' ? {} : { is_actived: statusFilter }
+);
+
+// 3️⃣ Componente de filtro customizado
+const StatusFilter = () => (
+  <EntitySelect
+    value={String(statusFilter)}
+    onChange={(v) => setStatusFilter(v === 'all' ? 'all' : v === 'true')}
+    items={[
+      { 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]"
+  />
+);
+```
+
+**📝 Como funciona:**
+- `statusFilter` controla o estado do filtro
+- `useExamplesCrud` recebe `{ is_actived: true }` como filtro backend
+- Backend retorna apenas registros com `is_actived = true`
+- Paginação mostra total correto (ex: "1-10 de 43 itens")
+
+---
+
+#### **Passo 3: Implementar Exportação para CSV**
+
+```typescript
+// src/examples/ExamplesPage.tsx
+import { Download } from 'lucide-react';
+import { useToast, formatDatetime } from 'forlogic-core';
+import { ExampleService } from './ExampleService';
+
+export const ExamplesPage = () => {
+  const { toast } = useToast();
+  const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
+  const manager = useExamplesCrud(
+    statusFilter === 'all' ? {} : { is_actived: statusFilter }
+  );
+
+  // 🚀 Função de exportação (busca TODOS os itens)
+  const handleExport = async () => {
+    try {
+      // 1️⃣ Mostrar feedback
+      toast({
+        title: 'Exportando...',
+        description: 'Buscando todos os registros'
+      });
+
+      // 2️⃣ Buscar TODOS os registros (limite alto)
+      const filters = statusFilter === 'all' ? {} : { is_actived: statusFilter };
+      const allData = await ExampleService.getAll({
+        search: manager.searchTerm, // Manter busca atual
+        limit: 10000, // Limite alto para buscar tudo
+        page: 1,
+        ...filters // Aplicar filtros de status
+      });
+
+      // 3️⃣ Validar dados
+      if (!allData.data || allData.data.length === 0) {
+        toast({
+          variant: 'destructive',
+          title: 'Nenhum dado disponível',
+          description: 'Não há dados para exportar'
+        });
+        return;
+      }
+
+      // 4️⃣ Definir cabeçalhos do CSV
+      const headers = [
+        'Título',
+        'Responsável',
+        'Status',
+        'Link',
+        'Descrição',
+        'Cor',
+        'Ícone',
+        'Atualizado em'
+      ];
+      
+      // 5️⃣ Mapear dados para linhas CSV
+      const rows = allData.data.map((item: Example) => [
+        item.title || '',
+        item.responsible_name || '',
+        item.is_actived ? 'Ativo' : 'Inativo',
+        item.url_field || '',
+        item.description || '',
+        item.color || '',
+        item.icon_name || '',
+        formatDatetime(item.updated_at)
+      ]);
+
+      // 6️⃣ Criar conteúdo CSV
+      const csvContent = [
+        headers.join(','),
+        ...rows.map(row => 
+          row.map(cell => `"${String(cell).replace(/"/g, '""')}"`).join(',')
+        )
+      ].join('\n');
+
+      // 7️⃣ Criar blob e fazer download
+      const blob = new Blob(['\ufeff' + csvContent], { 
+        type: 'text/csv;charset=utf-8;' 
+      });
+      const link = document.createElement('a');
+      const url = URL.createObjectURL(blob);
+      link.setAttribute('href', url);
+      link.setAttribute('download', `exemplos_${new Date().toISOString().split('T')[0]}.csv`);
+      link.style.visibility = 'hidden';
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+
+      // 8️⃣ Feedback de sucesso
+      toast({
+        title: 'Exportação concluída',
+        description: `${allData.data.length} registros exportados com sucesso`
+      });
+    } catch (error) {
+      console.error('Erro ao exportar:', error);
+      toast({
+        variant: 'destructive',
+        title: 'Erro na exportação',
+        description: 'Não foi possível exportar os dados'
+      });
+    }
+  };
+
+  // Restante do código...
+};
+```
+
+**⚠️ IMPORTANTE:**
+- `ExampleService.getAll()` busca TODOS os registros (não só da página)
+- Limite de 10.000 itens - ajuste se necessário
+- `\ufeff` adiciona BOM para Unicode (acentos no Excel)
+- Escape de aspas duplas: `""` dentro do CSV
+
+---
+
+#### **Passo 4: Configurar `customActions` e `filters`**
+
+```typescript
+// src/examples/ExamplesPage.tsx
+
+const CrudPage = createCrudPage({
+  manager,
+  config: {
+    entityName: 'exemplo',
+    entityNamePlural: 'exemplos',
+    columns: exampleColumns,
+    formSections,
+    
+    // ✅ Filtros na barra superior
+    filters: [
+      { type: 'search' }, // Busca padrão
+      { type: 'custom', component: StatusFilter } // Filtro customizado
+    ],
+    
+    // ✅ Botão de exportar na barra de ações
+    customActions: [
+      {
+        label: 'Exportar',
+        icon: Download as any,
+        variant: 'outline' as const,
+        action: handleExport
+      }
+    ],
+    
+    enableBulkActions: true
+  },
+  onSave: handleSave,
+  onToggleStatus: handleToggleStatus
+});
+```
+
+---
+
+#### **🎯 Tipos de Filtros Disponíveis**
+
+##### **1. Filtro de Busca (Search)**
+```typescript
+filters: [
+  { type: 'search' } // Busca automática nos searchFields do service
+]
+```
+
+##### **2. Filtro Select Nativo**
+```typescript
+filters: [
+  {
+    type: 'select',
+    placeholder: 'Status',
+    value: statusFilter,
+    onChange: setStatusFilter,
+    options: [
+      { value: 'all', label: '[Todos]' },
+      { value: 'active', label: 'Ativo' },
+      { value: 'inactive', label: 'Inativo' }
+    ]
+  }
+]
+```
+
+##### **3. Filtro Customizado (Recomendado)**
+```typescript
+const StatusFilter = () => (
+  <EntitySelect
+    value={String(statusFilter)}
+    onChange={(v) => setStatusFilter(v === 'all' ? 'all' : v === 'true')}
+    items={[
+      { id: 'true', name: 'Ativo' },
+      { id: 'false', name: 'Inativo' },
+      { id: 'all', name: '[Todos]' }
+    ]}
+    getItemValue={(item) => item.id}
+    getItemLabel={(item) => item.name}
+    placeholder="Status"
+  />
+);
+
+filters: [
+  { type: 'custom', component: StatusFilter }
+]
+```
+
+---
+
+#### **📊 Resultado Visual**
+
+**Barra de Ações:**
+```
+[ + Novo ] [ 🔽 Exportar ]   [ 🔍 Buscar... ] [ Status: Ativo ▼ ]
+```
+
+**Ao clicar em "Exportar":**
+1. ✅ Toast: "Exportando... Buscando todos os registros"
+2. ✅ Download automático: `exemplos_2025-01-21.csv`
+3. ✅ Toast: "43 registros exportados com sucesso"
+
+**Conteúdo do CSV:**
+```csv
+Título,Responsável,Status,Link,Descrição,Cor,Ícone,Atualizado em
+"Exemplo 1","João Silva","Ativo","https://...","Descrição exemplo","#3b82f6","Star","21/01/2025 14:30"
+"Exemplo 2","Maria Santos","Inativo","","Outro exemplo","#f59e0b","Heart","20/01/2025 09:15"
+```
+
+---
+
+#### **🔥 Boas Práticas**
+
+**✅ FAZER:**
+- Exportar via `service.getAll()` para buscar todos os registros
+- Aplicar mesmos filtros na exportação
+- Escapar aspas duplas: `cell.replace(/"/g, '""')`
+- Adicionar BOM Unicode: `\ufeff` para acentos
+- Mostrar feedback (toast) durante exportação
+- Usar `async/await` para exportação
+
+**❌ NÃO FAZER:**
+- Exportar apenas `manager.entities` (só dados da página atual)
+- Ignorar filtros aplicados ao exportar
+- Esquecer de tratar erros
+- Exportar sem feedback visual
+
+---
+
+---
+
 ### **6️⃣ Views Customizadas (substituir Tabela/Cards)**
 
 Substitua completamente a tabela padrão por qualquer componente customizado.