forlogic-core 2.1.4 → 2.2.0

package/docs/design-system/patterns/header-metadata.md

@@ -1,57 +1,57 @@
-# Padrão: Título, Subtítulo e Breadcrumbs via Header (usePageMetadata)
-
-## Regra
-
-**O padrão da aplicação é exibir título, subtítulo e breadcrumbs no header** usando `usePageMetadata()`.
-
-- **NÃO** usar `BodyContent` ou `ContentContainer` com título/subtítulo internos por padrão.
-- Breadcrumbs, títulos e subtítulos internos ao conteúdo são **exceções** e devem ser usados **somente quando explicitamente solicitados**.
-
-## Uso Padrão
-
-```tsx
-import { usePageMetadata } from 'forlogic-core';
-
-export function MinhaPage() {
-  usePageMetadata({ title: 'Título', subtitle: 'Subtítulo descritivo' });
-
-  return (
-    <div className="flex flex-col h-full p-4 gap-4">
-      {/* conteúdo direto, sem BodyContent/ContentContainer */}
-    </div>
-  );
-}
-```
-
-## Com Breadcrumbs
-
-```tsx
-usePageMetadata({
-  title: 'Editar Usuário',
-  subtitle: 'Atualize os dados cadastrais',
-  breadcrumbs: [
-    { label: 'Usuários', href: '/users' },
-    { label: 'João Silva' }
-  ]
-});
-```
-
-## Subtitle com ReactNode
-
-```tsx
-usePageMetadata({
-  title: 'Detalhes',
-  subtitle: <span>Veja a <Link to="/docs">documentação</Link></span>
-});
-```
-
-## ❌ Evitar (exceto quando pedido)
-
-```tsx
-// NÃO fazer por padrão:
-<BodyContent breadcrumbs={[{ label: 'Página' }]}>
-  <ContentContainer title="Título" subtitle="Subtítulo">
-    ...
-  </ContentContainer>
-</BodyContent>
-```
+# Padrão: Título, Subtítulo e Breadcrumbs via Header (usePageMetadata)
+
+## Regra
+
+**O padrão da aplicação é exibir título, subtítulo e breadcrumbs no header** usando `usePageMetadata()`.
+
+- **NÃO** usar `BodyContent` ou `ContentContainer` com título/subtítulo internos por padrão.
+- Breadcrumbs, títulos e subtítulos internos ao conteúdo são **exceções** e devem ser usados **somente quando explicitamente solicitados**.
+
+## Uso Padrão
+
+```tsx
+import { usePageMetadata } from 'forlogic-core';
+
+export function MinhaPage() {
+  usePageMetadata({ title: 'Título', subtitle: 'Subtítulo descritivo' });
+
+  return (
+    <div className="flex flex-col h-full p-4 gap-4">
+      {/* conteúdo direto, sem BodyContent/ContentContainer */}
+    </div>
+  );
+}
+```
+
+## Com Breadcrumbs
+
+```tsx
+usePageMetadata({
+  title: 'Editar Usuário',
+  subtitle: 'Atualize os dados cadastrais',
+  breadcrumbs: [
+    { label: 'Usuários', href: '/users' },
+    { label: 'João Silva' }
+  ]
+});
+```
+
+## Subtitle com ReactNode
+
+```tsx
+usePageMetadata({
+  title: 'Detalhes',
+  subtitle: <span>Veja a <Link to="/docs">documentação</Link></span>
+});
+```
+
+## ❌ Evitar (exceto quando pedido)
+
+```tsx
+// NÃO fazer por padrão:
+<BodyContent breadcrumbs={[{ label: 'Página' }]}>
+  <ContentContainer title="Título" subtitle="Subtítulo">
+    ...
+  </ContentContainer>
+</BodyContent>
+```

package/docs/design-system/patterns/i18n-setup.md

@@ -1,117 +1,117 @@
-# Padrão: Setup de Traduções (i18n)
-
-## Arquitetura de namespaces
-
-- `core` — traduções base da lib (save, cancel, delete, etc.)
-- `app` — traduções do projeto consumidor (injetadas via `CoreProviders`)
-- Resolução: `app` → `core` → fallback `pt-BR`
-
-## Setup em projetos consumidores
-
-### Projeto simples (poucas chaves)
-
-1. Criar JSON flat em `src/i18n/pt-BR.json`: `{ "key": "value" }` (sem nesting)
-2. Passar para CoreProviders:
-
-```tsx
-<CoreProviders appTranslations={{ 'pt-BR': ptBR, 'en-US': enUS }}>
-```
-
-3. Usar `useTranslation` de `forlogic-core` (nunca de `react-i18next`)
-
-### Projeto modular (múltiplas features)
-
-Para módulos com muitas chaves, dividir traduções por feature:
-
-```text
-src/i18n/
-├── pt-BR/
-│   ├── common.json          ← chaves gerais do módulo
-│   ├── matrices.json        ← feature: matrizes
-│   ├── requirements.json    ← feature: requisitos
-│   └── reports.json         ← feature: relatórios
-├── en-US/
-│   ├── common.json
-│   ├── matrices.json
-│   ├── requirements.json
-│   └── reports.json
-└── index.ts                 ← merge automático
-```
-
-#### Arquivo `src/i18n/index.ts`
-
-```ts
-import { mergeTranslationFiles } from 'forlogic-core/i18n';
-
-import ptCommon from './pt-BR/common.json';
-import ptMatrices from './pt-BR/matrices.json';
-import ptRequirements from './pt-BR/requirements.json';
-import ptReports from './pt-BR/reports.json';
-
-import enCommon from './en-US/common.json';
-import enMatrices from './en-US/matrices.json';
-import enRequirements from './en-US/requirements.json';
-import enReports from './en-US/reports.json';
-
-export const appTranslations = {
-  'pt-BR': mergeTranslationFiles(ptCommon, ptMatrices, ptRequirements, ptReports),
-  'en-US': mergeTranslationFiles(enCommon, enMatrices, enRequirements, enReports),
-};
-```
-
-#### Uso no App
-
-```tsx
-import { CoreProviders } from 'forlogic-core';
-import { appTranslations } from './i18n';
-
-function App() {
-  return (
-    <CoreProviders appTranslations={appTranslations}>
-      <BrowserRouter><Routes /></BrowserRouter>
-    </CoreProviders>
-  );
-}
-```
-
-## Regras dos JSONs
-
-- Formato **flat** (sem nesting): `{ "key": "value" }`
-- Chaves duplicadas entre arquivos: o último spread vence (common → features)
-- Chaves do `app` sobrescrevem chaves do `core` com mesmo nome
-
-## Resolução de chaves
-
-```
-t('save')       → app: não encontra → core: "Salvar"
-t('objective')  → app: "Objetivo"
-t('save') com override no app → app: "Gravar" (sobrescreve core)
-```
-
-## Helper `mergeTranslationFiles`
-
-Utilitário exportado pela lib para facilitar o merge:
-
-```ts
-import { mergeTranslationFiles } from 'forlogic-core/i18n';
-
-const ptBR = mergeTranslationFiles(common, matrices, requirements);
-// Equivalente a: { ...common, ...matrices, ...requirements }
-```
-
-## Debug
-
-```ts
-import { i18n } from 'forlogic-core';
-console.log('Resources:', i18n.store.data);
-```
-
-## Troubleshooting
-
-| Causa | Solução |
-|-------|---------|
-| Chaves aparecem ao invés de traduções | Instalar peer deps `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, sem nesting |
-| Chave duplicada entre features | Último arquivo no merge vence |
+# Padrão: Setup de Traduções (i18n)
+
+## Arquitetura de namespaces
+
+- `core` — traduções base da lib (save, cancel, delete, etc.)
+- `app` — traduções do projeto consumidor (injetadas via `CoreProviders`)
+- Resolução: `app` → `core` → fallback `pt-BR`
+
+## Setup em projetos consumidores
+
+### Projeto simples (poucas chaves)
+
+1. Criar JSON flat em `src/i18n/pt-BR.json`: `{ "key": "value" }` (sem nesting)
+2. Passar para CoreProviders:
+
+```tsx
+<CoreProviders appTranslations={{ 'pt-BR': ptBR, 'en-US': enUS }}>
+```
+
+3. Usar `useTranslation` de `forlogic-core` (nunca de `react-i18next`)
+
+### Projeto modular (múltiplas features)
+
+Para módulos com muitas chaves, dividir traduções por feature:
+
+```text
+src/i18n/
+├── pt-BR/
+│   ├── common.json          ← chaves gerais do módulo
+│   ├── matrices.json        ← feature: matrizes
+│   ├── requirements.json    ← feature: requisitos
+│   └── reports.json         ← feature: relatórios
+├── en-US/
+│   ├── common.json
+│   ├── matrices.json
+│   ├── requirements.json
+│   └── reports.json
+└── index.ts                 ← merge automático
+```
+
+#### Arquivo `src/i18n/index.ts`
+
+```ts
+import { mergeTranslationFiles } from 'forlogic-core/i18n';
+
+import ptCommon from './pt-BR/common.json';
+import ptMatrices from './pt-BR/matrices.json';
+import ptRequirements from './pt-BR/requirements.json';
+import ptReports from './pt-BR/reports.json';
+
+import enCommon from './en-US/common.json';
+import enMatrices from './en-US/matrices.json';
+import enRequirements from './en-US/requirements.json';
+import enReports from './en-US/reports.json';
+
+export const appTranslations = {
+  'pt-BR': mergeTranslationFiles(ptCommon, ptMatrices, ptRequirements, ptReports),
+  'en-US': mergeTranslationFiles(enCommon, enMatrices, enRequirements, enReports),
+};
+```
+
+#### Uso no App
+
+```tsx
+import { CoreProviders } from 'forlogic-core';
+import { appTranslations } from './i18n';
+
+function App() {
+  return (
+    <CoreProviders appTranslations={appTranslations}>
+      <BrowserRouter><Routes /></BrowserRouter>
+    </CoreProviders>
+  );
+}
+```
+
+## Regras dos JSONs
+
+- Formato **flat** (sem nesting): `{ "key": "value" }`
+- Chaves duplicadas entre arquivos: o último spread vence (common → features)
+- Chaves do `app` sobrescrevem chaves do `core` com mesmo nome
+
+## Resolução de chaves
+
+```
+t('save')       → app: não encontra → core: "Salvar"
+t('objective')  → app: "Objetivo"
+t('save') com override no app → app: "Gravar" (sobrescreve core)
+```
+
+## Helper `mergeTranslationFiles`
+
+Utilitário exportado pela lib para facilitar o merge:
+
+```ts
+import { mergeTranslationFiles } from 'forlogic-core/i18n';
+
+const ptBR = mergeTranslationFiles(common, matrices, requirements);
+// Equivalente a: { ...common, ...matrices, ...requirements }
+```
+
+## Debug
+
+```ts
+import { i18n } from 'forlogic-core';
+console.log('Resources:', i18n.store.data);
+```
+
+## Troubleshooting
+
+| Causa | Solução |
+|-------|---------|
+| Chaves aparecem ao invés de traduções | Instalar peer deps `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, sem nesting |
+| Chave duplicada entre features | Último arquivo no merge vence |

package/docs/design-system/patterns/pagination.md

@@ -1,27 +1,27 @@
-# Padrão: Paginação
-
-**SEMPRE** usar `Pagination` ou `CrudPrimitivePagination` da lib. NUNCA implementar manualmente.
-
-```tsx
-// ❌ PROIBIDO - paginação manual
-<div className="flex gap-2">
-  <Button onClick={() => setPage(p => p - 1)}>Anterior</Button>
-  <span>Página {page}</span>
-  <Button onClick={() => setPage(p => p + 1)}>Próxima</Button>
-</div>
-
-// ✅ CORRETO - componente padronizado
-import { CrudPrimitivePagination } from 'forlogic-core';
-
-<CrudPrimitivePagination
-  currentPage={page}
-  totalPages={totalPages}
-  pageSize={pageSize}
-  totalItems={total}
-  onPageChange={setPage}
-  onPageSizeChange={setPageSize}
-  variant="full"
-/>
-```
-
-**Obrigatório**: `variant="full"` inclui seletor de itens por página e "X-Y de Z itens".
+# Padrão: Paginação
+
+**SEMPRE** usar `Pagination` ou `CrudPrimitivePagination` da lib. NUNCA implementar manualmente.
+
+```tsx
+// ❌ PROIBIDO - paginação manual
+<div className="flex gap-2">
+  <Button onClick={() => setPage(p => p - 1)}>Anterior</Button>
+  <span>Página {page}</span>
+  <Button onClick={() => setPage(p => p + 1)}>Próxima</Button>
+</div>
+
+// ✅ CORRETO - componente padronizado
+import { CrudPrimitivePagination } from 'forlogic-core';
+
+<CrudPrimitivePagination
+  currentPage={page}
+  totalPages={totalPages}
+  pageSize={pageSize}
+  totalItems={total}
+  onPageChange={setPage}
+  onPageSizeChange={setPageSize}
+  variant="full"
+/>
+```
+
+**Obrigatório**: `variant="full"` inclui seletor de itens por página e "X-Y de Z itens".

package/docs/design-system/patterns/single-scroll.md

@@ -1,39 +1,39 @@
-# Padrão: Scroll Único no Viewport
-
-O padrão de Scroll Único evita barras de rolagem duplicadas na aplicação.
-
-## Cadeia de layout do AppLayout
-
-```text
-div.h-screen.overflow-hidden          ← preso ao viewport, sem scroll
-  ├─ header (sticky top-0)            ← cabeçalho fixo
-  └─ div.sidebar-container.flex-1.overflow-hidden
-      ├─ AppSidebar                   ← sidebar com scroll próprio
-      └─ main.flex-1.overflow-hidden
-          └─ div.flex-1.min-h-0.overflow-y-auto  ← SCROLL ATIVO aqui
-              └─ BodyContent (h-full)
-                  └─ ContentContainer (overflow-visible)  ← delega scroll para cima
-```
-
-| Componente | Classes | Responsabilidade |
-|------------|---------|------------------|
-| `AppLayout` raiz | `h-screen overflow-hidden` | Prende layout ao viewport |
-| Container de conteúdo | `flex-1 min-h-0 overflow-y-auto` | Gerencia scroll da página |
-| `BodyContent` | `h-full` | Container flexível |
-| `ContentContainer` | `overflow-visible` | Delega scroll para o pai |
-
-**Regra**: Apenas UM nível da hierarquia deve ter scroll ativo — o `div.overflow-y-auto` dentro do `<main>`.
-
-```tsx
-// ❌ ERRADO - min-h-screen permite crescer além do viewport
-<div className="min-h-screen overflow-auto">
-
-// ✅ CORRETO - h-screen trava no viewport
-<div className="h-screen overflow-hidden">
-  ...
-    <div className="flex-1 min-h-0 overflow-y-auto">
-      <BodyContent>...</BodyContent>
-    </div>
-```
-
-**`min-h-0`** é essencial no container com `overflow-y-auto` — sem ele, flex items não encolhem abaixo do tamanho do conteúdo.
+# Padrão: Scroll Único no Viewport
+
+O padrão de Scroll Único evita barras de rolagem duplicadas na aplicação.
+
+## Cadeia de layout do AppLayout
+
+```text
+div.h-screen.overflow-hidden          ← preso ao viewport, sem scroll
+  ├─ header (sticky top-0)            ← cabeçalho fixo
+  └─ div.sidebar-container.flex-1.overflow-hidden
+      ├─ AppSidebar                   ← sidebar com scroll próprio
+      └─ main.flex-1.overflow-hidden
+          └─ div.flex-1.min-h-0.overflow-y-auto  ← SCROLL ATIVO aqui
+              └─ BodyContent (h-full)
+                  └─ ContentContainer (overflow-visible)  ← delega scroll para cima
+```
+
+| Componente | Classes | Responsabilidade |
+|------------|---------|------------------|
+| `AppLayout` raiz | `h-screen overflow-hidden` | Prende layout ao viewport |
+| Container de conteúdo | `flex-1 min-h-0 overflow-y-auto` | Gerencia scroll da página |
+| `BodyContent` | `h-full` | Container flexível |
+| `ContentContainer` | `overflow-visible` | Delega scroll para o pai |
+
+**Regra**: Apenas UM nível da hierarquia deve ter scroll ativo — o `div.overflow-y-auto` dentro do `<main>`.
+
+```tsx
+// ❌ ERRADO - min-h-screen permite crescer além do viewport
+<div className="min-h-screen overflow-auto">
+
+// ✅ CORRETO - h-screen trava no viewport
+<div className="h-screen overflow-hidden">
+  ...
+    <div className="flex-1 min-h-0 overflow-y-auto">
+      <BodyContent>...</BodyContent>
+    </div>
+```
+
+**`min-h-0`** é essencial no container com `overflow-y-auto` — sem ele, flex items não encolhem abaixo do tamanho do conteúdo.

package/docs/design-system/patterns/vite-tailwind-setup.md

@@ -1,48 +1,48 @@
-# Padrão: Setup Vite + Tailwind para Projetos Consumidores
-
-## Vite — Security Headers
-
-```ts
-import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
-
-export default defineConfig(({ mode }) => ({
-  plugins: [
-    react(),
-    createSecurityHeadersPlugin(mode === 'development', {
-      supabaseUrls: ['https://SEU_PROJETO.supabase.co'],
-      additionalConnectSrc: ['https://*.qualiex.com'],
-    }),
-  ],
-  resolve: {
-    alias: { '@': path.resolve(__dirname, './src') },
-  },
-  publicDir: false,
-  esbuild: { sourcemap: true, target: 'es2020' },
-  build: { chunkSizeWarningLimit: 4000 },
-}));
-```
-
-Opções do plugin: `supabaseUrls`, `trustedOrigins`, `additionalScriptSrc`, `additionalStyleSrc`, `additionalConnectSrc`, `cspReportUri`, `enableTrustedTypes` (default true), `upgradeInsecureRequests` (default true).
-
-Alternativa: `createForlogicViteConfig()` factory que retorna config completa (ver README).
-
-## Tailwind
-
-```ts
-import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
-
-export default {
-  presets: [forlogicTailwindPreset],
-  content: [...forlogicContentPaths],
-} satisfies Config;
-```
-
-`forlogicContentPaths` inclui: `./src/**/*.{ts,tsx}`, `./lib/**/*.{ts,tsx}`, `./node_modules/forlogic-core/dist/**/*.{js,ts,jsx,tsx}`, etc.
-
-## Checklist
-
-- [ ] `createSecurityHeadersPlugin` no vite.config.ts com URLs do Supabase
-- [ ] `resolve.alias` usa `path.resolve(__dirname, ...)`
-- [ ] `forlogicTailwindPreset` no tailwind.config.ts
-- [ ] `forlogicContentPaths` no content
-- [ ] Variáveis CSS definidas no index.css (--primary, --background, etc.)
+# Padrão: Setup Vite + Tailwind para Projetos Consumidores
+
+## Vite — Security Headers
+
+```ts
+import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
+
+export default defineConfig(({ mode }) => ({
+  plugins: [
+    react(),
+    createSecurityHeadersPlugin(mode === 'development', {
+      supabaseUrls: ['https://SEU_PROJETO.supabase.co'],
+      additionalConnectSrc: ['https://*.qualiex.com'],
+    }),
+  ],
+  resolve: {
+    alias: { '@': path.resolve(__dirname, './src') },
+  },
+  publicDir: false,
+  esbuild: { sourcemap: true, target: 'es2020' },
+  build: { chunkSizeWarningLimit: 4000 },
+}));
+```
+
+Opções do plugin: `supabaseUrls`, `trustedOrigins`, `additionalScriptSrc`, `additionalStyleSrc`, `additionalConnectSrc`, `cspReportUri`, `enableTrustedTypes` (default true), `upgradeInsecureRequests` (default true).
+
+Alternativa: `createForlogicViteConfig()` factory que retorna config completa (ver README).
+
+## Tailwind
+
+```ts
+import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
+
+export default {
+  presets: [forlogicTailwindPreset],
+  content: [...forlogicContentPaths],
+} satisfies Config;
+```
+
+`forlogicContentPaths` inclui: `./src/**/*.{ts,tsx}`, `./lib/**/*.{ts,tsx}`, `./node_modules/forlogic-core/dist/**/*.{js,ts,jsx,tsx}`, etc.
+
+## Checklist
+
+- [ ] `createSecurityHeadersPlugin` no vite.config.ts com URLs do Supabase
+- [ ] `resolve.alias` usa `path.resolve(__dirname, ...)`
+- [ ] `forlogicTailwindPreset` no tailwind.config.ts
+- [ ] `forlogicContentPaths` no content
+- [ ] Variáveis CSS definidas no index.css (--primary, --background, etc.)

package/docs/design-system/platform.md

@@ -29,23 +29,23 @@ Componente único multi-provider de assinatura digital com fluxo em 3 fases: Upl
 
 **Uso:**
 ```tsx
-// Uso básico — provedor resolvido automaticamente pela config da unidade
-<DocumentSigner
-  showEventLog
-  onDocumentSigned={(data) => {
-    // data.provider → 'clicksign' ou 'd4sign'
-    // data.envelope_id, data.document_id, data.signer_id, data.environment
-    console.log('Assinado:', data);
-  }}
-  onError={(error) => {
-    console.error('Erro:', error.message);
-  }}
-/>
-
-// Passando PDF programaticamente (sem upload manual)
-<DocumentSigner
-  file={meuArquivoPdf}
-  onDocumentSigned={(data) => console.log('Assinado:', data)}
+// Uso básico — provedor resolvido automaticamente pela config da unidade
+<DocumentSigner
+  showEventLog
+  onDocumentSigned={(data) => {
+    // data.provider → 'clicksign' ou 'd4sign'
+    // data.envelope_id, data.document_id, data.signer_id, data.environment
+    console.log('Assinado:', data);
+  }}
+  onError={(error) => {
+    console.error('Erro:', error.message);
+  }}
+/>
+
+// Passando PDF programaticamente (sem upload manual)
+<DocumentSigner
+  file={meuArquivoPdf}
+  onDocumentSigned={(data) => console.log('Assinado:', data)}
 />
 ```
 
@@ -78,7 +78,7 @@ import { DocumentSigner } from
 -  permite busca manual ilimitada.
 - Configuração de produção: Admin → /a/cs (aba Assinatura digital).
 
-> Fonte: `src\design-system\docs\components\SignDoc.tsx`
+> Fonte: `src/design-system/docs/components/SignDoc.tsx`
 
 ---