forlogic-core 1.5.0 → 1.5.2

package/dist/README.md

@@ -0,0 +1,248 @@
+# ForLogic Core
+
+> **Biblioteca empresarial com React + TypeScript + Supabase**  
+> Sistema CRUD completo, autenticação, integração Qualiex e componentes UI prontos.
+
+---
+
+## 📦 Instalação
+
+```bash
+npm install forlogic-core
+```
+
+### Peer Dependencies
+
+A biblioteca requer as seguintes dependências (geralmente já presentes em projetos React):
+
+```bash
+npm install react react-dom react-router-dom @tanstack/react-query
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Configuração Inicial
+
+```tsx
+// src/main.tsx
+import { setupQualiexCore } from 'forlogic-core';
+import 'forlogic-core/index.css';
+
+setupQualiexCore({
+  supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
+  supabaseAnonKey: import.meta.env.VITE_SUPABASE_ANON_KEY
+});
+```
+
+### 2. Estrutura de Providers
+
+```tsx
+// src/App.tsx
+import { ErrorBoundary, QueryClientProvider, AuthProvider } from 'forlogic-core';
+import { BrowserRouter } from 'react-router-dom';
+
+function App() {
+  return (
+    <ErrorBoundary>
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider>
+          <BrowserRouter>
+            {/* Suas rotas aqui */}
+          </BrowserRouter>
+        </AuthProvider>
+      </QueryClientProvider>
+    </ErrorBoundary>
+  );
+}
+```
+
+### 3. Criar uma Página CRUD Completa
+
+```tsx
+// src/employees/EmployeesPage.tsx
+import { createCrudPage, createSimpleService, useCrud } from 'forlogic-core';
+
+// 1. Definir tipo
+interface Employee {
+  id?: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+// 2. Criar service
+const service = createSimpleService<Employee>('employees', { 
+  schemaName: 'central' // Usar schema do seu projeto
+});
+
+// 3. Criar hook
+const useEmployeesCrud = () => useCrud({ 
+  service, 
+  queryKey: 'employees' 
+});
+
+// 4. Configurar colunas e formulário
+const columns = [
+  { key: 'name', label: 'Nome' },
+  { key: 'email', label: 'Email' },
+  { key: 'role', label: 'Cargo' }
+];
+
+const formSections = [
+  {
+    title: 'Dados do Funcionário',
+    fields: [
+      { name: 'name', label: 'Nome', type: 'text', required: true },
+      { name: 'email', label: 'Email', type: 'email', required: true },
+      { name: 'role', label: 'Cargo', type: 'text', required: true }
+    ]
+  }
+];
+
+// 5. Exportar página
+export default createCrudPage({
+  useCrud: useEmployeesCrud,
+  columns,
+  formSections,
+  title: 'Funcionários'
+});
+```
+
+---
+
+## 📚 Documentação Completa
+
+A documentação detalhada está disponível em:
+
+- **[Regras para IA](dist/docs/AI_RULES.md)** - Checklist crítico para desenvolvimento assistido por IA
+- **[Troubleshooting](dist/docs/TROUBLESHOOTING.md)** - Soluções para problemas comuns
+- **[Templates Prontos](dist/docs/templates/)** - Códigos completos para copiar e usar
+- **[Navegação da Docs](dist/docs/README.md)** - Hub central da documentação
+
+---
+
+## 🎯 Recursos Principais
+
+### ✅ Sistema CRUD Completo
+- Tabelas com paginação, filtros e ordenação
+- Formulários automáticos com validação
+- Cards responsivos para mobile
+- Ações em lote (deletar múltiplos)
+
+### 🔐 Autenticação
+- Login/logout automático
+- Proteção de rotas
+- Integração com Supabase Auth
+- Gerenciamento de tokens
+
+### 🎨 Componentes UI
+- 50+ componentes prontos (shadcn/ui)
+- Design system completo
+- Dark mode nativo
+- Totalmente customizável
+
+### 🔗 Integrações
+- **Qualiex**: Componentes para seleção de usuários
+- **Supabase**: Cliente configurado automaticamente
+- **React Query**: Cache e sincronização de dados
+
+---
+
+## 💡 Exemplo de Uso Completo
+
+```tsx
+import { 
+  createCrudPage, 
+  createSimpleService, 
+  useCrud,
+  QualiexUserField 
+} from 'forlogic-core';
+
+interface Task {
+  id?: string;
+  title: string;
+  description: string;
+  responsible_id: string;
+  status: 'pending' | 'in_progress' | 'done';
+}
+
+const service = createSimpleService<Task>('tasks', { 
+  schemaName: 'central' 
+});
+
+const useTasksCrud = () => useCrud({ service, queryKey: 'tasks' });
+
+export default createCrudPage({
+  useCrud: useTasksCrud,
+  columns: [
+    { key: 'title', label: 'Título' },
+    { key: 'status', label: 'Status' },
+  ],
+  formSections: [
+    {
+      title: 'Dados da Tarefa',
+      fields: [
+        { name: 'title', label: 'Título', type: 'text', required: true },
+        { name: 'description', label: 'Descrição', type: 'textarea' },
+        { 
+          name: 'responsible_id', 
+          label: 'Responsável', 
+          type: 'custom',
+          component: QualiexUserField 
+        },
+        { 
+          name: 'status', 
+          label: 'Status', 
+          type: 'select',
+          options: [
+            { value: 'pending', label: 'Pendente' },
+            { value: 'in_progress', label: 'Em Progresso' },
+            { value: 'done', label: 'Concluído' }
+          ]
+        }
+      ]
+    }
+  ],
+  title: 'Tarefas'
+});
+```
+
+---
+
+## 🔧 Configuração Avançada
+
+### Import Modular (Tree-shaking)
+
+Para bundles menores, use imports específicos:
+
+```tsx
+import { Button, Input, Card } from 'forlogic-core/modular';
+```
+
+### Customização de Tema
+
+Edite `index.css` no seu projeto:
+
+```css
+:root {
+  --primary: 220 70% 50%;
+  --secondary: 210 40% 96.1%;
+  /* ... outros tokens */
+}
+```
+
+---
+
+## 📖 Links Úteis
+
+- **GitHub**: [forlogic-core](https://github.com/forlogic/forlogic-core)
+- **NPM**: [forlogic-core](https://www.npmjs.com/package/forlogic-core)
+- **Suporte**: [Issues](https://github.com/forlogic/forlogic-core/issues)
+
+---
+
+## 📝 Licença
+
+MIT License - ForLogic © 2025

package/dist/docs/AI_RULES.md

@@ -0,0 +1,213 @@
+# ForLogic Core - Regras Críticas para IA
+
+⚠️ **CONSULTAR SEMPRE antes de implementar funcionalidades**
+
+**Documentação completa:** `forlogic-core/dist/README.md` (quando instalado via npm)
+
+---
+
+## 📋 Checklist Rápido
+
+Antes de criar qualquer funcionalidade:
+
+- [ ] ✅ Verificar schema do projeto em `KNOWLEDGE.md`
+- [ ] ✅ Usar template CRUD padrão (Regra #2)
+- [ ] ✅ NÃO recriar integrações existentes (Regra #3 e #4)
+- [ ] ✅ Usar `useMemo()` em configs (Regra #5)
+- [ ] ✅ NÃO criar índices sem solicitação (Regra #6)
+
+---
+
+## ⚠️ Regra #1: Schema do Projeto
+
+**Problema:** IA usa `public` quando projeto tem schema customizado.
+
+**Solução:**
+1. **SEMPRE verificar** `KNOWLEDGE.md` → "Schema do Banco"
+2. **NUNCA assumir** schema `public`
+3. **Configurar corretamente** em todos os services
+
+**Exemplo:**
+```typescript
+// ❌ ERRADO (assume public)
+const service = createSimpleService<Employee>('employees');
+
+// ✅ CORRETO (usa schema do projeto)
+const service = createSimpleService<Employee>('employees', { 
+  schemaName: 'central' // ← schema do KNOWLEDGE.md
+});
+```
+
+**Ver detalhes:** README.md → "Quick Start" → Seção 1
+
+---
+
+## ⚠️ Regra #2: Template CRUD Padrão (Único)
+
+**Problema:** IA cria CRUDs customizados complexos desnecessariamente.
+
+**Solução:** Usar SEMPRE o template único de 4 passos:
+
+```typescript
+// 1. Service
+const service = createSimpleService<Entity>('table_name', { schemaName: 'central' });
+
+// 2. Hook
+const useCrud = () => useCrud({ service, queryKey: 'entities' });
+
+// 3. Save Handler
+const handleSave = createSimpleSaveHandler({
+  service,
+  queryClient,
+  queryKey: 'entities',
+  successMessage: 'Salvo com sucesso!',
+  errorMessage: 'Erro ao salvar'
+});
+
+// 4. Página
+export default createCrudPage({
+  useCrud,
+  columns: [...],
+  formSections: [...],
+  handleSave
+});
+```
+
+**Ver exemplos completos:** README.md → "Quick Start" → Seção 3
+
+---
+
+## ⚠️ Regra #3: Integração Qualiex
+
+**Problema:** IA recria componentes de seleção de usuários do Qualiex.
+
+**Solução:** Usar componentes prontos da lib:
+
+```typescript
+import { QualiexUserField, QualiexResponsibleSelectField } from 'forlogic-core';
+
+// Campo simples
+<QualiexUserField
+  name="user_id"
+  label="Usuário"
+  control={control}
+/>
+
+// Campo com múltipla seleção
+<QualiexResponsibleSelectField
+  name="responsibles"
+  label="Responsáveis"
+  control={control}
+  isMulti
+/>
+```
+
+**NÃO criar:** Componentes customizados, hooks próprios, integrações manuais.
+
+**Ver detalhes:** README.md → "Integrações" ou templates/qualiex-integration-example.tsx
+
+---
+
+## ⚠️ Regra #4: Integração Supabase
+
+**Problema:** IA cria cliente Supabase próprio ou configurações manuais.
+
+**Solução:** Usar setup automático via `setupQualiexCore()`:
+
+```typescript
+// src/main.tsx
+import { setupQualiexCore } from 'forlogic-core';
+
+setupQualiexCore({
+  supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
+  supabaseAnonKey: import.meta.env.VITE_SUPABASE_ANON_KEY
+});
+```
+
+**NÃO criar:** Clientes Supabase manuais, configurações duplicadas.
+
+**Ver detalhes:** README.md → "Quick Start" → Seção 1
+
+---
+
+## ⚠️ Regra #5: Performance (Evitar Reloads)
+
+**Problema:** Página recarrega ao trocar de rota (sidebar pisca, estado reseta).
+
+**Causa:** Configs recriadas a cada render (ex: `sidebarConfig` sem `useMemo`).
+
+**Solução:**
+
+### ✅ Usar `useMemo()` em configs:
+```typescript
+const sidebarConfig = useMemo(() => ({
+  modules: [...]
+}), []); // ← Dependências vazias se config é estático
+```
+
+### ✅ Estruturar rotas com `<Outlet />`:
+```typescript
+<Routes>
+  <Route path="/" element={<AppLayout sidebarConfig={sidebarConfig} />}>
+    <Route index element={<HomePage />} />
+    <Route path="employees" element={<EmployeesPage />} />
+  </Route>
+</Routes>
+```
+
+**Ver detalhes:** README.md → "Quick Start" → Seção 2 ou templates/app-layout.tsx
+
+---
+
+## ⚠️ Regra #6: Índices de Banco de Dados
+
+**Problema:** IA cria índices automaticamente em migrations sem necessidade.
+
+**Solução:**
+- ✅ **NÃO criar índices automaticamente**
+- ✅ **Criar índices APENAS quando:**
+  - Usuário solicita explicitamente
+  - Performance está degradada e índice é a solução
+  - Há justificativa técnica clara
+
+**Exemplo de quando NÃO criar:**
+```sql
+-- ❌ NÃO FAZER (sem solicitação)
+CREATE INDEX idx_employees_name ON central.employees(name);
+CREATE INDEX idx_employees_created_at ON central.employees(created_at);
+```
+
+**Exemplo de quando criar:**
+```sql
+-- ✅ OK (usuário solicitou explicitamente)
+-- "Por favor, crie um índice em 'email' para acelerar as buscas"
+CREATE INDEX idx_employees_email ON central.employees(email);
+```
+
+---
+
+## 🎯 Boas Práticas
+
+### Ordem dos Providers (App.tsx)
+```typescript
+<ErrorBoundary>
+  <QueryClientProvider client={queryClient}>
+    <AuthProvider>
+      <BrowserRouter>
+        <Routes>...</Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  </QueryClientProvider>
+</ErrorBoundary>
+```
+
+**Nota:** Se inverter, a própria IA verá o erro no console e corrigirá.
+
+---
+
+## 🔗 Links Úteis
+
+- **Documentação Completa:** `forlogic-core/dist/README.md`
+- **Templates Prontos:** `forlogic-core/dist/docs/templates/`
+- **Troubleshooting:** `forlogic-core/dist/docs/TROUBLESHOOTING.md`
+- **Hub da Docs:** `forlogic-core/dist/docs/README.md`

package/dist/docs/README.md

@@ -0,0 +1,102 @@
+# ForLogic Core - Documentação
+
+> **Sistema empresarial completo com React + TypeScript + Supabase**
+
+Esta é a documentação completa da biblioteca `forlogic-core` para desenvolvimento acelerado de sistemas empresariais.
+
+---
+
+## 📖 Documentação Principal
+
+### 📦 [README.md](../README.md)
+**Instalação e Quick Start**
+
+Use este guia para:
+- Instalar a biblioteca
+- Configuração inicial
+- Primeiro exemplo CRUD
+- Visão geral dos recursos
+
+### 🤖 [AI_RULES.md](AI_RULES.md)
+**Regras críticas para desenvolvimento com IA**
+
+Use este guia quando:
+- Desenvolver com assistência de IA
+- Evitar problemas comuns
+- Seguir melhores práticas
+- Verificar checklist antes de criar funcionalidades
+
+### 🔧 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+**Soluções para problemas comuns**
+
+Use este guia quando:
+- Encontrar erros inesperados
+- Precisar depurar problemas
+- Buscar soluções rápidas
+
+---
+
+---
+
+## 📁 Templates Prontos
+
+Códigos completos e funcionais em `templates/`:
+
+- **[app-layout.tsx](templates/app-layout.tsx)** - Layout principal com sidebar e autenticação
+- **[basic-crud-page.tsx](templates/basic-crud-page.tsx)** - CRUD básico completo
+- **[complete-crud-example.tsx](templates/complete-crud-example.tsx)** - CRUD com todos os recursos
+- **[custom-form.tsx](templates/custom-form.tsx)** - Formulário personalizado
+- **[custom-service.tsx](templates/custom-service.tsx)** - Service customizado
+- **[qualiex-integration-example.tsx](templates/qualiex-integration-example.tsx)** - Integração com Qualiex
+- **[sidebar-config.tsx](templates/sidebar-config.tsx)** - Configuração de menu lateral
+
+---
+
+## 📚 Documentação Adicional
+
+- **[CRUD System](../crud/README.md)** - Documentação técnica do sistema CRUD
+- **[Architecture](architecture/)** - Documentos sobre arquitetura interna
+
+---
+
+## 🧭 Navegação Rápida
+
+| Documento | O que contém | Para quem |
+|-----------|-------------|-----------|
+| **README.md** | Instalação, Quick Start, exemplos básicos | Iniciantes, primeiros passos |
+| **AI_RULES.md** | Checklist crítico, regras obrigatórias | IA, desenvolvedores com IA |
+| **TROUBLESHOOTING.md** | Soluções de erros, problemas comuns | Todos |
+| **Templates** | Códigos prontos para copiar | Todos |
+| **crud/README.md** | Documentação técnica do sistema CRUD | Desenvolvedores avançados |
+
+---
+
+## 💡 Fluxo de Ajuda
+
+```
+Primeira vez com a lib?
+└─> Leia README.md (instalação + quick start)
+    └─> Copie um template de templates/
+        └─> Problema? Veja TROUBLESHOOTING.md
+            └─> Desenvolvendo com IA? Consulte AI_RULES.md
+```
+
+---
+
+## 🔄 Mudanças na Estrutura
+
+### Versão Atual
+- ✅ **README.md** criado como hub principal
+- ✅ **AI_RULES.md** substitui AI_GUIDE.md (mais focado e prático)
+- ✅ Links atualizados para arquivos existentes
+- ✅ Referências corretas para documentação instalada
+
+### Arquivos Removidos
+- ❌ `AI_GUIDE.md` (substituído por AI_RULES.md + README.md)
+- ❌ `DEVELOPER_GUIDE.md` (conteúdo integrado em README.md e crud/README.md)
+
+---
+
+## 📝 Licença
+
+MIT License - ForLogic © 2025