forlogic-core 3.0.11 → 4.0.0

package/docs/WORKSPACE_KNOWLEDGE.md

@@ -1,189 +0,0 @@
-# forlogic-core — Workspace Knowledge
-
-> **Documento para colar no Lovable Workspace Knowledge** de projetos consumidores.
-> Funciona como mapa de referências cruzadas entre os projetos.
-
----
-
-## Projetos do Ecossistema
-
-| Projeto | Alias | Responsabilidade |
-|---------|-------|-----------------|
-| **forlogic-docs** | `@forlogic-docs` | Fonte canônica de regras, padrões, templates e documentação |
-| **qualiex-admin** | `@Admin` | Código-fonte da lib `forlogic-core`, Design System e docs gerados |
-
----
-
-## Onde buscar cada informação
-
-### Regras e Padrões → `@forlogic-docs`
-
-| O que | Caminho |
-|-------|---------|
-| Constituição (regras canônicas) | `docs/engenharia/padroes/constitution.md` |
-| Guia de migração de ícones | `docs/engenharia/padroes/icon-migration.md` |
-| Guia de publicação da lib | `docs/engenharia/devops/publish.md` |
-| Prompt: auditoria | `docs/templates/prompts/audit.md` |
-| Prompt: criação de tela | `docs/templates/prompts/new-screen.md` |
-| Prompt: starter template | `docs/templates/prompts/starter.md` |
-| ADRs (decisões de arquitetura) | `docs/adrs/` |
-| Specs de API | `docs/apis/` |
-
-### Código-fonte e Design System → `@Admin`
-
-| O que | Caminho |
-|-------|---------|
-| Código dos componentes UI | `lib/components/ui/` |
-| Sistema CRUD | `lib/crud/` |
-| Barrel exports (lista completa) | `lib/exports/ui.ts`, `lib/exports/index.ts` |
-| Documentação MD do Design System | `docs/design-system/` |
-| Golden snippets (exemplos) | `docs/design-system/examples.md` |
-| Docs interativos (código-fonte) | `src/design-system/docs/` |
-| Hooks compartilhados | `lib/hooks/` |
-| Providers (CoreProviders) | `lib/providers/` |
-| Serviços (Base, Email, Error) | `lib/services/` |
-| Config Vite/Tailwind | `lib/vite/`, `lib/tailwind/` |
-| Spec do módulo Queries | `spec/queries.md` |
-| Inventário de Supabase Storage | `docs/STORAGE_BUCKETS.md` |
-| **Guardrails de Segurança (normativo)** | **`docs/SECURITY.md`** |
-| **Tokens Qualiex (access + id, claims, headers)** | **`lib/auth/TOKENS.md`** |
-
----
-
-## Schema do Projeto
-
-> ⚠️ **O schema é definido no `README.md` de cada projeto consumidor.** Consulte-o antes de qualquer query.
-
-```ts
-// ✅ CORRETO — substituir pelo schema do projeto
-supabase.schema('SCHEMA_DO_PROJETO').from('tabela').select('*');
-
-// ❌ ERRADO
-supabase.from('tabela').select('*');
-```
-
----
-
-## Regras Invioláveis (resumo)
-
-> Fonte canônica: `@forlogic-docs docs/engenharia/padroes/constitution.md`
-
-| Regra | Detalhe |
-|-------|---------|
-| Schema obrigatório | `.schema('...')` em toda query Supabase |
-| Sem DELETE físico | Soft delete com `deleted_at` |
-| **Sem acesso anon** | RLS policies devem usar `TO authenticated` — **nunca** conceder acesso ao role `anon` sem justificativa documentada |
-| Lib-first | Usar `forlogic-core` antes de criar componente |
-| Import do Supabase | `getSupabaseClient()` de `forlogic-core` |
-| Import de i18n | `useTranslation` de `forlogic-core`, nunca de `react-i18next` |
-| Sem hardcoded admin | Nunca localStorage/sessionStorage para roles |
-| **PK Override** | `VITE_SUPABASE_PK_OVERRIDE` **obrigatória** no `.env` quando `backend="supabase"` — nunca remover. Ver `@Admin docs/design-system/patterns/feature-flags.md` |
-
----
-
-## Backend opcional (Supabase)
-
-> Detalhes: `@Admin docs/design-system/patterns/core-providers.md` (seção "Backend (Supabase opcional)").
-
-`CoreProviders` aceita a prop `backend`:
-
-| Modo | Quando usar | Envs exigidas |
-|------|-------------|---------------|
-| `'supabase'` (default) | App usa tabelas/edge functions do Supabase | `SUPABASE_URL` + `SUPABASE_PUBLISHABLE_KEY` (ou `VITE_SUPABASE_*` legadas — consolidadas pelo `resolveSupabaseEnv()` no `vite.config.ts`) + `VITE_SUPABASE_PK_OVERRIDE` |
-| `'dotnet'` | App consome apenas a API .NET do Qualiex (ex.: Documentos) | nenhuma do Supabase |
-
-```tsx
-<CoreProviders backend="dotnet" appTranslations={{ 'pt-BR': pt }}>
-  <BrowserRouter>...</BrowserRouter>
-</CoreProviders>
-```
-
-### Subpaths obrigatórios (breaking change)
-
-Os módulos abaixo **foram removidos do barrel principal** e só podem ser importados via subpath. Eles continuam exigindo Supabase em runtime:
-
-| Módulo | Import |
-|--------|--------|
-| Assinatura digital | `import { DocumentSigner } from 'forlogic-core/sign'` |
-| Trilha de auditoria | `import { AuditTrailPage } from 'forlogic-core/audit-trail'` |
-| Planos de ação | `import { ... } from 'forlogic-core/action-plans'` |
-| Liderança | `import { ... } from 'forlogic-core/leadership'` |
-| UO / Places | `import { ... } from 'forlogic-core/places'` |
-
-Use `isSupabaseConfigured()` para checar disponibilidade antes de instanciar o cliente Supabase em código condicional.
-
-### Política de acesso `anon` no Supabase
-
-**Por padrão, nenhuma tabela, function ou storage policy deve conceder acesso ao role `anon`.**
-
-Todas as policies devem usar `TO authenticated` e validar o JWT do tenant:
-
-```sql
--- ✅ CORRETO
-CREATE POLICY "select" ON schema.tabela
-FOR SELECT TO authenticated
-USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
-
--- ❌ ERRADO — nunca usar anon
-CREATE POLICY "select" ON schema.tabela
-FOR SELECT TO anon, authenticated
-USING (true);
-```
-
-**Exceções são permitidas apenas quando:**
-
-1. A funcionalidade é **intencionalmente pública** (ex: validação de certificado, página de candidatura externa)
-2. A exceção está **documentada na migration SQL** com comentário `-- ANON: <motivo>`
-3. A exceção está **registrada no `@security-memory`** do projeto
-
-**Funções `SECURITY DEFINER`:** por padrão, revogar permissão de `anon`:
-
-```sql
-REVOKE EXECUTE ON FUNCTION schema.minha_funcao FROM anon;
--- Manter apenas authenticated
-GRANT EXECUTE ON FUNCTION schema.minha_funcao TO authenticated;
-```
-
----
-
-## Design System — Categorias
-
-> Para ver props e exemplos: `@Admin docs/design-system/<arquivo>.md`
-
-| Categoria | Arquivo |
-|-----------|---------|
-| Fundação | `foundation.md` |
-| Botões & Ações | `buttons-actions.md` |
-| Inputs | `inputs.md` |
-| Seletores | `selectors.md` |
-| Data Display | `data-display.md` |
-| Data Grid | `tables-grids.md` |
-| Navegação | `navigation.md` |
-| Dialogs | `dialogs.md` |
-| Layout | `layout.md` |
-| CRUD | `crud.md` |
-
-### Aliases
-
-| Original | Alias(es) |
-|----------|-----------|
-| Combobox | SelectSearch, MultiSelect, EntitySelect |
-| ComboTree | TreeSelect |
-| ActionButton | ActionMenu, RowActions |
-| CrudPrimitiveTable | DataTable |
-
----
-
-## Instrução para IA — Leitura Obrigatória
-
-**QUANDO** criar ou modificar qualquer arquivo `.tsx`:
-
-- **SE** contém tabela/CRUD → **LER** `@Admin docs/design-system/crud.md` ANTES
-- **SE** contém formulário → **LER** `@Admin docs/design-system/inputs.md` ANTES
-- **SE** contém modal → **LER** `@Admin docs/design-system/dialogs.md` ANTES
-- **SE** contém botões/ações → **LER** `@Admin docs/design-system/buttons-actions.md` ANTES
-- **SE** é layout → **LER** `@Admin docs/design-system/layout.md` ANTES
-
-**SEMPRE** consultar `@Admin docs/design-system/examples.md` como referência.
-
-**VALIDAÇÃO**: Todo import de componente visual DEVE vir de `forlogic-core`.

package/docs/design-system/buttons-actions.md

@@ -1,433 +0,0 @@
-<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
-<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
-
-# Botões & Ações
-
-Categoria: **Botões & Ações** | 6 componentes
-
-### Action Menu (ActionButton)
-
-Botão compacto otimizado para ações em linhas de tabela e menus dropdown. OBRIGATÓRIO para todas as ações em tabelas CRUD. Também disponível como ActionMenu.
-
-**Uso:**
-```tsx
-import { 
-  ActionButton,  // ou: import { ActionMenu } from "forlogic-core"
-  DropdownMenu, 
-  DropdownMenuTrigger,
-  DropdownMenuContent,
-  DropdownMenuItem 
-} from "forlogic-core"
-import { Edit, Trash } from 'lucide-react'
-
-// 💡 Alias disponível: ActionMenu = ActionButton
-
-// ✅ CORRETO: Uso padrão em tabelas CRUD
-<DropdownMenu>
-  <DropdownMenuTrigger asChild>
-    <ActionButton />
-  </DropdownMenuTrigger>
-  <DropdownMenuContent align="end">
-    <DropdownMenuItem onClick={() => handleEdit(item)}>
-      <Edit className="mr-2 h-4 w-4" />
-      Editar
-    </DropdownMenuItem>
-    <DropdownMenuItem onClick={() => handleDelete(item)}>
-      <Trash className="mr-2 h-4 w-4" />
-      Excluir
-    </DropdownMenuItem>
-  </DropdownMenuContent>
-</DropdownMenu>
-
-// ✅ CORRETO: Com ícone customizado
-<ActionButton>
-  <Edit size={12} />
-</ActionButton>
-```
-
-**Props:**
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `children` | `ReactNode` | <EllipsisVertical /> | Conteúdo customizado (ícone padrão: três pontos verticais). |
-| `className` | `string` | - | Classes CSS adicionais. |
-| `onClick` | `() => void` | - | Handler de clique. |
-
-**Exemplos:**
-```tsx
-// ❌ NUNCA faça isso em tabelas CRUD
-<Button variant=
-```
-```tsx
-// ✅ SEMPRE use ActionButton em tabelas
-<DropdownMenu>
-  <DropdownMenuTrigger asChild>
-    <ActionButton />
-  </DropdownMenuTrigger>
-  <DropdownMenuContent align=
-```
-
-**Acessibilidade:**
-- Tamanho compacto (height: 28px, padding: 8px)
-- Ícone padrão: EllipsisVertical (três pontos verticais)
-- variant=
--  com estilo consistente do tema
-- Perfeito para menus de ação em linhas de tabela
-
-**Notas:**
-- 💡 Alias: Também disponível como 
--  — import { ActionMenu } from 
-- ,
-        
-- ,
-        
-- ghost
-- icon
-- ,
-        
-- ,
-        
-- ,
-        
-
-> Fonte: `src\design-system\docs\components\ActionButtonDoc.tsx`
-
----
-
-### Button
-
-Componente de botão com variantes semânticas, tamanhos e estados. Use para ações primárias, secundárias e destrutivas.
-
-**Uso:**
-```tsx
-import { Button } from "forlogic-core"
-
-<Button>Click me</Button>
-<Button variant="primary">Primary</Button>
-<Button variant="destructive">Delete</Button>
-```
-
-**Props:**
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `asChild` | `boolean` | false | Renderiza como elemento filho (ex: Link). |
-| `disabled` | `boolean` | false | Estado desabilitado. |
-
-**Exemplos:**
-```tsx
-<Button variant=
-```
-```tsx
-// ⚠️ DEPRECATED: Variantes mantidas para compatibilidade
-// Use as variantes semânticas (primary, secondary, etc.)
-<Button variant=
-```
-```tsx
-<Button size=
-```
-```tsx
-<Button size=
-```
-```tsx
-<Button>Normal</Button>
-<Button disabled>Disabled</Button>
-<Button disabled>
-  <Loader2 className=
-```
-```tsx
-<Button variant=
-```
-
-**Acessibilidade:**
-- Acessível via teclado (Tab, Enter, Space)
-- Indicador de foco visível (focus-visible)
-- Estado desabilitado comunicado a leitores de tela
-- Botões de ícone devem ter aria-label
-- Tamanho mínimo de toque de 44x44px no mobile
-
-**Notas:**
-- ✅ Use variant=
--  para a ação principal da página
-- ✅ Limite a um botão primário por seção
-- ✅ Use variant=
--  para ações destrutivas (consistente com Alert e Badge)
-- ✅ Inclua estado de loading para ações assíncronas
-- ❌ Não use múltiplos botões primários no mesmo contexto
-- ❌ Não crie estilos customizados fora do design system
-- 🎨 **Padrão v2**: Tamanho 
--  usa 
--  (8px) para consistência com inputs e selects.
-
-> Fonte: `src\design-system\docs\components\ButtonDoc.tsx`
-
----
-
-### Button
-
-Componente de botão com variantes semânticas, tamanhos e estados. Use para ações primárias, secundárias e destrutivas.
-
-**Uso:**
-```tsx
-import { Button } from "forlogic-core"
-
-<Button>Click me</Button>
-<Button variant="primary">Primary</Button>
-<Button variant="destructive">Delete</Button>
-```
-
-**Props:**
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `asChild` | `boolean` | false | Renderiza como elemento filho (ex: Link). |
-| `disabled` | `boolean` | false | Estado desabilitado. |
-
-**Exemplos:**
-```tsx
-<Button variant=
-```
-```tsx
-// ⚠️ DEPRECATED: Variantes mantidas para compatibilidade
-// Use as variantes semânticas (primary, secondary, etc.)
-<Button variant=
-```
-```tsx
-<Button size=
-```
-```tsx
-<Button size=
-```
-```tsx
-<Button>Normal</Button>
-<Button disabled>Disabled</Button>
-<Button disabled>
-  <Loader2 className=
-```
-```tsx
-<Button variant=
-```
-
-**Acessibilidade:**
-- Acessível via teclado (Tab, Enter, Space)
-- Indicador de foco visível (focus-visible)
-- Estado desabilitado comunicado a leitores de tela
-- Botões de ícone devem ter aria-label
-- Tamanho mínimo de toque de 44x44px no mobile
-
-**Notas:**
-- ✅ Use variant=
--  para a ação principal da página
-- ✅ Limite a um botão primário por seção
-- ✅ Use variant=
--  para ações destrutivas (consistente com Alert e Badge)
-- ✅ Inclua estado de loading para ações assíncronas
-- ❌ Não use múltiplos botões primários no mesmo contexto
-- ❌ Não crie estilos customizados fora do design system
-- 🎨 **Padrão v2**: Tamanho 
--  usa 
--  (8px) para consistência com inputs e selects.
-
-> Fonte: `src\design-system\docs\components\ButtonDoc.tsx`
-
----
-
-### Action Menu (ActionButton)
-
-Botão compacto otimizado para ações em linhas de tabela e menus dropdown. OBRIGATÓRIO para todas as ações em tabelas CRUD. Também disponível como ActionMenu.
-
-**Uso:**
-```tsx
-import { 
-  ActionButton,  // ou: import { ActionMenu } from "forlogic-core"
-  DropdownMenu, 
-  DropdownMenuTrigger,
-  DropdownMenuContent,
-  DropdownMenuItem 
-} from "forlogic-core"
-import { Edit, Trash } from 'lucide-react'
-
-// 💡 Alias disponível: ActionMenu = ActionButton
-
-// ✅ CORRETO: Uso padrão em tabelas CRUD
-<DropdownMenu>
-  <DropdownMenuTrigger asChild>
-    <ActionButton />
-  </DropdownMenuTrigger>
-  <DropdownMenuContent align="end">
-    <DropdownMenuItem onClick={() => handleEdit(item)}>
-      <Edit className="mr-2 h-4 w-4" />
-      Editar
-    </DropdownMenuItem>
-    <DropdownMenuItem onClick={() => handleDelete(item)}>
-      <Trash className="mr-2 h-4 w-4" />
-      Excluir
-    </DropdownMenuItem>
-  </DropdownMenuContent>
-</DropdownMenu>
-
-// ✅ CORRETO: Com ícone customizado
-<ActionButton>
-  <Edit size={12} />
-</ActionButton>
-```
-
-**Props:**
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `children` | `ReactNode` | <EllipsisVertical /> | Conteúdo customizado (ícone padrão: três pontos verticais). |
-| `className` | `string` | - | Classes CSS adicionais. |
-| `onClick` | `() => void` | - | Handler de clique. |
-
-**Exemplos:**
-```tsx
-// ❌ NUNCA faça isso em tabelas CRUD
-<Button variant=
-```
-```tsx
-// ✅ SEMPRE use ActionButton em tabelas
-<DropdownMenu>
-  <DropdownMenuTrigger asChild>
-    <ActionButton />
-  </DropdownMenuTrigger>
-  <DropdownMenuContent align=
-```
-
-**Acessibilidade:**
-- Tamanho compacto (height: 28px, padding: 8px)
-- Ícone padrão: EllipsisVertical (três pontos verticais)
-- variant=
--  com estilo consistente do tema
-- Perfeito para menus de ação em linhas de tabela
-
-**Notas:**
-- 💡 Alias: Também disponível como 
--  — import { ActionMenu } from 
-- ,
-        
-- ,
-        
-- ghost
-- icon
-- ,
-        
-- ,
-        
-- ,
-        
-
-> Fonte: `src\design-system\docs\components\ActionButtonDoc.tsx`
-
----
-
-### Switch
-
-Um controle que permite ao usuário alternar entre marcado e desmarcado.
-
-**Uso:**
-```tsx
-import { Switch, Label } from "forlogic-core"
-
-<div className="flex items-center space-x-2">
-  <Switch id="airplane-mode" />
-  <Label htmlFor="airplane-mode">Modo Avião</Label>
-</div>
-```
-
-**Props:**
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `id` | `string` | - | Identificador único para associar com Label. |
-| `checked` | `boolean` | - | Estado controlado do switch. |
-| `defaultChecked` | `boolean` | false | Estado inicial não controlado. |
-| `disabled` | `boolean` | false | Desabilita a interação. |
-| `required` | `boolean` | false | Indica campo obrigatório em formulário. |
-| `name` | `string` | - | Nome do campo para submissão de formulário. |
-| `onCheckedChange` | `(checked: boolean) => void` | - | Callback quando o estado muda. |
-
-**Exemplos:**
-```tsx
-// Desligado
-<Switch id=
-```
-```tsx
-import { Switch, Label } from
-```
-```tsx
-<div className=
-```
-```tsx
-<div className=
-```
-
-**Acessibilidade:**
-- Role 
--  aplicado automaticamente (WAI-ARIA)
-- Suporte completo de teclado (Espaço para alternar)
-- Estados aria-checked comunicados para leitores de tela
-- Associação com Label via htmlFor/id
-- Indicadores visuais de foco visíveis
-- Estado desabilitado comunicado via aria-disabled
-
-> Fonte: `src\design-system\docs\components\SwitchDoc.tsx`
-
----
-
-### Toggle
-
-Botões de dois estados que podem estar ligados ou desligados, individualmente ou em grupo.
-
-**Uso:**
-```tsx
-import { Toggle, ToggleGroup, ToggleGroupItem } from "forlogic-core"
-import { Bold, Italic } from "lucide-react"
-
-// Toggle individual
-<Toggle aria-label="Alternar negrito">
-  <Bold className="h-4 w-4" />
-</Toggle>
-
-// Toggle em grupo (seleção única)
-<ToggleGroup type="single" defaultValue="center">
-  <ToggleGroupItem value="left" aria-label="Alinhar à esquerda">
-    <AlignLeft className="h-4 w-4" />
-  </ToggleGroupItem>
-  <ToggleGroupItem value="center" aria-label="Centralizar">
-    <AlignCenter className="h-4 w-4" />
-  </ToggleGroupItem>
-</ToggleGroup>
-```
-
-**Props:**
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `pressed` | `boolean` | - | Estado controlado do Toggle. |
-| `defaultPressed` | `boolean` | false | Estado inicial não controlado do Toggle. |
-| `onPressedChange` | `(pressed: boolean) => void` | - | Callback quando o estado do Toggle muda. |
-| `disabled` | `boolean` | false | Desabilita a interação. |
-| `aria-label` | `string` | - | Obrigatório para acessibilidade quando não há texto visível. |
-
-**Exemplos:**
-```tsx
-import { Toggle } from
-```
-```tsx
-<Toggle aria-label=
-```
-```tsx
-import { ToggleGroup, ToggleGroupItem } from
-```
-```tsx
-import { ToggleGroup, ToggleGroupItem } from
-```
-
-**Acessibilidade:**
-- Role 
--  com aria-pressed aplicado automaticamente
-- Suporte completo de teclado (Espaço/Enter para alternar)
-- Navegação por setas entre itens do ToggleGroup
-- aria-label obrigatório para toggles apenas com ícones
-- Estados aria-pressed comunicados para leitores de tela
-- Indicadores visuais de foco e estado ativo
-- ToggleGroup implementa padrão roving tabindex
-
-> Fonte: `src\design-system\docs\components\ToggleDoc.tsx`
-
----