@ds-mo/ui 14.27.1 → 14.29.0

package/dist/mcp-data/registry/button-filled.json

@@ -78,10 +78,11 @@
         "Physical press scaling is on by default. Disable it only when an owning composite must keep child or background geometry fixed; hover and pressed interaction washes remain available.",
         "Visible labels are emphasized by default. Set labelEmphasis to false when a composed surface deliberately needs the button label to match adjacent regular-weight control labels; this does not change the action hierarchy, foreground, icon, or interaction states.",
         "ButtonFilled has no active, pressed, or selected state; a filled action is a command, not a toggle or a persistent selection.",
-        "An open popup is a transient pressed state instead. While expanded is true the pressed wash is held for the popup's complete rendered lifecycle and survives hover, so the trigger reads as held open without introducing a selected treatment.",
+        "An open popup is a transient pressed state instead. While surfaceOpen is true the pressed wash is held for the popup's complete rendered lifecycle and survives hover, so the trigger reads as held open without introducing a selected treatment.",
         "hasMenu supports only the label and icon-label variants. The chevron is what communicates that a menu will open, so an icon-only filled menu button would leave the affordance unstated.",
         "Split mode supports label, icon, and icon-label primary segments. The primary segment emits dsClick and the appended menu segment emits dsMenuClick.",
-        "Split mode keeps both segments flush and uses a tertiary on-background separator. Rounded changes the shared outer radius without separating the segments."
+        "Split mode keeps both segments flush and uses a tertiary on-background separator. Rounded changes the shared outer radius without separating the segments.",
+        "Use surfaceOpen to identify this command as the owner of a visible menu, picker, or panel, even when that surface is distant. Keep the pressed wash through exit motion without adding selected styling or sustained physical scaling. Inline expansion and completed commands do not acquire this treatment."
       ],
       "responsiveBehavior": [
         "Use fill width only when the parent layout calls for a full-width action, commonly on narrow form layouts."
@@ -101,6 +102,10 @@
         {
           "label": "Storybook examples",
           "path": "src/wc/components/ButtonFilled/ButtonFilled.stories.ts"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -146,7 +151,7 @@
           "attribute": "expanded",
           "required": false,
           "mutable": false,
-          "description": "Controlled open state of the popup this button triggers. Holds the pressed\nwash for the popup's rendered lifecycle. ButtonFilled has no selected state,\nso an open popup never promotes to an active treatment."
+          "description": "Controlled disclosure state forwarded to aria-expanded.\nUsing expanded alone for surface-open styling is deprecated; set surfaceOpen\nexplicitly to separate the rendered surface lifecycle from disclosure state."
         },
         "hasBorder": {
           "type": "boolean",
@@ -291,6 +296,14 @@
           "mutable": false,
           "description": "Append a separate ChevronDown menu segment while preserving this button's\nvariant, size, intent, contrast, loading, inactive, and width treatment."
         },
+        "surfaceOpen": {
+          "type": "boolean | undefined",
+          "resolvedType": "boolean | undefined",
+          "attribute": "surface-open",
+          "required": false,
+          "mutable": false,
+          "description": "The associated menu, picker, or panel is visible, including its exit motion.\nHolds only the pressed wash; does not set ARIA, selection, or press scaling.\nIn split mode this applies only to the menu segment. Explicit false disables\nthe legacy expanded-derived wash; omission preserves that compatibility path."
+        },
         "type": {
           "type": "'button' | 'submit' | 'reset'",
           "resolvedType": "\"button\" | \"reset\" | \"submit\"",
@@ -384,7 +397,7 @@
         "attribute": "expanded",
         "required": false,
         "mutable": false,
-        "description": "Controlled open state of the popup this button triggers. Holds the pressed\nwash for the popup's rendered lifecycle. ButtonFilled has no selected state,\nso an open popup never promotes to an active treatment."
+        "description": "Controlled disclosure state forwarded to aria-expanded.\nUsing expanded alone for surface-open styling is deprecated; set surfaceOpen\nexplicitly to separate the rendered surface lifecycle from disclosure state."
       },
       "hasBorder": {
         "type": "boolean",
@@ -529,6 +542,14 @@
         "mutable": false,
         "description": "Append a separate ChevronDown menu segment while preserving this button's\nvariant, size, intent, contrast, loading, inactive, and width treatment."
       },
+      "surfaceOpen": {
+        "type": "boolean | undefined",
+        "resolvedType": "boolean | undefined",
+        "attribute": "surface-open",
+        "required": false,
+        "mutable": false,
+        "description": "The associated menu, picker, or panel is visible, including its exit motion.\nHolds only the pressed wash; does not set ARIA, selection, or press scaling.\nIn split mode this applies only to the menu segment. Explicit false disables\nthe legacy expanded-derived wash; omission preserves that compatibility path."
+      },
       "type": {
         "type": "'button' | 'submit' | 'reset'",
         "resolvedType": "\"button\" | \"reset\" | \"submit\"",
@@ -633,7 +654,7 @@
     },
     {
       "path": "src/wc/components/ButtonFilled/ButtonFilled.tsx",
-      "content": "import { Component, Element, Event, EventEmitter, h, Host, Method, Prop } from '@stencil/core';\nimport { controlWidthClass } from '../../utils';\nimport type { ChoiceBackground } from '../../utils/choice-list';\nimport { beginElevatedControlPress } from '../../utils/control-press';\nimport { renderButtonContent } from '../../utils/button-render';\nimport type { ControlInsetDepth } from '../../utils/control-text';\nimport type { ButtonPopup, ButtonSize, ButtonVariant, ButtonWidth } from '../../utils/button-types';\n\nexport type ButtonFilledIntent =\n  | 'neutral'\n  | 'brand'\n  | 'ai'\n  | 'negative'\n  | 'warning'\n  | 'caution'\n  | 'positive'\n  | 'guide'\n  | 'walkthrough';\n\nexport type ButtonFilledContrast = 'bold' | 'strong' | 'medium' | 'faint';\n\nexport type ButtonFilledBackground = ChoiceBackground;\n\nexport type ButtonFilledVariant = ButtonVariant;\nexport type ButtonFilledSize = ButtonSize;\nexport type ButtonFilledWidth = ButtonWidth;\nexport type ButtonFilledPopup = ButtonPopup;\n\n@Component({\n  tag: 'ds-button-filled',\n  styleUrl: 'ButtonFilled.css',\n  scoped: true,\n})\nexport class ButtonFilled {\n  @Element() el!: HTMLElement;\n\n  /**\n   * Content layout. Default is label-only; pass `icon` for icon-only chrome\n   * (nav / tool rails) or `icon-label` for leading icon + text.\n   */\n  @Prop() variant: ButtonFilledVariant = 'label';\n\n  /** Control density (height, padding, icon, type). */\n  @Prop() size: ButtonFilledSize = 'md';\n\n  /** Use reduced outer geometry when nested inside a control of the same size. */\n  @Prop() isInset: boolean = false;\n\n  /** Single removes 4px overall; double removes 8px overall (xs stays single). */\n  @Prop() insetDepth: ControlInsetDepth = 'single';\n\n  /** Width fit — hug content (default) or fill the parent. */\n  @Prop() width: ButtonFilledWidth = 'hug';\n\n  /** Visible text for `label` / `icon-label` variants. */\n  @Prop() label: string = '';\n\n  /** Whether the visible label uses the emphasized weight. */\n  @Prop() labelEmphasis: boolean = true;\n\n  /** Icon name passed to <ds-icon> for `icon` / `icon-label` variants. */\n  @Prop() icon: string = '';\n\n  /** Semantic colour intent. */\n  @Prop() intent: ButtonFilledIntent = 'brand';\n\n  /**\n   * Background fill weight. Foreground uses the paired contrast token:\n   * bold → faint, strong → medium, medium → strong, faint → bold.\n   */\n  @Prop() contrast: ButtonFilledContrast = 'bold';\n\n  /** Show a 1px secondary inset border. */\n  @Prop() hasBorder: boolean = false;\n\n  /**\n   * Actual parent surface context for the optional inset border color only.\n   * Omit on primary and secondary surfaces.\n   */\n  @Prop() background: ButtonFilledBackground | undefined;\n\n  /** Use the half-radius treatment instead of the default control radius. */\n  @Prop() rounded: boolean = false;\n\n  /**\n   * Scale down during a physical pointer press.\n   * Disable when an owning composite requires fixed child or background geometry.\n   */\n  @Prop() pressScale: boolean = true;\n\n  /** Disables interaction. */\n  @Prop() isInactive: boolean = false;\n\n  /** Shows an inline loader and prevents interaction without applying inactive opacity. */\n  @Prop() isLoading: boolean = false;\n\n  /** Native button type. */\n  @Prop() type: 'button' | 'submit' | 'reset' = 'button';\n\n  /** Accessible name override. Required for icon-only buttons. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n\n  /** ID of the popup this button controls. */\n  @Prop() controls: string | undefined;\n\n  /**\n   * Controlled open state of the popup this button triggers. Holds the pressed\n   * wash for the popup's rendered lifecycle. ButtonFilled has no selected state,\n   * so an open popup never promotes to an active treatment.\n   */\n  @Prop() expanded: boolean | undefined;\n\n  /** Popup type exposed to assistive technology. */\n  @Prop() haspopup: ButtonFilledPopup | undefined;\n\n  /**\n   * Append a separate ChevronDown menu segment while preserving this button's\n   * variant, size, intent, contrast, loading, inactive, and width treatment.\n   */\n  @Prop() split: boolean = false;\n\n  /** Accessible name for the appended menu segment in split mode. */\n  @Prop() menuAriaLabel: string = 'More options';\n\n  /**\n   * This action *has* a menu: implies `aria-haspopup=\"menu\"` and adds the trailing\n   * chevron that carries the affordance.\n   *\n   * Only `label` and `icon-label` are supported. A filled button is never the\n   * overflow / more-options control — that role belongs to ButtonUnfilled with an\n   * `Ellipses` glyph, which conveys the menu without a chevron.\n   *\n   * Use `haspopup` directly for non-menu popups.\n   */\n  @Prop() hasMenu: boolean = false;\n\n  @Event() dsClick!: EventEmitter<MouseEvent>;\n  @Event() dsMenuClick!: EventEmitter<MouseEvent>;\n\n  private buttonEl: HTMLButtonElement | null = null;\n  private menuButtonEl: HTMLButtonElement | null = null;\n\n  @Method()\n  async setFocus(segment: 'primary' | 'menu' = 'primary') {\n    (segment === 'menu' ? this.menuButtonEl : this.buttonEl)?.focus();\n  }\n\n  private handleClick = (event: MouseEvent) => {\n    if (this.isInactive || this.isLoading) {\n      event.preventDefault();\n      event.stopPropagation();\n      return;\n    }\n    this.dsClick.emit(event);\n  };\n\n  private handleMenuClick = (event: MouseEvent) => {\n    if (this.isInactive || this.isLoading) {\n      event.preventDefault();\n      event.stopPropagation();\n      return;\n    }\n    this.dsMenuClick.emit(event);\n  };\n\n  private get resolvedHaspopup(): ButtonFilledPopup | undefined {\n    return this.haspopup ?? (this.hasMenu ? 'menu' : undefined);\n  }\n\n  private get accessibleName(): string | undefined {\n    if (this.ariaLabel) return this.ariaLabel;\n    if (this.isLoading && this.variant === 'label' && this.label) return this.label;\n    return undefined;\n  }\n\n  private get doubleInset(): boolean {\n    return this.isInset && this.insetDepth === 'double' && this.size !== 'xs';\n  }\n\n  private buttonClass(\n    variant: ButtonFilledVariant,\n    expanded: boolean,\n    bordered: boolean\n  ): Record<string, boolean> {\n    const cls: Record<string, boolean> = {\n      'button-filled': true,\n      'ds-button': true,\n      'ds-focus-ring-inset': true,\n      'ds-control-press-scale': this.pressScale && !this.split,\n      'ds-interaction-fill': !this.isInactive,\n      /* Bold is the default filled contrast — on-bold interaction tokens. */\n      'ds-interaction-fill--on-bold': this.contrast === 'bold',\n      'ds-interaction-fill--on-strong': this.contrast === 'strong',\n      'ds-interaction-fill--on-medium': this.contrast === 'medium',\n      /* faint → default app interaction tokens (no --on-*). */\n      'button-filled--bordered': bordered,\n      'ds-button--bordered': bordered,\n      'button-filled--expanded': expanded && !this.isInactive,\n      'ds-button--expanded': expanded && !this.isInactive,\n      'ds-control-inactive': this.isInactive,\n      'ds-control--lg': this.size === 'lg',\n      'ds-control--md': this.size === 'md',\n      'ds-control--sm': this.size === 'sm',\n      'ds-control--xs': this.size === 'xs',\n      'ds-control--inset': this.isInset && !this.doubleInset,\n      'ds-control--inset-double': this.doubleInset,\n      'ds-control-frame': true,\n      'button-filled--icon': variant === 'icon',\n      'ds-button--icon': variant === 'icon',\n      'button-filled--label': variant === 'label',\n      'button-filled--icon-label': variant === 'icon-label',\n      'button-filled--rounded': this.rounded,\n      'ds-button--rounded': this.rounded,\n      [`button-filled--background-${this.background}`]: this.background !== undefined,\n      [`button-filled--intent-${this.intent}`]: true,\n      [`button-filled--contrast-${this.contrast}`]: true,\n    };\n    return cls;\n  }\n\n  render() {\n    const primaryButton = (\n      <button\n        ref={el => {\n          this.buttonEl = el ?? null;\n        }}\n        type={this.type}\n        class={{\n          ...this.buttonClass(\n            this.variant,\n            !this.split && this.expanded === true,\n            this.hasBorder && !this.split\n          ),\n          'ds-button-split__primary': this.split,\n        }}\n        disabled={this.isInactive}\n        aria-label={this.accessibleName}\n        aria-busy={this.isLoading ? 'true' : undefined}\n        aria-disabled={this.isLoading ? 'true' : undefined}\n        aria-controls={this.split ? undefined : this.controls}\n        aria-expanded={\n          this.split || this.expanded === undefined ? undefined : String(this.expanded)\n        }\n        aria-haspopup={this.split ? undefined : this.resolvedHaspopup}\n        onPointerDown={event =>\n          beginElevatedControlPress(\n            event,\n            this.pressScale && !this.split && !this.isInactive && !this.isLoading\n          )\n        }\n        onClick={this.handleClick}\n      >\n        {renderButtonContent({\n          namespace: 'button-filled',\n          variant: this.variant,\n          size: this.size,\n          label: this.label,\n          labelEmphasis: this.labelEmphasis,\n          icon: this.icon,\n          hasMenu: !this.split && this.hasMenu,\n          isLoading: this.isLoading,\n        })}\n      </button>\n    );\n\n    const control = this.split ? (\n      <div\n        class={{\n          'ds-button-split': true,\n          'ds-button-split--rounded': this.rounded,\n        }}\n      >\n        {primaryButton}\n        <span class=\"ds-button-split__divider\" aria-hidden=\"true\" />\n        <button\n          ref={el => {\n            this.menuButtonEl = el ?? null;\n          }}\n          class={{\n            ...this.buttonClass('icon', this.expanded === true, false),\n            'ds-button-split__menu': true,\n          }}\n          type=\"button\"\n          disabled={this.isInactive || this.isLoading}\n          aria-label={this.menuAriaLabel}\n          aria-controls={this.controls}\n          aria-expanded={String(this.expanded === true)}\n          aria-haspopup=\"menu\"\n          onClick={this.handleMenuClick}\n        >\n          {renderButtonContent({\n            namespace: 'button-filled',\n            variant: 'icon',\n            size: this.size,\n            label: '',\n            labelEmphasis: true,\n            icon: 'ChevronDown',\n            hasMenu: false,\n            isLoading: false,\n          })}\n        </button>\n        {this.hasBorder ? <span class=\"ds-button-split__outline\" aria-hidden=\"true\" /> : null}\n      </div>\n    ) : (\n      primaryButton\n    );\n\n    return (\n      <Host\n        class={{\n          'button-filled-host': true,\n          'button-filled-host--icon': this.variant === 'icon' && !this.split,\n          'ds-button-host--icon': this.variant === 'icon' && !this.split,\n          'ds-button-split-host': this.split,\n          'ds-button-split-host--primary-icon': this.split && this.variant === 'icon',\n          [`button-filled-host--contrast-${this.contrast}`]: this.split,\n          [`button-filled-host--background-${this.background}`]:\n            this.split && this.background !== undefined,\n          'ds-control--lg': this.size === 'lg',\n          'ds-control--md': this.size === 'md',\n          'ds-control--sm': this.size === 'sm',\n          'ds-control--xs': this.size === 'xs',\n          'ds-control--inset': this.isInset && !this.doubleInset,\n          'ds-control--inset-double': this.doubleInset,\n          ...controlWidthClass(this.width),\n        }}\n        tabIndex={-1}\n      >\n        {control}\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, Event, EventEmitter, h, Host, Method, Prop } from '@stencil/core';\nimport { controlWidthClass } from '../../utils';\nimport type { ChoiceBackground } from '../../utils/choice-list';\nimport { beginElevatedControlPress } from '../../utils/control-press';\nimport { renderButtonContent } from '../../utils/button-render';\nimport type { ControlInsetDepth } from '../../utils/control-text';\nimport type { ButtonPopup, ButtonSize, ButtonVariant, ButtonWidth } from '../../utils/button-types';\n\nexport type ButtonFilledIntent =\n  | 'neutral'\n  | 'brand'\n  | 'ai'\n  | 'negative'\n  | 'warning'\n  | 'caution'\n  | 'positive'\n  | 'guide'\n  | 'walkthrough';\n\nexport type ButtonFilledContrast = 'bold' | 'strong' | 'medium' | 'faint';\n\nexport type ButtonFilledBackground = ChoiceBackground;\n\nexport type ButtonFilledVariant = ButtonVariant;\nexport type ButtonFilledSize = ButtonSize;\nexport type ButtonFilledWidth = ButtonWidth;\nexport type ButtonFilledPopup = ButtonPopup;\n\n@Component({\n  tag: 'ds-button-filled',\n  styleUrl: 'ButtonFilled.css',\n  scoped: true,\n})\nexport class ButtonFilled {\n  @Element() el!: HTMLElement;\n\n  /**\n   * Content layout. Default is label-only; pass `icon` for icon-only chrome\n   * (nav / tool rails) or `icon-label` for leading icon + text.\n   */\n  @Prop() variant: ButtonFilledVariant = 'label';\n\n  /** Control density (height, padding, icon, type). */\n  @Prop() size: ButtonFilledSize = 'md';\n\n  /** Use reduced outer geometry when nested inside a control of the same size. */\n  @Prop() isInset: boolean = false;\n\n  /** Single removes 4px overall; double removes 8px overall (xs stays single). */\n  @Prop() insetDepth: ControlInsetDepth = 'single';\n\n  /** Width fit — hug content (default) or fill the parent. */\n  @Prop() width: ButtonFilledWidth = 'hug';\n\n  /** Visible text for `label` / `icon-label` variants. */\n  @Prop() label: string = '';\n\n  /** Whether the visible label uses the emphasized weight. */\n  @Prop() labelEmphasis: boolean = true;\n\n  /** Icon name passed to <ds-icon> for `icon` / `icon-label` variants. */\n  @Prop() icon: string = '';\n\n  /** Semantic colour intent. */\n  @Prop() intent: ButtonFilledIntent = 'brand';\n\n  /**\n   * Background fill weight. Foreground uses the paired contrast token:\n   * bold → faint, strong → medium, medium → strong, faint → bold.\n   */\n  @Prop() contrast: ButtonFilledContrast = 'bold';\n\n  /** Show a 1px secondary inset border. */\n  @Prop() hasBorder: boolean = false;\n\n  /**\n   * Actual parent surface context for the optional inset border color only.\n   * Omit on primary and secondary surfaces.\n   */\n  @Prop() background: ButtonFilledBackground | undefined;\n\n  /** Use the half-radius treatment instead of the default control radius. */\n  @Prop() rounded: boolean = false;\n\n  /**\n   * Scale down during a physical pointer press.\n   * Disable when an owning composite requires fixed child or background geometry.\n   */\n  @Prop() pressScale: boolean = true;\n\n  /** Disables interaction. */\n  @Prop() isInactive: boolean = false;\n\n  /** Shows an inline loader and prevents interaction without applying inactive opacity. */\n  @Prop() isLoading: boolean = false;\n\n  /** Native button type. */\n  @Prop() type: 'button' | 'submit' | 'reset' = 'button';\n\n  /** Accessible name override. Required for icon-only buttons. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n\n  /** ID of the popup this button controls. */\n  @Prop() controls: string | undefined;\n\n  /**\n   * Controlled disclosure state forwarded to aria-expanded.\n   * Using expanded alone for surface-open styling is deprecated; set surfaceOpen\n   * explicitly to separate the rendered surface lifecycle from disclosure state.\n   */\n  @Prop() expanded: boolean | undefined;\n\n  /**\n   * The associated menu, picker, or panel is visible, including its exit motion.\n   * Holds only the pressed wash; does not set ARIA, selection, or press scaling.\n   * In split mode this applies only to the menu segment. Explicit false disables\n   * the legacy expanded-derived wash; omission preserves that compatibility path.\n   */\n  @Prop() surfaceOpen: boolean | undefined;\n\n  /** Popup type exposed to assistive technology. */\n  @Prop() haspopup: ButtonFilledPopup | undefined;\n\n  /**\n   * Append a separate ChevronDown menu segment while preserving this button's\n   * variant, size, intent, contrast, loading, inactive, and width treatment.\n   */\n  @Prop() split: boolean = false;\n\n  /** Accessible name for the appended menu segment in split mode. */\n  @Prop() menuAriaLabel: string = 'More options';\n\n  /**\n   * This action *has* a menu: implies `aria-haspopup=\"menu\"` and adds the trailing\n   * chevron that carries the affordance.\n   *\n   * Only `label` and `icon-label` are supported. A filled button is never the\n   * overflow / more-options control — that role belongs to ButtonUnfilled with an\n   * `Ellipses` glyph, which conveys the menu without a chevron.\n   *\n   * Use `haspopup` directly for non-menu popups.\n   */\n  @Prop() hasMenu: boolean = false;\n\n  @Event() dsClick!: EventEmitter<MouseEvent>;\n  @Event() dsMenuClick!: EventEmitter<MouseEvent>;\n\n  private buttonEl: HTMLButtonElement | null = null;\n  private menuButtonEl: HTMLButtonElement | null = null;\n\n  @Method()\n  async setFocus(segment: 'primary' | 'menu' = 'primary') {\n    (segment === 'menu' ? this.menuButtonEl : this.buttonEl)?.focus();\n  }\n\n  private handleClick = (event: MouseEvent) => {\n    if (this.isInactive || this.isLoading) {\n      event.preventDefault();\n      event.stopPropagation();\n      return;\n    }\n    this.dsClick.emit(event);\n  };\n\n  private handleMenuClick = (event: MouseEvent) => {\n    if (this.isInactive || this.isLoading) {\n      event.preventDefault();\n      event.stopPropagation();\n      return;\n    }\n    this.dsMenuClick.emit(event);\n  };\n\n  private get resolvedHaspopup(): ButtonFilledPopup | undefined {\n    return this.haspopup ?? (this.hasMenu ? 'menu' : undefined);\n  }\n\n  private get resolvedSurfaceOpen(): boolean {\n    return (this.surfaceOpen ?? this.expanded === true) && !this.isInactive;\n  }\n\n  private get accessibleName(): string | undefined {\n    if (this.ariaLabel) return this.ariaLabel;\n    if (this.isLoading && this.variant === 'label' && this.label) return this.label;\n    return undefined;\n  }\n\n  private get doubleInset(): boolean {\n    return this.isInset && this.insetDepth === 'double' && this.size !== 'xs';\n  }\n\n  private buttonClass(\n    variant: ButtonFilledVariant,\n    expanded: boolean,\n    bordered: boolean\n  ): Record<string, boolean> {\n    const cls: Record<string, boolean> = {\n      'button-filled': true,\n      'ds-button': true,\n      'ds-focus-ring-inset': true,\n      'ds-control-press-scale': this.pressScale && !this.split,\n      'ds-interaction-fill': !this.isInactive,\n      /* Bold is the default filled contrast — on-bold interaction tokens. */\n      'ds-interaction-fill--on-bold': this.contrast === 'bold',\n      'ds-interaction-fill--on-strong': this.contrast === 'strong',\n      'ds-interaction-fill--on-medium': this.contrast === 'medium',\n      /* faint → default app interaction tokens (no --on-*). */\n      'button-filled--bordered': bordered,\n      'ds-button--bordered': bordered,\n      'button-filled--expanded': expanded && !this.isInactive,\n      'ds-interaction-fill--surface-open': expanded,\n      'ds-button--expanded': expanded && !this.isInactive,\n      'ds-control-inactive': this.isInactive,\n      'ds-control--lg': this.size === 'lg',\n      'ds-control--md': this.size === 'md',\n      'ds-control--sm': this.size === 'sm',\n      'ds-control--xs': this.size === 'xs',\n      'ds-control--inset': this.isInset && !this.doubleInset,\n      'ds-control--inset-double': this.doubleInset,\n      'ds-control-frame': true,\n      'button-filled--icon': variant === 'icon',\n      'ds-button--icon': variant === 'icon',\n      'button-filled--label': variant === 'label',\n      'button-filled--icon-label': variant === 'icon-label',\n      'button-filled--rounded': this.rounded,\n      'ds-button--rounded': this.rounded,\n      [`button-filled--background-${this.background}`]: this.background !== undefined,\n      [`button-filled--intent-${this.intent}`]: true,\n      [`button-filled--contrast-${this.contrast}`]: true,\n    };\n    return cls;\n  }\n\n  render() {\n    const primaryButton = (\n      <button\n        ref={el => {\n          this.buttonEl = el ?? null;\n        }}\n        type={this.type}\n        class={{\n          ...this.buttonClass(\n            this.variant,\n            !this.split && this.resolvedSurfaceOpen,\n            this.hasBorder && !this.split\n          ),\n          'ds-button-split__primary': this.split,\n        }}\n        disabled={this.isInactive}\n        aria-label={this.accessibleName}\n        aria-busy={this.isLoading ? 'true' : undefined}\n        aria-disabled={this.isLoading ? 'true' : undefined}\n        aria-controls={this.split ? undefined : this.controls}\n        aria-expanded={\n          this.split || this.expanded === undefined ? undefined : String(this.expanded)\n        }\n        aria-haspopup={this.split ? undefined : this.resolvedHaspopup}\n        onPointerDown={event =>\n          beginElevatedControlPress(\n            event,\n            this.pressScale && !this.split && !this.isInactive && !this.isLoading\n          )\n        }\n        onClick={this.handleClick}\n      >\n        {renderButtonContent({\n          namespace: 'button-filled',\n          variant: this.variant,\n          size: this.size,\n          label: this.label,\n          labelEmphasis: this.labelEmphasis,\n          icon: this.icon,\n          hasMenu: !this.split && this.hasMenu,\n          isLoading: this.isLoading,\n        })}\n      </button>\n    );\n\n    const control = this.split ? (\n      <div\n        class={{\n          'ds-button-split': true,\n          'ds-button-split--rounded': this.rounded,\n        }}\n      >\n        {primaryButton}\n        <span class=\"ds-button-split__divider\" aria-hidden=\"true\" />\n        <button\n          ref={el => {\n            this.menuButtonEl = el ?? null;\n          }}\n          class={{\n            ...this.buttonClass('icon', this.resolvedSurfaceOpen, false),\n            'ds-button-split__menu': true,\n          }}\n          type=\"button\"\n          disabled={this.isInactive || this.isLoading}\n          aria-label={this.menuAriaLabel}\n          aria-controls={this.controls}\n          aria-expanded={String(this.expanded === true)}\n          aria-haspopup=\"menu\"\n          onClick={this.handleMenuClick}\n        >\n          {renderButtonContent({\n            namespace: 'button-filled',\n            variant: 'icon',\n            size: this.size,\n            label: '',\n            labelEmphasis: true,\n            icon: 'ChevronDown',\n            hasMenu: false,\n            isLoading: false,\n          })}\n        </button>\n        {this.hasBorder ? <span class=\"ds-button-split__outline\" aria-hidden=\"true\" /> : null}\n      </div>\n    ) : (\n      primaryButton\n    );\n\n    return (\n      <Host\n        class={{\n          'button-filled-host': true,\n          'button-filled-host--icon': this.variant === 'icon' && !this.split,\n          'ds-button-host--icon': this.variant === 'icon' && !this.split,\n          'ds-button-split-host': this.split,\n          'ds-button-split-host--primary-icon': this.split && this.variant === 'icon',\n          [`button-filled-host--contrast-${this.contrast}`]: this.split,\n          [`button-filled-host--background-${this.background}`]:\n            this.split && this.background !== undefined,\n          'ds-control--lg': this.size === 'lg',\n          'ds-control--md': this.size === 'md',\n          'ds-control--sm': this.size === 'sm',\n          'ds-control--xs': this.size === 'xs',\n          'ds-control--inset': this.isInset && !this.doubleInset,\n          'ds-control--inset-double': this.doubleInset,\n          ...controlWidthClass(this.width),\n        }}\n        tabIndex={-1}\n      >\n        {control}\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/button-unfilled.json

@@ -55,7 +55,7 @@
       "accessibility": [
         "Provide an explicit accessible name for every icon-only action.",
         "In split mode, provide menuAriaLabel for the appended ChevronDown segment, pass controls with the Menu id, and synchronize expanded with the Menu open state.",
-        "Set hasMenu when the button triggers a Menu; it implies aria-haspopup of menu. Pass controls with the Menu id and expanded from the same open state given to Menu. Expanded popup triggers hold only the pressed wash while open, without changing their resting foreground; expanded disclosure controls without popup semantics retain the normal resting appearance.",
+        "Set hasMenu when the button triggers a Menu; it implies aria-haspopup of menu. Pass controls with the Menu id and expanded from the same open state given to Menu. Surface-open popup triggers hold only the pressed wash while rendered, without changing their resting foreground; expanded disclosure controls without popup semantics retain the normal resting appearance.",
         "Give an icon-only menu button an accessible name that states the role, such as More options or Customize table, because no visible label or chevron carries it.",
         "Use haspopup directly for a non-menu popup such as a listbox or dialog; those cases get no chevron.",
         "Use pressed only for a genuine toggle button; it supplies aria-pressed and dsChange intent. Use isActive only for owner-controlled visual emphasis inside a composite whose selection semantics live on the owner.",
@@ -80,9 +80,10 @@
         "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width.",
         "hasMenu covers two distinct menu-button shapes and the variant selects between them. With label or icon-label the action has a menu, and a trailing chevron carries the affordance. With icon the button is a menu and no chevron is added.",
         "Because the icon-only shape has no chevron, its glyph must convey the menu on its own. Use Ellipses for a generic more-options or overflow control. Use a specific icon when the menu has a named purpose, such as Table for Customize table.",
-        "An open popup is a transient pressed state rather than a selected one. While expanded is true and haspopup or hasMenu identifies a popup, the pressed wash is held for the popup's complete rendered lifecycle and survives hover without promoting foreground or selected fill, including when chrome opts out of selected fills with activeFill set to false. Expanded disclosure buttons without popup semantics remain visually neutral.",
+        "An open popup is a transient pressed state rather than a selected one. While surfaceOpen is true, the pressed wash is held for the popup's complete rendered lifecycle and survives hover without promoting foreground or selected fill, including when chrome opts out of selected fills with activeFill set to false. Expanded disclosure buttons without popup semantics remain visually neutral.",
         "Split mode supports label, icon, and icon-label primary segments. The primary segment emits dsClick and the appended menu segment emits dsMenuClick.",
-        "Split mode keeps both segments flush and uses a tertiary surface-aware separator. Bordered mode also preserves the shared outer border; borderless mode limits the separator to the content line height."
+        "Split mode keeps both segments flush and uses a tertiary surface-aware separator. Bordered mode also preserves the shared outer border; borderless mode limits the separator to the content line height.",
+        "Use surfaceOpen to identify the owner of a visible menu, picker, or panel, even when it is distant. Preserve it through exit motion independently of expanded semantics, pressed toggles, and isActive selection. It preserves resting foreground and does not hold physical scaling. Inline expansion and last-click history do not acquire this treatment."
       ],
       "responsiveBehavior": [
         "The consuming layout decides when an icon-label action becomes icon-only and must provide an explicit accessible name after changing variants. Table caption Customize is one such layout: below 900px it uses the icon shape while keeping the same neutral resting foreground regardless of the controlled column configuration.",
@@ -105,6 +106,10 @@
         {
           "label": "Storybook examples",
           "path": "src/wc/components/ButtonUnfilled/ButtonUnfilled.stories.ts"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -167,7 +172,7 @@
           "attribute": "expanded",
           "required": false,
           "mutable": false,
-          "description": "Controlled disclosure or popup state forwarded to `aria-expanded`.\nPopup triggers hold only the pressed wash while open; their resting\nforeground is unchanged. Ordinary disclosures remain visually neutral."
+          "description": "Controlled disclosure state forwarded to aria-expanded.\nUsing expanded alone for surface-open styling is deprecated; set surfaceOpen\nexplicitly to separate the rendered surface lifecycle from disclosure state."
         },
         "focusTabIndex": {
           "type": "number",
@@ -327,6 +332,14 @@
           "mutable": false,
           "description": "Append a separate ChevronDown menu segment while preserving this button's\nvariant, size, surface, active, loading, border, and width treatment."
         },
+        "surfaceOpen": {
+          "type": "boolean | undefined",
+          "resolvedType": "boolean | undefined",
+          "attribute": "surface-open",
+          "required": false,
+          "mutable": false,
+          "description": "The associated menu, picker, or panel is visible, including its exit motion.\nHolds only the pressed wash; does not set ARIA, selection, or press scaling.\nIn split mode this applies only to the menu segment. Explicit false disables\nthe legacy expanded-derived wash; omission preserves that compatibility path."
+        },
         "type": {
           "type": "'button' | 'submit' | 'reset'",
           "resolvedType": "\"button\" | \"reset\" | \"submit\"",
@@ -444,7 +457,7 @@
         "attribute": "expanded",
         "required": false,
         "mutable": false,
-        "description": "Controlled disclosure or popup state forwarded to `aria-expanded`.\nPopup triggers hold only the pressed wash while open; their resting\nforeground is unchanged. Ordinary disclosures remain visually neutral."
+        "description": "Controlled disclosure state forwarded to aria-expanded.\nUsing expanded alone for surface-open styling is deprecated; set surfaceOpen\nexplicitly to separate the rendered surface lifecycle from disclosure state."
       },
       "focusTabIndex": {
         "type": "number",
@@ -604,6 +617,14 @@
         "mutable": false,
         "description": "Append a separate ChevronDown menu segment while preserving this button's\nvariant, size, surface, active, loading, border, and width treatment."
       },
+      "surfaceOpen": {
+        "type": "boolean | undefined",
+        "resolvedType": "boolean | undefined",
+        "attribute": "surface-open",
+        "required": false,
+        "mutable": false,
+        "description": "The associated menu, picker, or panel is visible, including its exit motion.\nHolds only the pressed wash; does not set ARIA, selection, or press scaling.\nIn split mode this applies only to the menu segment. Explicit false disables\nthe legacy expanded-derived wash; omission preserves that compatibility path."
+      },
       "type": {
         "type": "'button' | 'submit' | 'reset'",
         "resolvedType": "\"button\" | \"reset\" | \"submit\"",
@@ -716,7 +737,7 @@
     },
     {
       "path": "src/wc/components/ButtonUnfilled/ButtonUnfilled.tsx",
-      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n  Watch,\n} from '@stencil/core';\nimport { controlWidthClass } from '../../utils';\nimport { beginElevatedControlPress } from '../../utils/control-press';\nimport { renderButtonContent } from '../../utils/button-render';\nimport type { ControlInsetDepth } from '../../utils/control-text';\nimport { observeTableCaptionCompact } from '../../utils/table-caption-compact';\nimport type { ButtonPopup, ButtonSize, ButtonVariant, ButtonWidth } from '../../utils/button-types';\n\nexport type ButtonUnfilledBackground =\n  | 'faint'\n  | 'medium'\n  | 'bold'\n  | 'strong'\n  | 'translucent'\n  | 'inverted'\n  | 'media'\n  | 'always-dark';\n\nexport type ButtonUnfilledVariant = ButtonVariant;\nexport type ButtonUnfilledSize = ButtonSize;\nexport type ButtonUnfilledWidth = ButtonWidth;\nexport type ButtonUnfilledPopup = ButtonPopup;\n\n@Component({\n  tag: 'ds-button-unfilled',\n  styleUrl: 'ButtonUnfilled.css',\n  scoped: true,\n})\nexport class ButtonUnfilled {\n  @Element() el!: HTMLElement;\n\n  /**\n   * Content layout. Default is label-only; pass `icon` for icon-only chrome\n   * (nav / tool rails) or `icon-label` for leading icon + text.\n   */\n  @Prop() variant: ButtonUnfilledVariant = 'label';\n\n  /** Control density (height, padding, icon, type). */\n  @Prop() size: ButtonUnfilledSize = 'md';\n\n  /** Use reduced outer geometry when nested inside a control of the same size. */\n  @Prop() isInset: boolean = false;\n\n  /** Single removes 4px overall; double removes 8px overall (xs stays single). */\n  @Prop() insetDepth: ControlInsetDepth = 'single';\n\n  /** Width fit — hug content (default) or fill the parent. */\n  @Prop() width: ButtonUnfilledWidth = 'hug';\n\n  /** Visible text for `label` / `icon-label` variants. */\n  @Prop() label: string = '';\n\n  /** Whether the visible label uses the emphasized weight. */\n  @Prop() labelEmphasis: boolean = true;\n\n  /** Icon name passed to <ds-icon> for `icon` / `icon-label` variants. */\n  @Prop() icon: string = '';\n\n  /**\n   * Owner-controlled visual emphasis inside a composite. This does not add\n   * toggle semantics and does not emit dsChange.\n   */\n  @Prop() isActive: boolean = false;\n\n  /**\n   * When active, render the selected interaction fill.\n   * Default `true` for general UI. Shell chrome (nav / tool rails) should pass\n   * `false` so selection is foreground-only (primary color, no fill).\n   */\n  @Prop() activeFill: boolean = true;\n\n  /** Show a 1px secondary inset border. Default on; shell chrome can pass `false`. */\n  @Prop() hasBorder: boolean = true;\n\n  /** Use the half-radius treatment instead of the default control radius. */\n  @Prop() rounded: boolean = false;\n\n  /**\n   * Scale down during a physical pointer press.\n   * Disable when an owning composite requires fixed child or background geometry.\n   */\n  @Prop() pressScale: boolean = true;\n\n  /** Show a notification dot at the top-right of the icon zone (icon variant only). */\n  @Prop() dot: boolean = false;\n\n  /** Disables interaction. */\n  @Prop() isInactive: boolean = false;\n\n  /** Shows an inline loader and prevents interaction without applying inactive opacity. */\n  @Prop() isLoading: boolean = false;\n\n  /** Native button type. */\n  @Prop() type: 'button' | 'submit' | 'reset' = 'button';\n\n  /** Actual parent surface context. Omit on primary and secondary surfaces. */\n  @Prop() background: ButtonUnfilledBackground | undefined;\n\n  /** Accessible name override. Required for icon-only buttons. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  @Prop() controls: string | undefined;\n  /**\n   * Controlled disclosure or popup state forwarded to `aria-expanded`.\n   * Popup triggers hold only the pressed wash while open; their resting\n   * foreground is unchanged. Ordinary disclosures remain visually neutral.\n   */\n  @Prop() expanded: boolean | undefined;\n  @Prop() haspopup: ButtonUnfilledPopup | undefined;\n\n  /**\n   * Append a separate ChevronDown menu segment while preserving this button's\n   * variant, size, surface, active, loading, border, and width treatment.\n   */\n  @Prop() split: boolean = false;\n\n  /** Accessible name for the appended menu segment in split mode. */\n  @Prop() menuAriaLabel: string = 'More options';\n\n  /**\n   * Controlled state for a genuine toggle button. Adds aria-pressed, promotes\n   * active styling, and makes activation emit dsChange with the requested state.\n   */\n  @Prop() pressed: boolean | undefined;\n\n  /**\n   * Collapse the visible label and chevron to an icon-only control when the\n   * owning `ds-table` caption is narrower than 900px. The trigger omits those\n   * parts rather than clipping them.\n   */\n  @Prop({ reflect: true }) collapseLabel: boolean = false;\n\n  /**\n   * Mark the button as a Menu trigger. Implies `aria-haspopup=\"menu\"` and covers\n   * both menu-button shapes:\n   *\n   * - `label` / `icon-label` — the action *has* a menu; a trailing chevron carries\n   *   the affordance.\n   * - `icon` — the button *is* a menu. No chevron is added, so the glyph must\n   *   convey the menu on its own. Use `Ellipses` for generic more-options;\n   *   use a specific icon when the menu has a named purpose, such as\n   *   `Table` for Customize table.\n   *\n   * Use `haspopup` directly for non-menu popups.\n   */\n  @Prop() hasMenu: boolean = false;\n\n  /**\n   * Native `tabindex` for roving keyboard groups in shell chrome.\n   * Omit for the default button tab stop (`0`).\n   */\n  @Prop({ attribute: 'tab-index' }) focusTabIndex?: number;\n\n  @Event() dsClick!: EventEmitter<MouseEvent>;\n  @Event() dsMenuClick!: EventEmitter<MouseEvent>;\n  @Event() dsChange!: EventEmitter<boolean>;\n\n  @State() private captionCompact = false;\n\n  private buttonEl: HTMLButtonElement | null = null;\n  private menuButtonEl: HTMLButtonElement | null = null;\n  private captionCompactDisconnect: (() => void) | undefined;\n  private hasLoaded = false;\n\n  componentDidLoad(): void {\n    this.hasLoaded = true;\n    this.syncCaptionCompactObserver();\n  }\n\n  connectedCallback(): void {\n    if (this.hasLoaded) this.syncCaptionCompactObserver();\n  }\n\n  disconnectedCallback(): void {\n    this.disconnectCaptionCompactObserver();\n  }\n\n  @Watch('collapseLabel')\n  onCollapseLabelChange() {\n    this.syncCaptionCompactObserver();\n  }\n\n  @Method()\n  async setFocus(segment: 'primary' | 'menu' = 'primary') {\n    (segment === 'menu' ? this.menuButtonEl : this.buttonEl)?.focus();\n  }\n\n  private handleClick = (event: MouseEvent) => {\n    if (this.isInactive || this.isLoading) {\n      event.preventDefault();\n      event.stopPropagation();\n      return;\n    }\n    this.dsClick.emit(event);\n    if (this.pressed !== undefined) this.dsChange.emit(!this.pressed);\n  };\n\n  private handleMenuClick = (event: MouseEvent) => {\n    if (this.isInactive || this.isLoading) {\n      event.preventDefault();\n      event.stopPropagation();\n      return;\n    }\n    this.dsMenuClick.emit(event);\n  };\n\n  private get captionIconOnly(): boolean {\n    return (\n      this.collapseLabel &&\n      this.captionCompact &&\n      this.variant === 'icon-label' &&\n      Boolean(this.icon)\n    );\n  }\n\n  private get visualVariant(): ButtonUnfilledVariant {\n    return this.captionIconOnly ? 'icon' : this.variant;\n  }\n\n  private get showDot(): boolean {\n    return this.variant === 'icon' && this.dot && !this.isLoading;\n  }\n\n  private syncCaptionCompactObserver(): void {\n    this.disconnectCaptionCompactObserver();\n    if (!this.collapseLabel) {\n      if (this.captionCompact) this.captionCompact = false;\n      return;\n    }\n    this.captionCompactDisconnect = observeTableCaptionCompact(this.el, compact => {\n      if (this.captionCompact !== compact) this.captionCompact = compact;\n    });\n  }\n\n  private disconnectCaptionCompactObserver(): void {\n    this.captionCompactDisconnect?.();\n    this.captionCompactDisconnect = undefined;\n  }\n\n  private get resolvedHaspopup(): ButtonUnfilledPopup | undefined {\n    return this.haspopup ?? (this.hasMenu ? 'menu' : undefined);\n  }\n\n  private get doubleInset(): boolean {\n    return this.isInset && this.insetDepth === 'double' && this.size !== 'xs';\n  }\n\n  /** Only popup triggers hold a pressed visual while expanded. */\n  private get expandedPopup(): boolean {\n    return this.expanded === true && this.resolvedHaspopup !== undefined && !this.isInactive;\n  }\n\n  private get visuallyActive(): boolean {\n    return this.isActive || this.pressed === true;\n  }\n\n  /** Knock-out ring: selected fill → active wash; otherwise surface token. */\n  private get dotRing(): string {\n    if ((this.isActive || this.pressed === true) && this.activeFill) {\n      return 'var(--ds-interaction-active)';\n    }\n    return 'var(--ds-button-unfilled-dot-ring)';\n  }\n\n  private get accessibleName(): string | undefined {\n    if (this.ariaLabel) return this.ariaLabel;\n    if (this.isLoading && this.variant === 'label' && this.label) return this.label;\n    return undefined;\n  }\n\n  private buttonClass(\n    variant: ButtonUnfilledVariant,\n    expanded: boolean,\n    bordered: boolean\n  ): Record<string, boolean> {\n    const bg = this.background;\n    const cls: Record<string, boolean> = {\n      'button-unfilled': true,\n      'ds-button': true,\n      'ds-focus-ring-inset': true,\n      'ds-control-press-scale': this.pressScale && !this.split,\n      'ds-interaction-fill': true,\n      'ds-interaction-fill--selected':\n        (this.isActive || this.pressed === true) && this.activeFill && !this.isInactive,\n      'ds-interaction-fill--on-faint': bg === 'faint',\n      'ds-interaction-fill--on-medium': bg === 'medium',\n      'ds-interaction-fill--on-bold': bg === 'bold',\n      'ds-interaction-fill--on-strong': bg === 'strong',\n      'ds-interaction-fill--on-translucent': bg === 'translucent',\n      'ds-interaction-fill--on-inverted': bg === 'inverted',\n      'ds-interaction-fill--on-media': bg === 'media',\n      'ds-interaction-fill--on-always-dark': bg === 'always-dark',\n      'button-unfilled--active': this.visuallyActive,\n      'button-unfilled--expanded': expanded,\n      'ds-button--expanded': expanded,\n      'button-unfilled--bordered': bordered,\n      'ds-button--bordered': bordered,\n      'button-unfilled--rounded': this.rounded,\n      'ds-button--rounded': this.rounded,\n      'ds-control-inactive': this.isInactive,\n      'ds-control--lg': this.size === 'lg',\n      'ds-control--md': this.size === 'md',\n      'ds-control--sm': this.size === 'sm',\n      'ds-control--xs': this.size === 'xs',\n      'ds-control--inset': this.isInset && !this.doubleInset,\n      'ds-control--inset-double': this.doubleInset,\n      'ds-control-frame': true,\n      'button-unfilled--icon': variant === 'icon',\n      'ds-button--icon': variant === 'icon',\n      'button-unfilled--label': variant === 'label',\n      'button-unfilled--icon-label': variant === 'icon-label',\n      'button-unfilled--background-faint': bg === 'faint',\n      'button-unfilled--background-medium': bg === 'medium',\n      'button-unfilled--background-bold': bg === 'bold',\n      'button-unfilled--background-strong': bg === 'strong',\n      'button-unfilled--background-translucent': bg === 'translucent',\n      'button-unfilled--background-inverted': bg === 'inverted',\n      'button-unfilled--background-media': bg === 'media',\n      'button-unfilled--on-always-dark': bg === 'always-dark',\n    };\n    return cls;\n  }\n\n  render() {\n    const primaryButton = (\n      <button\n        ref={el => {\n          this.buttonEl = el ?? null;\n        }}\n        type={this.type}\n        class={{\n          ...this.buttonClass(\n            this.visualVariant,\n            !this.split && this.expandedPopup,\n            this.hasBorder && !this.split\n          ),\n          'ds-button-split__primary': this.split,\n        }}\n        disabled={this.isInactive}\n        tabIndex={this.focusTabIndex ?? 0}\n        aria-label={this.accessibleName}\n        aria-busy={this.isLoading ? 'true' : undefined}\n        aria-disabled={this.isLoading ? 'true' : undefined}\n        aria-controls={this.split ? undefined : this.controls}\n        aria-expanded={\n          this.split || this.expanded === undefined ? undefined : String(this.expanded)\n        }\n        aria-haspopup={this.split ? undefined : this.resolvedHaspopup}\n        aria-pressed={this.pressed === undefined ? undefined : String(this.pressed)}\n        onPointerDown={event =>\n          beginElevatedControlPress(\n            event,\n            this.pressScale && !this.split && !this.isInactive && !this.isLoading\n          )\n        }\n        onClick={this.handleClick}\n      >\n        {renderButtonContent({\n          namespace: 'button-unfilled',\n          variant: this.visualVariant,\n          size: this.size,\n          label: this.label,\n          labelEmphasis: this.labelEmphasis,\n          icon: this.icon,\n          hasMenu: !this.split && this.hasMenu,\n          isLoading: this.isLoading,\n          dot: {\n            visible: this.showDot,\n            background: this.dotRing,\n          },\n        })}\n      </button>\n    );\n\n    const control = this.split ? (\n      <div\n        class={{\n          'ds-button-split': true,\n          'ds-button-split--rounded': this.rounded,\n        }}\n      >\n        {primaryButton}\n        <span\n          class={{\n            'ds-button-split__divider': true,\n            'ds-button-split__divider--content-height': !this.hasBorder,\n          }}\n          aria-hidden=\"true\"\n        />\n        <button\n          ref={el => {\n            this.menuButtonEl = el ?? null;\n          }}\n          class={{\n            ...this.buttonClass('icon', this.expanded === true && !this.isInactive, false),\n            'ds-button-split__menu': true,\n          }}\n          type=\"button\"\n          disabled={this.isInactive || this.isLoading}\n          tabIndex={this.focusTabIndex ?? 0}\n          aria-label={this.menuAriaLabel}\n          aria-controls={this.controls}\n          aria-expanded={String(this.expanded === true)}\n          aria-haspopup=\"menu\"\n          onClick={this.handleMenuClick}\n        >\n          {renderButtonContent({\n            namespace: 'button-unfilled',\n            variant: 'icon',\n            size: this.size,\n            label: '',\n            labelEmphasis: true,\n            icon: 'ChevronDown',\n            hasMenu: false,\n            isLoading: false,\n          })}\n        </button>\n        {this.hasBorder ? <span class=\"ds-button-split__outline\" aria-hidden=\"true\" /> : null}\n      </div>\n    ) : (\n      primaryButton\n    );\n\n    return (\n      <Host\n        class={{\n          'button-unfilled-host': true,\n          'button-unfilled-host--icon': this.visualVariant === 'icon' && !this.split,\n          'ds-button-host--icon': this.visualVariant === 'icon' && !this.split,\n          'ds-button-split-host': this.split,\n          'ds-button-split-host--primary-icon': this.split && this.visualVariant === 'icon',\n          [`button-unfilled-host--background-${this.background}`]:\n            this.split && this.background !== undefined,\n          'ds-control--lg': this.size === 'lg',\n          'ds-control--md': this.size === 'md',\n          'ds-control--sm': this.size === 'sm',\n          'ds-control--xs': this.size === 'xs',\n          'ds-control--inset': this.isInset && !this.doubleInset,\n          'ds-control--inset-double': this.doubleInset,\n          'ds-table-caption-control': this.collapseLabel,\n          'ds-table-caption-control--compact': this.captionIconOnly,\n          ...controlWidthClass(this.width),\n        }}\n        tabIndex={-1}\n      >\n        {this.collapseLabel ? (\n          <ds-tooltip\n            label={this.captionIconOnly ? this.label || this.accessibleName || '' : ''}\n            side=\"top\"\n            size=\"sm\"\n          >\n            {control}\n          </ds-tooltip>\n        ) : (\n          control\n        )}\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n  Watch,\n} from '@stencil/core';\nimport { controlWidthClass } from '../../utils';\nimport { beginElevatedControlPress } from '../../utils/control-press';\nimport { renderButtonContent } from '../../utils/button-render';\nimport type { ControlInsetDepth } from '../../utils/control-text';\nimport { observeTableCaptionCompact } from '../../utils/table-caption-compact';\nimport type { ButtonPopup, ButtonSize, ButtonVariant, ButtonWidth } from '../../utils/button-types';\n\nexport type ButtonUnfilledBackground =\n  | 'faint'\n  | 'medium'\n  | 'bold'\n  | 'strong'\n  | 'translucent'\n  | 'inverted'\n  | 'media'\n  | 'always-dark';\n\nexport type ButtonUnfilledVariant = ButtonVariant;\nexport type ButtonUnfilledSize = ButtonSize;\nexport type ButtonUnfilledWidth = ButtonWidth;\nexport type ButtonUnfilledPopup = ButtonPopup;\n\n@Component({\n  tag: 'ds-button-unfilled',\n  styleUrl: 'ButtonUnfilled.css',\n  scoped: true,\n})\nexport class ButtonUnfilled {\n  @Element() el!: HTMLElement;\n\n  /**\n   * Content layout. Default is label-only; pass `icon` for icon-only chrome\n   * (nav / tool rails) or `icon-label` for leading icon + text.\n   */\n  @Prop() variant: ButtonUnfilledVariant = 'label';\n\n  /** Control density (height, padding, icon, type). */\n  @Prop() size: ButtonUnfilledSize = 'md';\n\n  /** Use reduced outer geometry when nested inside a control of the same size. */\n  @Prop() isInset: boolean = false;\n\n  /** Single removes 4px overall; double removes 8px overall (xs stays single). */\n  @Prop() insetDepth: ControlInsetDepth = 'single';\n\n  /** Width fit — hug content (default) or fill the parent. */\n  @Prop() width: ButtonUnfilledWidth = 'hug';\n\n  /** Visible text for `label` / `icon-label` variants. */\n  @Prop() label: string = '';\n\n  /** Whether the visible label uses the emphasized weight. */\n  @Prop() labelEmphasis: boolean = true;\n\n  /** Icon name passed to <ds-icon> for `icon` / `icon-label` variants. */\n  @Prop() icon: string = '';\n\n  /**\n   * Owner-controlled visual emphasis inside a composite. This does not add\n   * toggle semantics and does not emit dsChange.\n   */\n  @Prop() isActive: boolean = false;\n\n  /**\n   * When active, render the selected interaction fill.\n   * Default `true` for general UI. Shell chrome (nav / tool rails) should pass\n   * `false` so selection is foreground-only (primary color, no fill).\n   */\n  @Prop() activeFill: boolean = true;\n\n  /** Show a 1px secondary inset border. Default on; shell chrome can pass `false`. */\n  @Prop() hasBorder: boolean = true;\n\n  /** Use the half-radius treatment instead of the default control radius. */\n  @Prop() rounded: boolean = false;\n\n  /**\n   * Scale down during a physical pointer press.\n   * Disable when an owning composite requires fixed child or background geometry.\n   */\n  @Prop() pressScale: boolean = true;\n\n  /** Show a notification dot at the top-right of the icon zone (icon variant only). */\n  @Prop() dot: boolean = false;\n\n  /** Disables interaction. */\n  @Prop() isInactive: boolean = false;\n\n  /** Shows an inline loader and prevents interaction without applying inactive opacity. */\n  @Prop() isLoading: boolean = false;\n\n  /** Native button type. */\n  @Prop() type: 'button' | 'submit' | 'reset' = 'button';\n\n  /** Actual parent surface context. Omit on primary and secondary surfaces. */\n  @Prop() background: ButtonUnfilledBackground | undefined;\n\n  /** Accessible name override. Required for icon-only buttons. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  @Prop() controls: string | undefined;\n  /**\n   * Controlled disclosure state forwarded to aria-expanded.\n   * Using expanded alone for surface-open styling is deprecated; set surfaceOpen\n   * explicitly to separate the rendered surface lifecycle from disclosure state.\n   */\n  @Prop() expanded: boolean | undefined;\n\n  /**\n   * The associated menu, picker, or panel is visible, including its exit motion.\n   * Holds only the pressed wash; does not set ARIA, selection, or press scaling.\n   * In split mode this applies only to the menu segment. Explicit false disables\n   * the legacy expanded-derived wash; omission preserves that compatibility path.\n   */\n  @Prop() surfaceOpen: boolean | undefined;\n  @Prop() haspopup: ButtonUnfilledPopup | undefined;\n\n  /**\n   * Append a separate ChevronDown menu segment while preserving this button's\n   * variant, size, surface, active, loading, border, and width treatment.\n   */\n  @Prop() split: boolean = false;\n\n  /** Accessible name for the appended menu segment in split mode. */\n  @Prop() menuAriaLabel: string = 'More options';\n\n  /**\n   * Controlled state for a genuine toggle button. Adds aria-pressed, promotes\n   * active styling, and makes activation emit dsChange with the requested state.\n   */\n  @Prop() pressed: boolean | undefined;\n\n  /**\n   * Collapse the visible label and chevron to an icon-only control when the\n   * owning `ds-table` caption is narrower than 900px. The trigger omits those\n   * parts rather than clipping them.\n   */\n  @Prop({ reflect: true }) collapseLabel: boolean = false;\n\n  /**\n   * Mark the button as a Menu trigger. Implies `aria-haspopup=\"menu\"` and covers\n   * both menu-button shapes:\n   *\n   * - `label` / `icon-label` — the action *has* a menu; a trailing chevron carries\n   *   the affordance.\n   * - `icon` — the button *is* a menu. No chevron is added, so the glyph must\n   *   convey the menu on its own. Use `Ellipses` for generic more-options;\n   *   use a specific icon when the menu has a named purpose, such as\n   *   `Table` for Customize table.\n   *\n   * Use `haspopup` directly for non-menu popups.\n   */\n  @Prop() hasMenu: boolean = false;\n\n  /**\n   * Native `tabindex` for roving keyboard groups in shell chrome.\n   * Omit for the default button tab stop (`0`).\n   */\n  @Prop({ attribute: 'tab-index' }) focusTabIndex?: number;\n\n  @Event() dsClick!: EventEmitter<MouseEvent>;\n  @Event() dsMenuClick!: EventEmitter<MouseEvent>;\n  @Event() dsChange!: EventEmitter<boolean>;\n\n  @State() private captionCompact = false;\n\n  private buttonEl: HTMLButtonElement | null = null;\n  private menuButtonEl: HTMLButtonElement | null = null;\n  private captionCompactDisconnect: (() => void) | undefined;\n  private hasLoaded = false;\n\n  componentDidLoad(): void {\n    this.hasLoaded = true;\n    this.syncCaptionCompactObserver();\n  }\n\n  connectedCallback(): void {\n    if (this.hasLoaded) this.syncCaptionCompactObserver();\n  }\n\n  disconnectedCallback(): void {\n    this.disconnectCaptionCompactObserver();\n  }\n\n  @Watch('collapseLabel')\n  onCollapseLabelChange() {\n    this.syncCaptionCompactObserver();\n  }\n\n  @Method()\n  async setFocus(segment: 'primary' | 'menu' = 'primary') {\n    (segment === 'menu' ? this.menuButtonEl : this.buttonEl)?.focus();\n  }\n\n  private handleClick = (event: MouseEvent) => {\n    if (this.isInactive || this.isLoading) {\n      event.preventDefault();\n      event.stopPropagation();\n      return;\n    }\n    this.dsClick.emit(event);\n    if (this.pressed !== undefined) this.dsChange.emit(!this.pressed);\n  };\n\n  private handleMenuClick = (event: MouseEvent) => {\n    if (this.isInactive || this.isLoading) {\n      event.preventDefault();\n      event.stopPropagation();\n      return;\n    }\n    this.dsMenuClick.emit(event);\n  };\n\n  private get captionIconOnly(): boolean {\n    return (\n      this.collapseLabel &&\n      this.captionCompact &&\n      this.variant === 'icon-label' &&\n      Boolean(this.icon)\n    );\n  }\n\n  private get visualVariant(): ButtonUnfilledVariant {\n    return this.captionIconOnly ? 'icon' : this.variant;\n  }\n\n  private get showDot(): boolean {\n    return this.variant === 'icon' && this.dot && !this.isLoading;\n  }\n\n  private syncCaptionCompactObserver(): void {\n    this.disconnectCaptionCompactObserver();\n    if (!this.collapseLabel) {\n      if (this.captionCompact) this.captionCompact = false;\n      return;\n    }\n    this.captionCompactDisconnect = observeTableCaptionCompact(this.el, compact => {\n      if (this.captionCompact !== compact) this.captionCompact = compact;\n    });\n  }\n\n  private disconnectCaptionCompactObserver(): void {\n    this.captionCompactDisconnect?.();\n    this.captionCompactDisconnect = undefined;\n  }\n\n  private get resolvedHaspopup(): ButtonUnfilledPopup | undefined {\n    return this.haspopup ?? (this.hasMenu ? 'menu' : undefined);\n  }\n\n  private get doubleInset(): boolean {\n    return this.isInset && this.insetDepth === 'double' && this.size !== 'xs';\n  }\n\n  private get resolvedSurfaceOpen(): boolean {\n    const legacy = this.expanded === true && (this.split || this.resolvedHaspopup !== undefined);\n    return (this.surfaceOpen ?? legacy) && !this.isInactive;\n  }\n\n  private get visuallyActive(): boolean {\n    return this.isActive || this.pressed === true;\n  }\n\n  /** Knock-out ring: selected fill → active wash; otherwise surface token. */\n  private get dotRing(): string {\n    if ((this.isActive || this.pressed === true) && this.activeFill) {\n      return 'var(--ds-interaction-active)';\n    }\n    return 'var(--ds-button-unfilled-dot-ring)';\n  }\n\n  private get accessibleName(): string | undefined {\n    if (this.ariaLabel) return this.ariaLabel;\n    if (this.isLoading && this.variant === 'label' && this.label) return this.label;\n    return undefined;\n  }\n\n  private buttonClass(\n    variant: ButtonUnfilledVariant,\n    expanded: boolean,\n    bordered: boolean\n  ): Record<string, boolean> {\n    const bg = this.background;\n    const cls: Record<string, boolean> = {\n      'button-unfilled': true,\n      'ds-button': true,\n      'ds-focus-ring-inset': true,\n      'ds-control-press-scale': this.pressScale && !this.split,\n      'ds-interaction-fill': true,\n      'ds-interaction-fill--selected':\n        (this.isActive || this.pressed === true) && this.activeFill && !this.isInactive,\n      'ds-interaction-fill--on-faint': bg === 'faint',\n      'ds-interaction-fill--on-medium': bg === 'medium',\n      'ds-interaction-fill--on-bold': bg === 'bold',\n      'ds-interaction-fill--on-strong': bg === 'strong',\n      'ds-interaction-fill--on-translucent': bg === 'translucent',\n      'ds-interaction-fill--on-inverted': bg === 'inverted',\n      'ds-interaction-fill--on-media': bg === 'media',\n      'ds-interaction-fill--on-always-dark': bg === 'always-dark',\n      'button-unfilled--active': this.visuallyActive,\n      'button-unfilled--expanded': expanded,\n      'ds-interaction-fill--surface-open': expanded,\n      'ds-button--expanded': expanded,\n      'button-unfilled--bordered': bordered,\n      'ds-button--bordered': bordered,\n      'button-unfilled--rounded': this.rounded,\n      'ds-button--rounded': this.rounded,\n      'ds-control-inactive': this.isInactive,\n      'ds-control--lg': this.size === 'lg',\n      'ds-control--md': this.size === 'md',\n      'ds-control--sm': this.size === 'sm',\n      'ds-control--xs': this.size === 'xs',\n      'ds-control--inset': this.isInset && !this.doubleInset,\n      'ds-control--inset-double': this.doubleInset,\n      'ds-control-frame': true,\n      'button-unfilled--icon': variant === 'icon',\n      'ds-button--icon': variant === 'icon',\n      'button-unfilled--label': variant === 'label',\n      'button-unfilled--icon-label': variant === 'icon-label',\n      'button-unfilled--background-faint': bg === 'faint',\n      'button-unfilled--background-medium': bg === 'medium',\n      'button-unfilled--background-bold': bg === 'bold',\n      'button-unfilled--background-strong': bg === 'strong',\n      'button-unfilled--background-translucent': bg === 'translucent',\n      'button-unfilled--background-inverted': bg === 'inverted',\n      'button-unfilled--background-media': bg === 'media',\n      'button-unfilled--on-always-dark': bg === 'always-dark',\n    };\n    return cls;\n  }\n\n  render() {\n    const primaryButton = (\n      <button\n        ref={el => {\n          this.buttonEl = el ?? null;\n        }}\n        type={this.type}\n        class={{\n          ...this.buttonClass(\n            this.visualVariant,\n            !this.split && this.resolvedSurfaceOpen,\n            this.hasBorder && !this.split\n          ),\n          'ds-button-split__primary': this.split,\n        }}\n        disabled={this.isInactive}\n        tabIndex={this.focusTabIndex ?? 0}\n        aria-label={this.accessibleName}\n        aria-busy={this.isLoading ? 'true' : undefined}\n        aria-disabled={this.isLoading ? 'true' : undefined}\n        aria-controls={this.split ? undefined : this.controls}\n        aria-expanded={\n          this.split || this.expanded === undefined ? undefined : String(this.expanded)\n        }\n        aria-haspopup={this.split ? undefined : this.resolvedHaspopup}\n        aria-pressed={this.pressed === undefined ? undefined : String(this.pressed)}\n        onPointerDown={event =>\n          beginElevatedControlPress(\n            event,\n            this.pressScale && !this.split && !this.isInactive && !this.isLoading\n          )\n        }\n        onClick={this.handleClick}\n      >\n        {renderButtonContent({\n          namespace: 'button-unfilled',\n          variant: this.visualVariant,\n          size: this.size,\n          label: this.label,\n          labelEmphasis: this.labelEmphasis,\n          icon: this.icon,\n          hasMenu: !this.split && this.hasMenu,\n          isLoading: this.isLoading,\n          dot: {\n            visible: this.showDot,\n            background: this.dotRing,\n          },\n        })}\n      </button>\n    );\n\n    const control = this.split ? (\n      <div\n        class={{\n          'ds-button-split': true,\n          'ds-button-split--rounded': this.rounded,\n        }}\n      >\n        {primaryButton}\n        <span\n          class={{\n            'ds-button-split__divider': true,\n            'ds-button-split__divider--content-height': !this.hasBorder,\n          }}\n          aria-hidden=\"true\"\n        />\n        <button\n          ref={el => {\n            this.menuButtonEl = el ?? null;\n          }}\n          class={{\n            ...this.buttonClass('icon', this.resolvedSurfaceOpen, false),\n            'ds-button-split__menu': true,\n          }}\n          type=\"button\"\n          disabled={this.isInactive || this.isLoading}\n          tabIndex={this.focusTabIndex ?? 0}\n          aria-label={this.menuAriaLabel}\n          aria-controls={this.controls}\n          aria-expanded={String(this.expanded === true)}\n          aria-haspopup=\"menu\"\n          onClick={this.handleMenuClick}\n        >\n          {renderButtonContent({\n            namespace: 'button-unfilled',\n            variant: 'icon',\n            size: this.size,\n            label: '',\n            labelEmphasis: true,\n            icon: 'ChevronDown',\n            hasMenu: false,\n            isLoading: false,\n          })}\n        </button>\n        {this.hasBorder ? <span class=\"ds-button-split__outline\" aria-hidden=\"true\" /> : null}\n      </div>\n    ) : (\n      primaryButton\n    );\n\n    return (\n      <Host\n        class={{\n          'button-unfilled-host': true,\n          'button-unfilled-host--icon': this.visualVariant === 'icon' && !this.split,\n          'ds-button-host--icon': this.visualVariant === 'icon' && !this.split,\n          'ds-button-split-host': this.split,\n          'ds-button-split-host--primary-icon': this.split && this.visualVariant === 'icon',\n          [`button-unfilled-host--background-${this.background}`]:\n            this.split && this.background !== undefined,\n          'ds-control--lg': this.size === 'lg',\n          'ds-control--md': this.size === 'md',\n          'ds-control--sm': this.size === 'sm',\n          'ds-control--xs': this.size === 'xs',\n          'ds-control--inset': this.isInset && !this.doubleInset,\n          'ds-control--inset-double': this.doubleInset,\n          'ds-table-caption-control': this.collapseLabel,\n          'ds-table-caption-control--compact': this.captionIconOnly,\n          ...controlWidthClass(this.width),\n        }}\n        tabIndex={-1}\n      >\n        {this.collapseLabel ? (\n          <ds-tooltip\n            label={this.captionIconOnly ? this.label || this.accessibleName || '' : ''}\n            side=\"top\"\n            size=\"sm\"\n          >\n            {control}\n          </ds-tooltip>\n        ) : (\n          control\n        )}\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/card-navigation.json

@@ -0,0 +1,255 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "card-navigation",
+  "title": "CardNavigation",
+  "description": "Settings-style navigation surface with a native destination link, optional supporting copy, a fixed ChevronRight affordance, and an optional application-owned body.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/card-navigation",
+    "source": "src/wc/components/CardNavigation/CardNavigation.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "general",
+      "status": "stable",
+      "summary": "Settings-style navigation surface with a native destination link, optional supporting copy, a fixed ChevronRight affordance, and an optional application-owned body.",
+      "useWhen": [
+        "A settings page needs a card that leads to a deeper settings destination.",
+        "A compact destination card needs the complete surface to act as one link.",
+        "A settings summary must remain visible in a body while only the card header navigates."
+      ],
+      "avoidWhen": [
+        "The card edits its contents in place; use CardSetting for the edit-save-cancel workflow.",
+        "The destination is an action without a navigable URL.",
+        "The surface contains a chart, legend, metric visualization, or other data-visualization composition."
+      ],
+      "alternatives": [
+        {
+          "when": "The section switches between read-only and editable content in place.",
+          "component": "component:ds-card-setting",
+          "reason": "CardSetting owns the controlled edit-save-cancel workflow."
+        },
+        {
+          "when": "The surface contains a chart or specialized data-visualization composition.",
+          "component": "component:ds-card-chart",
+          "reason": "CardChart owns the independently evolving chart-card contract."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-text",
+        "component:ds-card-setting"
+      ],
+      "accessibility": [
+        "CardNavigation renders a native link whenever href resolves to an allowed URL, so Enter activation, link context menus, and modified-click behavior remain available.",
+        "The heading is rendered as an h2 and the optional description contributes to the link's accessible name.",
+        "The ChevronRight icon is decorative because the link text already names the destination.",
+        "Use the content variant only when interactive body content must remain outside the header link; never place interactive descendants inside the navigation-only card.",
+        "dsNavigate is cancelable so client-side routers can prevent native navigation after accepting an unmodified activation."
+      ],
+      "states": [
+        "The native link owns hover, pressed, and focus-visible states across the complete card in navigation-only mode.",
+        "In content mode, the native link owns those interaction states only across the header while the body remains application-owned.",
+        "An empty or unsafe href renders non-interactive card chrome without a false keyboard target.",
+        "The application owns destination loading, authorization, not-found, and recovery states after navigation."
+      ],
+      "responsiveBehavior": [
+        "Choose sm, md, or lg from the parent layout; the surface never exceeds its parent width.",
+        "Supporting copy wraps while the chevron remains visible at the trailing edge.",
+        "The parent owns wrapping, columns, stacking, and breakpoint changes between cards."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Set href to a valid relative or HTTP(S) URL.",
+          "Prevent dsNavigate only when an application router takes ownership of the same activation."
+        ],
+        "react": [
+          "Pass href for native link semantics and use onDsNavigate only when coordinating with a client-side router.",
+          "Use variant content when projecting interactive body content so those controls stay outside the link."
+        ],
+        "angular": [
+          "Bind href and prevent dsNavigate before calling Router.navigateByUrl for unmodified primary activations.",
+          "Use variant content when projecting interactive body content so those controls stay outside the link."
+        ]
+      },
+      "references": [
+        {
+          "label": "Storybook navigation-only and content examples",
+          "path": "src/wc/components/CardNavigation/CardNavigation.stories.ts"
+        },
+        {
+          "label": "Rendered navigation and interaction coverage",
+          "path": "tests/e2e/card-navigation.spec.ts"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "cardWidth": {
+          "type": "CardNavigationWidth",
+          "resolvedType": "\"lg\" | \"md\" | \"sm\"",
+          "attribute": "card-width",
+          "default": "'md'",
+          "required": false,
+          "mutable": false,
+          "description": "Card width token (`sm` / `md` / `lg`)."
+        },
+        "description": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "description",
+          "required": false,
+          "mutable": false,
+          "description": "Optional supporting copy shown below the heading."
+        },
+        "heading": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "heading",
+          "required": true,
+          "mutable": false,
+          "description": "Section or destination heading shown in the card header."
+        },
+        "href": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "href",
+          "required": true,
+          "mutable": false,
+          "description": "Destination for the card's native link."
+        },
+        "variant": {
+          "type": "CardNavigationVariant",
+          "resolvedType": "\"content\" | \"navigation-only\"",
+          "attribute": "variant",
+          "default": "'navigation-only'",
+          "required": false,
+          "mutable": false,
+          "description": "`navigation-only` makes the complete card the link. `content` keeps the\nheader as the link and exposes a non-interactive body slot below it."
+        }
+      },
+      "events": [
+        {
+          "name": "dsNavigate",
+          "detail": "CardNavigationDetail",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true,
+          "description": "Emits before native navigation. Prevent this event to take over routing;\nthe component will then prevent the original link navigation."
+        }
+      ],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "cardWidth": {
+        "type": "CardNavigationWidth",
+        "resolvedType": "\"lg\" | \"md\" | \"sm\"",
+        "attribute": "card-width",
+        "default": "'md'",
+        "required": false,
+        "mutable": false,
+        "description": "Card width token (`sm` / `md` / `lg`)."
+      },
+      "description": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "description",
+        "required": false,
+        "mutable": false,
+        "description": "Optional supporting copy shown below the heading."
+      },
+      "heading": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "heading",
+        "required": true,
+        "mutable": false,
+        "description": "Section or destination heading shown in the card header."
+      },
+      "href": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "href",
+        "required": true,
+        "mutable": false,
+        "description": "Destination for the card's native link."
+      },
+      "variant": {
+        "type": "CardNavigationVariant",
+        "resolvedType": "\"content\" | \"navigation-only\"",
+        "attribute": "variant",
+        "default": "'navigation-only'",
+        "required": false,
+        "mutable": false,
+        "description": "`navigation-only` makes the complete card the link. `content` keeps the\nheader as the link and exposes a non-interactive body slot below it."
+      }
+    },
+    "events": [
+      {
+        "name": "dsNavigate",
+        "detail": "CardNavigationDetail",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true,
+        "description": "Emits before native navigation. Prevent this event to take over routing;\nthe component will then prevent the original link navigation."
+      }
+    ],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-card-navigation",
+      "react": "DsCardNavigation",
+      "vue": "DsCardNavigation",
+      "angular": "DsCardNavigation"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-card-navigation.js';",
+        "example": "<ds-card-navigation></ds-card-navigation>"
+      },
+      "react": {
+        "import": "import { DsCardNavigation } from '@ds-mo/ui/react';",
+        "example": "<DsCardNavigation />"
+      },
+      "vue": {
+        "import": "import { DsCardNavigation } from '@ds-mo/ui/vue';",
+        "example": "<DsCardNavigation />"
+      },
+      "angular": {
+        "import": "import { DsCardNavigation } from '@ds-mo/ui/angular/ds-card-navigation';",
+        "example": "<ds-card-navigation></ds-card-navigation>"
+      },
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^6.5.1",
+          "@ds-mo/icons ^7.0.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Vue 3 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens",
+    "@ds-mo/icons"
+  ],
+  "registryDependencies": [
+    "icon",
+    "text"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/CardNavigation/CardNavigation.css",
+      "content": "@import '../../utils/chrome-header.css';\n@import '../../utils/interaction-fill.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/forced-colors.css';\n\n:host {\n  position: relative;\n  display: flex;\n  flex-direction: column;\n  box-sizing: border-box;\n  width: var(--_card-navigation-width);\n  max-width: 100%;\n  overflow: hidden;\n  border: none;\n  border-radius: var(--dimension-radius-125);\n  background-color: var(--color-background-primary);\n  box-shadow: var(--effect-shadow-elevated-sm);\n}\n\n:host(.card-navigation--content) {\n  min-height: var(--_card-navigation-min-height);\n}\n\n:host::after {\n  content: '';\n  position: absolute;\n  inset: 0;\n  z-index: 4;\n  border-radius: inherit;\n  box-shadow: var(--effect-highlight-elevated-sm);\n  pointer-events: none;\n}\n\n.card-navigation__target {\n  color: inherit;\n  text-decoration: none;\n  cursor: pointer;\n}\n\n.card-navigation__header {\n  flex: 0 0 auto;\n  border-radius: inherit;\n}\n\n:host(.card-navigation--content) .card-navigation__header {\n  border-radius: var(--dimension-radius-125) var(--dimension-radius-125) 0 0;\n  --ds-interaction-divider-width: var(--dimension-stroke-width-012);\n  --ds-interaction-divider-color: var(--color-border-tertiary);\n}\n\n.card-navigation__copy {\n  min-height: var(--dimension-size-400);\n  justify-content: center;\n}\n\nds-text.card-navigation__title,\nds-text.card-navigation__description {\n  overflow-wrap: anywhere;\n}\n\n.card-navigation__chevron {\n  justify-content: center;\n  width: var(--dimension-size-400);\n  color: var(--color-foreground-secondary);\n}\n\n.card-navigation__body {\n  display: flex;\n  flex: 1 1 auto;\n  flex-direction: column;\n  min-height: 0;\n  box-sizing: border-box;\n  background-color: var(--color-background-primary);\n  border-radius: 0 0 var(--dimension-radius-125) var(--dimension-radius-125);\n}\n\n@media (forced-colors: active) {\n  :host {\n    box-shadow: none;\n    outline: var(--dimension-stroke-width-012) solid var(--ds-forced-color-content);\n    outline-offset: calc(-1 * var(--dimension-stroke-width-012));\n  }\n\n  :host::after {\n    box-shadow: none;\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/CardNavigation/CardNavigation.tsx",
+      "content": "import { Component, Event, EventEmitter, h, Host, Prop } from '@stencil/core';\nimport { resolveSafeUrl } from '../../utils';\n\nexport type CardNavigationWidth = 'sm' | 'md' | 'lg';\nexport type CardNavigationVariant = 'navigation-only' | 'content';\n\nexport interface CardNavigationDetail {\n  href: string;\n  originalEvent: MouseEvent;\n}\n\nconst CARD_WIDTH_VARS: Record<CardNavigationWidth, string> = {\n  sm: 'var(--dimension-card-width-sm)',\n  md: 'var(--dimension-card-width-md)',\n  lg: 'var(--dimension-card-width-lg)',\n};\n\nconst CARD_HEIGHT_VARS: Record<CardNavigationWidth, string> = {\n  sm: 'var(--dimension-card-height-sm)',\n  md: 'var(--dimension-card-height-md)',\n  lg: 'var(--dimension-card-height-lg)',\n};\n\n@Component({\n  tag: 'ds-card-navigation',\n  styleUrl: 'CardNavigation.css',\n  scoped: true,\n})\nexport class CardNavigation {\n  /** Destination for the card's native link. */\n  @Prop() href!: string;\n\n  /** Section or destination heading shown in the card header. */\n  @Prop() heading!: string;\n\n  /** Optional supporting copy shown below the heading. */\n  @Prop() description: string | undefined;\n\n  /**\n   * `navigation-only` makes the complete card the link. `content` keeps the\n   * header as the link and exposes a non-interactive body slot below it.\n   */\n  @Prop() variant: CardNavigationVariant = 'navigation-only';\n\n  /** Card width token (`sm` / `md` / `lg`). */\n  @Prop() cardWidth: CardNavigationWidth = 'md';\n\n  /**\n   * Emits before native navigation. Prevent this event to take over routing;\n   * the component will then prevent the original link navigation.\n   */\n  @Event({ cancelable: true }) dsNavigate!: EventEmitter<CardNavigationDetail>;\n\n  private handleNavigation(href: string, originalEvent: MouseEvent) {\n    const navigateEvent = this.dsNavigate.emit({ href, originalEvent });\n    if (navigateEvent.defaultPrevented) originalEvent.preventDefault();\n  }\n\n  private renderHeader(href: string | undefined) {\n    const Target = href ? 'a' : 'div';\n    const description = this.description?.trim();\n\n    return (\n      <Target\n        class={{\n          'card-navigation__target': true,\n          'card-navigation__header': true,\n          'ds-chrome-header': true,\n          'ds-interaction-fill': !!href,\n          'ds-focus-ring-inset': !!href,\n        }}\n        href={href}\n        onClick={href ? (event: MouseEvent) => this.handleNavigation(href, event) : undefined}\n      >\n        <div\n          class={{\n            'card-navigation__copy': true,\n            'ds-chrome-header__copy': true,\n            'ds-chrome-header__copy--stacked': !!description,\n            'ds-control--md': true,\n            'ds-interaction-fill__content': true,\n          }}\n        >\n          <ds-text\n            class=\"card-navigation__title ds-chrome-header__heading\"\n            variant=\"text-title-small\"\n            emphasis\n            color=\"primary\"\n            as=\"h2\"\n          >\n            {this.heading}\n          </ds-text>\n          {description ? (\n            <ds-text\n              class=\"card-navigation__description ds-chrome-header__description\"\n              variant=\"text-body-small\"\n              color=\"secondary\"\n              as=\"span\"\n            >\n              {description}\n            </ds-text>\n          ) : null}\n        </div>\n        <span class=\"card-navigation__chevron ds-chrome-header__trailing ds-interaction-fill__content\">\n          <ds-icon name=\"ChevronRight\" size=\"md\" color=\"inherit\" aria-hidden=\"true\" />\n        </span>\n      </Target>\n    );\n  }\n\n  render() {\n    const href = resolveSafeUrl(this.href);\n    const hasContent = this.variant === 'content';\n\n    return (\n      <Host\n        class={{\n          'card-navigation': true,\n          'card-navigation--navigation-only': !hasContent,\n          'card-navigation--content': hasContent,\n        }}\n        style={{\n          '--_card-navigation-width': CARD_WIDTH_VARS[this.cardWidth],\n          '--_card-navigation-min-height': CARD_HEIGHT_VARS[this.cardWidth],\n        }}\n      >\n        {this.renderHeader(href)}\n        {hasContent ? (\n          <div class=\"card-navigation__body\">\n            <slot />\n          </div>\n        ) : null}\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}