@ds-mo/ui 12.6.2 → 12.8.0

package/dist/mcp-data/registry/scroll-overlay.json

@@ -156,7 +156,7 @@
       },
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/tokens ^5.0.0",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."

package/dist/mcp-data/registry/select-multi.json

@@ -49,23 +49,25 @@
         "The popup is a listbox with aria-multiselectable and every option exposes its independent aria-selected state.",
         "Disabled options expose aria-disabled and are skipped by keyboard navigation and typeahead.",
         "Keyboard navigation keeps the aria-activedescendant option scrolled into the visible listbox viewport.",
-        "Each row uses a medium-size presentation-only ds-checkbox indicator; multi-select option rows never add a prefix icon alongside it, and the option remains the sole selection semantic and interaction target.",
+        "Each row uses a presentation-only ds-checkbox indicator at the same density as the row; multi-select option rows never add a prefix icon alongside it, and the option remains the sole selection semantic and interaction target.",
         "The trigger keeps its field label visible and appends the current selected count; an explicit aria-label or aria-labelledby remains the authoritative accessible name when supplied.",
         "Use errorMessage with error so the trigger is described by the rendered alert."
       ],
       "states": [
+        "Select and SelectMulti share popup positioning, dismissal, focus, typeahead, and listbox traversal while retaining their distinct scalar and array selection contracts.",
+        "Every size applies one complete control-density recipe across trigger height, inline padding, icon zones, text-container inset, gap, and radius; error content follows the shared 4px field flow.",
         "Values is a controlled JavaScript array; dsChange emits a new array after each user toggle.",
         "Required SelectMulti controls begin without an automatic selection and require the user to make an explicit choice.",
         "Selecting an option keeps the popup open so additional values can be toggled.",
-        "The trigger label stays left-aligned at every width; every option row uses the same leading medium Checkbox indicator. The default control size is md in both forms and filter bars.",
+        "The trigger label stays left-aligned at every width; every option row uses the same leading Checkbox indicator at its density. The default control size is md in both forms and filter bars.",
         "The selected count always follows the persistent label as plain text separated by a centered dot, including for one selection, and counts every selected value even when search or grouping hides it. Never replace the count with selected option names.",
         "Create sections only for categories that are meaningful to customers, not merely to break a long list into arbitrary chunks.",
         "When any option supplies subtext, every row uses the same subtext structure and missing values render an em dash. Subtext should disambiguate or add decision-helpful information.",
         "Option labels stay on one line and truncate when constrained. Option subtext may wrap to at most two lines.",
         "The optional prefix icon and chevron always use the parent surface's secondary foreground color, including when selection promotes the label and count to primary.",
-        "The shared popup search control stays md at every trigger size, using body-medium text, a 20px icon, and the same internal spacing as a borderless Select trigger. Its container uses menu-item padding on every side and owns a 1px bottom divider that becomes a 1.5px bold-brand stroke while search has focus. Search placeholder text is secondary at rest and quaternary while focused because it becomes decorative once the editable field is active.",
+        "The shared popup search control follows the SelectMulti density, using the same text, icon, and internal spacing as a borderless trigger. Its container uses menu-item padding on every side and owns a 1px bottom divider that becomes a 1.5px bold-brand stroke while search has focus. Search placeholder text is secondary at rest and quaternary while focused because it becomes decorative once the editable field is active.",
         "When search contains text, the shared control shows a rounded sm icon-only ButtonUnfilled with the Cross icon and no border. It clears the local term, stays hidden for an empty term, and returns focus to search.",
-        "The shared summary-and-clear footer mirrors the search region's sizing: menu-item padding surrounds an md-height borderless row, and both texts use the same row and label insets as option text. The outer footer owns a 1px top divider.",
+        "The shared summary-and-clear footer mirrors the owning density: menu-item padding surrounds a borderless density row, and both texts use the same row and label insets as option text. The outer footer owns a 1px top divider.",
         "An empty filtered list composes the message-only body variant of EmptyState. Keep the default neutral no-results message unless localized product guidance makes the outcome clearer.",
         "Enable searchable for more than roughly 20 options, user-managed listings, large domains such as addresses, or sets users cannot efficiently scan. Local matching includes option labels, subtext, and section headings; the owner resolves remote data before assigning options.",
         "When allowClear is enabled, clear-all appears only after at least one value exists. Clearing is valid for optional and required fields; a required field becomes invalid until the user selects again.",
@@ -343,7 +345,7 @@
         },
         "size": {
           "type": "SelectMultiSize",
-          "resolvedType": "\"md\" | \"sm\" | \"xs\"",
+          "resolvedType": "\"lg\" | \"md\" | \"sm\" | \"xs\"",
           "attribute": "size",
           "default": "'md'",
           "required": false,
@@ -639,7 +641,7 @@
       },
       "size": {
         "type": "SelectMultiSize",
-        "resolvedType": "\"md\" | \"sm\" | \"xs\"",
+        "resolvedType": "\"lg\" | \"md\" | \"sm\" | \"xs\"",
         "attribute": "size",
         "default": "'md'",
         "required": false,
@@ -720,7 +722,7 @@
       "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: options, sections, values.",
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/tokens ^5.0.0",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
@@ -749,7 +751,7 @@
     },
     {
       "path": "src/wc/components/SelectMulti/SelectMulti.tsx",
-      "content": "import {\n  AttachInternals,\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n  Watch,\n} from '@stencil/core';\nimport {\n  controlWidthClass,\n  CONTROL_TEXT_VARIANT,\n  choicePopupMinWidth,\n  resolveCssLengthPx,\n  resolveCssTimeMs,\n  resolveChoicePopupAlignOffset,\n  TOKEN_DEFAULTS,\n  DEFAULT_REQUIRED_MESSAGE,\n  setRequiredValidity,\n  type ControlWidth,\n} from '../../utils';\nimport { computeAnchoredPopupPosition } from '../../utils/anchored-popup';\nimport { ChoiceFooter, ChoiceOptionRow, ChoiceSearch } from '../../utils/choice-list-parts';\nimport {\n  choiceBackgroundClassMap,\n  choiceListUsesSubtext,\n  enabledChoiceIndexes,\n  filterChoiceSections,\n  findChoiceTypeaheadMatch,\n  flattenChoiceSections,\n  moveChoiceIndex,\n  resolveChoiceSections,\n} from '../../utils/choice-list';\nimport type {\n  SelectBackground,\n  SelectOption,\n  SelectSection,\n  SelectSize,\n} from '../Select/Select';\n\nexport type SelectMultiOption = Omit<SelectOption, 'icon'>;\nexport type SelectMultiSection = Omit<SelectSection, 'options'> & {\n  options: SelectMultiOption[];\n};\nexport type SelectMultiBackground = SelectBackground;\nexport type SelectMultiSize = SelectSize;\nexport type SelectMultiWidth = ControlWidth;\n\nconst ICON_SIZE: Record<SelectMultiSize, 'md' | 'sm' | 'xs'> = {\n  md: 'md',\n  sm: 'sm',\n  xs: 'xs',\n};\n\nlet selectMultiId = 0;\n/** rAF retries while the conditionally rendered popup mounts. */\nconst POSITION_RETRY_BUDGET = 8;\n\n@Component({\n  tag: 'ds-select-multi',\n  styleUrl: 'SelectMulti.css',\n  scoped: true,\n  formAssociated: true,\n})\nexport class SelectMulti {\n  @Element() el!: HTMLElement;\n  @AttachInternals() internals!: ElementInternals;\n\n  /** Flat choices. Assign arrays through the JavaScript property. */\n  @Prop() options: SelectMultiOption[] = [];\n  /** Grouped choices; takes precedence over options. Assign through JavaScript. */\n  @Prop() sections: SelectMultiSection[] = [];\n  /** Selected values. Assign arrays through the JavaScript property. */\n  @Prop({ mutable: true }) values: string[] = [];\n  /** Controlled popup visibility. */\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n  /** Native form field name used for each repeated selected-value entry. */\n  @Prop({ reflect: true }) name: string | undefined;\n  /** Native disabled state. */\n  @Prop({ reflect: true }) disabled: boolean = false;\n  /** Require at least one valid selected value. */\n  @Prop({ reflect: true }) required: boolean = false;\n  /** Validation message used when required is missing. */\n  @Prop() requiredMessage: string = DEFAULT_REQUIRED_MESSAGE;\n  /** Persistent trigger label; selected option labels never replace it. */\n  @Prop() placeholder: string = 'Select';\n  /** Control density. */\n  @Prop() size: SelectMultiSize = 'md';\n  /** Width fit — hug content (default) or fill the parent. */\n  @Prop() width: SelectMultiWidth = 'hug';\n  /** Shared inactive treatment; removes interaction and form submission. */\n  @Prop() isInactive: boolean = false;\n  /** Replace the prefix with a loader and disable option interaction. */\n  @Prop() isLoading: boolean = false;\n  /** Show the selected interaction fill when at least one value exists. */\n  @Prop() activeFill: boolean = true;\n  /** Show the surface-aware inset border. */\n  @Prop() hasBorder: boolean = true;\n  /** Optional trigger prefix icon name. */\n  @Prop() icon: string | undefined;\n  /** Show the clear-all footer action when values exist. */\n  @Prop() allowClear: boolean = true;\n  /** Localized clear-all action label. */\n  @Prop() clearLabel: string = 'Clear';\n  /** Localized noun displayed after the selected count. */\n  @Prop() selectedLabel: string = 'selected';\n  /** Show immediate local filtering over option labels, subtext, and section headings. */\n  @Prop() searchable: boolean = false;\n  /** Localized search-field placeholder and accessible name. */\n  @Prop() searchPlaceholder: string = 'Search';\n  /** Localized empty-filter result text. */\n  @Prop() noResultsText: string = 'No results found';\n  /** Accessible loading status label. */\n  @Prop() loadingLabel: string = 'Loading';\n  /** Actual parent surface context; omit on primary and secondary surfaces. */\n  @Prop() background: SelectMultiBackground | undefined;\n  /** Show invalid visual state. */\n  @Prop() error: boolean = false;\n  /** Error text rendered below the trigger when error is true. */\n  @Prop() errorMessage: string | undefined;\n  /** ID applied to the internal combobox trigger for external labels. */\n  @Prop() inputId: string | undefined;\n  /** Direct accessible name when no external label is available. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  /** IDs of elements that label the combobox. */\n  @Prop({ attribute: 'aria-labelledby' }) ariaLabelledby: string | undefined;\n  /** Additional IDs that describe the combobox. */\n  @Prop({ attribute: 'aria-describedby' }) ariaDescribedby: string | undefined;\n\n  /** Emitted after user toggles or clearing with a new values array. */\n  @Event() dsChange!: EventEmitter<string[]>;\n  /** Emitted after the footer clear-all action. */\n  @Event() dsClear!: EventEmitter<void>;\n  /** Emitted whenever popup visibility changes. */\n  @Event() dsOpenChange!: EventEmitter<boolean>;\n\n  @State() private activeIndex = -1;\n  @State() private searchTerm = '';\n  @State() private formDisabled = false;\n  @State() private position = { x: 0, y: 0 };\n  @State() private positionReady = false;\n  @State() private focusRingVisible = false;\n\n  private readonly generatedId = `ds-select-multi-${++selectMultiId}`;\n  private readonly listboxId = `${this.generatedId}-listbox`;\n  private readonly errorId = `${this.generatedId}-error`;\n  private triggerEl: HTMLButtonElement | null = null;\n  private popupEl: HTMLDivElement | null = null;\n  private searchEl: HTMLInputElement | null = null;\n  private initialValues: string[] = [];\n  private typeahead = '';\n  private typeaheadTimer: ReturnType<typeof setTimeout> | null = null;\n  private outsideHandler: ((event: MouseEvent) => void) | null = null;\n  private repositionHandler: (() => void) | null = null;\n  private positionRetryRaf: number | null = null;\n\n  componentWillLoad() {\n    this.initialValues = [...this.values];\n    this.syncFormValue();\n  }\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  disconnectedCallback() {\n    this.cancelPositionRetry();\n    this.unbindPopupListeners();\n    if (this.typeaheadTimer) clearTimeout(this.typeaheadTimer);\n  }\n\n  @Watch('values')\n  @Watch('disabled')\n  @Watch('isInactive')\n  @Watch('required')\n  @Watch('name')\n  @Watch('options')\n  @Watch('sections')\n  syncFormValue() {\n    const resolvedValues = this.resolvedValues;\n    if (this.isDisabled || !this.name || resolvedValues.length === 0) {\n      this.internals.setFormValue(null);\n    } else {\n      const data = new FormData();\n      resolvedValues.forEach(value => data.append(this.name as string, value));\n      this.internals.setFormValue(data, JSON.stringify(resolvedValues));\n    }\n    const missing = this.required && !this.isDisabled && resolvedValues.length === 0;\n    setRequiredValidity(this.internals, missing, this.requiredMessage);\n    if (this.open) {\n      const enabled = enabledChoiceIndexes(this.visibleOptions);\n      if (!enabled.includes(this.activeIndex)) this.activeIndex = enabled[0] ?? -1;\n      requestAnimationFrame(() => this.updatePosition());\n    }\n  }\n\n  @Watch('isLoading')\n  onLoadingChange() {\n    if (this.open) requestAnimationFrame(() => this.updatePosition());\n  }\n\n  @Watch('open')\n  onOpenChange(open: boolean) {\n    this.dsOpenChange.emit(open);\n    if (open) {\n      this.bindPopupListeners();\n      this.schedulePositionUpdate(() => {\n        this.scrollActiveOptionIntoView();\n        if (this.searchable) this.searchEl?.focus();\n      });\n    } else {\n      this.cancelPositionRetry();\n      this.unbindPopupListeners();\n      this.searchTerm = '';\n      this.positionReady = false;\n    }\n  }\n\n  @Watch('searchTerm')\n  onSearchTermChange() {\n    this.activeIndex = enabledChoiceIndexes(this.visibleOptions)[0] ?? -1;\n    requestAnimationFrame(() => {\n      this.updatePosition();\n      this.scrollActiveOptionIntoView();\n    });\n  }\n\n  @Watch('activeIndex')\n  onActiveIndexChange() {\n    requestAnimationFrame(() => this.scrollActiveOptionIntoView());\n  }\n\n  formDisabledCallback(disabled: boolean) {\n    this.formDisabled = disabled;\n    this.syncFormValue();\n  }\n\n  formResetCallback() {\n    this.values = [...this.initialValues];\n    this.closePopup();\n  }\n\n  formStateRestoreCallback(state: string | File | FormData | null) {\n    if (typeof state !== 'string') {\n      this.values = [];\n      return;\n    }\n    try {\n      const restored = JSON.parse(state);\n      this.values = Array.isArray(restored)\n        ? restored.filter((value): value is string => typeof value === 'string')\n        : [];\n    } catch {\n      this.values = [];\n    }\n  }\n\n  @Method()\n  async setFocus() {\n    this.triggerEl?.focus();\n  }\n\n  private get isDisabled(): boolean {\n    return this.disabled || this.isInactive || this.formDisabled;\n  }\n\n  private get allSections(): SelectMultiSection[] {\n    return resolveChoiceSections(this.options, this.sections);\n  }\n\n  private get allOptions(): SelectMultiOption[] {\n    return flattenChoiceSections(this.allSections);\n  }\n\n  private get visibleSections(): SelectMultiSection[] {\n    return this.searchable\n      ? filterChoiceSections(this.allSections, this.searchTerm)\n      : this.allSections;\n  }\n\n  private get visibleOptions(): SelectMultiOption[] {\n    return flattenChoiceSections(this.visibleSections);\n  }\n\n  private get resolvedValues(): string[] {\n    const valid = new Set(this.allOptions.map(option => option.value));\n    return [...new Set(this.values.filter(value => valid.has(value)))];\n  }\n\n  private get hasSelection(): boolean {\n    return this.resolvedValues.length > 0;\n  }\n\n  private get activeOptionId(): string | undefined {\n    return !this.isLoading && this.activeIndex >= 0\n      ? `${this.generatedId}-option-${this.activeIndex}`\n      : undefined;\n  }\n\n  private scrollActiveOptionIntoView() {\n    if (!this.open || !this.activeOptionId) return;\n    this.el\n      .querySelector<HTMLElement>(`#${this.activeOptionId}`)\n      ?.scrollIntoView({ block: 'nearest', inline: 'nearest' });\n  }\n\n  private bindPopupListeners() {\n    this.unbindPopupListeners();\n    this.outsideHandler = event => {\n      if (this.el.contains(event.target as Node)) return;\n      this.closePopup();\n    };\n    this.repositionHandler = () => this.updatePosition();\n    document.addEventListener('mousedown', this.outsideHandler, true);\n    window.addEventListener('scroll', this.repositionHandler, true);\n    window.addEventListener('resize', this.repositionHandler);\n  }\n\n  private unbindPopupListeners() {\n    if (this.outsideHandler) {\n      document.removeEventListener('mousedown', this.outsideHandler, true);\n      this.outsideHandler = null;\n    }\n    if (this.repositionHandler) {\n      window.removeEventListener('scroll', this.repositionHandler, true);\n      window.removeEventListener('resize', this.repositionHandler);\n      this.repositionHandler = null;\n    }\n  }\n\n  private cancelPositionRetry() {\n    if (this.positionRetryRaf !== null) {\n      cancelAnimationFrame(this.positionRetryRaf);\n      this.positionRetryRaf = null;\n    }\n  }\n\n  /** Retry until the conditionally rendered popup is mounted and measurable. */\n  private schedulePositionUpdate(onReady?: () => void) {\n    if (!this.open) return;\n\n    this.cancelPositionRetry();\n    this.positionReady = false;\n    let remaining = POSITION_RETRY_BUDGET;\n\n    const attempt = () => {\n      this.positionRetryRaf = null;\n      if (!this.open) return;\n\n      if (this.updatePosition()) {\n        onReady?.();\n        return;\n      }\n\n      if (remaining > 0) {\n        remaining -= 1;\n        this.positionRetryRaf = requestAnimationFrame(attempt);\n      }\n    };\n\n    this.positionRetryRaf = requestAnimationFrame(attempt);\n  }\n\n  /** @returns `true` when the current popup was found and positioned. */\n  private updatePosition(): boolean {\n    if (\n      !this.open ||\n      !this.triggerEl ||\n      !this.popupEl ||\n      !this.popupEl.isConnected ||\n      !this.el.contains(this.popupEl)\n    ) return false;\n    const sectionPadding = resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n    this.popupEl.style.minWidth = `${choicePopupMinWidth(this.triggerEl.offsetWidth, sectionPadding)}px`;\n    this.position = computeAnchoredPopupPosition({\n      anchorRect: this.triggerEl.getBoundingClientRect(),\n      popupWidth: this.popupEl.offsetWidth,\n      popupHeight: this.popupEl.offsetHeight,\n      side: 'bottom',\n      align: 'start',\n      sideOffsetPx: sectionPadding,\n      alignOffsetPx: resolveChoicePopupAlignOffset({\n        align: 'start',\n        alignOffsetPx: 0,\n        sectionInsetPx: sectionPadding,\n      }),\n      viewportPadPx: sectionPadding,\n      viewportWidth: window.innerWidth,\n      viewportHeight: window.innerHeight,\n    });\n    this.positionReady = true;\n    return true;\n  }\n\n  private openPopup(focusVisible: boolean, edge?: 'first' | 'last') {\n    if (this.isDisabled || (!this.allOptions.length && !this.isLoading)) return;\n    const enabled = enabledChoiceIndexes(this.visibleOptions);\n    this.activeIndex =\n      edge === 'last'\n        ? (enabled[enabled.length - 1] ?? -1)\n        : (enabled[0] ?? -1);\n    this.focusRingVisible = focusVisible;\n    this.open = true;\n  }\n\n  private closePopup(restoreFocus = false) {\n    if (!this.open) return;\n    this.open = false;\n    if (restoreFocus) requestAnimationFrame(() => this.triggerEl?.focus());\n  }\n\n  private toggleOption(option: SelectMultiOption) {\n    if (option.isInactive || this.isLoading) return;\n    const current = this.resolvedValues;\n    const next = current.includes(option.value)\n      ? current.filter(value => value !== option.value)\n      : [...current, option.value];\n    this.values = next;\n    this.dsChange.emit([...next]);\n  }\n\n  private clearSelection = (event: Event) => {\n    event.preventDefault();\n    event.stopPropagation();\n    this.values = [];\n    this.dsChange.emit([]);\n    this.dsClear.emit();\n    requestAnimationFrame(() => (this.searchable ? this.searchEl?.focus() : this.triggerEl?.focus()));\n  };\n\n  private handleTypeahead(key: string) {\n    if (this.typeaheadTimer) clearTimeout(this.typeaheadTimer);\n    this.focusRingVisible = true;\n    const normalized = key.toLocaleLowerCase();\n    const repeatedCharacter =\n      this.typeahead.length > 0 &&\n      [...this.typeahead].every(character => character === normalized);\n    this.typeahead = repeatedCharacter ? normalized : `${this.typeahead}${normalized}`;\n    const match = findChoiceTypeaheadMatch(this.visibleOptions, this.typeahead, this.activeIndex);\n    if (match >= 0) this.activeIndex = match;\n    const resetMs = resolveCssTimeMs(\n      TOKEN_DEFAULTS.animationDurationMedium1,\n      TOKEN_DEFAULTS.animationDurationMedium1,\n    );\n    this.typeaheadTimer = setTimeout(() => {\n      this.typeahead = '';\n      this.typeaheadTimer = null;\n    }, resetMs);\n  }\n\n  private handleListKeyDown(event: KeyboardEvent) {\n    switch (event.key) {\n      case 'ArrowDown':\n        event.preventDefault();\n        this.focusRingVisible = true;\n        this.activeIndex = moveChoiceIndex(this.visibleOptions, this.activeIndex, 1);\n        break;\n      case 'ArrowUp':\n        event.preventDefault();\n        this.focusRingVisible = true;\n        this.activeIndex = moveChoiceIndex(this.visibleOptions, this.activeIndex, -1);\n        break;\n      case 'Home':\n        event.preventDefault();\n        this.focusRingVisible = true;\n        this.activeIndex = enabledChoiceIndexes(this.visibleOptions)[0] ?? -1;\n        break;\n      case 'End': {\n        event.preventDefault();\n        this.focusRingVisible = true;\n        const enabled = enabledChoiceIndexes(this.visibleOptions);\n        this.activeIndex = enabled[enabled.length - 1] ?? -1;\n        break;\n      }\n      case 'Enter':\n      case ' ': {\n        if (event.key === ' ' && this.searchable && event.target === this.searchEl) break;\n        event.preventDefault();\n        const option = this.visibleOptions[this.activeIndex];\n        if (option) this.toggleOption(option);\n        break;\n      }\n      case 'Escape':\n        event.preventDefault();\n        this.closePopup(true);\n        break;\n      case 'Tab':\n        this.closePopup();\n        break;\n      default:\n        if (!this.searchable && event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey) {\n          this.handleTypeahead(event.key);\n        }\n    }\n  }\n\n  private handleTriggerKeyDown = (event: KeyboardEvent) => {\n    if (!this.open) {\n      if (['ArrowDown', 'ArrowUp', 'Enter', ' '].includes(event.key)) {\n        event.preventDefault();\n        this.openPopup(true, event.key === 'ArrowUp' ? 'last' : 'first');\n      } else if (event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey) {\n        event.preventDefault();\n        this.openPopup(true);\n        if (this.searchable) this.searchTerm = event.key;\n        else this.handleTypeahead(event.key);\n      }\n      return;\n    }\n    this.handleListKeyDown(event);\n  };\n\n  private renderOption(option: SelectMultiOption, index: number, usesSubtext: boolean) {\n    const selected = this.values.includes(option.value);\n    const active = this.activeIndex === index;\n    return (\n      <ChoiceOptionRow\n        id={`${this.generatedId}-option-${index}`}\n        option={option}\n        selected={selected}\n        active={active}\n        focusRingVisible={this.focusRingVisible}\n        usesSubtext={usesSubtext}\n        leading={(\n          <span class=\"ds-choice-item__icon ds-interaction-fill__content\" aria-hidden=\"true\">\n            <ds-checkbox\n              class=\"select-option__checkbox\"\n              label=\"\"\n              size=\"md\"\n              checked={selected}\n              presentation\n            />\n          </span>\n        )}\n        onHover={() => {\n            this.focusRingVisible = false;\n            this.activeIndex = index;\n        }}\n        onSelect={() => this.toggleOption(option)}\n      />\n    );\n  }\n\n  render() {\n    const inactive = this.isDisabled;\n    const count = this.resolvedValues.length;\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const iconSize = ICON_SIZE[this.size];\n    const usesOptionSubtext = choiceListUsesSubtext(this.allOptions);\n    const showError = this.error && Boolean(this.errorMessage);\n    const describedBy = [this.ariaDescribedby, showError ? this.errorId : undefined]\n      .filter(Boolean)\n      .join(' ') || undefined;\n    const popupStyle = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.position.x)}px, ${Math.round(this.position.y)}px)`,\n      zIndex: 'var(--dimension-z-index-floating)',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n    let flatIndex = 0;\n\n    return (\n      <Host\n        class={{\n          'select-host': true,\n          'ds-control-inactive': inactive,\n          'ds-control--md': this.size === 'md',\n          'ds-control--sm': this.size === 'sm',\n          'ds-control--xs': this.size === 'xs',\n          ...controlWidthClass(this.width),\n          [`select-host--background-${this.background}`]: !!this.background,\n        }}\n      >\n        <button\n          ref={element => {\n            this.triggerEl = (element as HTMLButtonElement) ?? null;\n          }}\n          id={this.inputId ?? this.generatedId}\n          type=\"button\"\n          class={{\n            trigger: true,\n            'ds-focus-ring-inset': true,\n            'ds-interaction-fill': true,\n            'ds-interaction-fill--selected':\n              !inactive && this.activeFill && this.hasSelection,\n            'trigger--bordered': this.hasBorder || this.error,\n            'trigger--has-value': this.hasSelection,\n            'wrapper--error': this.error,\n            [`ds-control--${this.size}`]: true,\n            ...choiceBackgroundClassMap(this.background),\n          }}\n          disabled={inactive}\n          role=\"combobox\"\n          aria-haspopup=\"listbox\"\n          aria-expanded={String(this.open)}\n          aria-controls={this.open ? this.listboxId : undefined}\n          aria-activedescendant={this.open && !this.searchable ? this.activeOptionId : undefined}\n          aria-label={this.ariaLabel}\n          aria-labelledby={this.ariaLabelledby}\n          aria-describedby={describedBy}\n          aria-invalid={this.error ? 'true' : undefined}\n          aria-required={this.required || undefined}\n          aria-busy={this.isLoading ? 'true' : undefined}\n          onClick={() => (this.open ? this.closePopup() : this.openPopup(false))}\n          onKeyDown={this.handleTriggerKeyDown}\n        >\n          {(this.icon || this.isLoading) && (\n            <span class=\"trigger__prefix ds-interaction-fill__content\" aria-hidden=\"true\">\n              {this.isLoading ? (\n                <ds-loader size={iconSize} color=\"inherit\" />\n              ) : (\n                <ds-icon name={this.icon} size={iconSize} color=\"inherit\" />\n              )}\n            </span>\n          )}\n          <ds-text\n            class=\"trigger__label ds-interaction-fill__content\"\n            as=\"span\"\n            variant={textVariant}\n            color=\"inherit\"\n            lineTruncation={1}\n          >\n            {`${this.placeholder}${count > 0 ? ` · ${count}` : ''}`}\n          </ds-text>\n          <span class=\"trigger__chevron ds-interaction-fill__content\" aria-hidden=\"true\">\n            <ds-icon name=\"ChevronDown\" size={iconSize} color=\"inherit\" />\n          </span>\n        </button>\n\n        {this.open && (\n          <div\n            ref={element => {\n              this.popupEl = (element as HTMLDivElement) ?? null;\n            }}\n            class=\"select-popup ds-choice-popup\"\n            style={popupStyle}\n          >\n            {this.searchable && (\n              <ChoiceSearch\n                value={this.searchTerm}\n                placeholder={this.searchPlaceholder}\n                controls={this.listboxId}\n                activeDescendant={this.activeOptionId}\n                inputRef={element => {\n                  this.searchEl = element;\n                }}\n                clearLabel={this.clearLabel}\n                onValueChange={value => {\n                  this.searchTerm = value;\n                }}\n                onKeyDown={event => this.handleListKeyDown(event)}\n              />\n            )}\n            <div\n              id={this.listboxId}\n              class=\"ds-choice-list\"\n              role=\"listbox\"\n              aria-multiselectable=\"true\"\n              aria-label={this.ariaLabel ?? this.placeholder}\n              aria-busy={this.isLoading ? 'true' : undefined}\n            >\n              {this.isLoading ? (\n                <div\n                  class=\"ds-choice-loading\"\n                  role=\"option\"\n                  aria-selected=\"false\"\n                  aria-disabled=\"true\"\n                  aria-label={this.loadingLabel}\n                  aria-live=\"polite\"\n                >\n                  <ds-loader size=\"md\" color=\"inherit\" />\n                </div>\n              ) : this.visibleOptions.length === 0 ? (\n                <div\n                  class=\"ds-choice-empty\"\n                  role=\"option\"\n                  aria-selected=\"false\"\n                  aria-disabled=\"true\"\n                  aria-label={this.noResultsText}\n                  aria-live=\"polite\"\n                >\n                  <ds-empty-state body={this.noResultsText} />\n                </div>\n              ) : (\n                this.visibleSections.map(section => (\n                  <div\n                    class={{\n                      'ds-choice-section': true,\n                      'ds-choice-section--divided': !!section.divider,\n                    }}\n                    role={section.header ? 'group' : undefined}\n                    aria-label={section.header}\n                  >\n                    {section.header && (\n                      <ds-text\n                        class=\"ds-choice-section__header ds-control--md\"\n                        as=\"span\"\n                        variant=\"text-body-small\"\n                        emphasis\n                        color=\"primary\"\n                        aria-hidden=\"true\"\n                      >\n                        {section.header}\n                      </ds-text>\n                    )}\n                    {section.options.map(option => this.renderOption(\n                      option,\n                      flatIndex++,\n                      usesOptionSubtext,\n                    ))}\n                  </div>\n                ))\n              )}\n            </div>\n            {this.allowClear && this.hasSelection && !this.isLoading && (\n              <ChoiceFooter\n                summary={`${count} ${this.selectedLabel}`}\n                clearLabel={this.clearLabel}\n                onClear={this.clearSelection}\n              />\n            )}\n          </div>\n        )}\n\n        {showError && (\n          <ds-text\n            class=\"error-text\"\n            as=\"div\"\n            variant=\"text-body-small\"\n            color=\"negative\"\n            textId={this.errorId}\n            role=\"alert\"\n          >\n            {this.errorMessage}\n          </ds-text>\n        )}\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  AttachInternals,\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n  Watch,\n} from '@stencil/core';\nimport {\n  controlWidthClass,\n  CONTROL_SUPPORTING_TEXT_VARIANT,\n  CONTROL_TEXT_VARIANT,\n  DEFAULT_REQUIRED_MESSAGE,\n  setRequiredValidity,\n  type ControlWidth,\n} from '../../utils';\nimport { ChoiceFooter, ChoiceOptionRow, ChoiceSearch } from '../../utils/choice-list-parts';\nimport {\n  choiceBackgroundClassMap,\n  choiceListUsesSubtext,\n  filterChoiceSections,\n  flattenChoiceSections,\n  resolveChoiceSections,\n} from '../../utils/choice-list';\nimport { SelectController } from '../../utils/select-controller';\nimport type {\n  SelectBackground,\n  SelectOption,\n  SelectSection,\n  SelectSize,\n} from '../Select/Select';\n\nexport type SelectMultiOption = Omit<SelectOption, 'icon'>;\nexport type SelectMultiSection = Omit<SelectSection, 'options'> & {\n  options: SelectMultiOption[];\n};\nexport type SelectMultiBackground = SelectBackground;\nexport type SelectMultiSize = SelectSize;\nexport type SelectMultiWidth = ControlWidth;\n\nconst ICON_SIZE: Record<SelectMultiSize, 'lg' | 'md' | 'sm' | 'xs'> = {\n  lg: 'lg',\n  md: 'md',\n  sm: 'sm',\n  xs: 'xs',\n};\n\nlet selectMultiId = 0;\n\n@Component({\n  tag: 'ds-select-multi',\n  styleUrl: 'SelectMulti.css',\n  scoped: true,\n  formAssociated: true,\n})\nexport class SelectMulti {\n  @Element() el!: HTMLElement;\n  @AttachInternals() internals!: ElementInternals;\n\n  /** Flat choices. Assign arrays through the JavaScript property. */\n  @Prop() options: SelectMultiOption[] = [];\n  /** Grouped choices; takes precedence over options. Assign through JavaScript. */\n  @Prop() sections: SelectMultiSection[] = [];\n  /** Selected values. Assign arrays through the JavaScript property. */\n  @Prop({ mutable: true }) values: string[] = [];\n  /** Controlled popup visibility. */\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n  /** Native form field name used for each repeated selected-value entry. */\n  @Prop({ reflect: true }) name: string | undefined;\n  /** Native disabled state. */\n  @Prop({ reflect: true }) disabled: boolean = false;\n  /** Require at least one valid selected value. */\n  @Prop({ reflect: true }) required: boolean = false;\n  /** Validation message used when required is missing. */\n  @Prop() requiredMessage: string = DEFAULT_REQUIRED_MESSAGE;\n  /** Persistent trigger label; selected option labels never replace it. */\n  @Prop() placeholder: string = 'Select';\n  /** Control density. */\n  @Prop() size: SelectMultiSize = 'md';\n  /** Width fit — hug content (default) or fill the parent. */\n  @Prop() width: SelectMultiWidth = 'hug';\n  /** Shared inactive treatment; removes interaction and form submission. */\n  @Prop() isInactive: boolean = false;\n  /** Replace the prefix with a loader and disable option interaction. */\n  @Prop() isLoading: boolean = false;\n  /** Show the selected interaction fill when at least one value exists. */\n  @Prop() activeFill: boolean = true;\n  /** Show the surface-aware inset border. */\n  @Prop() hasBorder: boolean = true;\n  /** Optional trigger prefix icon name. */\n  @Prop() icon: string | undefined;\n  /** Show the clear-all footer action when values exist. */\n  @Prop() allowClear: boolean = true;\n  /** Localized clear-all action label. */\n  @Prop() clearLabel: string = 'Clear';\n  /** Localized noun displayed after the selected count. */\n  @Prop() selectedLabel: string = 'selected';\n  /** Show immediate local filtering over option labels, subtext, and section headings. */\n  @Prop() searchable: boolean = false;\n  /** Localized search-field placeholder and accessible name. */\n  @Prop() searchPlaceholder: string = 'Search';\n  /** Localized empty-filter result text. */\n  @Prop() noResultsText: string = 'No results found';\n  /** Accessible loading status label. */\n  @Prop() loadingLabel: string = 'Loading';\n  /** Actual parent surface context; omit on primary and secondary surfaces. */\n  @Prop() background: SelectMultiBackground | undefined;\n  /** Show invalid visual state. */\n  @Prop() error: boolean = false;\n  /** Error text rendered below the trigger when error is true. */\n  @Prop() errorMessage: string | undefined;\n  /** ID applied to the internal combobox trigger for external labels. */\n  @Prop() inputId: string | undefined;\n  /** Direct accessible name when no external label is available. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  /** IDs of elements that label the combobox. */\n  @Prop({ attribute: 'aria-labelledby' }) ariaLabelledby: string | undefined;\n  /** Additional IDs that describe the combobox. */\n  @Prop({ attribute: 'aria-describedby' }) ariaDescribedby: string | undefined;\n\n  /** Emitted after user toggles or clearing with a new values array. */\n  @Event() dsChange!: EventEmitter<string[]>;\n  /** Emitted after the footer clear-all action. */\n  @Event() dsClear!: EventEmitter<void>;\n  /** Emitted whenever popup visibility changes. */\n  @Event() dsOpenChange!: EventEmitter<boolean>;\n\n  @State() private activeIndex = -1;\n  @State() private searchTerm = '';\n  @State() private formDisabled = false;\n  @State() private position = { x: 0, y: 0 };\n  @State() private positionReady = false;\n  @State() private focusRingVisible = false;\n\n  private readonly generatedId = `ds-select-multi-${++selectMultiId}`;\n  private readonly listboxId = `${this.generatedId}-listbox`;\n  private readonly errorId = `${this.generatedId}-error`;\n  private initialValues: string[] = [];\n  private readonly controller = this.createController();\n\n  private createController() {\n    // eslint-disable-next-line @typescript-eslint/no-this-alias -- adapter getters preserve reactive component ownership without inheritance.\n    const owner = this;\n    return new SelectController<SelectMultiOption>({\n      get host() { return owner.el; },\n      generatedId: owner.generatedId,\n      get options() { return owner.visibleOptions; },\n      get searchable() { return owner.searchable; },\n      get isLoading() { return owner.isLoading; },\n      get isDisabled() { return owner.isDisabled; },\n      get preferredIndex() { return -1; },\n      get open() { return owner.open; },\n      set open(value) { owner.open = value; },\n      get activeIndex() { return owner.activeIndex; },\n      set activeIndex(value) { owner.activeIndex = value; },\n      get searchTerm() { return owner.searchTerm; },\n      set searchTerm(value) { owner.searchTerm = value; },\n      get focusRingVisible() { return owner.focusRingVisible; },\n      set focusRingVisible(value) { owner.focusRingVisible = value; },\n      get position() { return owner.position; },\n      set position(value) { owner.position = value; },\n      get positionReady() { return owner.positionReady; },\n      set positionReady(value) { owner.positionReady = value; },\n      selectOption: option => owner.toggleOption(option),\n    });\n  }\n\n  componentWillLoad() {\n    this.initialValues = [...this.values];\n    this.syncFormValue();\n  }\n\n  componentDidLoad() {\n    this.controller.connect();\n  }\n\n  disconnectedCallback() {\n    this.controller.disconnect();\n  }\n\n  @Watch('values')\n  @Watch('disabled')\n  @Watch('isInactive')\n  @Watch('required')\n  @Watch('name')\n  @Watch('options')\n  @Watch('sections')\n  syncFormValue() {\n    const resolvedValues = this.resolvedValues;\n    if (this.isDisabled || !this.name || resolvedValues.length === 0) {\n      this.internals.setFormValue(null);\n    } else {\n      const data = new FormData();\n      resolvedValues.forEach(value => data.append(this.name as string, value));\n      this.internals.setFormValue(data, JSON.stringify(resolvedValues));\n    }\n    const missing = this.required && !this.isDisabled && resolvedValues.length === 0;\n    setRequiredValidity(this.internals, missing, this.requiredMessage);\n    this.controller.optionsChanged();\n  }\n\n  @Watch('isLoading')\n  onLoadingChange() {\n    this.controller.loadingChanged();\n  }\n\n  @Watch('open')\n  onOpenChange(open: boolean) {\n    this.dsOpenChange.emit(open);\n    this.controller.openChanged(open);\n  }\n\n  @Watch('searchTerm')\n  onSearchTermChange() {\n    this.controller.searchChanged();\n  }\n\n  @Watch('activeIndex')\n  onActiveIndexChange() {\n    this.controller.activeIndexChanged();\n  }\n\n  formDisabledCallback(disabled: boolean) {\n    this.formDisabled = disabled;\n    this.syncFormValue();\n  }\n\n  formResetCallback() {\n    this.values = [...this.initialValues];\n    this.closePopup();\n  }\n\n  formStateRestoreCallback(state: string | File | FormData | null) {\n    if (typeof state !== 'string') {\n      this.values = [];\n      return;\n    }\n    try {\n      const restored = JSON.parse(state);\n      this.values = Array.isArray(restored)\n        ? restored.filter((value): value is string => typeof value === 'string')\n        : [];\n    } catch {\n      this.values = [];\n    }\n  }\n\n  @Method()\n  async setFocus() {\n    this.controller.setFocus();\n  }\n\n  private get isDisabled(): boolean {\n    return this.disabled || this.isInactive || this.formDisabled;\n  }\n\n  private get allSections(): SelectMultiSection[] {\n    return resolveChoiceSections(this.options, this.sections);\n  }\n\n  private get allOptions(): SelectMultiOption[] {\n    return flattenChoiceSections(this.allSections);\n  }\n\n  private get visibleSections(): SelectMultiSection[] {\n    return this.searchable\n      ? filterChoiceSections(this.allSections, this.searchTerm)\n      : this.allSections;\n  }\n\n  private get visibleOptions(): SelectMultiOption[] {\n    return flattenChoiceSections(this.visibleSections);\n  }\n\n  private get resolvedValues(): string[] {\n    const valid = new Set(this.allOptions.map(option => option.value));\n    return [...new Set(this.values.filter(value => valid.has(value)))];\n  }\n\n  private get hasSelection(): boolean {\n    return this.resolvedValues.length > 0;\n  }\n\n  private get activeOptionId(): string | undefined {\n    return this.controller.activeOptionId;\n  }\n\n  private closePopup(restoreFocus = false) {\n    this.controller.closePopup(restoreFocus);\n  }\n\n  private openPopup(focusVisible: boolean, edge?: 'first' | 'last') {\n    this.controller.openPopup(focusVisible, edge);\n  }\n\n  private toggleOption(option: SelectMultiOption) {\n    if (option.isInactive || this.isLoading) return;\n    const current = this.resolvedValues;\n    const next = current.includes(option.value)\n      ? current.filter(value => value !== option.value)\n      : [...current, option.value];\n    this.values = next;\n    this.dsChange.emit([...next]);\n  }\n\n  private clearSelection = (event: Event) => {\n    event.preventDefault();\n    event.stopPropagation();\n    this.values = [];\n    this.dsChange.emit([]);\n    this.dsClear.emit();\n    this.controller.focusSearchOrTrigger();\n  };\n\n  private readonly handleListKeyDown = this.controller.handleListKeyDown;\n  private readonly handleTriggerKeyDown = this.controller.handleTriggerKeyDown;\n\n  private renderOption(option: SelectMultiOption, index: number, usesSubtext: boolean) {\n    const selected = this.values.includes(option.value);\n    const active = this.activeIndex === index;\n    return (\n      <ChoiceOptionRow\n        size={this.size}\n        id={`${this.generatedId}-option-${index}`}\n        option={option}\n        selected={selected}\n        active={active}\n        focusRingVisible={this.focusRingVisible}\n        usesSubtext={usesSubtext}\n        leading={(\n          <span class=\"ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\" aria-hidden=\"true\">\n            <ds-checkbox\n              class=\"select-option__checkbox\"\n              label=\"\"\n              size={this.size}\n              checked={selected}\n              presentation\n            />\n          </span>\n        )}\n        onHover={() => {\n            this.focusRingVisible = false;\n            this.activeIndex = index;\n        }}\n        onSelect={() => this.toggleOption(option)}\n      />\n    );\n  }\n\n  render() {\n    const inactive = this.isDisabled;\n    const count = this.resolvedValues.length;\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const iconSize = ICON_SIZE[this.size];\n    const usesOptionSubtext = choiceListUsesSubtext(this.allOptions);\n    const showError = this.error && Boolean(this.errorMessage);\n    const describedBy = [this.ariaDescribedby, showError ? this.errorId : undefined]\n      .filter(Boolean)\n      .join(' ') || undefined;\n    const popupStyle = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.position.x)}px, ${Math.round(this.position.y)}px)`,\n      zIndex: 'var(--dimension-z-index-floating)',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n    let flatIndex = 0;\n\n    return (\n      <Host\n        class={{\n          'select-host': true,\n          'ds-field-stack': true,\n          'ds-control-inactive': inactive,\n          [`ds-control--${this.size}`]: true,\n          ...controlWidthClass(this.width),\n          [`select-host--background-${this.background}`]: !!this.background,\n        }}\n      >\n        <button\n          ref={element => {\n            this.controller.setTriggerElement((element as HTMLButtonElement) ?? null);\n          }}\n          id={this.inputId ?? this.generatedId}\n          type=\"button\"\n          class={{\n            trigger: true,\n            'ds-control-frame': true,\n            'ds-focus-ring-inset': true,\n            'ds-interaction-fill': true,\n            'ds-interaction-fill--selected':\n              !inactive && this.activeFill && this.hasSelection,\n            'trigger--bordered': this.hasBorder || this.error,\n            'trigger--has-value': this.hasSelection,\n            'wrapper--error': this.error,\n            [`ds-control--${this.size}`]: true,\n            ...choiceBackgroundClassMap(this.background),\n          }}\n          disabled={inactive}\n          role=\"combobox\"\n          aria-haspopup=\"listbox\"\n          aria-expanded={String(this.open)}\n          aria-controls={this.open ? this.listboxId : undefined}\n          aria-activedescendant={this.open && !this.searchable ? this.activeOptionId : undefined}\n          aria-label={this.ariaLabel}\n          aria-labelledby={this.ariaLabelledby}\n          aria-describedby={describedBy}\n          aria-invalid={this.error ? 'true' : undefined}\n          aria-required={this.required || undefined}\n          aria-busy={this.isLoading ? 'true' : undefined}\n          onClick={() => (this.open ? this.closePopup() : this.openPopup(false))}\n          onKeyDown={this.handleTriggerKeyDown}\n        >\n          {(this.icon || this.isLoading) && (\n            <span class=\"trigger__prefix ds-control-icon-box ds-interaction-fill__content\" aria-hidden=\"true\">\n              {this.isLoading ? (\n                <ds-loader size={iconSize} color=\"inherit\" />\n              ) : (\n                <ds-icon name={this.icon} size={iconSize} color=\"inherit\" />\n              )}\n            </span>\n          )}\n          <ds-text\n            class=\"trigger__label ds-control-label-box ds-interaction-fill__content\"\n            as=\"span\"\n            variant={textVariant}\n            color=\"inherit\"\n            lineTruncation={1}\n          >\n            {`${this.placeholder}${count > 0 ? ` · ${count}` : ''}`}\n          </ds-text>\n          <span class=\"trigger__chevron ds-control-icon-box ds-interaction-fill__content\" aria-hidden=\"true\">\n            <ds-icon name=\"ChevronDown\" size={iconSize} color=\"inherit\" />\n          </span>\n        </button>\n\n        {this.open && (\n          <div\n            ref={element => {\n              this.controller.setPopupElement((element as HTMLDivElement) ?? null);\n            }}\n            class=\"select-popup ds-choice-popup\"\n            style={popupStyle}\n          >\n            {this.searchable && (\n              <ChoiceSearch\n                size={this.size}\n                value={this.searchTerm}\n                placeholder={this.searchPlaceholder}\n                controls={this.listboxId}\n                activeDescendant={this.activeOptionId}\n                inputRef={this.controller.setSearchElement}\n                clearLabel={this.clearLabel}\n                onValueChange={value => {\n                  this.searchTerm = value;\n                }}\n                onKeyDown={event => this.handleListKeyDown(event)}\n              />\n            )}\n            <div\n              id={this.listboxId}\n              class=\"ds-choice-list\"\n              role=\"listbox\"\n              aria-multiselectable=\"true\"\n              aria-label={this.ariaLabel ?? this.placeholder}\n              aria-busy={this.isLoading ? 'true' : undefined}\n            >\n              {this.isLoading ? (\n                <div\n                  class=\"ds-choice-loading\"\n                  role=\"option\"\n                  aria-selected=\"false\"\n                  aria-disabled=\"true\"\n                  aria-label={this.loadingLabel}\n                  aria-live=\"polite\"\n                >\n                  <ds-loader size={this.size} color=\"inherit\" />\n                </div>\n              ) : this.visibleOptions.length === 0 ? (\n                <div\n                  class=\"ds-choice-empty ds-empty-region\"\n                  role=\"option\"\n                  aria-selected=\"false\"\n                  aria-disabled=\"true\"\n                  aria-label={this.noResultsText}\n                  aria-live=\"polite\"\n                >\n                  <ds-empty-state body={this.noResultsText} />\n                </div>\n              ) : (\n                this.visibleSections.map(section => (\n                  <div\n                    class={{\n                      'ds-choice-section': true,\n                      'ds-chrome-column': true,\n                      'ds-chrome-space--sm': true,\n                      'ds-choice-section--divided': !!section.divider,\n                    }}\n                    role={section.header ? 'group' : undefined}\n                    aria-label={section.header}\n                  >\n                    {section.header && (\n                      <ds-text\n                        class={`ds-choice-section__header 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                        {section.header}\n                      </ds-text>\n                    )}\n                    {section.options.map(option => this.renderOption(\n                      option,\n                      flatIndex++,\n                      usesOptionSubtext,\n                    ))}\n                  </div>\n                ))\n              )}\n            </div>\n            {this.allowClear && this.hasSelection && !this.isLoading && (\n              <ChoiceFooter\n                size={this.size}\n                summary={`${count} ${this.selectedLabel}`}\n                clearLabel={this.clearLabel}\n                onClear={this.clearSelection}\n              />\n            )}\n          </div>\n        )}\n\n        {showError && (\n          <ds-text\n            class=\"error-text\"\n            as=\"div\"\n            variant=\"text-body-small\"\n            color=\"negative\"\n            textId={this.errorId}\n            role=\"alert\"\n          >\n            {this.errorMessage}\n          </ds-text>\n        )}\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

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

@@ -58,6 +58,8 @@
         "Use errorMessage with error so the trigger is described by the rendered alert."
       ],
       "states": [
+        "Select and SelectMulti share popup positioning, dismissal, focus, typeahead, and listbox traversal while retaining their distinct scalar and array selection contracts.",
+        "Every size applies one complete control-density recipe across trigger height, inline padding, icon zones, text-container inset, gap, and radius; error content follows the shared 4px field flow.",
         "Value is controlled through the mutable value property; dsChange reports user selection and clearing.",
         "Required Selects begin without an automatic selection and require the user to make an explicit choice; do not preselect the first option merely to satisfy validity.",
         "When allowClear is enabled, the clear affordance appears only after a value exists. Clearing is valid for optional and required fields; a required field becomes invalid until the user selects again.",
@@ -69,9 +71,9 @@
         "When any option supplies subtext, every row uses the same subtext structure and missing values render an em dash. Subtext should disambiguate or add decision-helpful information.",
         "Option labels and the selected trigger label stay on one line and truncate when constrained. Option subtext may wrap to at most two lines.",
         "The optional prefix icon and chevron always use the parent surface's secondary foreground color, including when a selected value promotes the label to primary.",
-        "The shared popup search control stays md at every trigger size, using body-medium text, a 20px icon, and the same internal spacing as a borderless Select trigger. Its container uses menu-item padding on every side and owns a 1px bottom divider that becomes a 1.5px bold-brand stroke while search has focus. Search placeholder text is secondary at rest and quaternary while focused because it becomes decorative once the editable field is active.",
-        "When search contains text, the shared control shows a rounded sm icon-only ButtonUnfilled with the CrossCircle icon and no border. It clears the local term, stays hidden for an empty term, and returns focus to search.",
-        "The shared clear footer mirrors the search region's sizing: menu-item padding surrounds an md-height borderless row, and the Clear label uses the same row and label insets as option text. The outer footer owns a 1px top divider.",
+        "The shared popup search control follows the Select density, using the same text, icon, and internal spacing as a borderless trigger. Its container uses menu-item padding on every side and owns a 1px bottom divider that becomes a 1.5px bold-brand stroke while search has focus. Search placeholder text is secondary at rest and quaternary while focused because it becomes decorative once the editable field is active.",
+        "When search contains text, the shared control shows a rounded icon-only ButtonUnfilled with the CrossCircle icon and no border, sized to remain inset within the current row density. It clears the local term, stays hidden for an empty term, and returns focus to search.",
+        "The shared clear footer mirrors the owning density: menu-item padding surrounds a borderless density row, and the Clear label uses the same row and label insets as option text. The outer footer owns a 1px top divider.",
         "An empty filtered list composes the message-only body variant of EmptyState. Keep the default neutral no-results message unless localized product guidance makes the outcome clearer.",
         "Enable searchable for more than roughly 20 options, user-managed listings, large domains such as addresses, or sets users cannot efficiently scan. Local matching includes option labels, subtext, and section headings; the owner resolves remote data before assigning options.",
         "Validation timing belongs to the form owner and may be immediate or deferred until blur or submit; the Select exposes validity and error presentation without imposing that policy.",
@@ -336,7 +338,7 @@
         },
         "size": {
           "type": "SelectSize",
-          "resolvedType": "\"md\" | \"sm\" | \"xs\"",
+          "resolvedType": "\"lg\" | \"md\" | \"sm\" | \"xs\"",
           "attribute": "size",
           "default": "'md'",
           "required": false,
@@ -624,7 +626,7 @@
       },
       "size": {
         "type": "SelectSize",
-        "resolvedType": "\"md\" | \"sm\" | \"xs\"",
+        "resolvedType": "\"lg\" | \"md\" | \"sm\" | \"xs\"",
         "attribute": "size",
         "default": "'md'",
         "required": false,
@@ -706,7 +708,7 @@
       "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: options, sections.",
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/tokens ^5.0.0",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
@@ -729,12 +731,12 @@
   "files": [
     {
       "path": "src/wc/components/Select/Select.css",
-      "content": "@import '../../utils/choice-list.css';\n@import '../../utils/control-width.css';\n@import '../../utils/search-control.css';\n@import '../../utils/typography.css';\n\n:host(.select-host) {\n  display: inline-flex;\n  flex-direction: column;\n  gap: var(--dimension-space-050);\n  position: relative;\n  outline: none;\n  --ds-select-fg: var(--color-foreground-secondary);\n  --ds-select-fg-active: var(--color-foreground-primary);\n  --ds-select-prefix-fg: var(--ds-select-fg);\n  --ds-select-chevron-fg: var(--ds-select-fg);\n  --ds-select-border: var(--color-border-secondary);\n}\n\n:host(.ds-control-width--fill),\n:host(.ds-control-width--fill) .trigger {\n  width: 100%;\n}\n\n.trigger {\n  display: inline-flex;\n  align-items: center;\n  justify-content: flex-start;\n  box-sizing: border-box;\n  height: var(--ds-control-height, var(--dimension-size-400));\n  padding: 0 var(--ds-control-padding-inline, var(--dimension-space-075));\n  gap: var(--ds-control-gap, var(--dimension-space-050));\n  background: transparent;\n  border: none;\n  border-radius: var(--ds-control-radius, var(--dimension-radius-025));\n  color: var(--ds-select-fg);\n  cursor: default;\n  font-family: inherit;\n  -webkit-user-select: none;\n  user-select: none;\n  overflow: hidden;\n  transition: color var(--effect-motion-short-2);\n}\n\n.trigger--bordered {\n  --ds-interaction-border-width: var(--dimension-stroke-width-012);\n  --ds-interaction-border-color: var(--ds-select-border);\n}\n\n.trigger--has-value .trigger__label {\n  color: var(--ds-select-fg-active);\n}\n\n.wrapper--error {\n  --ds-interaction-border-width: var(--dimension-stroke-width-018);\n  --ds-interaction-border-color: var(--color-border-bold-negative);\n}\n\n.trigger__prefix,\n.trigger__chevron {\n  position: relative;\n  z-index: 2;\n  flex-shrink: 0;\n  width: var(--ds-control-icon, var(--dimension-iconography-md));\n  height: var(--ds-control-icon, var(--dimension-iconography-md));\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n}\n\n.trigger__prefix {\n  color: var(--ds-select-prefix-fg);\n}\n\n.trigger__chevron {\n  color: var(--ds-select-chevron-fg);\n}\n\n.trigger__label {\n  position: relative;\n  z-index: 2;\n  flex: 1 1 auto;\n  min-width: 0;\n  padding: 0 var(--ds-control-label-inset, var(--dimension-space-025));\n  text-align: left;\n  color: inherit;\n  transition: color var(--effect-motion-short-2);\n}\n\n.select-popup {\n  color: var(--color-foreground-secondary);\n}\n\n.select-option[aria-selected='true'] .ds-choice-item__icon {\n  color: var(--color-foreground-primary);\n}\n\n.error-text {\n  width: 100%;\n}\n\n:host(.select-host--background-medium) {\n  --ds-select-fg: var(--color-foreground-on-medium-background-secondary);\n  --ds-select-fg-active: var(--color-foreground-on-medium-background-primary);\n  --ds-select-border: var(--color-border-on-medium-background-secondary);\n}\n\n:host(.select-host--background-bold) {\n  --ds-select-fg: var(--color-foreground-on-bold-background-secondary);\n  --ds-select-fg-active: var(--color-foreground-on-bold-background-primary);\n  --ds-select-border: var(--color-border-on-bold-background-secondary);\n}\n\n:host(.select-host--background-strong) {\n  --ds-select-fg: var(--color-foreground-on-strong-background-secondary);\n  --ds-select-fg-active: var(--color-foreground-on-strong-background-primary);\n  --ds-select-border: var(--color-border-on-strong-background-secondary);\n}\n\n:host(.select-host--background-translucent) {\n  --ds-select-fg: var(--color-translucent-foreground-secondary);\n  --ds-select-fg-active: var(--color-translucent-foreground-primary);\n  --ds-select-border: var(--color-translucent-border-secondary);\n}\n\n:host(.select-host--background-inverted) {\n  --ds-select-fg: var(--color-inverted-foreground-secondary);\n  --ds-select-fg-active: var(--color-inverted-foreground-primary);\n  --ds-select-border: var(--color-inverted-border-secondary);\n}\n\n:host(.select-host--background-media) {\n  --ds-select-fg: var(--color-media-foreground-secondary);\n  --ds-select-fg-active: var(--color-media-foreground-primary);\n  --ds-select-border: var(--color-media-border-secondary);\n}\n\n:host(.select-host--background-always-dark) {\n  --ds-select-fg: var(--color-always-dark-foreground-secondary);\n  --ds-select-fg-active: var(--color-always-dark-foreground-primary);\n  --ds-select-border: var(--color-always-dark-border-secondary);\n}\n",
+      "content": "@import '../../utils/choice-list.css';\n@import '../../utils/control-parts.css';\n@import '../../utils/control-width.css';\n@import '../../utils/field-stack.css';\n@import '../../utils/search-control.css';\n@import '../../utils/typography.css';\n\n:host(.select-host) {\n  display: inline-flex;\n  position: relative;\n  outline: none;\n  --ds-select-fg: var(--color-foreground-secondary);\n  --ds-select-fg-active: var(--color-foreground-primary);\n  --ds-select-prefix-fg: var(--ds-select-fg);\n  --ds-select-chevron-fg: var(--ds-select-fg);\n  --ds-select-border: var(--color-border-secondary);\n}\n\n:host(.ds-control-width--fill),\n:host(.ds-control-width--fill) .trigger {\n  width: 100%;\n}\n\n.trigger {\n  justify-content: flex-start;\n  background: transparent;\n  border: none;\n  border-radius: var(--ds-control-radius, var(--dimension-radius-025));\n  color: var(--ds-select-fg);\n  cursor: default;\n  font-family: inherit;\n  -webkit-user-select: none;\n  user-select: none;\n  overflow: hidden;\n  transition: color var(--effect-motion-short-2);\n}\n\n.trigger--bordered {\n  --ds-interaction-border-width: var(--dimension-stroke-width-012);\n  --ds-interaction-border-color: var(--ds-select-border);\n}\n\n.trigger--has-value .trigger__label {\n  color: var(--ds-select-fg-active);\n}\n\n.wrapper--error {\n  --ds-interaction-border-width: var(--dimension-stroke-width-018);\n  --ds-interaction-border-color: var(--color-border-bold-negative);\n}\n\n.trigger__prefix,\n.trigger__chevron {\n  position: relative;\n  z-index: 2;\n}\n\n.trigger__prefix {\n  color: var(--ds-select-prefix-fg);\n}\n\n.trigger__chevron {\n  color: var(--ds-select-chevron-fg);\n}\n\n.trigger__label {\n  position: relative;\n  z-index: 2;\n  flex: 1 1 auto;\n  text-align: left;\n  color: inherit;\n  transition: color var(--effect-motion-short-2);\n}\n\n.select-popup {\n  color: var(--color-foreground-secondary);\n}\n\n.select-option[aria-selected='true'] .ds-choice-item__icon {\n  color: var(--color-foreground-primary);\n}\n\n.error-text {\n  width: 100%;\n}\n\n:host(.select-host--background-medium) {\n  --ds-select-fg: var(--color-foreground-on-medium-background-secondary);\n  --ds-select-fg-active: var(--color-foreground-on-medium-background-primary);\n  --ds-select-border: var(--color-border-on-medium-background-secondary);\n}\n\n:host(.select-host--background-bold) {\n  --ds-select-fg: var(--color-foreground-on-bold-background-secondary);\n  --ds-select-fg-active: var(--color-foreground-on-bold-background-primary);\n  --ds-select-border: var(--color-border-on-bold-background-secondary);\n}\n\n:host(.select-host--background-strong) {\n  --ds-select-fg: var(--color-foreground-on-strong-background-secondary);\n  --ds-select-fg-active: var(--color-foreground-on-strong-background-primary);\n  --ds-select-border: var(--color-border-on-strong-background-secondary);\n}\n\n:host(.select-host--background-translucent) {\n  --ds-select-fg: var(--color-translucent-foreground-secondary);\n  --ds-select-fg-active: var(--color-translucent-foreground-primary);\n  --ds-select-border: var(--color-translucent-border-secondary);\n}\n\n:host(.select-host--background-inverted) {\n  --ds-select-fg: var(--color-inverted-foreground-secondary);\n  --ds-select-fg-active: var(--color-inverted-foreground-primary);\n  --ds-select-border: var(--color-inverted-border-secondary);\n}\n\n:host(.select-host--background-media) {\n  --ds-select-fg: var(--color-media-foreground-secondary);\n  --ds-select-fg-active: var(--color-media-foreground-primary);\n  --ds-select-border: var(--color-media-border-secondary);\n}\n\n:host(.select-host--background-always-dark) {\n  --ds-select-fg: var(--color-always-dark-foreground-secondary);\n  --ds-select-fg-active: var(--color-always-dark-foreground-primary);\n  --ds-select-border: var(--color-always-dark-border-secondary);\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/Select/Select.tsx",
-      "content": "import {\n  AttachInternals,\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n  Watch,\n} from '@stencil/core';\nimport {\n  controlWidthClass,\n  CONTROL_TEXT_VARIANT,\n  choicePopupMinWidth,\n  resolveCssLengthPx,\n  resolveCssTimeMs,\n  resolveChoicePopupAlignOffset,\n  TOKEN_DEFAULTS,\n  DEFAULT_REQUIRED_MESSAGE,\n  setRequiredValidity,\n  type ControlWidth,\n} from '../../utils';\nimport { computeAnchoredPopupPosition } from '../../utils/anchored-popup';\nimport { ChoiceFooter, ChoiceOptionRow, ChoiceSearch } from '../../utils/choice-list-parts';\nimport {\n  choiceBackgroundClassMap,\n  choiceListUsesIcons,\n  choiceListUsesSubtext,\n  enabledChoiceIndexes,\n  filterChoiceSections,\n  findChoiceTypeaheadMatch,\n  flattenChoiceSections,\n  moveChoiceIndex,\n  resolveChoiceSections,\n  type ChoiceBackground,\n  type ChoiceOption,\n  type ChoiceSection,\n} from '../../utils/choice-list';\n\nexport type SelectOption = ChoiceOption;\nexport type SelectSection = ChoiceSection;\nexport type SelectBackground = ChoiceBackground;\nexport type SelectSize = 'md' | 'sm' | 'xs';\nexport type SelectWidth = ControlWidth;\n\nconst ICON_SIZE: Record<SelectSize, 'md' | 'sm' | 'xs'> = {\n  md: 'md',\n  sm: 'sm',\n  xs: 'xs',\n};\n\nlet selectId = 0;\n/** rAF retries while the conditionally rendered popup mounts. */\nconst POSITION_RETRY_BUDGET = 8;\n\n@Component({\n  tag: 'ds-select',\n  styleUrl: 'Select.css',\n  scoped: true,\n  formAssociated: true,\n})\nexport class Select {\n  @Element() el!: HTMLElement;\n  @AttachInternals() internals!: ElementInternals;\n\n  /** Flat choices. Assign arrays through the JavaScript property. */\n  @Prop() options: SelectOption[] = [];\n  /** Grouped choices; takes precedence over options. Assign through JavaScript. */\n  @Prop() sections: SelectSection[] = [];\n  /** Selected string value. Unknown values render the placeholder and are not submitted. */\n  @Prop({ mutable: true }) value: string = '';\n  /** Controlled popup visibility. */\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n  /** Native form field name. */\n  @Prop({ reflect: true }) name: string | undefined;\n  /** Native disabled state. */\n  @Prop({ reflect: true }) disabled: boolean = false;\n  /** Require one valid selected value. */\n  @Prop({ reflect: true }) required: boolean = false;\n  /** Validation message used when required is missing. */\n  @Prop() requiredMessage: string = DEFAULT_REQUIRED_MESSAGE;\n  /** Trigger text shown when no valid value is selected. */\n  @Prop() placeholder: string = 'Select';\n  /** Control density. */\n  @Prop() size: SelectSize = 'md';\n  /** Width fit — hug content (default) or fill the parent. */\n  @Prop() width: SelectWidth = 'hug';\n  /** Shared inactive treatment; removes interaction and form submission. */\n  @Prop() isInactive: boolean = false;\n  /** Replace the prefix with a loader and disable option interaction. */\n  @Prop() isLoading: boolean = false;\n  /** Show the selected interaction fill when a valid value exists. */\n  @Prop() activeFill: boolean = true;\n  /** Show the surface-aware inset border. */\n  @Prop() hasBorder: boolean = true;\n  /** Optional trigger prefix icon name. */\n  @Prop() icon: string | undefined;\n  /** Show the clear footer action when a value exists. */\n  @Prop() allowClear: boolean = true;\n  /** Localized clear action label. */\n  @Prop() clearLabel: string = 'Clear';\n  /** Show immediate local filtering over option labels, subtext, and section headings. */\n  @Prop() searchable: boolean = false;\n  /** Localized search-field placeholder and accessible name. */\n  @Prop() searchPlaceholder: string = 'Search';\n  /** Localized empty-filter result text. */\n  @Prop() noResultsText: string = 'No results found';\n  /** Accessible loading status label. */\n  @Prop() loadingLabel: string = 'Loading';\n  /** Actual parent surface context; omit on primary and secondary surfaces. */\n  @Prop() background: SelectBackground | undefined;\n  /** Show invalid visual state. */\n  @Prop() error: boolean = false;\n  /** Error text rendered below the trigger when error is true. */\n  @Prop() errorMessage: string | undefined;\n  /** ID applied to the internal combobox trigger for external labels. */\n  @Prop() inputId: string | undefined;\n  /** Direct accessible name when no external label is available. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  /** IDs of elements that label the combobox. */\n  @Prop({ attribute: 'aria-labelledby' }) ariaLabelledby: string | undefined;\n  /** Additional IDs that describe the combobox. */\n  @Prop({ attribute: 'aria-describedby' }) ariaDescribedby: string | undefined;\n\n  /** Emitted after user selection or clearing with the next scalar value. */\n  @Event() dsChange!: EventEmitter<string>;\n  /** Emitted after the footer clear action. */\n  @Event() dsClear!: EventEmitter<void>;\n  /** Emitted whenever popup visibility changes. */\n  @Event() dsOpenChange!: EventEmitter<boolean>;\n\n  @State() private activeIndex = -1;\n  @State() private searchTerm = '';\n  @State() private formDisabled = false;\n  @State() private position = { x: 0, y: 0 };\n  @State() private positionReady = false;\n  @State() private focusRingVisible = false;\n\n  private readonly generatedId = `ds-select-${++selectId}`;\n  private readonly listboxId = `${this.generatedId}-listbox`;\n  private readonly errorId = `${this.generatedId}-error`;\n  private triggerEl: HTMLButtonElement | null = null;\n  private popupEl: HTMLDivElement | null = null;\n  private searchEl: HTMLInputElement | null = null;\n  private initialValue = '';\n  private typeahead = '';\n  private typeaheadTimer: ReturnType<typeof setTimeout> | null = null;\n  private outsideHandler: ((event: MouseEvent) => void) | null = null;\n  private repositionHandler: (() => void) | null = null;\n  private positionRetryRaf: number | null = null;\n\n  componentWillLoad() {\n    this.initialValue = this.value;\n    this.syncFormValue();\n  }\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  disconnectedCallback() {\n    this.cancelPositionRetry();\n    this.unbindPopupListeners();\n    if (this.typeaheadTimer) clearTimeout(this.typeaheadTimer);\n  }\n\n  @Watch('value')\n  @Watch('disabled')\n  @Watch('isInactive')\n  @Watch('required')\n  @Watch('options')\n  @Watch('sections')\n  syncFormValue() {\n    const inactive = this.isDisabled;\n    const resolvedValue = this.hasSelection ? this.value : '';\n    this.internals.setFormValue(inactive ? null : resolvedValue);\n    const missing = this.required && !inactive && !resolvedValue;\n    setRequiredValidity(this.internals, missing, this.requiredMessage);\n    if (this.open) {\n      const enabled = enabledChoiceIndexes(this.visibleOptions);\n      if (!enabled.includes(this.activeIndex)) this.activeIndex = enabled[0] ?? -1;\n      requestAnimationFrame(() => this.updatePosition());\n    }\n  }\n\n  @Watch('isLoading')\n  onLoadingChange() {\n    if (this.open) requestAnimationFrame(() => this.updatePosition());\n  }\n\n  @Watch('open')\n  onOpenChange(open: boolean) {\n    this.dsOpenChange.emit(open);\n    if (open) {\n      this.bindPopupListeners();\n      this.schedulePositionUpdate(() => {\n        this.scrollActiveOptionIntoView();\n        if (this.searchable) this.searchEl?.focus();\n      });\n    } else {\n      this.cancelPositionRetry();\n      this.unbindPopupListeners();\n      this.searchTerm = '';\n      this.positionReady = false;\n    }\n  }\n\n  @Watch('searchTerm')\n  onSearchTermChange() {\n    const enabled = enabledChoiceIndexes(this.visibleOptions);\n    this.activeIndex = enabled[0] ?? -1;\n    requestAnimationFrame(() => {\n      this.updatePosition();\n      this.scrollActiveOptionIntoView();\n    });\n  }\n\n  @Watch('activeIndex')\n  onActiveIndexChange() {\n    requestAnimationFrame(() => this.scrollActiveOptionIntoView());\n  }\n\n  formDisabledCallback(disabled: boolean) {\n    this.formDisabled = disabled;\n    this.syncFormValue();\n  }\n\n  formResetCallback() {\n    this.value = this.initialValue;\n    this.closePopup();\n  }\n\n  formStateRestoreCallback(state: string | File | FormData | null) {\n    this.value = typeof state === 'string' ? state : '';\n  }\n\n  @Method()\n  async setFocus() {\n    this.triggerEl?.focus();\n  }\n\n  private get isDisabled(): boolean {\n    return this.disabled || this.isInactive || this.formDisabled;\n  }\n\n  private get allSections(): SelectSection[] {\n    return resolveChoiceSections(this.options, this.sections);\n  }\n\n  private get allOptions(): SelectOption[] {\n    return flattenChoiceSections(this.allSections);\n  }\n\n  private get visibleSections(): SelectSection[] {\n    return this.searchable\n      ? filterChoiceSections(this.allSections, this.searchTerm)\n      : this.allSections;\n  }\n\n  private get visibleOptions(): SelectOption[] {\n    return flattenChoiceSections(this.visibleSections);\n  }\n\n  private get selectedOption(): SelectOption | undefined {\n    return this.allOptions.find(option => option.value === this.value);\n  }\n\n  private get hasSelection(): boolean {\n    return Boolean(this.selectedOption);\n  }\n\n  private get activeOptionId(): string | undefined {\n    return !this.isLoading && this.activeIndex >= 0\n      ? `${this.generatedId}-option-${this.activeIndex}`\n      : undefined;\n  }\n\n  private scrollActiveOptionIntoView() {\n    if (!this.open || !this.activeOptionId) return;\n    this.el\n      .querySelector<HTMLElement>(`#${this.activeOptionId}`)\n      ?.scrollIntoView({ block: 'nearest', inline: 'nearest' });\n  }\n\n  private bindPopupListeners() {\n    this.unbindPopupListeners();\n    this.outsideHandler = event => {\n      const target = event.target as Node;\n      if (this.el.contains(target)) return;\n      this.closePopup();\n    };\n    this.repositionHandler = () => this.updatePosition();\n    document.addEventListener('mousedown', this.outsideHandler, true);\n    window.addEventListener('scroll', this.repositionHandler, true);\n    window.addEventListener('resize', this.repositionHandler);\n  }\n\n  private unbindPopupListeners() {\n    if (this.outsideHandler) {\n      document.removeEventListener('mousedown', this.outsideHandler, true);\n      this.outsideHandler = null;\n    }\n    if (this.repositionHandler) {\n      window.removeEventListener('scroll', this.repositionHandler, true);\n      window.removeEventListener('resize', this.repositionHandler);\n      this.repositionHandler = null;\n    }\n  }\n\n  private cancelPositionRetry() {\n    if (this.positionRetryRaf !== null) {\n      cancelAnimationFrame(this.positionRetryRaf);\n      this.positionRetryRaf = null;\n    }\n  }\n\n  /** Retry until the conditionally rendered popup is mounted and measurable. */\n  private schedulePositionUpdate(onReady?: () => void) {\n    if (!this.open) return;\n\n    this.cancelPositionRetry();\n    this.positionReady = false;\n    let remaining = POSITION_RETRY_BUDGET;\n\n    const attempt = () => {\n      this.positionRetryRaf = null;\n      if (!this.open) return;\n\n      if (this.updatePosition()) {\n        onReady?.();\n        return;\n      }\n\n      if (remaining > 0) {\n        remaining -= 1;\n        this.positionRetryRaf = requestAnimationFrame(attempt);\n      }\n    };\n\n    this.positionRetryRaf = requestAnimationFrame(attempt);\n  }\n\n  /** @returns `true` when the current popup was found and positioned. */\n  private updatePosition(): boolean {\n    if (\n      !this.open ||\n      !this.triggerEl ||\n      !this.popupEl ||\n      !this.popupEl.isConnected ||\n      !this.el.contains(this.popupEl)\n    ) return false;\n    const sectionPadding = resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n    this.popupEl.style.minWidth = `${choicePopupMinWidth(this.triggerEl.offsetWidth, sectionPadding)}px`;\n    this.position = computeAnchoredPopupPosition({\n      anchorRect: this.triggerEl.getBoundingClientRect(),\n      popupWidth: this.popupEl.offsetWidth,\n      popupHeight: this.popupEl.offsetHeight,\n      side: 'bottom',\n      align: 'start',\n      sideOffsetPx: sectionPadding,\n      alignOffsetPx: resolveChoicePopupAlignOffset({\n        align: 'start',\n        alignOffsetPx: 0,\n        sectionInsetPx: sectionPadding,\n      }),\n      viewportPadPx: sectionPadding,\n      viewportWidth: window.innerWidth,\n      viewportHeight: window.innerHeight,\n    });\n    this.positionReady = true;\n    return true;\n  }\n\n  private openPopup(focusVisible: boolean, edge?: 'first' | 'last') {\n    if (this.isDisabled || (!this.allOptions.length && !this.isLoading)) return;\n    const enabled = enabledChoiceIndexes(this.visibleOptions);\n    const selectedIndex = this.visibleOptions.findIndex(\n      option => option.value === this.value && !option.isInactive,\n    );\n    this.activeIndex =\n      edge === 'last'\n        ? (enabled[enabled.length - 1] ?? -1)\n        : selectedIndex >= 0\n          ? selectedIndex\n          : (enabled[0] ?? -1);\n    this.focusRingVisible = focusVisible;\n    this.open = true;\n  }\n\n  private closePopup(restoreFocus = false) {\n    if (!this.open) return;\n    this.open = false;\n    if (restoreFocus) requestAnimationFrame(() => this.triggerEl?.focus());\n  }\n\n  private selectOption(option: SelectOption) {\n    if (option.isInactive || this.isLoading) return;\n    this.value = option.value;\n    this.dsChange.emit(this.value);\n    this.closePopup(true);\n  }\n\n  private clearSelection = (event: Event) => {\n    event.preventDefault();\n    event.stopPropagation();\n    this.value = '';\n    this.dsChange.emit('');\n    this.dsClear.emit();\n    const enabled = enabledChoiceIndexes(this.visibleOptions);\n    this.activeIndex = enabled[0] ?? -1;\n    requestAnimationFrame(() => (this.searchable ? this.searchEl?.focus() : this.triggerEl?.focus()));\n  };\n\n  private moveActive(direction: 1 | -1) {\n    this.activeIndex = moveChoiceIndex(this.visibleOptions, this.activeIndex, direction);\n  }\n\n  private setActiveEdge(edge: 'first' | 'last') {\n    const enabled = enabledChoiceIndexes(this.visibleOptions);\n    this.activeIndex =\n      edge === 'first' ? (enabled[0] ?? -1) : (enabled[enabled.length - 1] ?? -1);\n  }\n\n  private handleTypeahead(key: string) {\n    if (this.typeaheadTimer) clearTimeout(this.typeaheadTimer);\n    this.focusRingVisible = true;\n    const normalized = key.toLocaleLowerCase();\n    const repeatedCharacter =\n      this.typeahead.length > 0 &&\n      [...this.typeahead].every(character => character === normalized);\n    this.typeahead = repeatedCharacter ? normalized : `${this.typeahead}${normalized}`;\n    const match = findChoiceTypeaheadMatch(this.visibleOptions, this.typeahead, this.activeIndex);\n    if (match >= 0) this.activeIndex = match;\n    const resetMs = resolveCssTimeMs(\n      TOKEN_DEFAULTS.animationDurationMedium1,\n      TOKEN_DEFAULTS.animationDurationMedium1,\n    );\n    this.typeaheadTimer = setTimeout(() => {\n      this.typeahead = '';\n      this.typeaheadTimer = null;\n    }, resetMs);\n  }\n\n  private handleListKeyDown(event: KeyboardEvent) {\n    switch (event.key) {\n      case 'ArrowDown':\n        event.preventDefault();\n        this.focusRingVisible = true;\n        this.moveActive(1);\n        break;\n      case 'ArrowUp':\n        event.preventDefault();\n        this.focusRingVisible = true;\n        this.moveActive(-1);\n        break;\n      case 'Home':\n        event.preventDefault();\n        this.focusRingVisible = true;\n        this.setActiveEdge('first');\n        break;\n      case 'End':\n        event.preventDefault();\n        this.focusRingVisible = true;\n        this.setActiveEdge('last');\n        break;\n      case 'Enter':\n      case ' ': {\n        if (event.key === ' ' && this.searchable && event.target === this.searchEl) break;\n        event.preventDefault();\n        const option = this.visibleOptions[this.activeIndex];\n        if (option) this.selectOption(option);\n        break;\n      }\n      case 'Escape':\n        event.preventDefault();\n        this.closePopup(true);\n        break;\n      case 'Tab':\n        this.closePopup();\n        break;\n      default:\n        if (!this.searchable && event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey) {\n          this.handleTypeahead(event.key);\n        }\n    }\n  }\n\n  private handleTriggerKeyDown = (event: KeyboardEvent) => {\n    if (!this.open) {\n      if (['ArrowDown', 'ArrowUp', 'Enter', ' '].includes(event.key)) {\n        event.preventDefault();\n        this.openPopup(true, event.key === 'ArrowUp' ? 'last' : 'first');\n      } else if (event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey) {\n        event.preventDefault();\n        this.openPopup(true);\n        if (this.searchable) {\n          this.searchTerm = event.key;\n        } else {\n          this.handleTypeahead(event.key);\n        }\n      }\n      return;\n    }\n    this.handleListKeyDown(event);\n  };\n\n  private renderOption(\n    option: SelectOption,\n    index: number,\n    usesIcons: boolean,\n    usesSubtext: boolean,\n  ) {\n    const selected = option.value === this.value;\n    const active = index === this.activeIndex;\n    return (\n      <ChoiceOptionRow\n        id={`${this.generatedId}-option-${index}`}\n        option={option}\n        selected={selected}\n        active={active}\n        focusRingVisible={this.focusRingVisible}\n        usesSubtext={usesSubtext}\n        leading={usesIcons && option.icon ? (\n          <span class=\"ds-choice-item__icon ds-interaction-fill__content\" aria-hidden=\"true\">\n            <ds-icon name={option.icon} size=\"md\" color=\"inherit\" />\n          </span>\n        ) : undefined}\n        onHover={() => {\n            this.focusRingVisible = false;\n            this.activeIndex = index;\n        }}\n        onSelect={() => this.selectOption(option)}\n      />\n    );\n  }\n\n  render() {\n    const inactive = this.isDisabled;\n    const showPlaceholder = !this.hasSelection;\n    const label = showPlaceholder ? this.placeholder : this.selectedOption?.label;\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const iconSize = ICON_SIZE[this.size];\n    const usesOptionIcons = choiceListUsesIcons(this.allOptions);\n    const usesOptionSubtext = choiceListUsesSubtext(this.allOptions);\n    const showError = this.error && Boolean(this.errorMessage);\n    const describedBy = [this.ariaDescribedby, showError ? this.errorId : undefined]\n      .filter(Boolean)\n      .join(' ') || undefined;\n    const popupStyle = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.position.x)}px, ${Math.round(this.position.y)}px)`,\n      zIndex: 'var(--dimension-z-index-floating)',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n    let flatIndex = 0;\n\n    return (\n      <Host\n        class={{\n          'select-host': true,\n          'ds-control-inactive': inactive,\n          'ds-control--md': this.size === 'md',\n          'ds-control--sm': this.size === 'sm',\n          'ds-control--xs': this.size === 'xs',\n          ...controlWidthClass(this.width),\n          [`select-host--background-${this.background}`]: !!this.background,\n        }}\n      >\n        <button\n          ref={element => {\n            this.triggerEl = (element as HTMLButtonElement) ?? null;\n          }}\n          id={this.inputId ?? this.generatedId}\n          type=\"button\"\n          class={{\n            trigger: true,\n            'ds-focus-ring-inset': true,\n            'ds-interaction-fill': true,\n            'ds-interaction-fill--selected':\n              !inactive && this.activeFill && this.hasSelection,\n            'trigger--bordered': this.hasBorder || this.error,\n            'trigger--placeholder': showPlaceholder,\n            'trigger--has-value': this.hasSelection,\n            'wrapper--error': this.error,\n            [`ds-control--${this.size}`]: true,\n            ...choiceBackgroundClassMap(this.background),\n          }}\n          disabled={inactive}\n          role=\"combobox\"\n          aria-haspopup=\"listbox\"\n          aria-expanded={String(this.open)}\n          aria-controls={this.open ? this.listboxId : undefined}\n          aria-activedescendant={this.open && !this.searchable ? this.activeOptionId : undefined}\n          aria-label={this.ariaLabel}\n          aria-labelledby={this.ariaLabelledby}\n          aria-describedby={describedBy}\n          aria-invalid={this.error ? 'true' : undefined}\n          aria-required={this.required || undefined}\n          aria-busy={this.isLoading ? 'true' : undefined}\n          onClick={() => (this.open ? this.closePopup() : this.openPopup(false))}\n          onKeyDown={this.handleTriggerKeyDown}\n        >\n          {(this.icon || this.isLoading) && (\n            <span class=\"trigger__prefix ds-interaction-fill__content\" aria-hidden=\"true\">\n              {this.isLoading ? (\n                <ds-loader size={iconSize} color=\"inherit\" />\n              ) : (\n                <ds-icon name={this.icon} size={iconSize} color=\"inherit\" />\n              )}\n            </span>\n          )}\n          <ds-text\n            class=\"trigger__label ds-interaction-fill__content\"\n            as=\"span\"\n            variant={textVariant}\n            color=\"inherit\"\n            lineTruncation={1}\n          >\n            {label}\n          </ds-text>\n          <span class=\"trigger__chevron ds-interaction-fill__content\" aria-hidden=\"true\">\n            <ds-icon name=\"ChevronDown\" size={iconSize} color=\"inherit\" />\n          </span>\n        </button>\n\n        {this.open && (\n          <div\n            ref={element => {\n              this.popupEl = (element as HTMLDivElement) ?? null;\n            }}\n            class=\"select-popup ds-choice-popup\"\n            style={popupStyle}\n          >\n            {this.searchable && (\n              <ChoiceSearch\n                value={this.searchTerm}\n                placeholder={this.searchPlaceholder}\n                controls={this.listboxId}\n                activeDescendant={this.activeOptionId}\n                inputRef={element => {\n                  this.searchEl = element;\n                }}\n                clearLabel={this.clearLabel}\n                onValueChange={value => {\n                  this.searchTerm = value;\n                }}\n                onKeyDown={event => this.handleListKeyDown(event)}\n              />\n            )}\n            <div\n              id={this.listboxId}\n              class=\"ds-choice-list\"\n              role=\"listbox\"\n              aria-label={this.ariaLabel ?? this.placeholder}\n              aria-busy={this.isLoading ? 'true' : undefined}\n            >\n              {this.isLoading ? (\n                <div\n                  class=\"ds-choice-loading\"\n                  role=\"option\"\n                  aria-selected=\"false\"\n                  aria-disabled=\"true\"\n                  aria-label={this.loadingLabel}\n                  aria-live=\"polite\"\n                >\n                  <ds-loader size=\"md\" color=\"inherit\" />\n                </div>\n              ) : this.visibleOptions.length === 0 ? (\n                <div\n                  class=\"ds-choice-empty\"\n                  role=\"option\"\n                  aria-selected=\"false\"\n                  aria-disabled=\"true\"\n                  aria-label={this.noResultsText}\n                  aria-live=\"polite\"\n                >\n                  <ds-empty-state body={this.noResultsText} />\n                </div>\n              ) : (\n                this.visibleSections.map(section => (\n                  <div\n                    class={{\n                      'ds-choice-section': true,\n                      'ds-choice-section--divided': !!section.divider,\n                    }}\n                    role={section.header ? 'group' : undefined}\n                    aria-label={section.header}\n                  >\n                    {section.header && (\n                      <ds-text\n                        class=\"ds-choice-section__header ds-control--md\"\n                        as=\"span\"\n                        variant=\"text-body-small\"\n                        emphasis\n                        color=\"primary\"\n                        aria-hidden=\"true\"\n                      >\n                        {section.header}\n                      </ds-text>\n                    )}\n                    {section.options.map(option => this.renderOption(\n                      option,\n                      flatIndex++,\n                      usesOptionIcons,\n                      usesOptionSubtext,\n                    ))}\n                  </div>\n                ))\n              )}\n            </div>\n            {this.allowClear && this.hasSelection && !this.isLoading && (\n              <ChoiceFooter clearLabel={this.clearLabel} onClear={this.clearSelection} />\n            )}\n          </div>\n        )}\n\n        {showError && (\n          <ds-text\n            class=\"error-text\"\n            as=\"div\"\n            variant=\"text-body-small\"\n            color=\"negative\"\n            textId={this.errorId}\n            role=\"alert\"\n          >\n            {this.errorMessage}\n          </ds-text>\n        )}\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  AttachInternals,\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n  Watch,\n} from '@stencil/core';\nimport {\n  controlWidthClass,\n  CONTROL_SUPPORTING_TEXT_VARIANT,\n  CONTROL_TEXT_VARIANT,\n  DEFAULT_REQUIRED_MESSAGE,\n  setRequiredValidity,\n  type ControlWidth,\n} from '../../utils';\nimport { ChoiceFooter, ChoiceOptionRow, ChoiceSearch } from '../../utils/choice-list-parts';\nimport {\n  choiceBackgroundClassMap,\n  choiceListUsesIcons,\n  choiceListUsesSubtext,\n  enabledChoiceIndexes,\n  filterChoiceSections,\n  flattenChoiceSections,\n  resolveChoiceSections,\n  type ChoiceBackground,\n  type ChoiceOption,\n  type ChoiceSection,\n} from '../../utils/choice-list';\nimport { SelectController } from '../../utils/select-controller';\n\nexport type SelectOption = ChoiceOption;\nexport type SelectSection = ChoiceSection;\nexport type SelectBackground = ChoiceBackground;\nexport type SelectSize = 'lg' | 'md' | 'sm' | 'xs';\nexport type SelectWidth = ControlWidth;\n\nconst ICON_SIZE: Record<SelectSize, 'lg' | 'md' | 'sm' | 'xs'> = {\n  lg: 'lg',\n  md: 'md',\n  sm: 'sm',\n  xs: 'xs',\n};\n\nlet selectId = 0;\n\n@Component({\n  tag: 'ds-select',\n  styleUrl: 'Select.css',\n  scoped: true,\n  formAssociated: true,\n})\nexport class Select {\n  @Element() el!: HTMLElement;\n  @AttachInternals() internals!: ElementInternals;\n\n  /** Flat choices. Assign arrays through the JavaScript property. */\n  @Prop() options: SelectOption[] = [];\n  /** Grouped choices; takes precedence over options. Assign through JavaScript. */\n  @Prop() sections: SelectSection[] = [];\n  /** Selected string value. Unknown values render the placeholder and are not submitted. */\n  @Prop({ mutable: true }) value: string = '';\n  /** Controlled popup visibility. */\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n  /** Native form field name. */\n  @Prop({ reflect: true }) name: string | undefined;\n  /** Native disabled state. */\n  @Prop({ reflect: true }) disabled: boolean = false;\n  /** Require one valid selected value. */\n  @Prop({ reflect: true }) required: boolean = false;\n  /** Validation message used when required is missing. */\n  @Prop() requiredMessage: string = DEFAULT_REQUIRED_MESSAGE;\n  /** Trigger text shown when no valid value is selected. */\n  @Prop() placeholder: string = 'Select';\n  /** Control density. */\n  @Prop() size: SelectSize = 'md';\n  /** Width fit — hug content (default) or fill the parent. */\n  @Prop() width: SelectWidth = 'hug';\n  /** Shared inactive treatment; removes interaction and form submission. */\n  @Prop() isInactive: boolean = false;\n  /** Replace the prefix with a loader and disable option interaction. */\n  @Prop() isLoading: boolean = false;\n  /** Show the selected interaction fill when a valid value exists. */\n  @Prop() activeFill: boolean = true;\n  /** Show the surface-aware inset border. */\n  @Prop() hasBorder: boolean = true;\n  /** Optional trigger prefix icon name. */\n  @Prop() icon: string | undefined;\n  /** Show the clear footer action when a value exists. */\n  @Prop() allowClear: boolean = true;\n  /** Localized clear action label. */\n  @Prop() clearLabel: string = 'Clear';\n  /** Show immediate local filtering over option labels, subtext, and section headings. */\n  @Prop() searchable: boolean = false;\n  /** Localized search-field placeholder and accessible name. */\n  @Prop() searchPlaceholder: string = 'Search';\n  /** Localized empty-filter result text. */\n  @Prop() noResultsText: string = 'No results found';\n  /** Accessible loading status label. */\n  @Prop() loadingLabel: string = 'Loading';\n  /** Actual parent surface context; omit on primary and secondary surfaces. */\n  @Prop() background: SelectBackground | undefined;\n  /** Show invalid visual state. */\n  @Prop() error: boolean = false;\n  /** Error text rendered below the trigger when error is true. */\n  @Prop() errorMessage: string | undefined;\n  /** ID applied to the internal combobox trigger for external labels. */\n  @Prop() inputId: string | undefined;\n  /** Direct accessible name when no external label is available. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  /** IDs of elements that label the combobox. */\n  @Prop({ attribute: 'aria-labelledby' }) ariaLabelledby: string | undefined;\n  /** Additional IDs that describe the combobox. */\n  @Prop({ attribute: 'aria-describedby' }) ariaDescribedby: string | undefined;\n\n  /** Emitted after user selection or clearing with the next scalar value. */\n  @Event() dsChange!: EventEmitter<string>;\n  /** Emitted after the footer clear action. */\n  @Event() dsClear!: EventEmitter<void>;\n  /** Emitted whenever popup visibility changes. */\n  @Event() dsOpenChange!: EventEmitter<boolean>;\n\n  @State() private activeIndex = -1;\n  @State() private searchTerm = '';\n  @State() private formDisabled = false;\n  @State() private position = { x: 0, y: 0 };\n  @State() private positionReady = false;\n  @State() private focusRingVisible = false;\n\n  private readonly generatedId = `ds-select-${++selectId}`;\n  private readonly listboxId = `${this.generatedId}-listbox`;\n  private readonly errorId = `${this.generatedId}-error`;\n  private initialValue = '';\n  private readonly controller = this.createController();\n\n  private createController() {\n    // eslint-disable-next-line @typescript-eslint/no-this-alias -- adapter getters preserve reactive component ownership without inheritance.\n    const owner = this;\n    return new SelectController<SelectOption>({\n      get host() { return owner.el; },\n      generatedId: owner.generatedId,\n      get options() { return owner.visibleOptions; },\n      get searchable() { return owner.searchable; },\n      get isLoading() { return owner.isLoading; },\n      get isDisabled() { return owner.isDisabled; },\n      get preferredIndex() {\n        return owner.visibleOptions.findIndex(\n          option => option.value === owner.value && !option.isInactive,\n        );\n      },\n      get open() { return owner.open; },\n      set open(value) { owner.open = value; },\n      get activeIndex() { return owner.activeIndex; },\n      set activeIndex(value) { owner.activeIndex = value; },\n      get searchTerm() { return owner.searchTerm; },\n      set searchTerm(value) { owner.searchTerm = value; },\n      get focusRingVisible() { return owner.focusRingVisible; },\n      set focusRingVisible(value) { owner.focusRingVisible = value; },\n      get position() { return owner.position; },\n      set position(value) { owner.position = value; },\n      get positionReady() { return owner.positionReady; },\n      set positionReady(value) { owner.positionReady = value; },\n      selectOption: option => owner.selectOption(option),\n    });\n  }\n\n  componentWillLoad() {\n    this.initialValue = this.value;\n    this.syncFormValue();\n  }\n\n  componentDidLoad() {\n    this.controller.connect();\n  }\n\n  disconnectedCallback() {\n    this.controller.disconnect();\n  }\n\n  @Watch('value')\n  @Watch('disabled')\n  @Watch('isInactive')\n  @Watch('required')\n  @Watch('options')\n  @Watch('sections')\n  syncFormValue() {\n    const inactive = this.isDisabled;\n    const resolvedValue = this.hasSelection ? this.value : '';\n    this.internals.setFormValue(inactive ? null : resolvedValue);\n    const missing = this.required && !inactive && !resolvedValue;\n    setRequiredValidity(this.internals, missing, this.requiredMessage);\n    this.controller.optionsChanged();\n  }\n\n  @Watch('isLoading')\n  onLoadingChange() {\n    this.controller.loadingChanged();\n  }\n\n  @Watch('open')\n  onOpenChange(open: boolean) {\n    this.dsOpenChange.emit(open);\n    this.controller.openChanged(open);\n  }\n\n  @Watch('searchTerm')\n  onSearchTermChange() {\n    this.controller.searchChanged();\n  }\n\n  @Watch('activeIndex')\n  onActiveIndexChange() {\n    this.controller.activeIndexChanged();\n  }\n\n  formDisabledCallback(disabled: boolean) {\n    this.formDisabled = disabled;\n    this.syncFormValue();\n  }\n\n  formResetCallback() {\n    this.value = this.initialValue;\n    this.closePopup();\n  }\n\n  formStateRestoreCallback(state: string | File | FormData | null) {\n    this.value = typeof state === 'string' ? state : '';\n  }\n\n  @Method()\n  async setFocus() {\n    this.controller.setFocus();\n  }\n\n  private get isDisabled(): boolean {\n    return this.disabled || this.isInactive || this.formDisabled;\n  }\n\n  private get allSections(): SelectSection[] {\n    return resolveChoiceSections(this.options, this.sections);\n  }\n\n  private get allOptions(): SelectOption[] {\n    return flattenChoiceSections(this.allSections);\n  }\n\n  private get visibleSections(): SelectSection[] {\n    return this.searchable\n      ? filterChoiceSections(this.allSections, this.searchTerm)\n      : this.allSections;\n  }\n\n  private get visibleOptions(): SelectOption[] {\n    return flattenChoiceSections(this.visibleSections);\n  }\n\n  private get selectedOption(): SelectOption | undefined {\n    return this.allOptions.find(option => option.value === this.value);\n  }\n\n  private get hasSelection(): boolean {\n    return Boolean(this.selectedOption);\n  }\n\n  private get activeOptionId(): string | undefined {\n    return this.controller.activeOptionId;\n  }\n\n  private closePopup(restoreFocus = false) {\n    this.controller.closePopup(restoreFocus);\n  }\n\n  private openPopup(focusVisible: boolean, edge?: 'first' | 'last') {\n    this.controller.openPopup(focusVisible, edge);\n  }\n\n  private selectOption(option: SelectOption) {\n    if (option.isInactive || this.isLoading) return;\n    this.value = option.value;\n    this.dsChange.emit(this.value);\n    this.controller.closePopup(true);\n  }\n\n  private clearSelection = (event: Event) => {\n    event.preventDefault();\n    event.stopPropagation();\n    this.value = '';\n    this.dsChange.emit('');\n    this.dsClear.emit();\n    const enabled = enabledChoiceIndexes(this.visibleOptions);\n    this.activeIndex = enabled[0] ?? -1;\n    this.controller.focusSearchOrTrigger();\n  };\n\n  private readonly handleListKeyDown = this.controller.handleListKeyDown;\n  private readonly handleTriggerKeyDown = this.controller.handleTriggerKeyDown;\n\n  private renderOption(\n    option: SelectOption,\n    index: number,\n    usesIcons: boolean,\n    usesSubtext: boolean,\n  ) {\n    const selected = option.value === this.value;\n    const active = index === this.activeIndex;\n    return (\n      <ChoiceOptionRow\n        size={this.size}\n        id={`${this.generatedId}-option-${index}`}\n        option={option}\n        selected={selected}\n        active={active}\n        focusRingVisible={this.focusRingVisible}\n        usesSubtext={usesSubtext}\n        leading={usesIcons && option.icon ? (\n          <span class=\"ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\" aria-hidden=\"true\">\n            <ds-icon name={option.icon} size={this.size} color=\"inherit\" />\n          </span>\n        ) : undefined}\n        onHover={() => {\n            this.focusRingVisible = false;\n            this.activeIndex = index;\n        }}\n        onSelect={() => this.selectOption(option)}\n      />\n    );\n  }\n\n  render() {\n    const inactive = this.isDisabled;\n    const showPlaceholder = !this.hasSelection;\n    const label = showPlaceholder ? this.placeholder : this.selectedOption?.label;\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const iconSize = ICON_SIZE[this.size];\n    const usesOptionIcons = choiceListUsesIcons(this.allOptions);\n    const usesOptionSubtext = choiceListUsesSubtext(this.allOptions);\n    const showError = this.error && Boolean(this.errorMessage);\n    const describedBy = [this.ariaDescribedby, showError ? this.errorId : undefined]\n      .filter(Boolean)\n      .join(' ') || undefined;\n    const popupStyle = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.position.x)}px, ${Math.round(this.position.y)}px)`,\n      zIndex: 'var(--dimension-z-index-floating)',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n    let flatIndex = 0;\n\n    return (\n      <Host\n        class={{\n          'select-host': true,\n          'ds-field-stack': true,\n          'ds-control-inactive': inactive,\n          [`ds-control--${this.size}`]: true,\n          ...controlWidthClass(this.width),\n          [`select-host--background-${this.background}`]: !!this.background,\n        }}\n      >\n        <button\n          ref={element => {\n            this.controller.setTriggerElement((element as HTMLButtonElement) ?? null);\n          }}\n          id={this.inputId ?? this.generatedId}\n          type=\"button\"\n          class={{\n            trigger: true,\n            'ds-control-frame': true,\n            'ds-focus-ring-inset': true,\n            'ds-interaction-fill': true,\n            'ds-interaction-fill--selected':\n              !inactive && this.activeFill && this.hasSelection,\n            'trigger--bordered': this.hasBorder || this.error,\n            'trigger--placeholder': showPlaceholder,\n            'trigger--has-value': this.hasSelection,\n            'wrapper--error': this.error,\n            [`ds-control--${this.size}`]: true,\n            ...choiceBackgroundClassMap(this.background),\n          }}\n          disabled={inactive}\n          role=\"combobox\"\n          aria-haspopup=\"listbox\"\n          aria-expanded={String(this.open)}\n          aria-controls={this.open ? this.listboxId : undefined}\n          aria-activedescendant={this.open && !this.searchable ? this.activeOptionId : undefined}\n          aria-label={this.ariaLabel}\n          aria-labelledby={this.ariaLabelledby}\n          aria-describedby={describedBy}\n          aria-invalid={this.error ? 'true' : undefined}\n          aria-required={this.required || undefined}\n          aria-busy={this.isLoading ? 'true' : undefined}\n          onClick={() => (this.open ? this.closePopup() : this.openPopup(false))}\n          onKeyDown={this.handleTriggerKeyDown}\n        >\n          {(this.icon || this.isLoading) && (\n            <span class=\"trigger__prefix ds-control-icon-box ds-interaction-fill__content\" aria-hidden=\"true\">\n              {this.isLoading ? (\n                <ds-loader size={iconSize} color=\"inherit\" />\n              ) : (\n                <ds-icon name={this.icon} size={iconSize} color=\"inherit\" />\n              )}\n            </span>\n          )}\n          <ds-text\n            class=\"trigger__label ds-control-label-box ds-interaction-fill__content\"\n            as=\"span\"\n            variant={textVariant}\n            color=\"inherit\"\n            lineTruncation={1}\n          >\n            {label}\n          </ds-text>\n          <span class=\"trigger__chevron ds-control-icon-box ds-interaction-fill__content\" aria-hidden=\"true\">\n            <ds-icon name=\"ChevronDown\" size={iconSize} color=\"inherit\" />\n          </span>\n        </button>\n\n        {this.open && (\n          <div\n            ref={element => {\n              this.controller.setPopupElement((element as HTMLDivElement) ?? null);\n            }}\n            class=\"select-popup ds-choice-popup\"\n            style={popupStyle}\n          >\n            {this.searchable && (\n              <ChoiceSearch\n                size={this.size}\n                value={this.searchTerm}\n                placeholder={this.searchPlaceholder}\n                controls={this.listboxId}\n                activeDescendant={this.activeOptionId}\n                inputRef={this.controller.setSearchElement}\n                clearLabel={this.clearLabel}\n                onValueChange={value => {\n                  this.searchTerm = value;\n                }}\n                onKeyDown={event => this.handleListKeyDown(event)}\n              />\n            )}\n            <div\n              id={this.listboxId}\n              class=\"ds-choice-list\"\n              role=\"listbox\"\n              aria-label={this.ariaLabel ?? this.placeholder}\n              aria-busy={this.isLoading ? 'true' : undefined}\n            >\n              {this.isLoading ? (\n                <div\n                  class=\"ds-choice-loading\"\n                  role=\"option\"\n                  aria-selected=\"false\"\n                  aria-disabled=\"true\"\n                  aria-label={this.loadingLabel}\n                  aria-live=\"polite\"\n                >\n                  <ds-loader size={this.size} color=\"inherit\" />\n                </div>\n              ) : this.visibleOptions.length === 0 ? (\n                <div\n                  class=\"ds-choice-empty ds-empty-region\"\n                  role=\"option\"\n                  aria-selected=\"false\"\n                  aria-disabled=\"true\"\n                  aria-label={this.noResultsText}\n                  aria-live=\"polite\"\n                >\n                  <ds-empty-state body={this.noResultsText} />\n                </div>\n              ) : (\n                this.visibleSections.map(section => (\n                  <div\n                    class={{\n                      'ds-choice-section': true,\n                      'ds-chrome-column': true,\n                      'ds-chrome-space--sm': true,\n                      'ds-choice-section--divided': !!section.divider,\n                    }}\n                    role={section.header ? 'group' : undefined}\n                    aria-label={section.header}\n                  >\n                    {section.header && (\n                      <ds-text\n                        class={`ds-choice-section__header 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                        {section.header}\n                      </ds-text>\n                    )}\n                    {section.options.map(option => this.renderOption(\n                      option,\n                      flatIndex++,\n                      usesOptionIcons,\n                      usesOptionSubtext,\n                    ))}\n                  </div>\n                ))\n              )}\n            </div>\n            {this.allowClear && this.hasSelection && !this.isLoading && (\n              <ChoiceFooter size={this.size} clearLabel={this.clearLabel} onClear={this.clearSelection} />\n            )}\n          </div>\n        )}\n\n        {showError && (\n          <ds-text\n            class=\"error-text\"\n            as=\"div\"\n            variant=\"text-body-small\"\n            color=\"negative\"\n            textId={this.errorId}\n            role=\"alert\"\n          >\n            {this.errorMessage}\n          </ds-text>\n        )}\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/shell-app.json

@@ -66,6 +66,7 @@
         "On desktop, PanelNav defaults expanded, permits user collapse or expansion, and respects the locally persisted desktop preference.",
         "On tablet, ShellApp keeps PanelNav permanently collapsed and prevents user expansion without overwriting the desktop preference.",
         "On mobile, ShellApp hides and inerts PanelNav and BarNav, uses a solid primary stage, and composes routed ShellPage MobileHeader presentations, MobileSheetNav, ShellTools, and the persistent five-item MobileBarNav.",
+        "When the application enables viewport-fit=cover, ShellApp reserves the shared top safe-area inset once for the complete mobile stage; nested routed, sheet, and tool headers must not add a second top inset.",
         "Mobile global surfaces conceal and inert the routed workspace without unmounting it, preserving nested routes and scroll state.",
         "Keep PanelNav width, BarNav height, PanelTools chrome, and main-content origin stable except during intentional responsive or collapse transitions.",
         "The bottom bar remains visible at all route and tool depths in the foundation release."
@@ -246,7 +247,7 @@
       },
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/tokens ^5.0.0",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
@@ -261,7 +262,7 @@
   "files": [
     {
       "path": "src/wc/components/ShellApp/ShellApp.css",
-      "content": ":host {\n  display: block;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  --ds-shell-panel-tools-width: var(--dimension-panel-width-xs);\n}\n\n.shell-app {\n  display: flex;\n  flex-direction: column;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  font-family: var(--typography-font-family, system-ui);\n}\n\n:host {\n  --_shell-chrome-bg: var(--color-background-secondary);\n}\n\n.shell-app__row {\n  display: flex;\n  flex: 1 1 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n}\n\n/*\n * One chrome layer behind the shell row. Wash uses background-attachment: fixed\n * so the pattern is locked to the viewport — panel/tools collapse only changes the\n * transparent window, not the pattern phase. JS sets wash background-size from\n * readShellViewportDimensions(), not the shell element box.\n */\n.shell-app__chrome {\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  z-index: 0;\n  background-color: var(--_shell-chrome-bg);\n}\n\n:host(.shell-app--gradient) .shell-app__chrome::before {\n  content: '';\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  background-position: 0 0;\n  background-attachment: fixed;\n  z-index: 1;\n  opacity: var(--ds-shell-gradient-opacity, 1);\n  background-image: var(--ds-shell-gradient-image, none);\n  background-size: var(--ds-shell-gradient-size, auto);\n  background-repeat: no-repeat;\n}\n\n.shell-app__panel {\n  flex: 0 0 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n  /* Above main so resize handle line can paint over the workspace edge */\n  z-index: 2;\n}\n\n.shell-app__panel ::slotted(ds-panel-nav) {\n  display: block;\n  height: 100%;\n}\n\n.shell-app__main {\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  display: grid;\n  grid-template-columns: minmax(0, 1fr) auto;\n  grid-template-rows: auto minmax(0, 1fr);\n  grid-template-areas:\n    'bar tools'\n    'content tools';\n  position: relative;\n  z-index: 1;\n}\n\n.shell-app__mobile-sheet-nav,\n.shell-app__mobile-bar-nav {\n  display: none;\n}\n\n.shell-app__bar {\n  grid-area: bar;\n  flex: 0 0 auto;\n  min-width: 0;\n}\n\n.shell-app__bar ::slotted(ds-bar-nav) {\n  display: block;\n}\n\n.shell-app__content {\n  grid-area: content;\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  overflow: auto;\n  overscroll-behavior: none;\n  /* Limit reflow to the page column — not on __main (breaks tools flex shrink). */\n  contain: layout;\n}\n\n/* Opaque page surface — masks the fixed chrome layer in the content column. */\n.shell-app__content {\n  position: relative;\n  z-index: 1;\n  background-color: var(--color-background-primary);\n}\n\n.shell-app__tools {\n  grid-area: tools;\n  flex: 0 0 auto;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  display: flex;\n  position: relative;\n  z-index: 0;\n  overflow: hidden;\n}\n\n.shell-app__tools ::slotted(ds-panel-tools) {\n  display: block;\n  height: 100%;\n  min-height: 0;\n}\n\n.shell-app__tools ::slotted(ds-shell-tools) {\n  display: block;\n  height: 100%;\n  min-height: 0;\n}\n\n:host(.shell-app--tools-fullscreen) .shell-app__panel,\n:host(.shell-app--tools-fullscreen) .shell-app__bar,\n:host(.shell-app--tools-fullscreen) .shell-app__content {\n  visibility: hidden;\n}\n\n:host(.shell-app--mobile) {\n  --_shell-chrome-bg: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__chrome,\n:host(.shell-app--mobile) .shell-app__panel,\n:host(.shell-app--mobile) .shell-app__bar {\n  display: none;\n}\n\n:host(.shell-app--mobile) .shell-app__main {\n  width: 100%;\n  grid-template-columns: minmax(0, 1fr);\n  grid-template-rows: minmax(0, 1fr) auto;\n  grid-template-areas:\n    'stage'\n    'mobile-bar-nav';\n  background: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__content,\n:host(.shell-app--mobile) .shell-app__tools,\n:host(.shell-app--mobile) .shell-app__mobile-sheet-nav {\n  grid-area: stage;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n}\n\n:host(.shell-app--mobile) .shell-app__content {\n  z-index: 1;\n  overflow: auto;\n}\n\n:host(.shell-app--mobile) .shell-app__tools {\n  z-index: 2;\n  width: 100%;\n  overflow: hidden;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__mobile-sheet-nav {\n  display: block;\n  z-index: 3;\n  overflow: hidden;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__mobile-bar-nav {\n  grid-area: mobile-bar-nav;\n  display: block;\n  min-width: 0;\n  position: relative;\n  z-index: 4;\n}\n\n:host(.shell-app--mobile) .shell-app__tools[hidden],\n:host(.shell-app--mobile) .shell-app__mobile-sheet-nav[hidden],\n:host(.shell-app--mobile) .shell-app__mobile-bar-nav[hidden] {\n  display: none;\n}\n\n:host(.shell-app--mobile-tool-active) .shell-app__content,\n:host(.shell-app--mobile-sheet-nav-open) .shell-app__content,\n:host(.shell-app--mobile-sheet-nav-open) .shell-app__tools {\n  visibility: hidden;\n}\n",
+      "content": ":host {\n  display: block;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  --ds-shell-panel-tools-width: var(--dimension-panel-width-xs);\n}\n\n.shell-app {\n  display: flex;\n  flex-direction: column;\n  height: 100%;\n  min-height: 0;\n  box-sizing: border-box;\n  overflow: hidden;\n  overscroll-behavior: none;\n  font-family: var(--typography-font-family, system-ui);\n}\n\n:host {\n  --_shell-chrome-bg: var(--color-background-secondary);\n}\n\n.shell-app__row {\n  display: flex;\n  flex: 1 1 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n}\n\n/*\n * One chrome layer behind the shell row. Wash uses background-attachment: fixed\n * so the pattern is locked to the viewport — panel/tools collapse only changes the\n * transparent window, not the pattern phase. JS sets wash background-size from\n * readShellViewportDimensions(), not the shell element box.\n */\n.shell-app__chrome {\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  z-index: 0;\n  background-color: var(--_shell-chrome-bg);\n}\n\n:host(.shell-app--gradient) .shell-app__chrome::before {\n  content: '';\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  background-position: 0 0;\n  background-attachment: fixed;\n  z-index: 1;\n  opacity: var(--ds-shell-gradient-opacity, 1);\n  background-image: var(--ds-shell-gradient-image, none);\n  background-size: var(--ds-shell-gradient-size, auto);\n  background-repeat: no-repeat;\n}\n\n.shell-app__panel {\n  flex: 0 0 auto;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n  /* Above main so resize handle line can paint over the workspace edge */\n  z-index: 2;\n}\n\n.shell-app__panel ::slotted(ds-panel-nav) {\n  display: block;\n  height: 100%;\n}\n\n.shell-app__main {\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  display: grid;\n  grid-template-columns: minmax(0, 1fr) auto;\n  grid-template-rows: auto minmax(0, 1fr);\n  grid-template-areas:\n    'bar tools'\n    'content tools';\n  position: relative;\n  z-index: 1;\n}\n\n.shell-app__mobile-sheet-nav,\n.shell-app__mobile-bar-nav {\n  display: none;\n}\n\n.shell-app__bar {\n  grid-area: bar;\n  flex: 0 0 auto;\n  min-width: 0;\n}\n\n.shell-app__bar ::slotted(ds-bar-nav) {\n  display: block;\n}\n\n.shell-app__content {\n  grid-area: content;\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: 0;\n  overflow: auto;\n  overscroll-behavior: none;\n  /* Limit reflow to the page column — not on __main (breaks tools flex shrink). */\n  contain: layout;\n}\n\n/* Opaque page surface — masks the fixed chrome layer in the content column. */\n.shell-app__content {\n  position: relative;\n  z-index: 1;\n  background-color: var(--color-background-primary);\n}\n\n.shell-app__tools {\n  grid-area: tools;\n  flex: 0 0 auto;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  display: flex;\n  position: relative;\n  z-index: 0;\n  overflow: hidden;\n}\n\n.shell-app__tools ::slotted(ds-panel-tools) {\n  display: block;\n  height: 100%;\n  min-height: 0;\n}\n\n.shell-app__tools ::slotted(ds-shell-tools) {\n  display: block;\n  height: 100%;\n  min-height: 0;\n}\n\n:host(.shell-app--tools-fullscreen) .shell-app__panel,\n:host(.shell-app--tools-fullscreen) .shell-app__bar,\n:host(.shell-app--tools-fullscreen) .shell-app__content {\n  visibility: hidden;\n}\n\n:host(.shell-app--mobile) {\n  --_shell-chrome-bg: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__chrome,\n:host(.shell-app--mobile) .shell-app__panel,\n:host(.shell-app--mobile) .shell-app__bar {\n  display: none;\n}\n\n:host(.shell-app--mobile) .shell-app__main {\n  width: 100%;\n  padding-block-start: env(safe-area-inset-top);\n  box-sizing: border-box;\n  grid-template-columns: minmax(0, 1fr);\n  grid-template-rows: minmax(0, 1fr) auto;\n  grid-template-areas:\n    'stage'\n    'mobile-bar-nav';\n  background: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__content,\n:host(.shell-app--mobile) .shell-app__tools,\n:host(.shell-app--mobile) .shell-app__mobile-sheet-nav {\n  grid-area: stage;\n  min-width: 0;\n  min-height: 0;\n  height: 100%;\n  position: relative;\n}\n\n:host(.shell-app--mobile) .shell-app__content {\n  z-index: 1;\n  overflow: auto;\n}\n\n:host(.shell-app--mobile) .shell-app__tools {\n  z-index: 2;\n  width: 100%;\n  overflow: hidden;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__mobile-sheet-nav {\n  display: block;\n  z-index: 3;\n  overflow: hidden;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-app--mobile) .shell-app__mobile-bar-nav {\n  grid-area: mobile-bar-nav;\n  display: block;\n  min-width: 0;\n  position: relative;\n  z-index: 4;\n}\n\n:host(.shell-app--mobile) .shell-app__tools[hidden],\n:host(.shell-app--mobile) .shell-app__mobile-sheet-nav[hidden],\n:host(.shell-app--mobile) .shell-app__mobile-bar-nav[hidden] {\n  display: none;\n}\n\n:host(.shell-app--mobile-tool-active) .shell-app__content,\n:host(.shell-app--mobile-sheet-nav-open) .shell-app__content,\n:host(.shell-app--mobile-sheet-nav-open) .shell-app__tools {\n  visibility: hidden;\n}\n",
       "type": "registry:ui"
     },
     {

package/dist/mcp-data/registry/shell-gradient-picker.json

@@ -166,7 +166,7 @@
       },
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/tokens ^5.0.0",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."

package/dist/mcp-data/registry/shell-gradient-swatch.json

@@ -183,7 +183,7 @@
       },
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/tokens ^5.0.0",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."

package/dist/mcp-data/registry/shell-page.json

@@ -65,7 +65,8 @@
         "A ShellPage-managed BarTitle remains concealed until headerCapacity is available and its rendered variant matches the resolved presentation, preventing a default-variant flash during route activation.",
         "responsiveMode=mobile hides and inerts the desktop header, exposes mobile-header, and disables desktop scroll-compaction geometry.",
         "Update headerCapacity synchronously with shell layout state so opening tools or crossing application breakpoints cannot briefly render the wrong presentation.",
-        "On roomy pages, the expanded header scrolls upward until its title and action row reaches the compact row position, then snaps variants without moving that shared visual anchor.",
+        "The default content inset is 32px in desktop mode and 16px in tablet and mobile modes, while preserving the larger bottom scroll space.",
+        "On roomy pages, the expanded header scrolls upward until its title and action row reaches the compact row position, while its bottom divider progressively extends from the expanded inset to edge-to-edge; it then snaps variants without moving that shared visual anchor.",
         "Scroll compaction preserves the expanded page flow offset so content never jumps beneath the sticky header.",
         "ShellPage relies on ShellApp's content scroller and never introduces nested scrolling.",
         "BarWorkflow remains compact and is not assigned BarTitle's capacity or scroll variants."
@@ -203,7 +204,7 @@
       },
       "peerDependencies": {
         "required": [
-          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/tokens ^5.0.0",
           "@ds-mo/icons ^6.4.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
@@ -218,12 +219,12 @@
   "files": [
     {
       "path": "src/wc/components/ShellPage/ShellPage.css",
-      "content": ":host {\n  display: block;\n  position: relative;\n  min-width: 0;\n  min-height: 100%;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n.shell-page__scroll-sentinel {\n  position: absolute;\n  inset-block-start: var(--ds-shell-page-header-travel, 0);\n  inset-inline-start: 0;\n  width: var(--dimension-stroke-width-012);\n  height: var(--dimension-stroke-width-012);\n  pointer-events: none;\n}\n\n.shell-page__sticky-header {\n  position: sticky;\n  inset-block-start: var(--ds-shell-page-sticky-offset, 0);\n  z-index: var(--dimension-z-index-raised);\n  min-width: 0;\n  background: var(--color-background-primary);\n  overflow: visible;\n  overflow-anchor: none;\n}\n\n.shell-page__desktop-header ::slotted(ds-bar-title),\n.shell-page__desktop-header ::slotted(ds-bar-workflow),\n.shell-page__mobile-header ::slotted(ds-mobile-header) {\n  display: block;\n  min-width: 0;\n}\n\n.shell-page__desktop-header[hidden],\n.shell-page__mobile-header[hidden] {\n  display: none;\n}\n\n:host(.shell-page-host--mobile) .shell-page__scroll-sentinel,\n:host(.shell-page-host--mobile) .shell-page__flow-spacer {\n  display: none;\n}\n\n.shell-page__flow-spacer {\n  height: var(--ds-shell-page-flow-spacer, 0);\n  background: var(--color-background-primary);\n}\n\n.shell-page__content {\n  min-width: 0;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-page-host--inset-default) .shell-page__content {\n  padding: var(--dimension-space-400) var(--dimension-space-400) var(--dimension-space-800);\n}\n\n:host(.shell-page-host--inset-none) .shell-page__content {\n  padding: 0;\n}\n",
+      "content": ":host {\n  display: block;\n  position: relative;\n  min-width: 0;\n  min-height: 100%;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n.shell-page__scroll-sentinel {\n  position: absolute;\n  inset-block-start: var(--ds-shell-page-header-travel, 0);\n  inset-inline-start: 0;\n  width: var(--dimension-stroke-width-012);\n  height: var(--dimension-stroke-width-012);\n  pointer-events: none;\n}\n\n.shell-page__sticky-header {\n  position: sticky;\n  inset-block-start: var(--ds-shell-page-sticky-offset, 0);\n  z-index: var(--dimension-z-index-raised);\n  min-width: 0;\n  background: var(--color-background-primary);\n  overflow: visible;\n  overflow-anchor: none;\n}\n\n.shell-page__desktop-header ::slotted(ds-bar-title),\n.shell-page__desktop-header ::slotted(ds-bar-workflow),\n.shell-page__mobile-header ::slotted(ds-mobile-header) {\n  display: block;\n  min-width: 0;\n}\n\n.shell-page__desktop-header[hidden],\n.shell-page__mobile-header[hidden] {\n  display: none;\n}\n\n:host(.shell-page-host--mobile) .shell-page__scroll-sentinel,\n:host(.shell-page-host--mobile) .shell-page__flow-spacer {\n  display: none;\n}\n\n.shell-page__flow-spacer {\n  height: var(--ds-shell-page-flow-spacer, 0);\n  background: var(--color-background-primary);\n}\n\n.shell-page__content {\n  min-width: 0;\n  box-sizing: border-box;\n  background: var(--color-background-primary);\n}\n\n:host(.shell-page-host--inset-default) .shell-page__content {\n  padding: var(--dimension-space-400) var(--dimension-space-400) var(--dimension-space-800);\n}\n\n:host(.shell-page-host--inset-default[responsive-mode='tablet']) .shell-page__content,\n:host(.shell-page-host--inset-default[responsive-mode='mobile']) .shell-page__content {\n  padding: var(--dimension-space-200) var(--dimension-space-200) var(--dimension-space-800);\n}\n\n:host(.shell-page-host--inset-none) .shell-page__content {\n  padding: 0;\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/ShellPage/ShellPage.tsx",
-      "content": "import { Component, Element, h, Host, Prop, State, Watch } from '@stencil/core';\nimport type { ShellResponsiveMode } from '../../shell/shell-responsive';\nimport { resolveCssLengthPx } from '../../utils/resolve-css-length-px';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\nimport { resolveShellPageHeaderVariant } from './shell-page-responsive';\nimport type {\n  ShellPageCapacity,\n  ShellPageContentInset,\n  ShellPageHeaderPresentation,\n} from './shell-page-types';\n\ntype BarTitleElement = HTMLElement & { variant: BarTitleVariant };\n\n@Component({\n  tag: 'ds-shell-page',\n  styleUrl: 'ShellPage.css',\n  scoped: true,\n})\nexport class ShellPage {\n  private static readonly MAX_HEADER_REVEAL_FRAMES = 12;\n  private static readonly MAX_HEADER_GEOMETRY_FRAMES = 12;\n\n  @Element() el!: HTMLElement;\n\n  /** Automatic capacity/scroll behavior, or an explicit header variant override. */\n  @Prop() headerPresentation: ShellPageHeaderPresentation = 'auto';\n\n  /** Available page-header capacity supplied by the owning application shell. */\n  @Prop() headerCapacity?: ShellPageCapacity;\n\n  /** Standard page gutters, or no inset for full-bleed page content. */\n  @Prop() contentInset: ShellPageContentInset = 'default';\n\n  /** Explicit shell breakpoint presentation. Mobile uses the dedicated mobile-header slot. */\n  @Prop({ attribute: 'responsive-mode', reflect: true })\n  responsiveMode: ShellResponsiveMode = 'desktop';\n\n  @State() private pageTopVisible = true;\n\n  private sentinelEl: HTMLElement | null = null;\n  private spacerEl: HTMLElement | null = null;\n  private stickyHeaderEl: HTMLElement | null = null;\n  private headerEl: BarTitleElement | null = null;\n  private expandedHeaderHeight = 0;\n  private headerTravel = 0;\n  private expandedGeometryFrozen = false;\n  private headerResizeObserver: ResizeObserver | null = null;\n  private headerMutationObserver: MutationObserver | null = null;\n  private headerRevealFrame: number | null = null;\n  private headerGeometryFrame: number | null = null;\n  private scrollRoot: HTMLElement | Window | null = null;\n\n  @Watch('headerCapacity')\n  @Watch('headerPresentation')\n  handleHeaderContractChange() {\n    this.syncHeaderVariant(true);\n  }\n\n  @Watch('responsiveMode')\n  handleResponsiveModeChange() {\n    this.observeHeader(this.responsiveMode === 'mobile' ? null : this.findHeader());\n  }\n\n  componentDidLoad() {\n    this.observeHeader(this.responsiveMode === 'mobile' ? null : this.findHeader());\n    this.connectScrollRoot();\n  }\n\n  componentDidRender() {\n    this.syncHeaderVariant();\n  }\n\n  disconnectedCallback() {\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = null;\n  }\n\n  private get effectiveVariant(): BarTitleVariant {\n    return resolveShellPageHeaderVariant(\n      this.headerPresentation,\n      this.headerCapacity ?? 'roomy',\n      this.pageTopVisible\n    );\n  }\n\n  private get headerContractResolved(): boolean {\n    return this.headerPresentation !== 'auto' || this.headerCapacity !== undefined;\n  }\n\n  private get isScrollCompacted(): boolean {\n    return (\n      this.headerPresentation === 'auto' && this.headerCapacity === 'roomy' && !this.pageTopVisible\n    );\n  }\n\n  private composedParent(element: Element): Element | null {\n    return (element as HTMLElement).assignedSlot?.parentElement ?? element.parentElement;\n  }\n\n  private findScrollRoot(): HTMLElement | Window {\n    let ancestor = this.composedParent(this.el);\n    while (ancestor && ancestor !== document.documentElement) {\n      const overflow = getComputedStyle(ancestor).overflowY;\n      if (overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay') {\n        return ancestor as HTMLElement;\n      }\n      ancestor = this.composedParent(ancestor);\n    }\n    return window;\n  }\n\n  private connectScrollRoot() {\n    const next = this.findScrollRoot();\n    if (next === this.scrollRoot) return;\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = next;\n    this.scrollRoot.addEventListener('scroll', this.handleScroll, { passive: true });\n    this.handleScroll();\n  }\n\n  private handleScroll = () => {\n    if (!this.sentinelEl || !this.scrollRoot) return;\n    const rootTop =\n      this.scrollRoot === window ? 0 : (this.scrollRoot as HTMLElement).getBoundingClientRect().top;\n    const nextPageTopVisible = this.sentinelEl.getBoundingClientRect().top >= rootTop;\n    if (\n      !nextPageTopVisible &&\n      this.pageTopVisible &&\n      this.headerEl?.classList.contains(this.variantClass('expanded'))\n    ) {\n      this.captureExpandedHeaderGeometry(this.headerEl);\n      this.expandedGeometryFrozen = true;\n    }\n    if (\n      nextPageTopVisible &&\n      this.expandedGeometryFrozen &&\n      this.el.getBoundingClientRect().top >= rootTop\n    ) {\n      this.expandedGeometryFrozen = false;\n      if (this.headerEl?.classList.contains(this.variantClass('expanded'))) {\n        this.captureExpandedHeaderGeometry(this.headerEl);\n      }\n    }\n    this.pageTopVisible = nextPageTopVisible;\n  };\n\n  private findHeader(): BarTitleElement | null {\n    return this.el.querySelector<BarTitleElement>('ds-bar-title');\n  }\n\n  private get compactHeaderHeight(): number {\n    return resolveCssLengthPx('--dimension-size-600', 0);\n  }\n\n  private setHeaderTravel(distance: number) {\n    const next = Math.max(0, distance);\n    if (Math.abs(next - this.headerTravel) < 0.5) return;\n    this.headerTravel = next;\n    this.el.style.setProperty('--ds-shell-page-header-travel', `${next}px`);\n    this.handleScroll();\n  }\n\n  private measureHeaderTravel(header: BarTitleElement) {\n    const anchor = header.querySelector<HTMLElement>('[data-shell-page-header-anchor]');\n    const compactHeight = this.compactHeaderHeight;\n    if (!anchor || compactHeight <= 0) return;\n\n    const headerRect = header.getBoundingClientRect();\n    const anchorRect = anchor.getBoundingClientRect();\n    if (headerRect.height <= 0 || anchorRect.height <= 0) return;\n\n    const expandedAnchorTop = anchorRect.top - headerRect.top;\n    const compactAnchorTop = Math.max(0, (compactHeight - anchorRect.height) / 2);\n    this.setHeaderTravel(expandedAnchorTop - compactAnchorTop);\n  }\n\n  private captureExpandedHeaderGeometry(header: BarTitleElement) {\n    this.expandedHeaderHeight = header.getBoundingClientRect().height;\n    this.measureHeaderTravel(header);\n  }\n\n  private setSpacerHeight(height: number) {\n    if (!this.spacerEl) return;\n    this.spacerEl.style.setProperty('--ds-shell-page-flow-spacer', `${Math.max(0, height)}px`);\n  }\n\n  private variantClass(variant: BarTitleVariant): string {\n    return `bar-title-host--${variant}`;\n  }\n\n  private setStickyHeaderOffset(renderedVariant: BarTitleVariant) {\n    this.stickyHeaderEl?.style.setProperty(\n      '--ds-shell-page-sticky-offset',\n      renderedVariant === 'expanded' &&\n        this.headerPresentation === 'auto' &&\n        this.headerCapacity === 'roomy'\n        ? `${-this.headerTravel}px`\n        : '0px'\n    );\n  }\n\n  private syncRenderedHeaderGeometry(header: BarTitleElement) {\n    const renderedVariant = this.effectiveVariant;\n    if (!header.classList.contains(this.variantClass(renderedVariant))) return;\n\n    // Update both flow-preservation pieces before reading layout. Otherwise a\n    // reverse compact → expanded render can briefly contain the tall header and\n    // the compact spacer together, giving browser scroll anchoring a transient\n    // height change to compensate.\n    this.setSpacerHeight(\n      this.isScrollCompacted ? this.expandedHeaderHeight - this.compactHeaderHeight : 0\n    );\n    this.setStickyHeaderOffset(renderedVariant);\n\n    if (renderedVariant === 'expanded' && !this.expandedGeometryFrozen) {\n      this.captureExpandedHeaderGeometry(header);\n      this.setStickyHeaderOffset(renderedVariant);\n    }\n  }\n\n  private cancelHeaderGeometrySync() {\n    if (this.headerGeometryFrame !== null) cancelAnimationFrame(this.headerGeometryFrame);\n    this.headerGeometryFrame = null;\n  }\n\n  private scheduleHeaderGeometrySync(header: BarTitleElement) {\n    this.cancelHeaderGeometrySync();\n    let framesRemaining = ShellPage.MAX_HEADER_GEOMETRY_FRAMES;\n    let framesElapsed = 0;\n    const sync = () => {\n      if (this.headerEl !== header) return;\n      framesRemaining -= 1;\n      framesElapsed += 1;\n      // In WebKit a child's componentDidLoad can precede its assignment into\n      // the parent's rendered slot. Revalidate after ShellApp has had a frame\n      // to expose the actual content scroller.\n      this.connectScrollRoot();\n      this.syncRenderedHeaderGeometry(header);\n      const geometryReady =\n        this.effectiveVariant !== 'expanded' ||\n        (this.expandedHeaderHeight > 0 && this.headerTravel > 0);\n      if ((geometryReady && framesElapsed >= 2) || framesRemaining <= 0) {\n        this.headerGeometryFrame = null;\n        return;\n      }\n      this.headerGeometryFrame = requestAnimationFrame(sync);\n    };\n    this.headerGeometryFrame = requestAnimationFrame(sync);\n  }\n\n  private cancelHeaderReveal() {\n    if (this.headerRevealFrame !== null) cancelAnimationFrame(this.headerRevealFrame);\n    this.headerRevealFrame = null;\n    this.headerEl?.removeAttribute('data-shell-page-syncing');\n  }\n\n  private revealHeaderWhenSynced(header: BarTitleElement, variant: BarTitleVariant) {\n    // Stencil normally re-renders within a frame or two of a prop change. Stop\n    // polling at the cap, but fail closed: a stale variant must never paint.\n    let framesRemaining = ShellPage.MAX_HEADER_REVEAL_FRAMES;\n    const reveal = () => {\n      if (this.headerEl !== header) {\n        header.removeAttribute('data-shell-page-syncing');\n        return;\n      }\n      framesRemaining -= 1;\n      if (header.classList.contains(this.variantClass(variant))) {\n        header.removeAttribute('data-shell-page-syncing');\n        this.headerRevealFrame = null;\n        return;\n      }\n      if (framesRemaining <= 0) {\n        this.headerRevealFrame = null;\n        return;\n      }\n      this.headerRevealFrame = requestAnimationFrame(reveal);\n    };\n    this.headerRevealFrame = requestAnimationFrame(reveal);\n  }\n\n  private syncHeaderVariant(concealUntilSynced = false) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    if (!this.headerContractResolved) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n      return;\n    }\n\n    const next = this.effectiveVariant;\n    const renderedVariantIsStale = !header.classList.contains(this.variantClass(next));\n    if (!renderedVariantIsStale) this.syncRenderedHeaderGeometry(header);\n    if (concealUntilSynced) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n    }\n    if (header.variant !== next) header.variant = next;\n    if (concealUntilSynced) {\n      this.revealHeaderWhenSynced(header, next);\n    }\n  }\n\n  private observeHeader(header: BarTitleElement | null) {\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.headerEl = header;\n    this.expandedHeaderHeight = 0;\n    this.expandedGeometryFrozen = false;\n    this.setHeaderTravel(0);\n    this.setSpacerHeight(0);\n    this.stickyHeaderEl?.style.setProperty('--ds-shell-page-sticky-offset', '0px');\n\n    if (!header) return;\n    if (header.classList.contains(this.variantClass('expanded'))) {\n      this.captureExpandedHeaderGeometry(header);\n    }\n    if (typeof ResizeObserver !== 'undefined') {\n      this.headerResizeObserver = new ResizeObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerResizeObserver.observe(header);\n    }\n    if (typeof MutationObserver !== 'undefined') {\n      this.headerMutationObserver = new MutationObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerMutationObserver.observe(header, {\n        attributes: true,\n        attributeFilter: ['class'],\n      });\n    }\n    this.syncHeaderVariant(true);\n    this.scheduleHeaderGeometrySync(header);\n  }\n\n  private handleHeaderSlotChange = (event: Event) => {\n    if (this.responsiveMode === 'mobile') return;\n    const slot = event.target as HTMLSlotElement;\n    const header = slot\n      .assignedElements()\n      .find(element => element.tagName.toLowerCase() === 'ds-bar-title');\n    this.observeHeader((header as BarTitleElement | undefined) ?? null);\n  };\n\n  render() {\n    const mobile = this.responsiveMode === 'mobile';\n    return (\n      <Host\n        role=\"main\"\n        class={{\n          'shell-page-host--inset-default': this.contentInset === 'default',\n          'shell-page-host--inset-none': this.contentInset === 'none',\n          'shell-page-host--mobile': mobile,\n          [`shell-page-host--header-${this.effectiveVariant}`]: true,\n        }}\n      >\n        <div\n          ref={el => {\n            this.sentinelEl = el ?? null;\n          }}\n          class=\"shell-page__scroll-sentinel\"\n          aria-hidden=\"true\"\n        />\n        <div\n          ref={el => {\n            this.stickyHeaderEl = el ?? null;\n          }}\n          class=\"shell-page__sticky-header\"\n        >\n          <div\n            class=\"shell-page__desktop-header\"\n            hidden={mobile}\n            aria-hidden={mobile ? 'true' : undefined}\n            inert={mobile ? true : undefined}\n          >\n            <slot name=\"header\" onSlotchange={this.handleHeaderSlotChange} />\n          </div>\n          <div\n            class=\"shell-page__mobile-header\"\n            hidden={!mobile}\n            aria-hidden={!mobile ? 'true' : undefined}\n            inert={!mobile ? true : undefined}\n          >\n            <slot name=\"mobile-header\" />\n          </div>\n        </div>\n        <div\n          ref={el => {\n            this.spacerEl = el ?? null;\n          }}\n          class=\"shell-page__flow-spacer\"\n          aria-hidden=\"true\"\n        />\n        <div class=\"shell-page__content\">\n          <slot />\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, h, Host, Prop, State, Watch } from '@stencil/core';\nimport type { ShellResponsiveMode } from '../../shell/shell-responsive';\nimport { resolveCssLengthPx } from '../../utils/resolve-css-length-px';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\nimport { resolveShellPageHeaderVariant } from './shell-page-responsive';\nimport type {\n  ShellPageCapacity,\n  ShellPageContentInset,\n  ShellPageHeaderPresentation,\n} from './shell-page-types';\n\ntype BarTitleElement = HTMLElement & { variant: BarTitleVariant };\n\n@Component({\n  tag: 'ds-shell-page',\n  styleUrl: 'ShellPage.css',\n  scoped: true,\n})\nexport class ShellPage {\n  private static readonly MAX_HEADER_REVEAL_FRAMES = 12;\n  private static readonly MAX_HEADER_GEOMETRY_FRAMES = 12;\n\n  @Element() el!: HTMLElement;\n\n  /** Automatic capacity/scroll behavior, or an explicit header variant override. */\n  @Prop() headerPresentation: ShellPageHeaderPresentation = 'auto';\n\n  /** Available page-header capacity supplied by the owning application shell. */\n  @Prop() headerCapacity?: ShellPageCapacity;\n\n  /** Standard page gutters, or no inset for full-bleed page content. */\n  @Prop() contentInset: ShellPageContentInset = 'default';\n\n  /** Explicit shell breakpoint presentation. Mobile uses the dedicated mobile-header slot. */\n  @Prop({ attribute: 'responsive-mode', reflect: true })\n  responsiveMode: ShellResponsiveMode = 'desktop';\n\n  @State() private pageTopVisible = true;\n\n  private sentinelEl: HTMLElement | null = null;\n  private spacerEl: HTMLElement | null = null;\n  private stickyHeaderEl: HTMLElement | null = null;\n  private headerEl: BarTitleElement | null = null;\n  private expandedHeaderHeight = 0;\n  private headerTravel = 0;\n  private expandedGeometryFrozen = false;\n  private headerResizeObserver: ResizeObserver | null = null;\n  private headerMutationObserver: MutationObserver | null = null;\n  private headerRevealFrame: number | null = null;\n  private headerGeometryFrame: number | null = null;\n  private scrollRoot: HTMLElement | Window | null = null;\n\n  @Watch('headerCapacity')\n  @Watch('headerPresentation')\n  handleHeaderContractChange() {\n    this.syncHeaderVariant(true);\n  }\n\n  @Watch('responsiveMode')\n  handleResponsiveModeChange() {\n    this.observeHeader(this.responsiveMode === 'mobile' ? null : this.findHeader());\n  }\n\n  componentDidLoad() {\n    this.observeHeader(this.responsiveMode === 'mobile' ? null : this.findHeader());\n    this.connectScrollRoot();\n  }\n\n  componentDidRender() {\n    this.syncHeaderVariant();\n  }\n\n  disconnectedCallback() {\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.headerEl?.style.removeProperty('--ds-bar-title-divider-inset');\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = null;\n  }\n\n  private get effectiveVariant(): BarTitleVariant {\n    return resolveShellPageHeaderVariant(\n      this.headerPresentation,\n      this.headerCapacity ?? 'roomy',\n      this.pageTopVisible\n    );\n  }\n\n  private get headerContractResolved(): boolean {\n    return this.headerPresentation !== 'auto' || this.headerCapacity !== undefined;\n  }\n\n  private get isScrollCompacted(): boolean {\n    return (\n      this.headerPresentation === 'auto' && this.headerCapacity === 'roomy' && !this.pageTopVisible\n    );\n  }\n\n  private composedParent(element: Element): Element | null {\n    return (element as HTMLElement).assignedSlot?.parentElement ?? element.parentElement;\n  }\n\n  private findScrollRoot(): HTMLElement | Window {\n    let ancestor = this.composedParent(this.el);\n    while (ancestor && ancestor !== document.documentElement) {\n      const overflow = getComputedStyle(ancestor).overflowY;\n      if (overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay') {\n        return ancestor as HTMLElement;\n      }\n      ancestor = this.composedParent(ancestor);\n    }\n    return window;\n  }\n\n  private connectScrollRoot() {\n    const next = this.findScrollRoot();\n    if (next === this.scrollRoot) return;\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = next;\n    this.scrollRoot.addEventListener('scroll', this.handleScroll, { passive: true });\n    this.handleScroll();\n  }\n\n  private handleScroll = () => {\n    if (!this.sentinelEl || !this.scrollRoot) return;\n    const rootTop =\n      this.scrollRoot === window ? 0 : (this.scrollRoot as HTMLElement).getBoundingClientRect().top;\n    this.syncHeaderDividerInset(rootTop);\n    const nextPageTopVisible = this.sentinelEl.getBoundingClientRect().top >= rootTop;\n    if (\n      !nextPageTopVisible &&\n      this.pageTopVisible &&\n      this.headerEl?.classList.contains(this.variantClass('expanded'))\n    ) {\n      this.captureExpandedHeaderGeometry(this.headerEl);\n      this.expandedGeometryFrozen = true;\n    }\n    if (\n      nextPageTopVisible &&\n      this.expandedGeometryFrozen &&\n      this.el.getBoundingClientRect().top >= rootTop\n    ) {\n      this.expandedGeometryFrozen = false;\n      if (this.headerEl?.classList.contains(this.variantClass('expanded'))) {\n        this.captureExpandedHeaderGeometry(this.headerEl);\n      }\n    }\n    this.pageTopVisible = nextPageTopVisible;\n  };\n\n  private findHeader(): BarTitleElement | null {\n    return this.el.querySelector<BarTitleElement>('ds-bar-title');\n  }\n\n  private get compactHeaderHeight(): number {\n    return resolveCssLengthPx('--dimension-size-600', 0);\n  }\n\n  private syncHeaderDividerInset(rootTop?: number) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    const ownsScrollTransition =\n      this.headerPresentation === 'auto' && this.headerCapacity === 'roomy';\n    const expandedInset = resolveCssLengthPx('--dimension-space-400', 0);\n    if (\n      !ownsScrollTransition ||\n      !this.sentinelEl ||\n      !this.scrollRoot ||\n      this.headerTravel <= 0 ||\n      expandedInset <= 0\n    ) {\n      header.style.removeProperty('--ds-bar-title-divider-inset');\n      return;\n    }\n\n    const scrollRootTop =\n      rootTop ??\n      (this.scrollRoot === window\n        ? 0\n        : (this.scrollRoot as HTMLElement).getBoundingClientRect().top);\n    const remainingTravel = this.sentinelEl.getBoundingClientRect().top - scrollRootTop;\n    const progress = Math.min(1, Math.max(0, 1 - remainingTravel / this.headerTravel));\n    header.style.setProperty('--ds-bar-title-divider-inset', `${expandedInset * (1 - progress)}px`);\n  }\n\n  private setHeaderTravel(distance: number) {\n    const next = Math.max(0, distance);\n    if (Math.abs(next - this.headerTravel) < 0.5) return;\n    this.headerTravel = next;\n    this.el.style.setProperty('--ds-shell-page-header-travel', `${next}px`);\n    this.handleScroll();\n  }\n\n  private measureHeaderTravel(header: BarTitleElement) {\n    const anchor = header.querySelector<HTMLElement>('[data-shell-page-header-anchor]');\n    const compactHeight = this.compactHeaderHeight;\n    if (!anchor || compactHeight <= 0) return;\n\n    const headerRect = header.getBoundingClientRect();\n    const anchorRect = anchor.getBoundingClientRect();\n    if (headerRect.height <= 0 || anchorRect.height <= 0) return;\n\n    const expandedAnchorTop = anchorRect.top - headerRect.top;\n    const compactAnchorTop = Math.max(0, (compactHeight - anchorRect.height) / 2);\n    this.setHeaderTravel(expandedAnchorTop - compactAnchorTop);\n  }\n\n  private captureExpandedHeaderGeometry(header: BarTitleElement) {\n    this.expandedHeaderHeight = header.getBoundingClientRect().height;\n    this.measureHeaderTravel(header);\n  }\n\n  private setSpacerHeight(height: number) {\n    if (!this.spacerEl) return;\n    this.spacerEl.style.setProperty('--ds-shell-page-flow-spacer', `${Math.max(0, height)}px`);\n  }\n\n  private variantClass(variant: BarTitleVariant): string {\n    return `bar-title-host--${variant}`;\n  }\n\n  private setStickyHeaderOffset(renderedVariant: BarTitleVariant) {\n    this.stickyHeaderEl?.style.setProperty(\n      '--ds-shell-page-sticky-offset',\n      renderedVariant === 'expanded' &&\n        this.headerPresentation === 'auto' &&\n        this.headerCapacity === 'roomy'\n        ? `${-this.headerTravel}px`\n        : '0px'\n    );\n  }\n\n  private syncRenderedHeaderGeometry(header: BarTitleElement) {\n    const renderedVariant = this.effectiveVariant;\n    if (!header.classList.contains(this.variantClass(renderedVariant))) return;\n\n    // Update both flow-preservation pieces before reading layout. Otherwise a\n    // reverse compact → expanded render can briefly contain the tall header and\n    // the compact spacer together, giving browser scroll anchoring a transient\n    // height change to compensate.\n    this.setSpacerHeight(\n      this.isScrollCompacted ? this.expandedHeaderHeight - this.compactHeaderHeight : 0\n    );\n    this.setStickyHeaderOffset(renderedVariant);\n\n    if (renderedVariant === 'expanded' && !this.expandedGeometryFrozen) {\n      this.captureExpandedHeaderGeometry(header);\n      this.setStickyHeaderOffset(renderedVariant);\n    }\n  }\n\n  private cancelHeaderGeometrySync() {\n    if (this.headerGeometryFrame !== null) cancelAnimationFrame(this.headerGeometryFrame);\n    this.headerGeometryFrame = null;\n  }\n\n  private scheduleHeaderGeometrySync(header: BarTitleElement) {\n    this.cancelHeaderGeometrySync();\n    let framesRemaining = ShellPage.MAX_HEADER_GEOMETRY_FRAMES;\n    let framesElapsed = 0;\n    const sync = () => {\n      if (this.headerEl !== header) return;\n      framesRemaining -= 1;\n      framesElapsed += 1;\n      // In WebKit a child's componentDidLoad can precede its assignment into\n      // the parent's rendered slot. Revalidate after ShellApp has had a frame\n      // to expose the actual content scroller.\n      this.connectScrollRoot();\n      this.syncRenderedHeaderGeometry(header);\n      const geometryReady =\n        this.effectiveVariant !== 'expanded' ||\n        (this.expandedHeaderHeight > 0 && this.headerTravel > 0);\n      if ((geometryReady && framesElapsed >= 2) || framesRemaining <= 0) {\n        this.headerGeometryFrame = null;\n        return;\n      }\n      this.headerGeometryFrame = requestAnimationFrame(sync);\n    };\n    this.headerGeometryFrame = requestAnimationFrame(sync);\n  }\n\n  private cancelHeaderReveal() {\n    if (this.headerRevealFrame !== null) cancelAnimationFrame(this.headerRevealFrame);\n    this.headerRevealFrame = null;\n    this.headerEl?.removeAttribute('data-shell-page-syncing');\n  }\n\n  private revealHeaderWhenSynced(header: BarTitleElement, variant: BarTitleVariant) {\n    // Stencil normally re-renders within a frame or two of a prop change. Stop\n    // polling at the cap, but fail closed: a stale variant must never paint.\n    let framesRemaining = ShellPage.MAX_HEADER_REVEAL_FRAMES;\n    const reveal = () => {\n      if (this.headerEl !== header) {\n        header.removeAttribute('data-shell-page-syncing');\n        return;\n      }\n      framesRemaining -= 1;\n      if (header.classList.contains(this.variantClass(variant))) {\n        header.removeAttribute('data-shell-page-syncing');\n        this.headerRevealFrame = null;\n        return;\n      }\n      if (framesRemaining <= 0) {\n        this.headerRevealFrame = null;\n        return;\n      }\n      this.headerRevealFrame = requestAnimationFrame(reveal);\n    };\n    this.headerRevealFrame = requestAnimationFrame(reveal);\n  }\n\n  private syncHeaderVariant(concealUntilSynced = false) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    this.syncHeaderDividerInset();\n    if (!this.headerContractResolved) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n      return;\n    }\n\n    const next = this.effectiveVariant;\n    const renderedVariantIsStale = !header.classList.contains(this.variantClass(next));\n    if (!renderedVariantIsStale) this.syncRenderedHeaderGeometry(header);\n    if (concealUntilSynced) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n    }\n    if (header.variant !== next) header.variant = next;\n    if (concealUntilSynced) {\n      this.revealHeaderWhenSynced(header, next);\n    }\n  }\n\n  private observeHeader(header: BarTitleElement | null) {\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.headerEl?.style.removeProperty('--ds-bar-title-divider-inset');\n    this.headerEl = header;\n    this.expandedHeaderHeight = 0;\n    this.expandedGeometryFrozen = false;\n    this.setHeaderTravel(0);\n    this.setSpacerHeight(0);\n    this.stickyHeaderEl?.style.setProperty('--ds-shell-page-sticky-offset', '0px');\n\n    if (!header) return;\n    if (header.classList.contains(this.variantClass('expanded'))) {\n      this.captureExpandedHeaderGeometry(header);\n    }\n    if (typeof ResizeObserver !== 'undefined') {\n      this.headerResizeObserver = new ResizeObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerResizeObserver.observe(header);\n    }\n    if (typeof MutationObserver !== 'undefined') {\n      this.headerMutationObserver = new MutationObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerMutationObserver.observe(header, {\n        attributes: true,\n        attributeFilter: ['class'],\n      });\n    }\n    this.syncHeaderVariant(true);\n    this.scheduleHeaderGeometrySync(header);\n  }\n\n  private handleHeaderSlotChange = (event: Event) => {\n    if (this.responsiveMode === 'mobile') return;\n    const slot = event.target as HTMLSlotElement;\n    const header = slot\n      .assignedElements()\n      .find(element => element.tagName.toLowerCase() === 'ds-bar-title');\n    this.observeHeader((header as BarTitleElement | undefined) ?? null);\n  };\n\n  render() {\n    const mobile = this.responsiveMode === 'mobile';\n    return (\n      <Host\n        role=\"main\"\n        class={{\n          'shell-page-host--inset-default': this.contentInset === 'default',\n          'shell-page-host--inset-none': this.contentInset === 'none',\n          'shell-page-host--mobile': mobile,\n          [`shell-page-host--header-${this.effectiveVariant}`]: true,\n        }}\n      >\n        <div\n          ref={el => {\n            this.sentinelEl = el ?? null;\n          }}\n          class=\"shell-page__scroll-sentinel\"\n          aria-hidden=\"true\"\n        />\n        <div\n          ref={el => {\n            this.stickyHeaderEl = el ?? null;\n          }}\n          class=\"shell-page__sticky-header\"\n        >\n          <div\n            class=\"shell-page__desktop-header\"\n            hidden={mobile}\n            aria-hidden={mobile ? 'true' : undefined}\n            inert={mobile ? true : undefined}\n          >\n            <slot name=\"header\" onSlotchange={this.handleHeaderSlotChange} />\n          </div>\n          <div\n            class=\"shell-page__mobile-header\"\n            hidden={!mobile}\n            aria-hidden={!mobile ? 'true' : undefined}\n            inert={!mobile ? true : undefined}\n          >\n            <slot name=\"mobile-header\" />\n          </div>\n        </div>\n        <div\n          ref={el => {\n            this.spacerEl = el ?? null;\n          }}\n          class=\"shell-page__flow-spacer\"\n          aria-hidden=\"true\"\n        />\n        <div class=\"shell-page__content\">\n          <slot />\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {