@ds-mo/ui 14.18.0 → 14.19.0

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

@@ -56,6 +56,7 @@
         "Switch rows use menuitemcheckbox semantics on the row; the nested ds-switch is an aria-hidden presentation indicator at the same density as the menu.",
         "Single-selection menus use menuitemradio semantics and aria-checked on each row, but render no nested radio control; selected interaction fill and primary foreground provide the visual state.",
         "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.",
+        "When the anchor is inside an open shadow tree, pass its HTMLElement through anchor. Outside activation, focus return, and forward Tab continuation follow the composed tree across that boundary.",
         "Use notification dots only as supplemental status and not as the sole indication of important information.",
         "Trailing tags are non-interactive supplemental content; their visible label remains part of the menu item's accessible name.",
         "Reorderable rows keep a presentation Drag handle. Pointer drag on the handle and Alt+Arrow Up or Down emit dsReorder without closing. Pointer cancellation abandons the pending move. Hide-locked reorderable rows expose aria-disabled for the unavailable toggle but stay focusable so they can move; fully locked rows stay out of the contiguous reorderable run.",
@@ -68,6 +69,7 @@
         "After dsReorder, replace items or the affected section with the emitted items array. Menu never mutates order and does not close.",
         "For selectionMode single, keep exactly one item isSelected and replace the items or sections array after dsSelect; Menu never mutates consumer-owned selection data.",
         "Arrays, objects, and element anchors must be assigned as JavaScript properties.",
+        "anchorId resolves only in the document tree; use the anchor property for a trigger rendered inside a shadow root.",
         "Use a swatch-picker section for a small curated visual preference and apply dsSwatchSelect immediately without closing the popup.",
         "Ordinary rows, section headings, and supporting text consume the Menu size. At xs, both the primary label and supporting text use caption metrics.",
         "A trailing tag resolves one density smaller than its menu row and uses the inset recipe so it nests without changing row height. Do not combine tag, dot, and switch suffixes on one item.",
@@ -75,9 +77,11 @@
       ],
       "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.",
-        "Treat side as the preferred placement. When the popup cannot fit there and the opposite side offers more room, Menu flips on that main axis before clamping the final position to the viewport.",
+        "Treat side as the preferred placement. When the popup cannot fit there and the opposite side offers more room, Menu flips on that main axis before clamping to the nearest data-ds-overlay-boundary rectangle or the viewport fallback.",
+        "Keep the popup attached while its external anchor moves or resizes, including during CSS transitions in responsive shell chrome.",
         "Cap the popup to the vertical room available on its resolved side. When content is taller, the choice list scrolls internally and keyboard focus scrolls the active row into view.",
-        "Avoid fixed widths that exceed narrow viewports."
+        "Assign boundary as an HTMLElement only when the nearest composed-tree boundary is not the intended collision owner.",
+        "Avoid fixed widths that exceed narrow collision boundaries."
       ],
       "frameworkCaveats": {
         "customElements": [
@@ -145,6 +149,13 @@
           "mutable": false,
           "description": "ID of the external trigger element for positioning"
         },
+        "boundary": {
+          "type": "HTMLElement | undefined",
+          "resolvedType": "HTMLElement | undefined",
+          "required": false,
+          "mutable": false,
+          "description": "Explicit collision owner; otherwise the nearest data-ds-overlay-boundary ancestor is used."
+        },
         "initialFocusVisible": {
           "type": "boolean",
           "resolvedType": "boolean",
@@ -321,6 +332,13 @@
         "mutable": false,
         "description": "ID of the external trigger element for positioning"
       },
+      "boundary": {
+        "type": "HTMLElement | undefined",
+        "resolvedType": "HTMLElement | undefined",
+        "required": false,
+        "mutable": false,
+        "description": "Explicit collision owner; otherwise the nearest data-ds-overlay-boundary ancestor is used."
+      },
       "initialFocusVisible": {
         "type": "boolean",
         "resolvedType": "boolean",
@@ -479,7 +497,7 @@
         "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.",
+      "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: anchor, boundary, items, sections.",
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^6.5.0",
@@ -510,7 +528,7 @@
     },
     {
       "path": "src/wc/components/Menu/Menu.tsx",
-      "content": "import {\n  Component,\n  Prop,\n  State,\n  Event,\n  EventEmitter,\n  Element,\n  Watch,\n  Listen,\n  h,\n  Host,\n} from '@stencil/core';\nimport {\n  choicePopupMinWidth,\n  CONTROL_SUPPORTING_TEXT_VARIANT,\n  CONTROL_TEXT_VARIANT,\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n  type ChoicePopupAnchorAlignment,\n  type ControlSize,\n} from '../../utils';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\nimport { computeAnchoredPosition, type AnchoredPositionInput } from '../../utils/anchored-position';\nimport type { MenuAlign, MenuSide } from './menu-position';\nimport {\n  isMenuPickerSection,\n  isMenuSwatchPickerSection,\n  type MenuItemData,\n  type MenuReorderDetail,\n  type MenuSection,\n} from './menu-types';\nimport { snapshotMenuSections } from './menu-sections';\nimport {\n  createMenuReorderDetail,\n  locateMenuItem,\n  menuReorderableRange,\n  moveReorderableMenuItemBefore,\n  moveReorderableMenuItemBy,\n} from './menu-reorder';\n\nexport type MenuSelectionMode = 'none' | 'single';\nexport type MenuSize = ControlSize;\nconst MENU_ITEM_TAG_SIZE: Record<MenuSize, 'md' | 'sm' | 'xs'> = {\n  lg: 'md',\n  md: 'sm',\n  sm: 'xs',\n  xs: 'xs',\n};\n\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  /** Choice-row density. */\n  @Prop() size: MenuSize = 'md';\n  /** Give ordinary rows mutually-exclusive menu semantics using isSelected. */\n  @Prop() selectionMode: MenuSelectionMode = 'none';\n  @Prop() sections: MenuSection[] = [];\n  /** Preferred side; placement flips to the opposite side when that offers a better fit. */\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 availableHeight: number | null = null;\n  @State() private focusRingVisible: boolean = false;\n  @State() private reorderFromFlat: number | null = null;\n  @State() private reorderInsertBefore: number | null = null;\n  @State() private reorderAnnouncement = '';\n\n  @Event() dsClose!: EventEmitter<void>;\n  /** Emitted after the popup's exit motion is complete and its rendered content is removed. */\n  @Event() dsAfterClose!: EventEmitter<void>;\n  @Event() dsSelect!: EventEmitter<MenuItemData>;\n  /** Emitted when a generic `swatch-picker` section option is chosen. */\n  @Event() dsSwatchSelect!: EventEmitter<string>;\n  /** Emitted after a pointer drop or keyboard move; Menu never mutates item order. */\n  @Event() dsReorder!: EventEmitter<MenuReorderDetail>;\n\n  private clickOutsideHandler: ((e: MouseEvent) => void) | null = null;\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n  private positionReadyCallback: (() => void) | undefined;\n  private suppressItemClick = false;\n  private reorderPointer: {\n    pointerId: number;\n    sectionIndex: number;\n    fromIndex: number;\n  } | null = null;\n  /**\n   * Anchored placement. The choice-cell measurement stays here on purpose: the\n   * inner-cell align offset and the `--dimension-menu-width-xs` floor are Menu\n   * semantics, not shared geometry.\n   */\n  private readonly position = new AnchoredPositionController({\n    getAnchor: () => this.resolvedAnchor ?? null,\n    getPopup: () => this.el.querySelector<HTMLElement>('.menu-popup'),\n    measure: (anchorEl, popup) => {\n      if (!this.open) return null;\n\n      const anchorRect = anchorEl.getBoundingClientRect();\n      const sectionInsetPx = this.viewportPadPx;\n      if (!this.minWidth) {\n        if (\n          this.anchorAlignment === 'choice-cell' &&\n          (this.side === 'top' || this.side === 'bottom')\n        ) {\n          popup.style.minWidth = `max(var(--dimension-menu-width-xs), ${choicePopupMinWidth(\n            anchorRect.width,\n            sectionInsetPx\n          )}px)`;\n        } else {\n          popup.style.removeProperty('min-width');\n        }\n      }\n\n      const viewportPadPx = this.viewportPadPx;\n      const list = popup.querySelector<HTMLElement>('.ds-choice-list');\n      const naturalPopupHeight = Math.min(\n        Math.max(popup.offsetHeight, list?.scrollHeight ?? 0),\n        window.innerHeight - viewportPadPx * 2\n      );\n      const input: AnchoredPositionInput = {\n        anchorRect,\n        popupWidth: popup.offsetWidth || this.popupFallbackWidthPx,\n        popupHeight: naturalPopupHeight || 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,\n        viewportWidth: window.innerWidth,\n        viewportHeight: window.innerHeight,\n      };\n      const unconstrained = computeAnchoredPosition(input);\n      return {\n        ...input,\n        popupHeight: Math.min(input.popupHeight, unconstrained.availableHeight),\n      };\n    },\n    apply: ({ x, y, availableHeight }) => {\n      this.pos = { x, y };\n      this.availableHeight = availableHeight;\n    },\n    onReady: () => {\n      this.positionReady = true;\n    },\n    liveUpdate: 'double-frame',\n    topLayer: true,\n  });\n  /** Last content actually painted while open; retained unchanged through exit motion. */\n  private lastRenderedSections: MenuSection[] = [];\n  private closingSections: MenuSection[] | null = null;\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  disconnectedCallback() {\n    this.cancelPositionRetry();\n    this.cancelLivePositionUpdate();\n    this.clearReorderPointer();\n    this.teardownListeners();\n  }\n\n  @Watch('open')\n  onOpenChange(isOpen: boolean) {\n    if (isOpen) {\n      this.teardownListeners();\n      this.closingSections = null;\n      this.shouldRender = true;\n      this.closing = false;\n      this.positionReady = false;\n      this.availableHeight = null;\n      this.focusRingVisible = this.initialFocusVisible;\n      this.setupListeners();\n      this.schedulePositionUpdate(() => {\n        this.focusInitialItem();\n      });\n    } else if (this.shouldRender) {\n      this.positionReadyCallback = undefined;\n      this.cancelPositionRetry();\n      this.captureClosingSections();\n      this.closing = true;\n      this.teardownListeners();\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    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (popup?.matches(':popover-open')) popup.hidePopover();\n    this.shouldRender = false;\n    this.closing = false;\n    this.lastRenderedSections = [];\n    this.closingSections = null;\n    this.clearReorderPointer();\n    this.reorderAnnouncement = '';\n    this.dsAfterClose.emit();\n  }\n\n  private captureClosingSections() {\n    if (this.closingSections) return;\n    const visibleSections = this.lastRenderedSections.length\n      ? this.lastRenderedSections\n      : this.activeSections;\n    this.closingSections = snapshotMenuSections(visibleSections);\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\n      (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(\n      document.querySelectorAll<HTMLElement>(MENU_FOCUSABLE_SELECTOR)\n    ).filter(\n      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(\n      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    this.position.cancel();\n  }\n\n  private cancelLivePositionUpdate() {\n    this.position.cancel();\n  }\n\n  /** Reposition after the current scroll/layout frame without hiding the open popup. */\n  private scheduleLivePositionUpdate() {\n    this.position.scheduleLiveUpdate();\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    this.positionReady = false;\n    // Opening often sets `open` and `anchorId` together. Each Watch reschedules\n    // placement; keep the open-path ready callback so initial focus is not dropped.\n    if (onReady) this.positionReadyCallback = onReady;\n    const callback = this.positionReadyCallback;\n    this.position.schedule(() => {\n      if (this.positionReadyCallback === callback) {\n        this.positionReadyCallback = undefined;\n      }\n      callback?.();\n    });\n  }\n\n  /** @returns `true` when anchor and popup were found and `pos` was updated. */\n  private calculatePosition(): boolean {\n    return this.position.update();\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 || !!it.reorderable);\n    this.focusedIndex = selectedIdx >= 0 ? selectedIdx : 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    document.addEventListener('mousedown', this.clickOutsideHandler, true);\n    this.position.observe();\n  }\n\n  private teardownListeners() {\n    this.position.unobserve();\n    if (this.clickOutsideHandler) {\n      document.removeEventListener('mousedown', this.clickOutsideHandler, true);\n      this.clickOutsideHandler = null;\n    }\n    if (this.closeTimer) {\n      clearTimeout(this.closeTimer);\n      this.closeTimer = null;\n    }\n  }\n\n  private close(restoreFocus = true) {\n    this.captureClosingSections();\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    if ((e.key === 'ArrowUp' || e.key === 'ArrowDown') && e.altKey && !e.ctrlKey && !e.shiftKey) {\n      this.handleReorderKey(e);\n      return;\n    }\n\n    const flat = this.flatItems;\n    const enabled = flat\n      .map((it, i) => ({ it, i }))\n      .filter(({ it }) => !it.isInactive || !!it.reorderable)\n      .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();\n        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();\n        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();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[0];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'End':\n        e.preventDefault();\n        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 (this.suppressItemClick) {\n      this.suppressItemClick = false;\n      return;\n    }\n    if (item.isInactive) return;\n    // Consumers commonly change the item source while handling selection.\n    // Capture first so the exit animation never paints the next menu context.\n    this.captureClosingSections();\n    this.dsSelect.emit(item);\n  }\n\n  private handleSwatchSelect(value: string) {\n    this.dsSwatchSelect.emit(value);\n  }\n\n  private handleReorderKey(event: KeyboardEvent): void {\n    const located = locateMenuItem(this.activeSections, this.focusedIndex);\n    if (!located || !located.items[located.itemIndex]?.reorderable) return;\n\n    const nextItems = moveReorderableMenuItemBy(\n      located.items,\n      located.itemIndex,\n      event.key === 'ArrowUp' ? -1 : 1\n    );\n    if (!nextItems) return;\n\n    event.preventDefault();\n    event.stopPropagation();\n    this.emitReorder(located.items, located.itemIndex, nextItems, located.sectionIndex);\n  }\n\n  private emitReorder(\n    items: MenuItemData[],\n    fromIndex: number,\n    nextItems: MenuItemData[],\n    sectionIndex: number\n  ): void {\n    const detail = createMenuReorderDetail(items, fromIndex, nextItems, sectionIndex);\n    if (!detail) return;\n    this.focusedIndex = this.flatIndexFor(sectionIndex, detail.toIndex);\n    this.announceReorder(detail);\n    this.dsReorder.emit(detail);\n  }\n\n  private flatIndexFor(sectionIndex: number, itemIndex: number): number {\n    let flat = 0;\n    for (let index = 0; index < this.activeSections.length; index += 1) {\n      const section = this.activeSections[index];\n      if (isMenuPickerSection(section)) continue;\n      if (index === sectionIndex) return flat + itemIndex;\n      flat += section.items.length;\n    }\n    return itemIndex;\n  }\n\n  private announceReorder(detail: MenuReorderDetail): void {\n    const range = menuReorderableRange(detail.items, detail.toIndex);\n    const count = range ? range.end - range.start + 1 : detail.items.length;\n    const position = range ? detail.toIndex - range.start + 1 : detail.toIndex + 1;\n    this.reorderAnnouncement = `${detail.item.label} moved to position ${position} of ${count}`;\n  }\n\n  private onReorderPointerDown(\n    event: PointerEvent,\n    sectionIndex: number,\n    itemIndex: number,\n    flatIndex: number\n  ): void {\n    if (event.button !== 0) return;\n    const section = this.activeSections[sectionIndex];\n    if (!section || isMenuPickerSection(section)) return;\n    if (!section.items[itemIndex]?.reorderable) return;\n\n    event.preventDefault();\n    event.stopPropagation();\n    this.suppressItemClick = true;\n    this.focusRingVisible = false;\n    this.focusedIndex = flatIndex;\n    this.focusItem(flatIndex);\n    this.reorderPointer = {\n      pointerId: event.pointerId,\n      sectionIndex,\n      fromIndex: itemIndex,\n    };\n    this.reorderFromFlat = flatIndex;\n    this.reorderInsertBefore = itemIndex;\n    window.addEventListener('pointermove', this.onReorderPointerMove);\n    window.addEventListener('pointerup', this.onReorderPointerUp);\n    window.addEventListener('pointercancel', this.onReorderPointerCancel);\n  }\n\n  private onReorderPointerMove = (event: PointerEvent) => {\n    const drag = this.reorderPointer;\n    if (!drag || event.pointerId !== drag.pointerId) return;\n    const section = this.activeSections[drag.sectionIndex];\n    if (!section || isMenuPickerSection(section)) return;\n\n    const insertBefore = this.resolveReorderInsertBefore(\n      event.clientY,\n      drag.sectionIndex,\n      drag.fromIndex,\n      section.items\n    );\n    if (insertBefore !== this.reorderInsertBefore) this.reorderInsertBefore = insertBefore;\n  };\n\n  private onReorderPointerUp = (event: PointerEvent) => {\n    const drag = this.reorderPointer;\n    if (!drag || event.pointerId !== drag.pointerId) return;\n\n    const section = this.activeSections[drag.sectionIndex];\n    const insertBefore = this.reorderInsertBefore;\n    this.clearReorderPointer();\n    queueMicrotask(() => {\n      this.suppressItemClick = false;\n    });\n    if (!section || isMenuPickerSection(section) || insertBefore === null) return;\n\n    const nextItems = moveReorderableMenuItemBefore(section.items, drag.fromIndex, insertBefore);\n    if (!nextItems) return;\n    this.emitReorder(section.items, drag.fromIndex, nextItems, drag.sectionIndex);\n  };\n\n  private onReorderPointerCancel = (event: PointerEvent) => {\n    if (!this.reorderPointer || event.pointerId !== this.reorderPointer.pointerId) return;\n    this.clearReorderPointer();\n    queueMicrotask(() => {\n      this.suppressItemClick = false;\n    });\n  };\n\n  private resolveReorderInsertBefore(\n    clientY: number,\n    sectionIndex: number,\n    fromIndex: number,\n    items: MenuItemData[]\n  ): number {\n    const range = menuReorderableRange(items, fromIndex);\n    if (!range) return fromIndex;\n\n    const buttons = [...this.el.querySelectorAll<HTMLElement>('.menu-item')];\n    const sectionStart = this.flatIndexFor(sectionIndex, 0);\n    let insertBefore = range.end + 1;\n    for (let itemIndex = range.start; itemIndex <= range.end; itemIndex += 1) {\n      const row = buttons[sectionStart + itemIndex];\n      if (!row) continue;\n      const rect = row.getBoundingClientRect();\n      if (clientY < rect.top + rect.height / 2) {\n        insertBefore = itemIndex;\n        break;\n      }\n    }\n    return Math.min(Math.max(insertBefore, range.start), range.end + 1);\n  }\n\n  private clearReorderPointer(): void {\n    if (this.reorderPointer) {\n      window.removeEventListener('pointermove', this.onReorderPointerMove);\n      window.removeEventListener('pointerup', this.onReorderPointerUp);\n      window.removeEventListener('pointercancel', this.onReorderPointerCancel);\n    }\n    this.reorderPointer = null;\n    this.reorderFromFlat = null;\n    this.reorderInsertBefore = null;\n  }\n\n  render() {\n    if (!this.shouldRender) return <Host style={{ display: 'contents' }} />;\n\n    const sections = this.closing\n      ? (this.closingSections ?? this.lastRenderedSections)\n      : this.activeSections;\n    const hasCompositeSections = sections.some(isMenuPickerSection);\n    if (!this.closing) {\n      this.lastRenderedSections = snapshotMenuSections(sections);\n      this.closingSections = null;\n    }\n    let flatIdx = 0;\n    const dragLocated =\n      this.reorderFromFlat === null ? null : locateMenuItem(sections, this.reorderFromFlat);\n    const dragRange = dragLocated\n      ? menuReorderableRange(dragLocated.items, dragLocated.itemIndex)\n      : null;\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    if (this.availableHeight !== null) {\n      popupStyle['max-height'] = `${Math.floor(this.availableHeight)}px`;\n    }\n\n    return (\n      <Host style={{ display: 'contents' }}>\n        <div\n          popover=\"manual\"\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={hasCompositeSections ? 'dialog' : 'menu'}\n          aria-label={this.menuLabel}\n          aria-orientation={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--swatch-picker': isMenuPickerSection(section),\n                  'ds-choice-section': true,\n                  'ds-chrome-column': true,\n                  'ds-chrome-space--sm': true,\n                  'ds-choice-section--divided': si < sections.length - 1,\n                  'ds-choice-section--headed-after-first': si > 0 && Boolean(section.header),\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-section-heading ds-control--${this.size}`}\n                    as=\"span\"\n                    variant={CONTROL_SUPPORTING_TEXT_VARIANT[this.size]}\n                    emphasis\n                    color=\"primary\"\n                    aria-hidden=\"true\"\n                  >\n                    <span class=\"ds-choice-section__header-label\">{section.header}</span>\n                  </ds-text>\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, itemIndex) => {\n                    const idx = flatIdx++;\n                    const isFocused = this.focusedIndex === idx;\n                    const isSingleSelectionItem =\n                      !hasCompositeSections && this.selectionMode === 'single' && !item.showSwitch;\n                    const usesLeading = section.items.some(\n                      candidate => candidate.reorderable || !!candidate.icon\n                    );\n                    const locked = !!item.isInactive && !item.reorderable;\n                    const dragging = this.reorderFromFlat === idx;\n                    const dropBefore =\n                      dragLocated?.sectionIndex === si &&\n                      dragRange !== null &&\n                      itemIndex <= dragRange.end &&\n                      this.reorderInsertBefore === itemIndex;\n                    const dropAfter =\n                      dragLocated?.sectionIndex === si &&\n                      dragRange !== null &&\n                      this.reorderInsertBefore === dragRange.end + 1 &&\n                      itemIndex === dragRange.end;\n                    return (\n                      <button\n                        key={item.value ?? `${si}-${item.label}`}\n                        type=\"button\"\n                        class={{\n                          'menu-item': true,\n                          'ds-choice-item': true,\n                          'ds-control-frame': true,\n                          [`ds-control--${this.size}`]: true,\n                          'ds-focus-ring-inset': true,\n                          'ds-focus-ring--visible': isFocused && this.focusRingVisible,\n                          'ds-interaction-fill': !locked,\n                          'ds-interaction-fill--selected': !!item.isSelected && !locked,\n                          'menu-item--selected': !!item.isSelected,\n                          'menu-item--switch': !!item.showSwitch,\n                          'ds-control-inactive': locked,\n                          'menu-item--destructive': !!item.isDestructive,\n                          'menu-item--focused': isFocused,\n                          'menu-item--dragging': dragging,\n                        }}\n                        role={\n                          hasCompositeSections\n                            ? undefined\n                            : item.showSwitch\n                              ? 'menuitemcheckbox'\n                              : isSingleSelectionItem\n                                ? 'menuitemradio'\n                                : 'menuitem'\n                        }\n                        aria-checked={\n                          !hasCompositeSections && item.showSwitch\n                            ? String(!!item.switchValue)\n                            : isSingleSelectionItem\n                              ? String(!!item.isSelected)\n                              : undefined\n                        }\n                        aria-pressed={\n                          hasCompositeSections\n                            ? String(item.showSwitch ? !!item.switchValue : !!item.isSelected)\n                            : undefined\n                        }\n                        aria-current={\n                          !hasCompositeSections &&\n                          !item.showSwitch &&\n                          !isSingleSelectionItem &&\n                          item.isSelected\n                            ? 'true'\n                            : undefined\n                        }\n                        aria-description={\n                          item.reorderable\n                            ? item.isInactive\n                              ? 'Visibility cannot be changed. Alt + Arrow Up or Alt + Arrow Down moves this row.'\n                              : 'Drag to reorder. Alt + Arrow Up or Alt + Arrow Down moves this row.'\n                            : undefined\n                        }\n                        aria-disabled={item.isInactive ? 'true' : undefined}\n                        disabled={locked}\n                        tabIndex={hasCompositeSections ? 0 : isFocused ? 0 : -1}\n                        onMouseDown={() => {\n                          this.focusRingVisible = false;\n                        }}\n                        onClick={() => this.handleItemClick(item)}\n                        onFocus={() => {\n                          this.focusedIndex = idx;\n                        }}\n                      >\n                        {(dropBefore || dropAfter) && (\n                          <span\n                            class={{\n                              'menu-item__drop-rail': true,\n                              'menu-item__drop-rail--before': dropBefore,\n                              'menu-item__drop-rail--after': dropAfter,\n                            }}\n                            data-menu-drop-rail\n                            aria-hidden=\"true\"\n                          />\n                        )}\n                        {item.reorderable ? (\n                          <span\n                            class=\"menu-item__handle ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\"\n                            data-menu-handle\n                            aria-hidden=\"true\"\n                            onPointerDown={event =>\n                              this.onReorderPointerDown(event, si, itemIndex, idx)\n                            }\n                            onClick={event => {\n                              event.preventDefault();\n                              event.stopPropagation();\n                            }}\n                          >\n                            <ds-icon name=\"Drag\" size={this.size} color=\"inherit\" />\n                          </span>\n                        ) : usesLeading && item.icon ? (\n                          <span\n                            class=\"menu-item__icon ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\"\n                            aria-hidden=\"true\"\n                          >\n                            <ds-icon name={item.icon} size={this.size} color=\"inherit\" />\n                          </span>\n                        ) : usesLeading ? (\n                          <span\n                            class=\"menu-item__icon-spacer ds-choice-item__icon ds-control-icon-box\"\n                            aria-hidden=\"true\"\n                          />\n                        ) : null}\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 ds-control-label-box\"\n                            as=\"span\"\n                            variant={CONTROL_TEXT_VARIANT[this.size]}\n                            color={item.isSelected ? 'primary' : 'secondary'}\n                          >\n                            {item.label}\n                          </ds-text>\n                          {item.subtext && (\n                            <ds-text\n                              class=\"menu-item__subtext ds-choice-item__subtext ds-control-label-box\"\n                              as=\"span\"\n                              variant={CONTROL_SUPPORTING_TEXT_VARIANT[this.size]}\n                              color=\"secondary\"\n                            >\n                              {item.subtext}\n                            </ds-text>\n                          )}\n                        </div>\n                        {item.tag && (\n                          <ds-tag\n                            class=\"ds-choice-item__tag ds-interaction-fill__content\"\n                            label={item.tag.label}\n                            size={MENU_ITEM_TAG_SIZE[this.size]}\n                            intent={item.tag.intent ?? 'neutral'}\n                            contrast={item.tag.contrast ?? 'faint'}\n                            rounded={item.tag.rounded ?? false}\n                            isInset\n                          />\n                        )}\n                        {item.dot && (\n                          <span\n                            class=\"menu-item__dot-box ds-interaction-fill__content\"\n                            aria-hidden=\"true\"\n                          >\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={this.size}\n                            checked={!!item.switchValue}\n                            isInactive={!!item.isInactive}\n                            presentation\n                          />\n                        )}\n                      </button>\n                    );\n                  })\n                )}\n              </div>\n            ))}\n          </div>\n        </div>\n        <div class=\"ds-visually-hidden\" role=\"status\" aria-live=\"polite\">\n          {this.reorderAnnouncement}\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Prop,\n  State,\n  Event,\n  EventEmitter,\n  Element,\n  Watch,\n  Listen,\n  h,\n  Host,\n} from '@stencil/core';\nimport {\n  choicePopupMinWidth,\n  CONTROL_SUPPORTING_TEXT_VARIANT,\n  CONTROL_TEXT_VARIANT,\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n  type ChoicePopupAnchorAlignment,\n  type ControlSize,\n} from '../../utils';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\nimport { AnchoredOverlayInteractionController } from '../../utils/anchored-overlay-interaction-controller';\nimport { resolveAnchoredOverlayBoundaryRect } from '../../utils/anchored-overlay-boundary';\nimport { computeAnchoredPosition, type AnchoredPositionInput } from '../../utils/anchored-position';\nimport type { MenuAlign, MenuSide } from './menu-position';\nimport {\n  isMenuPickerSection,\n  isMenuSwatchPickerSection,\n  type MenuItemData,\n  type MenuReorderDetail,\n  type MenuSection,\n} from './menu-types';\nimport { snapshotMenuSections } from './menu-sections';\nimport {\n  createMenuReorderDetail,\n  locateMenuItem,\n  menuReorderableRange,\n  moveReorderableMenuItemBefore,\n  moveReorderableMenuItemBy,\n} from './menu-reorder';\n\nexport type MenuSelectionMode = 'none' | 'single';\nexport type MenuSize = ControlSize;\nconst MENU_ITEM_TAG_SIZE: Record<MenuSize, 'md' | 'sm' | 'xs'> = {\n  lg: 'md',\n  md: 'sm',\n  sm: 'xs',\n  xs: 'xs',\n};\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  /** Choice-row density. */\n  @Prop() size: MenuSize = 'md';\n  /** Give ordinary rows mutually-exclusive menu semantics using isSelected. */\n  @Prop() selectionMode: MenuSelectionMode = 'none';\n  @Prop() sections: MenuSection[] = [];\n  /** Preferred side; placement flips to the opposite side when that offers a better fit. */\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  /** Explicit collision owner; otherwise the nearest data-ds-overlay-boundary ancestor is used. */\n  @Prop() boundary: HTMLElement | 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 availableHeight: number | null = null;\n  @State() private focusRingVisible: boolean = false;\n  @State() private reorderFromFlat: number | null = null;\n  @State() private reorderInsertBefore: number | null = null;\n  @State() private reorderAnnouncement = '';\n\n  @Event() dsClose!: EventEmitter<void>;\n  /** Emitted after the popup's exit motion is complete and its rendered content is removed. */\n  @Event() dsAfterClose!: EventEmitter<void>;\n  @Event() dsSelect!: EventEmitter<MenuItemData>;\n  /** Emitted when a generic `swatch-picker` section option is chosen. */\n  @Event() dsSwatchSelect!: EventEmitter<string>;\n  /** Emitted after a pointer drop or keyboard move; Menu never mutates item order. */\n  @Event() dsReorder!: EventEmitter<MenuReorderDetail>;\n\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n  private positionReadyCallback: (() => void) | undefined;\n  private suppressItemClick = false;\n  private reorderPointer: {\n    pointerId: number;\n    sectionIndex: number;\n    fromIndex: number;\n  } | null = null;\n  /**\n   * Anchored placement. The choice-cell measurement stays here on purpose: the\n   * inner-cell align offset and the `--dimension-menu-width-xs` floor are Menu\n   * semantics, not shared geometry.\n   */\n  private readonly position = new AnchoredPositionController({\n    getAnchor: () => this.resolvedAnchor ?? null,\n    getPopup: () => this.el.querySelector<HTMLElement>('.menu-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    measure: (anchorEl, popup) => {\n      if (!this.open) return null;\n\n      const anchorRect = anchorEl.getBoundingClientRect();\n      const sectionInsetPx = this.viewportPadPx;\n      if (!this.minWidth) {\n        if (\n          this.anchorAlignment === 'choice-cell' &&\n          (this.side === 'top' || this.side === 'bottom')\n        ) {\n          popup.style.minWidth = `max(var(--dimension-menu-width-xs), ${choicePopupMinWidth(\n            anchorRect.width,\n            sectionInsetPx\n          )}px)`;\n        } else {\n          popup.style.removeProperty('min-width');\n        }\n      }\n\n      const viewportPadPx = this.viewportPadPx;\n      const list = popup.querySelector<HTMLElement>('.ds-choice-list');\n      const naturalPopupHeight = Math.min(\n        Math.max(popup.offsetHeight, list?.scrollHeight ?? 0),\n        window.innerHeight - viewportPadPx * 2\n      );\n      const input: AnchoredPositionInput = {\n        anchorRect,\n        popupWidth: popup.offsetWidth || this.popupFallbackWidthPx,\n        popupHeight: naturalPopupHeight || 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,\n        viewportWidth: window.innerWidth,\n        viewportHeight: window.innerHeight,\n        collisionRect: resolveAnchoredOverlayBoundaryRect(anchorEl, this.boundary),\n      };\n      const unconstrained = computeAnchoredPosition(input);\n      return {\n        ...input,\n        popupHeight: Math.min(input.popupHeight, unconstrained.availableHeight),\n      };\n    },\n    apply: ({ x, y, availableHeight }) => {\n      this.pos = { x, y };\n      this.availableHeight = availableHeight;\n    },\n    onReady: () => {\n      this.positionReady = true;\n    },\n    liveUpdate: 'double-frame',\n    topLayer: true,\n    observeResize: true,\n    observeAnchorMotion: true,\n  });\n  private readonly interaction = new AnchoredOverlayInteractionController({\n    getAnchor: () => this.resolvedAnchor,\n    getPopup: () => this.el.querySelector<HTMLElement>('.menu-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    onOutsideActivation: () => this.close(),\n  });\n  /** Last content actually painted while open; retained unchanged through exit motion. */\n  private lastRenderedSections: MenuSection[] = [];\n  private closingSections: MenuSection[] | null = null;\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  disconnectedCallback() {\n    this.cancelPositionRetry();\n    this.cancelLivePositionUpdate();\n    this.clearReorderPointer();\n    this.teardownListeners();\n  }\n\n  @Watch('open')\n  onOpenChange(isOpen: boolean) {\n    if (isOpen) {\n      this.teardownListeners();\n      this.closingSections = null;\n      this.shouldRender = true;\n      this.closing = false;\n      this.positionReady = false;\n      this.availableHeight = null;\n      this.focusRingVisible = this.initialFocusVisible;\n      this.setupListeners();\n      this.schedulePositionUpdate(() => {\n        this.focusInitialItem();\n      });\n    } else if (this.shouldRender) {\n      this.positionReadyCallback = undefined;\n      this.cancelPositionRetry();\n      this.captureClosingSections();\n      this.closing = true;\n      this.teardownListeners();\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  @Watch('boundary')\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    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (popup?.matches(':popover-open')) popup.hidePopover();\n    this.shouldRender = false;\n    this.closing = false;\n    this.lastRenderedSections = [];\n    this.closingSections = null;\n    this.clearReorderPointer();\n    this.reorderAnnouncement = '';\n    this.dsAfterClose.emit();\n  }\n\n  private captureClosingSections() {\n    if (this.closingSections) return;\n    const visibleSections = this.lastRenderedSections.length\n      ? this.lastRenderedSections\n      : this.activeSections;\n    this.closingSections = snapshotMenuSections(visibleSections);\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 compositeTabLeavesPopup(event: KeyboardEvent): boolean {\n    return this.interaction.tabLeavesPopup(event);\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    this.position.cancel();\n  }\n\n  private cancelLivePositionUpdate() {\n    this.position.cancel();\n  }\n\n  /** Reposition after the current scroll/layout frame without hiding the open popup. */\n  private scheduleLivePositionUpdate() {\n    this.position.scheduleLiveUpdate();\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    this.positionReady = false;\n    // Opening often sets `open` and `anchorId` together. Each Watch reschedules\n    // placement; keep the open-path ready callback so initial focus is not dropped.\n    if (onReady) this.positionReadyCallback = onReady;\n    const callback = this.positionReadyCallback;\n    this.position.schedule(() => {\n      if (this.positionReadyCallback === callback) {\n        this.positionReadyCallback = undefined;\n      }\n      callback?.();\n    });\n  }\n\n  /** @returns `true` when anchor and popup were found and `pos` was updated. */\n  private calculatePosition(): boolean {\n    return this.position.update();\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 || !!it.reorderable);\n    this.focusedIndex = selectedIdx >= 0 ? selectedIdx : 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.interaction.connect();\n    this.position.observe();\n  }\n\n  private teardownListeners() {\n    this.position.unobserve();\n    this.interaction.disconnect();\n    if (this.closeTimer) {\n      clearTimeout(this.closeTimer);\n      this.closeTimer = null;\n    }\n  }\n\n  private close(restoreFocus = true) {\n    this.captureClosingSections();\n    if (restoreFocus) this.interaction.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.interaction.moveFocusAfterTab(e.shiftKey);\n      return;\n    }\n\n    if (this.hasCompositeSections) return;\n\n    if ((e.key === 'ArrowUp' || e.key === 'ArrowDown') && e.altKey && !e.ctrlKey && !e.shiftKey) {\n      this.handleReorderKey(e);\n      return;\n    }\n\n    const flat = this.flatItems;\n    const enabled = flat\n      .map((it, i) => ({ it, i }))\n      .filter(({ it }) => !it.isInactive || !!it.reorderable)\n      .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();\n        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();\n        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();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[0];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'End':\n        e.preventDefault();\n        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 (this.suppressItemClick) {\n      this.suppressItemClick = false;\n      return;\n    }\n    if (item.isInactive) return;\n    // Consumers commonly change the item source while handling selection.\n    // Capture first so the exit animation never paints the next menu context.\n    this.captureClosingSections();\n    this.dsSelect.emit(item);\n  }\n\n  private handleSwatchSelect(value: string) {\n    this.dsSwatchSelect.emit(value);\n  }\n\n  private handleReorderKey(event: KeyboardEvent): void {\n    const located = locateMenuItem(this.activeSections, this.focusedIndex);\n    if (!located || !located.items[located.itemIndex]?.reorderable) return;\n\n    const nextItems = moveReorderableMenuItemBy(\n      located.items,\n      located.itemIndex,\n      event.key === 'ArrowUp' ? -1 : 1\n    );\n    if (!nextItems) return;\n\n    event.preventDefault();\n    event.stopPropagation();\n    this.emitReorder(located.items, located.itemIndex, nextItems, located.sectionIndex);\n  }\n\n  private emitReorder(\n    items: MenuItemData[],\n    fromIndex: number,\n    nextItems: MenuItemData[],\n    sectionIndex: number\n  ): void {\n    const detail = createMenuReorderDetail(items, fromIndex, nextItems, sectionIndex);\n    if (!detail) return;\n    this.focusedIndex = this.flatIndexFor(sectionIndex, detail.toIndex);\n    this.announceReorder(detail);\n    this.dsReorder.emit(detail);\n  }\n\n  private flatIndexFor(sectionIndex: number, itemIndex: number): number {\n    let flat = 0;\n    for (let index = 0; index < this.activeSections.length; index += 1) {\n      const section = this.activeSections[index];\n      if (isMenuPickerSection(section)) continue;\n      if (index === sectionIndex) return flat + itemIndex;\n      flat += section.items.length;\n    }\n    return itemIndex;\n  }\n\n  private announceReorder(detail: MenuReorderDetail): void {\n    const range = menuReorderableRange(detail.items, detail.toIndex);\n    const count = range ? range.end - range.start + 1 : detail.items.length;\n    const position = range ? detail.toIndex - range.start + 1 : detail.toIndex + 1;\n    this.reorderAnnouncement = `${detail.item.label} moved to position ${position} of ${count}`;\n  }\n\n  private onReorderPointerDown(\n    event: PointerEvent,\n    sectionIndex: number,\n    itemIndex: number,\n    flatIndex: number\n  ): void {\n    if (event.button !== 0) return;\n    const section = this.activeSections[sectionIndex];\n    if (!section || isMenuPickerSection(section)) return;\n    if (!section.items[itemIndex]?.reorderable) return;\n\n    event.preventDefault();\n    event.stopPropagation();\n    this.suppressItemClick = true;\n    this.focusRingVisible = false;\n    this.focusedIndex = flatIndex;\n    this.focusItem(flatIndex);\n    this.reorderPointer = {\n      pointerId: event.pointerId,\n      sectionIndex,\n      fromIndex: itemIndex,\n    };\n    this.reorderFromFlat = flatIndex;\n    this.reorderInsertBefore = itemIndex;\n    window.addEventListener('pointermove', this.onReorderPointerMove);\n    window.addEventListener('pointerup', this.onReorderPointerUp);\n    window.addEventListener('pointercancel', this.onReorderPointerCancel);\n  }\n\n  private onReorderPointerMove = (event: PointerEvent) => {\n    const drag = this.reorderPointer;\n    if (!drag || event.pointerId !== drag.pointerId) return;\n    const section = this.activeSections[drag.sectionIndex];\n    if (!section || isMenuPickerSection(section)) return;\n\n    const insertBefore = this.resolveReorderInsertBefore(\n      event.clientY,\n      drag.sectionIndex,\n      drag.fromIndex,\n      section.items\n    );\n    if (insertBefore !== this.reorderInsertBefore) this.reorderInsertBefore = insertBefore;\n  };\n\n  private onReorderPointerUp = (event: PointerEvent) => {\n    const drag = this.reorderPointer;\n    if (!drag || event.pointerId !== drag.pointerId) return;\n\n    const section = this.activeSections[drag.sectionIndex];\n    const insertBefore = this.reorderInsertBefore;\n    this.clearReorderPointer();\n    queueMicrotask(() => {\n      this.suppressItemClick = false;\n    });\n    if (!section || isMenuPickerSection(section) || insertBefore === null) return;\n\n    const nextItems = moveReorderableMenuItemBefore(section.items, drag.fromIndex, insertBefore);\n    if (!nextItems) return;\n    this.emitReorder(section.items, drag.fromIndex, nextItems, drag.sectionIndex);\n  };\n\n  private onReorderPointerCancel = (event: PointerEvent) => {\n    if (!this.reorderPointer || event.pointerId !== this.reorderPointer.pointerId) return;\n    this.clearReorderPointer();\n    queueMicrotask(() => {\n      this.suppressItemClick = false;\n    });\n  };\n\n  private resolveReorderInsertBefore(\n    clientY: number,\n    sectionIndex: number,\n    fromIndex: number,\n    items: MenuItemData[]\n  ): number {\n    const range = menuReorderableRange(items, fromIndex);\n    if (!range) return fromIndex;\n\n    const buttons = [...this.el.querySelectorAll<HTMLElement>('.menu-item')];\n    const sectionStart = this.flatIndexFor(sectionIndex, 0);\n    let insertBefore = range.end + 1;\n    for (let itemIndex = range.start; itemIndex <= range.end; itemIndex += 1) {\n      const row = buttons[sectionStart + itemIndex];\n      if (!row) continue;\n      const rect = row.getBoundingClientRect();\n      if (clientY < rect.top + rect.height / 2) {\n        insertBefore = itemIndex;\n        break;\n      }\n    }\n    return Math.min(Math.max(insertBefore, range.start), range.end + 1);\n  }\n\n  private clearReorderPointer(): void {\n    if (this.reorderPointer) {\n      window.removeEventListener('pointermove', this.onReorderPointerMove);\n      window.removeEventListener('pointerup', this.onReorderPointerUp);\n      window.removeEventListener('pointercancel', this.onReorderPointerCancel);\n    }\n    this.reorderPointer = null;\n    this.reorderFromFlat = null;\n    this.reorderInsertBefore = null;\n  }\n\n  render() {\n    if (!this.shouldRender) return <Host style={{ display: 'contents' }} />;\n\n    const sections = this.closing\n      ? (this.closingSections ?? this.lastRenderedSections)\n      : this.activeSections;\n    const hasCompositeSections = sections.some(isMenuPickerSection);\n    if (!this.closing) {\n      this.lastRenderedSections = snapshotMenuSections(sections);\n      this.closingSections = null;\n    }\n    let flatIdx = 0;\n    const dragLocated =\n      this.reorderFromFlat === null ? null : locateMenuItem(sections, this.reorderFromFlat);\n    const dragRange = dragLocated\n      ? menuReorderableRange(dragLocated.items, dragLocated.itemIndex)\n      : null;\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    if (this.availableHeight !== null) {\n      popupStyle['max-height'] = `${Math.floor(this.availableHeight)}px`;\n    }\n\n    return (\n      <Host style={{ display: 'contents' }}>\n        <div\n          popover=\"manual\"\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={hasCompositeSections ? 'dialog' : 'menu'}\n          aria-label={this.menuLabel}\n          aria-orientation={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--swatch-picker': isMenuPickerSection(section),\n                  'ds-choice-section': true,\n                  'ds-chrome-column': true,\n                  'ds-chrome-space--sm': true,\n                  'ds-choice-section--divided': si < sections.length - 1,\n                  'ds-choice-section--headed-after-first': si > 0 && Boolean(section.header),\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-section-heading ds-control--${this.size}`}\n                    as=\"span\"\n                    variant={CONTROL_SUPPORTING_TEXT_VARIANT[this.size]}\n                    emphasis\n                    color=\"primary\"\n                    aria-hidden=\"true\"\n                  >\n                    <span class=\"ds-choice-section__header-label\">{section.header}</span>\n                  </ds-text>\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, itemIndex) => {\n                    const idx = flatIdx++;\n                    const isFocused = this.focusedIndex === idx;\n                    const isSingleSelectionItem =\n                      !hasCompositeSections && this.selectionMode === 'single' && !item.showSwitch;\n                    const usesLeading = section.items.some(\n                      candidate => candidate.reorderable || !!candidate.icon\n                    );\n                    const locked = !!item.isInactive && !item.reorderable;\n                    const dragging = this.reorderFromFlat === idx;\n                    const dropBefore =\n                      dragLocated?.sectionIndex === si &&\n                      dragRange !== null &&\n                      itemIndex <= dragRange.end &&\n                      this.reorderInsertBefore === itemIndex;\n                    const dropAfter =\n                      dragLocated?.sectionIndex === si &&\n                      dragRange !== null &&\n                      this.reorderInsertBefore === dragRange.end + 1 &&\n                      itemIndex === dragRange.end;\n                    return (\n                      <button\n                        key={item.value ?? `${si}-${item.label}`}\n                        type=\"button\"\n                        class={{\n                          'menu-item': true,\n                          'ds-choice-item': true,\n                          'ds-control-frame': true,\n                          [`ds-control--${this.size}`]: true,\n                          'ds-focus-ring-inset': true,\n                          'ds-focus-ring--visible': isFocused && this.focusRingVisible,\n                          'ds-interaction-fill': !locked,\n                          'ds-interaction-fill--selected': !!item.isSelected && !locked,\n                          'menu-item--selected': !!item.isSelected,\n                          'menu-item--switch': !!item.showSwitch,\n                          'ds-control-inactive': locked,\n                          'menu-item--destructive': !!item.isDestructive,\n                          'menu-item--focused': isFocused,\n                          'menu-item--dragging': dragging,\n                        }}\n                        role={\n                          hasCompositeSections\n                            ? undefined\n                            : item.showSwitch\n                              ? 'menuitemcheckbox'\n                              : isSingleSelectionItem\n                                ? 'menuitemradio'\n                                : 'menuitem'\n                        }\n                        aria-checked={\n                          !hasCompositeSections && item.showSwitch\n                            ? String(!!item.switchValue)\n                            : isSingleSelectionItem\n                              ? String(!!item.isSelected)\n                              : undefined\n                        }\n                        aria-pressed={\n                          hasCompositeSections\n                            ? String(item.showSwitch ? !!item.switchValue : !!item.isSelected)\n                            : undefined\n                        }\n                        aria-current={\n                          !hasCompositeSections &&\n                          !item.showSwitch &&\n                          !isSingleSelectionItem &&\n                          item.isSelected\n                            ? 'true'\n                            : undefined\n                        }\n                        aria-description={\n                          item.reorderable\n                            ? item.isInactive\n                              ? 'Visibility cannot be changed. Alt + Arrow Up or Alt + Arrow Down moves this row.'\n                              : 'Drag to reorder. Alt + Arrow Up or Alt + Arrow Down moves this row.'\n                            : undefined\n                        }\n                        aria-disabled={item.isInactive ? 'true' : undefined}\n                        disabled={locked}\n                        tabIndex={hasCompositeSections ? 0 : isFocused ? 0 : -1}\n                        onMouseDown={() => {\n                          this.focusRingVisible = false;\n                        }}\n                        onClick={() => this.handleItemClick(item)}\n                        onFocus={() => {\n                          this.focusedIndex = idx;\n                        }}\n                      >\n                        {(dropBefore || dropAfter) && (\n                          <span\n                            class={{\n                              'menu-item__drop-rail': true,\n                              'menu-item__drop-rail--before': dropBefore,\n                              'menu-item__drop-rail--after': dropAfter,\n                            }}\n                            data-menu-drop-rail\n                            aria-hidden=\"true\"\n                          />\n                        )}\n                        {item.reorderable ? (\n                          <span\n                            class=\"menu-item__handle ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\"\n                            data-menu-handle\n                            aria-hidden=\"true\"\n                            onPointerDown={event =>\n                              this.onReorderPointerDown(event, si, itemIndex, idx)\n                            }\n                            onClick={event => {\n                              event.preventDefault();\n                              event.stopPropagation();\n                            }}\n                          >\n                            <ds-icon name=\"Drag\" size={this.size} color=\"inherit\" />\n                          </span>\n                        ) : usesLeading && item.icon ? (\n                          <span\n                            class=\"menu-item__icon ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\"\n                            aria-hidden=\"true\"\n                          >\n                            <ds-icon name={item.icon} size={this.size} color=\"inherit\" />\n                          </span>\n                        ) : usesLeading ? (\n                          <span\n                            class=\"menu-item__icon-spacer ds-choice-item__icon ds-control-icon-box\"\n                            aria-hidden=\"true\"\n                          />\n                        ) : null}\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 ds-control-label-box\"\n                            as=\"span\"\n                            variant={CONTROL_TEXT_VARIANT[this.size]}\n                            color={item.isSelected ? 'primary' : 'secondary'}\n                          >\n                            {item.label}\n                          </ds-text>\n                          {item.subtext && (\n                            <ds-text\n                              class=\"menu-item__subtext ds-choice-item__subtext ds-control-label-box\"\n                              as=\"span\"\n                              variant={CONTROL_SUPPORTING_TEXT_VARIANT[this.size]}\n                              color=\"secondary\"\n                            >\n                              {item.subtext}\n                            </ds-text>\n                          )}\n                        </div>\n                        {item.tag && (\n                          <ds-tag\n                            class=\"ds-choice-item__tag ds-interaction-fill__content\"\n                            label={item.tag.label}\n                            size={MENU_ITEM_TAG_SIZE[this.size]}\n                            intent={item.tag.intent ?? 'neutral'}\n                            contrast={item.tag.contrast ?? 'faint'}\n                            rounded={item.tag.rounded ?? false}\n                            isInset\n                          />\n                        )}\n                        {item.dot && (\n                          <span\n                            class=\"menu-item__dot-box ds-interaction-fill__content\"\n                            aria-hidden=\"true\"\n                          >\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={this.size}\n                            checked={!!item.switchValue}\n                            isInactive={!!item.isInactive}\n                            presentation\n                          />\n                        )}\n                      </button>\n                    );\n                  })\n                )}\n              </div>\n            ))}\n          </div>\n        </div>\n        <div class=\"ds-visually-hidden\" role=\"status\" aria-live=\"polite\">\n          {this.reorderAnnouncement}\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {

package/dist/mcp-data/registry/message-composer.json

@@ -284,12 +284,12 @@
   "files": [
     {
       "path": "src/wc/components/MessageComposer/MessageComposer.css",
-      "content": "@import '../../utils/forced-colors.css';\n\n:host {\n  display: block;\n  width: 100%;\n  box-sizing: border-box;\n  -webkit-user-select: none;\n  user-select: none;\n}\n\n.message-composer {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050);\n  width: 100%;\n  margin: 0;\n}\n\n.message-composer__attachments:empty,\n.message-composer__tools:empty,\n.message-composer__error-actions:empty {\n  display: none;\n}\n\n.message-composer__error-support,\n.message-composer__error-message,\n.message-composer__error-actions {\n  display: flex;\n  align-items: center;\n}\n\n.message-composer__error-support {\n  justify-content: space-between;\n  flex-wrap: wrap;\n  gap: var(--dimension-space-075) var(--dimension-space-100);\n  min-width: 0;\n  padding: var(--dimension-space-075) var(--dimension-space-100);\n  background: var(--color-background-faint-negative);\n}\n\n.message-composer__error-message {\n  flex: 1 1 var(--dimension-panel-width-xs);\n  gap: var(--dimension-space-050);\n  min-width: 0;\n  color: var(--color-foreground-bold-negative);\n}\n\n.message-composer__error-actions {\n  flex: 0 1 auto;\n  flex-wrap: wrap;\n  gap: var(--dimension-space-050);\n}\n\n.message-composer__stack {\n  min-width: 0;\n}\n\n.message-composer--error .message-composer__stack {\n  overflow: hidden;\n  border: var(--dimension-stroke-width-012) solid var(--color-border-bold-negative);\n  border-radius: var(--dimension-radius-125);\n  background: var(--color-background-primary);\n  box-shadow: var(--effect-elevation-elevated-md);\n}\n\n.message-composer__field {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050);\n  padding: var(--dimension-space-100);\n  border-radius: var(--dimension-radius-125);\n  background: var(--color-background-primary);\n  box-shadow: var(--effect-elevation-elevated-md);\n  overflow: hidden;\n}\n\n.message-composer:not(.message-composer--error) .message-composer__field:focus-within {\n  box-shadow: var(--effect-elevation-elevated-md),\n    inset 0 0 0 var(--dimension-stroke-width-018) var(--color-border-bold-brand);\n}\n\n.message-composer--error .message-composer__field {\n  border-radius: 0;\n  box-shadow: none;\n}\n\ntextarea {\n  width: 100%;\n  min-height: calc(var(--typography-lineheight-md) * 2 + var(--dimension-space-150));\n  max-height: calc(var(--typography-lineheight-md) * 6 + var(--dimension-space-150));\n  padding: var(--dimension-space-075);\n  border: none;\n  outline: none;\n  resize: none;\n  overflow-y: auto;\n  box-sizing: border-box;\n  background: transparent;\n  color: var(--color-foreground-primary);\n  font-family: var(--typography-font-family-ui);\n  font-size: var(--typography-fontsize-md);\n  line-height: var(--typography-lineheight-md);\n  font-weight: var(--typography-weight-regular);\n  letter-spacing: var(--typography-letterspacing-negative-half);\n  -webkit-user-select: text;\n  user-select: text;\n}\n\ntextarea::placeholder {\n  color: var(--color-foreground-secondary);\n}\n\ntextarea:focus::placeholder {\n  color: var(--color-foreground-quaternary);\n}\n\ntextarea:focus,\ntextarea:focus-visible {\n  outline: none;\n}\n\n.message-composer__tools {\n  display: flex;\n  align-items: center;\n  gap: var(--dimension-space-050);\n  min-height: var(--dimension-size-400);\n}\n\n.message-composer__controls {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: var(--dimension-space-050);\n  width: 100%;\n  min-width: 0;\n}\n\n.message-composer__actions {\n  display: flex;\n  align-items: center;\n  gap: var(--dimension-space-100);\n  flex: 0 0 auto;\n  margin-inline-start: auto;\n}\n\n@media (forced-colors: active) {\n  .message-composer__field {\n    border: var(--dimension-stroke-width-012) solid var(--ds-forced-color-control-boundary);\n    box-shadow: none;\n  }\n\n  .message-composer--error .message-composer__field {\n    border: 0;\n  }\n\n  .message-composer--error .message-composer__stack {\n    border: var(--dimension-stroke-width-025) dashed var(--ds-forced-color-content);\n    box-shadow: none;\n  }\n\n  .message-composer__error-support {\n    border-block-end: var(--dimension-stroke-width-012) solid\n      var(--ds-forced-color-content);\n    background: var(--ds-forced-color-surface);\n  }\n}\n",
+      "content": "@import '../../utils/forced-colors.css';\n\n:host {\n  display: block;\n  width: 100%;\n  box-sizing: border-box;\n  -webkit-user-select: none;\n  user-select: none;\n}\n\n.message-composer {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050);\n  width: 100%;\n  margin: 0;\n}\n\n.message-composer__attachments:empty,\n.message-composer__tools:empty,\n.message-composer__error-actions:empty {\n  display: none;\n}\n\n.message-composer__error-support,\n.message-composer__error-message,\n.message-composer__error-actions {\n  display: flex;\n  align-items: center;\n}\n\n.message-composer__error-support {\n  justify-content: space-between;\n  flex-wrap: wrap;\n  gap: var(--dimension-space-075) var(--dimension-space-100);\n  min-width: 0;\n  padding: var(--dimension-space-075) var(--dimension-space-100);\n  background: var(--color-background-faint-negative);\n}\n\n.message-composer__error-message {\n  flex: 1 1 var(--dimension-panel-width-xs);\n  gap: var(--dimension-space-050);\n  min-width: 0;\n  color: var(--color-foreground-bold-negative);\n}\n\n.message-composer__error-actions {\n  flex: 0 1 auto;\n  flex-wrap: wrap;\n  gap: var(--dimension-space-050);\n}\n\n.message-composer__stack {\n  min-width: 0;\n}\n\n.message-composer--error .message-composer__stack {\n  overflow: hidden;\n  border: var(--dimension-stroke-width-012) solid var(--color-border-bold-negative);\n  border-radius: var(--dimension-radius-125);\n  background: var(--color-background-primary);\n  box-shadow: var(--effect-elevation-elevated-md);\n}\n\n.message-composer__field {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050);\n  padding: var(--dimension-space-100);\n  border-radius: var(--dimension-radius-125);\n  background: var(--color-background-primary);\n  box-shadow: var(--effect-elevation-elevated-md);\n  overflow: hidden;\n}\n\n.message-composer:not(.message-composer--error) .message-composer__field:focus-within {\n  box-shadow: var(--effect-elevation-elevated-md),\n    inset 0 0 0 var(--dimension-stroke-width-018) var(--color-border-bold-brand);\n}\n\n.message-composer--error .message-composer__field {\n  border-radius: 0;\n  box-shadow: none;\n}\n\ntextarea {\n  field-sizing: content;\n  width: 100%;\n  min-height: calc(var(--typography-lineheight-md) * 2 + var(--dimension-space-150));\n  max-height: calc(var(--typography-lineheight-md) * 6 + var(--dimension-space-150));\n  padding: var(--dimension-space-075);\n  border: none;\n  outline: none;\n  resize: none;\n  overflow-y: auto;\n  box-sizing: border-box;\n  background: transparent;\n  color: var(--color-foreground-primary);\n  font-family: var(--typography-font-family-ui);\n  font-size: var(--typography-fontsize-md);\n  line-height: var(--typography-lineheight-md);\n  font-weight: var(--typography-weight-regular);\n  letter-spacing: var(--typography-letterspacing-negative-half);\n  -webkit-user-select: text;\n  user-select: text;\n}\n\ntextarea::placeholder {\n  color: var(--color-foreground-secondary);\n}\n\ntextarea:focus::placeholder {\n  color: var(--color-foreground-quaternary);\n}\n\ntextarea:focus,\ntextarea:focus-visible {\n  outline: none;\n}\n\n.message-composer__tools {\n  display: flex;\n  align-items: center;\n  gap: var(--dimension-space-050);\n  min-height: var(--dimension-size-400);\n}\n\n.message-composer__controls {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: var(--dimension-space-050);\n  width: 100%;\n  min-width: 0;\n}\n\n.message-composer__actions {\n  display: flex;\n  align-items: center;\n  gap: var(--dimension-space-100);\n  flex: 0 0 auto;\n  margin-inline-start: auto;\n}\n\n@media (forced-colors: active) {\n  .message-composer__field {\n    border: var(--dimension-stroke-width-012) solid var(--ds-forced-color-control-boundary);\n    box-shadow: none;\n  }\n\n  .message-composer--error .message-composer__field {\n    border: 0;\n  }\n\n  .message-composer--error .message-composer__stack {\n    border: var(--dimension-stroke-width-025) dashed var(--ds-forced-color-content);\n    box-shadow: none;\n  }\n\n  .message-composer__error-support {\n    border-block-end: var(--dimension-stroke-width-012) solid\n      var(--ds-forced-color-content);\n    background: var(--ds-forced-color-surface);\n  }\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/MessageComposer/MessageComposer.tsx",
-      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  Watch,\n} from '@stencil/core';\nimport type { ButtonFilledIntent } from '../ButtonFilled/ButtonFilled';\nimport type { MessageComposerStatus } from '../conversation-types';\n\nlet composerId = 0;\n\n@Component({\n  tag: 'ds-message-composer',\n  styleUrl: 'MessageComposer.css',\n  scoped: true,\n})\nexport class MessageComposer {\n  @Element() el!: HTMLElement;\n\n  @Prop({ mutable: true }) value: string = '';\n  @Prop() placeholder: string = 'Write a message';\n  @Prop() label: string = 'Message';\n  @Prop() status: MessageComposerStatus = 'ready';\n  /** Submission failure shown while status is error. */\n  @Prop() errorMessage?: string;\n  @Prop() isInactive: boolean = false;\n  @Prop() submitIntent: ButtonFilledIntent = 'brand';\n\n  @Event() dsInput!: EventEmitter<string>;\n  @Event() dsSubmit!: EventEmitter<{ text: string }>;\n  @Event() dsStop!: EventEmitter<void>;\n\n  private textarea?: HTMLTextAreaElement;\n  private readonly errorId = `ds-message-composer-error-${++composerId}`;\n\n  componentDidLoad() {\n    this.resize();\n  }\n\n  @Watch('value')\n  onValueChange() {\n    requestAnimationFrame(() => this.resize());\n  }\n\n  @Method()\n  async setFocus() {\n    this.textarea?.focus();\n  }\n\n  private get streaming(): boolean {\n    return this.status === 'submitted' || this.status === 'streaming';\n  }\n\n  private resize() {\n    if (!this.textarea) return;\n    this.textarea.style.height = 'auto';\n    this.textarea.style.height = `${this.textarea.scrollHeight}px`;\n  }\n\n  private handleInput = (event: Event) => {\n    this.value = (event.target as HTMLTextAreaElement).value;\n    this.resize();\n    this.dsInput.emit(this.value);\n  };\n\n  private submit() {\n    const text = this.value.trim();\n    if (!text || this.isInactive || this.streaming) return;\n    this.dsSubmit.emit({ text });\n  }\n\n  private handleKeyDown = (event: KeyboardEvent) => {\n    if (event.key !== 'Enter' || event.shiftKey || event.isComposing) return;\n    event.preventDefault();\n    this.submit();\n  };\n\n  private handleAction = () => {\n    if (this.streaming) this.dsStop.emit();\n    else this.submit();\n  };\n\n  render() {\n    const error = this.status === 'error';\n    const visibleErrorMessage = this.errorMessage || 'Message could not be sent.';\n    const actionInactive = !this.streaming && (this.isInactive || !this.value.trim());\n    return (\n      <Host>\n        <form\n          class={{ 'message-composer': true, 'message-composer--error': error }}\n          aria-busy={this.streaming ? 'true' : undefined}\n          onSubmit={(event: Event) => {\n            event.preventDefault();\n            this.submit();\n          }}\n        >\n          <div class=\"message-composer__attachments\">\n            <slot name=\"attachments\" />\n          </div>\n          <div class=\"message-composer__stack\">\n            {error ? (\n              <div class=\"message-composer__error-support\">\n                <div id={this.errorId} class=\"message-composer__error-message\" role=\"alert\">\n                  <ds-icon name=\"ErrorTriangle\" size=\"xs\" color=\"inherit\" />\n                  <ds-text variant=\"text-body-small\" color=\"negative\">\n                    {visibleErrorMessage}\n                  </ds-text>\n                </div>\n                <div class=\"message-composer__error-actions\">\n                  <slot name=\"error-actions\" />\n                </div>\n              </div>\n            ) : null}\n            <div class=\"message-composer__field\">\n              <textarea\n                ref={element => {\n                  this.textarea = element;\n                }}\n                value={this.value}\n                placeholder={this.placeholder}\n                aria-label={this.label}\n                aria-invalid={error ? 'true' : undefined}\n                aria-describedby={error ? this.errorId : undefined}\n                disabled={this.isInactive}\n                rows={2}\n                onInput={this.handleInput}\n                onKeyDown={this.handleKeyDown}\n              />\n              <div class=\"message-composer__controls\">\n                <div class=\"message-composer__tools\">\n                  <slot name=\"tools\" />\n                </div>\n                <div class=\"message-composer__actions\">\n                  <slot name=\"actions\" />\n                  {actionInactive ? (\n                    <ds-tooltip label=\"Send message\" side=\"top\" size=\"sm\">\n                      <ds-button-unfilled\n                        class=\"message-composer__action\"\n                        variant=\"icon\"\n                        icon=\"ArrowUp\"\n                        size=\"md\"\n                        aria-label=\"Send message\"\n                        hasBorder\n                        isInactive\n                        onDsClick={this.handleAction}\n                      />\n                    </ds-tooltip>\n                  ) : (\n                    <ds-tooltip\n                      label={this.streaming ? 'Stop response' : 'Send message'}\n                      side=\"top\"\n                      size=\"sm\"\n                    >\n                      <ds-button-filled\n                        class=\"message-composer__action\"\n                        variant=\"icon\"\n                        icon={this.streaming ? 'SquareFilled' : 'ArrowUp'}\n                        intent={this.streaming ? 'brand' : this.submitIntent}\n                        contrast=\"bold\"\n                        size=\"md\"\n                        aria-label={this.streaming ? 'Stop response' : 'Send message'}\n                        onDsClick={this.handleAction}\n                      />\n                    </ds-tooltip>\n                  )}\n                </div>\n              </div>\n            </div>\n          </div>\n        </form>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n} from '@stencil/core';\nimport type { ButtonFilledIntent } from '../ButtonFilled/ButtonFilled';\nimport type { MessageComposerStatus } from '../conversation-types';\n\nlet composerId = 0;\n\n@Component({\n  tag: 'ds-message-composer',\n  styleUrl: 'MessageComposer.css',\n  scoped: true,\n})\nexport class MessageComposer {\n  @Element() el!: HTMLElement;\n\n  @Prop({ mutable: true }) value: string = '';\n  @Prop() placeholder: string = 'Write a message';\n  @Prop() label: string = 'Message';\n  @Prop() status: MessageComposerStatus = 'ready';\n  /** Submission failure shown while status is error. */\n  @Prop() errorMessage?: string;\n  @Prop() isInactive: boolean = false;\n  @Prop() submitIntent: ButtonFilledIntent = 'brand';\n\n  @Event() dsInput!: EventEmitter<string>;\n  @Event() dsSubmit!: EventEmitter<{ text: string }>;\n  @Event() dsStop!: EventEmitter<void>;\n\n  private textarea?: HTMLTextAreaElement;\n  private readonly errorId = `ds-message-composer-error-${++composerId}`;\n\n  @Method()\n  async setFocus() {\n    this.textarea?.focus();\n  }\n\n  private get streaming(): boolean {\n    return this.status === 'submitted' || this.status === 'streaming';\n  }\n\n  private handleInput = (event: Event) => {\n    this.value = (event.target as HTMLTextAreaElement).value;\n    this.dsInput.emit(this.value);\n  };\n\n  private submit() {\n    const text = this.value.trim();\n    if (!text || this.isInactive || this.streaming) return;\n    this.dsSubmit.emit({ text });\n  }\n\n  private handleKeyDown = (event: KeyboardEvent) => {\n    if (event.key !== 'Enter' || event.shiftKey || event.isComposing) return;\n    event.preventDefault();\n    this.submit();\n  };\n\n  private handleAction = () => {\n    if (this.streaming) this.dsStop.emit();\n    else this.submit();\n  };\n\n  render() {\n    const error = this.status === 'error';\n    const visibleErrorMessage = this.errorMessage || 'Message could not be sent.';\n    const actionInactive = !this.streaming && (this.isInactive || !this.value.trim());\n    return (\n      <Host>\n        <form\n          class={{ 'message-composer': true, 'message-composer--error': error }}\n          aria-busy={this.streaming ? 'true' : undefined}\n          onSubmit={(event: Event) => {\n            event.preventDefault();\n            this.submit();\n          }}\n        >\n          <div class=\"message-composer__attachments\">\n            <slot name=\"attachments\" />\n          </div>\n          <div class=\"message-composer__stack\">\n            {error ? (\n              <div class=\"message-composer__error-support\">\n                <div id={this.errorId} class=\"message-composer__error-message\" role=\"alert\">\n                  <ds-icon name=\"ErrorTriangle\" size=\"xs\" color=\"inherit\" />\n                  <ds-text variant=\"text-body-small\" color=\"negative\">\n                    {visibleErrorMessage}\n                  </ds-text>\n                </div>\n                <div class=\"message-composer__error-actions\">\n                  <slot name=\"error-actions\" />\n                </div>\n              </div>\n            ) : null}\n            <div class=\"message-composer__field\">\n              <textarea\n                ref={element => {\n                  this.textarea = element;\n                }}\n                value={this.value}\n                placeholder={this.placeholder}\n                aria-label={this.label}\n                aria-invalid={error ? 'true' : undefined}\n                aria-describedby={error ? this.errorId : undefined}\n                disabled={this.isInactive}\n                onInput={this.handleInput}\n                onKeyDown={this.handleKeyDown}\n              />\n              <div class=\"message-composer__controls\">\n                <div class=\"message-composer__tools\">\n                  <slot name=\"tools\" />\n                </div>\n                <div class=\"message-composer__actions\">\n                  <slot name=\"actions\" />\n                  {actionInactive ? (\n                    <ds-tooltip label=\"Send message\" side=\"top\" size=\"sm\">\n                      <ds-button-unfilled\n                        class=\"message-composer__action\"\n                        variant=\"icon\"\n                        icon=\"ArrowUp\"\n                        size=\"md\"\n                        aria-label=\"Send message\"\n                        hasBorder\n                        isInactive\n                        onDsClick={this.handleAction}\n                      />\n                    </ds-tooltip>\n                  ) : (\n                    <ds-tooltip\n                      label={this.streaming ? 'Stop response' : 'Send message'}\n                      side=\"top\"\n                      size=\"sm\"\n                    >\n                      <ds-button-filled\n                        class=\"message-composer__action\"\n                        variant=\"icon\"\n                        icon={this.streaming ? 'SquareFilled' : 'ArrowUp'}\n                        intent={this.streaming ? 'brand' : this.submitIntent}\n                        contrast=\"bold\"\n                        size=\"md\"\n                        aria-label={this.streaming ? 'Stop response' : 'Send message'}\n                        onDsClick={this.handleAction}\n                      />\n                    </ds-tooltip>\n                  )}\n                </div>\n              </div>\n            </div>\n          </div>\n        </form>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

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

@@ -2,7 +2,7 @@
   "$schema": "https://ui.shadcn.com/schema/registry-item.json",
   "name": "pagination",
   "title": "Pagination",
-  "description": "Controlled fixed or fitted page-size, compact range, and first/previous/next/last navigation for application-owned data windows.",
+  "description": "Controlled fixed or fitted page-size, compact range, adjacent-page navigation, and optional first/last controls for application-owned data windows.",
   "type": "registry:ui",
   "meta": {
     "library": "@ds-mo/ui",
@@ -13,14 +13,15 @@
     "intent": {
       "audience": "general",
       "status": "stable",
-      "summary": "Controlled fixed or fitted page-size, compact range, and first/previous/next/last navigation for application-owned data windows.",
+      "summary": "Controlled fixed or fitted page-size, compact range, adjacent-page navigation, and optional first/last controls for application-owned data windows.",
       "useWhen": [
         "A result set is divided into discrete pages and the application owns fetching or slicing each page.",
-        "A table or list needs a compact page-size selector, result range, and boundary-aware navigation."
+        "A table or list needs a compact page-size selector, result range, and boundary-aware navigation.",
+        "Direct first-page and last-page navigation is useful enough to opt into alongside the default Previous and Next controls."
       ],
       "avoidWhen": [
         "More results append to one continuous list; use the owning component's incremental-loading behavior instead.",
-        "Only previous and next navigation is meaningful and the total result count is unknown."
+        "The total result count is unknown; use an incremental-loading pattern instead."
       ],
       "commonlyComposedWith": [
         "component:ds-table",
@@ -31,18 +32,20 @@
         "The component renders a named navigation region, gives its compact page-size noun a complete accessible label, and gives every icon-only boundary control an explicit page action name.",
         "The visible page-size cluster states the localized noun, selected size, and current-page count of total, for example Rows: [25] 25 of 500. The page position uses compact ‘of’ phrasing, for example 1 of 20. A polite atomic status update retains the complete current range and ‘Page’ phrasing with the localized item noun.",
         "Left and Right Arrow request the adjacent page while focus is within pagination navigation controls. The page-size combobox retains its own arrow-key behavior.",
-        "Inactive boundary controls and every control during loading remain non-interactive while retaining their accessible names."
+        "Inactive boundary controls and every control during loading remain non-interactive while retaining their accessible names.",
+        "showFirstLastButtons adds explicitly named First page and Last page controls; Previous and Next remain present in either mode."
       ],
       "states": [
         "pageIndex, numeric effective pageSize, pageSizeMode, totalItems, and pageSizeOptions are controlled inputs. dsChange reports the complete next pagination state, previous index, size, and mode, and whether the request changed the page, page size, or fitted capacity; it never mutates controlled inputs.",
         "Page-size changes request the first page. Out-of-range page indexes and invalid numeric inputs normalize only for presentation; the owner remains authoritative.",
         "Zero results display 0–0 of 0 and Page 1 of 1. A partial final page caps the visible range at totalItems.",
         "loading preserves the full pagination surface, applies aria-busy to the navigation region, and prevents page or page-size requests.",
-        "fitToPage appends a Fit to page choice. fitPageSize supplies its effective whole-item capacity; the closed trigger says Fit while the range continues to expose the resulting count. fitToPageInactive keeps that choice visible but unavailable when fitting is not meaningful for the current data shape. Pagination does not measure layouts itself."
+        "fitToPage appends a Fit to page choice. fitPageSize supplies its effective whole-item capacity; the closed trigger says Fit while the range continues to expose the resulting count. fitToPageInactive keeps that choice visible but unavailable when fitting is not meaningful for the current data shape. Pagination does not measure layouts itself.",
+        "showFirstLastButtons defaults to false. Enable it when direct jumps to both result boundaries materially help the workflow."
       ],
       "responsiveBehavior": [
-        "The full-width controls remain on one line with noun, selected size, current-page count of total, a vertical divider, page position, and first, previous, next, and last navigation.",
-        "Inside a ds-table container narrower than 900px, pagination hides the visible current-page count and first/last boundary controls while retaining the page-size noun and selector plus previous, page position, and next. The complete current range remains available to assistive technology."
+        "The full-width controls remain on one line with noun, selected size, current-page count of total, a vertical divider, page position, Previous and Next, plus optional First and Last navigation.",
+        "Inside a ds-table container narrower than 900px, pagination hides the visible current-page count and any opted-in first/last controls while retaining the page-size noun and selector plus Previous, page position, and Next. The complete current range remains available to assistive technology."
       ],
       "frameworkCaveats": {
         "customElements": [
@@ -187,6 +190,15 @@
           "mutable": false,
           "description": "Available page sizes. Assign arrays through JavaScript."
         },
+        "showFirstLastButtons": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "show-first-last-buttons",
+          "default": "false",
+          "required": false,
+          "mutable": false,
+          "description": "Include direct first-page and last-page controls."
+        },
         "totalItems": {
           "type": "number",
           "resolvedType": "number",
@@ -334,6 +346,15 @@
         "mutable": false,
         "description": "Available page sizes. Assign arrays through JavaScript."
       },
+      "showFirstLastButtons": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "show-first-last-buttons",
+        "default": "false",
+        "required": false,
+        "mutable": false,
+        "description": "Include direct first-page and last-page controls."
+      },
       "totalItems": {
         "type": "number",
         "resolvedType": "number",
@@ -409,7 +430,7 @@
     },
     {
       "path": "src/wc/components/Pagination/Pagination.tsx",
-      "content": "import { Component, Element, Event, EventEmitter, h, Host, Prop, State } from '@stencil/core';\nimport { observeTableCaptionCompact } from '../../utils/table-caption-compact';\nimport { resolvePaginationState } from './pagination-model';\nimport type {\n  PaginationChangeDetail,\n  PaginationPageSizeMode,\n} from './pagination-types';\n\nlet paginationId = 0;\n\n@Component({\n  tag: 'ds-pagination',\n  styleUrl: 'Pagination.css',\n  scoped: true,\n})\nexport class Pagination {\n  @Element() el!: HTMLElement;\n\n  /** Controlled zero-based page index. */\n  @Prop() pageIndex: number = 0;\n  /** Controlled number of top-level items on a full page. */\n  @Prop() pageSize: number = 25;\n  /** Whether pageSize is a fixed choice or a measured Fit snapshot. */\n  @Prop() pageSizeMode: PaginationPageSizeMode = 'fixed';\n  /** Controlled total number of top-level items across every page. */\n  @Prop() totalItems: number = 0;\n  /** Available page sizes. Assign arrays through JavaScript. */\n  @Prop() pageSizeOptions: number[] = [25, 50, 100, 200];\n  /** Include the Fit to page choice. */\n  @Prop() fitToPage: boolean = false;\n  /** Keep the Fit to page choice visible but unavailable. */\n  @Prop() fitToPageInactive: boolean = false;\n  /** Effective whole-item capacity to request when Fit is selected. */\n  @Prop() fitPageSize: number | undefined;\n  /** Full choice-list label for Fit. */\n  @Prop() fitPageSizeLabel: string = 'Fit to page';\n  /** Compact closed-trigger label while Fit is selected. */\n  @Prop() fitPageSizeTriggerLabel: string = 'Fit';\n  /** Localized plural noun used by assistive range announcements. */\n  @Prop() itemLabel: string = 'items';\n  /** Visible page-size control label. */\n  @Prop() pageSizeLabel: string = 'Items';\n  /** Accessible page-size control label. Defaults to “{pageSizeLabel} per page”. */\n  @Prop() pageSizeAriaLabel: string | undefined;\n  /** Accessible name for the pagination navigation region. */\n  @Prop() label: string = 'Pagination';\n  /** Prevent interaction while the owner replaces the current data page. */\n  @Prop() loading: boolean = false;\n\n  /** Emits the complete next controlled state after a page or page-size request. */\n  @Event() dsChange!: EventEmitter<PaginationChangeDetail>;\n\n  @State() private tableCompact = false;\n\n  private readonly pageSizeControlId = `ds-pagination-${++paginationId}-page-size`;\n  private tableCompactDisconnect: (() => void) | undefined;\n  private hasLoaded = false;\n\n  componentDidLoad(): void {\n    this.hasLoaded = true;\n    this.syncTableCompactObserver();\n  }\n\n  connectedCallback(): void {\n    if (this.hasLoaded) this.syncTableCompactObserver();\n  }\n\n  disconnectedCallback(): void {\n    this.tableCompactDisconnect?.();\n    this.tableCompactDisconnect = undefined;\n  }\n\n  private syncTableCompactObserver(): void {\n    this.tableCompactDisconnect?.();\n    this.tableCompactDisconnect = observeTableCaptionCompact(this.el, compact => {\n      if (this.tableCompact !== compact) this.tableCompact = compact;\n    });\n  }\n\n  private requestPage(pageIndex: number): void {\n    const state = this.resolvedState;\n    if (this.loading || pageIndex === state.pageIndex || pageIndex < 0 || pageIndex >= state.totalPages) {\n      return;\n    }\n    this.dsChange.emit({\n      pageIndex,\n      pageSize: state.pageSize,\n      pageSizeMode: state.pageSizeMode,\n      totalItems: state.totalItems,\n      pageSizeOptions: state.pageSizeOptions,\n      fitToPage: this.fitToPage,\n      fitToPageInactive: this.fitToPageInactive,\n      fitPageSize: this.resolvedFitPageSize,\n      fitPageSizeLabel: this.fitPageSizeLabel,\n      fitPageSizeTriggerLabel: this.fitPageSizeTriggerLabel,\n      itemLabel: this.itemLabel,\n      pageSizeLabel: this.pageSizeLabel,\n      ariaLabel: this.label,\n      previousPageIndex: state.pageIndex,\n      previousPageSize: state.pageSize,\n      previousPageSizeMode: state.pageSizeMode,\n      reason: 'page',\n    });\n  }\n\n  private requestPageSize(value: string | string[]): void {\n    if (\n      this.loading ||\n      typeof value !== 'string' ||\n      (value === 'fit' && this.fitToPageInactive)\n    ) return;\n    const state = this.resolvedState;\n    const nextMode: PaginationPageSizeMode = value === 'fit' ? 'fit' : 'fixed';\n    const pageSize = nextMode === 'fit' ? this.resolvedFitPageSize : Number(value);\n    if (!pageSize || (pageSize === state.pageSize && nextMode === state.pageSizeMode)) return;\n    this.dsChange.emit({\n      pageIndex: 0,\n      pageSize: Math.trunc(pageSize),\n      pageSizeMode: nextMode,\n      totalItems: state.totalItems,\n      pageSizeOptions: state.pageSizeOptions,\n      fitToPage: this.fitToPage,\n      fitToPageInactive: this.fitToPageInactive,\n      fitPageSize: this.resolvedFitPageSize,\n      fitPageSizeLabel: this.fitPageSizeLabel,\n      fitPageSizeTriggerLabel: this.fitPageSizeTriggerLabel,\n      itemLabel: this.itemLabel,\n      pageSizeLabel: this.pageSizeLabel,\n      ariaLabel: this.label,\n      previousPageIndex: state.pageIndex,\n      previousPageSize: state.pageSize,\n      previousPageSizeMode: state.pageSizeMode,\n      reason: 'page-size',\n    });\n  }\n\n  private handleKeyDown(event: KeyboardEvent): void {\n    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {\n      return;\n    }\n    const fromChoiceControl = event.composedPath().some(node =>\n      node instanceof HTMLElement &&\n      (node.tagName === 'DS-SELECT' || ['INPUT', 'SELECT', 'TEXTAREA'].includes(node.tagName)),\n    );\n    if (fromChoiceControl || (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight')) return;\n    const state = this.resolvedState;\n    const pageIndex = event.key === 'ArrowLeft' ? state.pageIndex - 1 : state.pageIndex + 1;\n    if (this.loading || pageIndex < 0 || pageIndex >= state.totalPages) return;\n    event.preventDefault();\n    this.requestPage(pageIndex);\n  }\n\n  private get resolvedFitPageSize(): number | undefined {\n    return Number.isFinite(this.fitPageSize) && Number(this.fitPageSize) > 0\n      ? Math.trunc(Number(this.fitPageSize))\n      : undefined;\n  }\n\n  private get resolvedState() {\n    return resolvePaginationState({\n      pageIndex: this.pageIndex,\n      pageSize: this.pageSize,\n      pageSizeMode: this.pageSizeMode,\n      totalItems: this.totalItems,\n      pageSizeOptions: this.pageSizeOptions,\n    });\n  }\n\n  render() {\n    const state = this.resolvedState;\n    const atStart = state.pageIndex === 0;\n    const atEnd = state.pageIndex === state.totalPages - 1;\n    const visibleItems = state.totalItems === 0 ? 0 : state.lastItem - state.firstItem + 1;\n    const total = `${visibleItems} of ${state.totalItems}`;\n    const page = `${state.pageIndex + 1} of ${state.totalPages}`;\n    const announcedRange = `${state.firstItem}–${state.lastItem} of ${state.totalItems}`;\n    const announcedPage = `Page ${state.pageIndex + 1} of ${state.totalPages}`;\n    const pageSizeAriaLabel = this.pageSizeAriaLabel ?? `${this.pageSizeLabel} per page`;\n    const options: Array<{ label: string; value: string; isInactive?: boolean }> =\n      state.pageSizeOptions.map(value => ({ label: String(value), value: String(value) }));\n    if (this.fitToPage) {\n      options.push({\n        label: this.fitPageSizeLabel,\n        value: 'fit',\n        isInactive: this.fitToPageInactive || this.resolvedFitPageSize === undefined,\n      });\n    }\n\n    return (\n      <Host>\n        <nav\n          class={{\n            pagination: true,\n            'pagination--table-compact': this.tableCompact,\n          }}\n          aria-label={this.label}\n          aria-busy={this.loading ? 'true' : undefined}\n          onKeyDown={event => this.handleKeyDown(event)}\n        >\n          <div class=\"pagination__page-size\">\n            <ds-text\n              class=\"pagination__label\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              aria-hidden=\"true\"\n            >\n              {this.pageSizeLabel}:\n            </ds-text>\n            <span id={`${this.pageSizeControlId}-label`} class=\"ds-visually-hidden\">\n              {pageSizeAriaLabel}\n            </span>\n            <ds-select\n              class=\"pagination__page-size-select\"\n              size=\"md\"\n              inputId={this.pageSizeControlId}\n              ariaLabelledby={`${this.pageSizeControlId}-label`}\n              options={options}\n              value={state.pageSizeMode === 'fit' ? 'fit' : String(state.pageSize)}\n              triggerLabel={state.pageSizeMode === 'fit' ? this.fitPageSizeTriggerLabel : undefined}\n              indicator=\"up-down\"\n              allowClear={false}\n              activeFill={false}\n              hasBorder={false}\n              isInactive={this.loading}\n              onDsChange={event => {\n                event.stopPropagation();\n                this.requestPageSize(event.detail);\n              }}\n            />\n            <ds-text\n              class=\"pagination__total\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              fontFeature=\"tabular-nums\"\n            >\n              {total}\n            </ds-text>\n          </div>\n          <ds-divider\n            class=\"pagination__divider\"\n            orientation=\"vertical\"\n            length=\"var(--dimension-size-250)\"\n          />\n          <div class=\"pagination__navigation\">\n            <ds-button-unfilled\n              class=\"pagination__boundary\"\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronLeftDouble\"\n              ariaLabel=\"First page\"\n              hasBorder={false}\n              isInactive={this.loading || atStart}\n              onDsClick={() => this.requestPage(0)}\n            />\n            <ds-button-unfilled\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronLeft\"\n              ariaLabel=\"Previous page\"\n              hasBorder={false}\n              isInactive={this.loading || atStart}\n              onDsClick={() => this.requestPage(state.pageIndex - 1)}\n            />\n            <ds-text\n              class=\"pagination__page\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              fontFeature=\"tabular-nums\"\n            >\n              {page}\n            </ds-text>\n            <ds-button-unfilled\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronRight\"\n              ariaLabel=\"Next page\"\n              hasBorder={false}\n              isInactive={this.loading || atEnd}\n              onDsClick={() => this.requestPage(state.pageIndex + 1)}\n            />\n            <ds-button-unfilled\n              class=\"pagination__boundary\"\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronRightDouble\"\n              ariaLabel=\"Last page\"\n              hasBorder={false}\n              isInactive={this.loading || atEnd}\n              onDsClick={() => this.requestPage(state.totalPages - 1)}\n            />\n          </div>\n          <span class=\"ds-visually-hidden\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n            {announcedRange} {this.itemLabel}. {announcedPage}.\n          </span>\n        </nav>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, Event, EventEmitter, h, Host, Prop, State } from '@stencil/core';\nimport { observeTableCaptionCompact } from '../../utils/table-caption-compact';\nimport { resolvePaginationState } from './pagination-model';\nimport type {\n  PaginationChangeDetail,\n  PaginationPageSizeMode,\n} from './pagination-types';\n\nlet paginationId = 0;\n\n@Component({\n  tag: 'ds-pagination',\n  styleUrl: 'Pagination.css',\n  scoped: true,\n})\nexport class Pagination {\n  @Element() el!: HTMLElement;\n\n  /** Controlled zero-based page index. */\n  @Prop() pageIndex: number = 0;\n  /** Controlled number of top-level items on a full page. */\n  @Prop() pageSize: number = 25;\n  /** Whether pageSize is a fixed choice or a measured Fit snapshot. */\n  @Prop() pageSizeMode: PaginationPageSizeMode = 'fixed';\n  /** Controlled total number of top-level items across every page. */\n  @Prop() totalItems: number = 0;\n  /** Available page sizes. Assign arrays through JavaScript. */\n  @Prop() pageSizeOptions: number[] = [25, 50, 100, 200];\n  /** Include the Fit to page choice. */\n  @Prop() fitToPage: boolean = false;\n  /** Keep the Fit to page choice visible but unavailable. */\n  @Prop() fitToPageInactive: boolean = false;\n  /** Effective whole-item capacity to request when Fit is selected. */\n  @Prop() fitPageSize: number | undefined;\n  /** Full choice-list label for Fit. */\n  @Prop() fitPageSizeLabel: string = 'Fit to page';\n  /** Compact closed-trigger label while Fit is selected. */\n  @Prop() fitPageSizeTriggerLabel: string = 'Fit';\n  /** Localized plural noun used by assistive range announcements. */\n  @Prop() itemLabel: string = 'items';\n  /** Visible page-size control label. */\n  @Prop() pageSizeLabel: string = 'Items';\n  /** Accessible page-size control label. Defaults to “{pageSizeLabel} per page”. */\n  @Prop() pageSizeAriaLabel: string | undefined;\n  /** Accessible name for the pagination navigation region. */\n  @Prop() label: string = 'Pagination';\n  /** Include direct first-page and last-page controls. */\n  @Prop() showFirstLastButtons: boolean = false;\n  /** Prevent interaction while the owner replaces the current data page. */\n  @Prop() loading: boolean = false;\n\n  /** Emits the complete next controlled state after a page or page-size request. */\n  @Event() dsChange!: EventEmitter<PaginationChangeDetail>;\n\n  @State() private tableCompact = false;\n\n  private readonly pageSizeControlId = `ds-pagination-${++paginationId}-page-size`;\n  private tableCompactDisconnect: (() => void) | undefined;\n  private hasLoaded = false;\n\n  componentDidLoad(): void {\n    this.hasLoaded = true;\n    this.syncTableCompactObserver();\n  }\n\n  connectedCallback(): void {\n    if (this.hasLoaded) this.syncTableCompactObserver();\n  }\n\n  disconnectedCallback(): void {\n    this.tableCompactDisconnect?.();\n    this.tableCompactDisconnect = undefined;\n  }\n\n  private syncTableCompactObserver(): void {\n    this.tableCompactDisconnect?.();\n    this.tableCompactDisconnect = observeTableCaptionCompact(this.el, compact => {\n      if (this.tableCompact !== compact) this.tableCompact = compact;\n    });\n  }\n\n  private requestPage(pageIndex: number): void {\n    const state = this.resolvedState;\n    if (this.loading || pageIndex === state.pageIndex || pageIndex < 0 || pageIndex >= state.totalPages) {\n      return;\n    }\n    this.dsChange.emit({\n      pageIndex,\n      pageSize: state.pageSize,\n      pageSizeMode: state.pageSizeMode,\n      totalItems: state.totalItems,\n      pageSizeOptions: state.pageSizeOptions,\n      fitToPage: this.fitToPage,\n      fitToPageInactive: this.fitToPageInactive,\n      fitPageSize: this.resolvedFitPageSize,\n      fitPageSizeLabel: this.fitPageSizeLabel,\n      fitPageSizeTriggerLabel: this.fitPageSizeTriggerLabel,\n      itemLabel: this.itemLabel,\n      pageSizeLabel: this.pageSizeLabel,\n      ariaLabel: this.label,\n      showFirstLastButtons: this.showFirstLastButtons,\n      previousPageIndex: state.pageIndex,\n      previousPageSize: state.pageSize,\n      previousPageSizeMode: state.pageSizeMode,\n      reason: 'page',\n    });\n  }\n\n  private requestPageSize(value: string | string[]): void {\n    if (\n      this.loading ||\n      typeof value !== 'string' ||\n      (value === 'fit' && this.fitToPageInactive)\n    ) return;\n    const state = this.resolvedState;\n    const nextMode: PaginationPageSizeMode = value === 'fit' ? 'fit' : 'fixed';\n    const pageSize = nextMode === 'fit' ? this.resolvedFitPageSize : Number(value);\n    if (!pageSize || (pageSize === state.pageSize && nextMode === state.pageSizeMode)) return;\n    this.dsChange.emit({\n      pageIndex: 0,\n      pageSize: Math.trunc(pageSize),\n      pageSizeMode: nextMode,\n      totalItems: state.totalItems,\n      pageSizeOptions: state.pageSizeOptions,\n      fitToPage: this.fitToPage,\n      fitToPageInactive: this.fitToPageInactive,\n      fitPageSize: this.resolvedFitPageSize,\n      fitPageSizeLabel: this.fitPageSizeLabel,\n      fitPageSizeTriggerLabel: this.fitPageSizeTriggerLabel,\n      itemLabel: this.itemLabel,\n      pageSizeLabel: this.pageSizeLabel,\n      ariaLabel: this.label,\n      showFirstLastButtons: this.showFirstLastButtons,\n      previousPageIndex: state.pageIndex,\n      previousPageSize: state.pageSize,\n      previousPageSizeMode: state.pageSizeMode,\n      reason: 'page-size',\n    });\n  }\n\n  private handleKeyDown(event: KeyboardEvent): void {\n    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {\n      return;\n    }\n    const fromChoiceControl = event.composedPath().some(node =>\n      node instanceof HTMLElement &&\n      (node.tagName === 'DS-SELECT' || ['INPUT', 'SELECT', 'TEXTAREA'].includes(node.tagName)),\n    );\n    if (fromChoiceControl || (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight')) return;\n    const state = this.resolvedState;\n    const pageIndex = event.key === 'ArrowLeft' ? state.pageIndex - 1 : state.pageIndex + 1;\n    if (this.loading || pageIndex < 0 || pageIndex >= state.totalPages) return;\n    event.preventDefault();\n    this.requestPage(pageIndex);\n  }\n\n  private get resolvedFitPageSize(): number | undefined {\n    return Number.isFinite(this.fitPageSize) && Number(this.fitPageSize) > 0\n      ? Math.trunc(Number(this.fitPageSize))\n      : undefined;\n  }\n\n  private get resolvedState() {\n    return resolvePaginationState({\n      pageIndex: this.pageIndex,\n      pageSize: this.pageSize,\n      pageSizeMode: this.pageSizeMode,\n      totalItems: this.totalItems,\n      pageSizeOptions: this.pageSizeOptions,\n    });\n  }\n\n  render() {\n    const state = this.resolvedState;\n    const atStart = state.pageIndex === 0;\n    const atEnd = state.pageIndex === state.totalPages - 1;\n    const visibleItems = state.totalItems === 0 ? 0 : state.lastItem - state.firstItem + 1;\n    const total = `${visibleItems} of ${state.totalItems}`;\n    const page = `${state.pageIndex + 1} of ${state.totalPages}`;\n    const announcedRange = `${state.firstItem}–${state.lastItem} of ${state.totalItems}`;\n    const announcedPage = `Page ${state.pageIndex + 1} of ${state.totalPages}`;\n    const pageSizeAriaLabel = this.pageSizeAriaLabel ?? `${this.pageSizeLabel} per page`;\n    const options: Array<{ label: string; value: string; isInactive?: boolean }> =\n      state.pageSizeOptions.map(value => ({ label: String(value), value: String(value) }));\n    if (this.fitToPage) {\n      options.push({\n        label: this.fitPageSizeLabel,\n        value: 'fit',\n        isInactive: this.fitToPageInactive || this.resolvedFitPageSize === undefined,\n      });\n    }\n\n    return (\n      <Host>\n        <nav\n          class={{\n            pagination: true,\n            'pagination--table-compact': this.tableCompact,\n          }}\n          aria-label={this.label}\n          aria-busy={this.loading ? 'true' : undefined}\n          onKeyDown={event => this.handleKeyDown(event)}\n        >\n          <div class=\"pagination__page-size\">\n            <ds-text\n              class=\"pagination__label\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              aria-hidden=\"true\"\n            >\n              {this.pageSizeLabel}:\n            </ds-text>\n            <span id={`${this.pageSizeControlId}-label`} class=\"ds-visually-hidden\">\n              {pageSizeAriaLabel}\n            </span>\n            <ds-select\n              class=\"pagination__page-size-select\"\n              size=\"md\"\n              inputId={this.pageSizeControlId}\n              ariaLabelledby={`${this.pageSizeControlId}-label`}\n              options={options}\n              value={state.pageSizeMode === 'fit' ? 'fit' : String(state.pageSize)}\n              triggerLabel={state.pageSizeMode === 'fit' ? this.fitPageSizeTriggerLabel : undefined}\n              indicator=\"up-down\"\n              allowClear={false}\n              activeFill={false}\n              hasBorder={false}\n              isInactive={this.loading}\n              onDsChange={event => {\n                event.stopPropagation();\n                this.requestPageSize(event.detail);\n              }}\n            />\n            <ds-text\n              class=\"pagination__total\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              fontFeature=\"tabular-nums\"\n            >\n              {total}\n            </ds-text>\n          </div>\n          <ds-divider\n            class=\"pagination__divider\"\n            orientation=\"vertical\"\n            length=\"var(--dimension-size-250)\"\n          />\n          <div class=\"pagination__navigation\">\n            {this.showFirstLastButtons ? (\n              <ds-button-unfilled\n                class=\"pagination__boundary\"\n                variant=\"icon\"\n                size=\"md\"\n                icon=\"ChevronLeftDouble\"\n                ariaLabel=\"First page\"\n                hasBorder={false}\n                isInactive={this.loading || atStart}\n                onDsClick={() => this.requestPage(0)}\n              />\n            ) : null}\n            <ds-button-unfilled\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronLeft\"\n              ariaLabel=\"Previous page\"\n              hasBorder={false}\n              isInactive={this.loading || atStart}\n              onDsClick={() => this.requestPage(state.pageIndex - 1)}\n            />\n            <ds-text\n              class=\"pagination__page\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              fontFeature=\"tabular-nums\"\n            >\n              {page}\n            </ds-text>\n            <ds-button-unfilled\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronRight\"\n              ariaLabel=\"Next page\"\n              hasBorder={false}\n              isInactive={this.loading || atEnd}\n              onDsClick={() => this.requestPage(state.pageIndex + 1)}\n            />\n            {this.showFirstLastButtons ? (\n              <ds-button-unfilled\n                class=\"pagination__boundary\"\n                variant=\"icon\"\n                size=\"md\"\n                icon=\"ChevronRightDouble\"\n                ariaLabel=\"Last page\"\n                hasBorder={false}\n                isInactive={this.loading || atEnd}\n                onDsClick={() => this.requestPage(state.totalPages - 1)}\n              />\n            ) : null}\n          </div>\n          <span class=\"ds-visually-hidden\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n            {announcedRange} {this.itemLabel}. {announcedPage}.\n          </span>\n        </nav>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {
@@ -419,7 +440,7 @@
     },
     {
       "path": "src/wc/components/Pagination/pagination-types.ts",
-      "content": "export type PaginationChangeReason = 'page' | 'page-size' | 'fit';\nexport type PaginationPageSizeMode = 'fixed' | 'fit';\n\n/** Controlled pagination state shared by Pagination and pagination-aware consumers. */\nexport interface PaginationState {\n  /** Zero-based page index. */\n  pageIndex: number;\n  /** Number of top-level items on a full page. */\n  pageSize: number;\n  /** Whether pageSize is a chosen fixed value or a measured Fit snapshot. */\n  pageSizeMode?: PaginationPageSizeMode;\n  /** Total number of top-level items across every page. */\n  totalItems: number;\n  /** Available page sizes. Defaults to 25, 50, 100, and 200. */\n  pageSizeOptions?: number[];\n  /** Include a Fit to page option. The owner supplies the effective fitted size. */\n  fitToPage?: boolean;\n  /** Keep the Fit to page option visible but unavailable for the current data shape. */\n  fitToPageInactive?: boolean;\n  /** Effective page size proposed when Fit to page is selected. */\n  fitPageSize?: number;\n  /** Full option label for Fit in the open choice list. */\n  fitPageSizeLabel?: string;\n  /** Compact trigger label while Fit is selected. */\n  fitPageSizeTriggerLabel?: string;\n  /** Localized plural noun used by assistive range announcements. */\n  itemLabel?: string;\n  /** Visible label for the page-size selector. */\n  pageSizeLabel?: string;\n  /** Accessible name for the pagination navigation region. */\n  ariaLabel?: string;\n}\n\n/** Complete next controlled state emitted for a page or page-size request. */\nexport interface PaginationChangeDetail extends PaginationState {\n  previousPageIndex: number;\n  previousPageSize: number;\n  previousPageSizeMode: PaginationPageSizeMode;\n  reason: PaginationChangeReason;\n}\n",
+      "content": "export type PaginationChangeReason = 'page' | 'page-size' | 'fit';\nexport type PaginationPageSizeMode = 'fixed' | 'fit';\n\n/** Controlled pagination state shared by Pagination and pagination-aware consumers. */\nexport interface PaginationState {\n  /** Zero-based page index. */\n  pageIndex: number;\n  /** Number of top-level items on a full page. */\n  pageSize: number;\n  /** Whether pageSize is a chosen fixed value or a measured Fit snapshot. */\n  pageSizeMode?: PaginationPageSizeMode;\n  /** Total number of top-level items across every page. */\n  totalItems: number;\n  /** Available page sizes. Defaults to 25, 50, 100, and 200. */\n  pageSizeOptions?: number[];\n  /** Include a Fit to page option. The owner supplies the effective fitted size. */\n  fitToPage?: boolean;\n  /** Keep the Fit to page option visible but unavailable for the current data shape. */\n  fitToPageInactive?: boolean;\n  /** Effective page size proposed when Fit to page is selected. */\n  fitPageSize?: number;\n  /** Full option label for Fit in the open choice list. */\n  fitPageSizeLabel?: string;\n  /** Compact trigger label while Fit is selected. */\n  fitPageSizeTriggerLabel?: string;\n  /** Localized plural noun used by assistive range announcements. */\n  itemLabel?: string;\n  /** Visible label for the page-size selector. */\n  pageSizeLabel?: string;\n  /** Accessible name for the pagination navigation region. */\n  ariaLabel?: string;\n  /** Include direct first-page and last-page controls around Previous and Next. */\n  showFirstLastButtons?: boolean;\n}\n\n/** Complete next controlled state emitted for a page or page-size request. */\nexport interface PaginationChangeDetail extends PaginationState {\n  previousPageIndex: number;\n  previousPageSize: number;\n  previousPageSizeMode: PaginationPageSizeMode;\n  reason: PaginationChangeReason;\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/panel-nav.json

@@ -625,7 +625,7 @@
   "files": [
     {
       "path": "src/wc/components/PanelNav/PanelNav.css",
-      "content": "@import '../../utils/control-density.css';\n@import '../../utils/chrome-layout.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/interaction-fill.css';\n@import '../../utils/scrollbar-hidden.css';\n\n/* ── Theme variables ──────────────────────────────────────────────────────── */\n\n.panel-nav {\n  /* ─ Sizes ─ */\n  --_nav-width:              var(--dimension-panel-width-2xs);\n  --_nav-width-collapsed:    var(--dimension-size-600);\n  --_nav-item-height:        var(--dimension-size-400, 32px);\n  --_nav-padding-x:          var(--dimension-space-100, 8px);\n  --_nav-padding-y:          var(--dimension-space-100, 8px);\n  /* gear button outer width = padding*2 + icon */\n  --_nav-footer-btn-w:       calc(var(--dimension-space-075, 6px) * 2 + var(--dimension-iconography-md, 20px));\n\n  /* ─ Motion ─ */\n  /* --ds-panel-nav-speed: unitless multiplier; override in Storybook to slow-mo (e.g. 10 = 10×).\n     *-dur vars are duration-only (needed for calc); *-motion vars add easing for use in transitions. */\n  --_nav-speed:               var(--ds-panel-nav-speed, 1);\n  --_nav-expand-dur:          calc(var(--_nav-speed) * var(--effect-animation-duration-medium-1, 300ms));\n  --_nav-expand-motion:       var(--_nav-expand-dur) var(--effect-animation-easing-ease-in-out, ease);\n  --_nav-label-fade-dur:      calc(var(--_nav-speed) * var(--effect-animation-duration-medium-1, 300ms));\n  --_nav-label-fade-motion:   var(--_nav-label-fade-dur) var(--effect-animation-easing-ease-in-out, ease);\n  --_nav-label-fade-out-dur:  calc(var(--_nav-speed) * var(--effect-animation-duration-medium-1, 300ms));\n  --_nav-label-fade-out-motion: var(--_nav-label-fade-out-dur) var(--effect-animation-easing-ease-in-out, ease);\n\n  /* ─ Colours – default chrome (app surfaces) ─ */\n  --_nav-bg:           var(--color-background-secondary);\n  --_nav-border:       var(--color-border-tertiary);\n  --_nav-divider:      var(--color-border-tertiary);\n  --_nav-fg-primary:   var(--color-foreground-primary);\n  --_nav-fg-secondary: var(--color-foreground-secondary);\n  --_nav-fg-tertiary:  var(--color-foreground-tertiary);\n  --_nav-hover:        var(--color-interaction-hover);\n  --_nav-pressed:      var(--color-interaction-pressed);\n  --_nav-focus:        var(--color-interaction-focus);\n  --_nav-dot:          var(--color-foreground-bold-brand);\n  --ds-interaction-hover: var(--_nav-hover);\n  --ds-interaction-pressed: var(--_nav-pressed);\n  --ds-focus-ring-color: var(--_nav-focus);\n}\n\n/* ── Default chrome overrides ────────────────────────────────────────────── */\n\n/* Shell-owned chrome (bg + wash) — panel is a transparent frame. */\n:host-context(ds-shell-app:not([gradient-preset='none'])) .panel-nav,\n:host-context(ds-shell-app.shell-app--paper-texture) .panel-nav {\n  background-color: transparent;\n}\n\n/* Style slots — same app tokens for now; hook texture/glyph layers on these classes later. */\n.panel-nav--dashboard,\n.panel-nav--settings {\n  --_nav-bg:           var(--color-background-secondary);\n  --_nav-border:       var(--color-border-tertiary);\n  --_nav-divider:      var(--color-border-tertiary);\n  --_nav-fg-primary:   var(--color-foreground-primary);\n  --_nav-fg-secondary: var(--color-foreground-secondary);\n  --_nav-fg-tertiary:  var(--color-foreground-tertiary);\n  --_nav-hover:        var(--color-interaction-hover);\n  --_nav-pressed:      var(--color-interaction-pressed);\n  --_nav-focus:        var(--color-interaction-focus);\n  --_nav-dot:          var(--color-foreground-bold-brand);\n  --ds-interaction-hover: var(--_nav-hover);\n  --ds-interaction-pressed: var(--_nav-pressed);\n  --ds-focus-ring-color: var(--_nav-focus);\n}\n\n/* ── Shell ───────────────────────────────────────────────────────────────── */\n\n.panel-nav {\n  display: flex;\n  flex-direction: column;\n  position: relative;\n  width: var(--_nav-width);\n  min-width: var(--_nav-width);\n  height: 100%;\n  background-color: var(--_nav-bg);\n  border-right: var(--dimension-stroke-width-012, 1px) solid var(--_nav-border);\n  box-sizing: border-box;\n  overflow: visible;\n  transition:\n    width var(--_nav-expand-motion),\n    min-width var(--_nav-expand-motion),\n    background-color var(--effect-motion-short-3, 200ms ease),\n    border-color var(--effect-motion-short-3, 200ms ease);\n  font-family: var(--typography-font-family-ui, system-ui);\n  isolation: isolate;\n}\n\n.panel-nav__header,\n.panel-nav__body,\n.panel-nav__footer {\n  position: relative;\n  z-index: 3;\n}\n\n.panel-nav--collapsed {\n  width: var(--_nav-width-collapsed);\n  min-width: var(--_nav-width-collapsed);\n}\n\n/* ── Header ──────────────────────────────────────────────────────────────── */\n\n.panel-nav__header {\n  height: var(--dimension-size-600, 48px);\n  flex-shrink: 0;\n  border-bottom: var(--dimension-stroke-width-012, 1px) solid var(--_nav-divider);\n  transition: border-color var(--effect-motion-short-3, 200ms ease);\n}\n\n.panel-nav__header-btn {\n  all: unset;\n  /* Re-assert after unset — required for `.ds-interaction-fill` stacking. */\n  position: relative;\n  z-index: 0;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  padding: var(--dimension-space-075, 6px);\n  border-radius: var(--ds-control-radius, var(--dimension-radius-025, 2px));\n  cursor: default;\n  color: var(--_nav-fg-primary);\n  flex-shrink: 0;\n  box-sizing: border-box;\n  transition: color var(--effect-motion-short-3, 200ms ease);\n  /* Hover/press: `.ds-interaction-fill` (tokens from --_nav-* via --ds-interaction-*). */\n}\n\n.panel-nav--breakpoint-locked .panel-nav__header-btn {\n  cursor: default;\n}\n\n/* Logo — visible by default; instant swap to toggle on hover (no crossfade overlap) */\n.panel-nav__header-logo {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  position: relative;\n  z-index: 2;\n  opacity: 1;\n}\n\n.panel-nav__m-mark {\n  width: var(--dimension-iconography-md, 20px);\n  height: var(--dimension-iconography-md, 20px);\n  display: block;\n}\n\n/* Toggle icon — stacked on logo; under hover wash (::after z-index 3) */\n.panel-nav__header-toggle {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  position: absolute;\n  inset: 0;\n  z-index: 2;\n  opacity: 0;\n  pointer-events: none;\n}\n\n@media (hover: hover) and (pointer: fine) {\n  .panel-nav:not(.panel-nav--breakpoint-locked)\n    .panel-nav__header-btn:hover\n    .panel-nav__header-logo {\n    opacity: 0;\n  }\n\n  .panel-nav:not(.panel-nav--breakpoint-locked)\n    .panel-nav__header-btn:hover\n    .panel-nav__header-toggle {\n    opacity: 1;\n  }\n}\n\n/* ── Scrollable body ─────────────────────────────────────────────────────── */\n\n.panel-nav__body {\n  flex: 1;\n  overflow-y: auto;\n  overflow-x: hidden;\n}\n\n.panel-nav__sections {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-200, 16px);\n  width: 100%;\n}\n\n/* ── Group ───────────────────────────────────────────────────────────────── */\n\n.panel-nav__group {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050, 4px);\n}\n\n/*\n * Section headers — typography via ds-text (text-caption + emphasis).\n * Element selector so display:flex beats Text's inline-block, and padding\n * isn't clobbered by sharing `.panel-nav__item-label-text` on the same host.\n */\nds-text.panel-nav__group-label {\n  display: flex;\n  align-items: center;\n  box-sizing: border-box;\n  text-transform: uppercase;\n  color: var(--_nav-fg-secondary);\n  user-select: none;\n  height: var(--dimension-size-300, 24px);\n  /* Former nested pad: group-label (075) + item-label-text (025). */\n  padding: 0 calc(var(--dimension-space-075, 6px) + var(--ds-control-label-inset));\n  white-space: nowrap;\n  overflow: hidden;\n  max-height: var(--dimension-size-300, 24px);\n  opacity: 1;\n  transition:\n    opacity var(--_nav-label-fade-motion) 0ms,\n    max-height var(--_nav-label-fade-motion) 0ms,\n    padding var(--_nav-label-fade-motion) 0ms,\n    color var(--effect-motion-short-3, 200ms ease);\n}\n\n/* ── Item ────────────────────────────────────────────────────────────────── */\n\n.panel-nav__item {\n  all: unset;\n  /* Re-assert after unset — required for `.ds-interaction-fill` stacking. */\n  position: relative;\n  z-index: 0;\n  display: flex;\n  align-items: center;\n  gap: var(--dimension-space-050, 4px);\n  padding: 0 var(--dimension-space-075, 6px);\n  height: var(--dimension-size-400, 32px);\n  border-radius: var(--ds-control-radius, var(--dimension-radius-025, 2px));\n  cursor: default;\n  color: var(--_nav-fg-secondary);\n  box-sizing: border-box;\n  width: 100%;\n  user-select: none;\n  transition: color var(--effect-motion-short-1, 50ms ease-in-out);\n  /* Hover/press: `.ds-interaction-fill` — no --selected (icon/type weight only). */\n}\n\n/* ── Active item ─────────────────────────────────────────────────────────── */\n\n.panel-nav__item--active {\n  color: var(--_nav-fg-primary);\n  /* Bold typography via ds-text (text-body-medium + emphasis) on the label */\n}\n\n/* ── Item icon ───────────────────────────────────────────────────────────── */\n\n.panel-nav__item-icon {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  width: var(--dimension-iconography-md, 20px);\n  height: var(--dimension-iconography-md, 20px);\n  position: relative;\n  z-index: 2;\n}\n\n/* ── Item label ──────────────────────────────────────────────────────────── */\n\n.panel-nav__item-label {\n  position: relative;\n  z-index: 2;\n  flex: 1;\n  min-width: 0;\n  height: var(--typography-lineheight-md, 20px);\n  opacity: 1;\n  /* Gradient wipe: mask sweeps left-to-right on expand, right-to-left on collapse */\n  /* stylelint-disable-next-line color-named -- mask luminance stops, not theme colors */\n  mask-image: linear-gradient(to right, black 50%, transparent 100%);\n  /* stylelint-disable-next-line color-named -- mask luminance stops, not theme colors */\n  -webkit-mask-image: linear-gradient(to right, black 50%, transparent 100%);\n  mask-size: 200% 100%;\n  -webkit-mask-size: 200% 100%;\n  mask-position: 0% 0;\n  -webkit-mask-position: 0% 0;\n  transition:\n    opacity var(--_nav-label-fade-motion) 0ms,\n    mask-position var(--_nav-label-fade-motion) 0ms,\n    -webkit-mask-position var(--_nav-label-fade-motion) 0ms;\n}\n\n.panel-nav__item-label-text {\n  padding: 0 var(--ds-control-label-inset);\n}\n\n/* ── Item notification dot — 20px suffix zone matches the icon geometry ──── */\n\n.panel-nav__item-dot-box {\n  position: absolute;\n  z-index: 2;\n  right: var(--dimension-space-075, 6px);\n  top: var(--dimension-space-075, 6px);\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: var(--dimension-iconography-md, 20px);\n  height: var(--dimension-iconography-md, 20px);\n  pointer-events: none;\n}\n\n.panel-nav__item-dot {\n  transition:\n    transform var(--_nav-expand-motion);\n}\n\n.panel-nav--collapsed .panel-nav__item-dot {\n  transform: translate(\n    calc(var(--dimension-space-075, 6px) + var(--dimension-stroke-width-012, 1px)),\n    calc(0px - var(--dimension-space-075, 6px) - var(--dimension-stroke-width-012, 1px))\n  );\n}\n\n.panel-nav--animating .panel-nav__item-label {\n  text-overflow: clip;\n}\n\n.panel-nav--collapsed .panel-nav__item-label {\n  opacity: 0;\n  pointer-events: none;\n  text-overflow: clip;\n  mask-position: 100% 0;\n  -webkit-mask-position: 100% 0;\n  transition:\n    opacity var(--_nav-label-fade-out-motion) 0ms,\n    mask-position var(--_nav-label-fade-out-motion) 0ms,\n    -webkit-mask-position var(--_nav-label-fade-out-motion) 0ms;\n}\n\n.panel-nav--collapsed ds-text.panel-nav__group-label {\n  opacity: 0;\n  max-height: 0;\n  padding: 0 calc(var(--dimension-space-075, 6px) + var(--ds-control-label-inset));\n  pointer-events: none;\n  transition:\n    opacity var(--_nav-label-fade-out-motion) 0ms,\n    max-height var(--_nav-label-fade-out-motion) 0ms,\n    padding var(--_nav-label-fade-out-motion) 0ms,\n    color var(--effect-motion-short-3, 200ms ease);\n}\n\n/* ── Footer ──────────────────────────────────────────────────────────────── */\n\n.panel-nav__footer {\n  position: relative;\n  flex-shrink: 0;\n  /* single row: padding*2 + item */\n  height: calc(var(--_nav-padding-y) * 2 + var(--_nav-item-height));\n  transition: height var(--_nav-expand-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer {\n  /* two rows: padding*2 + item*2 + gap */\n  height: calc(var(--_nav-padding-y) * 2 + var(--_nav-item-height) * 2 + var(--dimension-space-050, 4px));\n}\n\n/* ── Footer icon button (gear / dashboard) ───────────────────────────────── */\n\n.panel-nav__footer-btn {\n  position: absolute;\n  left: var(--_nav-padding-x);\n  top: var(--_nav-padding-y);\n  --ds-button-unfilled-fg: var(--_nav-fg-secondary);\n  --ds-button-unfilled-fg-active: var(--_nav-fg-primary);\n  --ds-interaction-hover: var(--_nav-hover);\n  --ds-interaction-pressed: var(--_nav-pressed);\n  --ds-focus-ring-color: var(--_nav-focus);\n}\n\n/* ── Footer user — absolutely positioned, slides from row to below gear ───── */\n\n.panel-nav__footer-user {\n  position: absolute;\n  /* Expanded row: balanced shell inset with an 8px gear-to-user gap. */\n  left: calc(var(--_nav-padding-x) + var(--_nav-footer-btn-w) + var(--dimension-space-100, 8px));\n  right: var(--_nav-padding-x);\n  top: var(--_nav-padding-y);\n  width: auto;\n  min-width: 0;\n  transition:\n    left var(--_nav-expand-motion),\n    right var(--_nav-expand-motion),\n    top var(--_nav-expand-motion);\n}\n\n/* Popup-open state keeps the native footer trigger visibly pressed. */\n.panel-nav__footer-user--menu-expanded::after {\n  background: var(--_nav-pressed);\n}\n\n.panel-nav__footer-user--menu-expanded {\n  --ds-interaction-hover: var(--_nav-pressed);\n}\n\n.panel-nav--collapsed .panel-nav__footer-user {\n  /* Compact column keeps the intentionally tighter 4px vertical gap. */\n  left: var(--_nav-padding-x);\n  top: calc(var(--_nav-padding-y) + var(--_nav-item-height) + var(--dimension-space-050, 4px));\n}\n\n/* Label: absolute so it stays in place and only fades — no mask slide */\n.panel-nav__footer-user-label {\n  text-align: right;\n  position: absolute;\n  left: var(--dimension-space-075, 6px);\n  right: calc(var(--dimension-space-075, 6px) + var(--dimension-iconography-md, 20px) + var(--dimension-space-050, 4px));\n  top: 50%;\n  transform: translateY(-50%);\n  flex: none;\n  height: var(--typography-lineheight-md, 20px);\n  mask-image: none;\n  -webkit-mask-image: none;\n  transition: opacity var(--_nav-label-fade-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer-user-label {\n  opacity: 0;\n  pointer-events: none;\n  mask-position: 0% 0;\n  -webkit-mask-position: 0% 0;\n}\n\n/* ── Footer user icon — cross-fades chevron ↔ circle+initial ────────────── */\n\n/* Absolute — right-anchored in expanded, left-anchored in collapsed to match regular item icon position */\n.panel-nav__footer-user-icon {\n  position: absolute;\n  left: calc(100% - var(--dimension-iconography-md, 20px) - var(--dimension-space-075, 6px));\n  top: 0;\n  bottom: 0;\n  height: auto;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  transition: left var(--_nav-expand-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer-user-icon {\n  left: var(--dimension-space-075, 6px);\n}\n\n.panel-nav__footer-icon-expanded,\n.panel-nav__footer-icon-collapsed {\n  position: absolute;\n  inset: 0;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n}\n\n.panel-nav__footer-icon-expanded {\n  opacity: 1;\n  transition: opacity var(--_nav-label-fade-motion);\n}\n\n.panel-nav__footer-icon-collapsed {\n  opacity: 0;\n  transition: opacity var(--_nav-label-fade-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer-icon-expanded {\n  opacity: 0;\n  transition: opacity var(--_nav-label-fade-out-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer-icon-collapsed {\n  opacity: 1;\n  transition: opacity var(--_nav-label-fade-out-motion);\n}\n\n/* ── User initial — overlaid on the circle icon ─────────────────────────── */\n\n/*\n * Center the caption glyph on the Circle icon. Don't use inset:0 + flex — the\n * inner `.ds-text__element { width: 100% }` stretches and left-aligns the letter.\n * Translate-centering keeps the complete caption metric box on the icon center;\n * the caption variant remains the sole owner of its line-height.\n * (Do not set `inset: auto` after top/left — it resets them.)\n */\nds-text.panel-nav__user-initial,\nds-text.panel-nav__user-initial.ds-text--caption {\n  position: absolute;\n  top: 50%;\n  left: 50%;\n  right: auto;\n  bottom: auto;\n  transform: translate(-50%, -50%);\n  display: block;\n  width: max-content;\n  max-width: none;\n  min-width: 0;\n  text-align: center;\n  color: inherit;\n  pointer-events: none;\n}\n\n/* ── Drag-to-resize handle ───────────────────────────────────────────────── */\n\n/* The resize overlay line — extends past the right edge; keep above workspace content */\n.panel-nav__resize-handle {\n  position: absolute;\n  top: 0;\n  /* Centered on the right edge: --dimension-space-050 outside + inside = --dimension-space-100 hit zone */\n  right: var(--dimension-space-n050, -4px);\n  bottom: 0;\n  width: var(--dimension-space-100, 8px);\n  z-index: 20;\n  cursor: ew-resize;\n  touch-action: none;\n  /* Needs a real background for Safari hit-testing */\n  background: transparent;\n}\n\n/* Safari requires non-transparent fill for hit testing */\n.panel-nav__resize-handle::before {\n  content: '';\n  position: absolute;\n  inset: 0;\n  /* stylelint-disable-next-line color-named -- near-invisible hit-test fill; not a theme color */\n  background: rgba(0, 0, 0, 0.001);\n}\n\n/* Resize overlay line */\n.panel-nav__resize-handle::after {\n  content: '';\n  position: absolute;\n  top: 0;\n  bottom: 0;\n  left: 50%;\n  transform: translateX(-50%);\n  width: var(--dimension-stroke-width-025, 2px);\n  background: var(--color-foreground-primary);\n  opacity: 0;\n  pointer-events: none;\n  transition: opacity var(--effect-motion-short-2, 100ms ease-in-out);\n}\n\n.panel-nav__resize-handle--overlay::after {\n  opacity: 1;\n}\n\n/* ── Reduced motion ──────────────────────────────────────────────────────── */\n\n@media (prefers-reduced-motion: reduce) {\n  .panel-nav,\n  .panel-nav *,\n  .panel-nav *::before,\n  .panel-nav *::after,\n  .panel-nav__resize-handle,\n  .panel-nav__resize-handle::before,\n  .panel-nav__resize-handle::after {\n    /* Near-instant — browsers treat 0 as \"no transition\" and can skip the end state. */\n    transition-duration: var(--effect-animation-duration-instant) !important;\n    animation-duration: var(--effect-animation-duration-instant) !important;\n    transition-delay: var(--effect-animation-duration-instant) !important;\n  }\n}\n",
+      "content": "@import '../../utils/control-density.css';\n@import '../../utils/chrome-layout.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/interaction-fill.css';\n@import '../../utils/scrollbar-hidden.css';\n\n/* ── Theme variables ──────────────────────────────────────────────────────── */\n\n.panel-nav {\n  /* ─ Sizes ─ */\n  --_nav-width:              var(--dimension-panel-width-2xs);\n  --_nav-width-collapsed:    var(--dimension-size-600);\n  --_nav-item-height:        var(--dimension-size-400, 32px);\n  --_nav-padding-x:          var(--dimension-space-100, 8px);\n  --_nav-padding-y:          var(--dimension-space-100, 8px);\n  /* gear button outer width = padding*2 + icon */\n  --_nav-footer-btn-w:       calc(var(--dimension-space-075, 6px) * 2 + var(--dimension-iconography-md, 20px));\n\n  /* ─ Motion ─ */\n  /* --ds-panel-nav-speed: unitless multiplier; override in Storybook to slow-mo (e.g. 10 = 10×).\n     *-dur vars are duration-only (needed for calc); *-motion vars add easing for use in transitions. */\n  --_nav-speed:               var(--ds-panel-nav-speed, 1);\n  --_nav-expand-dur:          calc(var(--_nav-speed) * var(--effect-animation-duration-medium-1, 300ms));\n  --_nav-expand-motion:       var(--_nav-expand-dur) var(--effect-animation-easing-ease-in-out, ease);\n  --_nav-label-fade-dur:      calc(var(--_nav-speed) * var(--effect-animation-duration-medium-1, 300ms));\n  --_nav-label-fade-motion:   var(--_nav-label-fade-dur) var(--effect-animation-easing-ease-in-out, ease);\n  --_nav-label-fade-out-dur:  calc(var(--_nav-speed) * var(--effect-animation-duration-medium-1, 300ms));\n  --_nav-label-fade-out-motion: var(--_nav-label-fade-out-dur) var(--effect-animation-easing-ease-in-out, ease);\n\n  /* ─ Colours – default chrome (app surfaces) ─ */\n  --_nav-bg:           var(--color-background-secondary);\n  --_nav-border:       var(--color-border-tertiary);\n  --_nav-divider:      var(--color-border-tertiary);\n  --_nav-fg-primary:   var(--color-foreground-primary);\n  --_nav-fg-secondary: var(--color-foreground-secondary);\n  --_nav-fg-tertiary:  var(--color-foreground-tertiary);\n  --_nav-hover:        var(--color-interaction-hover);\n  --_nav-pressed:      var(--color-interaction-pressed);\n  --_nav-focus:        var(--color-interaction-focus);\n  --_nav-dot:          var(--color-foreground-bold-brand);\n  --ds-interaction-hover: var(--_nav-hover);\n  --ds-interaction-pressed: var(--_nav-pressed);\n  --ds-focus-ring-color: var(--_nav-focus);\n}\n\n/* ── Default chrome overrides ────────────────────────────────────────────── */\n\n/* Shell-owned chrome (bg + wash) — panel is a transparent frame. */\n:host-context(ds-shell-app:not([gradient-preset='none'])) .panel-nav,\n:host-context(ds-shell-app.shell-app--paper-texture) .panel-nav {\n  background-color: transparent;\n}\n\n/* Style slots — same app tokens for now; hook texture/glyph layers on these classes later. */\n.panel-nav--dashboard,\n.panel-nav--settings {\n  --_nav-bg:           var(--color-background-secondary);\n  --_nav-border:       var(--color-border-tertiary);\n  --_nav-divider:      var(--color-border-tertiary);\n  --_nav-fg-primary:   var(--color-foreground-primary);\n  --_nav-fg-secondary: var(--color-foreground-secondary);\n  --_nav-fg-tertiary:  var(--color-foreground-tertiary);\n  --_nav-hover:        var(--color-interaction-hover);\n  --_nav-pressed:      var(--color-interaction-pressed);\n  --_nav-focus:        var(--color-interaction-focus);\n  --_nav-dot:          var(--color-foreground-bold-brand);\n  --ds-interaction-hover: var(--_nav-hover);\n  --ds-interaction-pressed: var(--_nav-pressed);\n  --ds-focus-ring-color: var(--_nav-focus);\n}\n\n/* ── Shell ───────────────────────────────────────────────────────────────── */\n\n.panel-nav {\n  display: flex;\n  flex-direction: column;\n  position: relative;\n  width: var(--_nav-width);\n  min-width: var(--_nav-width);\n  height: 100%;\n  background-color: var(--_nav-bg);\n  border-right: var(--dimension-stroke-width-012, 1px) solid var(--_nav-border);\n  box-sizing: border-box;\n  overflow: visible;\n  transition:\n    width var(--_nav-expand-motion),\n    min-width var(--_nav-expand-motion),\n    background-color var(--effect-motion-short-3, 200ms ease),\n    border-color var(--effect-motion-short-3, 200ms ease);\n  font-family: var(--typography-font-family-ui, system-ui);\n  isolation: isolate;\n}\n\n.panel-nav__header,\n.panel-nav__body,\n.panel-nav__footer {\n  position: relative;\n  z-index: 3;\n}\n\n.panel-nav--collapsed {\n  width: var(--_nav-width-collapsed);\n  min-width: var(--_nav-width-collapsed);\n}\n\n/* ── Header ──────────────────────────────────────────────────────────────── */\n\n.panel-nav__header {\n  height: var(--dimension-size-600, 48px);\n  flex-shrink: 0;\n  border-bottom: var(--dimension-stroke-width-012, 1px) solid var(--_nav-divider);\n  transition: border-color var(--effect-motion-short-3, 200ms ease);\n}\n\n.panel-nav__header-btn {\n  all: unset;\n  /* Re-assert after unset — required for `.ds-interaction-fill` stacking. */\n  position: relative;\n  z-index: 0;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  padding: var(--dimension-space-075, 6px);\n  border-radius: var(--ds-control-radius, var(--dimension-radius-025, 2px));\n  cursor: default;\n  color: var(--_nav-fg-primary);\n  flex-shrink: 0;\n  box-sizing: border-box;\n  transition: color var(--effect-motion-short-3, 200ms ease);\n  /* Hover/press: `.ds-interaction-fill` (tokens from --_nav-* via --ds-interaction-*). */\n}\n\n.panel-nav--breakpoint-locked .panel-nav__header-btn {\n  cursor: default;\n}\n\n/* Logo — visible by default; instant swap to toggle on hover (no crossfade overlap) */\n.panel-nav__header-logo {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  position: relative;\n  z-index: 2;\n  opacity: 1;\n}\n\n.panel-nav__m-mark {\n  width: var(--dimension-iconography-md, 20px);\n  height: var(--dimension-iconography-md, 20px);\n  display: block;\n}\n\n/* Toggle icon — stacked on logo; under hover wash (::after z-index 3) */\n.panel-nav__header-toggle {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  position: absolute;\n  inset: 0;\n  z-index: 2;\n  opacity: 0;\n  pointer-events: none;\n}\n\n@media (hover: hover) and (pointer: fine) {\n  .panel-nav:not(.panel-nav--breakpoint-locked)\n    .panel-nav__header-btn:hover\n    .panel-nav__header-logo {\n    opacity: 0;\n  }\n\n  .panel-nav:not(.panel-nav--breakpoint-locked)\n    .panel-nav__header-btn:hover\n    .panel-nav__header-toggle {\n    opacity: 1;\n  }\n}\n\n/* ── Scrollable body ─────────────────────────────────────────────────────── */\n\n.panel-nav__body {\n  flex: 1;\n  overflow-y: auto;\n  overflow-x: hidden;\n}\n\n.panel-nav__sections {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-200, 16px);\n  width: 100%;\n}\n\n/* ── Group ───────────────────────────────────────────────────────────────── */\n\n.panel-nav__group {\n  display: flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050, 4px);\n}\n\n/*\n * Section headers — typography via ds-text (text-caption + emphasis).\n * Element selector so display:flex beats Text's inline-block, and padding\n * isn't clobbered by sharing `.panel-nav__item-label-text` on the same host.\n */\nds-text.panel-nav__group-label {\n  display: flex;\n  align-items: center;\n  box-sizing: border-box;\n  text-transform: uppercase;\n  color: var(--_nav-fg-secondary);\n  user-select: none;\n  height: var(--dimension-size-300, 24px);\n  /* Former nested pad: group-label (075) + item-label-text (025). */\n  padding: 0 calc(var(--dimension-space-075, 6px) + var(--ds-control-label-inset));\n  white-space: nowrap;\n  overflow: hidden;\n  max-height: var(--dimension-size-300, 24px);\n  opacity: 1;\n  transition:\n    opacity var(--_nav-label-fade-motion) 0ms,\n    max-height var(--_nav-label-fade-motion) 0ms,\n    padding var(--_nav-label-fade-motion) 0ms,\n    color var(--effect-motion-short-3, 200ms ease);\n}\n\n/* ── Item ────────────────────────────────────────────────────────────────── */\n\n.panel-nav__item {\n  all: unset;\n  /* Re-assert after unset — required for `.ds-interaction-fill` stacking. */\n  position: relative;\n  z-index: 0;\n  display: flex;\n  align-items: center;\n  gap: var(--dimension-space-050, 4px);\n  padding: 0 var(--dimension-space-075, 6px);\n  height: var(--dimension-size-400, 32px);\n  border-radius: var(--ds-control-radius, var(--dimension-radius-025, 2px));\n  cursor: default;\n  color: var(--_nav-fg-secondary);\n  box-sizing: border-box;\n  width: 100%;\n  user-select: none;\n  transition: color var(--effect-motion-short-1, 50ms ease-in-out);\n  /* Hover/press: `.ds-interaction-fill` — no --selected (icon/type weight only). */\n}\n\n/* ── Active item ─────────────────────────────────────────────────────────── */\n\n.panel-nav__item--active {\n  color: var(--_nav-fg-primary);\n  /* Bold typography via ds-text (text-body-medium + emphasis) on the label */\n}\n\n/* ── Item icon ───────────────────────────────────────────────────────────── */\n\n.panel-nav__item-icon {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  width: var(--dimension-iconography-md, 20px);\n  height: var(--dimension-iconography-md, 20px);\n  position: relative;\n  z-index: 2;\n}\n\n/* ── Item label ──────────────────────────────────────────────────────────── */\n\n.panel-nav__item-label {\n  position: relative;\n  z-index: 2;\n  flex: 1;\n  min-width: 0;\n  height: var(--typography-lineheight-md, 20px);\n  opacity: 1;\n  /* Gradient wipe: mask sweeps left-to-right on expand, right-to-left on collapse */\n  /* stylelint-disable-next-line color-named -- mask luminance stops, not theme colors */\n  mask-image: linear-gradient(to right, black 50%, transparent 100%);\n  /* stylelint-disable-next-line color-named -- mask luminance stops, not theme colors */\n  -webkit-mask-image: linear-gradient(to right, black 50%, transparent 100%);\n  mask-size: 200% 100%;\n  -webkit-mask-size: 200% 100%;\n  mask-position: 0% 0;\n  -webkit-mask-position: 0% 0;\n  transition:\n    opacity var(--_nav-label-fade-motion) 0ms,\n    mask-position var(--_nav-label-fade-motion) 0ms,\n    -webkit-mask-position var(--_nav-label-fade-motion) 0ms;\n}\n\n.panel-nav__item-label-text {\n  padding: 0 var(--ds-control-label-inset);\n}\n\n/* ── Item notification dot — 20px suffix zone matches the icon geometry ──── */\n\n.panel-nav__item-dot-box {\n  position: absolute;\n  z-index: 2;\n  right: var(--dimension-space-075, 6px);\n  top: var(--dimension-space-075, 6px);\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: var(--dimension-iconography-md, 20px);\n  height: var(--dimension-iconography-md, 20px);\n  pointer-events: none;\n}\n\n.panel-nav__item-dot {\n  transition:\n    transform var(--_nav-expand-motion);\n}\n\n.panel-nav--collapsed .panel-nav__item-dot {\n  transform: translate(\n    calc(var(--dimension-space-075, 6px) + var(--dimension-stroke-width-012, 1px)),\n    calc(0px - var(--dimension-space-075, 6px) - var(--dimension-stroke-width-012, 1px))\n  );\n}\n\n.panel-nav--animating .panel-nav__item-label {\n  text-overflow: clip;\n}\n\n.panel-nav--collapsed .panel-nav__item-label {\n  opacity: 0;\n  pointer-events: none;\n  text-overflow: clip;\n  mask-position: 100% 0;\n  -webkit-mask-position: 100% 0;\n  transition:\n    opacity var(--_nav-label-fade-out-motion) 0ms,\n    mask-position var(--_nav-label-fade-out-motion) 0ms,\n    -webkit-mask-position var(--_nav-label-fade-out-motion) 0ms;\n}\n\n.panel-nav--collapsed ds-text.panel-nav__group-label {\n  opacity: 0;\n  max-height: 0;\n  padding: 0 calc(var(--dimension-space-075, 6px) + var(--ds-control-label-inset));\n  pointer-events: none;\n  transition:\n    opacity var(--_nav-label-fade-out-motion) 0ms,\n    max-height var(--_nav-label-fade-out-motion) 0ms,\n    padding var(--_nav-label-fade-out-motion) 0ms,\n    color var(--effect-motion-short-3, 200ms ease);\n}\n\n/* ── Footer ──────────────────────────────────────────────────────────────── */\n\n.panel-nav__footer {\n  position: relative;\n  flex-shrink: 0;\n  /* single row: padding*2 + item */\n  height: calc(var(--_nav-padding-y) * 2 + var(--_nav-item-height));\n  transition: height var(--_nav-expand-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer {\n  /* two rows: padding*2 + item*2 + gap */\n  height: calc(var(--_nav-padding-y) * 2 + var(--_nav-item-height) * 2 + var(--dimension-space-050, 4px));\n}\n\n/* ── Footer icon button (gear / dashboard) ───────────────────────────────── */\n\n.panel-nav__footer-btn {\n  position: absolute;\n  left: var(--_nav-padding-x);\n  top: var(--_nav-padding-y);\n  --ds-button-unfilled-fg: var(--_nav-fg-secondary);\n  --ds-button-unfilled-fg-active: var(--_nav-fg-primary);\n  --ds-interaction-hover: var(--_nav-hover);\n  --ds-interaction-pressed: var(--_nav-pressed);\n  --ds-focus-ring-color: var(--_nav-focus);\n}\n\n/* ── Footer user — absolutely positioned, slides from row to below gear ───── */\n\n.panel-nav__footer-user {\n  position: absolute;\n  /* Expanded row: balanced shell inset with an 8px gear-to-user gap. */\n  left: calc(var(--_nav-padding-x) + var(--_nav-footer-btn-w) + var(--dimension-space-100, 8px));\n  right: var(--_nav-padding-x);\n  top: var(--_nav-padding-y);\n  width: auto;\n  min-width: 0;\n  transition:\n    left var(--_nav-expand-motion),\n    right var(--_nav-expand-motion),\n    top var(--_nav-expand-motion);\n}\n\n/* Popup-open state keeps the native footer trigger visibly pressed. */\n.panel-nav__footer-user--menu-expanded::after {\n  background: var(--_nav-pressed);\n}\n\n.panel-nav__footer-user--menu-expanded {\n  --ds-interaction-hover: var(--_nav-pressed);\n}\n\n.panel-nav--collapsed .panel-nav__footer-user {\n  /* Resolve one shared square control while keeping both inline edges animatable. */\n  left: var(--_nav-padding-x);\n  right: calc(100% - var(--_nav-padding-x) - var(--_nav-item-height));\n  top: calc(var(--_nav-padding-y) + var(--_nav-item-height) + var(--dimension-space-050, 4px));\n}\n\n/* Label: absolute so it stays in place and only fades — no mask slide */\n.panel-nav__footer-user-label {\n  text-align: right;\n  position: absolute;\n  left: var(--dimension-space-075, 6px);\n  right: calc(var(--dimension-space-075, 6px) + var(--dimension-iconography-md, 20px) + var(--dimension-space-050, 4px));\n  top: 50%;\n  transform: translateY(-50%);\n  flex: none;\n  height: var(--typography-lineheight-md, 20px);\n  mask-image: none;\n  -webkit-mask-image: none;\n  transition: opacity var(--_nav-label-fade-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer-user-label {\n  opacity: 0;\n  pointer-events: none;\n  mask-position: 0% 0;\n  -webkit-mask-position: 0% 0;\n}\n\n/* ── Footer user icon — cross-fades chevron ↔ circle+initial ────────────── */\n\n/* Absolute — right-anchored in expanded, left-anchored in collapsed to match regular item icon position */\n.panel-nav__footer-user-icon {\n  position: absolute;\n  left: calc(100% - var(--dimension-iconography-md, 20px) - var(--dimension-space-075, 6px));\n  top: 0;\n  bottom: 0;\n  height: auto;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  transition: left var(--_nav-expand-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer-user-icon {\n  left: var(--dimension-space-075, 6px);\n}\n\n.panel-nav__footer-icon-expanded,\n.panel-nav__footer-icon-collapsed {\n  position: absolute;\n  inset: 0;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n}\n\n.panel-nav__footer-icon-expanded {\n  opacity: 1;\n  transition: opacity var(--_nav-label-fade-motion);\n}\n\n.panel-nav__footer-icon-collapsed {\n  opacity: 0;\n  transition: opacity var(--_nav-label-fade-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer-icon-expanded {\n  opacity: 0;\n  transition: opacity var(--_nav-label-fade-out-motion);\n}\n\n.panel-nav--collapsed .panel-nav__footer-icon-collapsed {\n  opacity: 1;\n  transition: opacity var(--_nav-label-fade-out-motion);\n}\n\n/* ── User initial — overlaid on the circle icon ─────────────────────────── */\n\n/*\n * Center the caption glyph on the Circle icon. Don't use inset:0 + flex — the\n * inner `.ds-text__element { width: 100% }` stretches and left-aligns the letter.\n * Translate-centering keeps the complete caption metric box on the icon center;\n * the caption variant remains the sole owner of its line-height.\n * (Do not set `inset: auto` after top/left — it resets them.)\n */\nds-text.panel-nav__user-initial,\nds-text.panel-nav__user-initial.ds-text--caption {\n  position: absolute;\n  top: 50%;\n  left: 50%;\n  right: auto;\n  bottom: auto;\n  transform: translate(-50%, -50%);\n  display: block;\n  width: max-content;\n  max-width: none;\n  min-width: 0;\n  text-align: center;\n  color: inherit;\n  pointer-events: none;\n}\n\n/* ── Drag-to-resize handle ───────────────────────────────────────────────── */\n\n/* The resize overlay line — extends past the right edge; keep above workspace content */\n.panel-nav__resize-handle {\n  position: absolute;\n  top: 0;\n  /* Centered on the right edge: --dimension-space-050 outside + inside = --dimension-space-100 hit zone */\n  right: var(--dimension-space-n050, -4px);\n  bottom: 0;\n  width: var(--dimension-space-100, 8px);\n  z-index: 20;\n  cursor: ew-resize;\n  touch-action: none;\n  /* Needs a real background for Safari hit-testing */\n  background: transparent;\n}\n\n/* Safari requires non-transparent fill for hit testing */\n.panel-nav__resize-handle::before {\n  content: '';\n  position: absolute;\n  inset: 0;\n  /* stylelint-disable-next-line color-named -- near-invisible hit-test fill; not a theme color */\n  background: rgba(0, 0, 0, 0.001);\n}\n\n/* Resize overlay line */\n.panel-nav__resize-handle::after {\n  content: '';\n  position: absolute;\n  top: 0;\n  bottom: 0;\n  left: 50%;\n  transform: translateX(-50%);\n  width: var(--dimension-stroke-width-025, 2px);\n  background: var(--color-foreground-primary);\n  opacity: 0;\n  pointer-events: none;\n  transition: opacity var(--effect-motion-short-2, 100ms ease-in-out);\n}\n\n.panel-nav__resize-handle--overlay::after {\n  opacity: 1;\n}\n\n/* ── Reduced motion ──────────────────────────────────────────────────────── */\n\n@media (prefers-reduced-motion: reduce) {\n  .panel-nav,\n  .panel-nav *,\n  .panel-nav *::before,\n  .panel-nav *::after,\n  .panel-nav__resize-handle,\n  .panel-nav__resize-handle::before,\n  .panel-nav__resize-handle::after {\n    /* Near-instant — browsers treat 0 as \"no transition\" and can skip the end state. */\n    transition-duration: var(--effect-animation-duration-instant) !important;\n    animation-duration: var(--effect-animation-duration-instant) !important;\n    transition-delay: var(--effect-animation-duration-instant) !important;\n  }\n}\n",
       "type": "registry:ui"
     },
     {