forlogic-core 1.10.3 → 1.11.1

package/dist/README.md

@@ -14,6 +14,11 @@ A biblioteca `forlogic-core` requer as seguintes **peer dependencies** instalada
 # 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
@@ -22,6 +27,20 @@ npm install forlogic-core
 
 **Nota**: O npm/yarn irá alertar automaticamente se alguma peer dependency estiver faltando ou com versão incompatível.
 
+### ⚠️ 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`.
+
 ---
 
 ## 🤖 REGRAS CRÍTICAS
@@ -187,6 +206,277 @@ CREATE INDEX idx_processes_title ON processes.processes(title);
 
 ---
 
+## ⚙️ 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.
+
+### 📦 Instalação
+
+As configurações estão disponíveis via subpaths do pacote:
+
+```typescript
+// Configurações Vite
+import { createSecurityHeadersPlugin, createForlogicViteConfig } from 'forlogic-core/vite';
+
+// Preset Tailwind
+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 }) => {
+  const isDev = mode === 'development';
+
+  return {
+    plugins: [
+      react(),
+      createSecurityHeadersPlugin(isDev, {
+        // 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 adicionais
+        additionalScriptSrc: [
+          'https://cdn.analytics.com',
+        ],
+        
+        // CDNs de estilos adicionais
+        additionalStyleSrc: [
+          'https://fonts.custom.com',
+        ],
+        
+        // URI para reportar violações CSP
+        cspReportUri: 'https://seu-projeto.supabase.co/functions/v1/csp-report',
+        
+        // Habilitar Trusted Types em produção (default: true)
+        enableTrustedTypes: true,
+        
+        // Upgrade HTTP para HTTPS em produção (default: true)
+        upgradeInsecureRequests: true,
+      }),
+    ],
+  };
+});
+```
+
+#### Opções do Plugin
+
+| Opção | Tipo | Padrão | Descrição |
+|-------|------|--------|-----------|
+| `supabaseUrls` | `string[]` | `[]` | URLs do Supabase para permitir conexões |
+| `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 |
+| `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 completa padronizada:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react-swc';
+import { createForlogicViteConfig } from 'forlogic-core/vite';
+
+// Cria configuração com opções personalizadas
+const forlogicConfig = createForlogicViteConfig({
+  srcAlias: '@',           // Alias para ./src
+  libAlias: 'forlogic-core', // Alias para ./lib (desenvolvimento local)
+  security: {
+    supabaseUrls: ['https://seu-projeto.supabase.co'],
+    trustedOrigins: ['https://meu-app.com'],
+  },
+  server: {
+    host: '::',
+    port: 8080,
+  },
+  build: {
+    chunkSizeWarningLimit: 4000,
+  },
+});
+
+export default defineConfig(({ mode }) => {
+  const config = forlogicConfig(mode === 'development');
+  
+  return {
+    ...config,
+    plugins: [
+      react(),
+      ...config.plugins,
+    ],
+  };
+});
+```
+
+---
+
+### 🎨 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.
@@ -218,6 +508,150 @@ VITE_IS_QUALIEX=true
 
 ---
 
+## 🌐 Setup de Traduções para Projetos Consumidores
+
+O sistema de internacionalização (i18n) do `forlogic-core` carrega traduções dinamicamente do banco de dados Supabase. Para que funcione corretamente em projetos consumidores, siga os passos abaixo.
+
+### Requisitos
+
+| Requisito | Descrição |
+|-----------|-----------|
+| `VITE_SUPABASE_URL` | URL do projeto Supabase (mesma instância que contém `common.translations`) |
+| `VITE_SUPABASE_PUBLISHABLE_KEY` | Chave pública (anon key) do Supabase |
+| `i18next` | Peer dependency instalada |
+| `react-i18next` | Peer dependency instalada |
+| Tabela `common.translations` | Deve existir no Supabase com RLS pública para SELECT |
+
+### Passo 1: Instalar Peer Dependencies
+
+```bash
+npm install i18next@^25.0.0 react-i18next@^16.0.0
+```
+
+### Passo 2: Configurar Variáveis de Ambiente
+
+No arquivo `.env` do projeto consumidor:
+
+```env
+# Deve apontar para a mesma instância Supabase que contém common.translations
+VITE_SUPABASE_URL=https://seu-projeto.supabase.co
+VITE_SUPABASE_PUBLISHABLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+### Passo 3: Aguardar i18n Inicializar no main.tsx
+
+**⚠️ CRÍTICO**: O `main.tsx` deve aguardar o i18n carregar as traduções antes de renderizar a aplicação.
+
+```tsx
+// src/main.tsx
+import { createRoot } from 'react-dom/client';
+import { i18n } from 'forlogic-core';
+import App from './App';
+import './index.css';
+
+const renderApp = () => {
+  createRoot(document.getElementById("root")!).render(<App />);
+};
+
+// ✅ Aguardar i18n inicializar antes de renderizar
+if (i18n.isInitialized) {
+  renderApp();
+} else {
+  i18n.on('initialized', renderApp);
+}
+```
+
+**❌ ERRADO** - Renderizar sem aguardar (mostrará apenas chaves):
+
+```tsx
+// ❌ NÃO FAÇA ISSO - traduções não estarão prontas
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+### Passo 4: Usar CoreProviders no App.tsx
+
+```tsx
+// src/App.tsx
+import { CoreProviders } from 'forlogic-core';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <CoreProviders>
+      <BrowserRouter>
+        <Routes>
+          {/* Suas rotas */}
+        </Routes>
+      </BrowserRouter>
+    </CoreProviders>
+  );
+}
+
+export default App;
+```
+
+### Passo 5: Usar useTranslation do forlogic-core
+
+```tsx
+// ❌ ERRADO - Cria instância separada
+import { useTranslation } from 'react-i18next';
+
+// ✅ CORRETO - Usa mesma instância configurada
+import { useTranslation } from 'forlogic-core';
+
+function MeuComponente() {
+  const { t } = useTranslation();
+  return <h1>{t('minha.chave')}</h1>;
+}
+```
+
+### Troubleshooting
+
+#### Traduções mostram apenas as chaves (ex: `common.save` ao invés de "Salvar")
+
+| Causa | Solução |
+|-------|---------|
+| `main.tsx` não aguarda i18n | Adicionar verificação `i18n.isInitialized` conforme Passo 3 |
+| Peer dependencies faltando | Instalar `i18next` e `react-i18next` |
+| Variáveis de ambiente incorretas | Verificar `VITE_SUPABASE_URL` e `VITE_SUPABASE_PUBLISHABLE_KEY` |
+| Supabase diferente | Verificar se aponta para a mesma instância com `common.translations` |
+| Import de `react-i18next` direto | Usar import de `forlogic-core` |
+
+#### Debug: Verificar se traduções foram carregadas
+
+```tsx
+import { i18n } from 'forlogic-core';
+
+// No console
+console.log('i18n initialized:', i18n.isInitialized);
+console.log('Current language:', i18n.language);
+console.log('Loaded resources:', i18n.store.data);
+```
+
+#### Habilitar modo debug
+
+Adicione no `.env`:
+
+```env
+VITE_I18N_DEBUG_MODE=true
+```
+
+Com debug ativo, chaves traduzidas aparecem como `[chave ✅]` e chaves não encontradas como `[⚠️ chave]`.
+
+### Checklist de Configuração
+
+```markdown
+- [ ] Instalou `i18next@^25.0.0` e `react-i18next@^16.0.0`?
+- [ ] Configurou `VITE_SUPABASE_URL` apontando para a instância correta?
+- [ ] Configurou `VITE_SUPABASE_PUBLISHABLE_KEY`?
+- [ ] O `main.tsx` aguarda `i18n.isInitialized` antes de renderizar?
+- [ ] O `App.tsx` usa `CoreProviders`?
+- [ ] Todos os imports de `useTranslation` são de `forlogic-core`?
+- [ ] A tabela `common.translations` existe e tem RLS pública para SELECT?
+```
+
+---
+
 ## 🚀 Quick Setup: CoreProviders
 
 O `CoreProviders` é um componente que encapsula todos os providers essenciais da biblioteca, simplificando drasticamente a configuração de novos projetos.