forlogic-core 1.10.2 → 1.11.0

package/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,105 @@ VITE_IS_QUALIEX=true
 
 ---
 
+## 🚀 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
+
+---
+
 <!-- AUTO_GENERATED_START -->
 
 ### 📚 Estatísticas da Documentação