Menu

Quando usarWhen to use

Use Menu quandoUse Menu when

A interface precisa apresentar comandos, atalhos ou ações de um objeto. Para um trigger completo, use o padrão Action Menu.The interface needs to present commands, shortcuts, or object actions. For a complete trigger pattern, use Action Menu.

Não use Menu quandoDon't use Menu when

O usuário está escolhendo um valor de formulário; nesse caso use Select, Radio ou Checkbox. Se houver busca ou edição de texto, use Combobox.The user is choosing a form value; use Select, Radio, or Checkbox instead. If search or text entry is required, use Combobox.

AnatomiaAnatomy

1 Item (.ds-menu__item) — comando acionável com label obrigatório.
2 Ícone (.ds-menu__icon) — opcional, decorativo quando o texto já nomeia a ação.
3 Shortcut (.ds-menu__shortcut) — opcional, apenas informativo.
4 Separator (.ds-menu__separator) — separa grupos de ações relacionadas. 1 Item (.ds-menu__item) — actionable command with a required label.
2 Icon (.ds-menu__icon) — optional and decorative when text already names the action.
3 Shortcut (.ds-menu__shortcut) — optional and informational only.
4 Separator (.ds-menu__separator) — separates related action groups.

PadrãoDefault

<div class="ds-menu" role="menu" aria-label="File actions">
  <button class="ds-menu__item" role="menuitem" type="button">
    <span class="ds-menu__item-label">Rename file</span>
  </button>
  <div class="ds-menu__separator" role="separator"></div>
  <button class="ds-menu__item ds-menu__item--destructive" role="menuitem" type="button">
    <span class="ds-menu__item-label">Delete file</span>
  </button>
</div>

Action MenuAction Menu

Action Menu combina um Button trigger com um Menu posicionado. O módulo público ds-tis/menu (initActionMenus / destroyActionMenus) é obrigatório para o contrato interativo: abertura, Escape, setas, typeahead e retorno de foco. Eventos: ds-menu-open, ds-menu-close.Action Menu combines a Button trigger with a positioned Menu. The public ds-tis/menu module (initActionMenus / destroyActionMenus) is required for the interactive contract: open/close, Escape, arrow keys, typeahead, and focus return. Events: ds-menu-open, ds-menu-close.

<div class="ds-action-menu">
  <button class="ds-button ds-button--outline ds-action-menu__trigger"
          type="button"
          aria-haspopup="menu" aria-expanded="false" aria-controls="menu-id">
    <span class="ds-button__label">Project actions</span>
  </button>
  <div class="ds-menu ds-action-menu__content" id="menu-id" role="menu">...</div>
</div>

<script type="module">
  import { initActionMenus, destroyActionMenus } from 'ds-tis/menu';
  initActionMenus();
  // destroyActionMenus() ao desmontar a view
</script>

Estados e seleçãoStates and selection

<button class="ds-menu__item" role="menuitemradio" aria-checked="true">...</button>
<button class="ds-menu__item" role="menuitem" aria-disabled="true">...</button>

Boas práticasBest practices

Faça

Agrupe ações relacionadas com separadores; coloque ações destrutivas por último.Group related actions with separators; place destructive actions last.

Não faça

Não use Menu para seleção de valor de formulário — use Select ou Combobox.Don't use Menu for form value selection — use Select or Combobox.

Diretrizes de conteúdoContent guidelines

RegraRule	ExemploExample
Verbos de ação em sentence case	"Rename file", "Delete project"
Shortcuts apenas informativos	"R" ao lado de Rename — não substitui a ação
Destructive com linguagem clara	"Delete project" — não "Remove"

Mapeamento de tokensToken mapping

Parte	CSS	Token
Surface	`.ds-menu`	`component.menu.surface.*`
Item	`.ds-menu__item`	`component.menu.item.{height,gap,padding-x,radius,bg,content}`
Destructive	`.ds-menu__item--destructive`	`component.menu.item.{content,icon,meta}.color.destructive`
Icon	`.ds-menu__icon`	`component.menu.item.icon.{color,size,stroke-width}`
Overlay gap	`.ds-action-menu__content`	`component.action-menu.overlay.gap.default`

Classes CSSCSS classes

ClasseClass	DescriçãoDescription
`ds-menu`	Container do menu (`role="menu"`)Menu container (`role="menu"`)
`ds-menu__item`	Item de comandoCommand item
`ds-menu__item--destructive`	Ação destrutivaDestructive action
`ds-menu__separator`	Separador de gruposGroup separator
`ds-action-menu`	Wrapper trigger + popupTrigger + popup wrapper
`ds-action-menu__trigger`	Button que abre o menuButton that opens the menu
`ds-action-menu__content`	Menu posicionado no overlayPositioned menu in overlay

Interação por tecladoKeyboard interaction

TeclaKey	AçãoAction
`Arrow Down` / `Arrow Up`	Move foco entre itensMoves focus between items
`Home` / `End`	Primeiro / último itemFirst / last item
`Enter` / `Space`	Ativa o item focadoActivates focused item
`Escape`	Fecha o menu e retorna foco ao triggerCloses menu and returns focus to trigger

AccessibilityAccessibility

Critério WCAGWCAG criterion	RequisitoRequirement	Status
4.1.2 Name, Role, Value (A)	`role="menu"`, `role="menuitem"`, `aria-haspopup`, `aria-expanded`	✓
2.1.1 Keyboard (A)	Navegação por setas, Enter/Space, Escape via `initActionMenus` ou implementação equivalenteArrow navigation, Enter/Space, Escape via `initActionMenus` or equivalent	✓
2.4.3 Focus Order (A)	Foco inicial no primeiro item ao abrir; retorno ao trigger ao fecharInitial focus on first item when open; return to trigger on close	✓