@etus/ui 0.1.0

package/src/components/primitives/SplitButton/README.md

@@ -0,0 +1,1142 @@
+# SplitButton
+
+## Visão Geral
+
+O **SplitButton** é um componente composto que combina uma ação primária com um menu dropdown de ações secundárias. Divide-se em duas partes: um botão principal para a ação padrão e um gatilho que abre um menu com opções alternativas.
+
+### Casos de Uso
+
+- Ações com alternativas (ex: Salvar / Salvar como / Exportar)
+- Menus de ação contextual (ex: Responder / Responder a todos / Encaminhar)
+- Opções de criação múltipla (ex: Novo / Novo a partir de template)
+- Ações com variantes (ex: Download / Download como PDF / Download como CSV)
+- Comandos com atalhos (ex: Executar / Executar com debug)
+
+### Classificação
+
+**Categoria:** Atom (Primitivo)
+**Status:** Placeholder - Componente não implementado
+**Dependências Previstas:** `Button`, `DropdownMenu`, `@radix-ui/react-dropdown-menu`, `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Anatomia
+
+```
++---------------------------+-------+
+|    Primary Action         |   v   |
++---------------------------+-------+
+      Main Button           Trigger
+                               |
+                               v
+                        +-------------+
+                        | Option 1    |
+                        | Option 2    |
+                        | ----------- |
+                        | Option 3    |
+                        +-------------+
+                           Dropdown
+```
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Ação primária | `bg-primary`, `text-primary-foreground` |
+| `secondary` | Ação secundária | `bg-secondary`, `text-secondary-foreground` |
+| `destructive` | Ações perigosas | `bg-destructive`, `text-white` |
+| `outline` | Baixa ênfase | `border`, `bg-background` |
+| `ghost` | Mínima ênfase | Transparente, hover `bg-accent` |
+
+### Tamanhos (`size`)
+
+| Tamanho | Altura Main | Altura Trigger | Uso |
+|---------|-------------|----------------|-----|
+| `sm` | `h-8` (32px) | `h-8 w-8` | Espaços compactos, toolbars |
+| `default` | `h-9` (36px) | `h-9 w-9` | Uso geral |
+| `lg` | `h-10` (40px) | `h-10 w-10` | CTAs, ações principais |
+
+### Estados
+
+| Estado | Parte | Classes/Atributos | Comportamento |
+|--------|-------|-------------------|---------------|
+| Default | Ambos | - | Aparência base |
+| Hover Main | Main | `hover:bg-*/90` | Escurecimento apenas no main |
+| Hover Trigger | Trigger | `hover:bg-*/90` | Escurecimento apenas no trigger |
+| Focus | Ambos | `focus-visible:ring-[3px]` | Ring de 3px individual |
+| Disabled | Ambos | `disabled:opacity-50` | Todo o grupo desabilitado |
+| Open | Trigger | `data-[state=open]:bg-*/80` | Indica menu aberto |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--primary              /* Fundo default */
+--primary-foreground
+--secondary            /* Fundo secondary */
+--secondary-foreground
+--destructive          /* Fundo destructive */
+--accent               /* Hover */
+--ring                 /* Focus ring */
+--border               /* Divisor entre botões */
+
+/* Espaçamento */
+gap-0                  /* Sem gap entre main e trigger */
+
+/* Bordas */
+rounded-l-md           /* Main button */
+rounded-r-md           /* Trigger button */
+border-l               /* Divisor vertical */
+
+/* Transições */
+transition-all         /* Cores e transformações */
+```
+
+### data-slot
+
+```html
+<div data-slot="split-button">
+  <button data-slot="split-button-main">...</button>
+  <button data-slot="split-button-trigger">
+    <svg data-slot="split-button-icon" />
+  </button>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "secondary" \| "destructive" \| "outline" \| "ghost"` | `"default"` | Estilo visual |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Tamanho do botão |
+| `disabled` | `boolean` | `false` | Desabilita todo o componente |
+| `className` | `string` | - | Classes CSS adicionais (container) |
+| `mainClassName` | `string` | - | Classes CSS do botão principal |
+| `triggerClassName` | `string` | - | Classes CSS do trigger |
+| `children` | `ReactNode` | - | Conteúdo do botão principal |
+| `items` | `SplitButtonItem[]` | `[]` | Itens do menu dropdown |
+| `onMainClick` | `() => void` | - | Callback do botão principal |
+| `defaultOpen` | `boolean` | `false` | Menu aberto por padrão |
+| `open` | `boolean` | - | Controle externo do estado aberto |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback mudança de estado |
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Posição do menu |
+| `align` | `"start" \| "center" \| "end"` | `"end"` | Alinhamento do menu |
+| `ref` | `Ref<HTMLDivElement>` | - | Referência ao container |
+
+> Herda todas as props de `React.ComponentProps<"div">` (exceto `children`)
+
+### SplitButtonItem
+
+```typescript
+interface SplitButtonItem {
+  key: string
+  label: ReactNode
+  icon?: ReactNode
+  shortcut?: string
+  disabled?: boolean
+  destructive?: boolean
+  onSelect: () => void
+}
+
+// Separador
+interface SplitButtonSeparator {
+  key: string
+  type: "separator"
+}
+
+type SplitButtonMenuItem = SplitButtonItem | SplitButtonSeparator
+```
+
+### Callbacks
+
+| Callback | Tipo | Descrição |
+|----------|------|-----------|
+| `onMainClick` | `() => void` | Disparado ao clicar no botão principal |
+| `onOpenChange` | `(open: boolean) => void` | Disparado ao abrir/fechar menu |
+| `items[].onSelect` | `() => void` | Disparado ao selecionar item |
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+
+// Variants exportadas
+const splitButtonVariants = cva(/* ... */)
+
+// Props do componente
+interface SplitButtonProps
+  extends Omit<React.ComponentProps<"div">, "children">,
+    VariantProps<typeof splitButtonVariants> {
+  children: ReactNode
+  items: SplitButtonMenuItem[]
+  onMainClick?: () => void
+  defaultOpen?: boolean
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  side?: "top" | "bottom" | "left" | "right"
+  align?: "start" | "center" | "end"
+  mainClassName?: string
+  triggerClassName?: string
+}
+
+// Tipos derivados úteis
+type SplitButtonVariant = NonNullable<VariantProps<typeof splitButtonVariants>["variant"]>
+type SplitButtonSize = NonNullable<VariantProps<typeof splitButtonVariants>["size"]>
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint | Prime |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|:-----:|
+| **SplitButton nativo** | - | - | - | - | ~ | - | ✓ | - | - | - | ✓ | ✓ | ✓ | ✓ |
+| **ButtonGroup + Menu** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Variantes** | 5 | - | - | 5 | 3 | 6 | 5 | 4 | - | - | 5 | 4 | 4 | 5 |
+| **Tamanhos** | 3 | - | - | 4 | 3 | 5 | 4 | 4 | - | - | 4 | 4 | 3 | 3 |
+| **loading** | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓ | ✓ |
+| **Icon no main** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ |
+| **Shortcut hints** | ✓ | - | - | - | - | - | - | - | - | - | ✓ | - | ✓ | - |
+| **Separator items** | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Nested menus** | - | - | ✓ | - | ✓ | - | ✓ | - | ✓ | ✓ | ✓ | - | ✓ | ✓ |
+| **Controlled state** | ✓ | - | ✓ | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ |
+
+#### Nomenclatura por Design System
+
+| Design System | Nome do Componente | Implementação |
+|---------------|-------------------|---------------|
+| **Ant Design** | `Dropdown.Button` | Componente dedicado |
+| **Fluent UI** | `SplitButton` | Componente dedicado |
+| **Carbon** | `OverflowMenu` + `Button` | Composição |
+| **Blueprint** | `ButtonGroup` + `Popover` | Composição |
+| **PrimeReact** | `SplitButton` | Componente dedicado |
+| **MUI** | `ButtonGroup` + `Menu` | Composição recomendada |
+| **Chakra UI** | `Menu` + `Button` | Composição |
+| **Mantine** | `Button.Group` + `Menu` | Composição |
+| **Shadcn/ui** | `Button` + `DropdownMenu` | Composição manual |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | AntD | Fluent | Carbon | Blueprint | Prime |
+|------|:----:|:----:|:------:|:------:|:---------:|:-----:|
+| `variant`/`type` | ✓ | ✓ | ✓ | ✓ | `intent` | `severity` |
+| `size` | ✓ | ✓ | ✓ | ✓ | - | ✓ |
+| `disabled` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `loading` | - | ✓ | - | ✓ | `loading` | `loading` |
+| `icon` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `items`/`menu` | ✓ | `menu` | `menu` | `items` | N/A | `model` |
+| `placement` | ✓ | ✓ | - | - | `position` | `appendTo` |
+| `trigger` | - | `trigger` | - | - | - | - |
+| `buttonsRender` | - | ✓ | - | - | - | - |
+| `dropdownRender` | - | ✓ | - | - | - | - |
+
+#### Abordagens de Implementação
+
+**Componente Dedicado (maior ergonomia):**
+- **Ant Design** - `Dropdown.Button` com props `menu` e `onClick`
+- **Fluent UI** - `SplitButton` com `menuProps` e `primaryActionProps`
+- **PrimeReact** - `SplitButton` com `model` array
+- **Carbon** - Combinação com `OverflowMenu`
+
+**Composição Manual (maior flexibilidade):**
+- **MUI** - `ButtonGroup` + `Button` + `Menu`
+- **Chakra** - `Menu` wrapping `Button` + `MenuButton`
+- **Mantine** - `Button.Group` + `Menu`
+- **Shadcn** - `Button` + `DropdownMenu`
+
+**ETUS escolheu:** Componente dedicado (como Ant/Fluent/Prime) para melhor DX, construído sobre primitivos internos (Button + DropdownMenu).
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Elemento | Uso |
+|----------|----------|-----|
+| `aria-haspopup="menu"` | Trigger | Indica que abre menu |
+| `aria-expanded` | Trigger | Estado aberto/fechado |
+| `aria-controls` | Trigger | Referencia o menu |
+| `aria-label` | Trigger | "More options" ou similar |
+| `aria-disabled` | Ambos | Quando `disabled={true}` |
+| `role="menu"` | Dropdown | Semântica de menu |
+| `role="menuitem"` | Items | Semântica de item |
+| `aria-keyshortcuts` | Items | Atalhos de teclado |
+
+### Suporte a Teclado
+
+| Tecla | Contexto | Ação |
+|-------|----------|------|
+| `Tab` | Container | Move foco entre main e trigger |
+| `Enter` | Main button | Ativa ação principal |
+| `Space` | Main button | Ativa ação principal |
+| `Enter` / `Space` | Trigger | Abre menu |
+| `ArrowDown` | Trigger | Abre menu e foca primeiro item |
+| `ArrowUp` | Trigger | Abre menu e foca último item |
+| `ArrowDown` | Menu | Move para próximo item |
+| `ArrowUp` | Menu | Move para item anterior |
+| `Home` | Menu | Move para primeiro item |
+| `End` | Menu | Move para último item |
+| `Enter` / `Space` | Menu item | Seleciona item e fecha menu |
+| `Escape` | Menu | Fecha menu sem selecionar |
+| `Tab` | Menu | Fecha menu e move foco |
+
+### Focus Management
+
+```tsx
+// Focus ring individual em cada botão
+// Não usar focus no container, apenas nos botões internos
+
+// Main button
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+focus-visible:rounded-l-md  // Apenas lado esquerdo
+
+// Trigger button
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+focus-visible:rounded-r-md  // Apenas lado direito
+```
+
+### Screen Readers
+
+- Trigger deve ter `aria-label` descritivo (ex: "Mais opções de salvamento")
+- Items do menu devem anunciar atalhos se disponíveis
+- Separadores devem ser ignorados (`role="separator"` + `aria-hidden`)
+- Estado desabilitado deve ser anunciado
+
+### Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Desabilita animação de abertura do menu */
+  [data-slot="split-button-dropdown"] {
+    animation: none;
+  }
+}
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint | Prime |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|:---------:|:-----:|
+| **ARIA automático** | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ~ | ~ | ~ | ~ | ✓ | ✓ | ✓ | ~ |
+| **Focus management** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ✓ | ~ |
+| **Keyboard nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **aria-expanded** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **aria-haspopup** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Roving tabindex** | - | ✓ | ✓ | ✓ | ✓ | - | ✓ | - | - | - | ✓ | ✓ | ✓ | - |
+| **Type-ahead** | - | ✓ | ✓ | ✓ | ✓ | - | - | - | - | - | ✓ | - | ✓ | - |
+| **Portal support** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Virtualization** | - | - | - | - | - | - | ✓ | - | ✓ | - | ✓ | - | - | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { SplitButton } from "@etus/ui"
+
+function Example() {
+  const items = [
+    {
+      key: "save-as",
+      label: "Salvar como...",
+      onSelect: () => console.log("Save as"),
+    },
+    {
+      key: "export",
+      label: "Exportar",
+      onSelect: () => console.log("Export"),
+    },
+  ]
+
+  return (
+    <SplitButton
+      items={items}
+      onMainClick={() => console.log("Save")}
+    >
+      Salvar
+    </SplitButton>
+  )
+}
+```
+
+### Variantes
+
+```tsx
+<SplitButton variant="default" items={items}>Primary</SplitButton>
+<SplitButton variant="secondary" items={items}>Secondary</SplitButton>
+<SplitButton variant="destructive" items={items}>Delete</SplitButton>
+<SplitButton variant="outline" items={items}>Outline</SplitButton>
+<SplitButton variant="ghost" items={items}>Ghost</SplitButton>
+```
+
+### Tamanhos
+
+```tsx
+<SplitButton size="sm" items={items}>Small</SplitButton>
+<SplitButton size="default" items={items}>Default</SplitButton>
+<SplitButton size="lg" items={items}>Large</SplitButton>
+```
+
+### Com Ícones e Atalhos
+
+```tsx
+import { Save, FileDown, FileText, FilePdf } from "lucide-react"
+
+const items = [
+  {
+    key: "save-as",
+    label: "Salvar como...",
+    icon: <Save />,
+    shortcut: "Ctrl+Shift+S",
+    onSelect: handleSaveAs,
+  },
+  { key: "sep-1", type: "separator" },
+  {
+    key: "export-pdf",
+    label: "Exportar como PDF",
+    icon: <FilePdf />,
+    onSelect: handleExportPdf,
+  },
+  {
+    key: "export-doc",
+    label: "Exportar como DOC",
+    icon: <FileText />,
+    onSelect: handleExportDoc,
+  },
+]
+
+<SplitButton items={items} onMainClick={handleSave}>
+  <FileDown />
+  Salvar
+</SplitButton>
+```
+
+### Items Destrutivos
+
+```tsx
+const items = [
+  {
+    key: "archive",
+    label: "Arquivar",
+    onSelect: handleArchive,
+  },
+  { key: "sep-1", type: "separator" },
+  {
+    key: "delete",
+    label: "Excluir permanentemente",
+    destructive: true,
+    onSelect: handleDelete,
+  },
+]
+
+<SplitButton variant="destructive" items={items}>
+  Remover
+</SplitButton>
+```
+
+### Estado Controlado
+
+```tsx
+function ControlledExample() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <SplitButton
+      items={items}
+      open={open}
+      onOpenChange={setOpen}
+      onMainClick={() => {
+        console.log("Main action")
+        setOpen(false)
+      }}
+    >
+      Ação
+    </SplitButton>
+  )
+}
+```
+
+### Posicionamento do Menu
+
+```tsx
+// Menu acima
+<SplitButton items={items} side="top" align="end">
+  Salvar
+</SplitButton>
+
+// Menu alinhado ao início
+<SplitButton items={items} side="bottom" align="start">
+  Salvar
+</SplitButton>
+```
+
+### Estado Desabilitado
+
+```tsx
+<SplitButton items={items} disabled>
+  Desabilitado
+</SplitButton>
+```
+
+### Composição em Formulário
+
+```tsx
+function FormActions() {
+  const { formState } = useFormContext()
+  const { isSubmitting, isDirty } = formState
+
+  const saveOptions = [
+    {
+      key: "save-draft",
+      label: "Salvar rascunho",
+      shortcut: "Ctrl+D",
+      onSelect: handleSaveDraft,
+    },
+    {
+      key: "save-publish",
+      label: "Salvar e publicar",
+      shortcut: "Ctrl+Shift+P",
+      onSelect: handleSaveAndPublish,
+    },
+  ]
+
+  return (
+    <SplitButton
+      items={saveOptions}
+      disabled={!isDirty || isSubmitting}
+      onMainClick={handleSave}
+    >
+      {isSubmitting ? (
+        <>
+          <Loader2 className="animate-spin" />
+          Salvando...
+        </>
+      ) : (
+        "Salvar"
+      )}
+    </SplitButton>
+  )
+}
+```
+
+### Responsividade
+
+```tsx
+// Ocultar trigger em mobile
+<div className="flex">
+  <Button className="sm:hidden">Salvar</Button>
+  <SplitButton items={items} className="hidden sm:inline-flex">
+    Salvar
+  </SplitButton>
+</div>
+
+// Full width em mobile
+<SplitButton
+  items={items}
+  className="w-full sm:w-auto"
+  mainClassName="flex-1"
+>
+  Enviar
+</SplitButton>
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// SplitButton.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { SplitButton } from "./SplitButton"
+
+const defaultItems = [
+  { key: "option-1", label: "Option 1", onSelect: vi.fn() },
+  { key: "option-2", label: "Option 2", onSelect: vi.fn() },
+]
+
+describe("SplitButton", () => {
+  it("renders main button with children", () => {
+    render(<SplitButton items={defaultItems}>Save</SplitButton>)
+    expect(screen.getByRole("button", { name: /save/i })).toBeInTheDocument()
+  })
+
+  it("renders trigger button", () => {
+    render(<SplitButton items={defaultItems}>Save</SplitButton>)
+    expect(screen.getByRole("button", { name: /more options/i })).toBeInTheDocument()
+  })
+
+  it("applies variant classes to both buttons", () => {
+    render(
+      <SplitButton items={defaultItems} variant="destructive">
+        Delete
+      </SplitButton>
+    )
+    const buttons = screen.getAllByRole("button")
+    buttons.forEach(btn => {
+      expect(btn).toHaveClass("bg-destructive")
+    })
+  })
+
+  it("has data-slot attributes", () => {
+    const { container } = render(
+      <SplitButton items={defaultItems}>Save</SplitButton>
+    )
+    expect(container.querySelector('[data-slot="split-button"]')).toBeInTheDocument()
+    expect(container.querySelector('[data-slot="split-button-main"]')).toBeInTheDocument()
+    expect(container.querySelector('[data-slot="split-button-trigger"]')).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Interação
+
+```tsx
+describe("SplitButton interactions", () => {
+  it("calls onMainClick when main button is clicked", async () => {
+    const user = userEvent.setup()
+    const handleClick = vi.fn()
+
+    render(
+      <SplitButton items={defaultItems} onMainClick={handleClick}>
+        Save
+      </SplitButton>
+    )
+
+    await user.click(screen.getByRole("button", { name: /save/i }))
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it("opens menu when trigger is clicked", async () => {
+    const user = userEvent.setup()
+
+    render(<SplitButton items={defaultItems}>Save</SplitButton>)
+
+    await user.click(screen.getByRole("button", { name: /more options/i }))
+    expect(screen.getByRole("menu")).toBeInTheDocument()
+  })
+
+  it("calls item onSelect when menu item is clicked", async () => {
+    const user = userEvent.setup()
+    const handleSelect = vi.fn()
+
+    const items = [
+      { key: "option-1", label: "Option 1", onSelect: handleSelect },
+    ]
+
+    render(<SplitButton items={items}>Save</SplitButton>)
+
+    await user.click(screen.getByRole("button", { name: /more options/i }))
+    await user.click(screen.getByRole("menuitem", { name: /option 1/i }))
+
+    expect(handleSelect).toHaveBeenCalledTimes(1)
+  })
+
+  it("closes menu after selecting item", async () => {
+    const user = userEvent.setup()
+
+    render(<SplitButton items={defaultItems}>Save</SplitButton>)
+
+    await user.click(screen.getByRole("button", { name: /more options/i }))
+    await user.click(screen.getByRole("menuitem", { name: /option 1/i }))
+
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Teclado
+
+```tsx
+describe("SplitButton keyboard navigation", () => {
+  it("opens menu with ArrowDown on trigger", async () => {
+    const user = userEvent.setup()
+
+    render(<SplitButton items={defaultItems}>Save</SplitButton>)
+
+    screen.getByRole("button", { name: /more options/i }).focus()
+    await user.keyboard("{ArrowDown}")
+
+    expect(screen.getByRole("menu")).toBeInTheDocument()
+  })
+
+  it("closes menu with Escape", async () => {
+    const user = userEvent.setup()
+
+    render(<SplitButton items={defaultItems}>Save</SplitButton>)
+
+    await user.click(screen.getByRole("button", { name: /more options/i }))
+    expect(screen.getByRole("menu")).toBeInTheDocument()
+
+    await user.keyboard("{Escape}")
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument()
+  })
+
+  it("navigates items with arrow keys", async () => {
+    const user = userEvent.setup()
+
+    render(<SplitButton items={defaultItems}>Save</SplitButton>)
+
+    await user.click(screen.getByRole("button", { name: /more options/i }))
+    await user.keyboard("{ArrowDown}")
+
+    expect(screen.getByRole("menuitem", { name: /option 1/i })).toHaveFocus()
+
+    await user.keyboard("{ArrowDown}")
+    expect(screen.getByRole("menuitem", { name: /option 2/i })).toHaveFocus()
+  })
+
+  it("selects item with Enter", async () => {
+    const user = userEvent.setup()
+    const handleSelect = vi.fn()
+
+    const items = [
+      { key: "option-1", label: "Option 1", onSelect: handleSelect },
+    ]
+
+    render(<SplitButton items={items}>Save</SplitButton>)
+
+    await user.click(screen.getByRole("button", { name: /more options/i }))
+    await user.keyboard("{ArrowDown}")
+    await user.keyboard("{Enter}")
+
+    expect(handleSelect).toHaveBeenCalled()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("SplitButton accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <SplitButton items={defaultItems}>Save</SplitButton>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("trigger has aria-haspopup", () => {
+    render(<SplitButton items={defaultItems}>Save</SplitButton>)
+    const trigger = screen.getByRole("button", { name: /more options/i })
+    expect(trigger).toHaveAttribute("aria-haspopup", "menu")
+  })
+
+  it("trigger has aria-expanded when open", async () => {
+    const user = userEvent.setup()
+
+    render(<SplitButton items={defaultItems}>Save</SplitButton>)
+
+    const trigger = screen.getByRole("button", { name: /more options/i })
+    expect(trigger).toHaveAttribute("aria-expanded", "false")
+
+    await user.click(trigger)
+    expect(trigger).toHaveAttribute("aria-expanded", "true")
+  })
+
+  it("disabled state is accessible", () => {
+    render(
+      <SplitButton items={defaultItems} disabled>
+        Save
+      </SplitButton>
+    )
+
+    const buttons = screen.getAllByRole("button")
+    buttons.forEach(btn => {
+      expect(btn).toBeDisabled()
+    })
+  })
+})
+```
+
+### Testes de Estado Controlado
+
+```tsx
+describe("SplitButton controlled state", () => {
+  it("respects controlled open state", async () => {
+    const user = userEvent.setup()
+
+    const { rerender } = render(
+      <SplitButton items={defaultItems} open={false}>
+        Save
+      </SplitButton>
+    )
+
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument()
+
+    rerender(
+      <SplitButton items={defaultItems} open={true}>
+        Save
+      </SplitButton>
+    )
+
+    expect(screen.getByRole("menu")).toBeInTheDocument()
+  })
+
+  it("calls onOpenChange", async () => {
+    const user = userEvent.setup()
+    const handleOpenChange = vi.fn()
+
+    render(
+      <SplitButton items={defaultItems} onOpenChange={handleOpenChange}>
+        Save
+      </SplitButton>
+    )
+
+    await user.click(screen.getByRole("button", { name: /more options/i }))
+    expect(handleOpenChange).toHaveBeenCalledWith(true)
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### Prioridade Alta
+
+#### `loading` + `loadingText`
+
+Estado de carregamento no botão principal.
+
+```tsx
+// Proposta de API
+interface SplitButtonProps {
+  loading?: boolean
+  loadingText?: string
+}
+
+// Uso
+<SplitButton loading items={items}>Salvando...</SplitButton>
+<SplitButton loading loadingText="Processando..." items={items}>Enviar</SplitButton>
+```
+
+**Referências:** AntD (`loading`), Prime (`loading`), Carbon (`loading`)
+
+#### `icon` prop dedicada
+
+Prop para ícone no botão principal, sem necessidade de composição.
+
+```tsx
+// Proposta de API
+interface SplitButtonProps {
+  icon?: ReactNode
+}
+
+// Uso
+<SplitButton icon={<Save />} items={items}>Salvar</SplitButton>
+```
+
+**Referências:** AntD (`icon`), Fluent (`icon`), Prime (`icon`)
+
+### Prioridade Média
+
+#### Submenus (Nested Menus)
+
+Suporte a menus aninhados para hierarquias complexas.
+
+```tsx
+// Proposta de API
+interface SplitButtonItem {
+  // ... props existentes
+  items?: SplitButtonMenuItem[] // Submenu
+}
+
+// Uso
+const items = [
+  {
+    key: "export",
+    label: "Exportar",
+    items: [
+      { key: "pdf", label: "PDF", onSelect: handlePdf },
+      { key: "csv", label: "CSV", onSelect: handleCsv },
+    ],
+  },
+]
+```
+
+**Referências:** Radix, MUI, AntD, Fluent, Blueprint, Prime
+
+#### `buttonsRender` / `dropdownRender`
+
+Customização avançada dos elementos internos.
+
+```tsx
+// Proposta de API
+interface SplitButtonProps {
+  buttonsRender?: (buttons: [ReactNode, ReactNode]) => ReactNode
+  dropdownRender?: (menu: ReactNode) => ReactNode
+}
+```
+
+**Referências:** AntD (`buttonsRender`, `dropdownRender`)
+
+### Prioridade Baixa
+
+#### `trigger` customizável
+
+Controle sobre como o menu é acionado.
+
+```tsx
+// Proposta de API
+interface SplitButtonProps {
+  trigger?: "click" | "hover" | "contextMenu" | ("click" | "hover")[]
+}
+```
+
+**Referências:** AntD (`trigger`)
+
+#### Type-ahead search
+
+Busca por digitação no menu aberto.
+
+```tsx
+// Comportamento: usuário digita "ex" → foca em "Exportar"
+```
+
+**Referências:** React Aria, Radix, Ariakit, Headless UI, Fluent, Blueprint
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `loading` | ✓ Implementar | Alta demanda, UX essencial |
+| `icon` prop | ✓ Implementar | Ergonomia, consistência com Button |
+| Submenus | ⚠ Avaliar | Complexidade vs. frequência de uso |
+| `buttonsRender` | ❌ Evitar | Muito específico, usar slots |
+| `trigger` hover | ❌ Evitar | UX mobile ruim, a11y complexa |
+| Type-ahead | ✓ Implementar | Herda do DropdownMenu |
+
+---
+
+## Implementação Sugerida
+
+```tsx
+// SplitButton.tsx
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { ChevronDown } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+import { Button, buttonVariants } from "../Button"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "../../compounds/DropdownMenu"
+
+const splitButtonVariants = cva(
+  "inline-flex items-center rounded-md",
+  {
+    variants: {
+      variant: {
+        default: "",
+        secondary: "",
+        destructive: "",
+        outline: "",
+        ghost: "",
+      },
+      size: {
+        default: "",
+        sm: "",
+        lg: "",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+interface SplitButtonItem {
+  key: string
+  label: React.ReactNode
+  icon?: React.ReactNode
+  shortcut?: string
+  disabled?: boolean
+  destructive?: boolean
+  onSelect: () => void
+}
+
+interface SplitButtonSeparator {
+  key: string
+  type: "separator"
+}
+
+type SplitButtonMenuItem = SplitButtonItem | SplitButtonSeparator
+
+interface SplitButtonProps
+  extends Omit<React.ComponentProps<"div">, "children">,
+    VariantProps<typeof splitButtonVariants> {
+  children: React.ReactNode
+  items: SplitButtonMenuItem[]
+  onMainClick?: () => void
+  defaultOpen?: boolean
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  side?: "top" | "bottom" | "left" | "right"
+  align?: "start" | "center" | "end"
+  mainClassName?: string
+  triggerClassName?: string
+  disabled?: boolean
+}
+
+function SplitButton({
+  className,
+  variant = "default",
+  size = "default",
+  children,
+  items,
+  onMainClick,
+  defaultOpen,
+  open,
+  onOpenChange,
+  side = "bottom",
+  align = "end",
+  mainClassName,
+  triggerClassName,
+  disabled,
+  ref,
+  ...props
+}: SplitButtonProps) {
+  return (
+    <div
+      ref={ref}
+      data-slot="split-button"
+      className={cn(splitButtonVariants({ variant, size }), className)}
+      {...props}
+    >
+      <Button
+        data-slot="split-button-main"
+        variant={variant}
+        size={size}
+        disabled={disabled}
+        onClick={onMainClick}
+        className={cn("rounded-r-none border-r-0", mainClassName)}
+      >
+        {children}
+      </Button>
+
+      <DropdownMenu
+        defaultOpen={defaultOpen}
+        open={open}
+        onOpenChange={onOpenChange}
+      >
+        <DropdownMenuTrigger asChild>
+          <Button
+            data-slot="split-button-trigger"
+            variant={variant}
+            size={size === "lg" ? "icon-lg" : size === "sm" ? "icon-sm" : "icon"}
+            disabled={disabled}
+            aria-label="More options"
+            className={cn(
+              "rounded-l-none border-l border-l-primary-foreground/20",
+              triggerClassName
+            )}
+          >
+            <ChevronDown data-slot="split-button-icon" />
+          </Button>
+        </DropdownMenuTrigger>
+
+        <DropdownMenuContent side={side} align={align}>
+          {items.map((item) => {
+            if ("type" in item && item.type === "separator") {
+              return <DropdownMenuSeparator key={item.key} />
+            }
+
+            const menuItem = item as SplitButtonItem
+
+            return (
+              <DropdownMenuItem
+                key={menuItem.key}
+                disabled={menuItem.disabled}
+                onSelect={menuItem.onSelect}
+                className={cn(
+                  menuItem.destructive && "text-destructive focus:text-destructive"
+                )}
+              >
+                {menuItem.icon && (
+                  <span className="mr-2">{menuItem.icon}</span>
+                )}
+                <span className="flex-1">{menuItem.label}</span>
+                {menuItem.shortcut && (
+                  <span className="ml-auto text-xs text-muted-foreground">
+                    {menuItem.shortcut}
+                  </span>
+                )}
+              </DropdownMenuItem>
+            )
+          })}
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  )
+}
+
+export { SplitButton, splitButtonVariants }
+export type { SplitButtonProps, SplitButtonItem, SplitButtonMenuItem }
+```
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação | GitHub |
+|---------------|--------------|--------|
+| **Ant Design** | [Dropdown.Button](https://ant.design/components/dropdown#dropdownbutton) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **Fluent UI** | [SplitButton](https://react.fluentui.dev/?path=/docs/components-button-splitbutton--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [ComboButton](https://carbondesignsystem.com/components/combo-button/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [ButtonGroup + Popover](https://blueprintjs.com/docs/#core/components/button-group) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | [SplitButton](https://primereact.org/splitbutton/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+| **MUI** | [ButtonGroup](https://mui.com/material-ui/react-button-group/#split-button) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Chakra UI** | [Menu + Button](https://chakra-ui.com/docs/components/menu) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **Mantine** | [Button.Group + Menu](https://mantine.dev/core/button/#buttongroup) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Shadcn/ui** | [Button + DropdownMenu](https://ui.shadcn.com/docs/components/dropdown-menu) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [DropdownMenu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **React Aria** | [MenuTrigger](https://react-spectrum.adobe.com/react-aria/MenuTrigger.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Ariakit** | [Menu](https://ariakit.org/components/menu) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Headless UI** | [Menu](https://headlessui.com/react/menu) | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **NextUI** | [Dropdown](https://nextui.org/docs/components/dropdown) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Menu Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/)
+- [WAI-ARIA APG - Menu Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Radix DropdownMenu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu)
+- [Lucide Icons](https://lucide.dev/icons/)