forlogic-core 2.0.3 → 2.0.4

package/docs/design-system/layout.md

@@ -0,0 +1,351 @@
+<!-- ⚠️ 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`
+
+---