@ds-mo/ui 8.3.1 → 9.1.0

package/dist/mcp-data/registry/menu.json

@@ -0,0 +1,459 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "menu",
+  "title": "Menu",
+  "description": "Anchored action menu with flat commands, grouped sections, selected command state, supplemental notification dots, switches, and destructive actions.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/menu",
+    "source": "src/wc/components/Menu/Menu.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "general",
+      "status": "stable",
+      "summary": "Anchored action menu with flat commands, grouped sections, selected command state, supplemental notification dots, switches, and destructive actions.",
+      "useWhen": [
+        "A trigger reveals a short contextual list of commands or state-changing actions.",
+        "Actions need grouping, selected state, supplemental notification dots, switch rows, or destructive treatment."
+      ],
+      "avoidWhen": [
+        "The user is selecting a value for a form field.",
+        "The content requires rich dialog interaction or a multi-step workflow.",
+        "The actions should remain persistently visible."
+      ],
+      "alternatives": [
+        {
+          "when": "The choice is a form value with a label, validation, and submitted value.",
+          "component": "component:ds-select",
+          "reason": "Select provides form-control semantics and value ownership."
+        },
+        {
+          "when": "Several form values may be selected.",
+          "component": "component:ds-select-multi",
+          "reason": "SelectMulti provides multi-select listbox semantics, array value ownership, and count presentation."
+        },
+        {
+          "when": "The interaction needs substantial content, confirmation, or a form.",
+          "component": "component:ds-modal",
+          "reason": "Modal owns focus containment and dialog-level interaction."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-button-unfilled",
+        "component:ds-panel-nav",
+        "component:ds-switch",
+        "component:ds-swatch-picker"
+      ],
+      "patterns": [
+        "pattern:menu-trigger"
+      ],
+      "accessibility": [
+        "Anchor the menu to the control that opens it and return focus to that control when the menu closes.",
+        "Open with visible initial focus only when the trigger was activated from the keyboard.",
+        "Keep disabled items discoverable only when their unavailable state is meaningful.",
+        "Switch rows use menuitemcheckbox semantics on the row; the nested ds-switch is an aria-hidden md presentation indicator.",
+        "A swatch-picker section changes the popup to a non-modal dialog so its radio group and ordinary preference buttons keep valid nested semantics; Tab moves between its controls, then leaves and closes at the popup boundary.",
+        "Use notification dots only as supplemental status and not as the sole indication of important information."
+      ],
+      "states": [
+        "The host owns open state and responds to selection and close events.",
+        "Use either flat items or sections, not both.",
+        "After dsSelect from a switch row, update switchValue in the items property so the controlled indicator reflects the new state.",
+        "Arrays, objects, and element anchors must be assigned as JavaScript properties.",
+        "Use a swatch-picker section for a small curated visual preference and apply dsSwatchSelect immediately without closing the popup; the legacy gradient-picker section and dsGradientSelect remain compatibility-only."
+      ],
+      "responsiveBehavior": [
+        "Keep the default choice-cell anchor alignment so the first or last interactive row edge aligns with its trigger, matching Select; use popup-frame only for deliberate custom frame geometry.",
+        "Choose placement relative to the trigger and allow the component to clamp the popup to the viewport.",
+        "Avoid fixed widths that exceed narrow viewports."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Assign items, sections, and HTMLElement anchors as properties after the element is defined."
+        ],
+        "react": [
+          "Pass arrays and objects as wrapper props and handle generated onDsSelect and onDsClose event props."
+        ],
+        "angular": [
+          "Use property bindings for arrays, objects, and anchors and event bindings for dsSelect and dsClose."
+        ]
+      },
+      "references": [
+        {
+          "label": "Storybook examples",
+          "path": "src/wc/components/Menu/Menu.stories.ts"
+        },
+        {
+          "label": "Framework integration",
+          "path": "docs/framework-integration.md"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "align": {
+          "type": "MenuAlign",
+          "resolvedType": "\"center\" | \"end\" | \"start\"",
+          "attribute": "align",
+          "default": "'start'",
+          "required": false,
+          "mutable": false
+        },
+        "alignOffset": {
+          "type": "number | string",
+          "resolvedType": "number | string",
+          "attribute": "align-offset",
+          "default": "0",
+          "required": false,
+          "mutable": false,
+          "description": "Cross-axis offset — number (px) or TokoMo length."
+        },
+        "anchor": {
+          "type": "HTMLElement | undefined",
+          "resolvedType": "HTMLElement | undefined",
+          "required": false,
+          "mutable": false,
+          "description": "External trigger element to position against. Set via JS: menuEl.anchor = buttonEl"
+        },
+        "anchorAlignment": {
+          "type": "ChoicePopupAnchorAlignment",
+          "resolvedType": "\"choice-cell\" | \"popup-frame\"",
+          "attribute": "anchor-alignment",
+          "default": "'choice-cell'",
+          "required": false,
+          "mutable": false,
+          "description": "Align choice-row edges to the anchor by default; use `popup-frame` only for custom frame geometry."
+        },
+        "anchorId": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "anchor-id",
+          "required": false,
+          "mutable": false,
+          "description": "ID of the external trigger element for positioning"
+        },
+        "initialFocusVisible": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "initial-focus-visible",
+          "default": "false",
+          "required": false,
+          "mutable": false,
+          "description": "Show a visible ring on the initially focused menu item. Use only when the opener was keyboard-driven."
+        },
+        "items": {
+          "type": "MenuItemData[]",
+          "resolvedType": "MenuItemData[]",
+          "default": "[]",
+          "required": false,
+          "mutable": false
+        },
+        "menuLabel": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "menu-label",
+          "default": "'Menu'",
+          "required": false,
+          "mutable": false,
+          "description": "Accessible name for the popup menu."
+        },
+        "menuWidth": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "menu-width",
+          "required": false,
+          "mutable": false
+        },
+        "minWidth": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "min-width",
+          "required": false,
+          "mutable": false
+        },
+        "open": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "open",
+          "default": "false",
+          "required": false,
+          "mutable": true
+        },
+        "sections": {
+          "type": "MenuSection[]",
+          "resolvedType": "MenuSection[]",
+          "default": "[]",
+          "required": false,
+          "mutable": false
+        },
+        "side": {
+          "type": "MenuSide",
+          "resolvedType": "\"bottom\" | \"left\" | \"right\" | \"top\"",
+          "attribute": "side",
+          "default": "'bottom'",
+          "required": false,
+          "mutable": false
+        },
+        "sideOffset": {
+          "type": "number | string",
+          "resolvedType": "number | string",
+          "attribute": "side-offset",
+          "default": "TOKEN_CSS_LENGTHS.space050",
+          "required": false,
+          "mutable": false,
+          "description": "Gap between anchor and menu — number (px) or TokoMo length (`var(--dimension-space-050)`, etc.)."
+        }
+      },
+      "events": [
+        {
+          "name": "dsClose",
+          "detail": "void",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        },
+        {
+          "name": "dsGradientSelect",
+          "detail": "ShellGradientPreset",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true,
+          "description": "Emitted when a `gradient-picker` section swatch is chosen."
+        },
+        {
+          "name": "dsSelect",
+          "detail": "MenuItemData",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        },
+        {
+          "name": "dsSwatchSelect",
+          "detail": "string",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true,
+          "description": "Emitted when a generic `swatch-picker` section option is chosen."
+        }
+      ],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "align": {
+        "type": "MenuAlign",
+        "resolvedType": "\"center\" | \"end\" | \"start\"",
+        "attribute": "align",
+        "default": "'start'",
+        "required": false,
+        "mutable": false
+      },
+      "alignOffset": {
+        "type": "number | string",
+        "resolvedType": "number | string",
+        "attribute": "align-offset",
+        "default": "0",
+        "required": false,
+        "mutable": false,
+        "description": "Cross-axis offset — number (px) or TokoMo length."
+      },
+      "anchor": {
+        "type": "HTMLElement | undefined",
+        "resolvedType": "HTMLElement | undefined",
+        "required": false,
+        "mutable": false,
+        "description": "External trigger element to position against. Set via JS: menuEl.anchor = buttonEl"
+      },
+      "anchorAlignment": {
+        "type": "ChoicePopupAnchorAlignment",
+        "resolvedType": "\"choice-cell\" | \"popup-frame\"",
+        "attribute": "anchor-alignment",
+        "default": "'choice-cell'",
+        "required": false,
+        "mutable": false,
+        "description": "Align choice-row edges to the anchor by default; use `popup-frame` only for custom frame geometry."
+      },
+      "anchorId": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "anchor-id",
+        "required": false,
+        "mutable": false,
+        "description": "ID of the external trigger element for positioning"
+      },
+      "initialFocusVisible": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "initial-focus-visible",
+        "default": "false",
+        "required": false,
+        "mutable": false,
+        "description": "Show a visible ring on the initially focused menu item. Use only when the opener was keyboard-driven."
+      },
+      "items": {
+        "type": "MenuItemData[]",
+        "resolvedType": "MenuItemData[]",
+        "default": "[]",
+        "required": false,
+        "mutable": false
+      },
+      "menuLabel": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "menu-label",
+        "default": "'Menu'",
+        "required": false,
+        "mutable": false,
+        "description": "Accessible name for the popup menu."
+      },
+      "menuWidth": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "menu-width",
+        "required": false,
+        "mutable": false
+      },
+      "minWidth": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "min-width",
+        "required": false,
+        "mutable": false
+      },
+      "open": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "open",
+        "default": "false",
+        "required": false,
+        "mutable": true
+      },
+      "sections": {
+        "type": "MenuSection[]",
+        "resolvedType": "MenuSection[]",
+        "default": "[]",
+        "required": false,
+        "mutable": false
+      },
+      "side": {
+        "type": "MenuSide",
+        "resolvedType": "\"bottom\" | \"left\" | \"right\" | \"top\"",
+        "attribute": "side",
+        "default": "'bottom'",
+        "required": false,
+        "mutable": false
+      },
+      "sideOffset": {
+        "type": "number | string",
+        "resolvedType": "number | string",
+        "attribute": "side-offset",
+        "default": "TOKEN_CSS_LENGTHS.space050",
+        "required": false,
+        "mutable": false,
+        "description": "Gap between anchor and menu — number (px) or TokoMo length (`var(--dimension-space-050)`, etc.)."
+      }
+    },
+    "events": [
+      {
+        "name": "dsClose",
+        "detail": "void",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      },
+      {
+        "name": "dsGradientSelect",
+        "detail": "ShellGradientPreset",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true,
+        "description": "Emitted when a `gradient-picker` section swatch is chosen."
+      },
+      {
+        "name": "dsSelect",
+        "detail": "MenuItemData",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      },
+      {
+        "name": "dsSwatchSelect",
+        "detail": "string",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true,
+        "description": "Emitted when a generic `swatch-picker` section option is chosen."
+      }
+    ],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-menu",
+      "react": "DsMenu",
+      "angular": "DsMenu"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-menu.js';",
+        "example": "<ds-menu></ds-menu>"
+      },
+      "react": {
+        "import": "import { DsMenu } from '@ds-mo/ui/react';",
+        "example": "<DsMenu />"
+      },
+      "angular": {
+        "import": "import { DsMenu } from '@ds-mo/ui/angular/ds-menu';",
+        "example": "<ds-menu></ds-menu>"
+      },
+      "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: anchor, items, sections.",
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/icons ^6.2.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens"
+  ],
+  "registryDependencies": [
+    "badge",
+    "swatch-picker",
+    "switch",
+    "text"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/Menu/Menu.css",
+      "content": "@import '../../utils/choice-list.css';\n\n/* Inactive: `.ds-control-inactive` (25% opacity). */\n\n.menu-item--destructive .menu-item__label {\n  /* Beat ds-text color-* host classes for destructive rows. */\n  color: var(--color-foreground-bold-negative) !important;\n}\n\n/* Standard md icon zone keeps the dot aligned with other control suffixes. */\n.menu-item__dot-box {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  width: var(--ds-control-icon, var(--dimension-iconography-md));\n  height: var(--ds-control-icon, var(--dimension-iconography-md));\n  pointer-events: none;\n}\n\n/* ── Switch suffix ───────────────────────────────────────────────────────── */\n\n.menu-item__switch {\n  flex-shrink: 0;\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Menu/Menu.tsx",
+      "content": "import { Component, Prop, State, Event, EventEmitter, Element, Watch, Listen, h, Host } from '@stencil/core';\nimport {\n  choicePopupMinWidth,\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n  type ChoicePopupAnchorAlignment,\n} from '../../utils';\nimport { computeMenuPosition, type MenuAlign, type MenuSide } from './menu-position';\nimport type { MenuItemData, MenuSection } from './menu-types';\nimport {\n  isMenuGradientPickerSection,\n  isMenuPickerSection,\n  isMenuSwatchPickerSection,\n} from './menu-types';\nimport {\n  shellGradientPickerSections,\n  type ShellGradientPreset,\n} from '../../shell/shell-gradient-presets';\n\n/** rAF retries while the popup mounts or the anchor resolves. */\nconst POSITION_RETRY_BUDGET = 8;\nconst MENU_FOCUSABLE_SELECTOR = [\n  'a[href]',\n  'button:not([disabled])',\n  'input:not([disabled]):not([type=\"hidden\"])',\n  'select:not([disabled])',\n  'textarea:not([disabled])',\n  '[tabindex]:not([tabindex=\"-1\"])',\n].join(',');\n\n@Component({\n  tag: 'ds-menu',\n  styleUrl: 'Menu.css',\n  scoped: true,\n})\nexport class Menu {\n  @Element() el!: HTMLElement;\n\n  @Prop({ mutable: true }) open: boolean = false;\n  @Prop() items: MenuItemData[] = [];\n  @Prop() sections: MenuSection[] = [];\n  @Prop() side: MenuSide = 'bottom';\n  @Prop() align: MenuAlign = 'start';\n  /** Align choice-row edges to the anchor by default; use `popup-frame` only for custom frame geometry. */\n  @Prop() anchorAlignment: ChoicePopupAnchorAlignment = 'choice-cell';\n  /** Gap between anchor and menu — number (px) or TokoMo length (`var(--dimension-space-050)`, etc.). */\n  @Prop() sideOffset: number | string = TOKEN_CSS_LENGTHS.space050;\n  /** Cross-axis offset — number (px) or TokoMo length. */\n  @Prop() alignOffset: number | string = 0;\n  @Prop() menuWidth: string | undefined;\n  @Prop() minWidth: string | undefined;\n  /** External trigger element to position against. Set via JS: menuEl.anchor = buttonEl */\n  @Prop() anchor: HTMLElement | undefined;\n  /** ID of the external trigger element for positioning */\n  @Prop() anchorId: string | undefined;\n  /** Show a visible ring on the initially focused menu item. Use only when the opener was keyboard-driven. */\n  @Prop() initialFocusVisible: boolean = false;\n  /** Accessible name for the popup menu. */\n  @Prop() menuLabel: string = 'Menu';\n\n  @State() private shouldRender: boolean = false;\n  @State() private closing: boolean = false;\n  @State() private pos: { x: number; y: number } = { x: 0, y: 0 };\n  @State() private focusedIndex: number = 0;\n  @State() private positionReady: boolean = false;\n  @State() private focusRingVisible: boolean = false;\n\n  @Event() dsClose!: EventEmitter<void>;\n  @Event() dsSelect!: EventEmitter<MenuItemData>;\n  /** Emitted when a `gradient-picker` section swatch is chosen. */\n  @Event() dsGradientSelect!: EventEmitter<ShellGradientPreset>;\n  /** Emitted when a generic `swatch-picker` section option is chosen. */\n  @Event() dsSwatchSelect!: EventEmitter<string>;\n\n  private clickOutsideHandler: ((e: MouseEvent) => void) | null = null;\n  private scrollResizeHandler: (() => void) | null = null;\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n  private itemEls: HTMLElement[] = [];\n  private positionRetryRaf: number | null = null;\n  private listenersReady = false;\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  disconnectedCallback() {\n    this.cancelPositionRetry();\n    this.teardownListeners();\n  }\n\n  @Watch('open')\n  onOpenChange(isOpen: boolean) {\n    if (isOpen) {\n      this.teardownListeners();\n      this.shouldRender = true;\n      this.closing = false;\n      this.positionReady = false;\n      this.listenersReady = false;\n      this.focusRingVisible = this.initialFocusVisible;\n      this.listenersReady = true;\n      this.setupListeners();\n      this.schedulePositionUpdate(() => {\n        this.focusInitialItem();\n      });\n    } else if (this.shouldRender) {\n      this.cancelPositionRetry();\n      this.closing = true;\n      this.teardownListeners();\n      this.listenersReady = false;\n      const closeAnimationMs = this.closeAnimationMs;\n      if (closeAnimationMs <= 0) {\n        this.finishClose();\n        return;\n      }\n      this.closeTimer = setTimeout(() => {\n        this.closeTimer = null;\n        this.finishClose();\n      }, closeAnimationMs);\n    }\n  }\n\n  @Watch('anchor')\n  @Watch('anchorId')\n  onAnchorChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  @Watch('side')\n  @Watch('align')\n  @Watch('anchorAlignment')\n  @Watch('sideOffset')\n  @Watch('alignOffset')\n  onPositionPropsChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  private get viewportPadPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n  }\n\n  private get sideOffsetPx(): number {\n    return resolveCssLengthPx(this.sideOffset, TOKEN_DEFAULTS.space050);\n  }\n\n  private get alignOffsetPx(): number {\n    return resolveCssLengthPx(this.alignOffset, 0);\n  }\n\n  private get popupFallbackWidthPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuWidthXs, TOKEN_DEFAULTS.menuWidthXs);\n  }\n\n  private get popupFallbackHeightPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuFallbackHeight, TOKEN_DEFAULTS.menuFallbackHeight);\n  }\n\n  private get closeAnimationMs(): number {\n    return resolveMotionTimeMs(TOKEN_DEFAULTS.motionShort2, TOKEN_DEFAULTS.animationDurationShort3);\n  }\n\n  private finishClose() {\n    this.shouldRender = false;\n    this.closing = false;\n  }\n\n  private get resolvedAnchor(): HTMLElement | null {\n    if (this.anchor) return this.anchor;\n    if (this.anchorId) return document.getElementById(this.anchorId);\n    return null;\n  }\n\n  private get anchorFocusTarget(): HTMLElement | null {\n    const anchor = this.resolvedAnchor;\n    if (!anchor) return null;\n    if (anchor.matches(MENU_FOCUSABLE_SELECTOR)) return anchor;\n    return anchor.querySelector<HTMLElement>(MENU_FOCUSABLE_SELECTOR) ?? anchor;\n  }\n\n  private focusAnchor() {\n    const anchor = this.resolvedAnchor as (HTMLElement & { setFocus?: () => Promise<void> | void }) | null;\n    if (anchor?.setFocus) {\n      anchor.setFocus();\n      return;\n    }\n    this.anchorFocusTarget?.focus();\n  }\n\n  private moveFocusAfterTab(backwards: boolean) {\n    const anchor = this.anchorFocusTarget;\n    if (!anchor) return;\n    if (backwards) {\n      anchor.focus();\n      return;\n    }\n\n    const candidates = Array.from(document.querySelectorAll<HTMLElement>(MENU_FOCUSABLE_SELECTOR))\n      .filter(element => (\n        !element.closest('.menu-popup') &&\n        !element.closest('[inert]') &&\n        element.getClientRects().length > 0\n      ));\n    const index = candidates.indexOf(anchor);\n    (candidates[index + 1] ?? anchor).focus();\n  }\n\n  private compositeTabLeavesPopup(event: KeyboardEvent): boolean {\n    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (!popup) return true;\n    const focusables = Array.from(popup.querySelectorAll<HTMLElement>(MENU_FOCUSABLE_SELECTOR))\n      .filter(element => element.getClientRects().length > 0);\n    const currentIndex = focusables.indexOf(event.target as HTMLElement);\n    if (currentIndex < 0) return true;\n    return event.shiftKey ? currentIndex === 0 : currentIndex === focusables.length - 1;\n  }\n\n  private get activeSections(): MenuSection[] {\n    if (this.sections.length > 0) return this.sections;\n    if (this.items.length > 0) return [{ items: this.items }];\n    return [];\n  }\n\n  private get flatItems(): MenuItemData[] {\n    return this.activeSections.flatMap(section =>\n      isMenuPickerSection(section) ? [] : section.items,\n    );\n  }\n\n  /** Rich preference content is a non-modal dialog, not an ARIA action menu. */\n  private get hasCompositeSections(): boolean {\n    return this.activeSections.some(isMenuPickerSection);\n  }\n\n  private cancelPositionRetry() {\n    if (this.positionRetryRaf !== null) {\n      cancelAnimationFrame(this.positionRetryRaf);\n      this.positionRetryRaf = null;\n    }\n  }\n\n  /** Retry until anchor + popup exist — do not reveal at 0,0 on a failed first pass. */\n  private schedulePositionUpdate(onReady?: () => void) {\n    if (!this.open) return;\n\n    this.cancelPositionRetry();\n    this.positionReady = false;\n\n    let remaining = POSITION_RETRY_BUDGET;\n\n    const attempt = () => {\n      this.positionRetryRaf = null;\n      if (!this.open) return;\n\n      if (this.calculatePosition()) {\n        this.positionReady = true;\n        onReady?.();\n        return;\n      }\n\n      if (remaining > 0) {\n        remaining -= 1;\n        this.positionRetryRaf = requestAnimationFrame(attempt);\n      }\n    };\n\n    this.positionRetryRaf = requestAnimationFrame(attempt);\n  }\n\n  /** @returns `true` when anchor and popup were found and `pos` was updated. */\n  private calculatePosition(): boolean {\n    const anchorEl = this.resolvedAnchor;\n    if (!anchorEl) return false;\n    const popup = this.el.querySelector('.menu-popup') as HTMLElement | null;\n    if (!popup) return false;\n\n    const anchorRect = anchorEl.getBoundingClientRect();\n    const sectionInsetPx = this.viewportPadPx;\n    if (!this.minWidth) {\n      if (this.anchorAlignment === 'choice-cell' && (this.side === 'top' || this.side === 'bottom')) {\n        popup.style.minWidth = `max(var(--dimension-menu-width-xs), ${choicePopupMinWidth(anchorRect.width, sectionInsetPx)}px)`;\n      } else {\n        popup.style.removeProperty('min-width');\n      }\n    }\n\n    this.pos = computeMenuPosition({\n      anchorRect,\n      popupWidth: popup.offsetWidth || this.popupFallbackWidthPx,\n      popupHeight: popup.offsetHeight || this.popupFallbackHeightPx,\n      side: this.side,\n      align: this.align,\n      sideOffsetPx: this.sideOffsetPx,\n      alignOffsetPx: resolveChoicePopupAlignOffset({\n        align: this.align,\n        alignOffsetPx: this.alignOffsetPx,\n        sectionInsetPx,\n        anchorAlignment: this.anchorAlignment,\n      }),\n      viewportPadPx: this.viewportPadPx,\n      viewportWidth: window.innerWidth,\n      viewportHeight: window.innerHeight,\n    });\n    return true;\n  }\n\n  /** Focus the selected item when present, otherwise the first enabled item. */\n  private focusInitialItem() {\n    if (this.hasCompositeSections) {\n      requestAnimationFrame(() => {\n        this.el.querySelector<HTMLElement>('.menu-popup [tabindex=\"0\"]')?.focus();\n      });\n      return;\n    }\n\n    const flat = this.flatItems;\n    const selectedIdx = flat.findIndex(it => it.isSelected && !it.isInactive);\n    const firstEnabledIdx = flat.findIndex(it => !it.isInactive);\n    this.focusedIndex = selectedIdx >= 0\n      ? selectedIdx\n      : (firstEnabledIdx >= 0 ? firstEnabledIdx : 0);\n\n    requestAnimationFrame(() => {\n      const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n      btns[this.focusedIndex]?.focus();\n    });\n  }\n\n  private setupListeners() {\n    this.clickOutsideHandler = (e: MouseEvent) => {\n      const t = e.target as Node;\n      const popup = this.el.querySelector('.menu-popup');\n      const anchorEl = this.resolvedAnchor;\n      if (popup?.contains(t) || anchorEl?.contains(t)) return;\n      this.close();\n    };\n\n    this.scrollResizeHandler = () => {\n      if (this.shouldRender && !this.closing) this.calculatePosition();\n    };\n\n    document.addEventListener('mousedown', this.clickOutsideHandler, true);\n    window.addEventListener('scroll', this.scrollResizeHandler, true);\n    window.addEventListener('resize', this.scrollResizeHandler);\n  }\n\n  private teardownListeners() {\n    if (this.clickOutsideHandler) {\n      document.removeEventListener('mousedown', this.clickOutsideHandler, true);\n      this.clickOutsideHandler = null;\n    }\n    if (this.scrollResizeHandler) {\n      window.removeEventListener('scroll', this.scrollResizeHandler, true);\n      window.removeEventListener('resize', this.scrollResizeHandler);\n      this.scrollResizeHandler = null;\n    }\n    if (this.closeTimer) {\n      clearTimeout(this.closeTimer);\n      this.closeTimer = null;\n    }\n  }\n\n  private close(restoreFocus = true) {\n    if (restoreFocus) this.focusAnchor();\n    this.dsClose.emit();\n    this.open = false;\n    this.onOpenChange(false);\n  }\n\n  @Listen('keydown')\n  handleKeyDown(e: KeyboardEvent) {\n    if (!this.shouldRender || this.closing) return;\n\n    if (e.key === 'Escape') {\n      e.preventDefault();\n      this.close();\n      return;\n    }\n\n    if (e.key === 'Tab') {\n      if (this.hasCompositeSections && !this.compositeTabLeavesPopup(e)) return;\n      e.preventDefault();\n      this.close(false);\n      this.moveFocusAfterTab(e.shiftKey);\n      return;\n    }\n\n    if (this.hasCompositeSections) return;\n\n    const flat = this.flatItems;\n    const enabled = flat.map((it, i) => ({ it, i })).filter(({ it }) => !it.isInactive).map(({ i }) => i);\n    if (!enabled.length) return;\n\n    const cur = enabled.indexOf(this.focusedIndex);\n    const safe = cur < 0 ? 0 : cur;\n\n    switch (e.key) {\n      case 'ArrowDown':\n        e.preventDefault(); e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe + 1) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'ArrowUp':\n        e.preventDefault(); e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe - 1 + enabled.length) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'Home':\n        e.preventDefault(); e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[0];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'End':\n        e.preventDefault(); e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[enabled.length - 1];\n        this.focusItem(this.focusedIndex);\n        break;\n    }\n  }\n\n  private focusItem(idx: number) {\n    const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n    btns[idx]?.focus();\n  }\n\n  private handleItemClick(item: MenuItemData) {\n    if (item.isInactive) return;\n    this.dsSelect.emit(item);\n  }\n\n  private handleGradientSelect(preset: ShellGradientPreset) {\n    this.dsGradientSelect.emit(preset);\n  }\n\n  private handleSwatchSelect(value: string) {\n    this.dsSwatchSelect.emit(value);\n  }\n\n  render() {\n    if (!this.shouldRender) return <Host style={{ display: 'contents' }} />;\n\n    const sections = this.activeSections;\n    let flatIdx = 0;\n\n    const popupStyle: Record<string, string> = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.pos.x)}px, ${Math.round(this.pos.y)}px)`,\n      zIndex: '9998',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n\n    if (this.menuWidth) popupStyle['width'] = this.menuWidth;\n    if (this.minWidth) popupStyle['min-width'] = this.minWidth;\n\n    return (\n      <Host style={{ display: 'contents' }}>\n        <div\n          class={{\n            'menu-popup': true,\n            'menu-popup--closing': this.closing,\n            'ds-choice-popup': true,\n            'ds-choice-popup--closing': this.closing,\n          }}\n          style={popupStyle}\n          role={this.hasCompositeSections ? 'dialog' : 'menu'}\n          aria-label={this.menuLabel}\n          aria-orientation={this.hasCompositeSections ? undefined : 'vertical'}\n        >\n          <div class=\"ds-choice-list\">\n          {sections.map((section, si) => (\n            <div\n              key={si}\n              class={{\n                'menu-section': true,\n                'menu-section--divided': si < sections.length - 1,\n                'menu-section--gradient-picker': isMenuPickerSection(section),\n                'ds-choice-section': true,\n                'ds-choice-section--divided': si < sections.length - 1,\n              }}\n              role={section.header ? 'group' : undefined}\n              aria-label={section.header}\n            >\n              {section.header && (\n                <ds-text\n                  class=\"section-header ds-choice-section__header ds-control--md\"\n                  as=\"span\"\n                  variant=\"text-body-small\"\n                  emphasis\n                  color=\"primary\"\n                  aria-hidden=\"true\"\n                >\n                  {section.header}\n                </ds-text>\n              )}\n              {isMenuGradientPickerSection(section) ? (\n                <ds-swatch-picker\n                  value={section.value}\n                  groupLabel={section.header ?? 'Shell gradient theme'}\n                  sections={shellGradientPickerSections()}\n                  onDsChange={(e: CustomEvent<string>) => {\n                    e.stopPropagation();\n                    this.handleGradientSelect(e.detail as ShellGradientPreset);\n                  }}\n                />\n              ) : isMenuSwatchPickerSection(section) ? (\n                <ds-swatch-picker\n                  value={section.value}\n                  groupLabel={section.groupLabel ?? section.header ?? 'Swatch options'}\n                  options={section.options ?? []}\n                  sections={section.sections ?? []}\n                  onDsChange={(e: CustomEvent<string>) => {\n                    e.stopPropagation();\n                    this.handleSwatchSelect(e.detail);\n                  }}\n                />\n              ) : (\n                section.items.map(item => {\n                const idx = flatIdx++;\n                const isFocused = this.focusedIndex === idx;\n                return (\n                  <button\n                    key={idx}\n                    type=\"button\"\n                    class={{\n                      'menu-item': true,\n                      'ds-choice-item': true,\n                      'ds-control--md': true,\n                      'ds-focus-ring-inset': true,\n                      'ds-focus-ring--visible': isFocused && this.focusRingVisible,\n                      'ds-interaction-fill': !item.isInactive,\n                      'ds-interaction-fill--selected': !!item.isSelected && !item.isInactive,\n                      'menu-item--selected': !!item.isSelected,\n                      'ds-control-inactive': !!item.isInactive,\n                      'menu-item--destructive': !!item.isDestructive,\n                      'menu-item--focused': isFocused,\n                    }}\n                    role={this.hasCompositeSections ? undefined : item.showSwitch ? 'menuitemcheckbox' : 'menuitem'}\n                    aria-checked={!this.hasCompositeSections && item.showSwitch ? String(!!item.switchValue) : undefined}\n                    aria-pressed={this.hasCompositeSections\n                      ? String(item.showSwitch ? !!item.switchValue : !!item.isSelected)\n                      : undefined}\n                    aria-current={!this.hasCompositeSections && !item.showSwitch && item.isSelected ? 'true' : undefined}\n                    disabled={item.isInactive}\n                    tabIndex={this.hasCompositeSections ? 0 : isFocused ? 0 : -1}\n                    onMouseDown={() => { this.focusRingVisible = false; }}\n                    onClick={() => this.handleItemClick(item)}\n                    onFocus={() => { this.focusedIndex = idx; }}\n                  >\n                    <div class=\"menu-item__content ds-choice-item__content ds-interaction-fill__content\">\n                      <ds-text\n                        class=\"menu-item__label ds-choice-item__label\"\n                        as=\"span\"\n                        variant=\"text-body-medium\"\n                        color={item.isSelected ? 'primary' : 'secondary'}\n                      >\n                        {item.label}\n                      </ds-text>\n                      {item.subtext && (\n                        <ds-text class=\"menu-item__subtext ds-choice-item__subtext\" as=\"span\" variant=\"text-body-small\" color=\"secondary\">\n                          {item.subtext}\n                        </ds-text>\n                      )}\n                    </div>\n                    {item.dot && (\n                      <span class=\"menu-item__dot-box ds-interaction-fill__content\" aria-hidden=\"true\">\n                        <ds-badge\n                          class=\"menu-item__dot\"\n                          variant=\"dot\"\n                          hasRing={false}\n                          label=\"\"\n                        />\n                      </span>\n                    )}\n                    {item.showSwitch && (\n                      <ds-switch\n                        class=\"menu-item__switch ds-interaction-fill__content\"\n                        size=\"md\"\n                        checked={!!item.switchValue}\n                        presentation\n                      />\n                    )}\n                  </button>\n                );\n              }))}\n            </div>\n          ))}\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Menu/menu-placement.ts",
+      "content": "import type { ChoicePopupAnchorAlignment } from '../../utils/choice-popup-alignment';\nimport type { MenuAlign, MenuSide } from './menu-position';\n\n/** Placement props bindable on `ds-menu` (side, align, offsets). */\nexport interface MenuPlacement {\n  side: MenuSide;\n  align: MenuAlign;\n  anchorAlignment: ChoicePopupAnchorAlignment;\n  sideOffset: number | string;\n  alignOffset: number | string;\n}\n\n/**\n * Canonical `ds-menu` placement for the **panel-nav footer user menu**.\n * Anchor from `dsNavUserAction` detail `{ anchor }` (id `ds-panel-nav-user-menu-anchor`).\n *\n * Not for BarNav overflow menus — those use `side=\"bottom\"` / `align=\"end\"` internally.\n * `align: 'end'` bottom-aligns the last choice cell on the anchor; the side offset nudges into the content area:\n * - `sideOffset` space-100 + space-050 (12px): 4px past the panel-nav outer edge (anchor is ~8px inset).\n * - `anchorAlignment: 'choice-cell'`: the shared section inset puts the last row edge on the footer user row.\n */\nexport const PANEL_NAV_USER_MENU_PLACEMENT = {\n  side: 'right',\n  align: 'end',\n  anchorAlignment: 'choice-cell',\n  sideOffset: 'calc(var(--dimension-space-100) + var(--dimension-space-050))',\n  alignOffset: 0,\n} as const satisfies MenuPlacement;\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Menu/menu-position.ts",
+      "content": "import {\n  computeAnchoredPopupPosition,\n  type AnchoredPopupAlign,\n  type AnchoredPopupPositionInput,\n  type AnchoredPopupSide,\n} from '../../utils/anchored-popup';\n\nexport type MenuSide = AnchoredPopupSide;\nexport type MenuAlign = AnchoredPopupAlign;\nexport type MenuPositionInput = AnchoredPopupPositionInput;\n\n/** Backward-compatible menu alias for the shared anchored-popup layout math. */\nexport const computeMenuPosition = computeAnchoredPopupPosition;\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Menu/menu-types.ts",
+      "content": "import type { ShellGradientPreset } from '../../shell/shell-gradient-presets';\nimport type { SwatchPickerOption, SwatchPickerSection } from '../SwatchPicker/swatch-picker-types';\n\nexport type { MenuAlign, MenuSide } from './menu-position';\nexport {\n  PANEL_NAV_USER_MENU_PLACEMENT,\n  type MenuPlacement,\n} from './menu-placement';\n\nexport interface MenuItemData {\n  label: string;\n  value?: string;\n  subtext?: string;\n  /** Show a supplemental brand notification dot. */\n  dot?: boolean;\n  isSelected?: boolean;\n  isInactive?: boolean;\n  isDestructive?: boolean;\n  /** Render a compact switch indicator; the menu row owns interaction. */\n  showSwitch?: boolean;\n  switchValue?: boolean;\n}\n\nexport interface MenuItemsSection {\n  header?: string;\n  items: MenuItemData[];\n}\n\nexport interface MenuGradientPickerSection {\n  header?: string;\n  /** @deprecated Use the generic `swatch-picker` section. */\n  variant: 'gradient-picker';\n  value: ShellGradientPreset;\n}\n\nexport interface MenuSwatchPickerSection {\n  header?: string;\n  variant: 'swatch-picker';\n  value: string;\n  options?: SwatchPickerOption[];\n  sections?: SwatchPickerSection[];\n  groupLabel?: string;\n}\n\nexport type MenuSection =\n  | MenuItemsSection\n  | MenuGradientPickerSection\n  | MenuSwatchPickerSection;\n\nexport function isMenuGradientPickerSection(\n  section: MenuSection,\n): section is MenuGradientPickerSection {\n  return 'variant' in section && section.variant === 'gradient-picker';\n}\n\nexport function isMenuSwatchPickerSection(\n  section: MenuSection,\n): section is MenuSwatchPickerSection {\n  return 'variant' in section && section.variant === 'swatch-picker';\n}\n\nexport function isMenuPickerSection(\n  section: MenuSection,\n): section is MenuGradientPickerSection | MenuSwatchPickerSection {\n  return isMenuGradientPickerSection(section) || isMenuSwatchPickerSection(section);\n}\n\nexport type { ShellGradientPreset };\nexport type { SwatchPickerOption, SwatchPickerSection };\n",
+      "type": "registry:ui"
+    }
+  ]
+}