@etus/ui 0.1.0

package/src/components/navigation/Menu/README.md

@@ -0,0 +1,599 @@
+# Menu
+
+## Visão Geral
+
+O Menu e um componente base que fornece uma lista de opcoes navegaveis por teclado. Serve como fundacao para componentes mais especificos como DropdownMenu, ContextMenu e Menubar. E ideal para criar menus customizados ou listas de acoes com acessibilidade completa.
+
+### Classificacao Atomica
+- **Categoria**: Molecules
+- **Subcategoria**: Navigation
+
+### Casos de Uso Comuns
+- Listas de acoes em paineis laterais
+- Menus de navegacao vertical
+- Listas de comandos com atalhos
+- Menus de selecao customizados
+- Paletas de comandos (command palette)
+
+### Relacao com Outros Componentes
+- **DropdownMenu**: Usa Menu internamente com trigger popup
+- **ContextMenu**: Menu acionado por clique direito
+- **Menubar**: Barra horizontal de menus
+- **Command**: Menu com busca integrada
+- **NavigationMenu**: Para navegacao principal
+
+## Design Specs
+
+### Estrutura
+
+```
+Menu
+├── MenuGroup (opcional)
+│   ├── MenuLabel
+│   └── MenuItem[]
+├── MenuSeparator
+└── MenuItem[]
+    ├── [Icon]
+    ├── Label
+    └── [Shortcut]
+```
+
+### Variantes de Item
+
+| Variante | Descricao | Uso |
+|----------|-----------|-----|
+| `default` | Estilo padrao | Acoes normais |
+| `destructive` | Vermelho/perigo | Acoes destrutivas |
+| `disabled` | Desabilitado | Opcoes indisponiveis |
+
+### Estados
+
+- **Default**: Background transparente
+- **Hover**: `bg-accent text-accent-foreground`
+- **Focus**: Ring de foco visivel
+- **Active**: `bg-accent/80`
+- **Disabled**: `opacity-50 pointer-events-none`
+- **Selected**: Indicador visual (check, background)
+
+### Tokens de Design
+
+#### Cores
+- Background: `bg-background` ou `bg-popover`
+- Item hover: `bg-accent`
+- Text: `text-foreground`
+- Muted: `text-muted-foreground`
+- Destructive: `text-destructive`
+- Border: `border-border`
+
+#### Espacamento
+- Menu padding: `p-1` ou `p-2`
+- Item padding: `px-2 py-1.5` ou `px-3 py-2`
+- Item gap: `gap-2`
+- Group gap: `gap-1`
+
+#### Tipografia
+- Items: `text-sm`
+- Labels: `text-xs font-medium uppercase tracking-wider`
+- Shortcuts: `text-xs text-muted-foreground`
+
+#### Bordas
+- Menu: `rounded-md` ou `rounded-lg`
+- Items: `rounded-sm`
+- Separator: `h-px bg-border`
+
+#### Icones
+- Size: `size-4` (16px)
+- Color: `text-muted-foreground` ou herda
+
+### Consideracoes de Responsividade
+- Menu se adapta ao container pai
+- Em mobile, considerar items maiores (min 44px altura)
+- Touch targets adequados
+- Scroll interno se necessario
+
+## API
+
+### Componentes Sugeridos
+
+#### Menu
+Container principal do menu.
+
+```typescript
+interface MenuProps extends React.ComponentProps<"div"> {
+  /** Orientacao do menu */
+  orientation?: "vertical" | "horizontal"
+  /** Se o menu e parte de um grupo maior */
+  role?: "menu" | "menubar" | "listbox"
+}
+```
+
+#### MenuGroup
+Agrupa items relacionados.
+
+```typescript
+interface MenuGroupProps extends React.ComponentProps<"div"> {
+  /** ID do grupo para acessibilidade */
+  id?: string
+}
+```
+
+#### MenuLabel
+Label para um grupo de items.
+
+```typescript
+interface MenuLabelProps extends React.ComponentProps<"div"> {
+  /** Se deve ter padding extra para alinhar com items com icone */
+  inset?: boolean
+}
+```
+
+#### MenuItem
+Item individual do menu.
+
+```typescript
+interface MenuItemProps extends React.ComponentProps<"button"> {
+  /** Variante visual */
+  variant?: "default" | "destructive"
+  /** Se deve ter padding extra para alinhar com items com icone */
+  inset?: boolean
+  /** Se o item esta selecionado */
+  selected?: boolean
+  /** Callback quando selecionado */
+  onSelect?: () => void
+  /** Desabilita o item */
+  disabled?: boolean
+}
+```
+
+#### MenuSeparator
+Divisor entre grupos ou items.
+
+```typescript
+interface MenuSeparatorProps extends React.ComponentProps<"div"> {}
+```
+
+#### MenuShortcut
+Exibe atalho de teclado.
+
+```typescript
+interface MenuShortcutProps extends React.ComponentProps<"span"> {}
+```
+
+### Interfaces TypeScript
+
+```typescript
+import type { ComponentProps, ReactNode } from "react"
+
+export interface MenuProps extends ComponentProps<"div"> {
+  orientation?: "vertical" | "horizontal"
+  onValueChange?: (value: string) => void
+  value?: string
+  defaultValue?: string
+}
+
+export interface MenuItemProps extends ComponentProps<"button"> {
+  variant?: "default" | "destructive"
+  inset?: boolean
+  selected?: boolean
+  value?: string
+  onSelect?: () => void
+  disabled?: boolean
+  asChild?: boolean
+}
+
+export interface MenuGroupProps extends ComponentProps<"div"> {
+  label?: string
+}
+
+export interface MenuLabelProps extends ComponentProps<"div"> {
+  inset?: boolean
+}
+
+export interface MenuSeparatorProps extends ComponentProps<"div"> {}
+
+export interface MenuShortcutProps extends ComponentProps<"span"> {}
+```
+
+### Comparacao com Referencias
+
+| Feature | ETUS | Radix | Ariakit | Headless UI | React Aria |
+|---------|------|-------|---------|-------------|------------|
+| Keyboard Nav | Sim | Sim | Sim | Sim | Sim |
+| Type-ahead | Sim | Sim | Sim | Nao | Sim |
+| Groups | Sim | Sim | Sim | Sim | Sim |
+| Separators | Sim | Sim | Sim | Sim | Sim |
+| Nested | Sim | Sim | Sim | Sim | Sim |
+| Shortcuts | Sim | Nao | Nao | Nao | Nao |
+| Variants | Sim | Nao | Nao | Nao | Nao |
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="menu"`: No container do menu
+- `role="menuitem"`: Nos items
+- `role="separator"`: Nos separadores
+- `role="group"`: Nos grupos
+- `aria-disabled`: Items desabilitados
+- `aria-current` ou `aria-selected`: Item selecionado
+- `aria-labelledby`: Referencia label do grupo
+
+### Navegacao por Teclado
+- `Arrow Down/Up`: Navega entre items (vertical)
+- `Arrow Right/Left`: Navega (horizontal) ou abre submenu
+- `Enter/Space`: Seleciona item
+- `Home/End`: Primeiro/ultimo item
+- `Escape`: Fecha menu (se em popup)
+- `A-Z`: Type-ahead para navegacao rapida
+
+### Contraste e Legibilidade
+- Contraste WCAG AA em todos os estados
+- Focus ring visivel (`ring-2 ring-ring`)
+- Tamanho minimo de fonte 14px
+
+### Tecnologias Assistivas
+- Menu anunciado como "menu"
+- Items anunciados com papel
+- Estado de selecao anunciado
+- Grupos e labels anunciados
+
+### Conformidade WCAG
+- **Nivel alvo**: WCAG 2.1 AA
+- **Criterios**:
+  - 1.3.1 Info and Relationships
+  - 2.1.1 Keyboard
+  - 2.4.3 Focus Order
+  - 4.1.2 Name, Role, Value
+
+## Exemplos
+
+### Menu Basico
+
+```tsx
+import { Menu, MenuItem, MenuSeparator } from "@etus/ui"
+
+function BasicMenu() {
+  return (
+    <Menu className="w-56 border rounded-lg p-1">
+      <MenuItem onSelect={() => console.log("Edit")}>
+        Edit
+      </MenuItem>
+      <MenuItem onSelect={() => console.log("Duplicate")}>
+        Duplicate
+      </MenuItem>
+      <MenuItem onSelect={() => console.log("Archive")}>
+        Archive
+      </MenuItem>
+      <MenuSeparator />
+      <MenuItem variant="destructive" onSelect={() => console.log("Delete")}>
+        Delete
+      </MenuItem>
+    </Menu>
+  )
+}
+```
+
+### Menu com Icones e Atalhos
+
+```tsx
+import { Menu, MenuItem, MenuShortcut, MenuSeparator } from "@etus/ui"
+import { Copy, Scissors, Clipboard, Trash2 } from "lucide-react"
+
+function MenuWithIcons() {
+  return (
+    <Menu className="w-56 border rounded-lg p-1">
+      <MenuItem>
+        <Scissors className="mr-2 h-4 w-4" />
+        Cut
+        <MenuShortcut>Ctrl+X</MenuShortcut>
+      </MenuItem>
+      <MenuItem>
+        <Copy className="mr-2 h-4 w-4" />
+        Copy
+        <MenuShortcut>Ctrl+C</MenuShortcut>
+      </MenuItem>
+      <MenuItem>
+        <Clipboard className="mr-2 h-4 w-4" />
+        Paste
+        <MenuShortcut>Ctrl+V</MenuShortcut>
+      </MenuItem>
+      <MenuSeparator />
+      <MenuItem variant="destructive">
+        <Trash2 className="mr-2 h-4 w-4" />
+        Delete
+        <MenuShortcut>Del</MenuShortcut>
+      </MenuItem>
+    </Menu>
+  )
+}
+```
+
+### Menu com Grupos
+
+```tsx
+import { Menu, MenuItem, MenuGroup, MenuLabel, MenuSeparator } from "@etus/ui"
+import { User, Settings, CreditCard, HelpCircle, LogOut } from "lucide-react"
+
+function GroupedMenu() {
+  return (
+    <Menu className="w-56 border rounded-lg p-1">
+      <MenuGroup>
+        <MenuLabel>Account</MenuLabel>
+        <MenuItem>
+          <User className="mr-2 h-4 w-4" />
+          Profile
+        </MenuItem>
+        <MenuItem>
+          <Settings className="mr-2 h-4 w-4" />
+          Settings
+        </MenuItem>
+        <MenuItem>
+          <CreditCard className="mr-2 h-4 w-4" />
+          Billing
+        </MenuItem>
+      </MenuGroup>
+      <MenuSeparator />
+      <MenuGroup>
+        <MenuLabel>Support</MenuLabel>
+        <MenuItem>
+          <HelpCircle className="mr-2 h-4 w-4" />
+          Help Center
+        </MenuItem>
+      </MenuGroup>
+      <MenuSeparator />
+      <MenuItem variant="destructive">
+        <LogOut className="mr-2 h-4 w-4" />
+        Logout
+      </MenuItem>
+    </Menu>
+  )
+}
+```
+
+### Menu de Navegacao Lateral
+
+```tsx
+import { Menu, MenuItem } from "@etus/ui"
+import { Home, Inbox, Calendar, Settings, Users, BarChart } from "lucide-react"
+
+function SidebarMenu() {
+  const [active, setActive] = useState("home")
+
+  const items = [
+    { id: "home", icon: Home, label: "Home" },
+    { id: "inbox", icon: Inbox, label: "Inbox", badge: 5 },
+    { id: "calendar", icon: Calendar, label: "Calendar" },
+    { id: "analytics", icon: BarChart, label: "Analytics" },
+    { id: "team", icon: Users, label: "Team" },
+    { id: "settings", icon: Settings, label: "Settings" },
+  ]
+
+  return (
+    <Menu className="w-64 p-2 space-y-1">
+      {items.map((item) => (
+        <MenuItem
+          key={item.id}
+          selected={active === item.id}
+          onSelect={() => setActive(item.id)}
+          className="w-full justify-start"
+        >
+          <item.icon className="mr-3 h-4 w-4" />
+          {item.label}
+          {item.badge && (
+            <span className="ml-auto bg-primary text-primary-foreground text-xs px-2 py-0.5 rounded-full">
+              {item.badge}
+            </span>
+          )}
+        </MenuItem>
+      ))}
+    </Menu>
+  )
+}
+```
+
+### Menu com Selecao
+
+```tsx
+import { useState } from "react"
+import { Menu, MenuItem, MenuLabel, MenuSeparator } from "@etus/ui"
+import { Check } from "lucide-react"
+
+function SelectableMenu() {
+  const [selected, setSelected] = useState("option-1")
+
+  const options = [
+    { id: "option-1", label: "Option 1" },
+    { id: "option-2", label: "Option 2" },
+    { id: "option-3", label: "Option 3" },
+  ]
+
+  return (
+    <Menu className="w-48 border rounded-lg p-1">
+      <MenuLabel>Select an option</MenuLabel>
+      <MenuSeparator />
+      {options.map((option) => (
+        <MenuItem
+          key={option.id}
+          selected={selected === option.id}
+          onSelect={() => setSelected(option.id)}
+        >
+          <span className="w-4 mr-2">
+            {selected === option.id && <Check className="h-4 w-4" />}
+          </span>
+          {option.label}
+        </MenuItem>
+      ))}
+    </Menu>
+  )
+}
+```
+
+### Menu com Submenu
+
+```tsx
+import { Menu, MenuItem, MenuSeparator } from "@etus/ui"
+import { ChevronRight, Share, Mail, Link, MessageSquare } from "lucide-react"
+
+function MenuWithSubmenu() {
+  const [showShareSubmenu, setShowShareSubmenu] = useState(false)
+
+  return (
+    <Menu className="w-56 border rounded-lg p-1">
+      <MenuItem>Edit</MenuItem>
+      <MenuItem>Duplicate</MenuItem>
+      <div className="relative">
+        <MenuItem
+          onMouseEnter={() => setShowShareSubmenu(true)}
+          onMouseLeave={() => setShowShareSubmenu(false)}
+        >
+          <Share className="mr-2 h-4 w-4" />
+          Share
+          <ChevronRight className="ml-auto h-4 w-4" />
+        </MenuItem>
+        {showShareSubmenu && (
+          <Menu
+            className="absolute left-full top-0 ml-1 w-48 border rounded-lg p-1"
+            onMouseEnter={() => setShowShareSubmenu(true)}
+            onMouseLeave={() => setShowShareSubmenu(false)}
+          >
+            <MenuItem>
+              <Mail className="mr-2 h-4 w-4" />
+              Email
+            </MenuItem>
+            <MenuItem>
+              <MessageSquare className="mr-2 h-4 w-4" />
+              Message
+            </MenuItem>
+            <MenuItem>
+              <Link className="mr-2 h-4 w-4" />
+              Copy Link
+            </MenuItem>
+          </Menu>
+        )}
+      </div>
+      <MenuSeparator />
+      <MenuItem variant="destructive">Delete</MenuItem>
+    </Menu>
+  )
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+- Renderizacao de items
+- Aplicacao de variantes
+- Estados selected/disabled
+
+#### Testes de Integracao
+- Navegacao por teclado
+- Callbacks de selecao
+- Grupos e separadores
+
+#### Testes de Acessibilidade
+- Roles ARIA corretos
+- Keyboard navigation
+- Screen reader announcements
+
+### Exemplos de Codigo
+
+```typescript
+import { describe, it, expect, vi } from "vitest"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { Menu, MenuItem, MenuSeparator, MenuLabel } from "./Menu"
+
+describe("Menu", () => {
+  it("renders menu items", () => {
+    render(
+      <Menu>
+        <MenuItem>Item 1</MenuItem>
+        <MenuItem>Item 2</MenuItem>
+      </Menu>
+    )
+
+    expect(screen.getByRole("menu")).toBeInTheDocument()
+    expect(screen.getAllByRole("menuitem")).toHaveLength(2)
+  })
+
+  it("navigates with arrow keys", async () => {
+    render(
+      <Menu>
+        <MenuItem>Item 1</MenuItem>
+        <MenuItem>Item 2</MenuItem>
+        <MenuItem>Item 3</MenuItem>
+      </Menu>
+    )
+
+    const items = screen.getAllByRole("menuitem")
+    items[0].focus()
+
+    await userEvent.keyboard("{ArrowDown}")
+    expect(items[1]).toHaveFocus()
+
+    await userEvent.keyboard("{ArrowDown}")
+    expect(items[2]).toHaveFocus()
+
+    await userEvent.keyboard("{ArrowUp}")
+    expect(items[1]).toHaveFocus()
+  })
+
+  it("calls onSelect when item is clicked", async () => {
+    const onSelect = vi.fn()
+
+    render(
+      <Menu>
+        <MenuItem onSelect={onSelect}>Item 1</MenuItem>
+      </Menu>
+    )
+
+    await userEvent.click(screen.getByText("Item 1"))
+    expect(onSelect).toHaveBeenCalled()
+  })
+
+  it("disables items correctly", () => {
+    render(
+      <Menu>
+        <MenuItem disabled>Disabled Item</MenuItem>
+      </Menu>
+    )
+
+    expect(screen.getByText("Disabled Item")).toHaveAttribute(
+      "aria-disabled",
+      "true"
+    )
+  })
+
+  it("renders separator with correct role", () => {
+    render(
+      <Menu>
+        <MenuItem>Item 1</MenuItem>
+        <MenuSeparator data-testid="separator" />
+        <MenuItem>Item 2</MenuItem>
+      </Menu>
+    )
+
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "role",
+      "separator"
+    )
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Pode ser construido sobre Radix Primitives ou React Aria
+- Gerenciamento de foco via roving tabindex ou aria-activedescendant
+- Type-ahead busca items pelo texto
+- Considerar virtualizacao para listas muito longas
+
+## Referências
+
+- [WAI-ARIA Menu Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/)
+- [Radix UI Menu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu)
+- [React Aria Menu](https://react-spectrum.adobe.com/react-aria/Menu.html)
+- [Ariakit Menu](https://ariakit.org/components/menu)

package/src/components/navigation/Menu/index.ts

@@ -0,0 +1,17 @@
+export * from './Menu'
+export {
+  menuGroupVariants,
+  menuItemVariants,
+  menuLabelVariants,
+  menuSeparatorVariants,
+  menuShortcutVariants,
+  menuVariants,
+} from './Menu.variants'
+export type {
+  MenuGroupProps,
+  MenuItemProps,
+  MenuLabelProps,
+  MenuProps,
+  MenuSeparatorProps,
+  MenuShortcutProps,
+} from './Menu.types'