forlogic-core 3.0.10 → 4.0.0

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

@@ -1,117 +0,0 @@
-# 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/module-access.md

@@ -1,72 +0,0 @@
-# Module Access Guard
-
-O `ModuleAccessGuard` envolve a aplicação e bloqueia o acesso de usuários sem
-permissão no módulo (`moduleAlias`). É injetado automaticamente pelo
-`CoreProviders` quando você passa `moduleAccessGuardProps` ou usa um dos shortcuts
-abaixo.
-
-## Props relacionadas
-
-| Prop                    | Tipo                       | Default       | Descrição |
-|-------------------------|----------------------------|---------------|-----------|
-| `bypassPaths`           | `string[]`                 | `undefined`   | Rotas que ignoram o guard. Suporta glob simples no final (`/public/*`). |
-| `noAccessRedirectPath`  | `string`                   | `undefined`   | Path para onde usuários **autenticados e sem acesso** são redirecionados. |
-| `noAccessRedirectMode`  | `'always' \| 'never'`      | `'always'`    | Quando há `noAccessRedirectPath`, controla se o redirect dispara. |
-| `accessDeniedRoutes`    | `Record<string, ReactNode>`| `undefined`   | Conteúdo customizado por rota dentro da tela de bloqueio. |
-
-> O `noAccessRedirectPath` aceita path com ou sem o `:alias`. Se começar com `/`
-> e a URL atual tiver um alias na primeira posição (`/inovacao/...`), o alias é
-> prefixado automaticamente — você passa `/fe`, vira `/inovacao/fe`.
-
-## Exemplo: rota pública `/fe` + redirect pós-login
-
-Cenário do projeto Educação:
-
-- `/fe` (área do aluno) deve ser pública.
-- Usuários sem licença no módulo Educação caem por padrão na home privada
-  após o login do Qualiex — em vez de mostrar a tela de bloqueio, queremos
-  mandá-los para `/fe`.
-
-```tsx
-<CoreProviders
-  backend="dotnet"
-  associationsBaseUrl={env.QUALIEX_API}
-  moduleAccessGuardProps={{
-    bypassPaths: ['/fe', '/fe/*'],
-    noAccessRedirectPath: '/fe',
-    noAccessRedirectMode: 'always',
-  }}
-  appTranslations={{ 'pt-BR': pt }}
->
-  ...
-</CoreProviders>
-```
-
-### Tabela de comportamento
-
-| Cenário                                                         | Resultado |
-|-----------------------------------------------------------------|-----------|
-| Usuário deslogado acessa `/fe`                                  | Vê a página (precisa estar fora do `ProtectedRoute` no router do app) |
-| Usuário deslogado acessa qualquer outra rota                    | Redirect para login pelo `ProtectedRoute` |
-| Usuário logado **sem acesso** cai na home pós-login             | Redirecionado para `/fe` |
-| Usuário logado **sem acesso** digita `/turmas` na URL           | Redirecionado para `/fe` (não vê mais a tela de bloqueio) |
-| Usuário logado **com acesso** navega em qualquer rota privada   | Tudo normal |
-
-## Atenção
-
-- **`bypassPaths` ≠ rota pública**. Ele só ignora o gating do módulo. Para
-  permitir acesso anônimo (sem login), a rota também precisa ficar fora do
-  `ProtectedRoute` no router do projeto consumidor.
-- **`noAccessRedirectPath` não substitui auth**. Ele só dispara para usuários
-  já autenticados. Usuários deslogados continuam barrados pelo `ProtectedRoute`.
-- O guard evita loops: se o destino do redirect for igual ao pathname atual,
-  os children são renderizados (combine com `bypassPaths` para liberar o destino).
-
-## Combinações comuns
-
-| Objetivo                                                       | Configuração |
-|----------------------------------------------------------------|--------------|
-| Liberar uma rota pública sem mexer no comportamento padrão     | `bypassPaths: ['/publico/*']` |
-| Mandar quem não tem licença para uma landing interna           | `noAccessRedirectPath: '/sem-acesso'` |
-| Liberar landing + redirecionar todo o resto para ela           | `bypassPaths: ['/fe', '/fe/*']` + `noAccessRedirectPath: '/fe'` |
-| Manter UI de bloqueio (comportamento legado)                   | Nenhuma das duas props |

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

@@ -1,27 +0,0 @@
-# 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 +0,0 @@
-# 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,49 +0,0 @@
-# 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.)
-- [ ] `VITE_SUPABASE_PK_OVERRIDE` no `.env` com a publishable key correta (ver `feature-flags.md`)

package/docs/design-system/platform.md

@@ -1,55 +0,0 @@
-<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
-<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
-
-# Plataforma
-
-Categoria: **Plataforma** | 6 componentes
-
-### Autenticação (Auth)
-
-*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
-
----
-
-### Alias via URL
-
-*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
-
----
-
-### Acesso Módulo (ModuleAccess)
-
-*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
-
----
-
-### D4Sign — Teste de Webhook
-
-Página interna de QA para validar o round-trip: criação de envelope D4Sign → registro do webhook → assinatura no iframe embedded → recebimento do callback via Realtime em common.sign_documents. Use antes de publicar uma nova versão da lib para o Educação.
-
-**Uso:**
-```tsx
-<D4SignWebhookTester />
-
-// Requisitos:
-// 1. Usuário autenticado (alias ativo)
-// 2. sign_configs do alias com provider = 'd4sign'
-// 3. Edge functions \`d4sign\` e \`d4sign-webhook\` deployadas
-// 4. Realtime habilitado em common.sign_documents
-```
-
-> Fonte: `src\design-system\docs\components\D4SignTestDoc.tsx`
-
----
-
-### Segurança (Vite Config)
-
-*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
-
----
-
-### Environments (Config)
-
-*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
-
----