# Menu A compact row list that switches between one-off action semantics and controlled single-selection semantics. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/controls/Menu/Menu.tsx ## Guidance { "summary": "A compact row list that switches between one-off action semantics and controlled single-selection semantics.", "guidance": [ { "heading": "Overview", "body": "The option-list **body** for bottom sheets, popovers, and dropdown content — the rows, not the\ntrigger. `selectionMode` switches its meaning: `single` is a picker, `none` is an action list." }, { "heading": "When to use", "body": "Reach for `Menu` whenever you need a list of rows inside an opened surface. Two modes:\n\n- `selectionMode=\"single\"` renders a **picker** (role listbox/option, a check on the current `value`) — the body of a `Select` or `Dropdown` sheet.\n- `selectionMode=\"none\"` renders an **action list** (role menu/menuitem) of one-off commands like Rename, Share, Delete. Items can be `disabled` or `destructive`.\n\nChoosing between the neighbors:\n\n- Need the collapsed trigger that opens this list? That's `Dropdown` (or `Select` for a form value).\n- Picking one value from a short fixed set inside a form? Use `Select`, which composes a `Menu` internally.\n- Filtering a long list by typing? Use `Autocomplete`.\n\nIn-app it renders the activity-filter rows opened from the `Dropdown` in `ActivityFeed.tsx`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/controls/Menu/Menu.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [ { "name": "items", "type": "MenuItem[]", "declared_type": "MenuItem[]", "required": true, "description": "Rows in render order. Keep one meaning per menu: all commands, or all option values.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 38 } }, { "name": "ariaLabel", "type": "string", "declared_type": "string", "required": true, "description": "Accessible name for the container; the trigger's label sits on a separate element.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 40 } }, { "name": "selectionMode", "type": "MenuSelectionMode | undefined", "declared_type": "MenuSelectionMode", "required": false, "description": "Selection semantics. Use `single` for picker-style menus.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 42 }, "values": [ "none", "single" ], "values_complete": true, "default": "'none'", "default_kind": "source-expression" }, { "name": "value", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Current selected value when `selectionMode` is `single`.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 44 } }, { "name": "onSelect", "type": "((value: string) => void) | undefined", "declared_type": "(value: string) => void", "required": false, "description": "Called with the pressed row's `value`. Omitting it makes every row inert.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 46 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for item presses. Defaults to `true` (`selection` for single-select, otherwise `light`).", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 48 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 49 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 50 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Container selector, and the stem each row's selector is derived from.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 52 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Menu", "public_path": "Menu", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Menu", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 59 }, "props_type": "MenuProps", "props": [ { "name": "items", "type": "MenuItem[]", "declared_type": "MenuItem[]", "required": true, "description": "Rows in render order. Keep one meaning per menu: all commands, or all option values.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 38 } }, { "name": "ariaLabel", "type": "string", "declared_type": "string", "required": true, "description": "Accessible name for the container; the trigger's label sits on a separate element.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 40 } }, { "name": "selectionMode", "type": "MenuSelectionMode | undefined", "declared_type": "MenuSelectionMode", "required": false, "description": "Selection semantics. Use `single` for picker-style menus.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 42 }, "values": [ "none", "single" ], "values_complete": true, "default": "'none'", "default_kind": "source-expression" }, { "name": "value", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Current selected value when `selectionMode` is `single`.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 44 } }, { "name": "onSelect", "type": "((value: string) => void) | undefined", "declared_type": "(value: string) => void", "required": false, "description": "Called with the pressed row's `value`. Omitting it makes every row inert.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 46 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for item presses. Defaults to `true` (`selection` for single-select, otherwise `light`).", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 48 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 49 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 50 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Container selector, and the stem each row's selector is derived from.", "source": { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 52 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 9, "name": "MenuSelectionMode", "code": "export type MenuSelectionMode = 'none' | 'single';" }, { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 15, "name": "MenuItem", "code": "export interface MenuItem {\n /** Emitted by `onSelect`, matched against `MenuProps.value`, and used as the React key. */\n value: string;\n /** Primary row text. A node, but keep it inline: it renders inside a `Text`. */\n label: React.ReactNode;\n /** Optional leading content, usually an `Icon`. */\n leading?: React.ReactNode;\n /** Second line under the label, for spelling out an action's consequence. */\n description?: React.ReactNode;\n /** Blocks the press and dims the row, so `onSelect` never fires for it. */\n disabled?: boolean;\n /** Applies danger text treatment for destructive actions. */\n destructive?: boolean;\n /** Optional test selector. Falls back to `${testId}-${value}`. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 36, "name": "MenuProps", "code": "export interface MenuProps {\n /** Rows in render order. Keep one meaning per menu: all commands, or all option values. */\n items: MenuItem[];\n /** Accessible name for the container; the trigger's label sits on a separate element. */\n ariaLabel: string;\n /** Selection semantics. Use `single` for picker-style menus. */\n selectionMode?: MenuSelectionMode;\n /** Current selected value when `selectionMode` is `single`. */\n value?: string;\n /** Called with the pressed row's `value`. Omitting it makes every row inert. */\n onSelect?: (value: string) => void;\n /** Haptic feedback for item presses. Defaults to `true` (`selection` for single-select, otherwise `light`). */\n haptic?: HapticFeedback;\n className?: string;\n style?: React.CSSProperties;\n /** Container selector, and the stem each row's selector is derived from. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/tokens/CdsHaptic.ts", "line": 6, "name": "HapticFeedback", "code": "export type HapticFeedback = boolean | HapticType;" }, { "path": "packages/design-system/src/tokens/HapticType.ts", "line": 2, "name": "HapticType", "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Menu", "status": "preview", "version": "1.1.0", "summary": "A compact row list that switches between one-off action semantics and controlled single-selection semantics." }, "parts": [ { "id": "container", "label": "Container", "description": "Owns the menu or listbox role, accessible name, and row spacing." }, { "id": "item", "label": "Item", "description": "Native button exposing action or option semantics and disabled state." }, { "id": "leading", "label": "Leading visual", "description": "Optional icon or visual before item copy." }, { "id": "label", "label": "Item label", "description": "Primary action or option name." }, { "id": "description", "label": "Item description", "description": "Optional supporting copy beneath an action label." }, { "id": "selection-mark", "label": "Selection mark", "description": "Trailing check shown only on the selected single-choice item." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "One row treatment configured through the independent selection-mode axis." } }, "sizes": {}, "selectionModes": { "none": { "label": "Actions", "description": "Exposes menu and menuitem semantics for one-off commands." }, "single": { "label": "Single selection", "description": "Exposes listbox and option semantics with one selected value." } } }, "variants": [ { "id": "base", "label": "Base", "description": "Compact menu rows whose role is selected through a separate semantic mode.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "container-gap", "label": "Item gap", "kind": "exact", "token": "--cds-space-4", "value": 4, "unit": "px", "appliesTo": [ "container", "item" ] }, { "id": "item-min-height", "label": "Item minimum height", "kind": "exact", "token": "--cds-size-48", "value": 48, "unit": "px", "appliesTo": [ "item" ] }, { "id": "item-horizontal-padding", "label": "Item horizontal padding", "kind": "exact", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "item" ] }, { "id": "item-corner-radius", "label": "Item corner radius", "kind": "exact", "token": "--cds-radius-md", "value": 16, "unit": "px", "appliesTo": [ "item" ] } ], "layout": { "alignment": "Leading visual and copy align at the row start while the selected check remains trailing.", "flow": "Rows stack vertically; each row contains optional leading visual, flexible copy, then optional selection mark.", "notes": [ "Use action mode for commands and single-selection mode for values; do not mix both meanings in one menu.", "Place Menu inside an owned surface such as Modal or popover." ] }, "typographyAndColor": { "typography": [ { "label": "Item label", "description": "Use the body ramp for primary row labels.", "token": "--cds-type-body-size" }, { "label": "Description", "description": "Use body-small for supporting copy.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Selected row", "description": "Fill the selected single-choice row with the bold surface so selection reads as a high-contrast pill, consistent with other selected controls.", "token": "--cds-bg-bold" }, { "label": "Selected row content", "description": "Flip the selected row's label and check to on-bold so they read on the bold fill.", "token": "--cds-text-on-bold" }, { "label": "Primary label", "description": "Use primary text emphasis for normal actions and unselected options.", "token": "--cds-text-primary" }, { "label": "Description and leading visual", "description": "Use secondary text emphasis.", "token": "--cds-text-secondary" }, { "label": "Destructive action", "description": "Use the solid danger role only for irreversible actions.", "token": "--cds-status-danger-solid" }, { "label": "Selection mark", "description": "Use on-bold for the selected check, which sits on the bold selected row.", "token": "--cds-text-on-bold" } ] }, "states": [ { "id": "default", "label": "Default", "description": "Shows an enabled normal item." }, { "id": "selected", "label": "Selected", "description": "Fills the row with the bold surface and shows an on-bold check and option state in single-selection mode." }, { "id": "focused", "label": "Focused", "description": "Shows a visible focus ring on the row button." }, { "id": "disabled", "label": "Disabled", "description": "Blocks the item and dims its full contents." }, { "id": "destructive", "label": "Destructive", "description": "Uses danger emphasis for an enabled irreversible action." } ], "behavior": [ { "label": "Action mode", "description": "Emit the pressed value from menu items without maintaining selected state." }, { "label": "Single-selection mode", "description": "Expose the controlled value as one selected option and emit a new value on press." }, { "label": "Disabled items", "description": "Never emit selection or action callbacks from disabled rows." } ], "accessibility": [ { "label": "Container semantics", "description": "Require an accessible name and expose menu for actions or listbox for single selection." }, { "label": "Row semantics", "description": "Expose menuitem or option roles consistently with the container mode." }, { "label": "Selection and disabled state", "description": "Expose selected state only in single-selection mode and preserve native disabled behavior." } ], "contentAdaptation": [ { "label": "Long copy", "description": "Wrap labels and descriptions within the flexible copy column." }, { "label": "Destructive labels", "description": "Name the affected object and action clearly; danger color does not replace explicit wording." } ], "motionHaptics": { "motion": [ { "label": "Selection change", "description": "Update selected surface and check without changing row geometry." } ], "haptics": [ { "label": "Mode-aware feedback", "description": "Request selection feedback for single-choice items and light feedback for action items." } ] }, "platformDifferences": [ { "platforms": [ "web" ], "description": "Web maps modes to ARIA menu/menuitem or listbox/option roles; native platforms map the same distinction to action and selectable-row accessibility traits.", "rationale": "Semantic intent is shared while each platform exposes its native assistive-technology vocabulary." } ] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-space-4", "light": "4px", "dark": "4px" }, { "name": "--cds-size-48", "light": "48px", "dark": "48px" }, { "name": "--cds-space-16", "light": "16px", "dark": "16px" }, { "name": "--cds-radius-md", "light": "16px", "dark": "16px" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-type-body-small-size", "light": "0.875rem", "dark": "0.875rem" }, { "name": "--cds-bg-bold", "light": "#0b0b0a", "dark": "#ffffff" }, { "name": "--cds-text-on-bold", "light": "#ffffff", "dark": "#141410" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-text-secondary", "light": "#646260", "dark": "#ffffff99" }, { "name": "--cds-status-danger-solid", "light": "#b83100", "dark": "#b83100" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Playground](/storybook/iframe.html?id=cloaked-design-system-controls-menu--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/controls/Menu/Menu.stories.tsx - [Action Menu](/storybook/iframe.html?id=cloaked-design-system-controls-menu--action-menu&viewMode=story) | export: ActionMenu | source: packages/design-system/src/components/controls/Menu/Menu.stories.tsx - [With Leading Icons](/storybook/iframe.html?id=cloaked-design-system-controls-menu--with-leading-icons&viewMode=story) | export: WithLeadingIcons | source: packages/design-system/src/components/controls/Menu/Menu.stories.tsx - [With Dropdown Sheet](/storybook/iframe.html?id=cloaked-design-system-controls-menu--with-dropdown-sheet&viewMode=story) | export: WithDropdownSheet | source: packages/design-system/src/components/controls/Menu/Menu.stories.tsx - [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-controls-menu--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/controls/Menu/Menu.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.