@ds-mo/ui 14.28.0 → 14.29.0

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

@@ -66,7 +66,8 @@
         "isInset opts into reduced outer geometry only when Tag is nested inside a control of the same density. The default single inset removes 4px overall; insetDepth double removes 8px overall and falls back to single at xs to protect minimum icon geometry. Semantic styling, typography, icons, gaps, radius, and interaction remain unchanged.",
         "Labels stay on one line and truncate only when the owner supplies a maximum width.",
         "Omitted interactive renders static metadata with no focus, event, or suffix. Interactive adds the fixed ChevronUpDown suffix and emits dsClick without toggling expanded internally.",
-        "isInactive disables only the interactive button and applies the shared inactive treatment."
+        "isInactive disables only the interactive button and applies the shared inactive treatment.",
+        "Interactive tags use surfaceOpen for the associated menu lifecycle, including exit motion. This holds the shared pressed wash without changing the intent that describes the metadata value. Static tags never acquire surface ownership."
       ],
       "responsiveBehavior": [
         "The owner selects md, sm, or xs density to match its local layout and owns collection wrapping, overflow, and condensation. Use isInset only for same-density control nesting.",
@@ -87,6 +88,10 @@
         {
           "label": "Storybook examples",
           "path": "src/wc/components/Tag/Tag.stories.ts"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -199,6 +204,14 @@
           "default": "'md'",
           "required": false,
           "mutable": false
+        },
+        "surfaceOpen": {
+          "type": "boolean | undefined",
+          "resolvedType": "boolean | undefined",
+          "attribute": "surface-open",
+          "required": false,
+          "mutable": false,
+          "description": "Associated menu remains visible, including exit motion. Omission preserves\nthe deprecated expanded-derived wash; explicit false suppresses it."
         }
       },
       "events": [
@@ -322,6 +335,14 @@
         "default": "'md'",
         "required": false,
         "mutable": false
+      },
+      "surfaceOpen": {
+        "type": "boolean | undefined",
+        "resolvedType": "boolean | undefined",
+        "attribute": "surface-open",
+        "required": false,
+        "mutable": false,
+        "description": "Associated menu remains visible, including exit motion. Omission preserves\nthe deprecated expanded-derived wash; explicit false suppresses it."
       }
     },
     "events": [
@@ -382,12 +403,12 @@
   "files": [
     {
       "path": "src/wc/components/Tag/Tag.css",
-      "content": "@import '../../utils/tag-chip.css';\n@import '../../utils/control-density-inset.css';\n\n/* A one-character rounded Tag resolves to a circle at every density. */\n:host {\n  min-inline-size: var(--ds-control-height);\n}\n\n/* ── Intent × Contrast — strong ─────────────────────────────────────────── */\n\n:host(.tag--intent-neutral.tag--contrast-strong) {\n  background-color: var(--color-background-strong-neutral);\n  color: var(--color-foreground-medium-neutral);\n}\n:host(.tag--intent-brand.tag--contrast-strong) {\n  background-color: var(--color-background-strong-brand);\n  color: var(--color-foreground-on-strong-background-primary);\n}\n:host(.tag--intent-ai.tag--contrast-strong) {\n  background-color: var(--color-background-strong-ai);\n  color: var(--color-foreground-medium-ai);\n}\n:host(.tag--intent-negative.tag--contrast-strong) {\n  background-color: var(--color-background-strong-negative);\n  color: var(--color-foreground-medium-negative);\n}\n:host(.tag--intent-warning.tag--contrast-strong) {\n  background-color: var(--color-background-strong-warning);\n  color: var(--color-foreground-medium-warning);\n}\n:host(.tag--intent-caution.tag--contrast-strong) {\n  background-color: var(--color-background-strong-caution);\n  color: var(--color-foreground-medium-caution);\n}\n:host(.tag--intent-positive.tag--contrast-strong) {\n  background-color: var(--color-background-strong-positive);\n  color: var(--color-foreground-medium-positive);\n}\n\n/* ── Intent × Contrast — bold ───────────────────────────────────────────── */\n\n:host(.tag--intent-neutral.tag--contrast-bold) {\n  background-color: var(--color-background-bold-neutral);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-brand.tag--contrast-bold) {\n  background-color: var(--color-background-bold-brand);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-ai.tag--contrast-bold) {\n  background-color: var(--color-background-bold-ai);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-negative.tag--contrast-bold) {\n  background-color: var(--color-background-bold-negative);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-warning.tag--contrast-bold) {\n  background-color: var(--color-background-bold-warning);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-caution.tag--contrast-bold) {\n  background-color: var(--color-background-bold-caution);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-positive.tag--contrast-bold) {\n  background-color: var(--color-background-bold-positive);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n\n/* ── Intent × Contrast — medium ─────────────────────────────────────────── */\n\n:host(.tag--intent-neutral.tag--contrast-medium) {\n  background-color: var(--color-background-medium-neutral);\n  color: var(--color-foreground-strong-neutral);\n}\n:host(.tag--intent-brand.tag--contrast-medium) {\n  background-color: var(--color-background-medium-brand);\n  color: var(--color-foreground-on-medium-background-primary);\n}\n:host(.tag--intent-ai.tag--contrast-medium) {\n  background-color: var(--color-background-medium-ai);\n  color: var(--color-foreground-strong-ai);\n}\n:host(.tag--intent-negative.tag--contrast-medium) {\n  background-color: var(--color-background-medium-negative);\n  color: var(--color-foreground-strong-negative);\n}\n:host(.tag--intent-warning.tag--contrast-medium) {\n  background-color: var(--color-background-medium-warning);\n  color: var(--color-foreground-strong-warning);\n}\n:host(.tag--intent-caution.tag--contrast-medium) {\n  background-color: var(--color-background-medium-caution);\n  color: var(--color-foreground-strong-caution);\n}\n:host(.tag--intent-positive.tag--contrast-medium) {\n  background-color: var(--color-background-medium-positive);\n  color: var(--color-foreground-strong-positive);\n}\n\n/* ── Intent × Contrast — faint ──────────────────────────────────────────── */\n\n:host(.tag--intent-neutral.tag--contrast-faint) {\n  background-color: var(--color-background-faint-neutral);\n  color: var(--color-foreground-bold-neutral);\n}\n:host(.tag--intent-brand.tag--contrast-faint) {\n  background-color: var(--color-background-faint-brand);\n  color: var(--color-foreground-bold-brand);\n}\n:host(.tag--intent-ai.tag--contrast-faint) {\n  background-color: var(--color-background-faint-ai);\n  color: var(--color-foreground-bold-ai);\n}\n:host(.tag--intent-negative.tag--contrast-faint) {\n  background-color: var(--color-background-faint-negative);\n  color: var(--color-foreground-bold-negative);\n}\n:host(.tag--intent-warning.tag--contrast-faint) {\n  background-color: var(--color-background-faint-warning);\n  color: var(--color-foreground-bold-warning);\n}\n:host(.tag--intent-caution.tag--contrast-faint) {\n  background-color: var(--color-background-faint-caution);\n  color: var(--color-foreground-bold-caution);\n}\n:host(.tag--intent-positive.tag--contrast-faint) {\n  background-color: var(--color-background-faint-positive);\n  color: var(--color-foreground-bold-positive);\n}\n\n/* ── Interactive menu trigger ───────────────────────────────────────────── */\n\n:host(.tag--interactive) {\n  padding: 0;\n  gap: 0;\n}\n\n.tag__button {\n  all: unset;\n  position: relative;\n  z-index: 0;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  min-width: 0;\n  max-width: 100%;\n  height: 100%;\n  padding: 0 var(--ds-control-padding-inline);\n  gap: var(--ds-control-gap);\n  border-radius: inherit;\n  color: inherit;\n  cursor: default;\n}\n\n.tag__button:disabled {\n  cursor: not-allowed;\n}\n\n.tag__button--expanded::after {\n  background: var(--ds-interaction-pressed);\n}\n\n/* Hover/press wash stays above the Tag's semantic background. */\n\n/* ── Icons ──────────────────────────────────────────────────────────────── */\n\n.tag__prefix-icon,\n.tag__suffix-icon {\n  position: relative;\n  z-index: 2;\n  display: inline-flex;\n  flex-shrink: 0;\n  width: var(--ds-control-icon);\n  height: var(--ds-control-icon);\n}\n",
+      "content": "@import '../../utils/tag-chip.css';\n@import '../../utils/control-density-inset.css';\n\n/* A one-character rounded Tag resolves to a circle at every density. */\n:host {\n  min-inline-size: var(--ds-control-height);\n}\n\n/* ── Intent × Contrast — strong ─────────────────────────────────────────── */\n\n:host(.tag--intent-neutral.tag--contrast-strong) {\n  background-color: var(--color-background-strong-neutral);\n  color: var(--color-foreground-medium-neutral);\n}\n:host(.tag--intent-brand.tag--contrast-strong) {\n  background-color: var(--color-background-strong-brand);\n  color: var(--color-foreground-on-strong-background-primary);\n}\n:host(.tag--intent-ai.tag--contrast-strong) {\n  background-color: var(--color-background-strong-ai);\n  color: var(--color-foreground-medium-ai);\n}\n:host(.tag--intent-negative.tag--contrast-strong) {\n  background-color: var(--color-background-strong-negative);\n  color: var(--color-foreground-medium-negative);\n}\n:host(.tag--intent-warning.tag--contrast-strong) {\n  background-color: var(--color-background-strong-warning);\n  color: var(--color-foreground-medium-warning);\n}\n:host(.tag--intent-caution.tag--contrast-strong) {\n  background-color: var(--color-background-strong-caution);\n  color: var(--color-foreground-medium-caution);\n}\n:host(.tag--intent-positive.tag--contrast-strong) {\n  background-color: var(--color-background-strong-positive);\n  color: var(--color-foreground-medium-positive);\n}\n\n/* ── Intent × Contrast — bold ───────────────────────────────────────────── */\n\n:host(.tag--intent-neutral.tag--contrast-bold) {\n  background-color: var(--color-background-bold-neutral);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-brand.tag--contrast-bold) {\n  background-color: var(--color-background-bold-brand);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-ai.tag--contrast-bold) {\n  background-color: var(--color-background-bold-ai);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-negative.tag--contrast-bold) {\n  background-color: var(--color-background-bold-negative);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-warning.tag--contrast-bold) {\n  background-color: var(--color-background-bold-warning);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-caution.tag--contrast-bold) {\n  background-color: var(--color-background-bold-caution);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n:host(.tag--intent-positive.tag--contrast-bold) {\n  background-color: var(--color-background-bold-positive);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n\n/* ── Intent × Contrast — medium ─────────────────────────────────────────── */\n\n:host(.tag--intent-neutral.tag--contrast-medium) {\n  background-color: var(--color-background-medium-neutral);\n  color: var(--color-foreground-strong-neutral);\n}\n:host(.tag--intent-brand.tag--contrast-medium) {\n  background-color: var(--color-background-medium-brand);\n  color: var(--color-foreground-on-medium-background-primary);\n}\n:host(.tag--intent-ai.tag--contrast-medium) {\n  background-color: var(--color-background-medium-ai);\n  color: var(--color-foreground-strong-ai);\n}\n:host(.tag--intent-negative.tag--contrast-medium) {\n  background-color: var(--color-background-medium-negative);\n  color: var(--color-foreground-strong-negative);\n}\n:host(.tag--intent-warning.tag--contrast-medium) {\n  background-color: var(--color-background-medium-warning);\n  color: var(--color-foreground-strong-warning);\n}\n:host(.tag--intent-caution.tag--contrast-medium) {\n  background-color: var(--color-background-medium-caution);\n  color: var(--color-foreground-strong-caution);\n}\n:host(.tag--intent-positive.tag--contrast-medium) {\n  background-color: var(--color-background-medium-positive);\n  color: var(--color-foreground-strong-positive);\n}\n\n/* ── Intent × Contrast — faint ──────────────────────────────────────────── */\n\n:host(.tag--intent-neutral.tag--contrast-faint) {\n  background-color: var(--color-background-faint-neutral);\n  color: var(--color-foreground-bold-neutral);\n}\n:host(.tag--intent-brand.tag--contrast-faint) {\n  background-color: var(--color-background-faint-brand);\n  color: var(--color-foreground-bold-brand);\n}\n:host(.tag--intent-ai.tag--contrast-faint) {\n  background-color: var(--color-background-faint-ai);\n  color: var(--color-foreground-bold-ai);\n}\n:host(.tag--intent-negative.tag--contrast-faint) {\n  background-color: var(--color-background-faint-negative);\n  color: var(--color-foreground-bold-negative);\n}\n:host(.tag--intent-warning.tag--contrast-faint) {\n  background-color: var(--color-background-faint-warning);\n  color: var(--color-foreground-bold-warning);\n}\n:host(.tag--intent-caution.tag--contrast-faint) {\n  background-color: var(--color-background-faint-caution);\n  color: var(--color-foreground-bold-caution);\n}\n:host(.tag--intent-positive.tag--contrast-faint) {\n  background-color: var(--color-background-faint-positive);\n  color: var(--color-foreground-bold-positive);\n}\n\n/* ── Interactive menu trigger ───────────────────────────────────────────── */\n\n:host(.tag--interactive) {\n  padding: 0;\n  gap: 0;\n}\n\n.tag__button {\n  all: unset;\n  position: relative;\n  z-index: 0;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  min-width: 0;\n  max-width: 100%;\n  height: 100%;\n  padding: 0 var(--ds-control-padding-inline);\n  gap: var(--ds-control-gap);\n  border-radius: inherit;\n  color: inherit;\n  cursor: default;\n}\n\n.tag__button:disabled {\n  cursor: not-allowed;\n}\n\n/* Hover/press wash stays above the Tag's semantic background. */\n\n/* ── Icons ──────────────────────────────────────────────────────────────── */\n\n.tag__prefix-icon,\n.tag__suffix-icon {\n  position: relative;\n  z-index: 2;\n  display: inline-flex;\n  flex-shrink: 0;\n  width: var(--ds-control-icon);\n  height: var(--ds-control-icon);\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/Tag/Tag.tsx",
-      "content": "import { Component, Event, EventEmitter, Prop, h, Host } from '@stencil/core';\nimport { CONTROL_TEXT_VARIANT, type ControlInsetDepth } from '../../utils';\n\nexport type TagIntent =\n  | 'neutral'\n  | 'brand'\n  | 'ai'\n  | 'negative'\n  | 'warning'\n  | 'caution'\n  | 'positive';\nexport type TagContrast = 'strong' | 'bold' | 'medium' | 'faint';\nexport type TagSize = 'md' | 'sm' | 'xs';\n\n/**\n * `ds-icon` size prop matching control-density icon metrics\n * (md→20 / sm→16 / xs→12 via `--dimension-iconography-*`).\n */\nconst ICON_SIZE: Record<TagSize, 'md' | 'sm' | 'xs'> = {\n  md: 'md',\n  sm: 'sm',\n  xs: 'xs',\n};\n\n@Component({\n  tag: 'ds-tag',\n  styleUrl: 'Tag.css',\n  scoped: true,\n})\nexport class Tag {\n  @Prop() label!: string;\n  /** Canonical icon name rendered before the visible label. */\n  @Prop() icon: string = '';\n  @Prop() intent: TagIntent = 'neutral';\n  @Prop() contrast: TagContrast = 'faint';\n  @Prop() size: TagSize = 'md';\n  /** Use the reduced outer geometry when nested inside a control of the same size. */\n  @Prop() isInset: boolean = false;\n  /** Single removes 4px overall; double removes 8px overall (xs stays single). */\n  @Prop() insetDepth: ControlInsetDepth = 'single';\n  @Prop() rounded: boolean = false;\n  @Prop() maxWidth: string | number | undefined;\n  /** Render a menu-trigger button with a fixed ChevronUpDown suffix. */\n  @Prop() interactive: boolean = false;\n  /** Controlled open state for the menu triggered by an interactive Tag. */\n  @Prop() expanded: boolean = false;\n  /** ID of the menu controlled by an interactive Tag. */\n  @Prop() ariaControls: string | undefined;\n  /** Disable an interactive Tag and apply the shared inactive treatment. */\n  @Prop() isInactive: boolean = false;\n\n  /** Fired when the interactive Tag button is activated. */\n  @Event() dsClick!: EventEmitter<MouseEvent>;\n\n  private handleClick = (event: MouseEvent) => {\n    if (!this.interactive || this.isInactive) return;\n    this.dsClick.emit(event);\n  };\n\n  render() {\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const iconSize = ICON_SIZE[this.size];\n    const doubleInset = this.isInset && this.insetDepth === 'double' && this.size !== 'xs';\n\n    const maxWidthStyle =\n      this.maxWidth != null\n        ? { maxWidth: typeof this.maxWidth === 'number' ? `${this.maxWidth}px` : this.maxWidth }\n        : undefined;\n    const hostClass = {\n      tag: true,\n      [`tag--intent-${this.intent}`]: true,\n      [`tag--contrast-${this.contrast}`]: true,\n      [`tag--size-${this.size}`]: true,\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 && !doubleInset,\n      'ds-control--inset-double': doubleInset,\n      'tag--rounded': this.rounded,\n      'tag--interactive': this.interactive,\n      'ds-control-inactive': this.interactive && this.isInactive,\n    };\n    const content = [\n      this.icon && (\n        <ds-icon\n          class=\"tag__prefix-icon\"\n          name={this.icon}\n          size={iconSize}\n          color=\"inherit\"\n        ></ds-icon>\n      ),\n      <ds-text class=\"tag__label\" as=\"span\" variant={textVariant} color=\"inherit\">\n        {this.label}\n      </ds-text>,\n    ];\n\n    if (!this.interactive) {\n      return (\n        <Host class={hostClass} style={maxWidthStyle}>\n          {content}\n        </Host>\n      );\n    }\n\n    return (\n      <Host class={hostClass} style={maxWidthStyle}>\n        <button\n          type=\"button\"\n          class={{\n            tag__button: true,\n            'tag__button--expanded': this.expanded,\n            'ds-interaction-fill': true,\n            'ds-focus-ring-inset': true,\n          }}\n          aria-haspopup=\"menu\"\n          aria-expanded={this.expanded ? 'true' : 'false'}\n          aria-controls={this.ariaControls}\n          disabled={this.isInactive || undefined}\n          onClick={this.handleClick}\n        >\n          {content}\n          <ds-icon\n            class=\"tag__suffix-icon\"\n            name=\"ChevronUpDown\"\n            size={iconSize}\n            color=\"inherit\"\n          ></ds-icon>\n        </button>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Event, EventEmitter, Prop, h, Host } from '@stencil/core';\nimport { CONTROL_TEXT_VARIANT, type ControlInsetDepth } from '../../utils';\n\nexport type TagIntent =\n  | 'neutral'\n  | 'brand'\n  | 'ai'\n  | 'negative'\n  | 'warning'\n  | 'caution'\n  | 'positive';\nexport type TagContrast = 'strong' | 'bold' | 'medium' | 'faint';\nexport type TagSize = 'md' | 'sm' | 'xs';\n\n/**\n * `ds-icon` size prop matching control-density icon metrics\n * (md→20 / sm→16 / xs→12 via `--dimension-iconography-*`).\n */\nconst ICON_SIZE: Record<TagSize, 'md' | 'sm' | 'xs'> = {\n  md: 'md',\n  sm: 'sm',\n  xs: 'xs',\n};\n\n@Component({\n  tag: 'ds-tag',\n  styleUrl: 'Tag.css',\n  scoped: true,\n})\nexport class Tag {\n  @Prop() label!: string;\n  /** Canonical icon name rendered before the visible label. */\n  @Prop() icon: string = '';\n  @Prop() intent: TagIntent = 'neutral';\n  @Prop() contrast: TagContrast = 'faint';\n  @Prop() size: TagSize = 'md';\n  /** Use the reduced outer geometry when nested inside a control of the same size. */\n  @Prop() isInset: boolean = false;\n  /** Single removes 4px overall; double removes 8px overall (xs stays single). */\n  @Prop() insetDepth: ControlInsetDepth = 'single';\n  @Prop() rounded: boolean = false;\n  @Prop() maxWidth: string | number | undefined;\n  /** Render a menu-trigger button with a fixed ChevronUpDown suffix. */\n  @Prop() interactive: boolean = false;\n  /** Controlled open state for the menu triggered by an interactive Tag. */\n  @Prop() expanded: boolean = false;\n  /** Associated menu remains visible, including exit motion. Omission preserves\n   * the deprecated expanded-derived wash; explicit false suppresses it. */\n  @Prop() surfaceOpen: boolean | undefined;\n  /** ID of the menu controlled by an interactive Tag. */\n  @Prop() ariaControls: string | undefined;\n  /** Disable an interactive Tag and apply the shared inactive treatment. */\n  @Prop() isInactive: boolean = false;\n\n  /** Fired when the interactive Tag button is activated. */\n  @Event() dsClick!: EventEmitter<MouseEvent>;\n\n  private handleClick = (event: MouseEvent) => {\n    if (!this.interactive || this.isInactive) return;\n    this.dsClick.emit(event);\n  };\n\n  render() {\n    const textVariant = CONTROL_TEXT_VARIANT[this.size];\n    const iconSize = ICON_SIZE[this.size];\n    const doubleInset = this.isInset && this.insetDepth === 'double' && this.size !== 'xs';\n\n    const maxWidthStyle =\n      this.maxWidth != null\n        ? { maxWidth: typeof this.maxWidth === 'number' ? `${this.maxWidth}px` : this.maxWidth }\n        : undefined;\n    const hostClass = {\n      tag: true,\n      [`tag--intent-${this.intent}`]: true,\n      [`tag--contrast-${this.contrast}`]: true,\n      [`tag--size-${this.size}`]: true,\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 && !doubleInset,\n      'ds-control--inset-double': doubleInset,\n      'tag--rounded': this.rounded,\n      'tag--interactive': this.interactive,\n      'ds-control-inactive': this.interactive && this.isInactive,\n    };\n    const content = [\n      this.icon && (\n        <ds-icon\n          class=\"tag__prefix-icon\"\n          name={this.icon}\n          size={iconSize}\n          color=\"inherit\"\n        ></ds-icon>\n      ),\n      <ds-text class=\"tag__label\" as=\"span\" variant={textVariant} color=\"inherit\">\n        {this.label}\n      </ds-text>,\n    ];\n\n    if (!this.interactive) {\n      return (\n        <Host class={hostClass} style={maxWidthStyle}>\n          {content}\n        </Host>\n      );\n    }\n\n    return (\n      <Host class={hostClass} style={maxWidthStyle}>\n        <button\n          type=\"button\"\n          class={{\n            tag__button: true,\n            'tag__button--expanded': this.expanded,\n            'ds-interaction-fill--surface-open':\n              (this.surfaceOpen ?? this.expanded) && !this.isInactive,\n            'ds-interaction-fill': true,\n            'ds-focus-ring-inset': true,\n          }}\n          aria-haspopup=\"menu\"\n          aria-expanded={this.expanded ? 'true' : 'false'}\n          aria-controls={this.ariaControls}\n          disabled={this.isInactive || undefined}\n          onClick={this.handleClick}\n        >\n          {content}\n          <ds-icon\n            class=\"tag__suffix-icon\"\n            name=\"ChevronUpDown\"\n            size={iconSize}\n            color=\"inherit\"\n          ></ds-icon>\n        </button>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/styles/table.css

@@ -1206,6 +1206,7 @@
 
 :where(.ds-table__row > .ds-table__cell.ds-interaction-fill) {
   --ds-interaction-active: var(--_table-row-selected);
+  --ds-interaction-pressed: var(--_table-row-pressed);
   --ds-interaction-group-fill: transparent;
 }
 

package/dist/types/components/BarTitle/BarTitle.d.ts

@@ -52,6 +52,8 @@ export declare class BarTitle {
     dsAction: EventEmitter<string>;
     private sectionMenuOpen;
     private openActionMenuId;
+    private surfaceActionMenuId;
+    private sectionSurfaceOpen;
     private sectionMenuInitialFocusVisible;
     private actionMenuInitialFocusVisible;
     private readonly instanceId;
@@ -92,6 +94,7 @@ export declare class BarTitle {
     private closeSectionMenu;
     private handleSectionSelect;
     private toggleActionMenu;
+    private finishActionMenuClose;
     private closeActionMenu;
     private handleActionSelect;
     private renderSectionSelector;

package/dist/types/components/ButtonFilled/ButtonFilled.d.ts

@@ -62,11 +62,18 @@ export declare class ButtonFilled {
     /** ID of the popup this button controls. */
     controls: string | undefined;
     /**
-     * Controlled open state of the popup this button triggers. Holds the pressed
-     * wash for the popup's rendered lifecycle. ButtonFilled has no selected state,
-     * so an open popup never promotes to an active treatment.
+     * Controlled disclosure state forwarded to aria-expanded.
+     * Using expanded alone for surface-open styling is deprecated; set surfaceOpen
+     * explicitly to separate the rendered surface lifecycle from disclosure state.
      */
     expanded: boolean | undefined;
+    /**
+     * The associated menu, picker, or panel is visible, including its exit motion.
+     * Holds only the pressed wash; does not set ARIA, selection, or press scaling.
+     * In split mode this applies only to the menu segment. Explicit false disables
+     * the legacy expanded-derived wash; omission preserves that compatibility path.
+     */
+    surfaceOpen: boolean | undefined;
     /** Popup type exposed to assistive technology. */
     haspopup: ButtonFilledPopup | undefined;
     /**
@@ -95,6 +102,7 @@ export declare class ButtonFilled {
     private handleClick;
     private handleMenuClick;
     private get resolvedHaspopup();
+    private get resolvedSurfaceOpen();
     private get accessibleName();
     private get doubleInset();
     private buttonClass;

package/dist/types/components/ButtonUnfilled/ButtonUnfilled.d.ts

@@ -61,11 +61,18 @@ export declare class ButtonUnfilled {
     ariaLabel: string | null;
     controls: string | undefined;
     /**
-     * Controlled disclosure or popup state forwarded to `aria-expanded`.
-     * Popup triggers hold only the pressed wash while open; their resting
-     * foreground is unchanged. Ordinary disclosures remain visually neutral.
+     * Controlled disclosure state forwarded to aria-expanded.
+     * Using expanded alone for surface-open styling is deprecated; set surfaceOpen
+     * explicitly to separate the rendered surface lifecycle from disclosure state.
      */
     expanded: boolean | undefined;
+    /**
+     * The associated menu, picker, or panel is visible, including its exit motion.
+     * Holds only the pressed wash; does not set ARIA, selection, or press scaling.
+     * In split mode this applies only to the menu segment. Explicit false disables
+     * the legacy expanded-derived wash; omission preserves that compatibility path.
+     */
+    surfaceOpen: boolean | undefined;
     haspopup: ButtonUnfilledPopup | undefined;
     /**
      * Append a separate ChevronDown menu segment while preserving this button's
@@ -126,8 +133,7 @@ export declare class ButtonUnfilled {
     private disconnectCaptionCompactObserver;
     private get resolvedHaspopup();
     private get doubleInset();
-    /** Only popup triggers hold a pressed visual while expanded. */
-    private get expandedPopup();
+    private get resolvedSurfaceOpen();
     private get visuallyActive();
     /** Knock-out ring: selected fill → active wash; otherwise surface token. */
     private get dotRing();

package/dist/types/components/MobileSectionSwitcher/MobileSectionSwitcher.d.ts

@@ -15,6 +15,7 @@ export declare class MobileSectionSwitcher {
     /** Selection intent. The route, tool, or workflow owner updates `value`. */
     dsChange: EventEmitter<string>;
     private menuOpen;
+    private menuSurfaceOpen;
     private initialFocusVisible;
     private sheetClosing;
     private focusedSection;
@@ -28,6 +29,7 @@ export declare class MobileSectionSwitcher {
     componentDidLoad(): void;
     componentDidRender(): void;
     disconnectedCallback(): void;
+    handlePresentationChange(): void;
     handleContextChange(): void;
     private finishSheetClose;
     private focusSheetItem;

package/dist/types/components/PanelNav/PanelNav.d.ts

@@ -40,8 +40,11 @@ export declare class PanelNav {
     dashboardLabel: string;
     settingsLabel: string;
     accountLabel: string;
-    /** Keep the account-menu trigger visually pressed while its popup is open or closing. */
+    /** Account disclosure state. Expanded-derived styling is deprecated; use accountMenuSurfaceOpen for the rendered lifetime. */
     accountMenuExpanded: boolean;
+    /** External account surface is visible, including exit motion. Omission
+     * preserves the deprecated accountMenuExpanded-derived wash. */
+    accountMenuSurfaceOpen: boolean | undefined;
     dashboardNavigationLabel: string;
     settingsNavigationLabel: string;
     expandNavigationLabel: string;

package/dist/types/components/PanelToolHeader/PanelToolHeader.d.ts

@@ -20,6 +20,8 @@ export declare class PanelToolHeader {
     menuControls: string | undefined;
     /** Whether the controlled menu is open. */
     menuExpanded: boolean;
+    /** Associated menu surface is visible, including exit motion. */
+    menuSurfaceOpen: boolean | undefined;
     /** Trailing application-owned icon actions. When present, these replace the legacy menu action. */
     actions: PanelToolsHeaderAction[];
     dsBack: EventEmitter<MouseEvent>;

package/dist/types/components/PanelToolSearch/PanelToolSearch.d.ts

@@ -21,6 +21,8 @@ export declare class PanelToolSearch {
     filterControls: string | undefined;
     /** Whether the controlled filter menu is open. */
     filterExpanded: boolean;
+    /** Associated filter surface is visible, including exit motion. */
+    filterSurfaceOpen: boolean | undefined;
     /** Promote the trigger foreground when one or more filters are applied. */
     filterActive: boolean;
     dsChange: EventEmitter<string>;

package/dist/types/components/PanelTools/panel-tools-types.d.ts

@@ -113,6 +113,8 @@ export interface PanelToolsHeaderAction {
     triggerId?: string;
     controls?: string;
     expanded?: boolean;
+    /** Associated surface remains visible, including exit motion. */
+    surfaceOpen?: boolean;
     haspopup?: 'menu' | 'dialog' | 'listbox' | 'tree' | 'grid';
     pressed?: boolean;
     isInactive?: boolean;

package/dist/types/components/ShellApp/ShellApp.d.ts

@@ -91,6 +91,7 @@ export declare class ShellApp {
     private managedInboxTool;
     private managedBrowseContext;
     private mobileActionMenuOpen;
+    private mobileActionSurfaceOpen;
     private mobileActionMenuInitialFocusVisible;
     private readonly instanceId;
     private readonly mobileActionMenuTriggerId;

package/dist/types/components/ShellApp/shell-app-types.d.ts

@@ -32,6 +32,8 @@ export interface ShellNavigationConfig {
     userName?: string;
     userInitial?: string;
     accountMenuExpanded?: boolean;
+    /** Associated account surface remains visible, including exit motion. */
+    accountMenuSurfaceOpen?: boolean;
     dashboardLabel?: string;
     settingsLabel?: string;
     accountLabel?: string;

package/dist/types/components/Table/Table.d.ts

@@ -61,6 +61,13 @@ export declare class Table {
     selectionMode: TableSelectionMode;
     /** Controlled selected row identities. IDs outside the loaded rows are preserved. */
     selectedRowIds: string[];
+    /**
+     * Identity of the interactive row whose associated surface is visible.
+     * Holds its pressed wash independently of checkbox selection. Keep the ID
+     * through exit motion and clear it after close; the application owns toggling
+     * and switching the surface. Off-window identities survive virtualization.
+     */
+    surfaceOpenRowId: string | undefined;
     /** Initial loading state. Existing rows stay visible; incremental loading uses loadingMore. */
     loading: boolean;
     /** Replace opted-in table-owned caption controls with same-size visual skeletons. */
@@ -132,11 +139,14 @@ export declare class Table {
     private fitPageSize;
     private actionMenu;
     private actionMenuInitialFocusVisible;
+    private actionMenuSurface;
     private truncateTooltipLabel;
     private captionCompact;
     private columnCustomizerOpen;
+    private columnCustomizerSurfaceOpen;
     private columnCustomizerInitialFocusVisible;
     private dataModeSwitcherOpen;
+    private dataModeSwitcherSurfaceOpen;
     private dataModeSwitcherInitialFocusVisible;
     private virtualWindow;
     private readonly actionMenuElementId;

package/dist/types/components/Table/table-row-view.d.ts

@@ -11,8 +11,13 @@ export interface TableRowViewOptions {
         rowId: string;
         columnId: string;
     } | null;
+    actionMenuSurface?: {
+        rowId: string;
+        columnId: string;
+    } | null;
     highlightMatcher: TableHighlightMatcher;
     highlightFieldIds: string[];
+    surfaceOpenRowId?: string;
     ariaRowIndex?: number;
     variableVirtualSize?: boolean;
     intrinsicBlockSize?: number;
@@ -26,5 +31,5 @@ export interface TableRowViewOptions {
     onActionMenuToggle: (row: TableRow, column: TableColumn, event: MouseEvent) => void;
 }
 /** Render one semantic body row and the complete declarative table-cell vocabulary. */
-export declare function renderTableRow({ row, model, visibleColumns, emptyCellLabel, actionMenuElementId, actionMenu, highlightMatcher, highlightFieldIds, ariaRowIndex, variableVirtualSize, intrinsicBlockSize, rowKey, renderSelectionControl, renderStickyEdge, onRowActivate, onRowKeyDown, onRowSelection, onCellAction, onActionMenuToggle, }: TableRowViewOptions): any;
+export declare function renderTableRow({ row, model, visibleColumns, emptyCellLabel, actionMenuElementId, actionMenu, actionMenuSurface, highlightMatcher, highlightFieldIds, surfaceOpenRowId, ariaRowIndex, variableVirtualSize, intrinsicBlockSize, rowKey, renderSelectionControl, renderStickyEdge, onRowActivate, onRowKeyDown, onRowSelection, onCellAction, onActionMenuToggle, }: TableRowViewOptions): any;
 //# sourceMappingURL=table-row-view.d.ts.map

package/dist/types/components/TableSort/TableSort.d.ts

@@ -10,6 +10,7 @@ export declare class TableSort {
     ariaLabel: string | null;
     dsSortChange: EventEmitter<TableSortChangeDetail>;
     private menuOpen;
+    private menuSurfaceOpen;
     private initialFocusVisible;
     private readonly componentId;
     private readonly triggerId;

package/dist/types/components/Tag/Tag.d.ts

@@ -20,6 +20,9 @@ export declare class Tag {
     interactive: boolean;
     /** Controlled open state for the menu triggered by an interactive Tag. */
     expanded: boolean;
+    /** Associated menu remains visible, including exit motion. Omission preserves
+     * the deprecated expanded-derived wash; explicit false suppresses it. */
+    surfaceOpen: boolean | undefined;
     /** ID of the menu controlled by an interactive Tag. */
     ariaControls: string | undefined;
     /** Disable an interactive Tag and apply the shared inactive treatment. */

package/dist/types/components.d.ts

@@ -599,7 +599,7 @@ export namespace Components {
          */
         "controls": string | undefined;
         /**
-          * Controlled open state of the popup this button triggers. Holds the pressed wash for the popup's rendered lifecycle. ButtonFilled has no selected state, so an open popup never promotes to an active treatment.
+          * Controlled disclosure state forwarded to aria-expanded. Using expanded alone for surface-open styling is deprecated; set surfaceOpen explicitly to separate the rendered surface lifecycle from disclosure state.
          */
         "expanded": boolean | undefined;
         /**
@@ -682,6 +682,10 @@ export namespace Components {
           * @default false
          */
         "split": boolean;
+        /**
+          * The associated menu, picker, or panel is visible, including its exit motion. Holds only the pressed wash; does not set ARIA, selection, or press scaling. In split mode this applies only to the menu segment. Explicit false disables the legacy expanded-derived wash; omission preserves that compatibility path.
+         */
+        "surfaceOpen": boolean | undefined;
         /**
           * Native button type.
           * @default 'button'
@@ -725,7 +729,7 @@ export namespace Components {
          */
         "dot": boolean;
         /**
-          * Controlled disclosure or popup state forwarded to `aria-expanded`. Popup triggers hold only the pressed wash while open; their resting foreground is unchanged. Ordinary disclosures remain visually neutral.
+          * Controlled disclosure state forwarded to aria-expanded. Using expanded alone for surface-open styling is deprecated; set surfaceOpen explicitly to separate the rendered surface lifecycle from disclosure state.
          */
         "expanded": boolean | undefined;
         /**
@@ -813,6 +817,10 @@ export namespace Components {
           * @default false
          */
         "split": boolean;
+        /**
+          * The associated menu, picker, or panel is visible, including its exit motion. Holds only the pressed wash; does not set ARIA, selection, or press scaling. In split mode this applies only to the menu segment. Explicit false disables the legacy expanded-derived wash; omission preserves that compatibility path.
+         */
+        "surfaceOpen": boolean | undefined;
         /**
           * Native button type.
           * @default 'button'
@@ -2151,10 +2159,14 @@ export namespace Components {
          */
         "accountLabel": string;
         /**
-          * Keep the account-menu trigger visually pressed while its popup is open or closing.
+          * Account disclosure state. Expanded-derived styling is deprecated; use accountMenuSurfaceOpen for the rendered lifetime.
           * @default false
          */
         "accountMenuExpanded": boolean;
+        /**
+          * External account surface is visible, including exit motion. Omission preserves the deprecated accountMenuExpanded-derived wash.
+         */
+        "accountMenuSurfaceOpen": boolean | undefined;
         /**
           * ID of the active child route when URL matching is unavailable.
           * @default ''
@@ -2311,6 +2323,10 @@ export namespace Components {
           * @default false
          */
         "menuExpanded": boolean;
+        /**
+          * Associated menu surface is visible, including exit motion.
+         */
+        "menuSurfaceOpen": boolean | undefined;
         /**
           * Stable id placed on the menu trigger host for ds-menu anchoring.
           * @default ''
@@ -2356,6 +2372,10 @@ export namespace Components {
           * @default false
          */
         "filterExpanded": boolean;
+        /**
+          * Associated filter surface is visible, including exit motion.
+         */
+        "filterSurfaceOpen": boolean | undefined;
         /**
           * Stable id placed on the filter trigger for ds-menu anchoring.
           * @default ''
@@ -3446,6 +3466,10 @@ export namespace Components {
           * @default false
          */
         "stickyHeader": boolean;
+        /**
+          * Identity of the interactive row whose associated surface is visible. Holds its pressed wash independently of checkbox selection. Keep the ID through exit motion and clear it after close; the application owns toggling and switching the surface. Off-window identities survive virtualization.
+         */
+        "surfaceOpenRowId": string | undefined;
         "totalCount": number | undefined;
         /**
           * Reserved space below a viewport-fitted table.
@@ -3713,6 +3737,10 @@ export namespace Components {
           * @default 'md'
          */
         "size": TagSize;
+        /**
+          * Associated menu remains visible, including exit motion. Omission preserves the deprecated expanded-derived wash; explicit false suppresses it.
+         */
+        "surfaceOpen": boolean | undefined;
     }
     interface DsText {
         "align": TextAlign | undefined;
@@ -6083,7 +6111,7 @@ declare namespace LocalJSX {
          */
         "controls"?: string | undefined;
         /**
-          * Controlled open state of the popup this button triggers. Holds the pressed wash for the popup's rendered lifecycle. ButtonFilled has no selected state, so an open popup never promotes to an active treatment.
+          * Controlled disclosure state forwarded to aria-expanded. Using expanded alone for surface-open styling is deprecated; set surfaceOpen explicitly to separate the rendered surface lifecycle from disclosure state.
          */
         "expanded"?: boolean | undefined;
         /**
@@ -6167,6 +6195,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "split"?: boolean;
+        /**
+          * The associated menu, picker, or panel is visible, including its exit motion. Holds only the pressed wash; does not set ARIA, selection, or press scaling. In split mode this applies only to the menu segment. Explicit false disables the legacy expanded-derived wash; omission preserves that compatibility path.
+         */
+        "surfaceOpen"?: boolean | undefined;
         /**
           * Native button type.
           * @default 'button'
@@ -6210,7 +6242,7 @@ declare namespace LocalJSX {
          */
         "dot"?: boolean;
         /**
-          * Controlled disclosure or popup state forwarded to `aria-expanded`. Popup triggers hold only the pressed wash while open; their resting foreground is unchanged. Ordinary disclosures remain visually neutral.
+          * Controlled disclosure state forwarded to aria-expanded. Using expanded alone for surface-open styling is deprecated; set surfaceOpen explicitly to separate the rendered surface lifecycle from disclosure state.
          */
         "expanded"?: boolean | undefined;
         /**
@@ -6300,6 +6332,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "split"?: boolean;
+        /**
+          * The associated menu, picker, or panel is visible, including its exit motion. Holds only the pressed wash; does not set ARIA, selection, or press scaling. In split mode this applies only to the menu segment. Explicit false disables the legacy expanded-derived wash; omission preserves that compatibility path.
+         */
+        "surfaceOpen"?: boolean | undefined;
         /**
           * Native button type.
           * @default 'button'
@@ -7760,10 +7796,14 @@ declare namespace LocalJSX {
          */
         "accountLabel"?: string;
         /**
-          * Keep the account-menu trigger visually pressed while its popup is open or closing.
+          * Account disclosure state. Expanded-derived styling is deprecated; use accountMenuSurfaceOpen for the rendered lifetime.
           * @default false
          */
         "accountMenuExpanded"?: boolean;
+        /**
+          * External account surface is visible, including exit motion. Omission preserves the deprecated accountMenuExpanded-derived wash.
+         */
+        "accountMenuSurfaceOpen"?: boolean | undefined;
         /**
           * ID of the active child route when URL matching is unavailable.
           * @default ''
@@ -7941,6 +7981,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "menuExpanded"?: boolean;
+        /**
+          * Associated menu surface is visible, including exit motion.
+         */
+        "menuSurfaceOpen"?: boolean | undefined;
         /**
           * Stable id placed on the menu trigger host for ds-menu anchoring.
           * @default ''
@@ -7989,6 +8033,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "filterExpanded"?: boolean;
+        /**
+          * Associated filter surface is visible, including exit motion.
+         */
+        "filterSurfaceOpen"?: boolean | undefined;
         /**
           * Stable id placed on the filter trigger for ds-menu anchoring.
           * @default ''
@@ -9194,6 +9242,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "stickyHeader"?: boolean;
+        /**
+          * Identity of the interactive row whose associated surface is visible. Holds its pressed wash independently of checkbox selection. Keep the ID through exit motion and clear it after close; the application owns toggling and switching the surface. Off-window identities survive virtualization.
+         */
+        "surfaceOpenRowId"?: string | undefined;
         "totalCount"?: number | undefined;
         /**
           * Reserved space below a viewport-fitted table.
@@ -9531,6 +9583,10 @@ declare namespace LocalJSX {
           * @default 'md'
          */
         "size"?: TagSize;
+        /**
+          * Associated menu remains visible, including exit motion. Omission preserves the deprecated expanded-derived wash; explicit false suppresses it.
+         */
+        "surfaceOpen"?: boolean | undefined;
     }
     interface DsText {
         "align"?: TextAlign | undefined;
@@ -9958,6 +10014,7 @@ declare namespace LocalJSX {
         "ariaLabel": string | null;
         "controls": string | undefined;
         "expanded": boolean | undefined;
+        "surfaceOpen": boolean | undefined;
         "haspopup": ButtonFilledPopup | undefined;
         "split": boolean;
         "menuAriaLabel": string;
@@ -9985,6 +10042,7 @@ declare namespace LocalJSX {
         "ariaLabel": string | null;
         "controls": string | undefined;
         "expanded": boolean | undefined;
+        "surfaceOpen": boolean | undefined;
         "haspopup": ButtonUnfilledPopup | undefined;
         "split": boolean;
         "menuAriaLabel": string;
@@ -10340,6 +10398,7 @@ declare namespace LocalJSX {
         "settingsLabel": string;
         "accountLabel": string;
         "accountMenuExpanded": boolean;
+        "accountMenuSurfaceOpen": boolean | undefined;
         "dashboardNavigationLabel": string;
         "settingsNavigationLabel": string;
         "expandNavigationLabel": string;
@@ -10362,6 +10421,7 @@ declare namespace LocalJSX {
         "menuTriggerId": string;
         "menuControls": string | undefined;
         "menuExpanded": boolean;
+        "menuSurfaceOpen": boolean | undefined;
     }
     interface DsPanelToolSearchAttributes {
         "value": string;
@@ -10374,6 +10434,7 @@ declare namespace LocalJSX {
         "filterTriggerId": string;
         "filterControls": string | undefined;
         "filterExpanded": boolean;
+        "filterSurfaceOpen": boolean | undefined;
         "filterActive": boolean;
     }
     interface DsPanelToolsAttributes {
@@ -10560,6 +10621,7 @@ declare namespace LocalJSX {
         "viewportInsetBlockEnd": string;
         "scrollLabel": string | undefined;
         "selectionMode": TableSelectionMode;
+        "surfaceOpenRowId": string | undefined;
         "loading": boolean;
         "chromeLoading": boolean;
         "skeletonRows": number;
@@ -10646,6 +10708,7 @@ declare namespace LocalJSX {
         "maxWidth": string;
         "interactive": boolean;
         "expanded": boolean;
+        "surfaceOpen": boolean | undefined;
         "ariaControls": string | undefined;
         "isInactive": boolean;
     }

package/dist/types/utils/choice-list.d.ts

@@ -22,6 +22,8 @@ export interface ChoiceOptionAction {
     controls?: string;
     /** Keep the action visible and expose its controlled popup state. */
     expanded?: boolean;
+    /** Keep the action visible and held while its associated surface is rendered. */
+    surfaceOpen?: boolean;
 }
 export interface ChoiceSection {
     header?: string;

package/dist/vue/ds-button-filled.js

@@ -24,6 +24,7 @@ export const DsButtonFilled = /*@__PURE__*/ defineContainer('ds-button-filled',
     'ariaLabel',
     'controls',
     'expanded',
+    'surfaceOpen',
     'haspopup',
     'split',
     'menuAriaLabel',

package/dist/vue/ds-button-unfilled.js

@@ -25,6 +25,7 @@ export const DsButtonUnfilled = /*@__PURE__*/ defineContainer('ds-button-unfille
     'ariaLabel',
     'controls',
     'expanded',
+    'surfaceOpen',
     'haspopup',
     'split',
     'menuAriaLabel',