forlogic-core 1.16.3 → 1.16.5

package/README.md

@@ -75,16 +75,16 @@ A `forlogic-core` é a **biblioteca central** de componentes, serviços e utilit
 
 ```typescript
 // ✅ Sempre importe da forlogic-core
-import { 
-  Button, 
-  Input, 
-  Dialog, 
+import {
+  Button,
+  Input,
+  Dialog,
   Combobox,
   SplitButton,
   RichTextEditor,
   createCrudPage,
   cn,
-  formatDatetime 
+  formatDatetime
 } from 'forlogic-core';
 ```
 
@@ -100,21 +100,21 @@ 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 |
+| 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` | Baixa documentação atualizada |
+| 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`                  | Baixa documentação atualizada                       |
 
 ### ⚠️ Exceções (quando PODE criar localmente)
 
@@ -309,6 +309,7 @@ import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tail
 ### 🔒 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.
@@ -349,27 +350,27 @@ export default defineConfig(({ mode }) => ({
         '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,
@@ -380,17 +381,17 @@ export default defineConfig(({ mode }) => ({
 
 #### 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 |
+| 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          |
 
 ---
 
@@ -417,7 +418,7 @@ const forlogicConfig = createForlogicViteConfig({
 export default defineConfig(({ mode }) => {
   const isDev = mode === 'development';
   const baseConfig = forlogicConfig(isDev);
-  
+
   return {
     ...baseConfig,
     plugins: [react(), ...baseConfig.plugins],
@@ -454,12 +455,12 @@ export default defineConfig(({ mode }) => {
       host: '::',
       port: 8080,
     },
-    
+
     // Força re-bundle quando atualizar forlogic-core
     optimizeDeps: {
       force: true,
     },
-    
+
     plugins: [
       react(),
       // Headers de segurança (CSP, CORS, etc.)
@@ -476,21 +477,21 @@ export default defineConfig(({ mode }) => {
           : '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,
     },
@@ -530,6 +531,7 @@ export default defineConfig(({ mode }) => ({
 ### 🎨 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
@@ -646,11 +648,11 @@ A biblioteca suporta feature flags para habilitar/desabilitar funcionalidades op
 
 ### Variáveis Disponíveis
 
-| Variável | Descrição | Valores | Padrão |
-|----------|-----------|---------|--------|
+| 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"` |
+| `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
 
@@ -677,13 +679,13 @@ O sistema de internacionalização (i18n) do `forlogic-core` carrega traduções
 
 ### 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 |
+| 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
 
@@ -772,13 +774,13 @@ function MeuComponente() {
 
 #### 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` |
+| 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
 
@@ -823,14 +825,14 @@ O `CoreProviders` é um componente que encapsula todos os providers essenciais d
 
 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 |
+| 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
 
@@ -883,10 +885,10 @@ function App() {
 
 ### 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 |
+| 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
 
@@ -920,12 +922,12 @@ O `SidebarActionTrigger` permite adicionar ações principais de módulo no side
 
 ### 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 |
+| 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
 
@@ -935,27 +937,27 @@ 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-item',
+        label: 'Novo Item',
+        icon: FileText,
+        onClick: () => openCreateDialog()
       },
-      { 
-        id: 'create-folder', 
-        label: 'Nova Pasta', 
-        icon: Folder, 
-        onClick: () => openFolderDialog() 
+      {
+        id: 'create-folder',
+        label: 'Nova Pasta',
+        icon: Folder,
+        onClick: () => openFolderDialog()
       },
     ]
   },
-  
+
   // Navegação
   navigation: [
     { label: 'Visão Geral', path: '/', icon: Home },
@@ -968,20 +970,20 @@ const sidebarConfig: 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 |
+| 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 |
+| 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
 
@@ -1023,7 +1025,7 @@ import { CoreProviders, ModalStateProvider, useModalState } from 'forlogic-core'
 // Em componentes com modal
 function MeuDialog({ open, onOpenChange }) {
   const { registerModal, unregisterModal } = useModalState();
-  
+
   useEffect(() => {
     if (open) {
       registerModal('meu-dialog');
@@ -1031,7 +1033,7 @@ function MeuDialog({ open, onOpenChange }) {
       unregisterModal('meu-dialog');
     }
   }, [open]);
-  
+
   return <Dialog open={open} onOpenChange={onOpenChange}>...</Dialog>;
 }
 ```
@@ -1039,11 +1041,13 @@ function MeuDialog({ open, onOpenChange }) {
 ### 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)
@@ -1071,11 +1075,11 @@ npm run pull-docs
 
 ### O que é sincronizado
 
-| Arquivo | Descrição |
-|---------|-----------|
-| `docs/FORLOGIC_CORE_README.md` | README completo da biblioteca |
-| `docs/DESIGN_SYSTEM.md` | Documentação do Design System |
-| `docs/KNOWLEDGE.md` | Knowledge base para IA/Lovable |
+| Arquivo                        | Descrição                      |
+| ------------------------------ | ------------------------------ |
+| `docs/FORLOGIC_CORE_README.md` | README completo da biblioteca  |
+| `docs/DESIGN_SYSTEM.md`        | Documentação do Design System  |
+| `docs/KNOWLEDGE.md`            | Knowledge base para IA/Lovable |
 
 ### Benefícios
 
@@ -1149,7 +1153,7 @@ O comando usa credenciais públicas do Supabase do forlogic-core e não requer c
 - [Loading](./docs/DESIGN_SYSTEM.md#skeleton) - Componentes para estados de carregamento: Skeleton (placeholders), Spinner (indicador de loading), e LoadingState (gerenciamento declarativo).
 - [Media](./docs/DESIGN_SYSTEM.md#media) - Módulo completo para upload, edição e renderização de imagens e vídeos. Inclui editores interativos, renderizadores otimizados e hook genérico de upload.
 - [Menubar](./docs/DESIGN_SYSTEM.md#menubar) - Barra de menu horizontal com submenus, checkboxes e radio items. Ideal para barras de navegação de aplicações desktop-like, seguindo padrões de aplicações nativas.
-- [ModulesDialog](./docs/DESIGN_SYSTEM.md#modulesdialog) - Dialog para navegação entre módulos do sistema, organizado em abas (Qualiex, Clássicos) com separação entre módulos contratados e disponíveis, OnboardingDialog para descoberta e cards informativos no rodapé.
+- [ModulesDialog](./docs/DESIGN_SYSTEM.md#modulesdialog) - Dialog para navegação entre módulos do sistema.
 - [Navigation Menu](./docs/DESIGN_SYSTEM.md#navigationmenu) - Uma coleção de links para navegação em websites.
 - [Onboarding Dialog](./docs/DESIGN_SYSTEM.md#onboardingdialog) - Componente para fluxos de onboarding em múltiplos passos. Suporta imagens estáticas, GIFs, navegação entre steps e indicador de progresso com dropdown.
 - [Pagination](./docs/DESIGN_SYSTEM.md#pagination) - Componente de paginação padronizado com layout de 3 colunas, seletor de itens por página e navegação completa.
@@ -1197,7 +1201,7 @@ O comando usa credenciais públicas do Supabase do forlogic-core e não requer c
 - [ErrorBoundary](./docs/DESIGN_SYSTEM.md#errorboundary) - Componente de classe React que captura erros de renderização em componentes filhos, evitando que a aplicação inteira quebre.
 - [Hooks](./docs/DESIGN_SYSTEM.md#hooks) - Hooks utilitários da biblioteca forlogic-core para otimização, dados, formatação e UI. Todos os hooks seguem padrões React e são compatíveis com React Query quando aplicável.
 - [Internacionalização (i18n)](./docs/DESIGN_SYSTEM.md#i18n) - Sistema de internacionalização usando react-i18next com traduções carregadas de um arquivo JSON estático local (lib/i18n/translations.json). Suporta pt-BR, en-US e es-ES com gerenciamento de preferências do usuário.
-- [Controle de Acesso a Módulos](./docs/DESIGN_SYSTEM.md#moduleaccess) - Sistema para verificar e bloquear automaticamente o acesso do usuário a módulos da plataforma Qualiex. Inclui proteção automática de rotas via CoreProviders e hook para verificações programáticas.
+- [Acesso Módulo (ModuleAccess)](./docs/DESIGN_SYSTEM.md#moduleaccess) - Sistema de autorização para verificar e bloquear acesso a módulos da plataforma Qualiex. Proteção automática de rotas via CoreProviders e hook para verificações programáticas.
 - [Segurança (Vite Config)](./docs/DESIGN_SYSTEM.md#security) - Plugin de segurança para Vite que aplica headers OWASP, CSP configurável, CORS seguro e proteções contra ataques comuns. Configuração centralizada para todos os projetos Forlogic.
 - [Services](./docs/DESIGN_SYSTEM.md#services) - Serviços utilitários da biblioteca forlogic-core para operações CRUD, envio de emails, tratamento de erros e gerenciamento de traduções. Todos os serviços são singletons prontos para uso.
 - [Utilities](./docs/DESIGN_SYSTEM.md#utilities) - Funções utilitárias essenciais exportadas pela biblioteca para manipulação de classes CSS, formatação de datas e valores monetários.
@@ -1206,4 +1210,4 @@ O comando usa credenciais públicas do Supabase do forlogic-core e não requer c
 
 > 📘 **Documentação Completa**: Para ver detalhes de props, exemplos de uso e acessibilidade de cada componente, consulte o [Design System Completo](./docs/DESIGN_SYSTEM.md).
 
-<!-- AUTO_GENERATED_END -->
+<!-- AUTO_GENERATED_END -->