forlogic-core 2.2.5 → 2.2.7

package/docs/design-system/patterns/feature-flags.md

@@ -1,81 +1,81 @@
-# Padrão: Feature Flags (Variáveis de Ambiente)
-
-## Variáveis disponíveis
-
-| Variável | Descrição | Padrão |
-|----------|-----------|--------|
-| `VITE_SHOW_USER_PREFERENCES` | Exibe "Preferências" no menu do usuário (idioma, timezone, formato de data) | Não exibe |
-| `VITE_I18N_DEBUG_MODE` | Modo debug de i18n (mostra chaves ao invés de traduções) | `"false"` |
-| `VITE_IS_QUALIEX` | Usa logos Qualiex ao invés de Forlogic | `"false"` |
-| `VITE_SHOW_EDIT_PROFILE` | Exibe "Editar Perfil" no menu do usuário (foto e idioma) | Não exibe |
-| `VITE_WIKI_URL` | Exibe botão "Wiki" no header da aplicação. O valor é a URL que será aberta ao clicar | Não exibe |
-| `VITE_SHOW_ADMIN_REPORTS` | Exibe relatórios administrativos | `"false"` |
-| `VITE_SUPABASE_PK_OVERRIDE` | **Obrigatória.** Publishable key correta do Supabase. Ver [seção abaixo](#vite_supabase_pk_override). | — |
-
-## Uso
-
-```env
-VITE_SHOW_USER_PREFERENCES=true
-VITE_I18N_DEBUG_MODE=false
-VITE_IS_QUALIEX=true
-VITE_WIKI_URL=https://wiki.example.com
-VITE_SHOW_ADMIN_REPORTS=false
-VITE_SUPABASE_PK_OVERRIDE="sb_publishable_w-TKU0hE4bjM_uOgt3fK1g_ewrXKJ8J"
-```
-
-Variáveis Vite precisam do prefixo `VITE_` para serem expostas ao cliente.
-
----
-
-## `VITE_SUPABASE_PK_OVERRIDE`
-
-### Problema
-
-O Supabase desativou as legacy API keys (formato JWT `eyJhbGci...`). A integração Supabase do Lovable **sobrescreve automaticamente** `VITE_SUPABASE_PUBLISHABLE_KEY` no `.env` com a legacy anon key a cada prompt, causando `401 Unauthorized` em todas as requests.
-
-### Solução
-
-A lib `forlogic-core` implementa um mecanismo de override:
-
-1. Se `VITE_SUPABASE_PK_OVERRIDE` existir no `.env` → a lib usa essa key (ignora `VITE_SUPABASE_PUBLISHABLE_KEY`)
-2. Se não existir → usa `VITE_SUPABASE_PUBLISHABLE_KEY` normalmente
-3. Se a key ativa for uma JWT legada → exibe banner vermelho no preview (DEV) + erro no console
-
-O Lovable **nunca toca** em `VITE_SUPABASE_PK_OVERRIDE` porque só auto-popula estas 3 variáveis:
-- `VITE_SUPABASE_URL`
-- `VITE_SUPABASE_PUBLISHABLE_KEY`
-- `VITE_SUPABASE_PROJECT_ID`
-
-### Configuração obrigatória
-
-**Todo projeto consumidor** que aponta para o Supabase `ccjfvpnndclajkleyqkc` deve adicionar no `.env`:
-
-```env
-VITE_SUPABASE_PK_OVERRIDE="sb_publishable_w-TKU0hE4bjM_uOgt3fK1g_ewrXKJ8J"
-```
-
-### Como funciona internamente
-
-```text
-VITE_SUPABASE_PK_OVERRIDE existe?
-  ├─ SIM → usar ela (ignora VITE_SUPABASE_PUBLISHABLE_KEY)
-  │        console.info: "✅ Usando VITE_SUPABASE_PK_OVERRIDE..."
-  └─ NÃO → usar VITE_SUPABASE_PUBLISHABLE_KEY
-       ├─ Formato sb_publishable_* → OK
-       └─ Formato eyJ* (JWT legada) → ⛔ Erro
-            ├─ console.error com diagnóstico completo
-            └─ Banner vermelho fixo no topo (apenas DEV)
-```
-
-### Arquivos relevantes na lib
-
-| Arquivo | Responsabilidade |
-|---------|-----------------|
-| `lib/supabase/legacyKeyGuard.ts` | `resolvePublishableKey()`, `isLegacyAnonKey()`, `warnIfLegacyKey()` |
-| `lib/supabase/SupabaseSingleton.ts` | Usa `resolvePublishableKey()` para a key do client |
-| `lib/supabase/publicClient.ts` | Idem para o client público |
-| `lib/providers/CoreProviders.tsx` | Renderiza `LegacyKeyBanner` em DEV |
-
-### ⚠️ Nunca remova esta variável do `.env`
-
-Mesmo que o Lovable corrija a integração no futuro, a presença do override não causa nenhum efeito colateral negativo — é um fallback seguro.
+# Padrão: Feature Flags (Variáveis de Ambiente)
+
+## Variáveis disponíveis
+
+| Variável | Descrição | Padrão |
+|----------|-----------|--------|
+| `VITE_SHOW_USER_PREFERENCES` | Exibe "Preferências" no menu do usuário (idioma, timezone, formato de data) | Não exibe |
+| `VITE_I18N_DEBUG_MODE` | Modo debug de i18n (mostra chaves ao invés de traduções) | `"false"` |
+| `VITE_IS_QUALIEX` | Usa logos Qualiex ao invés de Forlogic | `"false"` |
+| `VITE_SHOW_EDIT_PROFILE` | Exibe "Editar Perfil" no menu do usuário (foto e idioma) | Não exibe |
+| `VITE_WIKI_URL` | Exibe botão "Wiki" no header da aplicação. O valor é a URL que será aberta ao clicar | Não exibe |
+| `VITE_SHOW_ADMIN_REPORTS` | Exibe relatórios administrativos | `"false"` |
+| `VITE_SUPABASE_PK_OVERRIDE` | **Obrigatória.** Publishable key correta do Supabase. Ver [seção abaixo](#vite_supabase_pk_override). | — |
+
+## Uso
+
+```env
+VITE_SHOW_USER_PREFERENCES=true
+VITE_I18N_DEBUG_MODE=false
+VITE_IS_QUALIEX=true
+VITE_WIKI_URL=https://wiki.example.com
+VITE_SHOW_ADMIN_REPORTS=false
+VITE_SUPABASE_PK_OVERRIDE="sb_publishable_w-TKU0hE4bjM_uOgt3fK1g_ewrXKJ8J"
+```
+
+Variáveis Vite precisam do prefixo `VITE_` para serem expostas ao cliente.
+
+---
+
+## `VITE_SUPABASE_PK_OVERRIDE`
+
+### Problema
+
+O Supabase desativou as legacy API keys (formato JWT `eyJhbGci...`). A integração Supabase do Lovable **sobrescreve automaticamente** `VITE_SUPABASE_PUBLISHABLE_KEY` no `.env` com a legacy anon key a cada prompt, causando `401 Unauthorized` em todas as requests.
+
+### Solução
+
+A lib `forlogic-core` implementa um mecanismo de override:
+
+1. Se `VITE_SUPABASE_PK_OVERRIDE` existir no `.env` → a lib usa essa key (ignora `VITE_SUPABASE_PUBLISHABLE_KEY`)
+2. Se não existir → usa `VITE_SUPABASE_PUBLISHABLE_KEY` normalmente
+3. Se a key ativa for uma JWT legada → exibe banner vermelho no preview (DEV) + erro no console
+
+O Lovable **nunca toca** em `VITE_SUPABASE_PK_OVERRIDE` porque só auto-popula estas 3 variáveis:
+- `VITE_SUPABASE_URL`
+- `VITE_SUPABASE_PUBLISHABLE_KEY`
+- `VITE_SUPABASE_PROJECT_ID`
+
+### Configuração obrigatória
+
+**Todo projeto consumidor** que aponta para o Supabase `ccjfvpnndclajkleyqkc` deve adicionar no `.env`:
+
+```env
+VITE_SUPABASE_PK_OVERRIDE="sb_publishable_w-TKU0hE4bjM_uOgt3fK1g_ewrXKJ8J"
+```
+
+### Como funciona internamente
+
+```text
+VITE_SUPABASE_PK_OVERRIDE existe?
+  ├─ SIM → usar ela (ignora VITE_SUPABASE_PUBLISHABLE_KEY)
+  │        console.info: "✅ Usando VITE_SUPABASE_PK_OVERRIDE..."
+  └─ NÃO → usar VITE_SUPABASE_PUBLISHABLE_KEY
+       ├─ Formato sb_publishable_* → OK
+       └─ Formato eyJ* (JWT legada) → ⛔ Erro
+            ├─ console.error com diagnóstico completo
+            └─ Banner vermelho fixo no topo (apenas DEV)
+```
+
+### Arquivos relevantes na lib
+
+| Arquivo | Responsabilidade |
+|---------|-----------------|
+| `lib/supabase/legacyKeyGuard.ts` | `resolvePublishableKey()`, `isLegacyAnonKey()`, `warnIfLegacyKey()` |
+| `lib/supabase/SupabaseSingleton.ts` | Usa `resolvePublishableKey()` para a key do client |
+| `lib/supabase/publicClient.ts` | Idem para o client público |
+| `lib/providers/CoreProviders.tsx` | Renderiza `LegacyKeyBanner` em DEV |
+
+### ⚠️ Nunca remova esta variável do `.env`
+
+Mesmo que o Lovable corrija a integração no futuro, a presença do override não causa nenhum efeito colateral negativo — é um fallback seguro.

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.