@ds-mo/ui 14.36.0 → 15.1.0

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

@@ -113,7 +113,54 @@
           "label": "Cross-browser form and accessibility coverage",
           "path": "tests/e2e/forms.spec.ts"
         }
-      ]
+      ],
+      "styling": {
+        "rationale": "The component owns the protected recipes below; unspecified host properties and application layout remain customizable.",
+        "protected": [
+          {
+            "properties": [
+              "font",
+              "font-size",
+              "font-weight",
+              "font-family",
+              "line-height",
+              "letter-spacing",
+              "height",
+              "min-height",
+              "max-height",
+              "padding",
+              "gap"
+            ],
+            "reason": "The control density is one atomic recipe; use the size and inset props instead of replacing internal metrics.",
+            "props": [
+              "size"
+            ]
+          },
+          {
+            "properties": [
+              "border-radius"
+            ],
+            "reason": "The component owns its corner treatment; select the supported radius treatment.",
+            "props": [
+              "size"
+            ]
+          },
+          {
+            "properties": [
+              "background",
+              "border",
+              "box-shadow",
+              "color"
+            ],
+            "reason": "The component owns its surface and interaction treatment; use its semantic presentation props or compose an application-owned surrounding surface.",
+            "props": [
+              "hasBorder",
+              "size"
+            ]
+          }
+        ],
+        "customProperties": []
+      }
     },
     "api": {
       "props": {
@@ -743,7 +790,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^6.5.1",
-          "@ds-mo/icons ^7.0.0"
+          "@ds-mo/icons ^8.1.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Vue 3 wrappers; Angular 19-22 standalone adapters."
       }
@@ -768,7 +815,7 @@
     },
     {
       "path": "src/wc/components/Input/Input.tsx",
-      "content": "import {\n  AttachInternals,\n  Component,\n  Prop,\n  State,\n  Event,\n  EventEmitter,\n  Element,\n  Method,\n  Watch,\n  h,\n  Host,\n} from '@stencil/core';\nimport {\n  controlWidthClass,\n  CONTROL_TEXT_VARIANT,\n  DEFAULT_REQUIRED_MESSAGE,\n  restoreStringFormState,\n  setFormControlValue,\n  setRequiredValidity,\n  type ControlWidth,\n} from '../../utils';\n\nexport type InputType = 'text' | 'email' | 'tel' | 'url' | 'search' | 'password' | 'number';\nexport type InputSize = 'lg' | 'md' | 'sm' | 'xs';\nexport type InputWidth = ControlWidth;\nexport type InputTextAlign = 'start' | 'end';\n\nconst CONTROL_ADORNMENT = 'ds-select, ds-button-unfilled, ds-button-filled';\n\nfunction isControlAdornment(element: Element): boolean {\n  return element.matches(CONTROL_ADORNMENT) || Boolean(element.querySelector(CONTROL_ADORNMENT));\n}\n\nconst ICON_SIZE: Record<InputSize, 'lg' | 'md' | 'sm' | 'xs'> = {\n  lg: 'lg',\n  md: 'md',\n  sm: 'sm',\n  xs: 'xs',\n};\n\nconst CLEAR_BUTTON_SIZE: Record<InputSize, 'md' | 'sm' | 'xs'> = {\n  lg: 'md',\n  md: 'sm',\n  sm: 'xs',\n  xs: 'xs',\n};\n\nlet idCounter = 0;\n\n@Component({\n  tag: 'ds-input',\n  styleUrl: 'Input.css',\n  scoped: true,\n  formAssociated: true,\n})\nexport class Input {\n  @Element() el!: HTMLElement;\n  @AttachInternals() internals!: ElementInternals;\n\n  private generatedId = `ds-input-${++idCounter}`;\n  private errorId = `${this.generatedId}-error`;\n\n  @Prop({ mutable: true }) value: string = '';\n  @Prop({ reflect: true }) name: string | undefined;\n  @Prop({ reflect: true }) form: string | undefined;\n  @Prop({ reflect: true }) disabled: boolean = false;\n  /** Keeps the value focusable and submittable while preventing edits. */\n  @Prop({ reflect: true }) readOnly: boolean = false;\n  @Prop({ reflect: true }) required: boolean = false;\n  @Prop() requiredMessage: string = DEFAULT_REQUIRED_MESSAGE;\n  @Prop() clearLabel: string = 'Clear';\n  @Prop() showPasswordLabel: string = 'Show password';\n  @Prop() hidePasswordLabel: string = 'Hide password';\n  @Prop() placeholder: string | undefined;\n  @Prop() type: InputType = 'text';\n  /** Minimum accepted value when type is number. */\n  @Prop() min: number | undefined;\n  /** Maximum accepted value when type is number. */\n  @Prop() max: number | undefined;\n  /** Numeric increment used by native stepping and constraint validation. */\n  @Prop() step: number | undefined;\n  /** Align the editable value; number steppers follow the same inline edge. */\n  @Prop() textAlign: InputTextAlign = 'start';\n  /** Native browser autofill hint. */\n  @Prop({ attribute: 'autocomplete' }) autoComplete: string | undefined;\n  /** Preferred virtual keyboard without changing the value semantics. */\n  @Prop({ attribute: 'inputmode' }) inputMode: string = '';\n  /** Preferred virtual-keyboard action label. */\n  @Prop({ attribute: 'enterkeyhint' }) enterKeyHint: string = '';\n  /** Control density. */\n  @Prop() size: InputSize = 'md';\n  /** Width fit — fill the parent (default) or hug the available content. */\n  @Prop() width: InputWidth = 'fill';\n  /** Show the standard inset border, including focused and invalid strokes. */\n  @Prop() hasBorder: boolean = true;\n  /** Show the standard hover and pressed fill when the field is not embedded in interactive chrome. */\n  @Prop() hasInteractionFill: boolean = true;\n  /** Optional leading icon name. */\n  @Prop() icon: string | undefined;\n  @Prop() isInactive: boolean = false;\n  @Prop() autoFocus: boolean = false;\n  @Prop() error: boolean = false;\n  @Prop() errorMessage: string | undefined;\n  /** Associates the internal input with an external <label>. */\n  @Prop() inputId: string | undefined;\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  @Prop({ attribute: 'aria-labelledby' }) ariaLabelledby: string | undefined;\n  @Prop({ attribute: 'aria-describedby' }) ariaDescribedby: string | undefined;\n  /** Identifies the results or popup controlled by the editable field. */\n  @Prop({ attribute: 'aria-controls' }) ariaControls: string | undefined;\n  /** Identifies the active descendant while focus remains in the editable field. */\n  @Prop({ attribute: 'aria-activedescendant' }) ariaActiveDescendant: string | undefined;\n\n  @Event() dsChange!: EventEmitter<string>;\n  @Event() dsClear!: EventEmitter<void>;\n\n  private initialValue = '';\n  private inputEl?: HTMLInputElement;\n  @State() private formDisabled = false;\n  @State() private hasPrefix = false;\n  @State() private hasPrefixControl = false;\n  @State() private hasSuffix = false;\n  @State() private hasSuffixControl = false;\n  @State() private focused = false;\n  @State() private touched = false;\n  @State() private passwordRevealed = false;\n  private restorePasswordFocus = false;\n\n  componentWillLoad() {\n    this.initialValue = this.value;\n    this.syncAdornmentSlots();\n    this.syncFormValue();\n  }\n\n  componentDidRender() {\n    this.syncAdornmentSlots();\n    if (!this.restorePasswordFocus) return;\n    this.restorePasswordFocus = false;\n    this.inputEl?.focus({ preventScroll: true });\n  }\n\n  @Watch('type')\n  onTypeChange() {\n    if (this.type !== 'password') this.passwordRevealed = false;\n  }\n\n  private syncAdornmentSlots() {\n    const prefixNodes = [...this.el.querySelectorAll('[slot=\"prefix\"]')];\n    const suffixNodes = [...this.el.querySelectorAll('[slot=\"suffix\"]')];\n    const hasPrefix = prefixNodes.length > 0;\n    const hasPrefixControl = prefixNodes.some(isControlAdornment);\n    const hasSuffix = suffixNodes.length > 0;\n    const hasSuffixControl = suffixNodes.some(isControlAdornment);\n    if (hasPrefix !== this.hasPrefix) this.hasPrefix = hasPrefix;\n    if (hasPrefixControl !== this.hasPrefixControl) this.hasPrefixControl = hasPrefixControl;\n    if (hasSuffix !== this.hasSuffix) this.hasSuffix = hasSuffix;\n    if (hasSuffixControl !== this.hasSuffixControl) this.hasSuffixControl = hasSuffixControl;\n  }\n\n  @Watch('value')\n  @Watch('disabled')\n  @Watch('isInactive')\n  @Watch('required')\n  syncFormValue() {\n    const inactive = this.isInactive || this.disabled || this.formDisabled;\n    setFormControlValue(this.internals, this.value, { inactive });\n    const missing = this.required && !inactive && this.value.length === 0;\n    setRequiredValidity(this.internals, missing, this.requiredMessage);\n  }\n\n  formDisabledCallback(disabled: boolean) {\n    this.formDisabled = disabled;\n    this.syncFormValue();\n  }\n\n  formResetCallback() {\n    this.value = this.initialValue;\n    this.passwordRevealed = false;\n  }\n\n  formStateRestoreCallback(state: string | File | FormData | null) {\n    this.value = restoreStringFormState(state);\n  }\n\n  @Method()\n  async setFocus() {\n    this.inputEl?.focus();\n  }\n\n  private handleInput = (e: Event) => {\n    this.value = (e.target as HTMLInputElement).value;\n    this.dsChange.emit(this.value);\n  };\n\n  private handleFocus = () => {\n    this.focused = true;\n  };\n\n  private handleBlur = () => {\n    this.focused = false;\n    this.touched = true;\n  };\n\n  private handleClear = () => {\n    this.value = '';\n    this.dsChange.emit('');\n    this.dsClear.emit();\n    this.inputEl?.focus();\n  };\n\n  private handleTogglePassword = () => {\n    this.passwordRevealed = !this.passwordRevealed;\n    this.restorePasswordFocus = true;\n  };\n\n  private numericStepDisabled(direction: 1 | -1): boolean {\n    if (this.value.trim() === '') return false;\n    const value = Number(this.value);\n    if (!Number.isFinite(value)) return false;\n    if (direction > 0 && this.max !== undefined) return value >= this.max;\n    if (direction < 0 && this.min !== undefined) return value <= this.min;\n    return false;\n  }\n\n  private handleNumericStep = (direction: 1 | -1) => {\n    const input = this.inputEl;\n    if (!input || input.disabled || input.readOnly || this.numericStepDisabled(direction)) return;\n\n    const previous = input.value;\n    if (direction > 0) input.stepUp();\n    else input.stepDown();\n    input.focus({ preventScroll: true });\n    if (input.value === previous) return;\n\n    this.value = input.value;\n    this.dsChange.emit(this.value);\n  };\n\n  private renderNumericStepper(inactive: boolean) {\n    const incrementDisabled = inactive || this.readOnly || this.numericStepDisabled(1);\n    const decrementDisabled = inactive || this.readOnly || this.numericStepDisabled(-1);\n\n    return (\n      <span class=\"input-control__number-stepper\">\n        <button\n          type=\"button\"\n          class=\"input-control__number-step input-control__number-step--increment ds-focus-ring-inset ds-interaction-fill\"\n          disabled={incrementDisabled}\n          tabIndex={-1}\n          aria-hidden=\"true\"\n          onClick={() => this.handleNumericStep(1)}\n        >\n          <ds-icon\n            class=\"input-control__number-step-icon ds-interaction-fill__content\"\n            name=\"ChevronUp\"\n            size=\"xs\"\n            color=\"inherit\"\n          />\n        </button>\n        <button\n          type=\"button\"\n          class=\"input-control__number-step input-control__number-step--decrement ds-focus-ring-inset ds-interaction-fill\"\n          disabled={decrementDisabled}\n          tabIndex={-1}\n          aria-hidden=\"true\"\n          onClick={() => this.handleNumericStep(-1)}\n        >\n          <ds-icon\n            class=\"input-control__number-step-icon ds-interaction-fill__content\"\n            name=\"ChevronDown\"\n            size=\"xs\"\n            color=\"inherit\"\n          />\n        </button>\n      </span>\n    );\n  }\n\n  render() {\n    const inputId = this.inputId ?? this.generatedId;\n    const inactive = this.isInactive || this.disabled || this.formDisabled;\n    const filled = this.value.length > 0;\n    const dirty = this.value !== this.initialValue;\n    const showClear = this.type === 'search' && filled && !inactive && !this.readOnly;\n    const showPasswordToggle = this.type === 'password';\n    const nativeType = showPasswordToggle && this.passwordRevealed ? 'text' : this.type;\n    const showError = this.error && Boolean(this.errorMessage);\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const iconSize = ICON_SIZE[this.size];\n    const numeric = this.type === 'number';\n    const resolvedAutoComplete = this.autoComplete ?? (this.type === 'search' ? 'off' : undefined);\n    const suppressBrowserChrome = this.type === 'search' || this.type === 'password';\n\n    const describedBy =\n      [this.ariaDescribedby, showError ? this.errorId : undefined].filter(Boolean).join(' ') ||\n      undefined;\n\n    return (\n      <Host\n        class={{\n          'input-host': true,\n          'ds-field-stack': true,\n          'ds-field-stack--supporting-inset': !this.hasBorder,\n          'ds-control-inactive': inactive,\n          [`ds-control--${this.size}`]: true,\n          ...controlWidthClass(this.width),\n        }}\n        data-disabled={inactive ? '' : undefined}\n        data-readonly={this.readOnly ? '' : undefined}\n        data-required={this.required ? '' : undefined}\n        data-invalid={this.error ? '' : undefined}\n        data-filled={filled ? '' : undefined}\n        data-focused={this.focused ? '' : undefined}\n        data-dirty={dirty ? '' : undefined}\n        data-touched={this.touched ? '' : undefined}\n      >\n        <div\n          class={{\n            'input-control': true,\n            'input-control--number': numeric,\n            'input-control--align-start': this.textAlign === 'start',\n            'input-control--align-end': this.textAlign === 'end',\n            'ds-control-frame': true,\n            'input-control--bordered': this.hasBorder,\n            'input-control--error': this.hasBorder && this.error,\n            'input-control--prefix-control': this.hasPrefixControl,\n            'input-control--suffix-control': this.hasSuffixControl,\n            'ds-interaction-fill': this.hasInteractionFill,\n            [`ds-control--${this.size}`]: true,\n          }}\n        >\n          {numeric && this.textAlign === 'end' && this.renderNumericStepper(inactive)}\n          {this.icon && (\n            <span\n              class=\"input-control__prefix ds-control-icon-box ds-interaction-fill__content\"\n              aria-hidden=\"true\"\n            >\n              <ds-icon name={this.icon} size={iconSize} color=\"inherit\" />\n            </span>\n          )}\n          <span\n            class={{\n              'input-control__prefix-text': true,\n              'ds-control-label-box': !this.hasPrefixControl,\n              'ds-interaction-fill__content': true,\n              'input-control__prefix-text--control': this.hasPrefixControl,\n              'input-control__prefix-text--empty': !this.hasPrefix,\n            }}\n          >\n            <slot name=\"prefix\" onSlotchange={() => this.syncAdornmentSlots()} />\n            {this.hasPrefixControl && (\n              <ds-divider\n                class=\"input-control__adornment-divider\"\n                orientation=\"vertical\"\n                length=\"var(--ds-control-icon)\"\n              />\n            )}\n          </span>\n          <input\n            ref={element => {\n              this.inputEl = element;\n            }}\n            type={nativeType}\n            id={inputId}\n            value={this.value}\n            placeholder={this.placeholder}\n            min={numeric ? this.min : undefined}\n            max={numeric ? this.max : undefined}\n            step={numeric ? this.step : undefined}\n            disabled={inactive}\n            readOnly={this.readOnly}\n            required={this.required}\n            autoFocus={this.autoFocus}\n            autoComplete={resolvedAutoComplete}\n            autoCapitalize={suppressBrowserChrome ? 'none' : undefined}\n            autoCorrect={suppressBrowserChrome ? 'off' : undefined}\n            spellcheck={suppressBrowserChrome ? false : undefined}\n            inputMode={this.inputMode || undefined}\n            enterKeyHint={this.enterKeyHint || undefined}\n            class={`native-input native-input--align-${this.textAlign} ds-control-label-box ds-text--${textVariant.replace('text-', '')} ds-text--regular ds-interaction-fill__content`}\n            aria-label={this.ariaLabel}\n            aria-labelledby={this.ariaLabelledby}\n            aria-describedby={describedBy}\n            aria-controls={this.ariaControls}\n            aria-activedescendant={this.ariaActiveDescendant}\n            aria-invalid={this.error ? 'true' : undefined}\n            onInput={this.handleInput}\n            onFocus={this.handleFocus}\n            onBlur={this.handleBlur}\n          />\n          <span\n            class={{\n              'input-control__suffix': true,\n              'ds-control-label-box': !this.hasSuffixControl,\n              'input-control__suffix--control': this.hasSuffixControl,\n              'input-control__suffix--empty': !this.hasSuffix,\n            }}\n          >\n            {this.hasSuffixControl && (\n              <ds-divider\n                class=\"input-control__adornment-divider\"\n                orientation=\"vertical\"\n                length=\"var(--ds-control-icon)\"\n              />\n            )}\n            <slot name=\"suffix\" onSlotchange={() => this.syncAdornmentSlots()} />\n          </span>\n          {showClear && (\n            <ds-button-unfilled\n              class=\"input-control__clear\"\n              variant=\"icon\"\n              size={CLEAR_BUTTON_SIZE[this.size]}\n              icon=\"CrossCircle\"\n              hasBorder={false}\n              rounded\n              ariaLabel={this.clearLabel}\n              onDsClick={this.handleClear}\n            />\n          )}\n          {showPasswordToggle && (\n            <ds-button-unfilled\n              class=\"input-control__trailing-action\"\n              variant=\"icon\"\n              size={this.size}\n              icon={this.passwordRevealed ? 'EyeDisabled' : 'Eye'}\n              hasBorder={false}\n              isInset\n              isInactive={inactive}\n              ariaLabel={this.passwordRevealed ? this.hidePasswordLabel : this.showPasswordLabel}\n              onDsClick={this.handleTogglePassword}\n            />\n          )}\n          {numeric && this.textAlign === 'start' && this.renderNumericStepper(inactive)}\n        </div>\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  Prop,\n  State,\n  Event,\n  EventEmitter,\n  Element,\n  Method,\n  Watch,\n  h,\n  Host,\n} from '@stencil/core';\nimport {\n  controlWidthClass,\n  CONTROL_TEXT_VARIANT,\n  DEFAULT_REQUIRED_MESSAGE,\n  restoreStringFormState,\n  setFormControlValue,\n  setRequiredValidity,\n  type ControlWidth,\n} from '../../utils';\n\nexport type InputType = 'text' | 'email' | 'tel' | 'url' | 'search' | 'password' | 'number';\nexport type InputSize = 'lg' | 'md' | 'sm' | 'xs';\nexport type InputWidth = ControlWidth;\nexport type InputTextAlign = 'start' | 'end';\n\nconst CONTROL_ADORNMENT = 'ds-select, ds-button-unfilled, ds-button-filled';\n\nfunction isControlAdornment(element: Element): boolean {\n  return element.matches(CONTROL_ADORNMENT) || Boolean(element.querySelector(CONTROL_ADORNMENT));\n}\n\nconst ICON_SIZE: Record<InputSize, 'lg' | 'md' | 'sm' | 'xs'> = {\n  lg: 'lg',\n  md: 'md',\n  sm: 'sm',\n  xs: 'xs',\n};\n\nconst CLEAR_BUTTON_SIZE: Record<InputSize, 'md' | 'sm' | 'xs'> = {\n  lg: 'md',\n  md: 'sm',\n  sm: 'xs',\n  xs: 'xs',\n};\n\nlet idCounter = 0;\n\n@Component({\n  tag: 'ds-input',\n  styleUrl: 'Input.css',\n  scoped: true,\n  formAssociated: true,\n})\nexport class Input {\n  @Element() el!: HTMLElement;\n  @AttachInternals() internals!: ElementInternals;\n\n  private generatedId = `ds-input-${++idCounter}`;\n  private errorId = `${this.generatedId}-error`;\n\n  @Prop({ mutable: true }) value: string = '';\n  @Prop({ reflect: true }) name: string | undefined;\n  @Prop({ reflect: true }) form: string | undefined;\n  @Prop({ reflect: true }) disabled: boolean = false;\n  /** Keeps the value focusable and submittable while preventing edits. */\n  @Prop({ reflect: true }) readOnly: boolean = false;\n  @Prop({ reflect: true }) required: boolean = false;\n  @Prop() requiredMessage: string = DEFAULT_REQUIRED_MESSAGE;\n  @Prop() clearLabel: string = 'Clear';\n  @Prop() showPasswordLabel: string = 'Show password';\n  @Prop() hidePasswordLabel: string = 'Hide password';\n  @Prop() placeholder: string | undefined;\n  @Prop() type: InputType = 'text';\n  /** Minimum accepted value when type is number. */\n  @Prop() min: number | undefined;\n  /** Maximum accepted value when type is number. */\n  @Prop() max: number | undefined;\n  /** Numeric increment used by native stepping and constraint validation. */\n  @Prop() step: number | undefined;\n  /** Align the editable value; number steppers follow the same inline edge. */\n  @Prop() textAlign: InputTextAlign = 'start';\n  /** Native browser autofill hint. */\n  @Prop({ attribute: 'autocomplete' }) autoComplete: string | undefined;\n  /** Preferred virtual keyboard without changing the value semantics. */\n  @Prop({ attribute: 'inputmode' }) inputMode: string = '';\n  /** Preferred virtual-keyboard action label. */\n  @Prop({ attribute: 'enterkeyhint' }) enterKeyHint: string = '';\n  /** Control density. */\n  @Prop() size: InputSize = 'md';\n  /** Width fit — fill the parent (default) or hug the available content. */\n  @Prop() width: InputWidth = 'fill';\n  /** Show the standard inset border, including focused and invalid strokes. */\n  @Prop() hasBorder: boolean = true;\n  /** Show the standard hover and pressed fill when the field is not embedded in interactive chrome. */\n  @Prop() hasInteractionFill: boolean = true;\n  /** Optional leading icon name. */\n  @Prop() icon: string | undefined;\n  @Prop() isInactive: boolean = false;\n  @Prop() autoFocus: boolean = false;\n  @Prop() error: boolean = false;\n  @Prop() errorMessage: string | undefined;\n  /** Associates the internal input with an external <label>. */\n  @Prop() inputId: string | undefined;\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  @Prop({ attribute: 'aria-labelledby' }) ariaLabelledby: string | undefined;\n  @Prop({ attribute: 'aria-describedby' }) ariaDescribedby: string | undefined;\n  /** Identifies the results or popup controlled by the editable field. */\n  @Prop({ attribute: 'aria-controls' }) ariaControls: string | undefined;\n  /** Identifies the active descendant while focus remains in the editable field. */\n  @Prop({ attribute: 'aria-activedescendant' }) ariaActiveDescendant: string | undefined;\n\n  @Event() dsChange!: EventEmitter<string>;\n  @Event() dsClear!: EventEmitter<void>;\n\n  private initialValue = '';\n  private inputEl?: HTMLInputElement;\n  @State() private formDisabled = false;\n  @State() private hasPrefix = false;\n  @State() private hasPrefixControl = false;\n  @State() private hasSuffix = false;\n  @State() private hasSuffixControl = false;\n  @State() private focused = false;\n  @State() private touched = false;\n  @State() private passwordRevealed = false;\n  private restorePasswordFocus = false;\n\n  componentWillLoad() {\n    this.initialValue = this.value;\n    this.syncAdornmentSlots();\n    this.syncFormValue();\n  }\n\n  componentDidRender() {\n    this.syncAdornmentSlots();\n    if (!this.restorePasswordFocus) return;\n    this.restorePasswordFocus = false;\n    this.inputEl?.focus({ preventScroll: true });\n  }\n\n  @Watch('type')\n  onTypeChange() {\n    if (this.type !== 'password') this.passwordRevealed = false;\n  }\n\n  private syncAdornmentSlots() {\n    const prefixNodes = [...this.el.querySelectorAll('[slot=\"prefix\"]')];\n    const suffixNodes = [...this.el.querySelectorAll('[slot=\"suffix\"]')];\n    const hasPrefix = prefixNodes.length > 0;\n    const hasPrefixControl = prefixNodes.some(isControlAdornment);\n    const hasSuffix = suffixNodes.length > 0;\n    const hasSuffixControl = suffixNodes.some(isControlAdornment);\n    if (hasPrefix !== this.hasPrefix) this.hasPrefix = hasPrefix;\n    if (hasPrefixControl !== this.hasPrefixControl) this.hasPrefixControl = hasPrefixControl;\n    if (hasSuffix !== this.hasSuffix) this.hasSuffix = hasSuffix;\n    if (hasSuffixControl !== this.hasSuffixControl) this.hasSuffixControl = hasSuffixControl;\n  }\n\n  @Watch('value')\n  @Watch('disabled')\n  @Watch('isInactive')\n  @Watch('required')\n  syncFormValue() {\n    const inactive = this.isInactive || this.disabled || this.formDisabled;\n    setFormControlValue(this.internals, this.value, { inactive });\n    const missing = this.required && !inactive && this.value.length === 0;\n    setRequiredValidity(this.internals, missing, this.requiredMessage);\n  }\n\n  formDisabledCallback(disabled: boolean) {\n    this.formDisabled = disabled;\n    this.syncFormValue();\n  }\n\n  formResetCallback() {\n    this.value = this.initialValue;\n    this.passwordRevealed = false;\n  }\n\n  formStateRestoreCallback(state: string | File | FormData | null) {\n    this.value = restoreStringFormState(state);\n  }\n\n  @Method()\n  async setFocus() {\n    this.inputEl?.focus();\n  }\n\n  private handleInput = (e: Event) => {\n    this.value = (e.target as HTMLInputElement).value;\n    this.dsChange.emit(this.value);\n  };\n\n  private handleFocus = () => {\n    this.focused = true;\n  };\n\n  private handleBlur = () => {\n    this.focused = false;\n    this.touched = true;\n  };\n\n  private handleClear = () => {\n    this.value = '';\n    this.dsChange.emit('');\n    this.dsClear.emit();\n    this.inputEl?.focus();\n  };\n\n  private handleTogglePassword = () => {\n    this.passwordRevealed = !this.passwordRevealed;\n    this.restorePasswordFocus = true;\n  };\n\n  private numericStepDisabled(direction: 1 | -1): boolean {\n    if (this.value.trim() === '') return false;\n    const value = Number(this.value);\n    if (!Number.isFinite(value)) return false;\n    if (direction > 0 && this.max !== undefined) return value >= this.max;\n    if (direction < 0 && this.min !== undefined) return value <= this.min;\n    return false;\n  }\n\n  private handleNumericStep = (direction: 1 | -1) => {\n    const input = this.inputEl;\n    if (!input || input.disabled || input.readOnly || this.numericStepDisabled(direction)) return;\n\n    const previous = input.value;\n    if (direction > 0) input.stepUp();\n    else input.stepDown();\n    input.focus({ preventScroll: true });\n    if (input.value === previous) return;\n\n    this.value = input.value;\n    this.dsChange.emit(this.value);\n  };\n\n  private renderNumericStepper(inactive: boolean) {\n    const incrementDisabled = inactive || this.readOnly || this.numericStepDisabled(1);\n    const decrementDisabled = inactive || this.readOnly || this.numericStepDisabled(-1);\n\n    return (\n      <span class=\"input-control__number-stepper\">\n        <button\n          type=\"button\"\n          class=\"input-control__number-step input-control__number-step--increment ds-focus-ring-inset ds-interaction-fill\"\n          disabled={incrementDisabled}\n          tabIndex={-1}\n          aria-hidden=\"true\"\n          onClick={() => this.handleNumericStep(1)}\n        >\n          <ds-icon\n            class=\"input-control__number-step-icon ds-interaction-fill__content\"\n            name=\"ChevronUp\"\n            size=\"xs\"\n            color=\"inherit\"\n          />\n        </button>\n        <button\n          type=\"button\"\n          class=\"input-control__number-step input-control__number-step--decrement ds-focus-ring-inset ds-interaction-fill\"\n          disabled={decrementDisabled}\n          tabIndex={-1}\n          aria-hidden=\"true\"\n          onClick={() => this.handleNumericStep(-1)}\n        >\n          <ds-icon\n            class=\"input-control__number-step-icon ds-interaction-fill__content\"\n            name=\"ChevronDown\"\n            size=\"xs\"\n            color=\"inherit\"\n          />\n        </button>\n      </span>\n    );\n  }\n\n  render() {\n    const inputId = this.inputId ?? this.generatedId;\n    const inactive = this.isInactive || this.disabled || this.formDisabled;\n    const filled = this.value.length > 0;\n    const dirty = this.value !== this.initialValue;\n    const showClear = this.type === 'search' && filled && !inactive && !this.readOnly;\n    const showPasswordToggle = this.type === 'password';\n    const nativeType = showPasswordToggle && this.passwordRevealed ? 'text' : this.type;\n    const showError = this.error && Boolean(this.errorMessage);\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const iconSize = ICON_SIZE[this.size];\n    const numeric = this.type === 'number';\n    const resolvedAutoComplete = this.autoComplete ?? (this.type === 'search' ? 'off' : undefined);\n    const suppressBrowserChrome = this.type === 'search' || this.type === 'password';\n\n    const describedBy =\n      [this.ariaDescribedby, showError ? this.errorId : undefined].filter(Boolean).join(' ') ||\n      undefined;\n\n    return (\n      <Host\n        class={{\n          'input-host': true,\n          'ds-field-stack': true,\n          'ds-field-stack--supporting-inset': !this.hasBorder,\n          'ds-control-inactive': inactive,\n          [`ds-control--${this.size}`]: true,\n          ...controlWidthClass(this.width),\n        }}\n        data-disabled={inactive ? '' : undefined}\n        data-readonly={this.readOnly ? '' : undefined}\n        data-required={this.required ? '' : undefined}\n        data-invalid={this.error ? '' : undefined}\n        data-filled={filled ? '' : undefined}\n        data-focused={this.focused ? '' : undefined}\n        data-dirty={dirty ? '' : undefined}\n        data-touched={this.touched ? '' : undefined}\n      >\n        <div\n          class={{\n            'input-control': true,\n            'input-control--number': numeric,\n            'input-control--align-start': this.textAlign === 'start',\n            'input-control--align-end': this.textAlign === 'end',\n            'ds-control-frame': true,\n            'input-control--bordered': this.hasBorder,\n            'input-control--error': this.hasBorder && this.error,\n            'input-control--prefix-control': this.hasPrefixControl,\n            'input-control--suffix-control': this.hasSuffixControl,\n            'ds-interaction-fill': this.hasInteractionFill,\n            [`ds-control--${this.size}`]: true,\n          }}\n        >\n          {numeric && this.textAlign === 'end' && this.renderNumericStepper(inactive)}\n          {this.icon && (\n            <span\n              class=\"input-control__prefix ds-control-icon-box ds-interaction-fill__content\"\n              aria-hidden=\"true\"\n            >\n              <ds-icon name={this.icon} size={iconSize} color=\"inherit\" />\n            </span>\n          )}\n          <span\n            class={{\n              'input-control__prefix-text': true,\n              'ds-control-label-box': !this.hasPrefixControl,\n              'ds-interaction-fill__content': true,\n              'input-control__prefix-text--control': this.hasPrefixControl,\n              'input-control__prefix-text--empty': !this.hasPrefix,\n            }}\n          >\n            <slot name=\"prefix\" onSlotchange={() => this.syncAdornmentSlots()} />\n            {this.hasPrefixControl && (\n              <ds-divider\n                class=\"input-control__adornment-divider\"\n                orientation=\"vertical\"\n                length=\"var(--ds-control-icon)\"\n              />\n            )}\n          </span>\n          <input\n            ref={element => {\n              this.inputEl = element;\n            }}\n            type={nativeType}\n            id={inputId}\n            value={this.value}\n            placeholder={this.placeholder}\n            min={numeric ? this.min : undefined}\n            max={numeric ? this.max : undefined}\n            step={numeric ? this.step : undefined}\n            disabled={inactive}\n            readOnly={this.readOnly}\n            required={this.required}\n            autoFocus={this.autoFocus}\n            autoComplete={resolvedAutoComplete}\n            autoCapitalize={suppressBrowserChrome ? 'none' : undefined}\n            autoCorrect={suppressBrowserChrome ? 'off' : undefined}\n            spellcheck={suppressBrowserChrome ? false : undefined}\n            inputMode={this.inputMode || undefined}\n            enterKeyHint={this.enterKeyHint || undefined}\n            class={`native-input native-input--align-${this.textAlign} ds-control-label-box ds-text--${textVariant.replace('text-', '')} ds-text--regular ds-interaction-fill__content`}\n            aria-label={this.ariaLabel}\n            aria-labelledby={this.ariaLabelledby}\n            aria-describedby={describedBy}\n            aria-controls={this.ariaControls}\n            aria-activedescendant={this.ariaActiveDescendant}\n            aria-invalid={this.error ? 'true' : undefined}\n            onInput={this.handleInput}\n            onFocus={this.handleFocus}\n            onBlur={this.handleBlur}\n          />\n          <span\n            class={{\n              'input-control__suffix': true,\n              'ds-control-label-box': !this.hasSuffixControl,\n              'input-control__suffix--control': this.hasSuffixControl,\n              'input-control__suffix--empty': !this.hasSuffix,\n            }}\n          >\n            {this.hasSuffixControl && (\n              <ds-divider\n                class=\"input-control__adornment-divider\"\n                orientation=\"vertical\"\n                length=\"var(--ds-control-icon)\"\n              />\n            )}\n            <slot name=\"suffix\" onSlotchange={() => this.syncAdornmentSlots()} />\n          </span>\n          {showClear && (\n            <ds-button-unfilled\n              class=\"input-control__clear\"\n              variant=\"icon\"\n              size={CLEAR_BUTTON_SIZE[this.size]}\n              icon=\"CrossCircle\"\n              hasBorder={false}\n              rounded\n              ariaLabel={this.clearLabel}\n              onDsClick={this.handleClear}\n            />\n          )}\n          {showPasswordToggle && (\n            <ds-button-unfilled\n              class=\"input-control__trailing-action\"\n              variant=\"icon\"\n              size={this.size}\n              icon={this.passwordRevealed ? 'EyeStrikethrough' : 'Eye'}\n              hasBorder={false}\n              isInset\n              isInactive={inactive}\n              ariaLabel={this.passwordRevealed ? this.hidePasswordLabel : this.showPasswordLabel}\n              onDsClick={this.handleTogglePassword}\n            />\n          )}\n          {numeric && this.textAlign === 'start' && this.renderNumericStepper(inactive)}\n        </div>\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/loader.json

@@ -78,7 +78,27 @@
           "label": "Storybook examples",
           "path": "src/wc/components/Loader/Loader.stories.ts"
         }
-      ]
+      ],
+      "styling": {
+        "rationale": "The component owns the protected recipes below; unspecified host properties and application layout remain customizable.",
+        "protected": [
+          {
+            "properties": [
+              "width",
+              "height",
+              "min-width",
+              "min-height",
+              "max-width",
+              "max-height"
+            ],
+            "reason": "The primitive owns its size recipe; select size and position it through the parent layout.",
+            "props": [
+              "size"
+            ]
+          }
+        ],
+        "customProperties": []
+      }
     },
     "api": {
       "props": {
@@ -172,7 +192,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^6.5.1",
-          "@ds-mo/icons ^7.0.0"
+          "@ds-mo/icons ^8.1.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Vue 3 wrappers; Angular 19-22 standalone adapters."
       }

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

@@ -49,7 +49,23 @@
           "label": "Prose distribution decision",
           "path": "docs/prose-foundation.md"
         }
-      ]
+      ],
+      "styling": {
+        "rationale": "The public prose stylesheet intentionally owns typography and exposes consumer customization.",
+        "protected": [],
+        "customProperties": [
+          {
+            "name": "--ds-prose-text-max-inline-size",
+            "source": "src/wc/styles/prose.css",
+            "reason": "Application-owned readable prose measure."
+          },
+          {
+            "name": "--ds-code-font-variant-ligatures",
+            "source": "src/wc/styles/prose.css",
+            "reason": "Application-owned code ligature preference."
+          }
+        ]
+      }
     },
     "api": {
       "props": {
@@ -123,7 +139,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^6.5.1",
-          "@ds-mo/icons ^7.0.0"
+          "@ds-mo/icons ^8.1.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Vue 3 wrappers; Angular 19-22 standalone adapters."
       }

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

@@ -106,7 +106,32 @@
           "label": "Framework integration",
           "path": "docs/framework-integration.md"
         }
-      ]
+      ],
+      "styling": {
+        "rationale": "The component owns the protected recipes below; unspecified host properties and application layout remain customizable.",
+        "protected": [
+          {
+            "properties": [
+              "background",
+              "border",
+              "box-shadow",
+              "color"
+            ],
+            "reason": "The component owns its surface and interaction treatment; use its semantic presentation props or compose an application-owned surrounding surface.",
+            "props": [
+              "size"
+            ]
+          },
+          {
+            "properties": [
+              "border-radius"
+            ],
+            "reason": "The component owns its surface radius; retain the shared recipe and customize an outer wrapper when needed.",
+            "props": []
+          }
+        ],
+        "customProperties": []
+      }
     },
     "api": {
       "props": {
@@ -539,7 +564,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^6.5.1",
-          "@ds-mo/icons ^7.0.0"
+          "@ds-mo/icons ^8.1.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Vue 3 wrappers; Angular 19-22 standalone adapters."
       }
@@ -561,12 +586,12 @@
   "files": [
     {
       "path": "src/wc/components/Menu/Menu.css",
-      "content": "@import '../../utils/radius.css';\n@import '../../utils/choice-list.css';\n@import '../../utils/visually-hidden.css';\n@import '../../utils/forced-colors.css';\n\n/* Inactive: `.ds-control-inactive` (50% opacity). */\n\n.menu-empty {\n  padding: var(--dimension-space-200);\n  box-sizing: border-box;\n  overflow-wrap: anywhere;\n}\n\n.menu-item--destructive .menu-item__label {\n  /* Beat ds-text color-* host classes for destructive rows. */\n  color: var(--color-foreground-bold-negative) !important;\n}\n\n/* Standard md icon zone keeps the dot aligned with other control suffixes. */\n.menu-item__dot-box {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  width: var(--ds-control-icon, var(--dimension-iconography-md));\n  height: var(--ds-control-icon, var(--dimension-iconography-md));\n  pointer-events: none;\n}\n\n/* Switch suffix keeps an 8px label-to-control gap without changing the\n   density gap between a prefix icon or drag handle and the label. */\n.menu-item__switch {\n  flex-shrink: 0;\n  margin-inline-start: calc(\n    var(--dimension-space-100) - var(--ds-control-gap, var(--dimension-space-050))\n  );\n}\n\n/* ── Prefix icon / reorder handle ────────────────────────────────────────── */\n\n.menu-item > .menu-item__handle {\n  pointer-events: auto;\n  cursor: grab;\n  touch-action: none;\n}\n\n.menu-item > .menu-item__handle:active,\n.menu-item--dragging > .menu-item__handle {\n  cursor: grabbing;\n}\n\n.menu-item--dragging {\n  opacity: var(--effect-opacity-medium);\n}\n\n.menu-item__drop-rail {\n  position: absolute;\n  z-index: var(--dimension-z-index-raised);\n  inset-inline: var(--dimension-space-050);\n  block-size: var(--dimension-stroke-width-025);\n  border-radius: var(--dimension-radius-half);\n  background: var(--color-border-bold-brand);\n  pointer-events: none;\n}\n\n.menu-item__drop-rail--before {\n  inset-block-start: calc(-1 * var(--dimension-space-025));\n  transform: translateY(-50%);\n}\n\n.menu-item__drop-rail--after {\n  inset-block-end: calc(-1 * var(--dimension-space-025));\n  transform: translateY(50%);\n}\n\n@media (forced-colors: active) {\n  .menu-item__drop-rail {\n    background: var(--ds-forced-color-selected);\n  }\n}\n\n.table-preferences-embedded {\n  display: flex;\n  flex-direction: column;\n  min-width: 0;\n  min-height: 0;\n  color: var(--color-foreground-secondary);\n}\n",
+      "content": "@import '../../utils/radius.css';\n@import '../../utils/choice-list.css';\n@import '../../utils/visually-hidden.css';\n@import '../../utils/forced-colors.css';\n\n/* Inactive: `.ds-control-inactive` (50% opacity). */\n\n.menu-empty {\n  padding: var(--dimension-space-200);\n  box-sizing: border-box;\n  overflow-wrap: anywhere;\n}\n\n.menu-item--destructive .menu-item__label {\n  /* Beat ds-text color-* host classes for destructive rows. */\n  color: var(--color-foreground-bold-negative) !important;\n}\n\n/* Standard md icon zone keeps the dot aligned with other control suffixes. */\n.menu-item__dot-box {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  width: var(--ds-control-icon, var(--dimension-iconography-md));\n  height: var(--ds-control-icon, var(--dimension-iconography-md));\n  pointer-events: none;\n}\n\n/* Switch suffix keeps an 8px label-to-control gap without changing the\n   density gap between a prefix icon or drag handle and the label. */\n.menu-item__switch {\n  flex-shrink: 0;\n  margin-inline-start: calc(\n    var(--dimension-space-100) - var(--ds-control-gap, var(--dimension-space-050))\n  );\n}\n\n/* ── Prefix icon / reorder handle ────────────────────────────────────────── */\n\n.menu-item > .menu-item__handle {\n  pointer-events: auto;\n  cursor: grab;\n  touch-action: none;\n}\n\n.menu-item > .menu-item__handle:active,\n.menu-item--dragging > .menu-item__handle {\n  cursor: grabbing;\n}\n\n.menu-item--dragging {\n  opacity: var(--effect-opacity-medium);\n}\n\n.menu-item__drop-rail {\n  position: absolute;\n  z-index: var(--dimension-z-index-raised);\n  inset-inline: var(--dimension-space-050);\n  block-size: var(--dimension-stroke-width-025);\n  border-radius: var(--dimension-radius-half);\n  background: var(--color-border-bold-brand);\n  pointer-events: none;\n}\n\n.menu-item__drop-rail--before {\n  inset-block-start: calc(-1 * var(--dimension-space-025));\n  transform: translateY(-50%);\n}\n\n.menu-item__drop-rail--after {\n  inset-block-end: calc(-1 * var(--dimension-space-025));\n  transform: translateY(50%);\n}\n\n@media (forced-colors: active) {\n  .menu-item__drop-rail {\n    background: var(--ds-forced-color-selected);\n  }\n}\n\n.data-preferences-embedded {\n  display: flex;\n  flex-direction: column;\n  min-width: 0;\n  min-height: 0;\n  color: var(--color-foreground-secondary);\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/Menu/Menu.tsx",
-      "content": "import {\n  Component,\n  Prop,\n  State,\n  Event,\n  EventEmitter,\n  Element,\n  Watch,\n  Listen,\n  h,\n  Host,\n} from '@stencil/core';\nimport {\n  choicePopupMinWidth,\n  CONTROL_SUPPORTING_TEXT_VARIANT,\n  CONTROL_TEXT_VARIANT,\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n  type ChoicePopupAnchorAlignment,\n  type ControlSize,\n} from '../../utils';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\nimport { AnchoredOverlayInteractionController } from '../../utils/anchored-overlay-interaction-controller';\nimport { resolveAnchoredOverlayBoundaryRect } from '../../utils/anchored-overlay-boundary';\nimport { computeAnchoredPosition, type AnchoredPositionInput } from '../../utils/anchored-position';\nimport type { MenuAlign, MenuSide } from './menu-position';\nimport {\n  isMenuPickerSection,\n  isMenuSwatchPickerSection,\n  type MenuItemData,\n  type MenuReorderDetail,\n  type MenuSection,\n} from './menu-types';\nimport { snapshotMenuSections } from './menu-sections';\nimport {\n  createMenuReorderDetail,\n  locateMenuItem,\n  menuReorderableRange,\n  moveReorderableMenuItemBefore,\n  moveReorderableMenuItemBy,\n} from './menu-reorder';\n\nexport type MenuSelectionMode = 'none' | 'single';\nexport type MenuSize = ControlSize;\nlet menuId = 0;\nconst MENU_ITEM_TAG_SIZE: Record<MenuSize, 'md' | 'sm' | 'xs'> = {\n  lg: 'md',\n  md: 'sm',\n  sm: 'xs',\n  xs: 'xs',\n};\n\n@Component({\n  tag: 'ds-menu',\n  styleUrl: 'Menu.css',\n  scoped: true,\n})\nexport class Menu {\n  @Element() el!: HTMLElement;\n\n  /** Render content inside a parent-owned surface; the parent owns dismissal and positioning. */\n  @Prop() embedded: boolean = false;\n  @Prop({ mutable: true }) open: boolean = false;\n  @Prop() items: MenuItemData[] = [];\n  /** Choice-row density. */\n  @Prop() size: MenuSize = 'md';\n  /** Give ordinary rows mutually-exclusive menu semantics using isSelected. */\n  @Prop() selectionMode: MenuSelectionMode = 'none';\n  @Prop() sections: MenuSection[] = [];\n  /** Preferred side; placement flips to the opposite side when that offers a better fit. */\n  @Prop() side: MenuSide = 'bottom';\n  @Prop() align: MenuAlign = 'start';\n  /** Align choice-row edges to the anchor by default; use `popup-frame` only for custom frame geometry. */\n  @Prop() anchorAlignment: ChoicePopupAnchorAlignment = 'choice-cell';\n  /** Gap between anchor and menu — number (px) or TokoMo length (`var(--dimension-space-050)`, etc.). */\n  @Prop() sideOffset: number | string = TOKEN_CSS_LENGTHS.space050;\n  /** Cross-axis offset — number (px) or TokoMo length. */\n  @Prop() alignOffset: number | string = 0;\n  @Prop() menuWidth: string | undefined;\n  @Prop() minWidth: string | undefined;\n  /** External trigger element to position against. Set via JS: menuEl.anchor = buttonEl */\n  @Prop() anchor: HTMLElement | undefined;\n  /** ID of the external trigger element for positioning */\n  @Prop() anchorId: string | undefined;\n  /** Explicit collision owner; otherwise the nearest data-ds-overlay-boundary ancestor is used. */\n  @Prop() boundary: HTMLElement | undefined;\n  /** Show a visible ring on the initially focused menu item. Use only when the opener was keyboard-driven. */\n  @Prop() initialFocusVisible: boolean = false;\n  /** Accessible name for the popup menu. */\n  @Prop() menuLabel: string = 'Menu';\n  /** Informational message shown when there are no choices. Uses a non-modal dialog, not a fake menu item. */\n  @Prop() emptyMessage: string = '';\n\n  @State() private shouldRender: boolean = false;\n  @State() private closing: boolean = false;\n  @State() private pos: { x: number; y: number } = { x: 0, y: 0 };\n  @State() private focusedIndex: number = 0;\n  @State() private positionReady: boolean = false;\n  @State() private availableHeight: number | null = null;\n  @State() private focusRingVisible: boolean = false;\n  @State() private reorderFromFlat: number | null = null;\n  @State() private reorderInsertBefore: number | null = null;\n  @State() private reorderAnnouncement = '';\n\n  @Event() dsClose!: EventEmitter<void>;\n  /** Emitted after the popup's exit motion is complete and its rendered content is removed. */\n  @Event() dsAfterClose!: EventEmitter<void>;\n  @Event() dsSelect!: EventEmitter<MenuItemData>;\n  /** Emitted when a generic `swatch-picker` section option is chosen. */\n  @Event() dsSwatchSelect!: EventEmitter<string>;\n  /** Emitted after a pointer drop or keyboard move; Menu never mutates item order. */\n  @Event() dsReorder!: EventEmitter<MenuReorderDetail>;\n\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n  private positionReadyCallback: (() => void) | undefined;\n  private suppressItemClick = false;\n  private reorderPointer: {\n    pointerId: number;\n    sectionIndex: number;\n    fromIndex: number;\n  } | null = null;\n  /**\n   * Anchored placement. The choice-cell measurement stays here on purpose: the\n   * inner-cell align offset and the `--dimension-menu-width-xs` floor are Menu\n   * semantics, not shared geometry.\n   */\n  private readonly position = new AnchoredPositionController({\n    getAnchor: () => this.resolvedAnchor ?? null,\n    getPopup: () => this.el.querySelector<HTMLElement>('.menu-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    measure: (anchorEl, popup) => {\n      if (!this.open) return null;\n\n      const anchorRect = anchorEl.getBoundingClientRect();\n      const sectionInsetPx = this.viewportPadPx;\n      if (!this.minWidth) {\n        if (\n          this.anchorAlignment === 'choice-cell' &&\n          (this.side === 'top' || this.side === 'bottom')\n        ) {\n          popup.style.minWidth = `max(var(--dimension-menu-width-xs), ${choicePopupMinWidth(\n            anchorRect.width,\n            sectionInsetPx\n          )}px)`;\n        } else {\n          popup.style.removeProperty('min-width');\n        }\n      }\n\n      const viewportPadPx = this.viewportPadPx;\n      const list = popup.querySelector<HTMLElement>('.ds-choice-list');\n      const naturalPopupHeight = Math.min(\n        Math.max(popup.offsetHeight, list?.scrollHeight ?? 0),\n        window.innerHeight - viewportPadPx * 2\n      );\n      const input: AnchoredPositionInput = {\n        anchorRect,\n        popupWidth: popup.offsetWidth || this.popupFallbackWidthPx,\n        popupHeight: naturalPopupHeight || this.popupFallbackHeightPx,\n        side: this.side,\n        align: this.align,\n        sideOffsetPx: this.sideOffsetPx,\n        alignOffsetPx: resolveChoicePopupAlignOffset({\n          align: this.align,\n          alignOffsetPx: this.alignOffsetPx,\n          sectionInsetPx,\n          anchorAlignment: this.anchorAlignment,\n        }),\n        viewportPadPx,\n        viewportWidth: window.innerWidth,\n        viewportHeight: window.innerHeight,\n        collisionRect: resolveAnchoredOverlayBoundaryRect(anchorEl, this.boundary),\n      };\n      const unconstrained = computeAnchoredPosition(input);\n      return {\n        ...input,\n        popupHeight: Math.min(input.popupHeight, unconstrained.availableHeight),\n      };\n    },\n    apply: ({ x, y, availableHeight }) => {\n      this.pos = { x, y };\n      this.availableHeight = availableHeight;\n    },\n    onReady: () => {\n      this.positionReady = true;\n    },\n    liveUpdate: 'double-frame',\n    topLayer: true,\n    observeResize: true,\n    observeAnchorMotion: true,\n  });\n  private readonly interaction = new AnchoredOverlayInteractionController({\n    getAnchor: () => this.resolvedAnchor,\n    getPopup: () => this.el.querySelector<HTMLElement>('.menu-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    onOutsideActivation: () => this.close(),\n  });\n  /** Last content actually painted while open; retained unchanged through exit motion. */\n  private lastRenderedSections: MenuSection[] = [];\n  private closingSections: MenuSection[] | null = null;\n  private readonly emptyMessageId = `ds-menu-empty-${++menuId}`;\n  private lastRenderedEmptyMessage = '';\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  disconnectedCallback() {\n    this.cancelPositionRetry();\n    this.cancelLivePositionUpdate();\n    this.clearReorderPointer();\n    this.teardownListeners();\n  }\n\n  @Watch('open')\n  onOpenChange(isOpen: boolean) {\n    if (this.embedded) return;\n    if (isOpen) {\n      this.teardownListeners();\n      this.closingSections = null;\n      this.shouldRender = true;\n      this.closing = false;\n      this.positionReady = false;\n      this.availableHeight = null;\n      this.focusRingVisible = this.initialFocusVisible;\n      this.setupListeners();\n      this.schedulePositionUpdate(() => {\n        this.focusInitialItem();\n      });\n    } else if (this.shouldRender) {\n      this.positionReadyCallback = undefined;\n      this.cancelPositionRetry();\n      this.captureClosingSections();\n      this.closing = true;\n      this.teardownListeners();\n      const closeAnimationMs = this.closeAnimationMs;\n      if (closeAnimationMs <= 0) {\n        this.finishClose();\n        return;\n      }\n      this.closeTimer = setTimeout(() => {\n        this.closeTimer = null;\n        this.finishClose();\n      }, closeAnimationMs);\n    }\n  }\n\n  @Watch('anchor')\n  @Watch('anchorId')\n  @Watch('boundary')\n  onAnchorChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  @Watch('side')\n  @Watch('align')\n  @Watch('anchorAlignment')\n  @Watch('sideOffset')\n  @Watch('alignOffset')\n  onPositionPropsChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  private get viewportPadPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n  }\n\n  private get sideOffsetPx(): number {\n    return resolveCssLengthPx(this.sideOffset, TOKEN_DEFAULTS.space050);\n  }\n\n  private get alignOffsetPx(): number {\n    return resolveCssLengthPx(this.alignOffset, 0);\n  }\n\n  private get popupFallbackWidthPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuWidthXs, TOKEN_DEFAULTS.menuWidthXs);\n  }\n\n  private get popupFallbackHeightPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuFallbackHeight, TOKEN_DEFAULTS.menuFallbackHeight);\n  }\n\n  private get closeAnimationMs(): number {\n    return resolveMotionTimeMs(TOKEN_DEFAULTS.motionShort2, TOKEN_DEFAULTS.animationDurationShort3);\n  }\n\n  private finishClose() {\n    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (popup?.matches(':popover-open')) popup.hidePopover();\n    this.shouldRender = false;\n    this.closing = false;\n    this.lastRenderedSections = [];\n    this.closingSections = null;\n    this.clearReorderPointer();\n    this.reorderAnnouncement = '';\n    this.dsAfterClose.emit();\n  }\n\n  private captureClosingSections() {\n    if (this.closingSections) return;\n    const visibleSections = this.lastRenderedSections.length\n      ? this.lastRenderedSections\n      : this.activeSections;\n    this.closingSections = snapshotMenuSections(visibleSections);\n  }\n\n  private get resolvedAnchor(): HTMLElement | null {\n    if (this.anchor) return this.anchor;\n    if (this.anchorId) return document.getElementById(this.anchorId);\n    return null;\n  }\n\n  private compositeTabLeavesPopup(event: KeyboardEvent): boolean {\n    return this.interaction.tabLeavesPopup(event);\n  }\n\n  private get activeSections(): MenuSection[] {\n    if (this.sections.length > 0) return this.sections;\n    if (this.items.length > 0) return [{ items: this.items }];\n    return [];\n  }\n\n  private get flatItems(): MenuItemData[] {\n    return this.activeSections.flatMap(section =>\n      isMenuPickerSection(section) ? [] : section.items\n    );\n  }\n\n  /** Rich preference content is a non-modal dialog, not an ARIA action menu. */\n  private get hasCompositeSections(): boolean {\n    return this.activeSections.some(isMenuPickerSection);\n  }\n\n  private cancelPositionRetry() {\n    this.position.cancel();\n  }\n\n  private cancelLivePositionUpdate() {\n    this.position.cancel();\n  }\n\n  /** Reposition after the current scroll/layout frame without hiding the open popup. */\n  private scheduleLivePositionUpdate() {\n    this.position.scheduleLiveUpdate();\n  }\n\n  /** Retry until anchor + popup exist — do not reveal at 0,0 on a failed first pass. */\n  private schedulePositionUpdate(onReady?: () => void) {\n    if (!this.open) return;\n    this.positionReady = false;\n    // Opening often sets `open` and `anchorId` together. Each Watch reschedules\n    // placement; keep the open-path ready callback so initial focus is not dropped.\n    if (onReady) this.positionReadyCallback = onReady;\n    const callback = this.positionReadyCallback;\n    this.position.schedule(() => {\n      if (this.positionReadyCallback === callback) {\n        this.positionReadyCallback = undefined;\n      }\n      callback?.();\n    });\n  }\n\n  /** @returns `true` when anchor and popup were found and `pos` was updated. */\n  private calculatePosition(): boolean {\n    return this.position.update();\n  }\n\n  /** Focus the selected item when present, otherwise the first enabled item. */\n  private focusInitialItem() {\n    if (!this.hasCompositeSections && !this.flatItems.length && this.emptyMessage.trim()) {\n      requestAnimationFrame(() => {\n        if (this.open) this.el.querySelector<HTMLElement>('.menu-popup')?.focus();\n      });\n      return;\n    }\n    if (this.hasCompositeSections) {\n      requestAnimationFrame(() => {\n        this.el.querySelector<HTMLElement>('.menu-popup [tabindex=\"0\"]')?.focus();\n      });\n      return;\n    }\n\n    const flat = this.flatItems;\n    const selectedIdx = flat.findIndex(it => it.isSelected && !it.isInactive);\n    const firstEnabledIdx = flat.findIndex(it => !it.isInactive || !!it.reorderable);\n    this.focusedIndex = selectedIdx >= 0 ? selectedIdx : firstEnabledIdx >= 0 ? firstEnabledIdx : 0;\n\n    requestAnimationFrame(() => {\n      const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n      btns[this.focusedIndex]?.focus();\n    });\n  }\n\n  private setupListeners() {\n    this.interaction.connect();\n    this.position.observe();\n  }\n\n  private teardownListeners() {\n    this.position.unobserve();\n    this.interaction.disconnect();\n    if (this.closeTimer) {\n      clearTimeout(this.closeTimer);\n      this.closeTimer = null;\n    }\n  }\n\n  private close(restoreFocus = true) {\n    this.captureClosingSections();\n    if (restoreFocus) this.interaction.focusAnchor();\n    this.dsClose.emit();\n    this.open = false;\n    this.onOpenChange(false);\n  }\n\n  @Listen('keydown')\n  handleKeyDown(e: KeyboardEvent) {\n    if (this.embedded && (e.key === 'Escape' || e.key === 'Tab')) return;\n    if ((!this.shouldRender && !this.embedded) || this.closing) return;\n\n    if (e.key === 'Escape') {\n      e.preventDefault();\n      this.close();\n      return;\n    }\n\n    if (e.key === 'Tab') {\n      if (this.hasCompositeSections && !this.compositeTabLeavesPopup(e)) return;\n      e.preventDefault();\n      this.close(false);\n      this.interaction.moveFocusAfterTab(e.shiftKey);\n      return;\n    }\n\n    if (this.hasCompositeSections) return;\n\n    if ((e.key === 'ArrowUp' || e.key === 'ArrowDown') && e.altKey && !e.ctrlKey && !e.shiftKey) {\n      this.handleReorderKey(e);\n      return;\n    }\n\n    const flat = this.flatItems;\n    const enabled = flat\n      .map((it, i) => ({ it, i }))\n      .filter(({ it }) => !it.isInactive || !!it.reorderable)\n      .map(({ i }) => i);\n    if (!enabled.length) return;\n\n    const cur = enabled.indexOf(this.focusedIndex);\n    const safe = cur < 0 ? 0 : cur;\n\n    switch (e.key) {\n      case 'ArrowDown':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe + 1) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'ArrowUp':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe - 1 + enabled.length) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'Home':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[0];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'End':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[enabled.length - 1];\n        this.focusItem(this.focusedIndex);\n        break;\n    }\n  }\n\n  private focusItem(idx: number) {\n    const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n    btns[idx]?.focus();\n  }\n\n  private handleItemClick(item: MenuItemData) {\n    if (this.suppressItemClick) {\n      this.suppressItemClick = false;\n      return;\n    }\n    if (item.isInactive) return;\n    // Consumers commonly change the item source while handling selection.\n    // Capture first so the exit animation never paints the next menu context.\n    this.captureClosingSections();\n    this.dsSelect.emit(item);\n  }\n\n  private handleSwatchSelect(value: string) {\n    this.dsSwatchSelect.emit(value);\n  }\n\n  private handleReorderKey(event: KeyboardEvent): void {\n    const located = locateMenuItem(this.activeSections, this.focusedIndex);\n    if (!located || !located.items[located.itemIndex]?.reorderable) return;\n\n    const nextItems = moveReorderableMenuItemBy(\n      located.items,\n      located.itemIndex,\n      event.key === 'ArrowUp' ? -1 : 1\n    );\n    if (!nextItems) return;\n\n    event.preventDefault();\n    event.stopPropagation();\n    this.emitReorder(located.items, located.itemIndex, nextItems, located.sectionIndex);\n  }\n\n  private emitReorder(\n    items: MenuItemData[],\n    fromIndex: number,\n    nextItems: MenuItemData[],\n    sectionIndex: number\n  ): void {\n    const detail = createMenuReorderDetail(items, fromIndex, nextItems, sectionIndex);\n    if (!detail) return;\n    this.focusedIndex = this.flatIndexFor(sectionIndex, detail.toIndex);\n    this.announceReorder(detail);\n    this.dsReorder.emit(detail);\n  }\n\n  private flatIndexFor(sectionIndex: number, itemIndex: number): number {\n    let flat = 0;\n    for (let index = 0; index < this.activeSections.length; index += 1) {\n      const section = this.activeSections[index];\n      if (isMenuPickerSection(section)) continue;\n      if (index === sectionIndex) return flat + itemIndex;\n      flat += section.items.length;\n    }\n    return itemIndex;\n  }\n\n  private announceReorder(detail: MenuReorderDetail): void {\n    const range = menuReorderableRange(detail.items, detail.toIndex);\n    const count = range ? range.end - range.start + 1 : detail.items.length;\n    const position = range ? detail.toIndex - range.start + 1 : detail.toIndex + 1;\n    this.reorderAnnouncement = `${detail.item.label} moved to position ${position} of ${count}`;\n  }\n\n  private onReorderPointerDown(\n    event: PointerEvent,\n    sectionIndex: number,\n    itemIndex: number,\n    flatIndex: number\n  ): void {\n    if (event.button !== 0) return;\n    const section = this.activeSections[sectionIndex];\n    if (!section || isMenuPickerSection(section)) return;\n    if (!section.items[itemIndex]?.reorderable) return;\n\n    event.preventDefault();\n    event.stopPropagation();\n    this.suppressItemClick = true;\n    this.focusRingVisible = false;\n    this.focusedIndex = flatIndex;\n    this.focusItem(flatIndex);\n    this.reorderPointer = {\n      pointerId: event.pointerId,\n      sectionIndex,\n      fromIndex: itemIndex,\n    };\n    this.reorderFromFlat = flatIndex;\n    this.reorderInsertBefore = itemIndex;\n    window.addEventListener('pointermove', this.onReorderPointerMove);\n    window.addEventListener('pointerup', this.onReorderPointerUp);\n    window.addEventListener('pointercancel', this.onReorderPointerCancel);\n  }\n\n  private onReorderPointerMove = (event: PointerEvent) => {\n    const drag = this.reorderPointer;\n    if (!drag || event.pointerId !== drag.pointerId) return;\n    const section = this.activeSections[drag.sectionIndex];\n    if (!section || isMenuPickerSection(section)) return;\n\n    const insertBefore = this.resolveReorderInsertBefore(\n      event.clientY,\n      drag.sectionIndex,\n      drag.fromIndex,\n      section.items\n    );\n    if (insertBefore !== this.reorderInsertBefore) this.reorderInsertBefore = insertBefore;\n  };\n\n  private onReorderPointerUp = (event: PointerEvent) => {\n    const drag = this.reorderPointer;\n    if (!drag || event.pointerId !== drag.pointerId) return;\n\n    const section = this.activeSections[drag.sectionIndex];\n    const insertBefore = this.reorderInsertBefore;\n    this.clearReorderPointer();\n    queueMicrotask(() => {\n      this.suppressItemClick = false;\n    });\n    if (!section || isMenuPickerSection(section) || insertBefore === null) return;\n\n    const nextItems = moveReorderableMenuItemBefore(section.items, drag.fromIndex, insertBefore);\n    if (!nextItems) return;\n    this.emitReorder(section.items, drag.fromIndex, nextItems, drag.sectionIndex);\n  };\n\n  private onReorderPointerCancel = (event: PointerEvent) => {\n    if (!this.reorderPointer || event.pointerId !== this.reorderPointer.pointerId) return;\n    this.clearReorderPointer();\n    queueMicrotask(() => {\n      this.suppressItemClick = false;\n    });\n  };\n\n  private resolveReorderInsertBefore(\n    clientY: number,\n    sectionIndex: number,\n    fromIndex: number,\n    items: MenuItemData[]\n  ): number {\n    const range = menuReorderableRange(items, fromIndex);\n    if (!range) return fromIndex;\n\n    const buttons = [...this.el.querySelectorAll<HTMLElement>('.menu-item')];\n    const sectionStart = this.flatIndexFor(sectionIndex, 0);\n    let insertBefore = range.end + 1;\n    for (let itemIndex = range.start; itemIndex <= range.end; itemIndex += 1) {\n      const row = buttons[sectionStart + itemIndex];\n      if (!row) continue;\n      const rect = row.getBoundingClientRect();\n      if (clientY < rect.top + rect.height / 2) {\n        insertBefore = itemIndex;\n        break;\n      }\n    }\n    return Math.min(Math.max(insertBefore, range.start), range.end + 1);\n  }\n\n  private clearReorderPointer(): void {\n    if (this.reorderPointer) {\n      window.removeEventListener('pointermove', this.onReorderPointerMove);\n      window.removeEventListener('pointerup', this.onReorderPointerUp);\n      window.removeEventListener('pointercancel', this.onReorderPointerCancel);\n    }\n    this.reorderPointer = null;\n    this.reorderFromFlat = null;\n    this.reorderInsertBefore = null;\n  }\n\n  render() {\n    if (!this.shouldRender && !this.embedded) return <Host style={{ display: 'contents' }} />;\n\n    const sections = this.closing\n      ? (this.closingSections ?? this.lastRenderedSections)\n      : this.activeSections;\n    const hasCompositeSections = sections.some(isMenuPickerSection);\n    const emptyMessage = this.closing ? this.lastRenderedEmptyMessage : this.emptyMessage.trim();\n    const showEmpty =\n      Boolean(emptyMessage) &&\n      !hasCompositeSections &&\n      sections.every(section => !isMenuPickerSection(section) && section.items.length === 0);\n    if (!this.closing) {\n      this.lastRenderedEmptyMessage = emptyMessage;\n      this.lastRenderedSections = snapshotMenuSections(sections);\n      this.closingSections = null;\n    }\n    let flatIdx = 0;\n    const dragLocated =\n      this.reorderFromFlat === null ? null : locateMenuItem(sections, this.reorderFromFlat);\n    const dragRange = dragLocated\n      ? menuReorderableRange(dragLocated.items, dragLocated.itemIndex)\n      : null;\n\n    const popupStyle: Record<string, string> = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.pos.x)}px, ${Math.round(this.pos.y)}px)`,\n      zIndex: '9998',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n\n    if (this.menuWidth) popupStyle['width'] = this.menuWidth;\n    if (this.minWidth) popupStyle['min-width'] = this.minWidth;\n    if (this.availableHeight !== null) {\n      popupStyle['max-height'] = `${Math.floor(this.availableHeight)}px`;\n    }\n\n    return (\n      <Host style={{ display: 'contents' }}>\n        <div\n          popover={this.embedded ? undefined : 'manual'}\n          class={{\n            'menu-popup': true,\n            'menu-popup--closing': this.closing,\n            'ds-choice-popup': !this.embedded,\n            'table-preferences-embedded': this.embedded,\n            'ds-choice-popup--closing': this.closing,\n            'ds-focus-ring': showEmpty,\n            'ds-focus-ring--visible': showEmpty && this.focusRingVisible,\n          }}\n          style={this.embedded ? undefined : popupStyle}\n          role={hasCompositeSections || showEmpty ? 'dialog' : 'menu'}\n          aria-label={this.menuLabel}\n          aria-orientation={hasCompositeSections || showEmpty ? undefined : 'vertical'}\n          aria-describedby={showEmpty ? this.emptyMessageId : undefined}\n          tabIndex={showEmpty ? -1 : undefined}\n        >\n          <div class=\"ds-choice-list\">\n            {showEmpty ? (\n              <ds-text\n                textId={this.emptyMessageId}\n                class=\"menu-empty\"\n                as=\"p\"\n                variant={CONTROL_TEXT_VARIANT[this.size]}\n                color=\"secondary\"\n              >\n                {emptyMessage}\n              </ds-text>\n            ) : (\n              sections.map((section, si) => (\n                <div\n                  key={si}\n                  class={{\n                    'menu-section': true,\n                    'menu-section--divided': si < sections.length - 1,\n                    'menu-section--swatch-picker': isMenuPickerSection(section),\n                    'ds-choice-section': true,\n                    'ds-chrome-column': true,\n                    'ds-chrome-space--sm': true,\n                    'ds-choice-section--divided': si < sections.length - 1,\n                    'ds-choice-section--headed-after-first': si > 0 && Boolean(section.header),\n                  }}\n                  role={section.header ? 'group' : undefined}\n                  aria-label={section.header}\n                >\n                  {section.header && (\n                    <ds-text\n                      class={`section-header ds-choice-section__header ds-control-section-heading ds-control--${this.size}`}\n                      as=\"span\"\n                      variant={CONTROL_SUPPORTING_TEXT_VARIANT[this.size]}\n                      emphasis\n                      color=\"primary\"\n                      aria-hidden=\"true\"\n                    >\n                      <span class=\"ds-choice-section__header-label\">{section.header}</span>\n                    </ds-text>\n                  )}\n                  {isMenuSwatchPickerSection(section) ? (\n                    <ds-swatch-picker\n                      value={section.value}\n                      groupLabel={section.groupLabel ?? section.header ?? 'Swatch options'}\n                      options={section.options ?? []}\n                      sections={section.sections ?? []}\n                      onDsChange={(e: CustomEvent<string>) => {\n                        e.stopPropagation();\n                        this.handleSwatchSelect(e.detail);\n                      }}\n                    />\n                  ) : (\n                    section.items.map((item, itemIndex) => {\n                      const idx = flatIdx++;\n                      const isFocused = this.focusedIndex === idx;\n                      const isSingleSelectionItem =\n                        !hasCompositeSections &&\n                        this.selectionMode === 'single' &&\n                        !item.showSwitch;\n                      const usesLeading = section.items.some(\n                        candidate => candidate.reorderable || !!candidate.icon\n                      );\n                      const locked = !!item.isInactive && !item.reorderable;\n                      const dragging = this.reorderFromFlat === idx;\n                      const dropBefore =\n                        dragLocated?.sectionIndex === si &&\n                        dragRange !== null &&\n                        itemIndex <= dragRange.end &&\n                        this.reorderInsertBefore === itemIndex;\n                      const dropAfter =\n                        dragLocated?.sectionIndex === si &&\n                        dragRange !== null &&\n                        this.reorderInsertBefore === dragRange.end + 1 &&\n                        itemIndex === dragRange.end;\n                      return (\n                        <button\n                          key={item.value ?? `${si}-${item.label}`}\n                          type=\"button\"\n                          class={{\n                            'menu-item': true,\n                            'ds-choice-item': true,\n                            'ds-control-frame': true,\n                            [`ds-control--${this.size}`]: true,\n                            'ds-focus-ring-inset': true,\n                            'ds-focus-ring--visible': isFocused && this.focusRingVisible,\n                            'ds-interaction-fill': !locked,\n                            'ds-interaction-fill--selected': !!item.isSelected && !locked,\n                            'menu-item--selected': !!item.isSelected,\n                            'menu-item--switch': !!item.showSwitch,\n                            'ds-control-inactive': locked,\n                            'menu-item--destructive': !!item.isDestructive,\n                            'menu-item--focused': isFocused,\n                            'menu-item--dragging': dragging,\n                          }}\n                          role={\n                            hasCompositeSections\n                              ? undefined\n                              : item.showSwitch\n                                ? 'menuitemcheckbox'\n                                : isSingleSelectionItem\n                                  ? 'menuitemradio'\n                                  : 'menuitem'\n                          }\n                          aria-checked={\n                            !hasCompositeSections && item.showSwitch\n                              ? String(!!item.switchValue)\n                              : isSingleSelectionItem\n                                ? String(!!item.isSelected)\n                                : undefined\n                          }\n                          aria-pressed={\n                            hasCompositeSections\n                              ? String(item.showSwitch ? !!item.switchValue : !!item.isSelected)\n                              : undefined\n                          }\n                          aria-current={\n                            !hasCompositeSections &&\n                            !item.showSwitch &&\n                            !isSingleSelectionItem &&\n                            item.isSelected\n                              ? 'true'\n                              : undefined\n                          }\n                          aria-description={\n                            item.reorderable\n                              ? item.isInactive\n                                ? 'Visibility cannot be changed. Alt + Arrow Up or Alt + Arrow Down moves this row.'\n                                : 'Drag to reorder. Alt + Arrow Up or Alt + Arrow Down moves this row.'\n                              : undefined\n                          }\n                          aria-disabled={item.isInactive ? 'true' : undefined}\n                          disabled={locked}\n                          tabIndex={\n                            hasCompositeSections || (this.embedded && idx === 0)\n                              ? 0\n                              : isFocused\n                                ? 0\n                                : -1\n                          }\n                          onMouseDown={() => {\n                            this.focusRingVisible = false;\n                          }}\n                          onClick={() => this.handleItemClick(item)}\n                          onFocus={() => {\n                            this.focusedIndex = idx;\n                          }}\n                        >\n                          {(dropBefore || dropAfter) && (\n                            <span\n                              class={{\n                                'menu-item__drop-rail': true,\n                                'menu-item__drop-rail--before': dropBefore,\n                                'menu-item__drop-rail--after': dropAfter,\n                              }}\n                              data-menu-drop-rail\n                              aria-hidden=\"true\"\n                            />\n                          )}\n                          {item.reorderable ? (\n                            <span\n                              class=\"menu-item__handle ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\"\n                              data-menu-handle\n                              aria-hidden=\"true\"\n                              onPointerDown={event =>\n                                this.onReorderPointerDown(event, si, itemIndex, idx)\n                              }\n                              onClick={event => {\n                                event.preventDefault();\n                                event.stopPropagation();\n                              }}\n                            >\n                              <ds-icon name=\"Drag\" size={this.size} color=\"inherit\" />\n                            </span>\n                          ) : usesLeading && item.icon ? (\n                            <span\n                              class=\"menu-item__icon ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\"\n                              aria-hidden=\"true\"\n                            >\n                              <ds-icon name={item.icon} size={this.size} color=\"inherit\" />\n                            </span>\n                          ) : usesLeading ? (\n                            <span\n                              class=\"menu-item__icon-spacer ds-choice-item__icon ds-control-icon-box\"\n                              aria-hidden=\"true\"\n                            />\n                          ) : null}\n                          <div class=\"menu-item__content ds-choice-item__content ds-interaction-fill__content\">\n                            <ds-text\n                              class=\"menu-item__label ds-choice-item__label ds-control-label-box\"\n                              as=\"span\"\n                              variant={CONTROL_TEXT_VARIANT[this.size]}\n                              color={item.isSelected ? 'primary' : 'secondary'}\n                            >\n                              {item.label}\n                            </ds-text>\n                            {item.subtext && (\n                              <ds-text\n                                class=\"menu-item__subtext ds-choice-item__subtext ds-control-label-box\"\n                                as=\"span\"\n                                variant={CONTROL_SUPPORTING_TEXT_VARIANT[this.size]}\n                                color=\"secondary\"\n                              >\n                                {item.subtext}\n                              </ds-text>\n                            )}\n                          </div>\n                          {item.tag && (\n                            <ds-tag\n                              class=\"ds-choice-item__tag ds-interaction-fill__content\"\n                              label={item.tag.label}\n                              size={MENU_ITEM_TAG_SIZE[this.size]}\n                              intent={item.tag.intent ?? 'neutral'}\n                              contrast={item.tag.contrast ?? 'faint'}\n                              rounded={item.tag.rounded ?? false}\n                              isInset\n                            />\n                          )}\n                          {item.dot && (\n                            <span\n                              class=\"menu-item__dot-box ds-interaction-fill__content\"\n                              aria-hidden=\"true\"\n                            >\n                              <ds-badge\n                                class=\"menu-item__dot\"\n                                variant=\"dot\"\n                                hasRing={false}\n                                label=\"\"\n                              />\n                            </span>\n                          )}\n                          {item.showSwitch && (\n                            <ds-switch\n                              class=\"menu-item__switch ds-interaction-fill__content\"\n                              size={this.size}\n                              checked={!!item.switchValue}\n                              isInactive={!!item.isInactive}\n                              presentation\n                            />\n                          )}\n                        </button>\n                      );\n                    })\n                  )}\n                </div>\n              ))\n            )}\n          </div>\n        </div>\n        <div class=\"ds-visually-hidden\" role=\"status\" aria-live=\"polite\">\n          {this.reorderAnnouncement}\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Prop,\n  State,\n  Event,\n  EventEmitter,\n  Element,\n  Watch,\n  Listen,\n  h,\n  Host,\n} from '@stencil/core';\nimport {\n  choicePopupMinWidth,\n  CONTROL_SUPPORTING_TEXT_VARIANT,\n  CONTROL_TEXT_VARIANT,\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n  type ChoicePopupAnchorAlignment,\n  type ControlSize,\n} from '../../utils';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\nimport { AnchoredOverlayInteractionController } from '../../utils/anchored-overlay-interaction-controller';\nimport { resolveAnchoredOverlayBoundaryRect } from '../../utils/anchored-overlay-boundary';\nimport { computeAnchoredPosition, type AnchoredPositionInput } from '../../utils/anchored-position';\nimport type { MenuAlign, MenuSide } from './menu-position';\nimport {\n  isMenuPickerSection,\n  isMenuSwatchPickerSection,\n  type MenuItemData,\n  type MenuReorderDetail,\n  type MenuSection,\n} from './menu-types';\nimport { snapshotMenuSections } from './menu-sections';\nimport {\n  createMenuReorderDetail,\n  locateMenuItem,\n  menuReorderableRange,\n  moveReorderableMenuItemBefore,\n  moveReorderableMenuItemBy,\n} from './menu-reorder';\n\nexport type MenuSelectionMode = 'none' | 'single';\nexport type MenuSize = ControlSize;\nlet menuId = 0;\nconst MENU_ITEM_TAG_SIZE: Record<MenuSize, 'md' | 'sm' | 'xs'> = {\n  lg: 'md',\n  md: 'sm',\n  sm: 'xs',\n  xs: 'xs',\n};\n\n@Component({\n  tag: 'ds-menu',\n  styleUrl: 'Menu.css',\n  scoped: true,\n})\nexport class Menu {\n  @Element() el!: HTMLElement;\n\n  /** Render content inside a parent-owned surface; the parent owns dismissal and positioning. */\n  @Prop() embedded: boolean = false;\n  @Prop({ mutable: true }) open: boolean = false;\n  @Prop() items: MenuItemData[] = [];\n  /** Choice-row density. */\n  @Prop() size: MenuSize = 'md';\n  /** Give ordinary rows mutually-exclusive menu semantics using isSelected. */\n  @Prop() selectionMode: MenuSelectionMode = 'none';\n  @Prop() sections: MenuSection[] = [];\n  /** Preferred side; placement flips to the opposite side when that offers a better fit. */\n  @Prop() side: MenuSide = 'bottom';\n  @Prop() align: MenuAlign = 'start';\n  /** Align choice-row edges to the anchor by default; use `popup-frame` only for custom frame geometry. */\n  @Prop() anchorAlignment: ChoicePopupAnchorAlignment = 'choice-cell';\n  /** Gap between anchor and menu — number (px) or TokoMo length (`var(--dimension-space-050)`, etc.). */\n  @Prop() sideOffset: number | string = TOKEN_CSS_LENGTHS.space050;\n  /** Cross-axis offset — number (px) or TokoMo length. */\n  @Prop() alignOffset: number | string = 0;\n  @Prop() menuWidth: string | undefined;\n  @Prop() minWidth: string | undefined;\n  /** External trigger element to position against. Set via JS: menuEl.anchor = buttonEl */\n  @Prop() anchor: HTMLElement | undefined;\n  /** ID of the external trigger element for positioning */\n  @Prop() anchorId: string | undefined;\n  /** Explicit collision owner; otherwise the nearest data-ds-overlay-boundary ancestor is used. */\n  @Prop() boundary: HTMLElement | undefined;\n  /** Show a visible ring on the initially focused menu item. Use only when the opener was keyboard-driven. */\n  @Prop() initialFocusVisible: boolean = false;\n  /** Accessible name for the popup menu. */\n  @Prop() menuLabel: string = 'Menu';\n  /** Informational message shown when there are no choices. Uses a non-modal dialog, not a fake menu item. */\n  @Prop() emptyMessage: string = '';\n\n  @State() private shouldRender: boolean = false;\n  @State() private closing: boolean = false;\n  @State() private pos: { x: number; y: number } = { x: 0, y: 0 };\n  @State() private focusedIndex: number = 0;\n  @State() private positionReady: boolean = false;\n  @State() private availableHeight: number | null = null;\n  @State() private focusRingVisible: boolean = false;\n  @State() private reorderFromFlat: number | null = null;\n  @State() private reorderInsertBefore: number | null = null;\n  @State() private reorderAnnouncement = '';\n\n  @Event() dsClose!: EventEmitter<void>;\n  /** Emitted after the popup's exit motion is complete and its rendered content is removed. */\n  @Event() dsAfterClose!: EventEmitter<void>;\n  @Event() dsSelect!: EventEmitter<MenuItemData>;\n  /** Emitted when a generic `swatch-picker` section option is chosen. */\n  @Event() dsSwatchSelect!: EventEmitter<string>;\n  /** Emitted after a pointer drop or keyboard move; Menu never mutates item order. */\n  @Event() dsReorder!: EventEmitter<MenuReorderDetail>;\n\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n  private positionReadyCallback: (() => void) | undefined;\n  private suppressItemClick = false;\n  private reorderPointer: {\n    pointerId: number;\n    sectionIndex: number;\n    fromIndex: number;\n  } | null = null;\n  /**\n   * Anchored placement. The choice-cell measurement stays here on purpose: the\n   * inner-cell align offset and the `--dimension-menu-width-xs` floor are Menu\n   * semantics, not shared geometry.\n   */\n  private readonly position = new AnchoredPositionController({\n    getAnchor: () => this.resolvedAnchor ?? null,\n    getPopup: () => this.el.querySelector<HTMLElement>('.menu-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    measure: (anchorEl, popup) => {\n      if (!this.open) return null;\n\n      const anchorRect = anchorEl.getBoundingClientRect();\n      const sectionInsetPx = this.viewportPadPx;\n      if (!this.minWidth) {\n        if (\n          this.anchorAlignment === 'choice-cell' &&\n          (this.side === 'top' || this.side === 'bottom')\n        ) {\n          popup.style.minWidth = `max(var(--dimension-menu-width-xs), ${choicePopupMinWidth(\n            anchorRect.width,\n            sectionInsetPx\n          )}px)`;\n        } else {\n          popup.style.removeProperty('min-width');\n        }\n      }\n\n      const viewportPadPx = this.viewportPadPx;\n      const list = popup.querySelector<HTMLElement>('.ds-choice-list');\n      const naturalPopupHeight = Math.min(\n        Math.max(popup.offsetHeight, list?.scrollHeight ?? 0),\n        window.innerHeight - viewportPadPx * 2\n      );\n      const input: AnchoredPositionInput = {\n        anchorRect,\n        popupWidth: popup.offsetWidth || this.popupFallbackWidthPx,\n        popupHeight: naturalPopupHeight || this.popupFallbackHeightPx,\n        side: this.side,\n        align: this.align,\n        sideOffsetPx: this.sideOffsetPx,\n        alignOffsetPx: resolveChoicePopupAlignOffset({\n          align: this.align,\n          alignOffsetPx: this.alignOffsetPx,\n          sectionInsetPx,\n          anchorAlignment: this.anchorAlignment,\n        }),\n        viewportPadPx,\n        viewportWidth: window.innerWidth,\n        viewportHeight: window.innerHeight,\n        collisionRect: resolveAnchoredOverlayBoundaryRect(anchorEl, this.boundary),\n      };\n      const unconstrained = computeAnchoredPosition(input);\n      return {\n        ...input,\n        popupHeight: Math.min(input.popupHeight, unconstrained.availableHeight),\n      };\n    },\n    apply: ({ x, y, availableHeight }) => {\n      this.pos = { x, y };\n      this.availableHeight = availableHeight;\n    },\n    onReady: () => {\n      this.positionReady = true;\n    },\n    liveUpdate: 'double-frame',\n    topLayer: true,\n    observeResize: true,\n    observeAnchorMotion: true,\n  });\n  private readonly interaction = new AnchoredOverlayInteractionController({\n    getAnchor: () => this.resolvedAnchor,\n    getPopup: () => this.el.querySelector<HTMLElement>('.menu-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    onOutsideActivation: () => this.close(),\n  });\n  /** Last content actually painted while open; retained unchanged through exit motion. */\n  private lastRenderedSections: MenuSection[] = [];\n  private closingSections: MenuSection[] | null = null;\n  private readonly emptyMessageId = `ds-menu-empty-${++menuId}`;\n  private lastRenderedEmptyMessage = '';\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  disconnectedCallback() {\n    this.cancelPositionRetry();\n    this.cancelLivePositionUpdate();\n    this.clearReorderPointer();\n    this.teardownListeners();\n  }\n\n  @Watch('open')\n  onOpenChange(isOpen: boolean) {\n    if (this.embedded) return;\n    if (isOpen) {\n      this.teardownListeners();\n      this.closingSections = null;\n      this.shouldRender = true;\n      this.closing = false;\n      this.positionReady = false;\n      this.availableHeight = null;\n      this.focusRingVisible = this.initialFocusVisible;\n      this.setupListeners();\n      this.schedulePositionUpdate(() => {\n        this.focusInitialItem();\n      });\n    } else if (this.shouldRender) {\n      this.positionReadyCallback = undefined;\n      this.cancelPositionRetry();\n      this.captureClosingSections();\n      this.closing = true;\n      this.teardownListeners();\n      const closeAnimationMs = this.closeAnimationMs;\n      if (closeAnimationMs <= 0) {\n        this.finishClose();\n        return;\n      }\n      this.closeTimer = setTimeout(() => {\n        this.closeTimer = null;\n        this.finishClose();\n      }, closeAnimationMs);\n    }\n  }\n\n  @Watch('anchor')\n  @Watch('anchorId')\n  @Watch('boundary')\n  onAnchorChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  @Watch('side')\n  @Watch('align')\n  @Watch('anchorAlignment')\n  @Watch('sideOffset')\n  @Watch('alignOffset')\n  onPositionPropsChange() {\n    if (this.open) this.schedulePositionUpdate();\n  }\n\n  private get viewportPadPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n  }\n\n  private get sideOffsetPx(): number {\n    return resolveCssLengthPx(this.sideOffset, TOKEN_DEFAULTS.space050);\n  }\n\n  private get alignOffsetPx(): number {\n    return resolveCssLengthPx(this.alignOffset, 0);\n  }\n\n  private get popupFallbackWidthPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuWidthXs, TOKEN_DEFAULTS.menuWidthXs);\n  }\n\n  private get popupFallbackHeightPx(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuFallbackHeight, TOKEN_DEFAULTS.menuFallbackHeight);\n  }\n\n  private get closeAnimationMs(): number {\n    return resolveMotionTimeMs(TOKEN_DEFAULTS.motionShort2, TOKEN_DEFAULTS.animationDurationShort3);\n  }\n\n  private finishClose() {\n    const popup = this.el.querySelector<HTMLElement>('.menu-popup');\n    if (popup?.matches(':popover-open')) popup.hidePopover();\n    this.shouldRender = false;\n    this.closing = false;\n    this.lastRenderedSections = [];\n    this.closingSections = null;\n    this.clearReorderPointer();\n    this.reorderAnnouncement = '';\n    this.dsAfterClose.emit();\n  }\n\n  private captureClosingSections() {\n    if (this.closingSections) return;\n    const visibleSections = this.lastRenderedSections.length\n      ? this.lastRenderedSections\n      : this.activeSections;\n    this.closingSections = snapshotMenuSections(visibleSections);\n  }\n\n  private get resolvedAnchor(): HTMLElement | null {\n    if (this.anchor) return this.anchor;\n    if (this.anchorId) return document.getElementById(this.anchorId);\n    return null;\n  }\n\n  private compositeTabLeavesPopup(event: KeyboardEvent): boolean {\n    return this.interaction.tabLeavesPopup(event);\n  }\n\n  private get activeSections(): MenuSection[] {\n    if (this.sections.length > 0) return this.sections;\n    if (this.items.length > 0) return [{ items: this.items }];\n    return [];\n  }\n\n  private get flatItems(): MenuItemData[] {\n    return this.activeSections.flatMap(section =>\n      isMenuPickerSection(section) ? [] : section.items\n    );\n  }\n\n  /** Rich preference content is a non-modal dialog, not an ARIA action menu. */\n  private get hasCompositeSections(): boolean {\n    return this.activeSections.some(isMenuPickerSection);\n  }\n\n  private cancelPositionRetry() {\n    this.position.cancel();\n  }\n\n  private cancelLivePositionUpdate() {\n    this.position.cancel();\n  }\n\n  /** Reposition after the current scroll/layout frame without hiding the open popup. */\n  private scheduleLivePositionUpdate() {\n    this.position.scheduleLiveUpdate();\n  }\n\n  /** Retry until anchor + popup exist — do not reveal at 0,0 on a failed first pass. */\n  private schedulePositionUpdate(onReady?: () => void) {\n    if (!this.open) return;\n    this.positionReady = false;\n    // Opening often sets `open` and `anchorId` together. Each Watch reschedules\n    // placement; keep the open-path ready callback so initial focus is not dropped.\n    if (onReady) this.positionReadyCallback = onReady;\n    const callback = this.positionReadyCallback;\n    this.position.schedule(() => {\n      if (this.positionReadyCallback === callback) {\n        this.positionReadyCallback = undefined;\n      }\n      callback?.();\n    });\n  }\n\n  /** @returns `true` when anchor and popup were found and `pos` was updated. */\n  private calculatePosition(): boolean {\n    return this.position.update();\n  }\n\n  /** Focus the selected item when present, otherwise the first enabled item. */\n  private focusInitialItem() {\n    if (!this.hasCompositeSections && !this.flatItems.length && this.emptyMessage.trim()) {\n      requestAnimationFrame(() => {\n        if (this.open) this.el.querySelector<HTMLElement>('.menu-popup')?.focus();\n      });\n      return;\n    }\n    if (this.hasCompositeSections) {\n      requestAnimationFrame(() => {\n        this.el.querySelector<HTMLElement>('.menu-popup [tabindex=\"0\"]')?.focus();\n      });\n      return;\n    }\n\n    const flat = this.flatItems;\n    const selectedIdx = flat.findIndex(it => it.isSelected && !it.isInactive);\n    const firstEnabledIdx = flat.findIndex(it => !it.isInactive || !!it.reorderable);\n    this.focusedIndex = selectedIdx >= 0 ? selectedIdx : firstEnabledIdx >= 0 ? firstEnabledIdx : 0;\n\n    requestAnimationFrame(() => {\n      const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n      btns[this.focusedIndex]?.focus();\n    });\n  }\n\n  private setupListeners() {\n    this.interaction.connect();\n    this.position.observe();\n  }\n\n  private teardownListeners() {\n    this.position.unobserve();\n    this.interaction.disconnect();\n    if (this.closeTimer) {\n      clearTimeout(this.closeTimer);\n      this.closeTimer = null;\n    }\n  }\n\n  private close(restoreFocus = true) {\n    this.captureClosingSections();\n    if (restoreFocus) this.interaction.focusAnchor();\n    this.dsClose.emit();\n    this.open = false;\n    this.onOpenChange(false);\n  }\n\n  @Listen('keydown')\n  handleKeyDown(e: KeyboardEvent) {\n    if (this.embedded && (e.key === 'Escape' || e.key === 'Tab')) return;\n    if ((!this.shouldRender && !this.embedded) || this.closing) return;\n\n    if (e.key === 'Escape') {\n      e.preventDefault();\n      this.close();\n      return;\n    }\n\n    if (e.key === 'Tab') {\n      if (this.hasCompositeSections && !this.compositeTabLeavesPopup(e)) return;\n      e.preventDefault();\n      this.close(false);\n      this.interaction.moveFocusAfterTab(e.shiftKey);\n      return;\n    }\n\n    if (this.hasCompositeSections) return;\n\n    if ((e.key === 'ArrowUp' || e.key === 'ArrowDown') && e.altKey && !e.ctrlKey && !e.shiftKey) {\n      this.handleReorderKey(e);\n      return;\n    }\n\n    const flat = this.flatItems;\n    const enabled = flat\n      .map((it, i) => ({ it, i }))\n      .filter(({ it }) => !it.isInactive || !!it.reorderable)\n      .map(({ i }) => i);\n    if (!enabled.length) return;\n\n    const cur = enabled.indexOf(this.focusedIndex);\n    const safe = cur < 0 ? 0 : cur;\n\n    switch (e.key) {\n      case 'ArrowDown':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe + 1) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'ArrowUp':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[(safe - 1 + enabled.length) % enabled.length];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'Home':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[0];\n        this.focusItem(this.focusedIndex);\n        break;\n      case 'End':\n        e.preventDefault();\n        e.stopPropagation();\n        this.focusRingVisible = true;\n        this.focusedIndex = enabled[enabled.length - 1];\n        this.focusItem(this.focusedIndex);\n        break;\n    }\n  }\n\n  private focusItem(idx: number) {\n    const btns = this.el.querySelectorAll<HTMLElement>('.menu-item');\n    btns[idx]?.focus();\n  }\n\n  private handleItemClick(item: MenuItemData) {\n    if (this.suppressItemClick) {\n      this.suppressItemClick = false;\n      return;\n    }\n    if (item.isInactive) return;\n    // Consumers commonly change the item source while handling selection.\n    // Capture first so the exit animation never paints the next menu context.\n    this.captureClosingSections();\n    this.dsSelect.emit(item);\n  }\n\n  private handleSwatchSelect(value: string) {\n    this.dsSwatchSelect.emit(value);\n  }\n\n  private handleReorderKey(event: KeyboardEvent): void {\n    const located = locateMenuItem(this.activeSections, this.focusedIndex);\n    if (!located || !located.items[located.itemIndex]?.reorderable) return;\n\n    const nextItems = moveReorderableMenuItemBy(\n      located.items,\n      located.itemIndex,\n      event.key === 'ArrowUp' ? -1 : 1\n    );\n    if (!nextItems) return;\n\n    event.preventDefault();\n    event.stopPropagation();\n    this.emitReorder(located.items, located.itemIndex, nextItems, located.sectionIndex);\n  }\n\n  private emitReorder(\n    items: MenuItemData[],\n    fromIndex: number,\n    nextItems: MenuItemData[],\n    sectionIndex: number\n  ): void {\n    const detail = createMenuReorderDetail(items, fromIndex, nextItems, sectionIndex);\n    if (!detail) return;\n    this.focusedIndex = this.flatIndexFor(sectionIndex, detail.toIndex);\n    this.announceReorder(detail);\n    this.dsReorder.emit(detail);\n  }\n\n  private flatIndexFor(sectionIndex: number, itemIndex: number): number {\n    let flat = 0;\n    for (let index = 0; index < this.activeSections.length; index += 1) {\n      const section = this.activeSections[index];\n      if (isMenuPickerSection(section)) continue;\n      if (index === sectionIndex) return flat + itemIndex;\n      flat += section.items.length;\n    }\n    return itemIndex;\n  }\n\n  private announceReorder(detail: MenuReorderDetail): void {\n    const range = menuReorderableRange(detail.items, detail.toIndex);\n    const count = range ? range.end - range.start + 1 : detail.items.length;\n    const position = range ? detail.toIndex - range.start + 1 : detail.toIndex + 1;\n    this.reorderAnnouncement = `${detail.item.label} moved to position ${position} of ${count}`;\n  }\n\n  private onReorderPointerDown(\n    event: PointerEvent,\n    sectionIndex: number,\n    itemIndex: number,\n    flatIndex: number\n  ): void {\n    if (event.button !== 0) return;\n    const section = this.activeSections[sectionIndex];\n    if (!section || isMenuPickerSection(section)) return;\n    if (!section.items[itemIndex]?.reorderable) return;\n\n    event.preventDefault();\n    event.stopPropagation();\n    this.suppressItemClick = true;\n    this.focusRingVisible = false;\n    this.focusedIndex = flatIndex;\n    this.focusItem(flatIndex);\n    this.reorderPointer = {\n      pointerId: event.pointerId,\n      sectionIndex,\n      fromIndex: itemIndex,\n    };\n    this.reorderFromFlat = flatIndex;\n    this.reorderInsertBefore = itemIndex;\n    window.addEventListener('pointermove', this.onReorderPointerMove);\n    window.addEventListener('pointerup', this.onReorderPointerUp);\n    window.addEventListener('pointercancel', this.onReorderPointerCancel);\n  }\n\n  private onReorderPointerMove = (event: PointerEvent) => {\n    const drag = this.reorderPointer;\n    if (!drag || event.pointerId !== drag.pointerId) return;\n    const section = this.activeSections[drag.sectionIndex];\n    if (!section || isMenuPickerSection(section)) return;\n\n    const insertBefore = this.resolveReorderInsertBefore(\n      event.clientY,\n      drag.sectionIndex,\n      drag.fromIndex,\n      section.items\n    );\n    if (insertBefore !== this.reorderInsertBefore) this.reorderInsertBefore = insertBefore;\n  };\n\n  private onReorderPointerUp = (event: PointerEvent) => {\n    const drag = this.reorderPointer;\n    if (!drag || event.pointerId !== drag.pointerId) return;\n\n    const section = this.activeSections[drag.sectionIndex];\n    const insertBefore = this.reorderInsertBefore;\n    this.clearReorderPointer();\n    queueMicrotask(() => {\n      this.suppressItemClick = false;\n    });\n    if (!section || isMenuPickerSection(section) || insertBefore === null) return;\n\n    const nextItems = moveReorderableMenuItemBefore(section.items, drag.fromIndex, insertBefore);\n    if (!nextItems) return;\n    this.emitReorder(section.items, drag.fromIndex, nextItems, drag.sectionIndex);\n  };\n\n  private onReorderPointerCancel = (event: PointerEvent) => {\n    if (!this.reorderPointer || event.pointerId !== this.reorderPointer.pointerId) return;\n    this.clearReorderPointer();\n    queueMicrotask(() => {\n      this.suppressItemClick = false;\n    });\n  };\n\n  private resolveReorderInsertBefore(\n    clientY: number,\n    sectionIndex: number,\n    fromIndex: number,\n    items: MenuItemData[]\n  ): number {\n    const range = menuReorderableRange(items, fromIndex);\n    if (!range) return fromIndex;\n\n    const buttons = [...this.el.querySelectorAll<HTMLElement>('.menu-item')];\n    const sectionStart = this.flatIndexFor(sectionIndex, 0);\n    let insertBefore = range.end + 1;\n    for (let itemIndex = range.start; itemIndex <= range.end; itemIndex += 1) {\n      const row = buttons[sectionStart + itemIndex];\n      if (!row) continue;\n      const rect = row.getBoundingClientRect();\n      if (clientY < rect.top + rect.height / 2) {\n        insertBefore = itemIndex;\n        break;\n      }\n    }\n    return Math.min(Math.max(insertBefore, range.start), range.end + 1);\n  }\n\n  private clearReorderPointer(): void {\n    if (this.reorderPointer) {\n      window.removeEventListener('pointermove', this.onReorderPointerMove);\n      window.removeEventListener('pointerup', this.onReorderPointerUp);\n      window.removeEventListener('pointercancel', this.onReorderPointerCancel);\n    }\n    this.reorderPointer = null;\n    this.reorderFromFlat = null;\n    this.reorderInsertBefore = null;\n  }\n\n  render() {\n    if (!this.shouldRender && !this.embedded) return <Host style={{ display: 'contents' }} />;\n\n    const sections = this.closing\n      ? (this.closingSections ?? this.lastRenderedSections)\n      : this.activeSections;\n    const hasCompositeSections = sections.some(isMenuPickerSection);\n    const emptyMessage = this.closing ? this.lastRenderedEmptyMessage : this.emptyMessage.trim();\n    const showEmpty =\n      Boolean(emptyMessage) &&\n      !hasCompositeSections &&\n      sections.every(section => !isMenuPickerSection(section) && section.items.length === 0);\n    if (!this.closing) {\n      this.lastRenderedEmptyMessage = emptyMessage;\n      this.lastRenderedSections = snapshotMenuSections(sections);\n      this.closingSections = null;\n    }\n    let flatIdx = 0;\n    const dragLocated =\n      this.reorderFromFlat === null ? null : locateMenuItem(sections, this.reorderFromFlat);\n    const dragRange = dragLocated\n      ? menuReorderableRange(dragLocated.items, dragLocated.itemIndex)\n      : null;\n\n    const popupStyle: Record<string, string> = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.pos.x)}px, ${Math.round(this.pos.y)}px)`,\n      zIndex: '9998',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n\n    if (this.menuWidth) popupStyle['width'] = this.menuWidth;\n    if (this.minWidth) popupStyle['min-width'] = this.minWidth;\n    if (this.availableHeight !== null) {\n      popupStyle['max-height'] = `${Math.floor(this.availableHeight)}px`;\n    }\n\n    return (\n      <Host style={{ display: 'contents' }}>\n        <div\n          popover={this.embedded ? undefined : 'manual'}\n          class={{\n            'menu-popup': true,\n            'menu-popup--closing': this.closing,\n            'ds-choice-popup': !this.embedded,\n            'data-preferences-embedded': this.embedded,\n            'ds-choice-popup--closing': this.closing,\n            'ds-focus-ring': showEmpty,\n            'ds-focus-ring--visible': showEmpty && this.focusRingVisible,\n          }}\n          style={this.embedded ? undefined : popupStyle}\n          role={hasCompositeSections || showEmpty ? 'dialog' : 'menu'}\n          aria-label={this.menuLabel}\n          aria-orientation={hasCompositeSections || showEmpty ? undefined : 'vertical'}\n          aria-describedby={showEmpty ? this.emptyMessageId : undefined}\n          tabIndex={showEmpty ? -1 : undefined}\n        >\n          <div class=\"ds-choice-list\">\n            {showEmpty ? (\n              <ds-text\n                textId={this.emptyMessageId}\n                class=\"menu-empty\"\n                as=\"p\"\n                variant={CONTROL_TEXT_VARIANT[this.size]}\n                color=\"secondary\"\n              >\n                {emptyMessage}\n              </ds-text>\n            ) : (\n              sections.map((section, si) => (\n                <div\n                  key={si}\n                  class={{\n                    'menu-section': true,\n                    'menu-section--divided': si < sections.length - 1,\n                    'menu-section--swatch-picker': isMenuPickerSection(section),\n                    'ds-choice-section': true,\n                    'ds-chrome-column': true,\n                    'ds-chrome-space--sm': true,\n                    'ds-choice-section--divided': si < sections.length - 1,\n                    'ds-choice-section--headed-after-first': si > 0 && Boolean(section.header),\n                  }}\n                  role={section.header ? 'group' : undefined}\n                  aria-label={section.header}\n                >\n                  {section.header && (\n                    <ds-text\n                      class={`section-header ds-choice-section__header ds-control-section-heading ds-control--${this.size}`}\n                      as=\"span\"\n                      variant={CONTROL_SUPPORTING_TEXT_VARIANT[this.size]}\n                      emphasis\n                      color=\"primary\"\n                      aria-hidden=\"true\"\n                    >\n                      <span class=\"ds-choice-section__header-label\">{section.header}</span>\n                    </ds-text>\n                  )}\n                  {isMenuSwatchPickerSection(section) ? (\n                    <ds-swatch-picker\n                      value={section.value}\n                      groupLabel={section.groupLabel ?? section.header ?? 'Swatch options'}\n                      options={section.options ?? []}\n                      sections={section.sections ?? []}\n                      onDsChange={(e: CustomEvent<string>) => {\n                        e.stopPropagation();\n                        this.handleSwatchSelect(e.detail);\n                      }}\n                    />\n                  ) : (\n                    section.items.map((item, itemIndex) => {\n                      const idx = flatIdx++;\n                      const isFocused = this.focusedIndex === idx;\n                      const isSingleSelectionItem =\n                        !hasCompositeSections &&\n                        this.selectionMode === 'single' &&\n                        !item.showSwitch;\n                      const usesLeading = section.items.some(\n                        candidate => candidate.reorderable || !!candidate.icon\n                      );\n                      const locked = !!item.isInactive && !item.reorderable;\n                      const dragging = this.reorderFromFlat === idx;\n                      const dropBefore =\n                        dragLocated?.sectionIndex === si &&\n                        dragRange !== null &&\n                        itemIndex <= dragRange.end &&\n                        this.reorderInsertBefore === itemIndex;\n                      const dropAfter =\n                        dragLocated?.sectionIndex === si &&\n                        dragRange !== null &&\n                        this.reorderInsertBefore === dragRange.end + 1 &&\n                        itemIndex === dragRange.end;\n                      return (\n                        <button\n                          key={item.value ?? `${si}-${item.label}`}\n                          type=\"button\"\n                          class={{\n                            'menu-item': true,\n                            'ds-choice-item': true,\n                            'ds-control-frame': true,\n                            [`ds-control--${this.size}`]: true,\n                            'ds-focus-ring-inset': true,\n                            'ds-focus-ring--visible': isFocused && this.focusRingVisible,\n                            'ds-interaction-fill': !locked,\n                            'ds-interaction-fill--selected': !!item.isSelected && !locked,\n                            'menu-item--selected': !!item.isSelected,\n                            'menu-item--switch': !!item.showSwitch,\n                            'ds-control-inactive': locked,\n                            'menu-item--destructive': !!item.isDestructive,\n                            'menu-item--focused': isFocused,\n                            'menu-item--dragging': dragging,\n                          }}\n                          role={\n                            hasCompositeSections\n                              ? undefined\n                              : item.showSwitch\n                                ? 'menuitemcheckbox'\n                                : isSingleSelectionItem\n                                  ? 'menuitemradio'\n                                  : 'menuitem'\n                          }\n                          aria-checked={\n                            !hasCompositeSections && item.showSwitch\n                              ? String(!!item.switchValue)\n                              : isSingleSelectionItem\n                                ? String(!!item.isSelected)\n                                : undefined\n                          }\n                          aria-pressed={\n                            hasCompositeSections\n                              ? String(item.showSwitch ? !!item.switchValue : !!item.isSelected)\n                              : undefined\n                          }\n                          aria-current={\n                            !hasCompositeSections &&\n                            !item.showSwitch &&\n                            !isSingleSelectionItem &&\n                            item.isSelected\n                              ? 'true'\n                              : undefined\n                          }\n                          aria-description={\n                            item.reorderable\n                              ? item.isInactive\n                                ? 'Visibility cannot be changed. Alt + Arrow Up or Alt + Arrow Down moves this row.'\n                                : 'Drag to reorder. Alt + Arrow Up or Alt + Arrow Down moves this row.'\n                              : undefined\n                          }\n                          aria-disabled={item.isInactive ? 'true' : undefined}\n                          disabled={locked}\n                          tabIndex={\n                            hasCompositeSections || (this.embedded && idx === 0)\n                              ? 0\n                              : isFocused\n                                ? 0\n                                : -1\n                          }\n                          onMouseDown={() => {\n                            this.focusRingVisible = false;\n                          }}\n                          onClick={() => this.handleItemClick(item)}\n                          onFocus={() => {\n                            this.focusedIndex = idx;\n                          }}\n                        >\n                          {(dropBefore || dropAfter) && (\n                            <span\n                              class={{\n                                'menu-item__drop-rail': true,\n                                'menu-item__drop-rail--before': dropBefore,\n                                'menu-item__drop-rail--after': dropAfter,\n                              }}\n                              data-menu-drop-rail\n                              aria-hidden=\"true\"\n                            />\n                          )}\n                          {item.reorderable ? (\n                            <span\n                              class=\"menu-item__handle ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\"\n                              data-menu-handle\n                              aria-hidden=\"true\"\n                              onPointerDown={event =>\n                                this.onReorderPointerDown(event, si, itemIndex, idx)\n                              }\n                              onClick={event => {\n                                event.preventDefault();\n                                event.stopPropagation();\n                              }}\n                            >\n                              <ds-icon name=\"DragDots\" size={this.size} color=\"inherit\" />\n                            </span>\n                          ) : usesLeading && item.icon ? (\n                            <span\n                              class=\"menu-item__icon ds-choice-item__icon ds-control-icon-box ds-interaction-fill__content\"\n                              aria-hidden=\"true\"\n                            >\n                              <ds-icon name={item.icon} size={this.size} color=\"inherit\" />\n                            </span>\n                          ) : usesLeading ? (\n                            <span\n                              class=\"menu-item__icon-spacer ds-choice-item__icon ds-control-icon-box\"\n                              aria-hidden=\"true\"\n                            />\n                          ) : null}\n                          <div class=\"menu-item__content ds-choice-item__content ds-interaction-fill__content\">\n                            <ds-text\n                              class=\"menu-item__label ds-choice-item__label ds-control-label-box\"\n                              as=\"span\"\n                              variant={CONTROL_TEXT_VARIANT[this.size]}\n                              color={item.isSelected ? 'primary' : 'secondary'}\n                            >\n                              {item.label}\n                            </ds-text>\n                            {item.subtext && (\n                              <ds-text\n                                class=\"menu-item__subtext ds-choice-item__subtext ds-control-label-box\"\n                                as=\"span\"\n                                variant={CONTROL_SUPPORTING_TEXT_VARIANT[this.size]}\n                                color=\"secondary\"\n                              >\n                                {item.subtext}\n                              </ds-text>\n                            )}\n                          </div>\n                          {item.tag && (\n                            <ds-tag\n                              class=\"ds-choice-item__tag ds-interaction-fill__content\"\n                              label={item.tag.label}\n                              size={MENU_ITEM_TAG_SIZE[this.size]}\n                              intent={item.tag.intent ?? 'neutral'}\n                              contrast={item.tag.contrast ?? 'faint'}\n                              rounded={item.tag.rounded ?? false}\n                              isInset\n                            />\n                          )}\n                          {item.dot && (\n                            <span\n                              class=\"menu-item__dot-box ds-interaction-fill__content\"\n                              aria-hidden=\"true\"\n                            >\n                              <ds-badge\n                                class=\"menu-item__dot\"\n                                variant=\"dot\"\n                                hasRing={false}\n                                label=\"\"\n                              />\n                            </span>\n                          )}\n                          {item.showSwitch && (\n                            <ds-switch\n                              class=\"menu-item__switch ds-interaction-fill__content\"\n                              size={this.size}\n                              checked={!!item.switchValue}\n                              isInactive={!!item.isInactive}\n                              presentation\n                            />\n                          )}\n                        </button>\n                      );\n                    })\n                  )}\n                </div>\n              ))\n            )}\n          </div>\n        </div>\n        <div class=\"ds-visually-hidden\" role=\"status\" aria-live=\"polite\">\n          {this.reorderAnnouncement}\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {

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

@@ -47,7 +47,12 @@
           "label": "Message metadata composition",
           "path": "src/wc/components/Message/Message.stories.ts"
         }
-      ]
+      ],
+      "styling": {
+        "rationale": "The application may position the action group; child buttons own their appearance.",
+        "protected": [],
+        "customProperties": []
+      }
     },
     "api": {
       "props": {
@@ -163,7 +168,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^6.5.1",
-          "@ds-mo/icons ^7.0.0"
+          "@ds-mo/icons ^8.1.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Vue 3 wrappers; Angular 19-22 standalone adapters."
       }

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

@@ -45,7 +45,32 @@
           "label": "Storybook examples",
           "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
         }
-      ]
+      ],
+      "styling": {
+        "rationale": "The component owns the protected recipes below; unspecified host properties and application layout remain customizable.",
+        "protected": [
+          {
+            "properties": [
+              "background",
+              "border",
+              "box-shadow",
+              "color"
+            ],
+            "reason": "The component owns its surface and interaction treatment; use its semantic presentation props or compose an application-owned surrounding surface.",
+            "props": [
+              "variant"
+            ]
+          },
+          {
+            "properties": [
+              "border-radius"
+            ],
+            "reason": "The component owns its surface radius; retain the shared recipe and customize an outer wrapper when needed.",
+            "props": []
+          }
+        ],
+        "customProperties": []
+      }
     },
     "api": {
       "props": {
@@ -103,7 +128,7 @@
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^6.5.1",
-          "@ds-mo/icons ^7.0.0"
+          "@ds-mo/icons ^8.1.0"
         ],
         "frameworks": "Custom Elements; React 18/19 wrappers; Vue 3 wrappers; Angular 19-22 standalone adapters."
       }