navigation — wyrd.component.menu

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: Menu  tag: wyrd-menu  package: wyrd.component.menu  title: Menu  summary: Popup command collection with a trigger label, canonical open state, collection navigation, and one select event.relationships:  related-to:    - collection-navigation    - behavior-menuclassification:  category: navigation  composition: collection  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: label      type:        kind: string      required: false      default: Menu      serializable: true      summary: Trigger label and accessible-name source for the menu button.    - name: items      type:        kind: array        item:          kind: object          fields:            id:              kind: string            label:              kind: string            disabled:              kind: boolean      required: false      default:        - id: edit          label: Edit        - id: duplicate          label: Duplicate        - id: delete          label: Delete      serializable: true      summary: Ordered menu item data; disabled items render but are skipped by collection navigation and activation.    - name: is-open      type:        kind: boolean      required: false      default: false      controlled: true      reflects: true      serializable: true      summary: Controlled popup visibility.    - name: default-open      type:        kind: boolean      required: false      default: false      serializable: true      summary: Initial uncontrolled popup visibility.    - name: is-disabled      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Prevents opening and item activation.    - name: trigger-mode      type:        kind: enum        values:          - button          - context-menu      required: false      default: button      reflects: true      serializable: true      summary: Opens from the button or from a context-menu gesture on the trigger surface.  slots: []  events:    - name: open-change      payload:        is-open:          kind: boolean        reason:          kind: enum          values:            - trigger            - context-menu            - escape            - select            - dismiss      bubbles: true      composed: true      cancelable: false      summary: Canonical popup visibility event.    - name: select      payload:        id:          kind: string        label:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Canonical item activation event emitted once per accepted selection.  states:    - name: closed      source: behavior-runtime      summary: Popup content is not visible.    - name: open      source: behavior-runtime      summary: Popup content is visible and collection navigation is active.    - name: focus-visible      source: platform      summary: Trigger or active item has keyboard-visible focus.    - name: disabled      source: property      summary: Disabled state derived from is-disabled.  parts:    - name: root      summary: Menu root and positioning owner.    - name: trigger      summary: Interactive trigger control.    - name: popup      summary: Popup surface.    - name: item      summary: Repeated menu item container.  tokens:    trigger:      background: color.surface      foreground: color.on-surface      border-color: color.outline      padding-x: spacing.md      padding-y: spacing.sm    panel:      background: color.surface-container      foreground: color.on-surface      border-color: color.outline    item:      active-background: color.primary-hover      active-foreground: color.on-primary      padding-x: spacing.md      padding-y: spacing.sm    radius: rounded.md    border-width: 1px    gap: spacing.xs    padding-x: spacing.xs    padding-y: spacing.xsmessages: []obligations:  accessibility:    role: menu    name: Label property provides the accessible name for the menu button.    keyboard:      - Enter, Space, ArrowDown, and ArrowUp open the menu from the trigger.      - ArrowDown and ArrowUp move the active item while the popup is open.      - Home and End move to the collection boundaries.      - Typeahead moves to the next matching item.      - Escape closes the menu and restores focus to the trigger.      - Tab dismisses the menu and allows normal focus traversal.      - In context-menu trigger mode, Shift+F10 and the ContextMenu key open the menu at the focused trigger surface.    semantics:      - Trigger exposes menu popup and expanded state.      - Popup exposes menu semantics and active descendant state where supported.      - Disabled menu prevents popup opening and item activation.      - Disabled items remain visible but are skipped by keyboard navigation and do not activate.      - Context-menu trigger mode keeps the trigger surface keyboard focusable and exposes menu popup state.  behavior:    model: collection    runtimeBlueprint: behavior/menu    interactions:      - Opening at first or last item follows the committed menu behavior trace.      - Collection navigation owns active item movement, disabled-item skipping, wrapping, and typeahead.      - Selecting an item emits select and closes the popup.      - Context-menu trigger mode opens at the pointer coordinates on contextmenu and at the trigger surface for keyboard invocation.      - Web targets position the popup with the package flip/shift utility and a zero-size virtual anchor at the invocation coordinates.      - Flutter opens context-menu trigger mode on long press and anchors the menu at the press position.    hostEffects:      - Move focus to the popup on open.      - Restore focus to the trigger on close.      - Dispatch item activation event.      - Preserve the context-menu invocation point while the popup is open and recompute collision-aware positioning on viewport changes.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact  sdui:    status: serializable    serializableProperties:      - label      - items      - is-open      - default-open      - is-disabled      - trigger-mode    serializableSlots: []    eventBindings:      - open-change      - select    notes: Menu item data and open state serialize; target runtimes own focus, positioning, and keyboard host effects.examples:  - name: closed    state: closed    properties:      label: Actions      items:        - id: edit          label: Edit        - id: duplicate          label: Duplicate        - id: delete          label: Delete      is-open: false    slots: {}  - name: open    state: open    properties:      label: Actions      items:        - id: edit          label: Edit        - id: duplicate          label: Duplicate        - id: delete          label: Delete      default-open: true    slots: {}  - name: disabled    state: disabled    properties:      label: Actions      items:        - id: edit          label: Edit        - id: duplicate          label: Duplicate        - id: delete          label: Delete      is-disabled: true    slots: {}  - name: context-menu    state: closed    properties:      label: File actions      trigger-mode: context-menu      items:        - id: rename          label: Rename        - id: duplicate          label: Duplicate        - id: delete          label: Delete    slots: {}

Examples

Generated from the contract's examples block. Previews are the published @wyrd-company/react component, themed by the brand's role tokens — flip the site's light/dark toggle and they follow.

Code target React Flutter Applies to every example on component pages.

closed state: closed

Usage

import { WyrdMenu } from "@wyrd-company/react";

<WyrdMenu label="Actions" items={[{"id":"edit","label":"Edit"},{"id":"duplicate","label":"Duplicate"},{"id":"delete","label":"Delete"}]} isOpen={false} />

// events: onOpenChange, onSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdMenu(
  label: 'Actions',
  items: [{"id":"edit","label":"Edit"},{"id":"duplicate","label":"Duplicate"},{"id":"delete","label":"Delete"}],
  isOpen: false,
)

// events: onOpenChanged, onSelect

open state: open

Usage

import { WyrdMenu } from "@wyrd-company/react";

<WyrdMenu label="Actions" items={[{"id":"edit","label":"Edit"},{"id":"duplicate","label":"Duplicate"},{"id":"delete","label":"Delete"}]} defaultOpen />

// events: onOpenChange, onSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdMenu(
  label: 'Actions',
  items: [{"id":"edit","label":"Edit"},{"id":"duplicate","label":"Duplicate"},{"id":"delete","label":"Delete"}],
  defaultOpen: true,
)

// events: onOpenChanged, onSelect

disabled state: disabled

Usage

import { WyrdMenu } from "@wyrd-company/react";

<WyrdMenu label="Actions" items={[{"id":"edit","label":"Edit"},{"id":"duplicate","label":"Duplicate"},{"id":"delete","label":"Delete"}]} isDisabled />

// events: onOpenChange, onSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdMenu(
  label: 'Actions',
  items: [{"id":"edit","label":"Edit"},{"id":"duplicate","label":"Duplicate"},{"id":"delete","label":"Delete"}],
  isDisabled: true,
)

// events: onOpenChanged, onSelect

context-menu state: closed

Usage

import { WyrdMenu } from "@wyrd-company/react";

<WyrdMenu label="File actions" triggerMode="context-menu" items={[{"id":"rename","label":"Rename"},{"id":"duplicate","label":"Duplicate"},{"id":"delete","label":"Delete"}]} />

// events: onOpenChange, onSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdMenu(
  label: 'File actions',
  triggerMode: 'context-menu',
  items: [{"id":"rename","label":"Rename"},{"id":"duplicate","label":"Duplicate"},{"id":"delete","label":"Delete"}],
)

// events: onOpenChanged, onSelect

Properties

Name	Type	Default	Summary
`label`	`string`	`Menu`	Trigger label and accessible-name source for the menu button.
`items`	`array`	`[object Object],[object Object],[object Object]`	Ordered menu item data; disabled items render but are skipped by collection navigation and activation.
`is-open`	`boolean`	`false`	Controlled popup visibility.
`default-open`	`boolean`	`false`	Initial uncontrolled popup visibility.
`is-disabled`	`boolean`	`false`	Prevents opening and item activation.
`trigger-mode`	`button \| context-menu`	`button`	Opens from the button or from a context-menu gesture on the trigger surface.

Slots & events

Event	Payload	Summary
`open-change`	`is-open, reason`	Canonical popup visibility event.
`select`	`id, label`	Canonical item activation event emitted once per accepted selection.

Tokens

The contract's token bindings. Open the shared contextual sidebar from any example; primary swatches reflect the color you pick there. Error swatches show the active preset's values; editing any knob switches to custom and resets error to TWW · Ink.

Binding	Token
`trigger.background`	`color.surface`
`trigger.foreground`	`color.on-surface`
`trigger.border-color`	`color.outline`
`trigger.padding-x`	`spacing.md`
`trigger.padding-y`	`spacing.sm`
`panel.background`	`color.surface-container`
`panel.foreground`	`color.on-surface`
`panel.border-color`	`color.outline`
`item.active-background`	`color.primary-hover`
`item.active-foreground`	`color.on-primary`
`item.padding-x`	`spacing.md`
`item.padding-y`	`spacing.sm`
`radius`	`rounded.md`
`border-width`	`1px`
`gap`	`spacing.xs`
`padding-x`	`spacing.xs`
`padding-y`	`spacing.xs`

States

State	Source	Summary
`closed`	behavior-runtime	Popup content is not visible.
`open`	behavior-runtime	Popup content is visible and collection navigation is active.
`focus-visible`	platform	Trigger or active item has keyboard-visible focus.
`disabled`	property	Disabled state derived from is-disabled.

SDUI

Status: serializable. Menu item data and open state serialize; target runtimes own focus, positioning, and keyboard host effects.

Serializable	Members
Properties	`label, items, is-open, default-open, is-disabled, trigger-mode`
Slots	`—`
Events	`open-change, select`

  The Wyrding Way — a contract-first design system. © Wyrd Company 
   Pipeline demo
 Choose an example to inspect its pipeline context.
 Explore the shape of a brand's pipeline input: presets and knobs regenerate the illustrative excerpt below — not a compilable DESIGN.md (see the format reference). Primary swatches update live; accent, shape, density, and ground are excerpt-only; error swatches are preset-derived until any edit switches to custom (TWW · Ink errors). Component previews use the published brand package and the site's light/dark toggle.
 
  Start from
       
 * homages — shown for range, not affiliation.
 
  Tokens
 Primary updates live swatches. Accent, shape, density, and ground appear in the excerpt only. Error swatches follow the preset until you edit a knob — then they reset to TWW · Ink.
  color.primary   #26221A    color.accent   #9C7C14    rounded.md   2px    density   1.0×    ground     
 
   DESIGN.md excerpt illustrative

Examples

Properties

Slots & events

Tokens

States

Accessibility

SDUI