navigation — wyrd.component.command

Command

Modal command palette composed from dialog overlay, combobox filtering, and flat collection navigation; hosts own global shortcuts such as Command-K.

Install @wyrd-company/react or the Flutter package and use it directly — your DESIGN.md does the styling.

catalog/contracts/command.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: Command  tag: wyrd-command  package: wyrd.component.command  title: Command  summary: Modal command palette composed from dialog overlay, combobox filtering, and flat collection navigation; hosts own global shortcuts such as Command-K.relationships:  related-to:    - collection-navigation    - quality-parity-and-gatesclassification:  category: navigation  composition: collection  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: label      type:        kind: string      required: true      serializable: true      summary: Accessible name for the command palette dialog.    - name: items      type:        kind: array        item:          kind: object          fields:            label:              kind: string            value:              kind: string            group:              kind: string            shortcut:              kind: string            disabled:              kind: boolean      required: false      default: []      serializable: true      summary: Flat ordered command data; group creates single-level labelled sections and shortcut is render-only text.    - name: is-open      type:        kind: boolean      required: false      controlled: true      reflects: true      serializable: true      summary: Controlled modal visibility.    - name: default-open      type:        kind: boolean      required: false      default: false      serializable: true      summary: Initial uncontrolled modal visibility.    - name: active-index      type:        kind: integer        minimum: 0      required: false      default: 0      serializable: true      summary: Initial active index in the filtered enabled command collection.  slots: []  events:    - name: open-change      payload:        is-open:          kind: boolean        reason:          kind: enum          values:            - trigger            - escape            - backdrop            - select            - programmatic      bubbles: true      composed: true      cancelable: false      summary: Canonical modal visibility event.    - name: select      payload:        value:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Canonical command activation event emitted once per accepted selection.  states:    - name: closed      source: property      summary: Command palette is absent from the active overlay surface.    - name: open      source: property      summary: Command palette is modal and collection navigation is active.    - name: filtering      source: platform      summary: Input contains a non-empty filter query.    - name: empty      source: platform      summary: No command label matches the current query.    - name: focus-visible      source: platform      summary: Filter input has keyboard-visible focus.  parts:    - name: backdrop      summary: Modal backdrop.    - name: surface      summary: Command palette dialog surface.    - name: input      summary: Editable command filter with combobox semantics.    - name: list      summary: Filtered command listbox.    - name: group      summary: Single-level command group.    - name: group-heading      summary: Visible and programmatically associated group heading.    - name: item      summary: Repeated command option.    - name: label      summary: Command item label.    - name: shortcut      summary: Render-only keyboard shortcut display string.    - name: empty-state      summary: Localized message shown when filtering has no matches.  tokens:    surface:      background: color.surface-container      foreground: color.on-surface      border-color: color.outline      radius: rounded.lg      shadow: shadow.lg      max-width: 40rem    scrim:      color: color.on-background      opacity: opacity.muted    input:      background: color.surface      foreground: color.on-surface      placeholder: color.on-surface-variant      border-color: color.outline      border-color-focus: color.primary      border-width: 1px      radius: rounded.md      padding-x: spacing.md      padding-y: spacing.sm      text: typography.body-lg    list:      gap: spacing.xs      padding-y: spacing.sm    group-heading:      foreground: color.on-surface-variant      padding-x: spacing.md      padding-y: spacing.xs      text: typography.label-sm    item:      foreground: color.on-surface      active-background: color.secondary      disabled-foreground: color.on-surface-variant      padding-x: spacing.md      padding-y: spacing.sm    shortcut:      foreground: color.on-surface-variant      text: typography.label-sm    empty-state:      foreground: color.on-surface-variant      padding-x: spacing.md      padding-y: spacing.lgmessages:  - key: command.placeholder    description: Placeholder text for the command palette filter input.  - key: command.no-results    description: Empty-state text shown when no command label matches the filter query.obligations:  accessibility:    role: dialog    name: Label property provides the accessible name for the modal dialog.    description: The dialog contains a combobox input controlling a grouped listbox.    keyboard:      - Text input follows platform editing keys and receives focus when the palette opens.      - ArrowDown and ArrowUp move the active enabled command, wrapping at collection boundaries.      - Home and End move to the first and last enabled filtered commands.      - Enter selects the active enabled command.      - Escape requests modal dismissal and restores focus to the host return target.      - Tab and Shift+Tab remain trapped inside the modal surface.    semantics:      - Web input exposes combobox, expanded, autocomplete=list, aria-controls, and aria-activedescendant semantics.      - Web listbox, option, and active-descendant IDREF targets live in the same document root.      - Single-level groups expose group semantics and labelled headings without changing flat keyboard order.      - Disabled items remain visible but are skipped by navigation and cannot activate.      - The empty state is announced through a polite status region and uses a localized component message.      - Flutter exposes the modal route, text field, group headings, enabled state, and active item through platform semantics; aria-activedescendant has no native Flutter equivalent.  behavior:    model: collection    interactions:      - Dialog overlay machinery owns modality, backdrop dismissal, Escape dismissal, focus containment, and focus restoration.      - Combobox input machinery owns the filter query, case-insensitive substring matching, aria-activedescendant, and input focus.      - Collection navigation owns active item movement, disabled-item skipping, wrapping, Home, End, and activation.      - Controlled is-open wins over default-open; selection requests close after emitting select.      - Global shortcuts, including Command-K, are host responsibilities and are never bound by the component.      - Fuzzy matching and nested pages or sub-menus are future capabilities outside v1.    hostEffects:      - Present and dismiss a modal overlay surface.      - Trap focus while open and restore focus after close.      - Focus the filter input when opened.      - Dispatch open-change and select events.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion    - keyboard-inset    - safe-area  sdui:    status: serializable    serializableProperties:      - label      - items      - is-open      - default-open      - active-index    serializableSlots: []    eventBindings:      - open-change      - select    notes: Flat command data and open state serialize; query, modal route ownership, focus effects, and host global shortcuts remain target-local.examples:  - name: usage    state: closed    properties:      label: Command palette      is-open: false      items:        - label: Open file          value: open-file          group: File        - label: Save file          value: save-file          group: File        - label: Toggle sidebar          value: toggle-sidebar          group: View    slots: {}  - name: grouped    state: open    properties:      label: Command palette      default-open: true      items:        - label: Open file          value: open-file          group: File          shortcut: Command O        - label: Save file          value: save-file          group: File          shortcut: Command S        - label: Toggle sidebar          value: toggle-sidebar          group: View          shortcut: Command B    slots: {}  - name: disabled-item    state: open    properties:      label: Command palette      default-open: true      items:        - label: Copy          value: copy          group: Edit          shortcut: Command C        - label: Paste          value: paste          group: Edit          shortcut: Command V          disabled: true    slots: {}  - name: empty    state: empty    properties:      label: Command palette      default-open: true      items: []    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.

usage state: closed

Usage

import { useState } from "react";
import { WyrdButton, WyrdCommand } from "@wyrd-company/react";

export function CommandInteractionExample() {
  const [open, setOpen] = useState(false);
  const close = () => setOpen(false);
  return <>
    <WyrdButton onPress={() => setOpen(true)}>Open command palette</WyrdButton>
    <WyrdCommand label="Command palette" isOpen={open}
      items={[{ label: "Open file", value: "open-file", group: "File" }, { label: "Save file", value: "save-file", group: "File" }, { label: "Toggle sidebar", value: "toggle-sidebar", group: "View" }]}
      onOpenChange={(event) => !event.isOpen && close()} onSelect={close} />
  </>;
}

import 'package:flutter/widgets.dart';
import 'package:wyrd_flutter/wyrd_flutter.dart';

class CommandInteractionExample extends StatefulWidget {
  const CommandInteractionExample({super.key});
  @override State<CommandInteractionExample> createState() => _CommandInteractionExampleState();
}
class _CommandInteractionExampleState extends State<CommandInteractionExample> {
  bool open = false;
  @override Widget build(BuildContext context) => Stack(children: [
    WyrdButton(onPressed: (_) => setState(() => open = true), child: const Text('Open command palette')),
    WyrdCommand(label: 'Command palette', isOpen: open, items: const [{'label':'Open file','value':'open-file','group':'File'},{'label':'Save file','value':'save-file','group':'File'},{'label':'Toggle sidebar','value':'toggle-sidebar','group':'View'}],
      onOpenChanged: (event) { if (!event.isOpen) setState(() => open = false); }, onSelect: (_) => setState(() => open = false)),
  ]);
}

grouped state: open

Usage

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

<WyrdCommand label="Command palette" defaultOpen items={[{"label":"Open file","value":"open-file","group":"File","shortcut":"Command O"},{"label":"Save file","value":"save-file","group":"File","shortcut":"Command S"},{"label":"Toggle sidebar","value":"toggle-sidebar","group":"View","shortcut":"Command B"}]} />

// events: onOpenChange, onSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCommand(
  label: 'Command palette',
  defaultOpen: true,
  items: [{"label":"Open file","value":"open-file","group":"File","shortcut":"Command O"},{"label":"Save file","value":"save-file","group":"File","shortcut":"Command S"},{"label":"Toggle sidebar","value":"toggle-sidebar","group":"View","shortcut":"Command B"}],
)

// events: onOpenChanged, onSelect

disabled-item state: open

Usage

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

<WyrdCommand label="Command palette" defaultOpen items={[{"label":"Copy","value":"copy","group":"Edit","shortcut":"Command C"},{"label":"Paste","value":"paste","group":"Edit","shortcut":"Command V","disabled":true}]} />

// events: onOpenChange, onSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCommand(
  label: 'Command palette',
  defaultOpen: true,
  items: [{"label":"Copy","value":"copy","group":"Edit","shortcut":"Command C"},{"label":"Paste","value":"paste","group":"Edit","shortcut":"Command V","disabled":true}],
)

// events: onOpenChanged, onSelect

empty state: empty

Usage

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

<WyrdCommand label="Command palette" defaultOpen items={[]} />

// events: onOpenChange, onSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCommand(
  label: 'Command palette',
  defaultOpen: true,
  items: [],
)

// events: onOpenChanged, onSelect

Properties

Name	Type	Default	Summary
`label`	`string`	`undefined`	Accessible name for the command palette dialog.
`items`	`array`		Flat ordered command data; group creates single-level labelled sections and shortcut is render-only text.
`is-open`	`boolean`	`undefined`	Controlled modal visibility.
`default-open`	`boolean`	`false`	Initial uncontrolled modal visibility.
`active-index`	`integer`	`0`	Initial active index in the filtered enabled command collection.

Slots & events

Event	Payload	Summary
`open-change`	`is-open, reason`	Canonical modal visibility event.
`select`	`value`	Canonical command 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
`surface.background`	`color.surface-container`
`surface.foreground`	`color.on-surface`
`surface.border-color`	`color.outline`
`surface.radius`	`rounded.lg`
`surface.shadow`	`shadow.lg`
`surface.max-width`	`40rem`
`scrim.color`	`color.on-background`
`scrim.opacity`	`opacity.muted`
`input.background`	`color.surface`
`input.foreground`	`color.on-surface`
`input.placeholder`	`color.on-surface-variant`
`input.border-color`	`color.outline`
`input.border-color-focus`	`color.primary`
`input.border-width`	`1px`
`input.radius`	`rounded.md`
`input.padding-x`	`spacing.md`
`input.padding-y`	`spacing.sm`
`input.text`	`typography.body-lg`
`list.gap`	`spacing.xs`
`list.padding-y`	`spacing.sm`
`group-heading.foreground`	`color.on-surface-variant`
`group-heading.padding-x`	`spacing.md`
`group-heading.padding-y`	`spacing.xs`
`group-heading.text`	`typography.label-sm`
`item.foreground`	`color.on-surface`
`item.active-background`	`color.secondary`
`item.disabled-foreground`	`color.on-surface-variant`
`item.padding-x`	`spacing.md`
`item.padding-y`	`spacing.sm`
`shortcut.foreground`	`color.on-surface-variant`
`shortcut.text`	`typography.label-sm`
`empty-state.foreground`	`color.on-surface-variant`
`empty-state.padding-x`	`spacing.md`
`empty-state.padding-y`	`spacing.lg`

States

State	Source	Summary
`closed`	property	Command palette is absent from the active overlay surface.
`open`	property	Command palette is modal and collection navigation is active.
`filtering`	platform	Input contains a non-empty filter query.
`empty`	platform	No command label matches the current query.
`focus-visible`	platform	Filter input has keyboard-visible focus.

SDUI

Status: serializable. Flat command data and open state serialize; query, modal route ownership, focus effects, and host global shortcuts remain target-local.

Serializable	Members
Properties	`label, items, is-open, default-open, active-index`
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