@ds-mo/ui 14.28.0 → 14.29.1

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

@@ -81,6 +81,7 @@
         "The flow-preservation spacer follows contentSurface so compacting a secondary page cannot expose a primary strip before its content.",
         "On roomy pages, the expanded header scrolls upward until its title and action row reaches the compact row position, while its bottom divider progressively extends from the expanded inset to edge-to-edge; it then snaps variants without moving that shared visual anchor.",
         "Scroll compaction preserves the expanded page flow offset so content never jumps beneath the sticky header.",
+        "The sticky header paints above the isolated routed-content layer, so product surfaces and callouts scroll beneath its opaque boundary instead of covering page chrome.",
         "ShellPage relies on ShellApp's content scroller and never introduces nested scrolling.",
         "BarWorkflow remains compact and is not assigned BarTitle's capacity or scroll variants."
       ],
@@ -341,7 +342,7 @@
   "files": [
     {
       "path": "src/wc/components/ShellPage/ShellPage.css",
-      "content": ":host {\n  --_shell-page-content-background: var(--color-background-primary);\n  --_shell-page-header-background: var(--color-background-primary);\n  --_shell-page-responsive-content-block-start-inset: var(--dimension-space-400);\n  --_shell-page-content-block-start-inset: var(\n    --ds-shell-page-content-block-start-inset,\n    var(--_shell-page-responsive-content-block-start-inset)\n  );\n  --ds-shell-page-sticky-header-block-size: var(--dimension-size-600);\n  --ds-shell-page-content-block-start-offset: calc(\n    var(--ds-shell-page-sticky-header-block-size) + var(--_shell-page-content-block-start-inset)\n  );\n  display: block;\n  position: relative;\n  min-width: 0;\n  min-height: 100%;\n  box-sizing: border-box;\n  background: var(--_shell-page-content-background);\n}\n\n:host(.shell-page-host--surface-secondary) {\n  --_shell-page-content-background: var(--color-background-secondary);\n}\n\n:host(.shell-page-host--surface-secondary[responsive-mode='desktop']),\n:host(.shell-page-host--surface-secondary[responsive-mode='tablet']) {\n  --_shell-page-header-background: var(--color-background-secondary);\n}\n\n:host([responsive-mode='tablet']),\n:host([responsive-mode='mobile']) {\n  --_shell-page-responsive-content-block-start-inset: var(--dimension-space-200);\n}\n\n:host([responsive-mode='mobile']) {\n  --ds-shell-page-sticky-header-block-size: calc(\n    var(--dimension-size-500) + var(--dimension-space-200)\n  );\n}\n\n:host(.shell-page-host--header-compact),\n:host(.shell-page-host--header-constrained) {\n  --_shell-page-content-block-start-inset: var(\n    --ds-shell-page-compact-content-block-start-inset,\n    var(--_shell-page-responsive-content-block-start-inset)\n  );\n}\n\n:host(.shell-page-host--inset-none),\n:host(.shell-page-host--block-start-inset-none) {\n  --_shell-page-content-block-start-inset: 0px;\n}\n\n:host(.shell-page-host--desktop-header-shell-bar) {\n  --ds-shell-page-sticky-header-block-size: 0px;\n}\n\n:host(.shell-page-host--desktop-header-shell-bar.shell-page-host--inset-default) {\n  --_shell-page-content-block-start-inset: var(--_shell-page-responsive-content-block-start-inset);\n}\n\n.shell-page__scroll-sentinel {\n  position: absolute;\n  inset-block-start: var(--ds-shell-page-header-travel, 0);\n  inset-inline-start: 0;\n  width: var(--dimension-stroke-width-012);\n  height: var(--dimension-stroke-width-012);\n  pointer-events: none;\n}\n\n.shell-page__sticky-header {\n  position: sticky;\n  inset-block-start: var(--ds-shell-page-sticky-offset, 0);\n  z-index: var(--dimension-z-index-raised);\n  min-width: 0;\n  background: var(--_shell-page-header-background);\n  overflow: visible;\n  overflow-anchor: none;\n}\n\n.shell-page__desktop-header ::slotted(ds-bar-title),\n.shell-page__desktop-header ::slotted(ds-bar-workflow),\n.shell-page__mobile-header ::slotted(ds-mobile-header) {\n  display: block;\n  min-width: 0;\n}\n\n.shell-page__desktop-header[hidden],\n.shell-page__mobile-header[hidden] {\n  display: none;\n}\n\n:host(.shell-page-host--mobile) .shell-page__scroll-sentinel,\n:host(.shell-page-host--mobile) .shell-page__flow-spacer {\n  display: none;\n}\n\n.shell-page__flow-spacer {\n  height: var(--ds-shell-page-flow-spacer, 0);\n  background: var(--_shell-page-content-background);\n}\n\n.shell-page__content {\n  min-width: 0;\n  box-sizing: border-box;\n  background: var(--_shell-page-content-background);\n}\n\n:host(.shell-page-host--inset-default) .shell-page__content {\n  padding: var(--dimension-space-400);\n  padding-block-start: var(--_shell-page-content-block-start-inset);\n}\n\n:host(.shell-page-host--inset-default[responsive-mode='tablet']) .shell-page__content,\n:host(.shell-page-host--inset-default[responsive-mode='mobile']) .shell-page__content {\n  padding: var(--dimension-space-200);\n  padding-block-start: var(--_shell-page-content-block-start-inset);\n}\n\n:host(.shell-page-host--inset-none) .shell-page__content {\n  padding: 0;\n}\n",
+      "content": ":host {\n  --_shell-page-content-background: var(--color-background-primary);\n  --_shell-page-header-background: var(--color-background-primary);\n  --_shell-page-responsive-content-block-start-inset: var(--dimension-space-400);\n  --_shell-page-content-block-start-inset: var(\n    --ds-shell-page-content-block-start-inset,\n    var(--_shell-page-responsive-content-block-start-inset)\n  );\n  --ds-shell-page-sticky-header-block-size: var(--dimension-size-600);\n  --ds-shell-page-content-block-start-offset: calc(\n    var(--ds-shell-page-sticky-header-block-size) + var(--_shell-page-content-block-start-inset)\n  );\n  display: block;\n  position: relative;\n  min-width: 0;\n  min-height: 100%;\n  box-sizing: border-box;\n  background: var(--_shell-page-content-background);\n}\n\n:host(.shell-page-host--surface-secondary) {\n  --_shell-page-content-background: var(--color-background-secondary);\n}\n\n:host(.shell-page-host--surface-secondary[responsive-mode='desktop']),\n:host(.shell-page-host--surface-secondary[responsive-mode='tablet']) {\n  --_shell-page-header-background: var(--color-background-secondary);\n}\n\n:host([responsive-mode='tablet']),\n:host([responsive-mode='mobile']) {\n  --_shell-page-responsive-content-block-start-inset: var(--dimension-space-200);\n}\n\n:host([responsive-mode='mobile']) {\n  --ds-shell-page-sticky-header-block-size: calc(\n    var(--dimension-size-500) + var(--dimension-space-200)\n  );\n}\n\n:host(.shell-page-host--header-compact),\n:host(.shell-page-host--header-constrained) {\n  --_shell-page-content-block-start-inset: var(\n    --ds-shell-page-compact-content-block-start-inset,\n    var(--_shell-page-responsive-content-block-start-inset)\n  );\n}\n\n:host(.shell-page-host--inset-none),\n:host(.shell-page-host--block-start-inset-none) {\n  --_shell-page-content-block-start-inset: 0px;\n}\n\n:host(.shell-page-host--desktop-header-shell-bar) {\n  --ds-shell-page-sticky-header-block-size: 0px;\n}\n\n:host(.shell-page-host--desktop-header-shell-bar.shell-page-host--inset-default) {\n  --_shell-page-content-block-start-inset: var(--_shell-page-responsive-content-block-start-inset);\n}\n\n.shell-page__scroll-sentinel {\n  position: absolute;\n  inset-block-start: var(--ds-shell-page-header-travel, 0);\n  inset-inline-start: 0;\n  width: var(--dimension-stroke-width-012);\n  height: var(--dimension-stroke-width-012);\n  pointer-events: none;\n}\n\n.shell-page__sticky-header {\n  position: sticky;\n  inset-block-start: var(--ds-shell-page-sticky-offset, 0);\n  z-index: var(--dimension-z-index-raised);\n  min-width: 0;\n  background: var(--_shell-page-header-background);\n  overflow: visible;\n  overflow-anchor: none;\n}\n\n.shell-page__desktop-header ::slotted(ds-bar-title),\n.shell-page__desktop-header ::slotted(ds-bar-workflow),\n.shell-page__mobile-header ::slotted(ds-mobile-header) {\n  display: block;\n  min-width: 0;\n}\n\n.shell-page__desktop-header[hidden],\n.shell-page__mobile-header[hidden] {\n  display: none;\n}\n\n:host(.shell-page-host--mobile) .shell-page__scroll-sentinel,\n:host(.shell-page-host--mobile) .shell-page__flow-spacer {\n  display: none;\n}\n\n.shell-page__flow-spacer {\n  height: var(--ds-shell-page-flow-spacer, 0);\n  background: var(--_shell-page-content-background);\n}\n\n.shell-page__content {\n  min-width: 0;\n  box-sizing: border-box;\n  background: var(--_shell-page-content-background);\n  isolation: isolate;\n}\n\n:host(.shell-page-host--inset-default) .shell-page__content {\n  padding: var(--dimension-space-400);\n  padding-block-start: var(--_shell-page-content-block-start-inset);\n}\n\n:host(.shell-page-host--inset-default[responsive-mode='tablet']) .shell-page__content,\n:host(.shell-page-host--inset-default[responsive-mode='mobile']) .shell-page__content {\n  padding: var(--dimension-space-200);\n  padding-block-start: var(--_shell-page-content-block-start-inset);\n}\n\n:host(.shell-page-host--inset-none) .shell-page__content {\n  padding: 0;\n}\n",
       "type": "registry:ui"
     },
     {

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

@@ -49,7 +49,8 @@
         "Items with mobileDestination inbox map to one mobile Inbox destination while retaining the actual active tool id; the canonical recipe exposes Activity directly and keeps Inbox grouping opt-in.",
         "Stable tool ids own named slots; label, order, rail placement, shortcut, and mobile destination are explicit item data.",
         "Application-owned rail accessories are forwarded unchanged to PanelTools on desktop and tablet and remain independent from activeTool and open.",
-        "Switching responsive mode must not recreate application-owned slotted product elements."
+        "Switching responsive mode must not recreate application-owned slotted product elements.",
+        "Header actions forward application-owned surfaceOpen through each presentation, independently of expanded semantics and pressed toggles."
       ],
       "responsiveBehavior": [
         "Desktop and tablet compose PanelTools-compatible rail and drawer chrome.",
@@ -75,6 +76,10 @@
         {
           "label": "PanelTools contract",
           "path": "src/wc/components/PanelTools/PanelTools.agent.json"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -453,7 +458,7 @@
     },
     {
       "path": "src/wc/components/ShellTools/ShellTools.tsx",
-      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  Watch,\n} from '@stencil/core';\nimport {\n  PANEL_TOOLS_LABELS,\n  type PanelToolsHeaderConfig,\n  type PanelToolsHeaders,\n  type PanelToolsItem,\n  type PanelToolsRailAccessory,\n  type PanelToolsRailAccessoryActionDetail,\n  type PanelToolsToolId,\n} from '../PanelTools/panel-tools-types';\nimport {\n  orderPanelToolsItems,\n  reconcilePanelToolsAvailability,\n  resolvePanelToolActivation,\n} from '../PanelTools/panel-tools-utils';\nimport {\n  itemUsesShellInbox,\n  isShellInboxTool,\n  resolveAvailableInboxTool,\n  type ShellInboxToolId,\n  type ShellResponsiveMode,\n} from '../../shell/shell-responsive';\n\n@Component({\n  tag: 'ds-shell-tools',\n  styleUrl: 'ShellTools.css',\n  shadow: true,\n})\nexport class ShellTools {\n  @Element() el!: HTMLElement;\n\n  /** Resolved by ShellApp; mobile uses a full-stage tool presentation. */\n  @Prop({ attribute: 'responsive-mode', reflect: true })\n  responsiveMode: ShellResponsiveMode = 'desktop';\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n  @Prop({ mutable: true, attribute: 'active-tool', reflect: true })\n  activeTool: PanelToolsToolId | '' = '';\n  @Prop({ mutable: true, reflect: true }) presentation: 'drawer' | 'fullscreen' = 'drawer';\n  @Prop({ attribute: 'fullscreen-header-mode', reflect: true })\n  fullscreenHeaderMode: 'shared' | 'split' = 'shared';\n  @Prop() items: PanelToolsItem[] = [];\n  /** Desktop/tablet rail accessories. Intentionally omitted from the mobile tool stage. */\n  @Prop() accessories: PanelToolsRailAccessory[] = [];\n  @Prop() headers: PanelToolsHeaders = {};\n  @Prop({ attribute: 'storage-key' }) storageKey: string = '';\n  @Prop() toolsLabel: string = 'Tools';\n  @Prop() toolShortcutsLabel: string = 'Tool shortcuts';\n  @Prop() inboxLabel: string = 'Inbox';\n  @Prop() inboxNavigationLabel: string = 'Inbox sections';\n\n  @Watch('presentation')\n  presentationChanged(next: 'drawer' | 'fullscreen', previous: 'drawer' | 'fullscreen') {\n    if (next === previous) return;\n\n    /*\n     * Consumers update ShellTools and their slotted master/detail layout in the\n     * same render. Forward the request immediately so PanelTools can conceal\n     * its surface until its matching render class commits on the next frame.\n     */\n    if (this.panelToolsEl && this.panelToolsEl.getAttribute('presentation') !== next) {\n      this.panelToolsEl.setAttribute('presentation', next);\n    }\n  }\n\n  @Event({ bubbles: true, composed: true }) dsToolChange!: EventEmitter<{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }>;\n  @Event({ bubbles: true, composed: true }) dsPresentationChange!: EventEmitter<{\n    presentation: 'drawer' | 'fullscreen';\n  }>;\n  @Event({ bubbles: true, composed: true }) dsHeaderBack!: EventEmitter<{\n    tool: PanelToolsToolId;\n  }>;\n  @Event({ bubbles: true, composed: true }) dsHeaderAction!: EventEmitter<{\n    tool: PanelToolsToolId;\n    id: string;\n  }>;\n  @Event({ bubbles: true, composed: true })\n  dsRailAccessoryAction!: EventEmitter<PanelToolsRailAccessoryActionDetail>;\n\n  private panelToolsEl: HTMLDsPanelToolsElement | null = null;\n\n  private get resolvedItems(): PanelToolsItem[] {\n    return this.items ?? [];\n  }\n\n  private get availableInboxTools(): ShellInboxToolId[] {\n    return this.resolvedItems\n      .filter(item => !item.isInactive && itemUsesShellInbox(item))\n      .map(item => item.id as ShellInboxToolId);\n  }\n\n  private get mobileViewOrder(): PanelToolsToolId[] {\n    return orderPanelToolsItems(this.resolvedItems).map(item => item.id);\n  }\n\n  private toolLabel(id: PanelToolsToolId): string {\n    const item = this.resolvedItems.find(candidate => candidate.id === id);\n    return (\n      item?.label ??\n      item?.ariaLabel ??\n      PANEL_TOOLS_LABELS[id as keyof typeof PANEL_TOOLS_LABELS] ??\n      id\n    );\n  }\n\n  private get mobileActiveTool(): PanelToolsToolId | '' {\n    const item = this.resolvedItems.find(candidate => candidate.id === this.activeTool);\n    const inbox = item ? itemUsesShellInbox(item) : isShellInboxTool(this.activeTool);\n    if (!inbox) return this.activeTool;\n    return resolveAvailableInboxTool(this.activeTool, this.availableInboxTools);\n  }\n\n  componentWillLoad() {\n    this.reconcileAvailability();\n  }\n\n  @Watch('items')\n  handleItemsChange() {\n    this.reconcileAvailability();\n  }\n\n  private reconcileAvailability() {\n    const next = reconcilePanelToolsAvailability(this.resolvedItems, this.open, this.activeTool);\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n  }\n\n  private resolvedHeaders(): PanelToolsHeaders {\n    return this.headers ?? {};\n  }\n\n  private activeHeader(tool: PanelToolsToolId): PanelToolsHeaderConfig {\n    return this.resolvedHeaders()[tool] ?? {};\n  }\n\n  private activateMobileTool(id: PanelToolsToolId) {\n    const item = this.resolvedItems.find(entry => entry.id === id);\n    if (!item || item.isInactive) return;\n    const next = resolvePanelToolActivation(this.open, this.activeTool, id);\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n    this.dsToolChange.emit({ id, selected: next.selected });\n  }\n\n  private selectInboxTool = (event: CustomEvent<string>) => {\n    const id = event.detail;\n    if (!this.availableInboxTools.includes(id) || id === this.mobileActiveTool) return;\n    this.open = true;\n    this.activeTool = id;\n    this.dsToolChange.emit({ id, selected: true });\n  };\n\n  private handlePanelToolChange = (\n    event: CustomEvent<{ id: PanelToolsToolId; selected: boolean }>\n  ) => {\n    this.activeTool = event.detail.id;\n    this.open = event.detail.selected;\n  };\n\n  private handlePanelPresentationChange = (\n    event: CustomEvent<{ presentation: 'drawer' | 'fullscreen' }>\n  ) => {\n    this.presentation = event.detail.presentation;\n  };\n\n  private handlePanelRailAccessoryAction = (\n    event: CustomEvent<PanelToolsRailAccessoryActionDetail>\n  ) => {\n    event.stopPropagation();\n    this.dsRailAccessoryAction.emit(event.detail);\n  };\n\n  private handleMobileHeaderAction = (\n    tool: PanelToolsToolId,\n    id: string,\n    event: CustomEvent<MouseEvent>\n  ) => {\n    event.stopPropagation();\n    this.dsHeaderAction.emit({ tool, id });\n  };\n\n  /** Match PanelTools' imperative activation contract in every responsive mode. */\n  @Method()\n  async activateTool(id: PanelToolsToolId) {\n    if (this.responsiveMode !== 'mobile') {\n      await this.panelToolsEl?.activateTool(id);\n      return;\n    }\n    this.activateMobileTool(id);\n  }\n\n  /** Close the active global tool surface. */\n  @Method()\n  async closeDrawer() {\n    if (this.responsiveMode !== 'mobile') {\n      await this.panelToolsEl?.closeDrawer();\n      return;\n    }\n    if (!this.open) return;\n    const id = this.activeTool;\n    this.open = false;\n    if (id) this.dsToolChange.emit({ id, selected: false });\n  }\n\n  /** Focus an application-owned action in the visible shared tool header. */\n  @Method()\n  async focusHeaderAction(id: string) {\n    if (this.responsiveMode !== 'mobile') {\n      await this.panelToolsEl?.focusHeaderAction(id);\n      return;\n    }\n    const action = (this.el.shadowRoot ?? this.el).querySelector(\n      `[data-header-action-id=\"${CSS.escape(id)}\"]`\n    ) as (HTMLElement & { setFocus?: () => Promise<void> }) | null;\n    await action?.setFocus?.();\n  }\n\n  private renderForwardedSlots() {\n    return this.mobileViewOrder.flatMap(id => [\n      <div key={`tool:${id}`} class=\"shell-tools__slot-proxy\" slot={id}>\n        <slot name={id} />\n      </div>,\n      <div key={`tool-view:${id}`} class=\"shell-tools__slot-proxy\" slot={`${id}-view`}>\n        <slot name={`${id}-view`} />\n      </div>,\n    ]);\n  }\n\n  private renderDesktop() {\n    return (\n      <div class=\"shell-tools__desktop\">\n        <ds-panel-tools\n          open={this.open}\n          activeTool={this.activeTool}\n          presentation={this.presentation}\n          fullscreenHeaderMode={this.fullscreenHeaderMode}\n          items={this.resolvedItems}\n          accessories={this.accessories ?? []}\n          headers={this.resolvedHeaders()}\n          storageKey={this.storageKey}\n          toolsLabel={this.toolsLabel}\n          toolShortcutsLabel={this.toolShortcutsLabel}\n          ref={element => {\n            this.panelToolsEl = element as HTMLDsPanelToolsElement | null;\n          }}\n          onDsToolChange={this.handlePanelToolChange}\n          onDsPresentationChange={this.handlePanelPresentationChange}\n          onDsRailAccessoryAction={this.handlePanelRailAccessoryAction}\n        >\n          {this.renderForwardedSlots()}\n        </ds-panel-tools>\n      </div>\n    );\n  }\n\n  private renderMobileHeader(tool: PanelToolsToolId) {\n    const header = this.activeHeader(tool);\n    const configuredTitle = header.title?.trim();\n    const title = configuredTitle || this.toolLabel(tool);\n    const actions = (header.actions ?? []).filter(action => action.id !== 'fullscreen');\n    const item = this.resolvedItems.find(candidate => candidate.id === tool);\n    const inboxRoot = Boolean(item && itemUsesShellInbox(item) && !header.showBack);\n    const sections = inboxRoot\n      ? this.availableInboxTools.map(id => {\n          const item = this.resolvedItems.find(candidate => candidate.id === id);\n          return {\n            id,\n            label: this.toolLabel(id),\n            variant: 'label' as const,\n            dot: item?.dot,\n          };\n        })\n      : [];\n\n    return (\n      <ds-mobile-header\n        class=\"shell-tools__mobile-header\"\n        heading={title}\n        headingLevel=\"h2\"\n        sections={sections}\n        value={tool}\n        sectionsAriaLabel={this.inboxNavigationLabel}\n        sectionsPresentation={inboxRoot ? 'segmented' : 'switcher'}\n        sectionsSize=\"lg\"\n        onDsSectionChange={this.selectInboxTool}\n      >\n        {header.showBack ? (\n          <ds-tooltip slot=\"leading\" label={header.backAriaLabel || 'Back'} side=\"bottom\" size=\"sm\">\n            <ds-button-unfilled\n              variant=\"icon\"\n              icon={header.backIcon || 'ChevronLeft'}\n              size=\"md\"\n              aria-label={header.backAriaLabel || 'Back'}\n              activeFill={false}\n              hasBorder={false}\n              onDsClick={() => this.dsHeaderBack.emit({ tool })}\n            />\n          </ds-tooltip>\n        ) : null}\n        {actions.map(action => (\n          <ds-tooltip\n            slot=\"trailing\"\n            key={action.id}\n            label={action.ariaLabel}\n            side=\"bottom\"\n            size=\"sm\"\n          >\n            <ds-button-unfilled\n              id={action.triggerId || undefined}\n              data-header-action-id={action.id}\n              variant=\"icon\"\n              icon={action.icon}\n              size=\"md\"\n              aria-label={action.ariaLabel}\n              haspopup={action.haspopup}\n              controls={action.controls}\n              expanded={action.expanded}\n              pressed={action.pressed}\n              isInactive={action.isInactive}\n              activeFill={false}\n              hasBorder={false}\n              onDsClick={(event: CustomEvent<MouseEvent>) =>\n                this.handleMobileHeaderAction(tool, action.id, event)\n              }\n            />\n          </ds-tooltip>\n        ))}\n      </ds-mobile-header>\n    );\n  }\n\n  private renderMobile() {\n    const tool = this.mobileActiveTool;\n    return (\n      <div\n        class=\"shell-tools__mobile\"\n        aria-hidden={this.open && tool ? undefined : 'true'}\n        inert={this.open && tool ? undefined : true}\n      >\n        {tool ? this.renderMobileHeader(tool) : null}\n        <div class=\"shell-tools__mobile-body\">\n          {this.mobileViewOrder.map(id => {\n            const active = this.open && id === tool;\n            return (\n              <div\n                key={`mobile-tool-view:${id}`}\n                class={{\n                  'shell-tools__view': true,\n                  'shell-tools__view--active': active,\n                }}\n                hidden={!active}\n                aria-hidden={active ? undefined : 'true'}\n                inert={active ? undefined : true}\n              >\n                <slot name={`${id}-view`}>\n                  <slot name={id} />\n                </slot>\n              </div>\n            );\n          })}\n        </div>\n      </div>\n    );\n  }\n\n  render() {\n    const mobile = this.responsiveMode === 'mobile';\n    return (\n      <Host\n        role={\n          mobile ? (this.presentation === 'fullscreen' ? 'dialog' : 'complementary') : undefined\n        }\n        aria-modal={mobile && this.presentation === 'fullscreen' ? 'true' : undefined}\n        aria-label={mobile ? this.toolsLabel : undefined}\n      >\n        {mobile ? this.renderMobile() : this.renderDesktop()}\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  Watch,\n} from '@stencil/core';\nimport {\n  PANEL_TOOLS_LABELS,\n  type PanelToolsHeaderConfig,\n  type PanelToolsHeaders,\n  type PanelToolsItem,\n  type PanelToolsRailAccessory,\n  type PanelToolsRailAccessoryActionDetail,\n  type PanelToolsToolId,\n} from '../PanelTools/panel-tools-types';\nimport {\n  orderPanelToolsItems,\n  reconcilePanelToolsAvailability,\n  resolvePanelToolActivation,\n} from '../PanelTools/panel-tools-utils';\nimport {\n  itemUsesShellInbox,\n  isShellInboxTool,\n  resolveAvailableInboxTool,\n  type ShellInboxToolId,\n  type ShellResponsiveMode,\n} from '../../shell/shell-responsive';\n\n@Component({\n  tag: 'ds-shell-tools',\n  styleUrl: 'ShellTools.css',\n  shadow: true,\n})\nexport class ShellTools {\n  @Element() el!: HTMLElement;\n\n  /** Resolved by ShellApp; mobile uses a full-stage tool presentation. */\n  @Prop({ attribute: 'responsive-mode', reflect: true })\n  responsiveMode: ShellResponsiveMode = 'desktop';\n  @Prop({ mutable: true, reflect: true }) open: boolean = false;\n  @Prop({ mutable: true, attribute: 'active-tool', reflect: true })\n  activeTool: PanelToolsToolId | '' = '';\n  @Prop({ mutable: true, reflect: true }) presentation: 'drawer' | 'fullscreen' = 'drawer';\n  @Prop({ attribute: 'fullscreen-header-mode', reflect: true })\n  fullscreenHeaderMode: 'shared' | 'split' = 'shared';\n  @Prop() items: PanelToolsItem[] = [];\n  /** Desktop/tablet rail accessories. Intentionally omitted from the mobile tool stage. */\n  @Prop() accessories: PanelToolsRailAccessory[] = [];\n  @Prop() headers: PanelToolsHeaders = {};\n  @Prop({ attribute: 'storage-key' }) storageKey: string = '';\n  @Prop() toolsLabel: string = 'Tools';\n  @Prop() toolShortcutsLabel: string = 'Tool shortcuts';\n  @Prop() inboxLabel: string = 'Inbox';\n  @Prop() inboxNavigationLabel: string = 'Inbox sections';\n\n  @Watch('presentation')\n  presentationChanged(next: 'drawer' | 'fullscreen', previous: 'drawer' | 'fullscreen') {\n    if (next === previous) return;\n\n    /*\n     * Consumers update ShellTools and their slotted master/detail layout in the\n     * same render. Forward the request immediately so PanelTools can conceal\n     * its surface until its matching render class commits on the next frame.\n     */\n    if (this.panelToolsEl && this.panelToolsEl.getAttribute('presentation') !== next) {\n      this.panelToolsEl.setAttribute('presentation', next);\n    }\n  }\n\n  @Event({ bubbles: true, composed: true }) dsToolChange!: EventEmitter<{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }>;\n  @Event({ bubbles: true, composed: true }) dsPresentationChange!: EventEmitter<{\n    presentation: 'drawer' | 'fullscreen';\n  }>;\n  @Event({ bubbles: true, composed: true }) dsHeaderBack!: EventEmitter<{\n    tool: PanelToolsToolId;\n  }>;\n  @Event({ bubbles: true, composed: true }) dsHeaderAction!: EventEmitter<{\n    tool: PanelToolsToolId;\n    id: string;\n  }>;\n  @Event({ bubbles: true, composed: true })\n  dsRailAccessoryAction!: EventEmitter<PanelToolsRailAccessoryActionDetail>;\n\n  private panelToolsEl: HTMLDsPanelToolsElement | null = null;\n\n  private get resolvedItems(): PanelToolsItem[] {\n    return this.items ?? [];\n  }\n\n  private get availableInboxTools(): ShellInboxToolId[] {\n    return this.resolvedItems\n      .filter(item => !item.isInactive && itemUsesShellInbox(item))\n      .map(item => item.id as ShellInboxToolId);\n  }\n\n  private get mobileViewOrder(): PanelToolsToolId[] {\n    return orderPanelToolsItems(this.resolvedItems).map(item => item.id);\n  }\n\n  private toolLabel(id: PanelToolsToolId): string {\n    const item = this.resolvedItems.find(candidate => candidate.id === id);\n    return (\n      item?.label ??\n      item?.ariaLabel ??\n      PANEL_TOOLS_LABELS[id as keyof typeof PANEL_TOOLS_LABELS] ??\n      id\n    );\n  }\n\n  private get mobileActiveTool(): PanelToolsToolId | '' {\n    const item = this.resolvedItems.find(candidate => candidate.id === this.activeTool);\n    const inbox = item ? itemUsesShellInbox(item) : isShellInboxTool(this.activeTool);\n    if (!inbox) return this.activeTool;\n    return resolveAvailableInboxTool(this.activeTool, this.availableInboxTools);\n  }\n\n  componentWillLoad() {\n    this.reconcileAvailability();\n  }\n\n  @Watch('items')\n  handleItemsChange() {\n    this.reconcileAvailability();\n  }\n\n  private reconcileAvailability() {\n    const next = reconcilePanelToolsAvailability(this.resolvedItems, this.open, this.activeTool);\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n  }\n\n  private resolvedHeaders(): PanelToolsHeaders {\n    return this.headers ?? {};\n  }\n\n  private activeHeader(tool: PanelToolsToolId): PanelToolsHeaderConfig {\n    return this.resolvedHeaders()[tool] ?? {};\n  }\n\n  private activateMobileTool(id: PanelToolsToolId) {\n    const item = this.resolvedItems.find(entry => entry.id === id);\n    if (!item || item.isInactive) return;\n    const next = resolvePanelToolActivation(this.open, this.activeTool, id);\n    this.open = next.open;\n    this.activeTool = next.activeTool;\n    this.dsToolChange.emit({ id, selected: next.selected });\n  }\n\n  private selectInboxTool = (event: CustomEvent<string>) => {\n    const id = event.detail;\n    if (!this.availableInboxTools.includes(id) || id === this.mobileActiveTool) return;\n    this.open = true;\n    this.activeTool = id;\n    this.dsToolChange.emit({ id, selected: true });\n  };\n\n  private handlePanelToolChange = (\n    event: CustomEvent<{ id: PanelToolsToolId; selected: boolean }>\n  ) => {\n    this.activeTool = event.detail.id;\n    this.open = event.detail.selected;\n  };\n\n  private handlePanelPresentationChange = (\n    event: CustomEvent<{ presentation: 'drawer' | 'fullscreen' }>\n  ) => {\n    this.presentation = event.detail.presentation;\n  };\n\n  private handlePanelRailAccessoryAction = (\n    event: CustomEvent<PanelToolsRailAccessoryActionDetail>\n  ) => {\n    event.stopPropagation();\n    this.dsRailAccessoryAction.emit(event.detail);\n  };\n\n  private handleMobileHeaderAction = (\n    tool: PanelToolsToolId,\n    id: string,\n    event: CustomEvent<MouseEvent>\n  ) => {\n    event.stopPropagation();\n    this.dsHeaderAction.emit({ tool, id });\n  };\n\n  /** Match PanelTools' imperative activation contract in every responsive mode. */\n  @Method()\n  async activateTool(id: PanelToolsToolId) {\n    if (this.responsiveMode !== 'mobile') {\n      await this.panelToolsEl?.activateTool(id);\n      return;\n    }\n    this.activateMobileTool(id);\n  }\n\n  /** Close the active global tool surface. */\n  @Method()\n  async closeDrawer() {\n    if (this.responsiveMode !== 'mobile') {\n      await this.panelToolsEl?.closeDrawer();\n      return;\n    }\n    if (!this.open) return;\n    const id = this.activeTool;\n    this.open = false;\n    if (id) this.dsToolChange.emit({ id, selected: false });\n  }\n\n  /** Focus an application-owned action in the visible shared tool header. */\n  @Method()\n  async focusHeaderAction(id: string) {\n    if (this.responsiveMode !== 'mobile') {\n      await this.panelToolsEl?.focusHeaderAction(id);\n      return;\n    }\n    const action = (this.el.shadowRoot ?? this.el).querySelector(\n      `[data-header-action-id=\"${CSS.escape(id)}\"]`\n    ) as (HTMLElement & { setFocus?: () => Promise<void> }) | null;\n    await action?.setFocus?.();\n  }\n\n  private renderForwardedSlots() {\n    return this.mobileViewOrder.flatMap(id => [\n      <div key={`tool:${id}`} class=\"shell-tools__slot-proxy\" slot={id}>\n        <slot name={id} />\n      </div>,\n      <div key={`tool-view:${id}`} class=\"shell-tools__slot-proxy\" slot={`${id}-view`}>\n        <slot name={`${id}-view`} />\n      </div>,\n    ]);\n  }\n\n  private renderDesktop() {\n    return (\n      <div class=\"shell-tools__desktop\">\n        <ds-panel-tools\n          open={this.open}\n          activeTool={this.activeTool}\n          presentation={this.presentation}\n          fullscreenHeaderMode={this.fullscreenHeaderMode}\n          items={this.resolvedItems}\n          accessories={this.accessories ?? []}\n          headers={this.resolvedHeaders()}\n          storageKey={this.storageKey}\n          toolsLabel={this.toolsLabel}\n          toolShortcutsLabel={this.toolShortcutsLabel}\n          ref={element => {\n            this.panelToolsEl = element as HTMLDsPanelToolsElement | null;\n          }}\n          onDsToolChange={this.handlePanelToolChange}\n          onDsPresentationChange={this.handlePanelPresentationChange}\n          onDsRailAccessoryAction={this.handlePanelRailAccessoryAction}\n        >\n          {this.renderForwardedSlots()}\n        </ds-panel-tools>\n      </div>\n    );\n  }\n\n  private renderMobileHeader(tool: PanelToolsToolId) {\n    const header = this.activeHeader(tool);\n    const configuredTitle = header.title?.trim();\n    const title = configuredTitle || this.toolLabel(tool);\n    const actions = (header.actions ?? []).filter(action => action.id !== 'fullscreen');\n    const item = this.resolvedItems.find(candidate => candidate.id === tool);\n    const inboxRoot = Boolean(item && itemUsesShellInbox(item) && !header.showBack);\n    const sections = inboxRoot\n      ? this.availableInboxTools.map(id => {\n          const item = this.resolvedItems.find(candidate => candidate.id === id);\n          return {\n            id,\n            label: this.toolLabel(id),\n            variant: 'label' as const,\n            dot: item?.dot,\n          };\n        })\n      : [];\n\n    return (\n      <ds-mobile-header\n        class=\"shell-tools__mobile-header\"\n        heading={title}\n        headingLevel=\"h2\"\n        sections={sections}\n        value={tool}\n        sectionsAriaLabel={this.inboxNavigationLabel}\n        sectionsPresentation={inboxRoot ? 'segmented' : 'switcher'}\n        sectionsSize=\"lg\"\n        onDsSectionChange={this.selectInboxTool}\n      >\n        {header.showBack ? (\n          <ds-tooltip slot=\"leading\" label={header.backAriaLabel || 'Back'} side=\"bottom\" size=\"sm\">\n            <ds-button-unfilled\n              variant=\"icon\"\n              icon={header.backIcon || 'ChevronLeft'}\n              size=\"md\"\n              aria-label={header.backAriaLabel || 'Back'}\n              activeFill={false}\n              hasBorder={false}\n              onDsClick={() => this.dsHeaderBack.emit({ tool })}\n            />\n          </ds-tooltip>\n        ) : null}\n        {actions.map(action => (\n          <ds-tooltip\n            slot=\"trailing\"\n            key={action.id}\n            label={action.ariaLabel}\n            side=\"bottom\"\n            size=\"sm\"\n          >\n            <ds-button-unfilled\n              id={action.triggerId || undefined}\n              data-header-action-id={action.id}\n              variant=\"icon\"\n              icon={action.icon}\n              size=\"md\"\n              aria-label={action.ariaLabel}\n              haspopup={action.haspopup}\n              controls={action.controls}\n              expanded={action.expanded}\n              surfaceOpen={action.surfaceOpen}\n              pressed={action.pressed}\n              isInactive={action.isInactive}\n              activeFill={false}\n              hasBorder={false}\n              onDsClick={(event: CustomEvent<MouseEvent>) =>\n                this.handleMobileHeaderAction(tool, action.id, event)\n              }\n            />\n          </ds-tooltip>\n        ))}\n      </ds-mobile-header>\n    );\n  }\n\n  private renderMobile() {\n    const tool = this.mobileActiveTool;\n    return (\n      <div\n        class=\"shell-tools__mobile\"\n        aria-hidden={this.open && tool ? undefined : 'true'}\n        inert={this.open && tool ? undefined : true}\n      >\n        {tool ? this.renderMobileHeader(tool) : null}\n        <div class=\"shell-tools__mobile-body\">\n          {this.mobileViewOrder.map(id => {\n            const active = this.open && id === tool;\n            return (\n              <div\n                key={`mobile-tool-view:${id}`}\n                class={{\n                  'shell-tools__view': true,\n                  'shell-tools__view--active': active,\n                }}\n                hidden={!active}\n                aria-hidden={active ? undefined : 'true'}\n                inert={active ? undefined : true}\n              >\n                <slot name={`${id}-view`}>\n                  <slot name={id} />\n                </slot>\n              </div>\n            );\n          })}\n        </div>\n      </div>\n    );\n  }\n\n  render() {\n    const mobile = this.responsiveMode === 'mobile';\n    return (\n      <Host\n        role={\n          mobile ? (this.presentation === 'fullscreen' ? 'dialog' : 'complementary') : undefined\n        }\n        aria-modal={mobile && this.presentation === 'fullscreen' ? 'true' : undefined}\n        aria-label={mobile ? this.toolsLabel : undefined}\n      >\n        {mobile ? this.renderMobile() : this.renderDesktop()}\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/table-group.json

@@ -46,7 +46,8 @@
       "states": [
         "options and grouping are controlled. A data option may supply product-owned orderOptions; otherwise Order defaults to Ascending and Descending. dsGroupChange reports a complete TableGroupingState and dsClear requests null grouping without mutating either input.",
         "Selecting a new data point starts at its first custom order option, or ascending when it has no custom order options. Re-selecting the active data point preserves its complete order state.",
-        "Selecting a data point or direction applies immediately and leaves the dialog open so the other pane can be changed."
+        "Selecting a data point or direction applies immediately and leaves the dialog open so the other pane can be changed.",
+        "The grouping picker automatically holds the shared surface-open wash through exit. Opening this picker is separate from expanding an inline table group."
       ],
       "responsiveBehavior": [
         "Use in the trailing region of ds-table-toolbar.",
@@ -72,6 +73,10 @@
         {
           "label": "Toolbar composition owner",
           "path": "src/wc/components/TableToolbar/TableToolbar.agent.json"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -294,7 +299,7 @@
     },
     {
       "path": "src/wc/components/TableGroup/TableGroup.tsx",
-      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Listen,\n  Prop,\n  State,\n  Watch,\n} from '@stencil/core';\nimport {\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n} from '../../utils';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\nimport { AnchoredOverlayInteractionController } from '../../utils/anchored-overlay-interaction-controller';\nimport { resolveAnchoredOverlayBoundaryRect } from '../../utils/anchored-overlay-boundary';\nimport { ChoiceListSection, ChoiceOptionRow } from '../../utils/choice-list-parts';\nimport type { TableGroupingState, TableSortDirection } from '../Table/table-types';\n\nexport interface TableGroupOrderOption {\n  label: string;\n  direction: TableSortDirection;\n  /** Optional application-owned data point used to order the group sections. */\n  orderBy?: string;\n}\n\nexport interface TableGroupOption {\n  label: string;\n  value: string;\n  description?: string;\n  isInactive?: boolean;\n  /** Product-owned order choices for this grouping data point. */\n  orderOptions?: TableGroupOrderOption[];\n}\n\nconst DEFAULT_ORDER_OPTIONS: TableGroupOrderOption[] = [\n  { label: 'Ascending', direction: 'asc' },\n  { label: 'Descending', direction: 'desc' },\n];\n\nlet tableGroupSeq = 0;\n\n@Component({\n  tag: 'ds-table-group',\n  styleUrl: 'TableGroup.css',\n  scoped: true,\n})\nexport class TableGroup {\n  @Element() private el!: HTMLElement;\n\n  /** Product-owned data points that may group the table. */\n  @Prop() options: TableGroupOption[] = [];\n  /** Controlled grouping field and the order of its group sections. */\n  @Prop() grouping: TableGroupingState | null = null;\n  /** Accessible name for the trigger and non-modal dialog. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  /** Controlled popup visibility. */\n  @Prop({ mutable: true }) open = false;\n  /** Empty message kept in the order pane until a grouping data point is selected. */\n  @Prop() emptyMessage = 'Select a group to choose its order.';\n  /** Clear action label. */\n  @Prop() clearLabel = 'Clear';\n\n  /** Requests replacement of the complete controlled grouping state. */\n  @Event() dsGroupChange!: EventEmitter<TableGroupingState>;\n  /** Requests removal of the controlled grouping state. */\n  @Event() dsClear!: EventEmitter<void>;\n  /** Reports controlled popup visibility changes. */\n  @Event() dsOpenChange!: EventEmitter<boolean>;\n\n  @State() private shouldRender = false;\n  @State() private closing = false;\n  @State() private positionReady = false;\n  @State() private pos = { x: 0, y: 0 };\n  @State() private focusRingVisible = false;\n\n  private readonly componentId = `ds-table-group-${++tableGroupSeq}`;\n  private readonly triggerId = `${this.componentId}-trigger`;\n  private readonly popupId = `${this.componentId}-popup`;\n  private triggerElement: HTMLElement | null = null;\n  private pendingInitialFocusVisible = false;\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n\n  private readonly position = new AnchoredPositionController({\n    getAnchor: () => this.triggerElement,\n    getPopup: () => this.el.querySelector<HTMLElement>('.table-group-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    measure: (anchor, popup) => {\n      if (!this.open) return null;\n      const sectionInsetPx = resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n      return {\n        anchorRect: anchor.getBoundingClientRect(),\n        popupWidth: popup.offsetWidth || this.popupFallbackWidth,\n        popupHeight: popup.offsetHeight || this.popupFallbackHeight,\n        side: 'bottom',\n        align: 'end',\n        sideOffsetPx: resolveCssLengthPx(TOKEN_CSS_LENGTHS.space050, TOKEN_DEFAULTS.space050),\n        alignOffsetPx: resolveChoicePopupAlignOffset({\n          align: 'end',\n          alignOffsetPx: 0,\n          sectionInsetPx,\n        }),\n        viewportPadPx: resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050),\n        viewportWidth: window.innerWidth,\n        viewportHeight: window.innerHeight,\n        collisionRect: resolveAnchoredOverlayBoundaryRect(anchor),\n      };\n    },\n    apply: ({ x, y }) => {\n      this.pos = { x, y };\n    },\n    onReady: () => {\n      this.positionReady = true;\n    },\n    liveUpdate: 'double-frame',\n    observeResize: true,\n    topLayer: true,\n  });\n\n  private readonly interaction = new AnchoredOverlayInteractionController({\n    getAnchor: () => this.triggerElement,\n    getPopup: () => this.el.querySelector<HTMLElement>('.table-group-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    onOutsideActivation: () => this.close(),\n  });\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  disconnectedCallback() {\n    this.position.unobserve();\n    this.interaction.disconnect();\n    if (this.closeTimer) clearTimeout(this.closeTimer);\n  }\n\n  @Watch('open')\n  onOpenChange(isOpen: boolean) {\n    if (isOpen) {\n      this.teardown();\n      this.shouldRender = true;\n      this.closing = false;\n      this.positionReady = false;\n      this.focusRingVisible = this.pendingInitialFocusVisible;\n      this.interaction.connect();\n      this.position.observe();\n      this.position.schedule(() => this.focusInitialDataPoint());\n      return;\n    }\n    if (!this.shouldRender) return;\n    this.position.cancel();\n    this.closing = true;\n    this.interaction.disconnect();\n    this.position.unobserve();\n    const duration = resolveMotionTimeMs(\n      TOKEN_DEFAULTS.motionShort2,\n      TOKEN_DEFAULTS.animationDurationShort3\n    );\n    if (duration <= 0) this.finishClose();\n    else this.closeTimer = setTimeout(() => this.finishClose(), duration);\n  }\n\n  @Listen('keydown')\n  handleKeyDown(event: KeyboardEvent) {\n    if (!this.shouldRender || this.closing) return;\n    if (event.key === 'Escape') {\n      event.preventDefault();\n      this.close();\n      return;\n    }\n    if (event.key !== 'Tab' || !this.interaction.tabLeavesPopup(event)) return;\n    event.preventDefault();\n    this.close(false);\n    this.interaction.moveFocusAfterTab(event.shiftKey);\n  }\n\n  private get popupFallbackWidth(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuWidthLg, TOKEN_DEFAULTS.menuWidthLg);\n  }\n\n  private get popupFallbackHeight(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuFallbackHeight, TOKEN_DEFAULTS.menuFallbackHeight);\n  }\n\n  private teardown() {\n    this.position.unobserve();\n    this.interaction.disconnect();\n    if (this.closeTimer) {\n      clearTimeout(this.closeTimer);\n      this.closeTimer = null;\n    }\n  }\n\n  private toggle(fromKeyboard = false) {\n    if (this.open) {\n      this.close();\n      return;\n    }\n    this.pendingInitialFocusVisible = fromKeyboard;\n    this.open = true;\n    this.dsOpenChange.emit(true);\n    this.onOpenChange(true);\n  }\n\n  private close(restoreFocus = true) {\n    if (restoreFocus) this.interaction.focusAnchor();\n    this.open = false;\n    this.dsOpenChange.emit(false);\n    this.onOpenChange(false);\n  }\n\n  private finishClose() {\n    const popup = this.el.querySelector<HTMLElement>('.table-group-popup');\n    if (popup?.matches(':popover-open')) popup.hidePopover();\n    this.shouldRender = false;\n    this.closing = false;\n    this.closeTimer = null;\n  }\n\n  private focusInitialDataPoint() {\n    requestAnimationFrame(() => {\n      const selected = this.grouping\n        ? this.el.querySelector<HTMLElement>(\n            `[data-group-value=\"${CSS.escape(this.grouping.columnId)}\"] [role=\"option\"]`\n          )\n        : null;\n      const initial =\n        selected ??\n        this.el.querySelector<HTMLElement>(\n          '[data-group-value] [role=\"option\"]:not([aria-disabled=\"true\"])'\n        );\n      initial?.focus();\n      this.pendingInitialFocusVisible = false;\n    });\n  }\n\n  private selectData(option: TableGroupOption) {\n    if (option.isInactive) return;\n    if (this.grouping?.columnId === option.value) {\n      this.dsGroupChange.emit({ ...this.grouping });\n      return;\n    }\n    const initialOrder = option.orderOptions?.[0];\n    this.dsGroupChange.emit({\n      columnId: option.value,\n      direction: initialOrder?.direction ?? 'asc',\n      ...(initialOrder?.orderBy ? { orderBy: initialOrder.orderBy } : {}),\n    });\n  }\n\n  private get activeOrderOptions(): TableGroupOrderOption[] {\n    const configured = this.options.find(\n      option => option.value === this.grouping?.columnId\n    )?.orderOptions;\n    return configured?.length ? configured : DEFAULT_ORDER_OPTIONS;\n  }\n\n  private get selectedOrderIndex(): number {\n    if (!this.grouping) return -1;\n    const exact = this.activeOrderOptions.findIndex(\n      option =>\n        option.direction === this.grouping?.direction && option.orderBy === this.grouping?.orderBy\n    );\n    if (exact >= 0) return exact;\n    if (this.grouping.orderBy === undefined) {\n      return this.activeOrderOptions.findIndex(\n        option => option.direction === this.grouping?.direction\n      );\n    }\n    return -1;\n  }\n\n  private selectOrder(option: TableGroupOrderOption, index: number) {\n    if (!this.grouping || this.selectedOrderIndex === index) return;\n    const grouping: TableGroupingState = {\n      columnId: this.grouping.columnId,\n      direction: option.direction,\n    };\n    if (option.orderBy) grouping.orderBy = option.orderBy;\n    this.dsGroupChange.emit(grouping);\n  }\n\n  private moveFocus(\n    event: KeyboardEvent,\n    selector: string,\n    currentIndex: number,\n    oppositeSelector?: string\n  ) {\n    if (oppositeSelector && (event.key === 'ArrowLeft' || event.key === 'ArrowRight')) {\n      event.preventDefault();\n      this.focusRingVisible = true;\n      this.el.querySelector<HTMLElement>(oppositeSelector)?.focus();\n      return;\n    }\n    if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return;\n    event.preventDefault();\n    const items = Array.from(this.el.querySelectorAll<HTMLElement>(selector)).filter(\n      item => item.getAttribute('aria-disabled') !== 'true'\n    );\n    if (!items.length) return;\n    let next: number;\n    if (event.key === 'Home') next = 0;\n    else if (event.key === 'End') next = items.length - 1;\n    else next = (currentIndex + (event.key === 'ArrowDown' ? 1 : -1) + items.length) % items.length;\n    this.focusRingVisible = true;\n    items[next]?.focus();\n  }\n\n  private renderDataOption(option: TableGroupOption, index: number) {\n    const selected = option.value === this.grouping?.columnId;\n    return (\n      <ChoiceOptionRow\n        id={`${this.componentId}-data-${index}`}\n        option={{ ...option }}\n        selected={selected}\n        active={selected}\n        focusRingVisible={this.focusRingVisible}\n        usesSubtext={Boolean(option.description)}\n        tabIndex={selected || (!this.grouping && index === 0) ? 0 : -1}\n        onHover={() => {\n          this.focusRingVisible = false;\n        }}\n        onSelect={() => this.selectData(option)}\n        onKeyDown={(event: KeyboardEvent) => {\n          if (event.key === 'Enter' || event.key === ' ') {\n            event.preventDefault();\n            this.selectData(option);\n            return;\n          }\n          this.moveFocus(\n            event,\n            '[data-group-value] [role=\"option\"]',\n            this.options\n              .filter(candidate => !candidate.isInactive)\n              .findIndex(candidate => candidate.value === option.value),\n            this.grouping\n              ? `[data-group-order-index=\"${this.selectedOrderIndex}\"] [role=\"option\"]`\n              : undefined\n          );\n        }}\n      />\n    );\n  }\n\n  private renderOrder(option: TableGroupOrderOption, index: number) {\n    const selected = index === this.selectedOrderIndex;\n    return (\n      <ChoiceOptionRow\n        id={`${this.componentId}-order-${index}`}\n        option={{ label: option.label, value: String(index) }}\n        selected={selected}\n        active={selected}\n        focusRingVisible={this.focusRingVisible}\n        usesSubtext={false}\n        tabIndex={selected ? 0 : -1}\n        onHover={() => {\n          this.focusRingVisible = false;\n        }}\n        onSelect={() => this.selectOrder(option, index)}\n        onKeyDown={(event: KeyboardEvent) => {\n          if (event.key === 'Enter' || event.key === ' ') {\n            event.preventDefault();\n            this.selectOrder(option, index);\n            return;\n          }\n          this.moveFocus(\n            event,\n            '[data-group-order-index] [role=\"option\"]',\n            index,\n            `[data-group-value=\"${CSS.escape(this.grouping?.columnId ?? '')}\"] [role=\"option\"]`\n          );\n        }}\n      />\n    );\n  }\n\n  render() {\n    const name = this.ariaLabel?.trim() || 'Group table';\n    const popupStyle: Record<string, string> = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.pos.x)}px, ${Math.round(this.pos.y)}px)`,\n      zIndex: '9998',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n\n    return (\n      <Host hidden={this.options.length === 0 ? true : undefined}>\n        {this.options.length ? (\n          <ds-button-unfilled\n            ref={element => {\n              this.triggerElement = (element as HTMLElement) ?? null;\n            }}\n            id={this.triggerId}\n            variant=\"icon-label\"\n            size=\"md\"\n            icon=\"SectionList\"\n            label=\"Group\"\n            labelEmphasis={false}\n            pressScale={false}\n            aria-label={name}\n            hasMenu={true}\n            collapseLabel={true}\n            expanded={this.open}\n            controls={this.popupId}\n            onDsClick={(event: CustomEvent<MouseEvent>) => this.toggle(event.detail.detail === 0)}\n          />\n        ) : null}\n\n        {this.shouldRender ? (\n          <div\n            id={this.popupId}\n            popover=\"manual\"\n            class={{\n              'table-group-popup': true,\n              'ds-choice-popup': true,\n              'ds-choice-popup--closing': this.closing,\n            }}\n            style={popupStyle}\n            role=\"dialog\"\n            aria-label={name}\n          >\n            <div class=\"table-group__body\">\n              <div class=\"table-group__data-pane\">\n                <ChoiceListSection\n                  heading=\"Data\"\n                  ariaLabel=\"Group data\"\n                  className=\"table-group__list\"\n                >\n                  {this.options.map((option, index) => (\n                    <div data-group-value={option.value}>\n                      {this.renderDataOption(option, index)}\n                    </div>\n                  ))}\n                </ChoiceListSection>\n                <div\n                  class=\"table-group__footer ds-choice-footer\"\n                  aria-hidden={!this.grouping ? 'true' : undefined}\n                >\n                  <div class=\"ds-choice-footer__content ds-control--md\">\n                    {this.grouping ? (\n                      <button\n                        class=\"ds-choice-footer__clear ds-text-action ds-focus-ring\"\n                        type=\"button\"\n                        onClick={() => this.dsClear.emit()}\n                      >\n                        <ds-text as=\"span\" variant=\"text-body-medium\" color=\"inherit\">\n                          {this.clearLabel}\n                        </ds-text>\n                      </button>\n                    ) : null}\n                  </div>\n                </div>\n              </div>\n\n              <div class=\"table-group__order-pane\">\n                {this.grouping ? (\n                  <ChoiceListSection\n                    heading=\"Order\"\n                    ariaLabel=\"Group order\"\n                    className=\"table-group__list\"\n                  >\n                    {this.activeOrderOptions.map((option, index) => (\n                      <div data-group-order-index={index}>{this.renderOrder(option, index)}</div>\n                    ))}\n                  </ChoiceListSection>\n                ) : (\n                  <div class=\"table-group__empty ds-choice-empty ds-empty-region\">\n                    <ds-empty-state body={this.emptyMessage} />\n                  </div>\n                )}\n              </div>\n            </div>\n          </div>\n        ) : null}\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Listen,\n  Prop,\n  State,\n  Watch,\n} from '@stencil/core';\nimport {\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  resolveMotionTimeMs,\n  TOKEN_CSS_LENGTHS,\n  TOKEN_DEFAULTS,\n} from '../../utils';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\nimport { AnchoredOverlayInteractionController } from '../../utils/anchored-overlay-interaction-controller';\nimport { resolveAnchoredOverlayBoundaryRect } from '../../utils/anchored-overlay-boundary';\nimport { ChoiceListSection, ChoiceOptionRow } from '../../utils/choice-list-parts';\nimport type { TableGroupingState, TableSortDirection } from '../Table/table-types';\n\nexport interface TableGroupOrderOption {\n  label: string;\n  direction: TableSortDirection;\n  /** Optional application-owned data point used to order the group sections. */\n  orderBy?: string;\n}\n\nexport interface TableGroupOption {\n  label: string;\n  value: string;\n  description?: string;\n  isInactive?: boolean;\n  /** Product-owned order choices for this grouping data point. */\n  orderOptions?: TableGroupOrderOption[];\n}\n\nconst DEFAULT_ORDER_OPTIONS: TableGroupOrderOption[] = [\n  { label: 'Ascending', direction: 'asc' },\n  { label: 'Descending', direction: 'desc' },\n];\n\nlet tableGroupSeq = 0;\n\n@Component({\n  tag: 'ds-table-group',\n  styleUrl: 'TableGroup.css',\n  scoped: true,\n})\nexport class TableGroup {\n  @Element() private el!: HTMLElement;\n\n  /** Product-owned data points that may group the table. */\n  @Prop() options: TableGroupOption[] = [];\n  /** Controlled grouping field and the order of its group sections. */\n  @Prop() grouping: TableGroupingState | null = null;\n  /** Accessible name for the trigger and non-modal dialog. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  /** Controlled popup visibility. */\n  @Prop({ mutable: true }) open = false;\n  /** Empty message kept in the order pane until a grouping data point is selected. */\n  @Prop() emptyMessage = 'Select a group to choose its order.';\n  /** Clear action label. */\n  @Prop() clearLabel = 'Clear';\n\n  /** Requests replacement of the complete controlled grouping state. */\n  @Event() dsGroupChange!: EventEmitter<TableGroupingState>;\n  /** Requests removal of the controlled grouping state. */\n  @Event() dsClear!: EventEmitter<void>;\n  /** Reports controlled popup visibility changes. */\n  @Event() dsOpenChange!: EventEmitter<boolean>;\n\n  @State() private shouldRender = false;\n  @State() private closing = false;\n  @State() private positionReady = false;\n  @State() private pos = { x: 0, y: 0 };\n  @State() private focusRingVisible = false;\n\n  private readonly componentId = `ds-table-group-${++tableGroupSeq}`;\n  private readonly triggerId = `${this.componentId}-trigger`;\n  private readonly popupId = `${this.componentId}-popup`;\n  private triggerElement: HTMLElement | null = null;\n  private pendingInitialFocusVisible = false;\n  private closeTimer: ReturnType<typeof setTimeout> | null = null;\n\n  private readonly position = new AnchoredPositionController({\n    getAnchor: () => this.triggerElement,\n    getPopup: () => this.el.querySelector<HTMLElement>('.table-group-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    measure: (anchor, popup) => {\n      if (!this.open) return null;\n      const sectionInsetPx = resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n      return {\n        anchorRect: anchor.getBoundingClientRect(),\n        popupWidth: popup.offsetWidth || this.popupFallbackWidth,\n        popupHeight: popup.offsetHeight || this.popupFallbackHeight,\n        side: 'bottom',\n        align: 'end',\n        sideOffsetPx: resolveCssLengthPx(TOKEN_CSS_LENGTHS.space050, TOKEN_DEFAULTS.space050),\n        alignOffsetPx: resolveChoicePopupAlignOffset({\n          align: 'end',\n          alignOffsetPx: 0,\n          sectionInsetPx,\n        }),\n        viewportPadPx: resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050),\n        viewportWidth: window.innerWidth,\n        viewportHeight: window.innerHeight,\n        collisionRect: resolveAnchoredOverlayBoundaryRect(anchor),\n      };\n    },\n    apply: ({ x, y }) => {\n      this.pos = { x, y };\n    },\n    onReady: () => {\n      this.positionReady = true;\n    },\n    liveUpdate: 'double-frame',\n    observeResize: true,\n    topLayer: true,\n  });\n\n  private readonly interaction = new AnchoredOverlayInteractionController({\n    getAnchor: () => this.triggerElement,\n    getPopup: () => this.el.querySelector<HTMLElement>('.table-group-popup'),\n    getOwnerDocument: () => this.el.ownerDocument,\n    onOutsideActivation: () => this.close(),\n  });\n\n  componentDidLoad() {\n    if (this.open) this.onOpenChange(true);\n  }\n\n  disconnectedCallback() {\n    this.position.unobserve();\n    this.interaction.disconnect();\n    if (this.closeTimer) clearTimeout(this.closeTimer);\n  }\n\n  @Watch('open')\n  onOpenChange(isOpen: boolean) {\n    if (isOpen) {\n      this.teardown();\n      this.shouldRender = true;\n      this.closing = false;\n      this.positionReady = false;\n      this.focusRingVisible = this.pendingInitialFocusVisible;\n      this.interaction.connect();\n      this.position.observe();\n      this.position.schedule(() => this.focusInitialDataPoint());\n      return;\n    }\n    if (!this.shouldRender) return;\n    this.position.cancel();\n    this.closing = true;\n    this.interaction.disconnect();\n    this.position.unobserve();\n    const duration = resolveMotionTimeMs(\n      TOKEN_DEFAULTS.motionShort2,\n      TOKEN_DEFAULTS.animationDurationShort3\n    );\n    if (duration <= 0) this.finishClose();\n    else this.closeTimer = setTimeout(() => this.finishClose(), duration);\n  }\n\n  @Listen('keydown')\n  handleKeyDown(event: KeyboardEvent) {\n    if (!this.shouldRender || this.closing) return;\n    if (event.key === 'Escape') {\n      event.preventDefault();\n      this.close();\n      return;\n    }\n    if (event.key !== 'Tab' || !this.interaction.tabLeavesPopup(event)) return;\n    event.preventDefault();\n    this.close(false);\n    this.interaction.moveFocusAfterTab(event.shiftKey);\n  }\n\n  private get popupFallbackWidth(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuWidthLg, TOKEN_DEFAULTS.menuWidthLg);\n  }\n\n  private get popupFallbackHeight(): number {\n    return resolveCssLengthPx(TOKEN_DEFAULTS.menuFallbackHeight, TOKEN_DEFAULTS.menuFallbackHeight);\n  }\n\n  private teardown() {\n    this.position.unobserve();\n    this.interaction.disconnect();\n    if (this.closeTimer) {\n      clearTimeout(this.closeTimer);\n      this.closeTimer = null;\n    }\n  }\n\n  private toggle(fromKeyboard = false) {\n    if (this.open) {\n      this.close();\n      return;\n    }\n    this.pendingInitialFocusVisible = fromKeyboard;\n    this.open = true;\n    this.dsOpenChange.emit(true);\n    this.onOpenChange(true);\n  }\n\n  private close(restoreFocus = true) {\n    if (restoreFocus) this.interaction.focusAnchor();\n    this.open = false;\n    this.dsOpenChange.emit(false);\n    this.onOpenChange(false);\n  }\n\n  private finishClose() {\n    const popup = this.el.querySelector<HTMLElement>('.table-group-popup');\n    if (popup?.matches(':popover-open')) popup.hidePopover();\n    this.shouldRender = false;\n    this.closing = false;\n    this.closeTimer = null;\n  }\n\n  private focusInitialDataPoint() {\n    requestAnimationFrame(() => {\n      const selected = this.grouping\n        ? this.el.querySelector<HTMLElement>(\n            `[data-group-value=\"${CSS.escape(this.grouping.columnId)}\"] [role=\"option\"]`\n          )\n        : null;\n      const initial =\n        selected ??\n        this.el.querySelector<HTMLElement>(\n          '[data-group-value] [role=\"option\"]:not([aria-disabled=\"true\"])'\n        );\n      initial?.focus();\n      this.pendingInitialFocusVisible = false;\n    });\n  }\n\n  private selectData(option: TableGroupOption) {\n    if (option.isInactive) return;\n    if (this.grouping?.columnId === option.value) {\n      this.dsGroupChange.emit({ ...this.grouping });\n      return;\n    }\n    const initialOrder = option.orderOptions?.[0];\n    this.dsGroupChange.emit({\n      columnId: option.value,\n      direction: initialOrder?.direction ?? 'asc',\n      ...(initialOrder?.orderBy ? { orderBy: initialOrder.orderBy } : {}),\n    });\n  }\n\n  private get activeOrderOptions(): TableGroupOrderOption[] {\n    const configured = this.options.find(\n      option => option.value === this.grouping?.columnId\n    )?.orderOptions;\n    return configured?.length ? configured : DEFAULT_ORDER_OPTIONS;\n  }\n\n  private get selectedOrderIndex(): number {\n    if (!this.grouping) return -1;\n    const exact = this.activeOrderOptions.findIndex(\n      option =>\n        option.direction === this.grouping?.direction && option.orderBy === this.grouping?.orderBy\n    );\n    if (exact >= 0) return exact;\n    if (this.grouping.orderBy === undefined) {\n      return this.activeOrderOptions.findIndex(\n        option => option.direction === this.grouping?.direction\n      );\n    }\n    return -1;\n  }\n\n  private selectOrder(option: TableGroupOrderOption, index: number) {\n    if (!this.grouping || this.selectedOrderIndex === index) return;\n    const grouping: TableGroupingState = {\n      columnId: this.grouping.columnId,\n      direction: option.direction,\n    };\n    if (option.orderBy) grouping.orderBy = option.orderBy;\n    this.dsGroupChange.emit(grouping);\n  }\n\n  private moveFocus(\n    event: KeyboardEvent,\n    selector: string,\n    currentIndex: number,\n    oppositeSelector?: string\n  ) {\n    if (oppositeSelector && (event.key === 'ArrowLeft' || event.key === 'ArrowRight')) {\n      event.preventDefault();\n      this.focusRingVisible = true;\n      this.el.querySelector<HTMLElement>(oppositeSelector)?.focus();\n      return;\n    }\n    if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return;\n    event.preventDefault();\n    const items = Array.from(this.el.querySelectorAll<HTMLElement>(selector)).filter(\n      item => item.getAttribute('aria-disabled') !== 'true'\n    );\n    if (!items.length) return;\n    let next: number;\n    if (event.key === 'Home') next = 0;\n    else if (event.key === 'End') next = items.length - 1;\n    else next = (currentIndex + (event.key === 'ArrowDown' ? 1 : -1) + items.length) % items.length;\n    this.focusRingVisible = true;\n    items[next]?.focus();\n  }\n\n  private renderDataOption(option: TableGroupOption, index: number) {\n    const selected = option.value === this.grouping?.columnId;\n    return (\n      <ChoiceOptionRow\n        id={`${this.componentId}-data-${index}`}\n        option={{ ...option }}\n        selected={selected}\n        active={selected}\n        focusRingVisible={this.focusRingVisible}\n        usesSubtext={Boolean(option.description)}\n        tabIndex={selected || (!this.grouping && index === 0) ? 0 : -1}\n        onHover={() => {\n          this.focusRingVisible = false;\n        }}\n        onSelect={() => this.selectData(option)}\n        onKeyDown={(event: KeyboardEvent) => {\n          if (event.key === 'Enter' || event.key === ' ') {\n            event.preventDefault();\n            this.selectData(option);\n            return;\n          }\n          this.moveFocus(\n            event,\n            '[data-group-value] [role=\"option\"]',\n            this.options\n              .filter(candidate => !candidate.isInactive)\n              .findIndex(candidate => candidate.value === option.value),\n            this.grouping\n              ? `[data-group-order-index=\"${this.selectedOrderIndex}\"] [role=\"option\"]`\n              : undefined\n          );\n        }}\n      />\n    );\n  }\n\n  private renderOrder(option: TableGroupOrderOption, index: number) {\n    const selected = index === this.selectedOrderIndex;\n    return (\n      <ChoiceOptionRow\n        id={`${this.componentId}-order-${index}`}\n        option={{ label: option.label, value: String(index) }}\n        selected={selected}\n        active={selected}\n        focusRingVisible={this.focusRingVisible}\n        usesSubtext={false}\n        tabIndex={selected ? 0 : -1}\n        onHover={() => {\n          this.focusRingVisible = false;\n        }}\n        onSelect={() => this.selectOrder(option, index)}\n        onKeyDown={(event: KeyboardEvent) => {\n          if (event.key === 'Enter' || event.key === ' ') {\n            event.preventDefault();\n            this.selectOrder(option, index);\n            return;\n          }\n          this.moveFocus(\n            event,\n            '[data-group-order-index] [role=\"option\"]',\n            index,\n            `[data-group-value=\"${CSS.escape(this.grouping?.columnId ?? '')}\"] [role=\"option\"]`\n          );\n        }}\n      />\n    );\n  }\n\n  render() {\n    const name = this.ariaLabel?.trim() || 'Group table';\n    const popupStyle: Record<string, string> = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.pos.x)}px, ${Math.round(this.pos.y)}px)`,\n      zIndex: '9998',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n\n    return (\n      <Host hidden={this.options.length === 0 ? true : undefined}>\n        {this.options.length ? (\n          <ds-button-unfilled\n            ref={element => {\n              this.triggerElement = (element as HTMLElement) ?? null;\n            }}\n            id={this.triggerId}\n            variant=\"icon-label\"\n            size=\"md\"\n            icon=\"SectionList\"\n            label=\"Group\"\n            labelEmphasis={false}\n            pressScale={false}\n            aria-label={name}\n            hasMenu={true}\n            collapseLabel={true}\n            expanded={this.open}\n            surfaceOpen={this.open || this.closing}\n            controls={this.popupId}\n            onDsClick={(event: CustomEvent<MouseEvent>) => this.toggle(event.detail.detail === 0)}\n          />\n        ) : null}\n\n        {this.shouldRender ? (\n          <div\n            id={this.popupId}\n            popover=\"manual\"\n            class={{\n              'table-group-popup': true,\n              'ds-choice-popup': true,\n              'ds-choice-popup--closing': this.closing,\n            }}\n            style={popupStyle}\n            role=\"dialog\"\n            aria-label={name}\n          >\n            <div class=\"table-group__body\">\n              <div class=\"table-group__data-pane\">\n                <ChoiceListSection\n                  heading=\"Data\"\n                  ariaLabel=\"Group data\"\n                  className=\"table-group__list\"\n                >\n                  {this.options.map((option, index) => (\n                    <div data-group-value={option.value}>\n                      {this.renderDataOption(option, index)}\n                    </div>\n                  ))}\n                </ChoiceListSection>\n                <div\n                  class=\"table-group__footer ds-choice-footer\"\n                  aria-hidden={!this.grouping ? 'true' : undefined}\n                >\n                  <div class=\"ds-choice-footer__content ds-control--md\">\n                    {this.grouping ? (\n                      <button\n                        class=\"ds-choice-footer__clear ds-text-action ds-focus-ring\"\n                        type=\"button\"\n                        onClick={() => this.dsClear.emit()}\n                      >\n                        <ds-text as=\"span\" variant=\"text-body-medium\" color=\"inherit\">\n                          {this.clearLabel}\n                        </ds-text>\n                      </button>\n                    ) : null}\n                  </div>\n                </div>\n              </div>\n\n              <div class=\"table-group__order-pane\">\n                {this.grouping ? (\n                  <ChoiceListSection\n                    heading=\"Order\"\n                    ariaLabel=\"Group order\"\n                    className=\"table-group__list\"\n                  >\n                    {this.activeOrderOptions.map((option, index) => (\n                      <div data-group-order-index={index}>{this.renderOrder(option, index)}</div>\n                    ))}\n                  </ChoiceListSection>\n                ) : (\n                  <div class=\"table-group__empty ds-choice-empty ds-empty-region\">\n                    <ds-empty-state body={this.emptyMessage} />\n                  </div>\n                )}\n              </div>\n            </div>\n          </div>\n        ) : null}\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/table-saved-views.json

@@ -40,7 +40,8 @@
       "states": [
         "views, value, and dirty are controlled. Dirty state is presented only for a selected custom view; the default template never shows the trigger dot or save/discard actions even if dirty is supplied. Selection, create, save, discard, rename, and remove events communicate intent and never mutate application records.",
         "The component owns only transient interaction state: the contextual menu, naming dialog, draft name, duplicate-name validation, and focus restoration.",
-        "The default view is a non-editable template. Application-owned custom views appear in a separate section with Rename and Remove actions. New view opens the naming dialog. When an editable selected view is dirty, that view row shows Save and negative Discard supporting actions while the footer remains dedicated to New view. The application decides which table state to capture, restore, and persist."
+        "The default view is a non-editable template. Application-owned custom views appear in a separate section with Rename and Remove actions. New view opens the naming dialog. When an editable selected view is dirty, that view row shows Save and negative Discard supporting actions while the footer remains dedicated to New view. The application decides which table state to capture, restore, and persist.",
+        "The built-in picker and contextual option menu each retain their own surface-open treatment. Opening a view menu does not select that view."
       ],
       "responsiveBehavior": [
         "The control remains a single toolbar item and relies on Select, Menu, and Modal collision and viewport behavior. Its trigger hugs short view names and is capped at the compact menu-width token so long names truncate while the dirty dot stays visible. Its choice popup keeps that same token as the minimum width.",
@@ -65,6 +66,10 @@
         {
           "label": "Toolbar composition owner",
           "path": "src/wc/components/TableToolbar/TableToolbar.agent.json"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -376,7 +381,7 @@
     },
     {
       "path": "src/wc/components/TableSavedViews/TableSavedViews.tsx",
-      "content": "import { Component, Element, Event, EventEmitter, h, Host, Prop, State } from '@stencil/core';\nimport type { MenuItemData } from '../Menu/menu-types';\nimport type {\n  SelectOptionActionDetail,\n  SelectOptionSubtextActionDetail,\n  SelectValue,\n} from '../Select/Select';\nimport type {\n  TableSavedView,\n  TableSavedViewChangeDetail,\n  TableSavedViewCreateDetail,\n  TableSavedViewDiscardDetail,\n  TableSavedViewRemoveDetail,\n  TableSavedViewRenameDetail,\n  TableSavedViewSaveDetail,\n} from './table-saved-views-types';\n\ntype SavedViewDialogMode = 'create' | 'rename';\n\nlet tableSavedViewsId = 0;\n\n@Component({\n  tag: 'ds-table-saved-views',\n  styleUrl: 'TableSavedViews.css',\n  scoped: true,\n})\nexport class TableSavedViews {\n  @Element() el!: HTMLElement;\n\n  /** Application-owned custom saved views. Assign arrays through the JavaScript property. */\n  @Prop() views: TableSavedView[] = [];\n  /** ID of the controlled active view, including the default view ID. */\n  @Prop() value: string = '__default__';\n  /** Whether the current table state differs from the selected custom view. Ignored for the default view. */\n  @Prop() dirty: boolean = false;\n  /** ID used for the built-in default view. */\n  @Prop() defaultViewId: string = '__default__';\n  /** Label used for the built-in default view. */\n  @Prop() defaultViewLabel: string = 'Default';\n  /** Accessible name for the saved-views select. */\n  @Prop() label: string = 'Saved views';\n  /** Trigger label shown while the default view is selected. */\n  @Prop() triggerLabel: string = 'Views';\n  /** Footer action label that opens the create-view dialog. */\n  @Prop() createLabel: string = 'New view';\n\n  /** Emitted when a view selection is requested. */\n  @Event() dsViewChange!: EventEmitter<TableSavedViewChangeDetail>;\n  /** Emitted after a valid create-view name is submitted. */\n  @Event() dsViewCreate!: EventEmitter<TableSavedViewCreateDetail>;\n  /** Emitted after a valid renamed view name is submitted. */\n  @Event() dsViewRename!: EventEmitter<TableSavedViewRenameDetail>;\n  /** Emitted when a custom view removal is requested. */\n  @Event() dsViewRemove!: EventEmitter<TableSavedViewRemoveDetail>;\n  /** Emitted when changes to the active custom view should replace its stored payload. */\n  @Event() dsViewSave!: EventEmitter<TableSavedViewSaveDetail>;\n  /** Emitted when the active custom view's stored payload should be restored. */\n  @Event() dsViewDiscard!: EventEmitter<TableSavedViewDiscardDetail>;\n\n  @State() private actionViewId: string | null = null;\n  @State() private actionAnchorId: string | undefined;\n  @State() private actionMenuOpen = false;\n  @State() private actionMenuInitialFocusVisible = false;\n  @State() private dialogOpen = false;\n  @State() private dialogMode: SavedViewDialogMode = 'create';\n  @State() private dialogViewId: string | null = null;\n  @State() private nameDraft = '';\n  @State() private nameError = '';\n\n  private readonly componentId = `ds-table-saved-views-${++tableSavedViewsId}`;\n  private readonly selectId = `${this.componentId}-select`;\n  private readonly actionMenuId = `${this.componentId}-actions`;\n  private readonly fieldId = `${this.componentId}-name-field`;\n  private readonly inputId = `${this.componentId}-name-input`;\n  private readonly actionItems: MenuItemData[] = [\n    { label: 'Rename', value: 'rename' },\n    { label: 'Remove', value: 'remove', isDestructive: true },\n  ];\n\n  private get selectedCustomView(): TableSavedView | undefined {\n    return this.views.find(view => view.id === this.value);\n  }\n\n  private get dialogView(): TableSavedView | undefined {\n    return this.views.find(view => view.id === this.dialogViewId);\n  }\n\n  private get sections() {\n    const custom = this.views.map(view => ({\n      label: view.label,\n      value: view.id,\n      subtextActions:\n        this.dirty && view.id === this.selectedCustomView?.id\n          ? [\n              { label: 'Save', value: 'save' },\n              { label: 'Discard', value: 'discard', tone: 'negative' as const },\n            ]\n          : undefined,\n      action: {\n        label: `Options for ${view.label}`,\n        controls: this.actionMenuId,\n        expanded: this.actionViewId === view.id && this.actionMenuOpen,\n      },\n    }));\n    const templates = {\n      header: 'Templates',\n      options: [{ label: this.defaultViewLabel, value: this.defaultViewId }],\n      divider: custom.length > 0,\n    };\n    return custom.length > 0 ? [templates, { header: 'Custom', options: custom }] : [templates];\n  }\n\n  private handleViewChange(value: SelectValue) {\n    if (typeof value === 'string') this.dsViewChange.emit({ viewId: value });\n  }\n\n  private handleSubtextAction(detail: SelectOptionSubtextActionDetail) {\n    const view = this.selectedCustomView;\n    if (!view || !this.dirty || detail.value !== view.id) return;\n    if (detail.actionValue === 'save') this.dsViewSave.emit({ viewId: view.id });\n    if (detail.actionValue === 'discard') this.dsViewDiscard.emit({ viewId: view.id });\n  }\n\n  private handleOptionAction(detail: SelectOptionActionDetail) {\n    if (!this.views.some(view => view.id === detail.value)) return;\n    this.actionMenuInitialFocusVisible = detail.originalEvent.detail === 0;\n    if (this.actionViewId === detail.value && this.actionMenuOpen) {\n      this.actionMenuOpen = false;\n      return;\n    }\n    this.actionViewId = detail.value;\n    this.actionAnchorId = detail.anchorId;\n    this.actionMenuOpen = true;\n  }\n\n  private handleActionSelect(event: CustomEvent<MenuItemData>) {\n    const viewId = this.actionViewId;\n    this.actionMenuOpen = false;\n    if (!viewId) return;\n    if (event.detail.value === 'rename') this.openDialog('rename', viewId);\n    if (event.detail.value === 'remove') this.dsViewRemove.emit({ viewId });\n  }\n\n  private openDialog(mode: SavedViewDialogMode, viewId: string | null = null) {\n    const view = mode === 'rename' ? this.views.find(item => item.id === viewId) : undefined;\n    if (mode === 'rename' && !view) return;\n    this.dialogMode = mode;\n    this.dialogViewId = view?.id ?? null;\n    this.nameDraft = view?.label ?? '';\n    this.nameError = '';\n    this.dialogOpen = true;\n    requestAnimationFrame(() => {\n      requestAnimationFrame(() => {\n        const input = this.el.querySelector<HTMLElement & { setFocus?: () => Promise<void> }>(\n          `#${this.inputId}`\n        );\n        void input?.setFocus?.();\n      });\n    });\n  }\n\n  private validateName(): string {\n    const name = this.nameDraft.trim();\n    if (!name) return 'View name is required.';\n    const duplicate = this.views.some(\n      view =>\n        view.id !== this.dialogViewId &&\n        view.label.trim().toLocaleLowerCase() === name.toLocaleLowerCase()\n    );\n    if (\n      duplicate ||\n      this.defaultViewLabel.trim().toLocaleLowerCase() === name.toLocaleLowerCase()\n    ) {\n      return 'A view with this name already exists.';\n    }\n    return '';\n  }\n\n  private submitDialog() {\n    const error = this.validateName();\n    if (error) {\n      this.nameError = error;\n      return;\n    }\n    const name = this.nameDraft.trim();\n    if (this.dialogMode === 'rename' && this.dialogView) {\n      this.dsViewRename.emit({ viewId: this.dialogView.id, name });\n    } else {\n      this.dsViewCreate.emit({ name });\n    }\n    this.dialogOpen = false;\n  }\n\n  private finishDialogClose() {\n    if (this.dialogOpen) return;\n    this.dialogViewId = null;\n    this.nameDraft = '';\n    this.nameError = '';\n    const select = this.el.querySelector<HTMLElement & { setFocus?: () => Promise<void> }>(\n      `#${this.selectId}`\n    );\n    void select?.setFocus?.();\n  }\n\n  render() {\n    return (\n      <Host>\n        <ds-select\n          id={this.selectId}\n          size=\"md\"\n          width=\"fill\"\n          placeholder={this.label}\n          aria-label={this.label}\n          sections={this.sections}\n          value={this.value}\n          triggerLabel={this.selectedCustomView ? undefined : this.triggerLabel}\n          triggerLabelPlaceholder={!this.selectedCustomView}\n          dot={this.dirty && Boolean(this.selectedCustomView)}\n          footerActionLabel={this.createLabel}\n          activeFill={false}\n          allowClear={false}\n          onDsChange={(event: CustomEvent<SelectValue>) => this.handleViewChange(event.detail)}\n          onDsFooterAction={() => this.openDialog('create')}\n          onDsOptionSubtextAction={(event: CustomEvent<SelectOptionSubtextActionDetail>) =>\n            this.handleSubtextAction(event.detail)\n          }\n          onDsOptionAction={(event: CustomEvent<SelectOptionActionDetail>) =>\n            this.handleOptionAction(event.detail)\n          }\n        />\n\n        <ds-menu\n          id={this.actionMenuId}\n          anchorId={this.actionAnchorId}\n          menuLabel=\"Saved view options\"\n          side=\"bottom\"\n          align=\"end\"\n          menuWidth=\"max-content\"\n          minWidth=\"0\"\n          items={this.actionItems}\n          open={this.actionMenuOpen}\n          initialFocusVisible={this.actionMenuInitialFocusVisible}\n          onDsClose={() => (this.actionMenuOpen = false)}\n          onDsAfterClose={() => {\n            if (this.actionMenuOpen) return;\n            this.actionViewId = null;\n            this.actionAnchorId = undefined;\n          }}\n          onDsSelect={(event: CustomEvent<MenuItemData>) => this.handleActionSelect(event)}\n        />\n\n        <ds-modal\n          open={this.dialogOpen}\n          heading={this.dialogMode === 'rename' ? 'Rename view' : 'Save as new view'}\n          modalWidth=\"sm\"\n          onDsClose={() => (this.dialogOpen = false)}\n          onDsAfterClose={() => this.finishDialogClose()}\n        >\n          <ds-field\n            label=\"Name\"\n            fieldId={this.fieldId}\n            error={this.nameError.length > 0}\n            errorMessage={this.nameError}\n          >\n            <ds-input\n              id={this.inputId}\n              size=\"md\"\n              placeholder=\"Enter a unique name\"\n              value={this.nameDraft}\n              autoFocus={true}\n              onDsChange={(event: CustomEvent<string>) => {\n                this.nameDraft = event.detail;\n                if (this.nameError) this.nameError = '';\n              }}\n              onKeyDown={(event: KeyboardEvent) => {\n                if (event.key === 'Enter') this.submitDialog();\n              }}\n            />\n          </ds-field>\n\n          <div slot=\"footer\" class=\"table-saved-views__dialog-actions\">\n            <ds-button-filled\n              label={this.dialogMode === 'rename' ? 'Rename' : 'Save'}\n              size=\"md\"\n              onDsClick={() => this.submitDialog()}\n            />\n            <ds-button-unfilled\n              label=\"Cancel\"\n              size=\"md\"\n              onDsClick={() => (this.dialogOpen = false)}\n            />\n          </div>\n        </ds-modal>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, Event, EventEmitter, h, Host, Prop, State } from '@stencil/core';\nimport type { MenuItemData } from '../Menu/menu-types';\nimport type {\n  SelectOptionActionDetail,\n  SelectOptionSubtextActionDetail,\n  SelectValue,\n} from '../Select/Select';\nimport type {\n  TableSavedView,\n  TableSavedViewChangeDetail,\n  TableSavedViewCreateDetail,\n  TableSavedViewDiscardDetail,\n  TableSavedViewRemoveDetail,\n  TableSavedViewRenameDetail,\n  TableSavedViewSaveDetail,\n} from './table-saved-views-types';\n\ntype SavedViewDialogMode = 'create' | 'rename';\n\nlet tableSavedViewsId = 0;\n\n@Component({\n  tag: 'ds-table-saved-views',\n  styleUrl: 'TableSavedViews.css',\n  scoped: true,\n})\nexport class TableSavedViews {\n  @Element() el!: HTMLElement;\n\n  /** Application-owned custom saved views. Assign arrays through the JavaScript property. */\n  @Prop() views: TableSavedView[] = [];\n  /** ID of the controlled active view, including the default view ID. */\n  @Prop() value: string = '__default__';\n  /** Whether the current table state differs from the selected custom view. Ignored for the default view. */\n  @Prop() dirty: boolean = false;\n  /** ID used for the built-in default view. */\n  @Prop() defaultViewId: string = '__default__';\n  /** Label used for the built-in default view. */\n  @Prop() defaultViewLabel: string = 'Default';\n  /** Accessible name for the saved-views select. */\n  @Prop() label: string = 'Saved views';\n  /** Trigger label shown while the default view is selected. */\n  @Prop() triggerLabel: string = 'Views';\n  /** Footer action label that opens the create-view dialog. */\n  @Prop() createLabel: string = 'New view';\n\n  /** Emitted when a view selection is requested. */\n  @Event() dsViewChange!: EventEmitter<TableSavedViewChangeDetail>;\n  /** Emitted after a valid create-view name is submitted. */\n  @Event() dsViewCreate!: EventEmitter<TableSavedViewCreateDetail>;\n  /** Emitted after a valid renamed view name is submitted. */\n  @Event() dsViewRename!: EventEmitter<TableSavedViewRenameDetail>;\n  /** Emitted when a custom view removal is requested. */\n  @Event() dsViewRemove!: EventEmitter<TableSavedViewRemoveDetail>;\n  /** Emitted when changes to the active custom view should replace its stored payload. */\n  @Event() dsViewSave!: EventEmitter<TableSavedViewSaveDetail>;\n  /** Emitted when the active custom view's stored payload should be restored. */\n  @Event() dsViewDiscard!: EventEmitter<TableSavedViewDiscardDetail>;\n\n  @State() private actionViewId: string | null = null;\n  @State() private actionAnchorId: string | undefined;\n  @State() private actionMenuOpen = false;\n  @State() private actionMenuInitialFocusVisible = false;\n  @State() private dialogOpen = false;\n  @State() private dialogMode: SavedViewDialogMode = 'create';\n  @State() private dialogViewId: string | null = null;\n  @State() private nameDraft = '';\n  @State() private nameError = '';\n\n  private readonly componentId = `ds-table-saved-views-${++tableSavedViewsId}`;\n  private readonly selectId = `${this.componentId}-select`;\n  private readonly actionMenuId = `${this.componentId}-actions`;\n  private readonly fieldId = `${this.componentId}-name-field`;\n  private readonly inputId = `${this.componentId}-name-input`;\n  private readonly actionItems: MenuItemData[] = [\n    { label: 'Rename', value: 'rename' },\n    { label: 'Remove', value: 'remove', isDestructive: true },\n  ];\n\n  private get selectedCustomView(): TableSavedView | undefined {\n    return this.views.find(view => view.id === this.value);\n  }\n\n  private get dialogView(): TableSavedView | undefined {\n    return this.views.find(view => view.id === this.dialogViewId);\n  }\n\n  private get sections() {\n    const custom = this.views.map(view => ({\n      label: view.label,\n      value: view.id,\n      subtextActions:\n        this.dirty && view.id === this.selectedCustomView?.id\n          ? [\n              { label: 'Save', value: 'save' },\n              { label: 'Discard', value: 'discard', tone: 'negative' as const },\n            ]\n          : undefined,\n      action: {\n        label: `Options for ${view.label}`,\n        controls: this.actionMenuId,\n        expanded: this.actionViewId === view.id && this.actionMenuOpen,\n        surfaceOpen: this.actionViewId === view.id,\n      },\n    }));\n    const templates = {\n      header: 'Templates',\n      options: [{ label: this.defaultViewLabel, value: this.defaultViewId }],\n      divider: custom.length > 0,\n    };\n    return custom.length > 0 ? [templates, { header: 'Custom', options: custom }] : [templates];\n  }\n\n  private handleViewChange(value: SelectValue) {\n    if (typeof value === 'string') this.dsViewChange.emit({ viewId: value });\n  }\n\n  private handleSubtextAction(detail: SelectOptionSubtextActionDetail) {\n    const view = this.selectedCustomView;\n    if (!view || !this.dirty || detail.value !== view.id) return;\n    if (detail.actionValue === 'save') this.dsViewSave.emit({ viewId: view.id });\n    if (detail.actionValue === 'discard') this.dsViewDiscard.emit({ viewId: view.id });\n  }\n\n  private handleOptionAction(detail: SelectOptionActionDetail) {\n    if (!this.views.some(view => view.id === detail.value)) return;\n    this.actionMenuInitialFocusVisible = detail.originalEvent.detail === 0;\n    if (this.actionViewId === detail.value && this.actionMenuOpen) {\n      this.actionMenuOpen = false;\n      return;\n    }\n    this.actionViewId = detail.value;\n    this.actionAnchorId = detail.anchorId;\n    this.actionMenuOpen = true;\n  }\n\n  private handleActionSelect(event: CustomEvent<MenuItemData>) {\n    const viewId = this.actionViewId;\n    this.actionMenuOpen = false;\n    if (!viewId) return;\n    if (event.detail.value === 'rename') this.openDialog('rename', viewId);\n    if (event.detail.value === 'remove') this.dsViewRemove.emit({ viewId });\n  }\n\n  private openDialog(mode: SavedViewDialogMode, viewId: string | null = null) {\n    const view = mode === 'rename' ? this.views.find(item => item.id === viewId) : undefined;\n    if (mode === 'rename' && !view) return;\n    this.dialogMode = mode;\n    this.dialogViewId = view?.id ?? null;\n    this.nameDraft = view?.label ?? '';\n    this.nameError = '';\n    this.dialogOpen = true;\n    requestAnimationFrame(() => {\n      requestAnimationFrame(() => {\n        const input = this.el.querySelector<HTMLElement & { setFocus?: () => Promise<void> }>(\n          `#${this.inputId}`\n        );\n        void input?.setFocus?.();\n      });\n    });\n  }\n\n  private validateName(): string {\n    const name = this.nameDraft.trim();\n    if (!name) return 'View name is required.';\n    const duplicate = this.views.some(\n      view =>\n        view.id !== this.dialogViewId &&\n        view.label.trim().toLocaleLowerCase() === name.toLocaleLowerCase()\n    );\n    if (\n      duplicate ||\n      this.defaultViewLabel.trim().toLocaleLowerCase() === name.toLocaleLowerCase()\n    ) {\n      return 'A view with this name already exists.';\n    }\n    return '';\n  }\n\n  private submitDialog() {\n    const error = this.validateName();\n    if (error) {\n      this.nameError = error;\n      return;\n    }\n    const name = this.nameDraft.trim();\n    if (this.dialogMode === 'rename' && this.dialogView) {\n      this.dsViewRename.emit({ viewId: this.dialogView.id, name });\n    } else {\n      this.dsViewCreate.emit({ name });\n    }\n    this.dialogOpen = false;\n  }\n\n  private finishDialogClose() {\n    if (this.dialogOpen) return;\n    this.dialogViewId = null;\n    this.nameDraft = '';\n    this.nameError = '';\n    const select = this.el.querySelector<HTMLElement & { setFocus?: () => Promise<void> }>(\n      `#${this.selectId}`\n    );\n    void select?.setFocus?.();\n  }\n\n  render() {\n    return (\n      <Host>\n        <ds-select\n          id={this.selectId}\n          size=\"md\"\n          width=\"fill\"\n          placeholder={this.label}\n          aria-label={this.label}\n          sections={this.sections}\n          value={this.value}\n          triggerLabel={this.selectedCustomView ? undefined : this.triggerLabel}\n          triggerLabelPlaceholder={!this.selectedCustomView}\n          dot={this.dirty && Boolean(this.selectedCustomView)}\n          footerActionLabel={this.createLabel}\n          activeFill={false}\n          allowClear={false}\n          onDsChange={(event: CustomEvent<SelectValue>) => this.handleViewChange(event.detail)}\n          onDsFooterAction={() => this.openDialog('create')}\n          onDsOptionSubtextAction={(event: CustomEvent<SelectOptionSubtextActionDetail>) =>\n            this.handleSubtextAction(event.detail)\n          }\n          onDsOptionAction={(event: CustomEvent<SelectOptionActionDetail>) =>\n            this.handleOptionAction(event.detail)\n          }\n        />\n\n        <ds-menu\n          id={this.actionMenuId}\n          anchorId={this.actionAnchorId}\n          menuLabel=\"Saved view options\"\n          side=\"bottom\"\n          align=\"end\"\n          menuWidth=\"max-content\"\n          minWidth=\"0\"\n          items={this.actionItems}\n          open={this.actionMenuOpen}\n          initialFocusVisible={this.actionMenuInitialFocusVisible}\n          onDsClose={() => (this.actionMenuOpen = false)}\n          onDsAfterClose={() => {\n            if (this.actionMenuOpen) return;\n            this.actionViewId = null;\n            this.actionAnchorId = undefined;\n          }}\n          onDsSelect={(event: CustomEvent<MenuItemData>) => this.handleActionSelect(event)}\n        />\n\n        <ds-modal\n          open={this.dialogOpen}\n          heading={this.dialogMode === 'rename' ? 'Rename view' : 'Save as new view'}\n          modalWidth=\"sm\"\n          onDsClose={() => (this.dialogOpen = false)}\n          onDsAfterClose={() => this.finishDialogClose()}\n        >\n          <ds-field\n            label=\"Name\"\n            fieldId={this.fieldId}\n            error={this.nameError.length > 0}\n            errorMessage={this.nameError}\n          >\n            <ds-input\n              id={this.inputId}\n              size=\"md\"\n              placeholder=\"Enter a unique name\"\n              value={this.nameDraft}\n              autoFocus={true}\n              onDsChange={(event: CustomEvent<string>) => {\n                this.nameDraft = event.detail;\n                if (this.nameError) this.nameError = '';\n              }}\n              onKeyDown={(event: KeyboardEvent) => {\n                if (event.key === 'Enter') this.submitDialog();\n              }}\n            />\n          </ds-field>\n\n          <div slot=\"footer\" class=\"table-saved-views__dialog-actions\">\n            <ds-button-filled\n              label={this.dialogMode === 'rename' ? 'Rename' : 'Save'}\n              size=\"md\"\n              onDsClick={() => this.submitDialog()}\n            />\n            <ds-button-unfilled\n              label=\"Cancel\"\n              size=\"md\"\n              onDsClick={() => (this.dialogOpen = false)}\n            />\n          </div>\n        </ds-modal>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {

package/dist/mcp-data/registry/table-search.json

@@ -44,7 +44,8 @@
         "Selected scopes render as neutral md Chips using the double-inset recipe so they remain 24px high inside the 32px md search control and each can be removed directly.",
         "Backspace edits a non-empty field-picker query, then closes the open slash listbox when that query is empty. When the table query is empty and the listbox is already closed, the next Backspace removes the last selected field. Ordinary Backspace edits table query text when the listbox is closed.",
         "Duplicate, blank, and unknown field identities are ignored for presentation. Selected fields preserve the consumer's order.",
-        "Inactive search leaves the tab order, closes the field listbox, and does not emit query or field changes."
+        "Inactive search leaves the tab order, closes the field listbox, and does not emit query or field changes.",
+        "The field-picker action holds the shared surface-open wash while its listbox is visible; chosen search fields remain independent."
       ],
       "responsiveBehavior": [
         "The control fills the available inline size supplied by the table toolbar search slot. Selected Chips and the editable query share one horizontal editor lane so the md control does not grow vertically.",
@@ -71,6 +72,10 @@
         {
           "label": "Toolbar composition owner",
           "path": "src/wc/components/TableToolbar/TableToolbar.agent.json"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -326,7 +331,7 @@
     },
     {
       "path": "src/wc/components/TableSearch/TableSearch.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 {\n  choicePopupMinWidth,\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  TOKEN_DEFAULTS,\n} from '../../utils';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\nimport { AnchoredOverlayInteractionController } from '../../utils/anchored-overlay-interaction-controller';\nimport { resolveAnchoredOverlayBoundaryRect } from '../../utils/anchored-overlay-boundary';\nimport {\n  availableTableSearchFields,\n  filterTableSearchFields,\n  nextTableSearchActiveIndex,\n  selectedTableSearchFields,\n  tableSearchFields,\n} from './table-search-model';\nimport type { TableColumn } from '../Table/table-types';\nimport type { TableSearchField, TableSearchFieldsChangeDetail } from './table-search-types';\n\nlet tableSearchSequence = 0;\n\n@Component({\n  tag: 'ds-table-search',\n  styleUrl: 'TableSearch.css',\n  scoped: true,\n})\nexport class TableSearch {\n  @Element() private el!: HTMLElement;\n\n  /** Controlled free-text query. */\n  @Prop() value: string = '';\n  /** Table column catalog used to derive searchable data points and their complete labels. */\n  @Prop() columns: TableColumn[] = [];\n  /** Controlled ordered field scopes rendered as Tags. */\n  @Prop() selectedFieldIds: string[] = [];\n  @Prop() placeholder: string = 'Search';\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string = 'Search table';\n  @Prop() clearLabel: string = 'Clear search';\n  @Prop() fieldMenuLabel: string = 'Choose search fields';\n  @Prop() isInactive: boolean = false;\n\n  @Event({ bubbles: false }) dsChange!: EventEmitter<string>;\n  @Event({ bubbles: false }) dsFieldsChange!: EventEmitter<TableSearchFieldsChangeDetail>;\n  @Event({ bubbles: false }) dsClear!: EventEmitter<void>;\n\n  @State() private menuOpen = false;\n  @State() private menuQuery = '';\n  @State() private activeIndex = 0;\n  @State() private focusRingVisible = false;\n  @State() private position = { x: 0, y: 0 };\n  @State() private positionReady = false;\n  @State() private availableHeight: number | null = null;\n  @State() private announcement = '';\n\n  private readonly componentId = `ds-table-search-${++tableSearchSequence}`;\n  private readonly inputId = `${this.componentId}-input`;\n  private readonly listboxId = `${this.componentId}-listbox`;\n  private readonly descriptionId = `${this.componentId}-description`;\n  private inputEl: HTMLInputElement | null = null;\n  private controlEl: HTMLElement | null = null;\n  private popupEl: HTMLElement | null = null;\n\n  private readonly positionController = new AnchoredPositionController({\n    getAnchor: () => this.controlEl,\n    getPopup: () => this.popupEl,\n    getOwnerDocument: () => this.el.ownerDocument,\n    measure: (anchor, popup) => {\n      if (!this.menuOpen || !popup.isConnected) return null;\n      const inset = resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n      popup.style.minWidth = `max(var(--ds-choice-popup-min-inline-size, ${TOKEN_DEFAULTS.menuWidthXs}), ${choicePopupMinWidth(anchor.offsetWidth, inset)}px)`;\n      const anchorRect = anchor.getBoundingClientRect();\n      return {\n        anchorRect,\n        popupWidth: popup.offsetWidth,\n        popupHeight: popup.offsetHeight,\n        side: 'bottom',\n        align: 'start',\n        sideOffsetPx: inset,\n        alignOffsetPx: resolveChoicePopupAlignOffset({\n          align: 'start',\n          alignOffsetPx: 0,\n          sectionInsetPx: inset,\n        }),\n        viewportPadPx: inset,\n        viewportWidth: window.innerWidth,\n        viewportHeight: window.innerHeight,\n        collisionRect: resolveAnchoredOverlayBoundaryRect(anchor),\n      };\n    },\n    apply: ({ x, y, availableHeight }) => {\n      this.position = { x, y };\n      this.availableHeight = availableHeight;\n    },\n    onReady: () => {\n      this.positionReady = true;\n    },\n    topLayer: true,\n    liveUpdate: 'frame',\n    observeResize: true,\n    observeAnchorMotion: true,\n  });\n\n  private readonly interactionController = new AnchoredOverlayInteractionController({\n    getAnchor: () => this.controlEl,\n    getPopup: () => this.popupEl,\n    getOwnerDocument: () => this.el.ownerDocument,\n    onOutsideActivation: () => this.closeMenu(),\n  });\n\n  disconnectedCallback(): void {\n    this.closeMenu();\n  }\n\n  @Watch('columns')\n  @Watch('selectedFieldIds')\n  syncAvailableFields(): void {\n    const count = this.availableFields.length;\n    if (count === 0) {\n      this.closeMenu();\n      return;\n    }\n    if (this.activeIndex >= count) this.activeIndex = count - 1;\n  }\n\n  @Watch('isInactive')\n  syncInactive(isInactive: boolean): void {\n    if (isInactive) this.closeMenu();\n  }\n\n  @Method()\n  async setFocus(): Promise<void> {\n    this.inputEl?.focus();\n  }\n\n  private get selectedFields(): TableSearchField[] {\n    return selectedTableSearchFields(this.searchFields, this.selectedFieldIds);\n  }\n\n  private get availableFields(): TableSearchField[] {\n    return availableTableSearchFields(this.searchFields, this.selectedFieldIds);\n  }\n\n  private get visibleFields(): TableSearchField[] {\n    return filterTableSearchFields(this.availableFields, this.menuQuery);\n  }\n\n  private get searchFields(): TableSearchField[] {\n    return tableSearchFields(this.columns);\n  }\n\n  private get activeOptionId(): string | undefined {\n    return this.menuOpen && this.activeIndex >= 0\n      ? `${this.componentId}-option-${this.activeIndex}`\n      : undefined;\n  }\n\n  private openMenu(fromKeyboard: boolean): void {\n    if (this.isInactive || this.menuOpen || this.availableFields.length === 0) return;\n    this.menuQuery = '';\n    // The native value can be ahead of the controlled prop when slash follows input\n    // in the same frame, so clear it before the queued render can skip an equal value.\n    if (this.inputEl) this.inputEl.value = '';\n    this.activeIndex = 0;\n    this.focusRingVisible = fromKeyboard;\n    this.positionReady = false;\n    this.menuOpen = true;\n    requestAnimationFrame(() => {\n      if (!this.menuOpen) return;\n      this.interactionController.connect();\n      this.positionController.observe();\n      this.positionController.schedule();\n    });\n  }\n\n  private closeMenu(): void {\n    if (!this.menuOpen && !this.popupEl) return;\n    if (this.popupEl?.matches(':popover-open')) this.popupEl.hidePopover();\n    this.positionController.unobserve();\n    this.interactionController.disconnect();\n    this.popupEl = null;\n    this.positionReady = false;\n    this.availableHeight = null;\n    this.menuOpen = false;\n    this.menuQuery = '';\n  }\n\n  private handleInput(event: Event): void {\n    const nextValue = (event.target as HTMLInputElement).value;\n    if (this.menuOpen) {\n      this.menuQuery = nextValue;\n      this.activeIndex = filterTableSearchFields(this.availableFields, nextValue).length ? 0 : -1;\n      this.focusRingVisible = false;\n      this.positionController.schedule();\n      return;\n    }\n\n    this.dsChange.emit(nextValue);\n  }\n\n  private selectField(field: TableSearchField): void {\n    this.dsFieldsChange.emit({ selectedFieldIds: [...this.selectedFieldIds, field.id] });\n    this.announcement = `${field.label} search field added.`;\n    this.closeMenu();\n    requestAnimationFrame(() => this.inputEl?.focus({ preventScroll: true }));\n  }\n\n  private removeLastField(): void {\n    const selected = this.selectedFields;\n    const removed = selected[selected.length - 1];\n    if (!removed) return;\n    this.dsFieldsChange.emit({\n      selectedFieldIds: this.selectedFieldIds.filter(fieldId => fieldId !== removed.id),\n    });\n    this.announcement = `${removed.label} search field removed.`;\n  }\n\n  private removeField(field: TableSearchField): void {\n    this.dsFieldsChange.emit({\n      selectedFieldIds: this.selectedFieldIds.filter(fieldId => fieldId !== field.id),\n    });\n    this.announcement = `${field.label} search field removed.`;\n    requestAnimationFrame(() => this.inputEl?.focus({ preventScroll: true }));\n  }\n\n  private clearSearch(): void {\n    if (this.value) this.dsChange.emit('');\n    if (this.selectedFieldIds.length) this.dsFieldsChange.emit({ selectedFieldIds: [] });\n    this.dsClear.emit();\n    this.announcement = 'Search cleared.';\n    this.closeMenu();\n    requestAnimationFrame(() => this.inputEl?.focus({ preventScroll: true }));\n  }\n\n  private handleKeyDown(event: KeyboardEvent): void {\n    if (event.key === '/' && !this.menuOpen && !event.altKey && !event.ctrlKey && !event.metaKey) {\n      event.preventDefault();\n      this.openMenu(true);\n      return;\n    }\n\n    if (event.key === 'Backspace' && this.menuOpen && this.menuQuery.length === 0) {\n      event.preventDefault();\n      this.closeMenu();\n      return;\n    }\n\n    if (event.key === 'Backspace' && this.value.length === 0) {\n      if (this.selectedFields.length) {\n        event.preventDefault();\n        this.removeLastField();\n      }\n      return;\n    }\n\n    if (!this.menuOpen) return;\n\n    if (event.key === 'Escape') {\n      event.preventDefault();\n      this.closeMenu();\n      return;\n    }\n\n    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {\n      event.preventDefault();\n      this.focusRingVisible = true;\n      this.activeIndex = nextTableSearchActiveIndex(\n        this.activeIndex,\n        this.visibleFields.length,\n        event.key === 'ArrowDown' ? 1 : -1\n      );\n      this.el\n        .querySelector<HTMLElement>(`#${CSS.escape(this.activeOptionId ?? '')}`)\n        ?.scrollIntoView({ block: 'nearest' });\n      return;\n    }\n\n    if (event.key === 'Enter') {\n      const field = this.visibleFields[this.activeIndex];\n      if (!field) return;\n      event.preventDefault();\n      this.selectField(field);\n      return;\n    }\n\n    if (event.key === 'Tab') this.closeMenu();\n  }\n\n  render() {\n    const selected = this.selectedFields;\n    const available = this.availableFields;\n    const visible = this.visibleFields;\n    const inputValue = this.menuOpen ? this.menuQuery : this.value;\n    const hasValue = this.value.length > 0 || selected.length > 0;\n    const description = selected.length\n      ? `Search limited to ${selected.map(field => field.label).join(' or ')}.`\n      : 'Search includes every available table field. Type slash to choose fields.';\n    const popupStyle: Record<string, string> = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.position.x)}px, ${Math.round(this.position.y)}px)`,\n      zIndex: 'var(--dimension-z-index-floating)',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n    if (this.availableHeight !== null) {\n      popupStyle['max-height'] = `${Math.floor(this.availableHeight)}px`;\n    }\n\n    return (\n      <Host\n        class={{\n          'table-search-host': true,\n          'ds-control--md': true,\n          'ds-control-inactive': this.isInactive,\n        }}\n        data-filled={hasValue ? '' : undefined}\n        data-expanded={this.menuOpen ? '' : undefined}\n      >\n        <div\n          ref={element => {\n            this.controlEl = element ?? null;\n          }}\n          class=\"table-search__control ds-control-frame ds-control--md ds-interaction-fill\"\n        >\n          <span\n            class=\"table-search__icon ds-control-icon-box ds-interaction-fill__content\"\n            aria-hidden=\"true\"\n          >\n            <ds-icon name=\"MagnifyingGlass\" size=\"md\" color=\"inherit\" />\n          </span>\n          <div class=\"table-search__editor ds-interaction-fill__content\">\n            {selected.map(field => (\n              <ds-chip\n                class=\"table-search__chip\"\n                key={field.id}\n                label={field.label}\n                size=\"md\"\n                state=\"default\"\n                isInset\n                insetDepth=\"double\"\n                isInactive={this.isInactive}\n                onDsRemove={() => this.removeField(field)}\n              />\n            ))}\n            <input\n              ref={element => {\n                this.inputEl = element ?? null;\n              }}\n              id={this.inputId}\n              class=\"table-search__input ds-text--body-medium ds-text--regular\"\n              type=\"search\"\n              role=\"combobox\"\n              value={inputValue}\n              placeholder={this.placeholder}\n              disabled={this.isInactive}\n              aria-label={this.ariaLabel}\n              aria-describedby={this.descriptionId}\n              aria-haspopup=\"listbox\"\n              aria-expanded={String(this.menuOpen)}\n              aria-controls={this.menuOpen ? this.listboxId : undefined}\n              aria-activedescendant={this.activeOptionId}\n              aria-keyshortcuts=\"/\"\n              autoComplete=\"off\"\n              autoCapitalize=\"none\"\n              autoCorrect=\"off\"\n              spellcheck={false}\n              onInput={event => this.handleInput(event)}\n              onKeyDown={event => this.handleKeyDown(event)}\n            />\n          </div>\n          {this.searchFields.length > 0 && (\n            <div class=\"table-search__actions ds-interaction-fill__content\">\n              {inputValue.length > 0 && !this.isInactive && (\n                <ds-button-unfilled\n                  class=\"table-search__clear\"\n                  variant=\"icon\"\n                  size=\"sm\"\n                  icon=\"CrossCircle\"\n                  hasBorder={false}\n                  rounded\n                  ariaLabel={this.clearLabel}\n                  onDsClick={() => this.clearSearch()}\n                />\n              )}\n              {inputValue.length > 0 && !this.isInactive && (\n                <ds-divider\n                  class=\"table-search__action-divider\"\n                  orientation=\"vertical\"\n                  length=\"var(--dimension-size-200)\"\n                />\n              )}\n              <ds-button-unfilled\n                class=\"table-search__slash\"\n                variant=\"label\"\n                size=\"md\"\n                label=\"/\"\n                labelEmphasis={false}\n                isInset\n                insetDepth=\"double\"\n                hasBorder={false}\n                ariaLabel={this.fieldMenuLabel}\n                focusTabIndex={-1}\n                haspopup=\"listbox\"\n                controls={this.menuOpen ? this.listboxId : undefined}\n                expanded={this.menuOpen}\n                isInactive={this.isInactive || available.length === 0}\n                onMouseDown={(event: MouseEvent) => event.preventDefault()}\n                onDsClick={() => {\n                  this.inputEl?.focus({ preventScroll: true });\n                  this.openMenu(false);\n                }}\n              />\n            </div>\n          )}\n        </div>\n        <span id={this.descriptionId} class=\"ds-visually-hidden\">\n          {description}\n        </span>\n        <span class=\"ds-visually-hidden\" aria-live=\"polite\">\n          {this.announcement}\n        </span>\n        {this.menuOpen && (\n          <div\n            popover=\"manual\"\n            ref={element => {\n              this.popupEl = element ?? null;\n            }}\n            class=\"table-search__popup ds-choice-popup\"\n            style={popupStyle}\n          >\n            <div\n              id={this.listboxId}\n              class=\"table-search__list ds-choice-list\"\n              role=\"listbox\"\n              aria-label={this.fieldMenuLabel}\n            >\n              {visible.map((field, index) => {\n                const active = index === this.activeIndex;\n                return (\n                  /* eslint-disable-next-line local/prefer-direct-ds-text -- The option owns listbox semantics and pointer interaction while ds-text remains its typography child. */\n                  <div\n                    id={`${this.componentId}-option-${index}`}\n                    key={field.id}\n                    class={{\n                      'table-search__option': true,\n                      'ds-choice-item': true,\n                      'ds-control-frame': true,\n                      'ds-control--md': true,\n                      'ds-focus-ring-inset': true,\n                      'ds-focus-ring--visible': active && this.focusRingVisible,\n                      'ds-interaction-fill': true,\n                      'ds-interaction-fill--selected': active,\n                    }}\n                    role=\"option\"\n                    aria-selected={String(active)}\n                    onMouseDown={event => event.preventDefault()}\n                    onMouseMove={() => {\n                      this.focusRingVisible = false;\n                      this.activeIndex = index;\n                    }}\n                    onClick={() => this.selectField(field)}\n                  >\n                    <ds-text\n                      class=\"ds-choice-item__label ds-control-label-box ds-interaction-fill__content\"\n                      as=\"span\"\n                      variant=\"text-body-medium\"\n                      color={active ? 'primary' : 'secondary'}\n                    >\n                      {field.label}\n                    </ds-text>\n                  </div>\n                );\n              })}\n              {visible.length === 0 && (\n                <div class=\"table-search__empty ds-choice-empty ds-empty-region\">\n                  <ds-empty-state body=\"No matching data points\" />\n                </div>\n              )}\n            </div>\n          </div>\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 {\n  choicePopupMinWidth,\n  resolveChoicePopupAlignOffset,\n  resolveCssLengthPx,\n  TOKEN_DEFAULTS,\n} from '../../utils';\nimport { AnchoredPositionController } from '../../utils/anchored-position-controller';\nimport { AnchoredOverlayInteractionController } from '../../utils/anchored-overlay-interaction-controller';\nimport { resolveAnchoredOverlayBoundaryRect } from '../../utils/anchored-overlay-boundary';\nimport {\n  availableTableSearchFields,\n  filterTableSearchFields,\n  nextTableSearchActiveIndex,\n  selectedTableSearchFields,\n  tableSearchFields,\n} from './table-search-model';\nimport type { TableColumn } from '../Table/table-types';\nimport type { TableSearchField, TableSearchFieldsChangeDetail } from './table-search-types';\n\nlet tableSearchSequence = 0;\n\n@Component({\n  tag: 'ds-table-search',\n  styleUrl: 'TableSearch.css',\n  scoped: true,\n})\nexport class TableSearch {\n  @Element() private el!: HTMLElement;\n\n  /** Controlled free-text query. */\n  @Prop() value: string = '';\n  /** Table column catalog used to derive searchable data points and their complete labels. */\n  @Prop() columns: TableColumn[] = [];\n  /** Controlled ordered field scopes rendered as Tags. */\n  @Prop() selectedFieldIds: string[] = [];\n  @Prop() placeholder: string = 'Search';\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string = 'Search table';\n  @Prop() clearLabel: string = 'Clear search';\n  @Prop() fieldMenuLabel: string = 'Choose search fields';\n  @Prop() isInactive: boolean = false;\n\n  @Event({ bubbles: false }) dsChange!: EventEmitter<string>;\n  @Event({ bubbles: false }) dsFieldsChange!: EventEmitter<TableSearchFieldsChangeDetail>;\n  @Event({ bubbles: false }) dsClear!: EventEmitter<void>;\n\n  @State() private menuOpen = false;\n  @State() private menuQuery = '';\n  @State() private activeIndex = 0;\n  @State() private focusRingVisible = false;\n  @State() private position = { x: 0, y: 0 };\n  @State() private positionReady = false;\n  @State() private availableHeight: number | null = null;\n  @State() private announcement = '';\n\n  private readonly componentId = `ds-table-search-${++tableSearchSequence}`;\n  private readonly inputId = `${this.componentId}-input`;\n  private readonly listboxId = `${this.componentId}-listbox`;\n  private readonly descriptionId = `${this.componentId}-description`;\n  private inputEl: HTMLInputElement | null = null;\n  private controlEl: HTMLElement | null = null;\n  private popupEl: HTMLElement | null = null;\n\n  private readonly positionController = new AnchoredPositionController({\n    getAnchor: () => this.controlEl,\n    getPopup: () => this.popupEl,\n    getOwnerDocument: () => this.el.ownerDocument,\n    measure: (anchor, popup) => {\n      if (!this.menuOpen || !popup.isConnected) return null;\n      const inset = resolveCssLengthPx(TOKEN_DEFAULTS.space050, TOKEN_DEFAULTS.space050);\n      popup.style.minWidth = `max(var(--ds-choice-popup-min-inline-size, ${TOKEN_DEFAULTS.menuWidthXs}), ${choicePopupMinWidth(anchor.offsetWidth, inset)}px)`;\n      const anchorRect = anchor.getBoundingClientRect();\n      return {\n        anchorRect,\n        popupWidth: popup.offsetWidth,\n        popupHeight: popup.offsetHeight,\n        side: 'bottom',\n        align: 'start',\n        sideOffsetPx: inset,\n        alignOffsetPx: resolveChoicePopupAlignOffset({\n          align: 'start',\n          alignOffsetPx: 0,\n          sectionInsetPx: inset,\n        }),\n        viewportPadPx: inset,\n        viewportWidth: window.innerWidth,\n        viewportHeight: window.innerHeight,\n        collisionRect: resolveAnchoredOverlayBoundaryRect(anchor),\n      };\n    },\n    apply: ({ x, y, availableHeight }) => {\n      this.position = { x, y };\n      this.availableHeight = availableHeight;\n    },\n    onReady: () => {\n      this.positionReady = true;\n    },\n    topLayer: true,\n    liveUpdate: 'frame',\n    observeResize: true,\n    observeAnchorMotion: true,\n  });\n\n  private readonly interactionController = new AnchoredOverlayInteractionController({\n    getAnchor: () => this.controlEl,\n    getPopup: () => this.popupEl,\n    getOwnerDocument: () => this.el.ownerDocument,\n    onOutsideActivation: () => this.closeMenu(),\n  });\n\n  disconnectedCallback(): void {\n    this.closeMenu();\n  }\n\n  @Watch('columns')\n  @Watch('selectedFieldIds')\n  syncAvailableFields(): void {\n    const count = this.availableFields.length;\n    if (count === 0) {\n      this.closeMenu();\n      return;\n    }\n    if (this.activeIndex >= count) this.activeIndex = count - 1;\n  }\n\n  @Watch('isInactive')\n  syncInactive(isInactive: boolean): void {\n    if (isInactive) this.closeMenu();\n  }\n\n  @Method()\n  async setFocus(): Promise<void> {\n    this.inputEl?.focus();\n  }\n\n  private get selectedFields(): TableSearchField[] {\n    return selectedTableSearchFields(this.searchFields, this.selectedFieldIds);\n  }\n\n  private get availableFields(): TableSearchField[] {\n    return availableTableSearchFields(this.searchFields, this.selectedFieldIds);\n  }\n\n  private get visibleFields(): TableSearchField[] {\n    return filterTableSearchFields(this.availableFields, this.menuQuery);\n  }\n\n  private get searchFields(): TableSearchField[] {\n    return tableSearchFields(this.columns);\n  }\n\n  private get activeOptionId(): string | undefined {\n    return this.menuOpen && this.activeIndex >= 0\n      ? `${this.componentId}-option-${this.activeIndex}`\n      : undefined;\n  }\n\n  private openMenu(fromKeyboard: boolean): void {\n    if (this.isInactive || this.menuOpen || this.availableFields.length === 0) return;\n    this.menuQuery = '';\n    // The native value can be ahead of the controlled prop when slash follows input\n    // in the same frame, so clear it before the queued render can skip an equal value.\n    if (this.inputEl) this.inputEl.value = '';\n    this.activeIndex = 0;\n    this.focusRingVisible = fromKeyboard;\n    this.positionReady = false;\n    this.menuOpen = true;\n    requestAnimationFrame(() => {\n      if (!this.menuOpen) return;\n      this.interactionController.connect();\n      this.positionController.observe();\n      this.positionController.schedule();\n    });\n  }\n\n  private closeMenu(): void {\n    if (!this.menuOpen && !this.popupEl) return;\n    if (this.popupEl?.matches(':popover-open')) this.popupEl.hidePopover();\n    this.positionController.unobserve();\n    this.interactionController.disconnect();\n    this.popupEl = null;\n    this.positionReady = false;\n    this.availableHeight = null;\n    this.menuOpen = false;\n    this.menuQuery = '';\n  }\n\n  private handleInput(event: Event): void {\n    const nextValue = (event.target as HTMLInputElement).value;\n    if (this.menuOpen) {\n      this.menuQuery = nextValue;\n      this.activeIndex = filterTableSearchFields(this.availableFields, nextValue).length ? 0 : -1;\n      this.focusRingVisible = false;\n      this.positionController.schedule();\n      return;\n    }\n\n    this.dsChange.emit(nextValue);\n  }\n\n  private selectField(field: TableSearchField): void {\n    this.dsFieldsChange.emit({ selectedFieldIds: [...this.selectedFieldIds, field.id] });\n    this.announcement = `${field.label} search field added.`;\n    this.closeMenu();\n    requestAnimationFrame(() => this.inputEl?.focus({ preventScroll: true }));\n  }\n\n  private removeLastField(): void {\n    const selected = this.selectedFields;\n    const removed = selected[selected.length - 1];\n    if (!removed) return;\n    this.dsFieldsChange.emit({\n      selectedFieldIds: this.selectedFieldIds.filter(fieldId => fieldId !== removed.id),\n    });\n    this.announcement = `${removed.label} search field removed.`;\n  }\n\n  private removeField(field: TableSearchField): void {\n    this.dsFieldsChange.emit({\n      selectedFieldIds: this.selectedFieldIds.filter(fieldId => fieldId !== field.id),\n    });\n    this.announcement = `${field.label} search field removed.`;\n    requestAnimationFrame(() => this.inputEl?.focus({ preventScroll: true }));\n  }\n\n  private clearSearch(): void {\n    if (this.value) this.dsChange.emit('');\n    if (this.selectedFieldIds.length) this.dsFieldsChange.emit({ selectedFieldIds: [] });\n    this.dsClear.emit();\n    this.announcement = 'Search cleared.';\n    this.closeMenu();\n    requestAnimationFrame(() => this.inputEl?.focus({ preventScroll: true }));\n  }\n\n  private handleKeyDown(event: KeyboardEvent): void {\n    if (event.key === '/' && !this.menuOpen && !event.altKey && !event.ctrlKey && !event.metaKey) {\n      event.preventDefault();\n      this.openMenu(true);\n      return;\n    }\n\n    if (event.key === 'Backspace' && this.menuOpen && this.menuQuery.length === 0) {\n      event.preventDefault();\n      this.closeMenu();\n      return;\n    }\n\n    if (event.key === 'Backspace' && this.value.length === 0) {\n      if (this.selectedFields.length) {\n        event.preventDefault();\n        this.removeLastField();\n      }\n      return;\n    }\n\n    if (!this.menuOpen) return;\n\n    if (event.key === 'Escape') {\n      event.preventDefault();\n      this.closeMenu();\n      return;\n    }\n\n    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {\n      event.preventDefault();\n      this.focusRingVisible = true;\n      this.activeIndex = nextTableSearchActiveIndex(\n        this.activeIndex,\n        this.visibleFields.length,\n        event.key === 'ArrowDown' ? 1 : -1\n      );\n      this.el\n        .querySelector<HTMLElement>(`#${CSS.escape(this.activeOptionId ?? '')}`)\n        ?.scrollIntoView({ block: 'nearest' });\n      return;\n    }\n\n    if (event.key === 'Enter') {\n      const field = this.visibleFields[this.activeIndex];\n      if (!field) return;\n      event.preventDefault();\n      this.selectField(field);\n      return;\n    }\n\n    if (event.key === 'Tab') this.closeMenu();\n  }\n\n  render() {\n    const selected = this.selectedFields;\n    const available = this.availableFields;\n    const visible = this.visibleFields;\n    const inputValue = this.menuOpen ? this.menuQuery : this.value;\n    const hasValue = this.value.length > 0 || selected.length > 0;\n    const description = selected.length\n      ? `Search limited to ${selected.map(field => field.label).join(' or ')}.`\n      : 'Search includes every available table field. Type slash to choose fields.';\n    const popupStyle: Record<string, string> = {\n      position: 'fixed',\n      left: '0',\n      top: '0',\n      transform: `translate(${Math.round(this.position.x)}px, ${Math.round(this.position.y)}px)`,\n      zIndex: 'var(--dimension-z-index-floating)',\n      visibility: this.positionReady ? 'visible' : 'hidden',\n    };\n    if (this.availableHeight !== null) {\n      popupStyle['max-height'] = `${Math.floor(this.availableHeight)}px`;\n    }\n\n    return (\n      <Host\n        class={{\n          'table-search-host': true,\n          'ds-control--md': true,\n          'ds-control-inactive': this.isInactive,\n        }}\n        data-filled={hasValue ? '' : undefined}\n        data-expanded={this.menuOpen ? '' : undefined}\n      >\n        <div\n          ref={element => {\n            this.controlEl = element ?? null;\n          }}\n          class=\"table-search__control ds-control-frame ds-control--md ds-interaction-fill\"\n        >\n          <span\n            class=\"table-search__icon ds-control-icon-box ds-interaction-fill__content\"\n            aria-hidden=\"true\"\n          >\n            <ds-icon name=\"MagnifyingGlass\" size=\"md\" color=\"inherit\" />\n          </span>\n          <div class=\"table-search__editor ds-interaction-fill__content\">\n            {selected.map(field => (\n              <ds-chip\n                class=\"table-search__chip\"\n                key={field.id}\n                label={field.label}\n                size=\"md\"\n                state=\"default\"\n                isInset\n                insetDepth=\"double\"\n                isInactive={this.isInactive}\n                onDsRemove={() => this.removeField(field)}\n              />\n            ))}\n            <input\n              ref={element => {\n                this.inputEl = element ?? null;\n              }}\n              id={this.inputId}\n              class=\"table-search__input ds-text--body-medium ds-text--regular\"\n              type=\"search\"\n              role=\"combobox\"\n              value={inputValue}\n              placeholder={this.placeholder}\n              disabled={this.isInactive}\n              aria-label={this.ariaLabel}\n              aria-describedby={this.descriptionId}\n              aria-haspopup=\"listbox\"\n              aria-expanded={String(this.menuOpen)}\n              aria-controls={this.menuOpen ? this.listboxId : undefined}\n              aria-activedescendant={this.activeOptionId}\n              aria-keyshortcuts=\"/\"\n              autoComplete=\"off\"\n              autoCapitalize=\"none\"\n              autoCorrect=\"off\"\n              spellcheck={false}\n              onInput={event => this.handleInput(event)}\n              onKeyDown={event => this.handleKeyDown(event)}\n            />\n          </div>\n          {this.searchFields.length > 0 && (\n            <div class=\"table-search__actions ds-interaction-fill__content\">\n              {inputValue.length > 0 && !this.isInactive && (\n                <ds-button-unfilled\n                  class=\"table-search__clear\"\n                  variant=\"icon\"\n                  size=\"sm\"\n                  icon=\"CrossCircle\"\n                  hasBorder={false}\n                  rounded\n                  ariaLabel={this.clearLabel}\n                  onDsClick={() => this.clearSearch()}\n                />\n              )}\n              {inputValue.length > 0 && !this.isInactive && (\n                <ds-divider\n                  class=\"table-search__action-divider\"\n                  orientation=\"vertical\"\n                  length=\"var(--dimension-size-200)\"\n                />\n              )}\n              <ds-button-unfilled\n                class=\"table-search__slash\"\n                variant=\"label\"\n                size=\"md\"\n                label=\"/\"\n                labelEmphasis={false}\n                isInset\n                insetDepth=\"double\"\n                hasBorder={false}\n                ariaLabel={this.fieldMenuLabel}\n                focusTabIndex={-1}\n                haspopup=\"listbox\"\n                controls={this.menuOpen ? this.listboxId : undefined}\n                expanded={this.menuOpen}\n                surfaceOpen={this.menuOpen}\n                isInactive={this.isInactive || available.length === 0}\n                onMouseDown={(event: MouseEvent) => event.preventDefault()}\n                onDsClick={() => {\n                  this.inputEl?.focus({ preventScroll: true });\n                  this.openMenu(false);\n                }}\n              />\n            </div>\n          )}\n        </div>\n        <span id={this.descriptionId} class=\"ds-visually-hidden\">\n          {description}\n        </span>\n        <span class=\"ds-visually-hidden\" aria-live=\"polite\">\n          {this.announcement}\n        </span>\n        {this.menuOpen && (\n          <div\n            popover=\"manual\"\n            ref={element => {\n              this.popupEl = element ?? null;\n            }}\n            class=\"table-search__popup ds-choice-popup\"\n            style={popupStyle}\n          >\n            <div\n              id={this.listboxId}\n              class=\"table-search__list ds-choice-list\"\n              role=\"listbox\"\n              aria-label={this.fieldMenuLabel}\n            >\n              {visible.map((field, index) => {\n                const active = index === this.activeIndex;\n                return (\n                  /* eslint-disable-next-line local/prefer-direct-ds-text -- The option owns listbox semantics and pointer interaction while ds-text remains its typography child. */\n                  <div\n                    id={`${this.componentId}-option-${index}`}\n                    key={field.id}\n                    class={{\n                      'table-search__option': true,\n                      'ds-choice-item': true,\n                      'ds-control-frame': true,\n                      'ds-control--md': true,\n                      'ds-focus-ring-inset': true,\n                      'ds-focus-ring--visible': active && this.focusRingVisible,\n                      'ds-interaction-fill': true,\n                      'ds-interaction-fill--selected': active,\n                    }}\n                    role=\"option\"\n                    aria-selected={String(active)}\n                    onMouseDown={event => event.preventDefault()}\n                    onMouseMove={() => {\n                      this.focusRingVisible = false;\n                      this.activeIndex = index;\n                    }}\n                    onClick={() => this.selectField(field)}\n                  >\n                    <ds-text\n                      class=\"ds-choice-item__label ds-control-label-box ds-interaction-fill__content\"\n                      as=\"span\"\n                      variant=\"text-body-medium\"\n                      color={active ? 'primary' : 'secondary'}\n                    >\n                      {field.label}\n                    </ds-text>\n                  </div>\n                );\n              })}\n              {visible.length === 0 && (\n                <div class=\"table-search__empty ds-choice-empty ds-empty-region\">\n                  <ds-empty-state body=\"No matching data points\" />\n                </div>\n              )}\n            </div>\n          </div>\n        )}\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {

package/dist/mcp-data/registry/table-sort.json

@@ -50,7 +50,8 @@
         "columns and sort are controlled. dsSortChange reports the next TableSortState and never mutates those inputs. The same sort object is what column headers emit through the table.",
         "Selecting a different data field keeps the current direction, or starts ascending when no sort exists. Selecting a direction applies it to the current field, or to the first sortable field when no sort exists. Selecting the already-active field or direction is a no-op and does not toggle the way a header click does.",
         "The trigger stays Sort in regular-weight resting secondary chrome. Field and direction selection live in the menu and on column headers, so the trigger never uses active primary emphasis. It keeps pressed interaction paint without physically scaling inside the stable table caption row.",
-        "Compound sortable headers contribute one Data row per segment. Action columns never appear."
+        "Compound sortable headers contribute one Data row per segment. Action columns never appear.",
+        "The trigger automatically holds the shared surface-open wash through menu exit while the selected sort remains independently controlled."
       ],
       "responsiveBehavior": [
         "Place the control in the trailing region of ds-table-toolbar with Filter and Group.",
@@ -76,6 +77,10 @@
         {
           "label": "Toolbar composition owner",
           "path": "src/wc/components/TableToolbar/TableToolbar.agent.json"
+        },
+        {
+          "label": "Surface ownership and trigger state",
+          "path": "src/docs/SurfaceOwnership.mdx"
         }
       ]
     },
@@ -218,7 +223,7 @@
     },
     {
       "path": "src/wc/components/TableSort/TableSort.tsx",
-      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n} from '@stencil/core';\nimport type { MenuItemData } from '../Menu/menu-types';\nimport type { TableColumn, TableSortChangeDetail, TableSortState } from '../Table/table-types';\nimport {\n  nextTableSortStateFromMenuItem,\n  tableSortFields,\n  tableSortMenuSections,\n  tableSortStatesEqual,\n} from './table-sort-menu';\n\nlet tableSortSeq = 0;\n\n@Component({\n  tag: 'ds-table-sort',\n  styleUrl: 'TableSort.css',\n  scoped: true,\n})\nexport class TableSort {\n  @Element() private el!: HTMLElement;\n\n  /** Catalog used to derive sortable fields, including compound header segments. */\n  @Prop() columns: TableColumn[] = [];\n  /** Controlled table sort. Header sorting and this menu share the same value. */\n  @Prop() sort: TableSortState | null = null;\n  /** Accessible name for the trigger and menu. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n\n  @Event({ bubbles: false }) dsSortChange!: EventEmitter<TableSortChangeDetail>;\n\n  @State() private menuOpen = false;\n  @State() private initialFocusVisible = false;\n\n  private readonly componentId = `ds-table-sort-${++tableSortSeq}`;\n  private readonly triggerId = `${this.componentId}-trigger`;\n  private readonly menuId = `${this.componentId}-menu`;\n\n  @Method()\n  async setFocus() {\n    const trigger = this.el.querySelector<HTMLElement & { setFocus?: () => Promise<void> }>(\n      `#${CSS.escape(this.triggerId)}`\n    );\n    await trigger?.setFocus?.();\n  }\n\n  render() {\n    const fields = tableSortFields(this.columns);\n    const name = this.ariaLabel?.trim() || 'Sort table';\n\n    return (\n      <Host hidden={fields.length === 0 ? true : undefined}>\n        {fields.length === 0 ? null : (\n          <ds-button-unfilled\n            id={this.triggerId}\n            variant=\"icon-label\"\n            size=\"md\"\n            icon=\"ArrowsVertical\"\n            label=\"Sort\"\n            labelEmphasis={false}\n            pressScale={false}\n            aria-label={name}\n            hasMenu={true}\n            collapseLabel={true}\n            expanded={this.menuOpen}\n            controls={this.menuId}\n            onDsClick={(event: CustomEvent<MouseEvent>) => {\n              this.toggle(event.detail.detail === 0);\n            }}\n          />\n        )}\n        {fields.length === 0 ? null : (\n          <ds-menu\n            id={this.menuId}\n            open={this.menuOpen}\n            anchorId={this.triggerId}\n            align=\"start\"\n            side=\"bottom\"\n            menuLabel={name}\n            selectionMode=\"none\"\n            initialFocusVisible={this.initialFocusVisible}\n            sections={tableSortMenuSections(this.columns, this.sort)}\n            onDsClose={() => this.close()}\n            onDsSelect={event => this.handleSelect(event.detail)}\n          />\n        )}\n      </Host>\n    );\n  }\n\n  private toggle(fromKeyboard = false): void {\n    if (this.menuOpen) this.close();\n    else this.open(fromKeyboard);\n  }\n\n  private open(fromKeyboard = false): void {\n    if (this.menuOpen) return;\n    this.initialFocusVisible = fromKeyboard;\n    this.menuOpen = true;\n  }\n\n  private close(): void {\n    this.menuOpen = false;\n  }\n\n  private handleSelect(item: MenuItemData): void {\n    const next = nextTableSortStateFromMenuItem(this.columns, this.sort, item);\n    if (tableSortStatesEqual(this.sort, next)) return;\n    this.dsSortChange.emit({ sort: next });\n  }\n}\n",
+      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  h,\n  Host,\n  Method,\n  Prop,\n  State,\n} from '@stencil/core';\nimport type { MenuItemData } from '../Menu/menu-types';\nimport type { TableColumn, TableSortChangeDetail, TableSortState } from '../Table/table-types';\nimport {\n  nextTableSortStateFromMenuItem,\n  tableSortFields,\n  tableSortMenuSections,\n  tableSortStatesEqual,\n} from './table-sort-menu';\n\nlet tableSortSeq = 0;\n\n@Component({\n  tag: 'ds-table-sort',\n  styleUrl: 'TableSort.css',\n  scoped: true,\n})\nexport class TableSort {\n  @Element() private el!: HTMLElement;\n\n  /** Catalog used to derive sortable fields, including compound header segments. */\n  @Prop() columns: TableColumn[] = [];\n  /** Controlled table sort. Header sorting and this menu share the same value. */\n  @Prop() sort: TableSortState | null = null;\n  /** Accessible name for the trigger and menu. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n\n  @Event({ bubbles: false }) dsSortChange!: EventEmitter<TableSortChangeDetail>;\n\n  @State() private menuOpen = false;\n  @State() private menuSurfaceOpen = false;\n  @State() private initialFocusVisible = false;\n\n  private readonly componentId = `ds-table-sort-${++tableSortSeq}`;\n  private readonly triggerId = `${this.componentId}-trigger`;\n  private readonly menuId = `${this.componentId}-menu`;\n\n  @Method()\n  async setFocus() {\n    const trigger = this.el.querySelector<HTMLElement & { setFocus?: () => Promise<void> }>(\n      `#${CSS.escape(this.triggerId)}`\n    );\n    await trigger?.setFocus?.();\n  }\n\n  render() {\n    const fields = tableSortFields(this.columns);\n    const name = this.ariaLabel?.trim() || 'Sort table';\n\n    return (\n      <Host hidden={fields.length === 0 ? true : undefined}>\n        {fields.length === 0 ? null : (\n          <ds-button-unfilled\n            id={this.triggerId}\n            variant=\"icon-label\"\n            size=\"md\"\n            icon=\"ArrowsVertical\"\n            label=\"Sort\"\n            labelEmphasis={false}\n            pressScale={false}\n            aria-label={name}\n            hasMenu={true}\n            collapseLabel={true}\n            expanded={this.menuOpen}\n            surfaceOpen={this.menuSurfaceOpen}\n            controls={this.menuId}\n            onDsClick={(event: CustomEvent<MouseEvent>) => {\n              this.toggle(event.detail.detail === 0);\n            }}\n          />\n        )}\n        {fields.length === 0 ? null : (\n          <ds-menu\n            id={this.menuId}\n            open={this.menuOpen}\n            anchorId={this.triggerId}\n            align=\"start\"\n            side=\"bottom\"\n            menuLabel={name}\n            selectionMode=\"none\"\n            initialFocusVisible={this.initialFocusVisible}\n            sections={tableSortMenuSections(this.columns, this.sort)}\n            onDsClose={() => this.close()}\n            onDsAfterClose={() => {\n              if (!this.menuOpen) this.menuSurfaceOpen = false;\n            }}\n            onDsSelect={event => this.handleSelect(event.detail)}\n          />\n        )}\n      </Host>\n    );\n  }\n\n  private toggle(fromKeyboard = false): void {\n    if (this.menuOpen) this.close();\n    else this.open(fromKeyboard);\n  }\n\n  private open(fromKeyboard = false): void {\n    if (this.menuOpen) return;\n    this.initialFocusVisible = fromKeyboard;\n    this.menuOpen = true;\n    this.menuSurfaceOpen = true;\n  }\n\n  private close(): void {\n    this.menuOpen = false;\n  }\n\n  private handleSelect(item: MenuItemData): void {\n    const next = nextTableSortStateFromMenuItem(this.columns, this.sort, item);\n    if (tableSortStatesEqual(this.sort, next)) return;\n    this.dsSortChange.emit({ sort: next });\n  }\n}\n",
       "type": "registry:ui"
     },
     {