forlogic-core 2.0.3 → 2.0.5

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

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