forlogic-core 3.0.11 → 4.0.0

package/docs/design-system/layout.md

@@ -1,351 +0,0 @@
-<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
-<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
-
-# Layout
-
-Categoria: **Layout** | 6 componentes
-
-### AppHeader
-
-Header principal da aplicação com título dinâmico, busca global integrada ao CRUD, ações customizáveis e informações do usuário. Altura fixa de 56px (h-14).
-
-**Uso:**
-```tsx
-import { AppLayout, usePageMetadata } from 'forlogic-core';
-
-// O AppHeader é renderizado automaticamente pelo AppLayout
-<AppLayout sidebarConfig={sidebarConfig}>
-  <Routes>...</Routes>
-</AppLayout>
-
-// Para configurar título, subtítulo e breadcrumbs
-function UsersPage() {
-  usePageMetadata({
-    title: 'Usuários',
-    subtitle: 'Gerenciamento de usuários do sistema'
-  });
-}
-
-// Com breadcrumbs
-function EditUserPage() {
-  usePageMetadata({
-    title: 'Editar Usuário',
-    subtitle: 'Atualize os dados cadastrais',
-    breadcrumbs: [
-      { label: 'Usuários', href: '/users' },
-      { label: 'João Silva' }
-    ]
-  });
-}
-
-// Subtitle com ReactNode
-function DetailPage() {
-  usePageMetadata({
-    title: 'Detalhes',
-    subtitle: <span>Veja a <Link to="/docs">documentação</Link></span>
-  });
-}
-```
-
-**Props:**
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `actions` | `ReactNode` | - | Botões de ação à direita do header (via PageMetadataContext) |
-| `selectedUnit (UserInfo)` | `Company | null` | - | Unidade selecionada |
-| `onUnitChange (UserInfo)` | `(unit: Company) => void` | - | Callback ao trocar unidade |
-
-**Exemplos:**
-```tsx
-// Áreas do AppHeader
-// 1. Título: Título da página + Subtítulo + Badge do módulo
-// 2. Busca: Input de busca global (visível quando habilitado)
-// 3. Ações: Botões customizáveis via PageMetadataContext
-// 4. Perfil: UserInfo com dropdown de usuário
-
-// Altura fixa: 56px (h-14 no Tailwind)
-```
-```tsx
-// UserInfo com variantes
-<UserInfo variant=
-```
-```tsx
-// Configurar campos pesquisáveis no service
-const userService = createSimpleService({
-  tableName:
-```
-
-**Acessibilidade:**
-- Busca acessível via teclado (Tab para navegar, Escape para limpar)
-- UserInfo dropdown acessível via teclado
-- Botões de ação com foco visível (focus-visible)
-- Título da página anunciado por leitores de tela (role=
-- )
-- Atalho de teclado para busca (/ ou Ctrl+K pode ser implementado)
-
-**Notas:**
-- ✅ Use PageMetadataContext para ações dinâmicas
-- ✅ Mantenha título curto e descritivo (máx. 3 palavras)
-- ✅ Use um único header por página
-- ✅ Limpe ações no useEffect cleanup
-- ✅ Use ícones do Lucide nos botões de ação
-- ❌ Não adicione múltiplos headers na mesma página
-- ❌ Não modifique a altura do header (fixo em 56px)
-- ❌ Não coloque formulários complexos no header
-- ❌ Não use mais de 3 botões de ação
-- ❌ Não esconda o UserInfo em páginas autenticadas
-
-> Fonte: `src\design-system\docs\components\layout\AppHeaderDoc.tsx`
-
----
-
-### AppSidebar
-
-Sidebar de navegação principal da aplicação com suporte a pin/unpin, permissões assíncronas, ações de módulo (SidebarActionTrigger), redimensionamento, navegação hierárquica e separadores visuais.
-
-**Uso:**
-```tsx
-import { AppLayout } from 'forlogic-core';
-import type { SidebarConfig } from 'forlogic-core';
-import { Home, Users, Settings, Shield, Plus, FileText, Folder } from 'lucide-react';
-
-const sidebarConfig: SidebarConfig = {
-  appName: 'Minha Aplicação',
-
-  // Ações do módulo (opcional)
-  moduleActions: {
-    triggerLabel: 'Criar',
-    triggerIcon: Plus,
-    actions: [
-      { id: 'new-doc', label: 'Novo Documento', icon: FileText, onClick: () => {} },
-      { id: 'new-folder', label: 'Nova Pasta', icon: Folder, onClick: () => {} },
-    ],
-  },
-
-  // Navegação (com suporte a hierarquia e separadores)
-  navigation: [
-    { label: 'Início', path: '/', icon: Home },
-    { label: 'Usuários', path: '/users', icon: Users },
-    { label: '', path: '', type: 'separator' },  // Linha horizontal separadora
-    {
-      label: 'Configurações',
-      path: '/settings',
-      icon: Settings,
-      children: [
-        { label: 'Perfil', path: '/settings/profile', icon: Users },
-        { label: 'Segurança', path: '/settings/security', icon: Shield },
-      ],
-    },
-  ],
-};
-
-// Uso via AppLayout (recomendado)
-<AppLayout sidebarConfig={sidebarConfig}>
-  <Routes>...</Routes>
-</AppLayout>
-
-// Uso direto (casos avançados)
-<AppSidebar
-  config={sidebarConfig}
-  resizable={true}
-  minWidth={224}
-  maxWidth={384}
-/>
-```
-
-**Exemplos:**
-```tsx
-// Estrutura do AppSidebar
-<Sidebar collapsible=
-```
-```tsx
-// Matching de rota ativa (hierárquico)
-const isActive = (path: string) =>
-  location.pathname === path ||
-  location.pathname.startsWith(path +
-```
-
-**Acessibilidade:**
-- Navegação acessível via teclado (Tab, Arrow keys, Enter)
-- Submenus expansíveis com Enter ou Space (via Collapsible)
-- Estado ativo comunicado via isActive no SidebarMenuButton
-- Itens desabilitados com cursor-not-allowed e opacity reduzida
-- Tooltips em modo colapsado para identificação de todos os itens
-- Botão pin/unpin oculto em mobile (hidden md:block) para evitar conflito com drawer
-- Contraste adequado entre estados ativo/inativo usando tokens semânticos
-
-**Notas:**
-- ✅ Use ícones consistentes do Lucide React para todos os itens
-- ✅ Máximo 2 níveis de aninhamento (item → children)
-- ✅ Labels curtas: 1-3 palavras, máximo 20 caracteres
-- ✅ Agrupe itens relacionados logicamente
-- ✅ Use permissionCheck para controle de acesso assíncrono
-- ✅ Use moduleActions para ações de criação/adição do módulo
-- ✅ Prefira AppLayout ao invés de usar AppSidebar diretamente
-- ❌ Não use mais de 10 itens no nível raiz
-- ❌ Não crie 3+ níveis de submenu (hierarquia profunda)
-- ❌ Não deixe itens sem ícones
-- ❌ Não misture ícones de bibliotecas diferentes
-- ❌ Não use labels com mais de 20 caracteres
-
-> Fonte: `src\design-system\docs\components\layout\AppSidebarDoc.tsx`
-
----
-
-### BodyContent
-
-Container principal de página com breadcrumb, background neutro e suporte a múltiplos containers de conteúdo.
-
-**Uso:**
-```tsx
-import { BodyContent, ContentContainer } from 'forlogic-core';
-
-<BodyContent
-  breadcrumbs={[
-    { label: 'Módulo', href: '/modulo' },
-    { label: 'Seção', href: '/modulo/secao' },
-    { label: 'Página Atual' }, // Sem href = página atual
-  ]}
->
-  <ContentContainer 
-    title="Título do Container" 
-    subtitle="Subtítulo com informações adicionais"
-  >
-    <p>Conteúdo principal aqui...</p>
-  </ContentContainer>
-</BodyContent>
-```
-
-**Exemplos:**
-```tsx
-<BodyContent
-  breadcrumbs={[
-    { label:
-```
-
-**Acessibilidade:**
-- O breadcrumb usa a tag nav com aria-label=
--  para identificação por leitores de tela
-- A página atual no breadcrumb é marcada com aria-current=
-- ,
-        
-- ,
-        
-- true
-
-**Notas:**
-- O background externo usa a cor Escala Neutra 100 (#F5F5F5) para separar visualmente do conteúdo
-- Os ContentContainers têm background branco (#FFFFFF) com sombra sutil e border-radius
-- Use múltiplos ContentContainers para agrupar conteúdos relacionados na mesma página
-- O último item do breadcrumb é automaticamente tratado como página atual (sem link)
-- Para integração com React Router, use asChild=true e passe o Link como children
-- O espaçamento entre containers segue o padrão do Design System (space-y-6)
-
-> Fonte: `src\design-system\docs\components\layout\BodyContentDoc.tsx`
-
----
-
-### CrudGrid
-
-Componente para exibir dados em formato de grade (cards) com todas as funcionalidades CRUD. Alternativa visual ao CrudTable para listagens com layout mais visual.
-
-> Fonte: `src\design-system\docs\components\crud\CrudGridDoc.tsx`
-
----
-
-### Resizable
-
-Painéis redimensionáveis para criar layouts flexíveis e adaptáveis. Baseado em react-resizable-panels.
-
-**Uso:**
-```tsx
-import { 
-  ResizablePanelGroup, 
-  ResizablePanel, 
-  ResizableHandle 
-} from 'forlogic-core/modular';
-
-function ResizableLayout() {
-  return (
-    <ResizablePanelGroup direction="horizontal" className="min-h-[200px]">
-      <ResizablePanel defaultSize={25}>
-        <div className="p-4">Painel Esquerdo</div>
-      </ResizablePanel>
-      <ResizableHandle withHandle />
-      <ResizablePanel defaultSize={75}>
-        <div className="p-4">Painel Direito</div>
-      </ResizablePanel>
-    </ResizablePanelGroup>
-  );
-}
-```
-
-**Acessibilidade:**
-- Suporte completo a navegação por teclado
-- Alças de redimensionamento focáveis com Tab
-- Use setas do teclado para redimensionar quando focado na alça
-- Focus ring visível para acessibilidade
-
-**Notas:**
-- ResizablePanelGroup deve envolver todos os ResizablePanel e ResizableHandle.
-- Use withHandle no ResizableHandle para melhor UX com indicador visual.
-- minSize e maxSize são valores percentuais (0-100).
-- A soma de defaultSize dos painéis deve ser 100.
-- Combine com hooks de resize (useColumnResize, useSidebarResize) para casos específicos.
-
-> Fonte: `src\design-system\docs\components\ResizableDoc.tsx`
-
----
-
-### ScrollArea
-
-Área de rolagem customizada com scrollbars estilizadas, baseada no Radix UI ScrollArea.
-
-**Uso:**
-```tsx
-import { ScrollArea, ScrollBar } from "forlogic-core"
-
-<ScrollArea className="h-72 w-48 rounded-md border">
-  <div className="p-4">
-    {items.map((item) => (
-      <div key={item.id}>{item.content}</div>
-    ))}
-  </div>
-</ScrollArea>
-
-// Scroll horizontal:
-<ScrollArea className="w-96 whitespace-nowrap rounded-md border">
-  <div className="flex w-max space-x-4 p-4">
-    {items.map((item) => (
-      <div key={item.id} className="w-[150px] shrink-0">{item.content}</div>
-    ))}
-  </div>
-  <ScrollBar orientation="horizontal" />
-</ScrollArea>
-```
-
-**Props:**
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `className` | `string` | - | Classes CSS para o container root. |
-| `children` | `ReactNode` | - | Conteúdo rolável. |
-
-**Exemplos:**
-```tsx
-<ScrollArea className=
-```
-
-**Acessibilidade:**
-- Scrollbars customizadas mantêm comportamento nativo de rolagem.
-- Funciona com teclado, trackpad e touch.
-- Compatível com leitores de tela.
-
-**Notas:**
-- O ScrollArea vertical é o padrão — não precisa de ScrollBar explícito.
-- Para scroll horizontal, adicione <ScrollBar orientation=
--  /> como filho direto.
-- Usado internamente pela DesignSystemSidebar, AppSidebar, e outros componentes com overflow.
-- Mantém bordas arredondadas do container pai (rounded-[inherit]).
-
-> Fonte: `src\design-system\docs\components\ScrollAreaDoc.tsx`
-
----