npm - forlogic-core - Versions diffs - 2.2.8 → 2.3.0 - Mend

forlogic-core 2.2.8 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1677) hide show

package/dist/README.md DELETED Viewed

@@ -1,1079 +0,0 @@
-# 🧱 Guia de Desenvolvimento
-> **IMPORTANTE**: Este README é genérico para todos os projetos. Para configurações específicas do projeto (como schema padrão), consulte o **Custom Knowledge** do projeto nas configurações do Lovable.
----
-## 📦 Instalação
-### Pré-requisitos
-A biblioteca `forlogic-core` requer as seguintes **peer dependencies** instaladas no seu projeto:
-```bash
-# Dependências obrigatórias
-npm install react@^18.0.0 react-dom@^18.0.0
-npm install lucide-react@>=0.400.0
-# Internacionalização (i18n)
-npm install i18next@^25.0.0 react-i18next@^16.0.0
-```
-### Instalar a Biblioteca
-```bash
-npm install forlogic-core
-```
-**Nota**: O npm/yarn irá alertar automaticamente se alguma peer dependency estiver faltando ou com versão incompatível.
-### Sincronizar regras e convenções
-```bash
-npx lib-update
-```
-> Copia apenas `docs/KNOWLEDGE.md` (regras + mapa de módulos) e `.note/memory/rules/`.
-> Documentação de componentes é acessada via rota `/ds` ou cross-project.
-### ⚠️ IMPORTANTE: Imports de i18n
-**Sempre** importe hooks de internacionalização do `forlogic-core`, nunca diretamente de `react-i18next`:
-```tsx
-// ❌ ERRADO - Causa conflito de instâncias (erro NO_I18NEXT_INSTANCE)
-import { useTranslation } from 'react-i18next';
-// ✅ CORRETO - Usa a mesma instância configurada pelo CoreProviders
-import { useTranslation } from 'forlogic-core';
-```
-Isso garante que todos os componentes compartilhem a mesma instância do i18next configurada pelo `CoreProviders`.
----
-## 📦 LIB-FIRST: Sempre Use Componentes da forlogic-core
-> **⚠️ REGRA FUNDAMENTAL**: Antes de criar qualquer componente, serviço ou utilitário no projeto, VERIFIQUE se já existe na `forlogic-core`.
-### 🤔 Por Quê?
-A `forlogic-core` é a **biblioteca central** de componentes, serviços e utilitários compartilhados entre todos os projetos. Quando você cria um componente local que já existe na lib:
-1. **❌ Drift de Design** - O componente local não acompanha evoluções futuras da lib
-2. **❌ Duplicação de Código** - Aumenta tamanho do bundle e manutenção
-3. **❌ Inconsistência** - UI/UX diferente entre projetos
-4. **❌ Retrabalho** - Correções de bugs precisam ser feitas em múltiplos lugares
-### 📋 Checklist OBRIGATÓRIO Antes de Criar Componentes
-```markdown
-- [ ] Pesquisei se o componente existe na forlogic-core?
-- [ ] Verifiquei a documentação do Design System (/design_system)?
-- [ ] Confirmei que a funcionalidade não pode ser alcançada com props/variantes existentes?
-- [ ] Se não existe, solicitei a inclusão na lib para beneficiar todos os projetos?
-```
-### ✅ CORRETO: Usar da Lib
-```typescript
-// ✅ Sempre importe da forlogic-core
-import {
-  Button,
-  Input,
-  Dialog,
-  Combobox,
-  SplitButton,
-  RichTextEditor,
-  createCrudPage,
-  cn,
-  formatDatetime
-} from 'forlogic-core';
-```
-### ❌ PROIBIDO: Criar Localmente (se existe na lib)
-```typescript
-// ❌ NUNCA crie pastas/arquivos que já existem na lib
-src/components/ui/button.tsx      // Existe na lib
-src/components/ui/dialog.tsx      // Existe na lib
-src/lib/utils.ts                  // cn() existe na lib
-src/components/SplitButton.tsx    // Existe na lib (a partir de v1.12.2)
-```
-### 🔄 Processo Quando Precisa de Customização
-| Cenário                             | Ação Correta                                         |
-| ----------------------------------- | ---------------------------------------------------- |
-| Componente não existe na lib        | ✅ Criar localmente E solicitar inclusão na lib      |
-| Precisa de variante nova            | ✅ Solicitar variante na lib (PR ou pedido)          |
-| Precisa de comportamento específico | ✅ Usar composição/wrapper ao invés de recriar       |
-| Bug no componente da lib            | ✅ Reportar e corrigir na lib, não criar cópia local |
-### 📖 Onde Verificar Componentes Disponíveis
-| Recurso                           | Descrição                                           |
-| --------------------------------- | --------------------------------------------------- |
-| `/design_system`                  | Design System com todos os componentes documentados |
-| `forlogic-core/lib/exports/ui.ts` | Lista de exports de UI                              |
-| `forlogic-core/lib/index.ts`      | Index principal com todos os exports                |
-| `npx lib-update`                  | Sincroniza regras e KNOWLEDGE.md                    |
-### ⚠️ Exceções (quando PODE criar localmente)
-1. **Componente específico de negócio** - Ex: `InvoiceCard`, `UserProfileWidget`
-2. **Composição de componentes da lib** - Ex: wrapper que combina Dialog + Form
-3. **Componente temporário** - Protótipo que será migrado para a lib depois
-4. **Funcionalidade não generalizável** - Algo tão específico que não faz sentido na lib
-> **📝 Mesmo nas exceções, avalie se o componente poderia ser generalizado e incluído na lib para beneficiar outros projetos.**
----
-## 🤖 REGRAS CRÍTICAS
-> **📋 Schema Padrão**: Veja no **Custom Knowledge** do projeto (Settings → Manage Knowledge) qual é o schema padrão deste projeto específico.
-### ⚠️ TOP 4 ERROS MAIS COMUNS
-1. **ESQUECER SCHEMA**
-```typescript
-// ❌ ERRADO
-.from('table')
-// ✅ CORRETO (verifique o schema padrão no Custom Knowledge)
-.schema('SEU_SCHEMA').from('table')
-```
-2. **RLS COM SINTAXE INCORRETA**
-```sql
--- ❌ ERRADO: Usar WITH CHECK em SELECT
-CREATE POLICY "Users view own" ON seu_schema.table
-FOR SELECT WITH CHECK (auth.uid() = id_user);
--- ✅ CORRETO: USING para SELECT
-CREATE POLICY "Users view own" ON seu_schema.table
-FOR SELECT USING (
-  ((SELECT auth.jwt()) ->> 'alias'::text) = alias
-);
-```
-3. **CRIAR POLÍTICAS DELETE**
-```sql
--- ❌ PROIBIDO: Política DELETE
-CREATE POLICY "table_delete" ON seu_schema.table
-FOR DELETE USING (...);
--- ✅ CORRETO: Use soft delete com UPDATE
-ALTER TABLE seu_schema.table ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE;
-```
-4. **CRIAR ÍNDICES AUTOMATICAMENTE**
-```sql
--- ❌ PROIBIDO criar índices sem aprovação
-CREATE INDEX idx_table_user ON seu_schema.table(id_user);
--- ✅ Apenas quando solicitado explicitamente e aprovado
-```
----
-## 📝 CONVENÇÕES DE NOMENCLATURA
-### ⚠️ PADRÕES OBRIGATÓRIOS
-**Foreign Keys (Chaves Estrangeiras):**
-```typescript
-// ❌ ERRADO
-process_id: string
-user_id: string
-// ✅ CORRETO - Sempre prefixo id_
-id_process: string
-id_user: string
-```
-**Booleans:**
-```typescript
-// ❌ ERRADO
-active: boolean
-removed: boolean
-// ✅ CORRETO - Sempre prefixo is_
-is_active: boolean
-is_removed: boolean
-```
-**Timestamps:**
-```typescript
-// ❌ ERRADO
-creation_date: string
-update_time: string
-// ✅ CORRETO - Sempre sufixo _at
-created_at: string
-updated_at: string
-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);
--- ❌ PROIBIDO: Índice em campo de busca "porque pode ser útil"
-CREATE INDEX idx_process_title ON processes(title);
--- ❌ PROIBIDO: Índice composto "por precaução"
-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`?
-- [ ] A migration NÃO contém políticas DELETE?
-- [ ] Se contém índice, o usuário solicitou EXPLICITAMENTE?
-- [ ] Se contém índice, foi feita análise de performance (EXPLAIN ANALYZE)?
-- [ ] Se contém índice, o usuário APROVOU adicionar à migration?
-- [ ] Estou usando soft delete ao invés de DELETE físico?
-- [ ] Especifiquei o schema correto em todas as tabelas?
-- [ ] Usei sintaxe correta nas políticas RLS (USING vs WITH CHECK)?
-```
-### 🔧 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."
-4. **Aguardar aprovação** do usuário
-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]
--- Justificativa: [RAZÃO ESPECÍFICA]
-CREATE INDEX idx_processes_title ON processes.processes(title);
--- Melhora busca por título em 80% (EXPLAIN ANALYZE anexo)
-```
----
-## ⚙️ Configuração Vite e Tailwind (Projetos Consumidores)
-A biblioteca `forlogic-core` exporta configurações padronizadas de Vite e Tailwind para garantir consistência de segurança e estilo em todos os projetos.
-### 📦 Imports Disponíveis
-```typescript
-// Configurações Vite (headers de segurança, CSP, CORS)
-import { createSecurityHeadersPlugin, createForlogicViteConfig } from 'forlogic-core/vite';
-// Preset Tailwind (cores, animações, gradientes)
-import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
-```
----
-### 🔒 Plugin de Headers de Segurança (Vite)
-O plugin configura automaticamente:
-- **Content Security Policy (CSP)** - Proteção contra XSS e injeção de scripts
-- **CORS seguro** - Origens confiáveis sem usar `*`
-- **Headers OWASP** - HSTS, X-Content-Type-Options, X-Frame-Options, etc.
-- **Permissions Policy** - Controle de APIs do navegador
-#### Uso Básico
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react-swc';
-import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
-export default defineConfig(({ mode }) => ({
-  plugins: [
-    react(),
-    createSecurityHeadersPlugin(mode === 'development', {
-      supabaseUrls: ['https://seu-projeto.supabase.co'],
-    }),
-  ],
-}));
-```
-#### Configuração Completa
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react-swc';
-import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
-export default defineConfig(({ mode }) => ({
-  plugins: [
-    react(),
-    createSecurityHeadersPlugin(mode === 'development', {
-      // URLs do Supabase para permitir conexões
-      supabaseUrls: [
-        'https://seu-projeto-dev.supabase.co',
-        'https://seu-projeto-prod.supabase.co',
-      ],
-      // Origens confiáveis adicionais para CORS
-      trustedOrigins: [
-        'https://meu-app.com',
-        'https://admin.meu-app.com',
-      ],
-      // APIs externas para connect-src
-      additionalConnectSrc: [
-        'https://api.exemplo.com',
-        'wss://websocket.exemplo.com',
-      ],
-      // CDNs de scripts/estilos/fontes adicionais
-      additionalScriptSrc: ['https://cdn.analytics.com'],
-      additionalStyleSrc: ['https://fonts.custom.com'],
-      additionalFontSrc: ['https://fonts.gstatic.com'],
-      // URI para reportar violações CSP
-      cspReportUri: 'https://seu-projeto.supabase.co/functions/v1/csp-report',
-      // Opções de produção (defaults: true)
-      enableTrustedTypes: true,
-      upgradeInsecureRequests: true,
-    }),
-  ],
-}));
-```
-#### Opções do Plugin
-| Opção                     | Tipo       | Padrão | Descrição                               |
-| ------------------------- | ---------- | ------ | --------------------------------------- |
-| `supabaseUrls`            | `string[]` | `[]`   | URLs do Supabase permitidas             |
-| `trustedOrigins`          | `string[]` | `[]`   | Origens confiáveis adicionais para CORS |
-| `additionalScriptSrc`     | `string[]` | `[]`   | Fontes de script adicionais para CSP    |
-| `additionalStyleSrc`      | `string[]` | `[]`   | Fontes de estilo adicionais para CSP    |
-| `additionalConnectSrc`    | `string[]` | `[]`   | APIs/WebSockets adicionais para CSP     |
-| `additionalFontSrc`       | `string[]` | `[]`   | Fontes de font adicionais para CSP      |
-| `cspReportUri`            | `string`   | -      | URI para relatório de violações CSP     |
-| `enableTrustedTypes`      | `boolean`  | `true` | Habilitar Trusted Types em produção     |
-| `upgradeInsecureRequests` | `boolean`  | `true` | Upgrade HTTP→HTTPS em produção          |
----
-### 🏗️ Factory de Configuração Vite (Opcional)
-Para projetos que desejam usar a configuração padronizada com segurança:
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react-swc';
-import path from 'path';
-import { createForlogicViteConfig } from 'forlogic-core/vite';
-const forlogicConfig = createForlogicViteConfig({
-  security: {
-    supabaseUrls: ['https://seu-projeto.supabase.co'],
-    trustedOrigins: ['https://meu-app.com'],
-  },
-  server: { host: '::', port: 8080 },
-  build: { chunkSizeWarningLimit: 4000 },
-});
-export default defineConfig(({ mode }) => {
-  const isDev = mode === 'development';
-  const baseConfig = forlogicConfig(isDev);
-  return {
-    ...baseConfig,
-    plugins: [react(), ...baseConfig.plugins],
-    // IMPORTANTE: resolve.alias deve usar caminhos absolutos
-    resolve: {
-      alias: {
-        '@': path.resolve(__dirname, './src'),
-      },
-    },
-  };
-});
-```
-> **⚠️ IMPORTANTE**: A factory **não** configura `resolve.alias` porque caminhos relativos não funcionam corretamente no build. Cada projeto deve definir seus próprios aliases com `path.resolve(__dirname, './caminho')` para garantir caminhos absolutos.
----
-### 📋 Template Completo para Projetos Consumidores
-Copie e adapte este template para novos projetos:
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react-swc';
-import path from 'path';
-import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
-export default defineConfig(({ mode }) => {
-  const isDev = mode === 'development';
-  return {
-    server: {
-      host: '::',
-      port: 8080,
-    },
-    // Força re-bundle quando atualizar forlogic-core
-    optimizeDeps: {
-      force: true,
-    },
-    plugins: [
-      react(),
-      // Headers de segurança (CSP, CORS, etc.)
-      createSecurityHeadersPlugin(isDev, {
-        supabaseUrls: [
-          'https://SEU_PROJETO.supabase.co',
-        ],
-        additionalConnectSrc: [
-          'https://*.qualiex.com',
-        ],
-        // Opcional: URI para relatório de violações CSP
-        cspReportUri: isDev
-          ? 'https://SEU_PROJETO_DEV.supabase.co/functions/v1/csp-report'
-          : 'https://SEU_PROJETO_PROD.supabase.co/functions/v1/csp-report',
-      }),
-    ],
-    // CRÍTICO: Aliases devem usar caminhos absolutos
-    resolve: {
-      alias: {
-        '@': path.resolve(__dirname, './src'),
-      },
-    },
-    publicDir: false,
-    esbuild: {
-      sourcemap: true,
-      target: 'es2020',
-    },
-    build: {
-      chunkSizeWarningLimit: 4000,
-    },
-  };
-});
-```
-#### Checklist de Configuração
-```markdown
-- [ ] Substituiu `SEU_PROJETO` pelas URLs do Supabase
-- [ ] Adicionou origens confiáveis em `additionalConnectSrc` se necessário
-- [ ] Verificou que `resolve.alias` usa `path.resolve(__dirname, ...)`
-- [ ] Reiniciou o servidor após modificar o arquivo
-```
----
-### 🔄 Forçar Re-bundle de Dependências
-Se você atualizar a `forlogic-core` e as mudanças não aparecerem no preview:
-```typescript
-// vite.config.ts
-export default defineConfig(({ mode }) => ({
-  optimizeDeps: {
-    force: true, // Força re-otimização a cada restart do dev server
-  },
-  // ...
-}));
-```
-> **⚠️ IMPORTANTE**: Após adicionar `force: true`, reinicie o servidor completamente (pare e inicie novamente).
----
-### 🎨 Preset Tailwind CSS
-O preset inclui:
-- **Cores semânticas** - primary, secondary, destructive, success, warning, etc.
-- **Border radius** - lg, md, sm padronizados
-- **Animações** - accordion, fade, slide, scale
-- **Gradientes** - primary, secondary, accent
-- **Sombras** - xs até 2xl, inner, primary
-#### Uso Básico
-```typescript
-// tailwind.config.ts
-import type { Config } from 'tailwindcss';
-import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
-export default {
-  presets: [forlogicTailwindPreset],
-  content: [
-    ...forlogicContentPaths,
-    // Paths adicionais específicos do seu projeto
-  ],
-} satisfies Config;
-```
-#### Uso com Extensões
-```typescript
-// tailwind.config.ts
-import type { Config } from 'tailwindcss';
-import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
-export default {
-  presets: [forlogicTailwindPreset],
-  content: [
-    ...forlogicContentPaths,
-  ],
-  theme: {
-    extend: {
-      // Extensões específicas do seu projeto
-      colors: {
-        brand: {
-          50: 'hsl(var(--brand-50))',
-          // ...
-        },
-      },
-    },
-  },
-  plugins: [
-    require('tailwindcss-animate'),
-    // Plugins adicionais
-  ],
-} satisfies Config;
-```
-#### Content Paths Padrão
-O `forlogicContentPaths` inclui:
-```typescript
-[
-  './pages/**/*.{ts,tsx}',
-  './components/**/*.{ts,tsx}',
-  './app/**/*.{ts,tsx}',
-  './src/**/*.{ts,tsx}',
-  './lib/**/*.{ts,tsx}',
-  './node_modules/forlogic-core/dist/**/*.{js,ts,jsx,tsx}',
-]
-```
----
-### 📋 Checklist de Configuração
-```markdown
-- [ ] Instalou `forlogic-core` no projeto?
-- [ ] Configurou `vite.config.ts` com `createSecurityHeadersPlugin`?
-- [ ] Adicionou URLs do Supabase em `supabaseUrls`?
-- [ ] Configurou `tailwind.config.ts` com `forlogicTailwindPreset`?
-- [ ] Adicionou `forlogicContentPaths` ao content?
-- [ ] Definiu variáveis CSS no `index.css` (--primary, --background, etc.)?
-```
----
-### 🔧 Configuração do package.json (Publicação da Lib)
-Para projetos que estão **publicando** a `forlogic-core`, adicione os exports condicionais:
-```json
-{
-  "exports": {
-    ".": {
-      "import": "./dist/index.esm.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./vite": {
-      "import": "./dist/vite/index.esm.js",
-      "require": "./dist/vite/index.js",
-      "types": "./dist/vite/index.d.ts"
-    },
-    "./tailwind": {
-      "import": "./dist/tailwind/index.esm.js",
-      "require": "./dist/tailwind/index.js",
-      "types": "./dist/tailwind/index.d.ts"
-    }
-  }
-}
-```
----
-## 🚩 Feature Flags (Variáveis de Ambiente)
-A biblioteca suporta feature flags para habilitar/desabilitar funcionalidades opcionais.
-### Variáveis Disponíveis
-| Variável                     | Descrição                                                                            | Valores              | Padrão    |
-| ---------------------------- | ------------------------------------------------------------------------------------ | -------------------- | --------- |
-| `VITE_SHOW_USER_PREFERENCES` | Exibe opção de "Preferências" no menu do usuário (idioma, timezone, formato de data) | `"true"` / `"false"` | Não exibe |
-| `VITE_I18N_DEBUG_MODE`       | Modo debug de internacionalização (mostra chaves ao invés de traduções)              | `"true"` / `"false"` | `"false"` |
-| `VITE_IS_QUALIEX`            | Define se usa logos Qualiex ou Forlogic                                              | `"true"` / `"false"` | `"false"` |
-### Configuração
-Adicione no seu arquivo `.env`:
-```env
-# Habilitar opção de preferências no perfil do usuário
-VITE_SHOW_USER_PREFERENCES=true
-# Modo debug de i18n (mostra chaves com ícones)
-VITE_I18N_DEBUG_MODE=false
-# Usar logos Qualiex
-VITE_IS_QUALIEX=true
-```
-> **Nota**: Variáveis de ambiente em Vite precisam ter o prefixo `VITE_` para serem expostas ao cliente.
----
-## 🌐 Setup de Traduções para Projetos Consumidores
-O sistema de i18n usa **namespaces**: a lib fornece traduções base no namespace `core` e cada projeto injeta suas traduções no namespace `app`. A resolução é: `app` → `core` → fallback `pt-BR`.
-### Requisitos
-| Requisito          | Descrição                                 |
-| ------------------ | ----------------------------------------- |
-| `i18next`          | Peer dependency instalada                 |
-| `react-i18next`    | Peer dependency instalada                 |
-| `CoreProviders`    | Wrapper no App.tsx                        |
-### Passo 1: Instalar Peer Dependencies
-```bash
-npm install i18next@^25.0.0 react-i18next@^16.0.0
-```
-### Passo 2: Criar JSONs de Tradução do Projeto
-Crie arquivos JSON flat (um por idioma) com as traduções específicas do seu projeto:
-```json
-// src/i18n/pt-BR.json
-{
-  "objective": "Objetivo",
-  "key_result": "Resultado-chave",
-  "cycle": "Ciclo"
-}
-```
-### Passo 3: Passar para CoreProviders via `appTranslations`
-```tsx
-// src/App.tsx
-import { CoreProviders } from 'forlogic-core';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-import ptBR from './i18n/pt-BR.json';
-// import enUS from './i18n/en-US.json'; // quando tiver
-function App() {
-  return (
-    <CoreProviders
-      moduleAlias="performance"
-      appTranslations={{
-        'pt-BR': ptBR,
-        // 'en-US': enUS,
-      }}
-    >
-      <BrowserRouter>
-        <Routes>
-          {/* Suas rotas */}
-        </Routes>
-      </BrowserRouter>
-    </CoreProviders>
-  );
-}
-export default App;
-```
-### Passo 4: Usar useTranslation do forlogic-core
-```tsx
-// ❌ ERRADO - Cria instância separada (erro NO_I18NEXT_INSTANCE)
-import { useTranslation } from 'react-i18next';
-// ✅ CORRETO - Usa mesma instância configurada
-import { useTranslation } from 'forlogic-core';
-function MeuComponente() {
-  const { t } = useTranslation();
-  return (
-    <div>
-      <h1>{t('objective')}</h1>     {/* namespace app → "Objetivo" */}
-      <Button>{t('save')}</Button>   {/* app → não encontra → core → "Salvar" */}
-    </div>
-  );
-}
-```
-### Como funciona a resolução de namespaces
-```
-t('save')
-  1. Busca em namespace 'app' (projeto) → não encontrou
-  2. Busca em namespace 'core' (lib) → "Salvar" ✅
-t('objective')
-  1. Busca em namespace 'app' (projeto) → "Objetivo" ✅
-t('save') com override no app
-  1. Busca em namespace 'app' → "Gravar" ✅ (sobrescreve o core)
-```
-### Troubleshooting
-#### Traduções mostram apenas as chaves
-| Causa                                | Solução                                                |
-| ------------------------------------ | ------------------------------------------------------ |
-| Peer dependencies faltando           | Instalar `i18next` e `react-i18next`                   |
-| Import de `react-i18next` direto     | Usar import de `forlogic-core`                         |
-| `appTranslations` não passado        | Adicionar prop no `CoreProviders`                      |
-| JSON com formato errado              | Deve ser flat: `{ "key": "value" }`, sem nesting       |
-#### Debug: Verificar se traduções foram carregadas
-```tsx
-import { i18n } from 'forlogic-core';
-console.log('i18n initialized:', i18n.isInitialized);
-console.log('Current language:', i18n.language);
-console.log('Loaded resources:', i18n.store.data);
-// Deve mostrar: { 'pt-BR': { core: {...}, app: {...} } }
-```
-### Checklist de Configuração
-```markdown
-- [ ] Instalou `i18next@^25.0.0` e `react-i18next@^16.0.0`?
-- [ ] Criou JSONs de tradução em `src/i18n/pt-BR.json`?
-- [ ] Passou `appTranslations` para o `CoreProviders`?
-- [ ] Todos os imports de `useTranslation` são de `forlogic-core` (nunca de `react-i18next`)?
-- [ ] O `App.tsx` usa `CoreProviders`?
-```
----
-## 🚀 Quick Setup: CoreProviders
-O `CoreProviders` é um componente que encapsula todos os providers essenciais da biblioteca, simplificando drasticamente a configuração de novos projetos.
-### O que está incluído
-O `CoreProviders` encapsula automaticamente:
-| Provider              | Descrição                                                   |
-| --------------------- | ----------------------------------------------------------- |
-| `ErrorBoundary`       | Captura e trata erros de renderização React                 |
-| `I18nextProvider`     | Sistema de internacionalização (i18n)                       |
-| `QueryClientProvider` | Cache e gerenciamento de queries (React Query)              |
-| `AuthProvider`        | Autenticação e gerenciamento de sessão                      |
-| `LocaleProvider`      | Gerenciamento de locale (idioma, timezone, formato de data) |
-| `TranslationLoader`   | Carregamento dinâmico de traduções do banco de dados        |
-### Uso Básico
-```tsx
-import { CoreProviders } from 'forlogic-core';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-function App() {
-  return (
-    <CoreProviders>
-      <BrowserRouter>
-        <Routes>
-          {/* Suas rotas aqui */}
-        </Routes>
-      </BrowserRouter>
-    </CoreProviders>
-  );
-}
-```
-### Com QueryClient Customizado
-Se você precisar de configurações específicas para o React Query:
-```tsx
-import { CoreProviders } from 'forlogic-core';
-import { QueryClient } from '@tanstack/react-query';
-import { BrowserRouter } from 'react-router-dom';
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 10 * 60 * 1000, // 10 minutos
-      retry: 2,
-      refetchOnWindowFocus: false,
-    },
-  },
-});
-function App() {
-  return (
-    <CoreProviders queryClient={queryClient}>
-      <BrowserRouter>
-        {/* Suas rotas */}
-      </BrowserRouter>
-    </CoreProviders>
-  );
-}
-```
-### Props
-| Prop          | Tipo          | Obrigatório | Descrição                                                                   |
-| ------------- | ------------- | ----------- | --------------------------------------------------------------------------- |
-| `children`    | `ReactNode`   | ✅          | Componentes filhos a serem envolvidos                                       |
-| `queryClient` | `QueryClient` | ❌          | Instância customizada do QueryClient. Se não fornecido, um default é criado |
-### QueryClient Default
-Se você não fornecer um `queryClient`, o `CoreProviders` cria um com as seguintes configurações:
-```typescript
-{
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutos
-      retry: 1,
-    },
-  },
-}
-```
-### Benefícios
-- ✅ **Zero configuração de i18n** - Traduções funcionam automaticamente
-- ✅ **Autenticação pronta** - `useAuth()` disponível em qualquer componente filho
-- ✅ **Tratamento de erros** - ErrorBoundary captura erros de renderização
-- ✅ **React Query configurado** - Cache e queries prontos para uso
-- ✅ **Locale gerenciado** - Preferências de idioma, timezone e formato de data
-- ✅ **Atualizações centralizadas** - Novos providers são adicionados automaticamente
----
-## 🎯 Ações Principais de Módulo (SidebarActionTrigger)
-O `SidebarActionTrigger` permite adicionar ações principais de módulo no sidebar, diferenciadas visualmente da navegação. São gatilhos de ação, não destinos de navegação.
-### Conceito
-| Característica      | Descrição                                                   |
-| ------------------- | ----------------------------------------------------------- |
-| **Ação de módulo**  | Válida apenas dentro do contexto do módulo ao qual pertence |
-| **Não global**      | Não aplicável a todo o sistema                              |
-| **Não contextual**  | Não depende de seleção de item específico                   |
-| **Destaque visual** | Exibida com aparência diferenciada da navegação             |
-### Uso Básico
-```tsx
-import { AppSidebar, SidebarConfig } from 'forlogic-core';
-import { Plus, FileText, Folder } from 'lucide-react';
-const sidebarConfig: SidebarConfig = {
-  appName: 'Meu Módulo',
-  // Ações principais do módulo
-  moduleActions: {
-    triggerLabel: 'Criar',
-    triggerIcon: Plus,
-    actions: [
-      {
-        id: 'create-item',
-        label: 'Novo Item',
-        icon: FileText,
-        onClick: () => openCreateDialog()
-      },
-      {
-        id: 'create-folder',
-        label: 'Nova Pasta',
-        icon: Folder,
-        onClick: () => openFolderDialog()
-      },
-    ]
-  },
-  // Navegação
-  navigation: [
-    { label: 'Visão Geral', path: '/', icon: Home },
-    { label: 'Configurações', path: '/settings', icon: Settings },
-  ]
-};
-<AppSidebar config={sidebarConfig} />
-```
-### Comportamento
-| Cenário               | Comportamento                     |
-| --------------------- | --------------------------------- |
-| **Uma ação**          | Clique executa a ação diretamente |
-| **Múltiplas ações**   | Clique exibe dropdown com opções  |
-| **Modal aberto**      | Gatilho fica desabilitado         |
-| **Sidebar colapsada** | Exibe apenas ícone com tooltip    |
-### Props do SidebarActionTrigger
-| Prop          | Tipo                   | Obrigatório | Descrição                   |
-| ------------- | ---------------------- | ----------- | --------------------------- |
-| `config`      | `SidebarActionsConfig` | ✅          | Configuração das ações      |
-| `isCollapsed` | `boolean`              | ❌          | Se a sidebar está colapsada |
-| `isDisabled`  | `boolean`              | ❌          | Desabilita o gatilho        |
-### Interface SidebarModuleAction
-```typescript
-interface SidebarModuleAction {
-  id: string;           // Identificador único
-  label: string;        // Texto do botão/opção
-  icon?: LucideIcon;    // Ícone opcional
-  onClick: () => void;  // Callback de execução
-  disabled?: boolean;   // Estado desabilitado
-  permissionCheck?: () => Promise<boolean>;
-}
-```
-### Interface SidebarActionsConfig
-```typescript
-interface SidebarActionsConfig {
-  triggerLabel?: string;    // Rótulo do gatilho (padrão: 'Criar')
-  triggerIcon?: LucideIcon; // Ícone do gatilho (padrão: Plus)
-  actions: SidebarModuleAction[];
-}
-```
-### Gerenciamento de Modais (Opcional)
-Para desabilitar o gatilho quando há modais abertos, use o `ModalStateProvider`:
-```tsx
-import { CoreProviders, ModalStateProvider, useModalState } from 'forlogic-core';
-// No App.tsx (opcional - CoreProviders não inclui por padrão)
-<CoreProviders>
-  <ModalStateProvider>
-    <AppLayout />
-  </ModalStateProvider>
-</CoreProviders>
-// Em componentes com modal
-function MeuDialog({ open, onOpenChange }) {
-  const { registerModal, unregisterModal } = useModalState();
-  useEffect(() => {
-    if (open) {
-      registerModal('meu-dialog');
-    } else {
-      unregisterModal('meu-dialog');
-    }
-  }, [open]);
-  return <Dialog open={open} onOpenChange={onOpenChange}>...</Dialog>;
-}
-```
-### Diretriz para Uso via Prompt
-#### ✅ Prompts corretos:
-- "Adicione uma ação principal 'Criar Processo' no sidebar do módulo"
-- "Configure o módulo para ter duas ações principais: 'Novo Item' e 'Nova Pasta'"
-- "Adicione o botão de criar no topo do sidebar como ação de módulo"
-#### ❌ Prompts ambíguos (evitar):
-- "Coloque um botão de criar no menu" (ambíguo - qual menu?)
-- "Adicione navegação para criar" (ação ≠ navegação)
-- "Crie um link para nova entidade" (link = navegação, não ação)
-## 🛠️ CLI: Sincronizar Regras e Convenções
-O `forlogic-core` disponibiliza um comando CLI para sincronizar regras e convenções arquiteturais para projetos consumidores.
-### Uso
-```bash
-# Via npx (recomendado)
-npx lib-update
-# Ou adicione ao package.json do seu projeto:
-{
-  "scripts": {
-    "lib-update": "lib-update"
-  }
-}
-# E execute:
-npm run lib-update
-```
-### O que é sincronizado
-| Arquivo/Diretório       | Descrição                                        |
-| ----------------------- | ------------------------------------------------ |
-| `docs/KNOWLEDGE.md`     | Regras críticas + mapa de módulos para IA/Lovable |
-| `.note/memory/rules/`   | Regras de schema, RLS, índices, .env             |
-### O que NÃO é sincronizado (leitura via cross-project → projeto **Admin**)
-| Recurso                     | Como acessar                                              |
-| --------------------------- | --------------------------------------------------------- |
-| Documentação de componentes | Rota `/ds` no projeto **Admin** ou cross-project          |
-| Props, exemplos, tipos      | Ler dos `*Doc.tsx` via cross-project → projeto **Admin**  |
-| Padrões de layout/CRUD      | `.note/memory/patterns/` via cross-project → **Admin**    |
-> 💡 A IA consegue ler o código-fonte do forlogic-core no projeto **Admin** via cross-project visibility.