forlogic-core 1.9.3 → 1.10.0

package/dist/DESIGN_SYSTEM.md

@@ -0,0 +1,676 @@
+# 🎨 forlogic-core - Design System
+
+> Documentação completa dos componentes, tokens e padrões do Design System
+
+**Versão:** 1.9.3  
+**Última atualização:** 2025-11-24
+
+---
+
+## 🚀 Início Rápido
+
+### Instalação
+
+```bash
+npm install forlogic-core
+```
+
+### Uso Básico
+
+```tsx
+import { Button, Input, Card } from 'forlogic-core';
+import 'forlogic-core/index.css';
+
+function App() {
+  return (
+    <Card>
+      <Input placeholder="Digite algo..." />
+      <Button>Enviar</Button>
+    </Card>
+  );
+}
+```
+
+---
+
+## 📖 Índice
+
+### 🎨 Fundamentos (Tokens)
+- [Colors](#colors) - Sistema de cores e temas
+- [Typography](#typography) - Escala tipográfica
+- [Spacing](#spacing) - Sistema de espaçamento
+- [Shadows](#shadows) - Sombras e elevação
+- [Radius](#radius) - Bordas arredondadas
+- [Transitions](#transitions) - Animações e transições
+- [Z-Index](#z-index) - Camadas de profundidade
+- [Opacities](#opacities) - Transparências
+
+### 🧩 Componentes UI
+
+#### Formulários
+- [Button](#button) - Botões e ações
+- [Input](#input) - Campos de entrada
+- [Textarea](#textarea) - Área de texto
+- [Select](#select) - Seleção de opções
+- [Checkbox](#checkbox) - Caixas de seleção
+- [Radio Group](#radio-group) - Seleção exclusiva
+- [Switch](#switch) - Interruptor on/off
+- [Combobox](#combobox) - Seleção com busca
+- [Date Picker](#date-picker) - Seletor de data
+- [Color Picker](#color-picker) - Seletor de cor
+- [Icon Picker](#icon-picker) - Seletor de ícones
+
+#### Layout
+- [Card](#card) - Cards e containers
+- [Dialog](#dialog) - Modais e diálogos
+- [Sheet](#sheet) - Painéis laterais
+- [Tabs](#tabs) - Abas de navegação
+- [Accordion](#accordion) - Conteúdo expansível
+- [Separator](#separator) - Divisores
+- [Scroll Area](#scroll-area) - Área com scroll
+- [Resizable](#resizable) - Painéis redimensionáveis
+- [Sidebar](#sidebar) - Barra lateral
+
+#### Navegação
+- [Breadcrumb](#breadcrumb) - Trilha de navegação
+- [Pagination](#pagination) - Paginação
+- [Dropdown Menu](#dropdown-menu) - Menu suspenso
+- [Navigation Menu](#navigation-menu) - Menu de navegação
+- [Menubar](#menubar) - Barra de menu
+
+#### Feedback
+- [Alert](#alert) - Alertas e avisos
+- [Toast](#toast) - Notificações temporárias
+- [Progress](#progress) - Barra de progresso
+- [Skeleton](#skeleton) - Loading placeholder
+- [Spinner](#spinner) - Indicador de carregamento
+- [Badge](#badge) - Etiquetas e badges
+- [Empty State](#empty-state) - Estado vazio
+
+#### Dados
+- [Table](#table) - Tabelas de dados
+- [Data List](#data-list) - Listas de dados
+
+#### Outros
+- [Avatar](#avatar) - Avatares de usuário
+- [Tooltip](#tooltip) - Dicas contextuais
+- [Popover](#popover) - Popover
+- [Hover Card](#hover-card) - Card ao hover
+- [Context Menu](#context-menu) - Menu de contexto
+- [Carousel](#carousel) - Carrossel
+- [Aspect Ratio](#aspect-ratio) - Proporção de aspecto
+
+### 🚀 Sistema CRUD
+- [createCrudPage](#createcrudpage) - Páginas CRUD automáticas
+- [BaseForm](#baseform) - Formulários dinâmicos
+- [CrudTable](#crudtable) - Tabelas com ações
+- [CrudCards](#crudcards) - Cards com ações
+- [WizardForm](#wizardform) - Formulários em etapas
+
+---
+
+## 🎨 FUNDAMENTOS (TOKENS)
+
+### Colors
+
+Sistema de cores baseado em HSL, totalmente compatível com temas claro/escuro.
+
+**Importação:**
+```tsx
+import { 
+  getColor, 
+  lightSemanticColors, 
+  darkSemanticColors,
+  neutralScale,
+  brandScale 
+} from 'forlogic-core/tokens';
+```
+
+**Escalas Disponíveis:**
+
+- **neutralScale**: Cinzas de 0 a 1000
+- **brandScale**: Cores da marca (primary, secondary, accent)
+- **functionalColors**: Success, warning, danger, info
+
+**Cores Semânticas (recomendadas):**
+
+```typescript
+// Superfícies
+surfaceBase        // Fundo base
+surfaceCard        // Cards e containers
+surfaceDialog      // Modais e diálogos
+surfaceHover       // Hover states
+
+// Texto
+textPrimary        // Texto principal
+textSecondary      // Texto secundário
+textMuted          // Texto desabilitado
+
+// Bordas
+borderDefault      // Bordas padrão
+borderInput        // Bordas de inputs
+borderFocus        // Bordas em foco
+
+// Ações
+actionPrimary      // Ação primária
+actionSecondary    // Ação secundária
+actionDestructive  // Ações destrutivas
+```
+
+**Uso em Componentes:**
+
+```tsx
+// Usar classes do Tailwind com tokens semânticos
+<div className="bg-background text-foreground border border-border">
+  <h1 className="text-primary">Título</h1>
+  <p className="text-muted-foreground">Descrição</p>
+</div>
+
+// Ou via tokens TypeScript
+const bgColor = lightSemanticColors.surfaceBase;
+```
+
+---
+
+### Typography
+
+Escala tipográfica consistente com presets para diferentes hierarquias.
+
+**Importação:**
+```tsx
+import { 
+  fontFamilies, 
+  fontSizes, 
+  fontWeights,
+  typographyPresets 
+} from 'forlogic-core/tokens';
+```
+
+**Famílias de Fonte:**
+```typescript
+fontFamilies.sans  // Fonte sans-serif padrão
+fontFamilies.mono  // Fonte monoespaçada
+```
+
+**Tamanhos:**
+```typescript
+fontSizes.xs   // 0.75rem (12px)
+fontSizes.sm   // 0.875rem (14px)
+fontSizes.base // 1rem (16px)
+fontSizes.lg   // 1.125rem (18px)
+fontSizes.xl   // 1.25rem (20px)
+fontSizes['2xl'] // 1.5rem (24px)
+fontSizes['3xl'] // 1.875rem (30px)
+fontSizes['4xl'] // 2.25rem (36px)
+```
+
+**Presets Tipográficos:**
+```tsx
+// Usar classes do Tailwind
+<h1 className="text-4xl font-bold">Heading 1</h1>
+<h2 className="text-3xl font-semibold">Heading 2</h2>
+<p className="text-base">Body text</p>
+<small className="text-sm text-muted-foreground">Small text</small>
+```
+
+---
+
+### Spacing
+
+Sistema de espaçamento consistente baseado em múltiplos de 4px.
+
+**Importação:**
+```tsx
+import { spacing, semanticSpacing, getSpacing } from 'forlogic-core/tokens';
+```
+
+**Escala:**
+```typescript
+spacing[0]   // 0px
+spacing[1]   // 0.25rem (4px)
+spacing[2]   // 0.5rem (8px)
+spacing[3]   // 0.75rem (12px)
+spacing[4]   // 1rem (16px)
+spacing[6]   // 1.5rem (24px)
+spacing[8]   // 2rem (32px)
+spacing[12]  // 3rem (48px)
+spacing[16]  // 4rem (64px)
+```
+
+**Uso:**
+```tsx
+<div className="p-4 m-2 space-y-4">
+  <Card className="p-6">Content</Card>
+</div>
+```
+
+---
+
+### Shadows
+
+Sistema de sombras para criar profundidade e hierarquia.
+
+**Importação:**
+```tsx
+import { shadows, elevation, getShadow } from 'forlogic-core/tokens';
+```
+
+**Níveis:**
+```tsx
+<Card className="shadow-sm">Subtle shadow</Card>
+<Card className="shadow">Default shadow</Card>
+<Card className="shadow-md">Medium shadow</Card>
+<Card className="shadow-lg">Large shadow</Card>
+<Card className="shadow-xl">Extra large shadow</Card>
+```
+
+---
+
+### Radius
+
+Bordas arredondadas consistentes.
+
+**Importação:**
+```tsx
+import { radius, getRadius } from 'forlogic-core/tokens';
+```
+
+**Valores:**
+```tsx
+<div className="rounded-none">No radius</div>
+<div className="rounded-sm">Small radius</div>
+<div className="rounded">Default radius</div>
+<div className="rounded-md">Medium radius</div>
+<div className="rounded-lg">Large radius</div>
+<div className="rounded-full">Full radius</div>
+```
+
+---
+
+### Transitions
+
+Animações e transições suaves.
+
+**Importação:**
+```tsx
+import { duration, easing, transitions } from 'forlogic-core/tokens';
+```
+
+**Uso:**
+```tsx
+<button className="transition-colors hover:bg-primary">
+  Hover me
+</button>
+
+<div className="transition-all duration-300 ease-in-out">
+  Animated
+</div>
+```
+
+---
+
+## 🧩 COMPONENTES UI
+
+### Button
+
+Componente de botão com múltiplas variantes, tamanhos e estados.
+
+**Importação:**
+```tsx
+import { Button } from 'forlogic-core';
+```
+
+**Uso Básico:**
+```tsx
+<Button>Default Button</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="outline" size="sm">Small</Button>
+<Button variant="ghost">Ghost Button</Button>
+<Button size="icon"><Icon /></Button>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| variant | "default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link" | "default" | Variante visual |
+| size | "default" \| "sm" \| "lg" \| "icon" | "default" | Tamanho do botão |
+| asChild | boolean | false | Compor com outro elemento |
+| disabled | boolean | false | Desabilitar botão |
+
+**Variantes:**
+- `default`: Botão primário com fundo sólido
+- `destructive`: Ações destrutivas (deletar, remover)
+- `outline`: Botão com borda, fundo transparente
+- `secondary`: Ação secundária
+- `ghost`: Sem borda, hover sutil
+- `link`: Estilo de link
+
+---
+
+### Input
+
+Campo de entrada de texto.
+
+**Importação:**
+```tsx
+import { Input } from 'forlogic-core';
+```
+
+**Uso:**
+```tsx
+<Input type="text" placeholder="Digite seu nome..." />
+<Input type="email" placeholder="email@exemplo.com" />
+<Input type="password" disabled />
+```
+
+---
+
+### Select
+
+Seleção de opções em dropdown.
+
+**Importação:**
+```tsx
+import { 
+  Select, 
+  SelectTrigger, 
+  SelectValue, 
+  SelectContent, 
+  SelectItem 
+} from 'forlogic-core';
+```
+
+**Uso:**
+```tsx
+<Select>
+  <SelectTrigger>
+    <SelectValue placeholder="Selecione..." />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="1">Opção 1</SelectItem>
+    <SelectItem value="2">Opção 2</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+---
+
+### Card
+
+Container para agrupar conteúdo relacionado.
+
+**Importação:**
+```tsx
+import { 
+  Card, 
+  CardHeader, 
+  CardTitle, 
+  CardDescription,
+  CardContent, 
+  CardFooter 
+} from 'forlogic-core';
+```
+
+**Uso:**
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Título do Card</CardTitle>
+    <CardDescription>Descrição opcional</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Conteúdo do card</p>
+  </CardContent>
+  <CardFooter>
+    <Button>Ação</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+### Dialog
+
+Modais e diálogos.
+
+**Importação:**
+```tsx
+import { 
+  Dialog, 
+  DialogTrigger, 
+  DialogContent, 
+  DialogHeader,
+  DialogTitle, 
+  DialogDescription,
+  DialogFooter 
+} from 'forlogic-core';
+```
+
+**Uso:**
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Abrir Modal</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Título do Modal</DialogTitle>
+      <DialogDescription>Descrição</DialogDescription>
+    </DialogHeader>
+    <div>Conteúdo do modal</div>
+    <DialogFooter>
+      <Button>Confirmar</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+---
+
+### Table
+
+Tabelas de dados.
+
+**Importação:**
+```tsx
+import { 
+  Table, 
+  TableHeader, 
+  TableBody, 
+  TableRow, 
+  TableHead, 
+  TableCell 
+} from 'forlogic-core';
+```
+
+**Uso:**
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Nome</TableHead>
+      <TableHead>Email</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>João</TableCell>
+      <TableCell>joao@exemplo.com</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+---
+
+### Toast
+
+Notificações temporárias.
+
+**Importação:**
+```tsx
+import { useToast } from 'forlogic-core';
+```
+
+**Uso:**
+```tsx
+function MyComponent() {
+  const { toast } = useToast();
+
+  return (
+    <Button onClick={() => toast({
+      title: "Sucesso!",
+      description: "Operação concluída com sucesso",
+    })}>
+      Mostrar Toast
+    </Button>
+  );
+}
+```
+
+---
+
+## 🚀 SISTEMA CRUD
+
+### createCrudPage
+
+Função utilitária que cria páginas CRUD completas automaticamente.
+
+**Importação:**
+```tsx
+import { createCrudPage } from 'forlogic-core';
+```
+
+**Exemplo Completo:**
+```tsx
+import { createCrudPage } from 'forlogic-core';
+import { processService } from './processService';
+import { processSchema } from './processValidation';
+
+export const ProcessesPage = createCrudPage({
+  entity: 'process',
+  service: processService,
+  schema: processSchema,
+  fields: [
+    { name: 'title', label: 'Título', type: 'text', required: true },
+    { name: 'description', label: 'Descrição', type: 'textarea' }
+  ],
+  columns: [
+    { key: 'title', label: 'Título' },
+    { key: 'created_at', label: 'Criado em', format: 'date' }
+  ]
+});
+```
+
+**Props:**
+| Prop | Tipo | Descrição |
+|------|------|-----------|
+| entity | string | Nome da entidade (singular) |
+| service | CrudService | Service com métodos CRUD |
+| schema | ZodSchema | Schema de validação Zod |
+| fields | FieldConfig[] | Configuração dos campos |
+| columns | ColumnConfig[] | Configuração das colunas |
+
+---
+
+### BaseForm
+
+Formulário dinâmico com validação.
+
+**Importação:**
+```tsx
+import { BaseForm } from 'forlogic-core';
+```
+
+**Uso:**
+```tsx
+<BaseForm
+  fields={[
+    { name: 'name', label: 'Nome', type: 'text', required: true },
+    { name: 'email', label: 'Email', type: 'email' }
+  ]}
+  onSubmit={handleSubmit}
+  defaultValues={initialData}
+/>
+```
+
+---
+
+### WizardForm
+
+Formulário em etapas (wizard).
+
+**Importação:**
+```tsx
+import { WizardForm } from 'forlogic-core';
+```
+
+**Uso:**
+```tsx
+<WizardForm
+  steps={[
+    {
+      title: 'Informações Básicas',
+      fields: [
+        { name: 'name', label: 'Nome', type: 'text' }
+      ]
+    },
+    {
+      title: 'Contato',
+      fields: [
+        { name: 'email', label: 'Email', type: 'email' }
+      ]
+    }
+  ]}
+  onSubmit={handleSubmit}
+/>
+```
+
+---
+
+## 📝 Notas Importantes
+
+### Peer Dependencies
+
+Certifique-se de ter instalado:
+- react@^18.0.0
+- react-dom@^18.0.0
+- lucide-react@>=0.400.0
+- @tanstack/react-query@^5.0.0
+- react-router-dom@^6.0.0
+
+### CSS Global
+
+Importe o CSS no seu arquivo principal:
+```tsx
+import 'forlogic-core/index.css';
+```
+
+### TypeScript
+
+Os tipos estão incluídos automaticamente. Não é necessário instalar `@types`.
+
+### Temas Claro/Escuro
+
+O forlogic-core suporta temas automaticamente. Use o `next-themes`:
+
+```tsx
+import { ThemeProvider } from 'next-themes';
+
+<ThemeProvider attribute="class" defaultTheme="system">
+  <App />
+</ThemeProvider>
+```
+
+---
+
+## 🔗 Links Úteis
+
+- **Repositório**: [GitHub](https://github.com/your-org/forlogic-core)
+- **Exemplos**: Veja `src/design-system/docs` para exemplos detalhados
+- **Suporte**: Abra uma issue no GitHub
+
+---
+
+**Última atualização:** 2025-11-24  
+**Versão:** 1.9.3