forlogic-core 1.5.0 → 1.5.2

package/dist/docs/templates/complete-crud-example.tsx

@@ -0,0 +1,307 @@
+/**
+ * TEMPLATE: CRUD Completo
+ * ⚠️ REGRAS: Consulte docs/AI_REFERENCE.md
+ */
+
+// ============= 1. DEFINIR INTERFACE DA ENTIDADE =============
+// src/your-entity/your-entity.ts
+
+export interface YourEntity {
+  id: string;
+  // Campos obrigatórios
+  name: string;
+  email: string;
+  status: 'active' | 'inactive' | 'pending';
+  
+  // Campos opcionais
+  phone?: string | null;
+  description?: string | null;
+  category?: string | null;
+  
+  // Timestamps
+  created_at?: string;
+  updated_at?: string;
+}
+
+// ============= 2. CRIAR SERVIÇO =============
+// src/your-entity/yourEntityService.ts
+
+import { createSimpleService } from 'forlogic-core';
+import { YourEntity } from './your-entity';
+
+export const yourEntityService = createSimpleService<YourEntity>({
+  tableName: 'your_entities',
+  entityName: 'YourEntity',
+  schemaName: 'YOUR_SCHEMA', // Use o schema do seu projeto (ex: 'central', 'trainings', 'public')
+  searchFields: ['name', 'email'], // Campos que serão buscados
+});
+
+// ============= 3. FORM SECTIONS WITH VALIDATION =============
+// src/your-entity/YourEntityPage.tsx (seções do formulário)
+
+import type { FormSection } from 'forlogic-core';
+
+// Define as seções do formulário com validações customizadas
+const formSections: FormSection[] = [
+  {
+    id: 'basic-info',
+    title: 'Informações Básicas',
+    fields: [
+      {
+        name: 'name',
+        label: 'Nome',
+        type: 'text',
+        required: true,
+        placeholder: 'Digite o nome',
+      },
+      {
+        name: 'email',
+        label: 'Email',
+        type: 'email',
+        required: true,
+        placeholder: 'email@exemplo.com',
+        validation: (value: string) => {
+          if (!value) return 'Email é obrigatório';
+          const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+          if (!emailRegex.test(value)) return 'Email inválido';
+          return undefined;
+        },
+      },
+      {
+        name: 'status',
+        label: 'Status',
+        type: 'select',
+        required: true,
+        options: [
+          { value: 'active', label: 'Ativo' },
+          { value: 'inactive', label: 'Inativo' },
+          { value: 'pending', label: 'Pendente' },
+        ],
+        defaultValue: 'active',
+      },
+    ],
+  },
+  {
+    id: 'additional-info',
+    title: 'Informações Adicionais',
+    fields: [
+      {
+        name: 'phone',
+        label: 'Telefone',
+        type: 'tel',
+        placeholder: '(00) 00000-0000',
+      },
+      {
+        name: 'category',
+        label: 'Categoria',
+        type: 'select',
+        options: [
+          { value: 'type1', label: 'Tipo 1' },
+          { value: 'type2', label: 'Tipo 2' },
+        ],
+      },
+      {
+        name: 'description',
+        label: 'Descrição',
+        type: 'textarea',
+        placeholder: 'Digite uma descrição...',
+      },
+    ],
+  },
+];
+
+// ============= 4. CRIAR PÁGINA CRUD =============
+// src/your-entity/YourEntityPage.tsx
+
+import { createCrudPage, createSimpleSaveHandler, useCrud, type CrudColumn } from 'forlogic-core';
+import { Folder, Mail, CheckCircle, XCircle, AlertCircle } from 'lucide-react';
+import { YourEntity } from './your-entity';
+import { yourEntityService } from './yourEntityService';
+
+// Função helper para renderizar status
+const renderStatus = (status: string) => {
+  const statusConfig = {
+    active: { icon: CheckCircle, label: 'Ativo', color: 'text-green-500' },
+    inactive: { icon: XCircle, label: 'Inativo', color: 'text-red-500' },
+    pending: { icon: AlertCircle, label: 'Pendente', color: 'text-yellow-500' },
+  };
+  
+  const config = statusConfig[status as keyof typeof statusConfig];
+  const Icon = config.icon;
+  
+  return (
+    <div className="flex items-center gap-2">
+      <Icon className={`h-4 w-4 ${config.color}`} />
+      <span className={config.color}>{config.label}</span>
+    </div>
+  );
+};
+
+// Configuração das colunas com renderização customizada
+const columns: CrudColumn<YourEntity>[] = [
+  { 
+    key: 'name', 
+    header: 'Nome',
+    sortable: true,
+    render: (item: YourEntity) => <span className="font-medium">{item.name}</span>
+  },
+  { 
+    key: 'status',
+    header: 'Status',
+    sortable: true,
+    render: (item: YourEntity) => renderStatus(item.status)
+  },
+  { 
+    key: 'email', 
+    header: 'Email',
+    sortable: true,
+    render: (item: YourEntity) => (
+      <a 
+        href={`mailto:${item.email}`}
+        className="flex items-center gap-2 text-primary hover:underline"
+      >
+        <Mail className="h-4 w-4" />
+        {item.email}
+      </a>
+    )
+  },
+  { 
+    key: 'category', 
+    header: 'Categoria',
+    sortable: true,
+    render: (item: YourEntity) => item.category || '-'
+  },
+];
+
+// Campos para exibição em cards (mobile/tablet)
+const cardFields = [
+  { 
+    key: 'name', 
+    label: 'Nome',
+    render: (item: YourEntity) => <span className="font-semibold text-lg">{item.name}</span>
+  },
+  { 
+    key: 'status',
+    label: 'Status',
+    render: (item: YourEntity) => renderStatus(item.status)
+  },
+  { 
+    key: 'email', 
+    label: 'Email',
+    render: (item: YourEntity) => (
+      <a 
+        href={`mailto:${item.email}`}
+        className="flex items-center gap-2 text-primary hover:underline"
+      >
+        <Mail className="h-4 w-4" />
+        {item.email}
+      </a>
+    )
+  },
+];
+
+// Componente da página
+export function YourEntityPage() {
+  const manager = useCrud(yourEntityService);
+
+  // Handler customizado para normalizar dados antes de salvar
+  const handleSave = createSimpleSaveHandler(
+    manager,
+    // Transform para CREATE
+    (data: any) => ({
+      ...data,
+      email: data.email?.toLowerCase().trim(),
+      phone: data.phone || null,
+      category: data.category || null,
+      description: data.description || null,
+      status: data.status || 'active',
+    }),
+    // Transform para UPDATE
+    (data: any) => ({
+      ...data,
+      email: data.email?.toLowerCase().trim(),
+      phone: data.phone || null,
+      category: data.category || null,
+      description: data.description || null,
+    })
+  );
+
+  // Criar página CRUD completa
+  const CrudPage = createCrudPage({
+    manager,
+    config: {
+      entityName: 'Entidade',
+      entityNamePlural: 'Entidades',
+      columns,
+      formSections, // Seções definidas anteriormente
+      cardFields
+    },
+    onSave: handleSave
+  });
+
+  return <CrudPage />;
+}
+
+// ============= 5. ADICIONAR NO APP.TSX =============
+/*
+import { YourEntityPage } from './your-entity/YourEntityPage';
+import { Folder } from 'lucide-react';
+
+// No sidebarConfig:
+navigation: [
+  { 
+    label: 'Suas Entidades', 
+    path: '/your-entities', 
+    icon: Folder, 
+    complementaryText: 'Gerenciar suas entidades' 
+  },
+]
+
+// Nas Routes:
+<Route
+  path="/your-entities"
+  element={
+    <ProtectedRoute>
+      <YourEntityPage />
+    </ProtectedRoute>
+  }
+/>
+*/
+
+// ============= PONTOS-CHAVE PARA CRUD COMPLETO =============
+/*
+1. **Arquitetura Simplificada**: 
+   - Apenas 2 camadas: createCrudPage → BaseForm
+   - Sem componentes intermediários desnecessários
+   - Use formSections diretamente no createCrudPage
+
+2. **Renderização Customizada**:
+   - Use a propriedade `render` nas columns e cardFields
+   - Receba o item completo no render: (item: YourEntity) => JSX
+   - Adicione ícones e formatação visual
+   - Crie links clicáveis (mailto, tel)
+
+3. **handleSave Customizado**:
+   - Use createSimpleSaveHandler com manager
+   - Normalize dados (lowercase emails, trim strings)
+   - Transforme dados antes de salvar
+   - Trate campos opcionais (null vs undefined)
+
+4. **cardFields**:
+   - Define como os dados aparecem em mobile/tablet
+   - Mostra apenas campos mais importantes
+   - Mesma renderização customizada das columns
+
+5. **Validações**:
+   - Cliente: função `validation` nos fields das formSections
+   - Retorne undefined (não null) para validação com sucesso
+   - Servidor: RLS policies no Supabase
+   - Dupla camada de segurança
+
+6. **Boas Práticas**:
+   - Use tipos TypeScript consistentes
+   - Crie funções helper para renderizações reutilizáveis
+   - Defina status como union types ('active' | 'inactive')
+   - Sempre normalize dados (emails lowercase, trim)
+   - NUNCA crie FormComponent customizado - use formSections!
+*/

package/dist/docs/templates/custom-form.tsx

@@ -0,0 +1,99 @@
+/**
+ * TEMPLATE: Formulário Customizado
+ * 📚 Detalhes: Consulte docs/FOR_AI.md
+ */
+import { BaseForm } from 'forlogic-core'
+import { z } from 'zod'
+
+// Schema de validação (opcional)
+const validationSchema = z.object({
+  FIELD_NAME: z.string().min(1, 'FIELD_LABEL é obrigatório'),
+  // Adicione mais validações conforme necessário
+})
+
+// Definir seções do formulário
+const formSections = [{
+  title: 'SECTION_TITLE',
+  fields: [
+    { 
+      key: 'FIELD_NAME', 
+      label: 'FIELD_LABEL', 
+      type: 'FIELD_TYPE' as const, 
+      required: BOOLEAN,
+      placeholder: 'PLACEHOLDER_TEXT'
+    },
+    // Campos de seleção
+    {
+      key: 'SELECT_FIELD',
+      label: 'SELECT_LABEL',
+      type: 'select' as const,
+      options: [
+        { value: 'option1', label: 'Opção 1' },
+        { value: 'option2', label: 'Opção 2' }
+      ]
+    },
+    // Campo de checkbox
+    { 
+      key: 'CHECKBOX_FIELD', 
+      label: 'CHECKBOX_LABEL', 
+      type: 'checkbox' as const 
+    },
+    // Campo de texto longo
+    { 
+      key: 'TEXTAREA_FIELD', 
+      label: 'TEXTAREA_LABEL', 
+      type: 'textarea' as const,
+      rows: 4
+    }
+  ]
+}]
+
+interface FORM_NAMEProps {
+  entityId?: string
+  onSave: (data: any) => void
+  onCancel: () => void
+}
+
+export function FORM_NAMEForm({ entityId, onSave, onCancel }: FORM_NAMEProps) {
+  return (
+    <BaseForm
+      entityId={entityId}
+      entity="TABLE_NAME"
+      entityLabel="ENTITY_LABEL"
+      formSections={formSections}
+      validationSchema={validationSchema}
+      onSave={onSave}
+      onCancel={onCancel}
+      submitText="Salvar ENTITY_LABEL"
+      cancelText="Cancelar"
+    />
+  )
+}
+
+/* 
+TIPOS DE CAMPO DISPONÍVEIS:
+
+- 'text' - Texto simples
+- 'email' - Email com validação
+- 'password' - Senha oculta
+- 'number' - Números
+- 'textarea' - Texto longo
+- 'select' - Lista de opções
+- 'checkbox' - Verdadeiro/falso
+- 'date' - Data
+- 'rich-text' - Editor HTML
+- 'qualiex-user' - Seleção de usuário Qualiex
+- 'qualiex-responsible' - Seleção de responsável Qualiex
+
+EXEMPLO DE VALIDAÇÃO COM ZOD:
+
+const schema = z.object({
+  name: z.string().min(1, 'Nome é obrigatório'),
+  email: z.string().email('Email inválido'),
+  age: z.number().min(18, 'Deve ser maior de idade'),
+  active: z.boolean(),
+  category: z.enum(['option1', 'option2'], {
+    errorMap: () => ({ message: 'Categoria é obrigatória' })
+  })
+})
+*/

package/dist/docs/templates/custom-service.tsx

@@ -0,0 +1,194 @@
+/**
+ * TEMPLATE: Service Customizado
+ * 📚 Detalhes: Consulte docs/FOR_AI.md
+ */
+import { BaseService } from 'forlogic-core'
+
+// Interface da entidade
+interface ENTITY_TYPE {
+  id?: string
+  FIELD_NAME: string
+  // Adicione mais campos conforme necessário
+  created_at?: string
+  updated_at?: string
+}
+
+class ENTITY_NAMEService extends BaseService<ENTITY_TYPE> {
+  constructor() {
+    super('TABLE_NAME')
+  }
+
+  // Método customizado - buscar por campo específico
+  async getByFIELD_NAME(fieldValue: string): Promise<ENTITY_TYPE[]> {
+    const { data, error } = await this.supabase
+      .from(this.tableName)
+      .select('*')
+      .eq('FIELD_NAME', fieldValue)
+
+    if (error) throw error
+    return data || []
+  }
+
+  // Método customizado - buscar ativos
+  async getActive(): Promise<ENTITY_TYPE[]> {
+    const { data, error } = await this.supabase
+      .from(this.tableName)
+      .select('*')
+      .eq('active', true)
+      .order('created_at', { ascending: false })
+
+    if (error) throw error
+    return data || []
+  }
+
+  // Override do método create com validação customizada
+  async create(item: Omit<ENTITY_TYPE, 'id'>): Promise<ENTITY_TYPE> {
+    // Validação customizada
+    if (!item.FIELD_NAME?.trim()) {
+      throw new Error('FIELD_LABEL é obrigatório')
+    }
+
+    // Verificar duplicatas
+    const existing = await this.getByFIELD_NAME(item.FIELD_NAME)
+    if (existing.length > 0) {
+      throw new Error('FIELD_LABEL já existe')
+    }
+
+    return super.create(item)
+  }
+
+  // Override do método update
+  async update(id: string, item: Partial<ENTITY_TYPE>): Promise<ENTITY_TYPE> {
+    // Validação antes de atualizar
+    if (item.FIELD_NAME && !item.FIELD_NAME.trim()) {
+      throw new Error('FIELD_LABEL não pode estar vazio')
+    }
+
+    return super.update(id, item)
+  }
+
+  // Método customizado - busca com paginação
+  async getPaginated(page: number = 1, pageSize: number = 10) {
+    const from = (page - 1) * pageSize
+    const to = from + pageSize - 1
+
+    const { data, error, count } = await this.supabase
+      .from(this.tableName)
+      .select('*', { count: 'exact' })
+      .range(from, to)
+      .order('created_at', { ascending: false })
+
+    if (error) throw error
+
+    return {
+      data: data || [],
+      count: count || 0,
+      page,
+      pageSize,
+      totalPages: Math.ceil((count || 0) / pageSize)
+    }
+  }
+
+  // Método customizado - busca com filtros
+  async search(filters: {
+    FIELD_NAME?: string
+    active?: boolean
+    dateFrom?: string
+    dateTo?: string
+  }) {
+    let query = this.supabase.from(this.tableName).select('*')
+
+    if (filters.FIELD_NAME) {
+      query = query.ilike('FIELD_NAME', `%${filters.FIELD_NAME}%`)
+    }
+
+    if (filters.active !== undefined) {
+      query = query.eq('active', filters.active)
+    }
+
+    if (filters.dateFrom) {
+      query = query.gte('created_at', filters.dateFrom)
+    }
+
+    if (filters.dateTo) {
+      query = query.lte('created_at', filters.dateTo)
+    }
+
+    const { data, error } = await query.order('created_at', { ascending: false })
+
+    if (error) throw error
+    return data || []
+  }
+
+  // Método customizado - estatísticas
+  async getStats() {
+    const { data, error } = await this.supabase
+      .from(this.tableName)
+      .select('active')
+
+    if (error) throw error
+
+    const total = data?.length || 0
+    const active = data?.filter(item => item.active).length || 0
+    const inactive = total - active
+
+    return {
+      total,
+      active,
+      inactive,
+      activePercentage: total > 0 ? Math.round((active / total) * 100) : 0
+    }
+  }
+}
+
+// Exportar instância singleton
+export const ENTITY_NAMEService_instance = new ENTITY_NAMEService()
+
+/* 
+EXEMPLO DE USO NO COMPONENTE:
+
+import { ENTITY_NAMEService_instance } from '../services/ENTITY_NAMEService'
+
+function MyComponent() {
+  const [items, setItems] = useState([])
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    async function loadData() {
+      try {
+        const data = await ENTITY_NAMEService_instance.getActive()
+        setItems(data)
+      } catch (error) {
+        console.error('Erro ao carregar dados:', error)
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    loadData()
+  }, [])
+
+  const handleCreate = async (newItem) => {
+    try {
+      await ENTITY_NAMEService_instance.create(newItem)
+      // Recarregar dados
+    } catch (error) {
+      console.error('Erro ao criar:', error)
+    }
+  }
+
+  return (
+    <div>
+      {/* Sua UI aqui */}
+    </div>
+  )
+}
+
+MÉTODOS HERDADOS DO BaseService:
+
+- getAll(): Promise<T[]>
+- getById(id: string): Promise<T | null>
+- create(item: Omit<T, 'id'>): Promise<T>
+- update(id: string, item: Partial<T>): Promise<T>
+- delete(id: string): Promise<void>
+*/