@ds-mo/ui 14.20.0 → 14.22.0

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

@@ -49,7 +49,7 @@
       ],
       "accessibility": [
         "ShellPage exposes the routed page as the main landmark; render exactly one active ShellPage inside ShellApp.",
-        "Provide one BarTitle or BarWorkflow through the desktop header slot and one MobileHeader through mobile-header when the page participates in the mobile shell.",
+        "Provide one BarTitle or BarWorkflow through the desktop header slot when desktopHeaderPlacement=page, and one MobileHeader through mobile-header when the page participates in the mobile shell.",
         "Keep loading, empty, validation, error, progress, success, and failure communication in the default product-content slot.",
         "Responsive variant changes preserve the same heading, controls, accessible names, and keyboard focus targets."
       ],
@@ -57,6 +57,7 @@
         "headerCapacity=roomy, compact, or constrained is supplied before paint by the owning application shell and describes the page-header space available after viewport and shell-chrome policy are applied.",
         "headerPresentation=auto selects the matching header variant from headerCapacity and scroll position.",
         "expanded, compact, and constrained are explicit overrides for exceptional layouts and deterministic examples.",
+        "desktopHeaderPlacement=page preserves page-local sticky title geometry. shell-bar declares that desktop and tablet title chrome is external and compact, restores the responsive top gutter, reports zero page-header block size, and disables page-header scroll compaction while preserving downstream compact-header behavior and full-bleed content.",
         "contentInset=default supplies standard page gutters; none permits maps, canvases, and other full-bleed content.",
         "contentInsetBlockStart=none removes only the gutter adjacent to the page header while retaining the responsive inline and bottom gutters.",
         "contentInsetBlockStartSize can provide an exact roomy top seam, while compactContentInsetBlockStartSize independently defines the compact and constrained seam. ShellPage exposes their resolved sticky-header offset through --ds-shell-page-content-block-start-offset for viewport-fitted descendants.",
@@ -73,6 +74,7 @@
         "responsiveMode=mobile hides and inerts the desktop header, exposes mobile-header, and disables desktop scroll-compaction geometry.",
         "Update headerCapacity synchronously with shell layout state so opening tools or crossing application breakpoints cannot briefly render the wrong presentation.",
         "The default content inset is balanced on every side: 32px in desktop mode and 16px in tablet and mobile modes.",
+        "When desktopHeaderPlacement=shell-bar, desktop and tablet ignore page-header-specific block-start seam overrides and expose --ds-shell-page-content-block-start-offset as the responsive gutter only; mobile keeps its MobileHeader geometry and existing seam.",
         "contentInsetBlockStart can independently remove the top gutter for table and canvas pages that should meet the sticky header; exact roomy and compact block-start sizes support pages whose seam changes with header capacity.",
         "The selected content surface persists unchanged across desktop, tablet, and mobile modes.",
         "On a secondary desktop or tablet page, BarTitle matches the page canvas across capacity and scroll-driven variant changes; the separate mobile-header presentation remains primary.",
@@ -84,7 +86,7 @@
       ],
       "frameworkCaveats": {
         "customElements": [
-          "Import ShellPage with BarTitle or BarWorkflow in slot=header and MobileHeader in slot=mobile-header, then render route content as default children.",
+          "Import ShellPage with BarTitle or BarWorkflow in slot=header when desktopHeaderPlacement=page and MobileHeader in slot=mobile-header, then render route content as default children.",
           "Do not set BarTitle.variant while ShellPage owns headerPresentation."
         ],
         "react": [
@@ -156,6 +158,15 @@
           "mutable": false,
           "description": "Canvas surface painted around and beneath routed page content."
         },
+        "desktopHeaderPlacement": {
+          "type": "ShellPageDesktopHeaderPlacement",
+          "resolvedType": "\"page\" | \"shell-bar\"",
+          "attribute": "desktop-header-placement",
+          "default": "'page'",
+          "required": false,
+          "mutable": false,
+          "description": "Desktop title chrome is rendered in this page or externally in the shell bar."
+        },
         "headerCapacity": {
           "type": "ShellPageCapacity",
           "resolvedType": "\"compact\" | \"constrained\" | \"roomy\" | undefined",
@@ -240,6 +251,15 @@
         "mutable": false,
         "description": "Canvas surface painted around and beneath routed page content."
       },
+      "desktopHeaderPlacement": {
+        "type": "ShellPageDesktopHeaderPlacement",
+        "resolvedType": "\"page\" | \"shell-bar\"",
+        "attribute": "desktop-header-placement",
+        "default": "'page'",
+        "required": false,
+        "mutable": false,
+        "description": "Desktop title chrome is rendered in this page or externally in the shell bar."
+      },
       "headerCapacity": {
         "type": "ShellPageCapacity",
         "resolvedType": "\"compact\" | \"constrained\" | \"roomy\" | undefined",
@@ -321,12 +341,12 @@
   "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.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}\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"
     },
     {
       "path": "src/wc/components/ShellPage/ShellPage.tsx",
-      "content": "import { Component, Element, h, Host, Prop, State, Watch } from '@stencil/core';\nimport type { ShellResponsiveMode } from '../../shell/shell-responsive';\nimport { resolveCssLengthPx } from '../../utils/resolve-css-length-px';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\nimport { resolveShellPageHeaderVariant } from './shell-page-responsive';\nimport type {\n  ShellPageCapacity,\n  ShellPageContentInset,\n  ShellPageContentSurface,\n  ShellPageHeaderPresentation,\n} from './shell-page-types';\n\ntype BarTitleElement = HTMLElement & { variant: BarTitleVariant };\n\n@Component({\n  tag: 'ds-shell-page',\n  styleUrl: 'ShellPage.css',\n  scoped: true,\n})\nexport class ShellPage {\n  private static readonly MAX_HEADER_REVEAL_FRAMES = 12;\n  private static readonly MAX_HEADER_GEOMETRY_FRAMES = 12;\n\n  @Element() el!: HTMLElement;\n\n  /** Automatic capacity/scroll behavior, or an explicit header variant override. */\n  @Prop() headerPresentation: ShellPageHeaderPresentation = 'auto';\n\n  /** Available page-header capacity supplied by the owning application shell. */\n  @Prop() headerCapacity?: ShellPageCapacity;\n\n  /** Standard page gutters, or no inset for full-bleed page content. */\n  @Prop() contentInset: ShellPageContentInset = 'default';\n\n  /** Preserve the responsive side/end gutters while allowing content to meet the header. */\n  @Prop() contentInsetBlockStart: ShellPageContentInset = 'default';\n\n  /** Exact block-start content inset, overriding the responsive default when provided. */\n  @Prop() contentInsetBlockStartSize?: string;\n\n  /** Exact block-start content inset while the header is compact or constrained. */\n  @Prop() compactContentInsetBlockStartSize?: string;\n\n  /** Allow roomy automatic headers to compact as the page scrolls. */\n  @Prop() scrollCompaction: boolean = true;\n\n  /** Canvas surface painted around and beneath routed page content. */\n  @Prop() contentSurface: ShellPageContentSurface = 'primary';\n\n  /** Explicit shell breakpoint presentation. Mobile uses the dedicated mobile-header slot. */\n  @Prop({ attribute: 'responsive-mode', reflect: true })\n  responsiveMode: ShellResponsiveMode = 'desktop';\n\n  @State() private pageTopVisible = true;\n\n  private sentinelEl: HTMLElement | null = null;\n  private spacerEl: HTMLElement | null = null;\n  private stickyHeaderEl: HTMLElement | null = null;\n  private headerEl: BarTitleElement | null = null;\n  private expandedHeaderHeight = 0;\n  private headerTravel = 0;\n  private expandedGeometryFrozen = false;\n  private pageHeaderResizeObserver: ResizeObserver | null = null;\n  private headerResizeObserver: ResizeObserver | null = null;\n  private headerMutationObserver: MutationObserver | null = null;\n  private headerRevealFrame: number | null = null;\n  private headerGeometryFrame: number | null = null;\n  private reconnectFrame: number | null = null;\n  private scrollRoot: HTMLElement | Window | null = null;\n  private hasLoaded = false;\n\n  @Watch('headerCapacity')\n  @Watch('headerPresentation')\n  @Watch('scrollCompaction')\n  handleHeaderContractChange() {\n    this.syncHeaderVariant(true);\n  }\n\n  @Watch('responsiveMode')\n  handleResponsiveModeChange() {\n    this.el.style.removeProperty('--ds-shell-page-sticky-header-block-size');\n    this.observeHeader(this.responsiveMode === 'mobile' ? null : this.findHeader());\n  }\n\n  componentDidLoad() {\n    this.hasLoaded = true;\n    this.connectRuntime();\n  }\n\n  componentDidRender() {\n    this.syncHeaderVariant();\n  }\n\n  connectedCallback() {\n    if (!this.hasLoaded) return;\n    if (this.reconnectFrame !== null) cancelAnimationFrame(this.reconnectFrame);\n    this.reconnectFrame = requestAnimationFrame(() => {\n      this.reconnectFrame = null;\n      if (this.el.isConnected) this.connectRuntime();\n    });\n  }\n\n  disconnectedCallback() {\n    if (this.reconnectFrame !== null) cancelAnimationFrame(this.reconnectFrame);\n    this.reconnectFrame = null;\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.pageHeaderResizeObserver?.disconnect();\n    this.pageHeaderResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.headerEl?.style.removeProperty('--ds-bar-title-divider-inset');\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = null;\n  }\n\n  private connectRuntime() {\n    this.observePageHeaderGeometry();\n    this.observeHeader(this.responsiveMode === 'mobile' ? null : this.findHeader());\n    this.connectScrollRoot();\n  }\n\n  private get effectiveVariant(): BarTitleVariant {\n    return resolveShellPageHeaderVariant(\n      this.headerPresentation,\n      this.headerCapacity ?? 'roomy',\n      this.scrollCompaction ? this.pageTopVisible : true\n    );\n  }\n\n  private get headerContractResolved(): boolean {\n    return this.headerPresentation !== 'auto' || this.headerCapacity !== undefined;\n  }\n\n  private get isScrollCompacted(): boolean {\n    return (\n      this.scrollCompaction &&\n      this.headerPresentation === 'auto' &&\n      this.headerCapacity === 'roomy' &&\n      !this.pageTopVisible\n    );\n  }\n\n  private get contentInsetStyles(): { [name: string]: string } {\n    const styles: { [name: string]: string } = {};\n    const expanded = this.contentInsetBlockStartSize?.trim();\n    const compact = this.compactContentInsetBlockStartSize?.trim();\n    if (expanded) styles['--ds-shell-page-content-block-start-inset'] = expanded;\n    if (compact) styles['--ds-shell-page-compact-content-block-start-inset'] = compact;\n    return styles;\n  }\n\n  private composedParent(element: Element): Element | null {\n    return (element as HTMLElement).assignedSlot?.parentElement ?? element.parentElement;\n  }\n\n  private findScrollRoot(): HTMLElement | Window {\n    let ancestor = this.composedParent(this.el);\n    while (ancestor && ancestor !== document.documentElement) {\n      const overflow = getComputedStyle(ancestor).overflowY;\n      if (overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay') {\n        return ancestor as HTMLElement;\n      }\n      ancestor = this.composedParent(ancestor);\n    }\n    return window;\n  }\n\n  private connectScrollRoot() {\n    const next = this.findScrollRoot();\n    if (next === this.scrollRoot) return;\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = next;\n    this.scrollRoot.addEventListener('scroll', this.handleScroll, { passive: true });\n    this.handleScroll();\n  }\n\n  private get scrollRootResolved(): boolean {\n    const shell = this.el.closest('ds-shell-app');\n    if (!shell) return true;\n    const expected = shell.querySelector<HTMLElement>('.shell-app__content');\n    return expected !== null && this.scrollRoot === expected;\n  }\n\n  private handleScroll = () => {\n    if (!this.sentinelEl || !this.scrollRoot) return;\n    const rootTop =\n      this.scrollRoot === window ? 0 : (this.scrollRoot as HTMLElement).getBoundingClientRect().top;\n    this.syncHeaderDividerInset(rootTop);\n    const nextPageTopVisible = this.sentinelEl.getBoundingClientRect().top >= rootTop;\n    if (\n      this.scrollCompaction &&\n      !nextPageTopVisible &&\n      this.pageTopVisible &&\n      this.headerEl?.classList.contains(this.variantClass('expanded'))\n    ) {\n      this.captureExpandedHeaderGeometry(this.headerEl);\n      this.expandedGeometryFrozen = true;\n    }\n    if (\n      nextPageTopVisible &&\n      this.expandedGeometryFrozen &&\n      this.el.getBoundingClientRect().top >= rootTop\n    ) {\n      this.expandedGeometryFrozen = false;\n      if (this.headerEl?.classList.contains(this.variantClass('expanded'))) {\n        this.captureExpandedHeaderGeometry(this.headerEl);\n      }\n    }\n    this.pageTopVisible = nextPageTopVisible;\n  };\n\n  private findHeader(): BarTitleElement | null {\n    return this.el.querySelector<BarTitleElement>('ds-bar-title');\n  }\n\n  private get compactHeaderHeight(): number {\n    return resolveCssLengthPx('--dimension-size-600', 0);\n  }\n\n  private syncHeaderDividerInset(rootTop?: number) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    const ownsScrollTransition =\n      this.scrollCompaction &&\n      this.headerPresentation === 'auto' &&\n      this.headerCapacity === 'roomy';\n    const expandedInset = resolveCssLengthPx('--dimension-space-400', 0);\n    if (\n      !ownsScrollTransition ||\n      !this.sentinelEl ||\n      !this.scrollRoot ||\n      this.headerTravel <= 0 ||\n      expandedInset <= 0\n    ) {\n      header.style.removeProperty('--ds-bar-title-divider-inset');\n      return;\n    }\n\n    const scrollRootTop =\n      rootTop ??\n      (this.scrollRoot === window\n        ? 0\n        : (this.scrollRoot as HTMLElement).getBoundingClientRect().top);\n    const remainingTravel = this.sentinelEl.getBoundingClientRect().top - scrollRootTop;\n    const progress = Math.min(1, Math.max(0, 1 - remainingTravel / this.headerTravel));\n    header.style.setProperty('--ds-bar-title-divider-inset', `${expandedInset * (1 - progress)}px`);\n  }\n\n  private setHeaderTravel(distance: number) {\n    const next = Math.max(0, distance);\n    if (Math.abs(next - this.headerTravel) < 0.5) return;\n    this.headerTravel = next;\n    this.el.style.setProperty('--ds-shell-page-header-travel', `${next}px`);\n    this.handleScroll();\n  }\n\n  private measureHeaderTravel(header: BarTitleElement) {\n    const anchor = header.querySelector<HTMLElement>('[data-shell-page-header-anchor]');\n    const compactHeight = this.compactHeaderHeight;\n    if (!anchor || compactHeight <= 0) return;\n\n    const headerRect = header.getBoundingClientRect();\n    const anchorRect = anchor.getBoundingClientRect();\n    if (headerRect.height <= 0 || anchorRect.height <= 0) return;\n\n    const expandedAnchorTop = anchorRect.top - headerRect.top;\n    const compactAnchorTop = Math.max(0, (compactHeight - anchorRect.height) / 2);\n    this.setHeaderTravel(expandedAnchorTop - compactAnchorTop);\n  }\n\n  private captureExpandedHeaderGeometry(header: BarTitleElement) {\n    // Keep the largest observed expanded geometry for this header instance.\n    // During a variant handoff Chromium can briefly report the compact box\n    // before the child host class mutation is delivered; that transient must\n    // not erase the flow reservation captured at the roomy page top.\n    this.expandedHeaderHeight = Math.max(\n      this.expandedHeaderHeight,\n      header.getBoundingClientRect().height\n    );\n    this.measureHeaderTravel(header);\n  }\n\n  private setSpacerHeight(height: number) {\n    if (!this.spacerEl) return;\n    this.spacerEl.style.setProperty('--ds-shell-page-flow-spacer', `${Math.max(0, height)}px`);\n  }\n\n  private variantClass(variant: BarTitleVariant): string {\n    return `bar-title-host--${variant}`;\n  }\n\n  private setStickyHeaderOffset(renderedVariant: BarTitleVariant) {\n    this.stickyHeaderEl?.style.setProperty(\n      '--ds-shell-page-sticky-offset',\n      renderedVariant === 'expanded' &&\n        this.scrollCompaction &&\n        this.headerPresentation === 'auto' &&\n        this.headerCapacity === 'roomy'\n        ? `${-this.headerTravel}px`\n        : '0px'\n    );\n  }\n\n  private syncPageHeaderBlockSize() {\n    const renderedHeight = this.stickyHeaderEl?.getBoundingClientRect().height ?? 0;\n    if (renderedHeight > 0) {\n      this.el.style.setProperty('--ds-shell-page-sticky-header-block-size', `${renderedHeight}px`);\n    }\n  }\n\n  private observePageHeaderGeometry() {\n    this.pageHeaderResizeObserver?.disconnect();\n    this.pageHeaderResizeObserver = null;\n    this.syncPageHeaderBlockSize();\n\n    if (!this.stickyHeaderEl || typeof ResizeObserver === 'undefined') return;\n    this.pageHeaderResizeObserver = new ResizeObserver(() => {\n      this.syncPageHeaderBlockSize();\n    });\n    this.pageHeaderResizeObserver.observe(this.stickyHeaderEl);\n  }\n\n  private syncRenderedHeaderGeometry(header: BarTitleElement) {\n    const renderedVariant = this.effectiveVariant;\n    if (!header.classList.contains(this.variantClass(renderedVariant))) return;\n\n    this.syncPageHeaderBlockSize();\n\n    // Update both flow-preservation pieces before reading layout. Otherwise a\n    // reverse compact → expanded render can briefly contain the tall header and\n    // the compact spacer together, giving browser scroll anchoring a transient\n    // height change to compensate.\n    this.setSpacerHeight(\n      this.isScrollCompacted ? this.expandedHeaderHeight - this.compactHeaderHeight : 0\n    );\n    this.setStickyHeaderOffset(renderedVariant);\n\n    if (renderedVariant === 'expanded' && !this.expandedGeometryFrozen) {\n      this.captureExpandedHeaderGeometry(header);\n      this.setStickyHeaderOffset(renderedVariant);\n    }\n  }\n\n  private cancelHeaderGeometrySync() {\n    if (this.headerGeometryFrame !== null) cancelAnimationFrame(this.headerGeometryFrame);\n    this.headerGeometryFrame = null;\n  }\n\n  private scheduleHeaderGeometrySync(header: BarTitleElement) {\n    this.cancelHeaderGeometrySync();\n    let framesRemaining = ShellPage.MAX_HEADER_GEOMETRY_FRAMES;\n    let framesElapsed = 0;\n    const sync = () => {\n      if (this.headerEl !== header) return;\n      framesRemaining -= 1;\n      framesElapsed += 1;\n      // In WebKit a child's componentDidLoad can precede its assignment into\n      // the parent's rendered slot. Revalidate after ShellApp has had a frame\n      // to expose the actual content scroller.\n      this.connectScrollRoot();\n      this.syncRenderedHeaderGeometry(header);\n      const geometryReady =\n        this.effectiveVariant !== 'expanded' ||\n        (this.expandedHeaderHeight > 0 && this.headerTravel > 0);\n      if (\n        (geometryReady && this.scrollRootResolved && framesElapsed >= 2) ||\n        framesRemaining <= 0\n      ) {\n        this.headerGeometryFrame = null;\n        return;\n      }\n      this.headerGeometryFrame = requestAnimationFrame(sync);\n    };\n    this.headerGeometryFrame = requestAnimationFrame(sync);\n  }\n\n  private cancelHeaderReveal() {\n    if (this.headerRevealFrame !== null) cancelAnimationFrame(this.headerRevealFrame);\n    this.headerRevealFrame = null;\n    this.headerEl?.removeAttribute('data-shell-page-syncing');\n  }\n\n  private revealHeaderWhenSynced(header: BarTitleElement, variant: BarTitleVariant) {\n    // Stencil normally re-renders within a frame or two of a prop change. Stop\n    // polling at the cap, but fail closed: a stale variant must never paint.\n    let framesRemaining = ShellPage.MAX_HEADER_REVEAL_FRAMES;\n    const reveal = () => {\n      if (this.headerEl !== header) {\n        header.removeAttribute('data-shell-page-syncing');\n        return;\n      }\n      framesRemaining -= 1;\n      if (header.classList.contains(this.variantClass(variant))) {\n        header.removeAttribute('data-shell-page-syncing');\n        this.headerRevealFrame = null;\n        return;\n      }\n      if (framesRemaining <= 0) {\n        this.headerRevealFrame = null;\n        return;\n      }\n      this.headerRevealFrame = requestAnimationFrame(reveal);\n    };\n    this.headerRevealFrame = requestAnimationFrame(reveal);\n  }\n\n  private syncHeaderVariant(concealUntilSynced = false) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    this.syncHeaderDividerInset();\n    if (!this.headerContractResolved) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n      return;\n    }\n\n    const next = this.effectiveVariant;\n    const renderedVariantIsStale = !header.classList.contains(this.variantClass(next));\n    if (!renderedVariantIsStale) this.syncRenderedHeaderGeometry(header);\n    if (renderedVariantIsStale && this.isScrollCompacted) {\n      // Preserve the expanded flow before asking BarTitle to become compact.\n      // This prevents the sentinel from moving back into view during the\n      // parent/child render handoff and keeps the variant transition stable.\n      this.setSpacerHeight(this.expandedHeaderHeight - this.compactHeaderHeight);\n      this.setStickyHeaderOffset(next);\n    }\n    if (concealUntilSynced) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n    }\n    if (header.variant !== next) {\n      header.variant = next;\n      // The child update and its MutationObserver callback can land in\n      // different phases across engines. Poll the rendered class as the\n      // authoritative handoff before committing sticky/spacer geometry.\n      this.scheduleHeaderGeometrySync(header);\n    }\n    if (concealUntilSynced) {\n      this.revealHeaderWhenSynced(header, next);\n    }\n  }\n\n  private observeHeader(header: BarTitleElement | null) {\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.headerEl?.style.removeProperty('--ds-bar-title-divider-inset');\n    this.headerEl = header;\n    this.expandedHeaderHeight = 0;\n    this.expandedGeometryFrozen = false;\n    this.setHeaderTravel(0);\n    this.setSpacerHeight(0);\n    this.stickyHeaderEl?.style.setProperty('--ds-shell-page-sticky-offset', '0px');\n\n    if (!header) return;\n    if (header.classList.contains(this.variantClass('expanded'))) {\n      this.captureExpandedHeaderGeometry(header);\n    }\n    if (typeof ResizeObserver !== 'undefined') {\n      this.headerResizeObserver = new ResizeObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerResizeObserver.observe(header);\n    }\n    if (typeof MutationObserver !== 'undefined') {\n      this.headerMutationObserver = new MutationObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerMutationObserver.observe(header, {\n        attributes: true,\n        attributeFilter: ['class'],\n        childList: true,\n        subtree: true,\n      });\n    }\n    this.syncHeaderVariant(true);\n    this.scheduleHeaderGeometrySync(header);\n  }\n\n  private handleHeaderSlotChange = (event: Event) => {\n    if (this.responsiveMode === 'mobile') return;\n    const slot = event.target as HTMLSlotElement;\n    const header = slot\n      .assignedElements()\n      .find(element => element.tagName.toLowerCase() === 'ds-bar-title');\n    this.observeHeader((header as BarTitleElement | undefined) ?? null);\n  };\n\n  render() {\n    const mobile = this.responsiveMode === 'mobile';\n    return (\n      <Host\n        role=\"main\"\n        style={this.contentInsetStyles}\n        class={{\n          'shell-page-host--inset-default': this.contentInset === 'default',\n          'shell-page-host--inset-none': this.contentInset === 'none',\n          'shell-page-host--block-start-inset-none': this.contentInsetBlockStart === 'none',\n          'shell-page-host--surface-primary': this.contentSurface === 'primary',\n          'shell-page-host--surface-secondary': this.contentSurface === 'secondary',\n          'shell-page-host--mobile': mobile,\n          [`shell-page-host--header-${this.effectiveVariant}`]: true,\n        }}\n      >\n        <div\n          ref={el => {\n            this.sentinelEl = el ?? null;\n          }}\n          class=\"shell-page__scroll-sentinel\"\n          aria-hidden=\"true\"\n        />\n        <div\n          ref={el => {\n            this.stickyHeaderEl = el ?? null;\n          }}\n          class=\"shell-page__sticky-header\"\n        >\n          <div\n            class=\"shell-page__desktop-header\"\n            hidden={mobile}\n            aria-hidden={mobile ? 'true' : undefined}\n            inert={mobile ? true : undefined}\n          >\n            <slot name=\"header\" onSlotchange={this.handleHeaderSlotChange} />\n          </div>\n          <div\n            class=\"shell-page__mobile-header\"\n            hidden={!mobile}\n            aria-hidden={!mobile ? 'true' : undefined}\n            inert={!mobile ? true : undefined}\n          >\n            <slot name=\"mobile-header\" />\n          </div>\n        </div>\n        <div\n          ref={el => {\n            this.spacerEl = el ?? null;\n          }}\n          class=\"shell-page__flow-spacer\"\n          aria-hidden=\"true\"\n        />\n        <div class=\"shell-page__content\">\n          <slot />\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, h, Host, Prop, State, Watch } from '@stencil/core';\nimport type { ShellResponsiveMode } from '../../shell/shell-responsive';\nimport { resolveCssLengthPx } from '../../utils/resolve-css-length-px';\nimport type { BarTitleVariant } from '../BarTitle/bar-title-types';\nimport { resolveShellPageHeaderVariant } from './shell-page-responsive';\nimport type {\n  ShellPageCapacity,\n  ShellPageContentInset,\n  ShellPageContentSurface,\n  ShellPageDesktopHeaderPlacement,\n  ShellPageHeaderPresentation,\n} from './shell-page-types';\n\ntype BarTitleElement = HTMLElement & { variant: BarTitleVariant };\n\n@Component({\n  tag: 'ds-shell-page',\n  styleUrl: 'ShellPage.css',\n  scoped: true,\n})\nexport class ShellPage {\n  private static readonly MAX_HEADER_REVEAL_FRAMES = 12;\n  private static readonly MAX_HEADER_GEOMETRY_FRAMES = 12;\n\n  @Element() el!: HTMLElement;\n\n  /** Automatic capacity/scroll behavior, or an explicit header variant override. */\n  @Prop() headerPresentation: ShellPageHeaderPresentation = 'auto';\n\n  /** Available page-header capacity supplied by the owning application shell. */\n  @Prop() headerCapacity?: ShellPageCapacity;\n\n  /** Desktop title chrome is rendered in this page or externally in the shell bar. */\n  @Prop({ attribute: 'desktop-header-placement', reflect: true })\n  desktopHeaderPlacement: ShellPageDesktopHeaderPlacement = 'page';\n\n  /** Standard page gutters, or no inset for full-bleed page content. */\n  @Prop() contentInset: ShellPageContentInset = 'default';\n\n  /** Preserve the responsive side/end gutters while allowing content to meet the header. */\n  @Prop() contentInsetBlockStart: ShellPageContentInset = 'default';\n\n  /** Exact block-start content inset, overriding the responsive default when provided. */\n  @Prop() contentInsetBlockStartSize?: string;\n\n  /** Exact block-start content inset while the header is compact or constrained. */\n  @Prop() compactContentInsetBlockStartSize?: string;\n\n  /** Allow roomy automatic headers to compact as the page scrolls. */\n  @Prop() scrollCompaction: boolean = true;\n\n  /** Canvas surface painted around and beneath routed page content. */\n  @Prop() contentSurface: ShellPageContentSurface = 'primary';\n\n  /** Explicit shell breakpoint presentation. Mobile uses the dedicated mobile-header slot. */\n  @Prop({ attribute: 'responsive-mode', reflect: true })\n  responsiveMode: ShellResponsiveMode = 'desktop';\n\n  @State() private pageTopVisible = true;\n\n  private sentinelEl: HTMLElement | null = null;\n  private spacerEl: HTMLElement | null = null;\n  private stickyHeaderEl: HTMLElement | null = null;\n  private headerEl: BarTitleElement | null = null;\n  private expandedHeaderHeight = 0;\n  private headerTravel = 0;\n  private expandedGeometryFrozen = false;\n  private pageHeaderResizeObserver: ResizeObserver | null = null;\n  private headerResizeObserver: ResizeObserver | null = null;\n  private headerMutationObserver: MutationObserver | null = null;\n  private headerRevealFrame: number | null = null;\n  private headerGeometryFrame: number | null = null;\n  private reconnectFrame: number | null = null;\n  private scrollRoot: HTMLElement | Window | null = null;\n  private hasLoaded = false;\n\n  @Watch('headerCapacity')\n  @Watch('headerPresentation')\n  @Watch('scrollCompaction')\n  handleHeaderContractChange() {\n    this.syncHeaderVariant(true);\n  }\n\n  @Watch('responsiveMode')\n  handleResponsiveModeChange() {\n    this.el.style.removeProperty('--ds-shell-page-sticky-header-block-size');\n    this.observeHeader(\n      this.responsiveMode === 'mobile' || this.desktopHeaderExternal ? null : this.findHeader()\n    );\n    this.syncPageHeaderBlockSize();\n  }\n\n  @Watch('desktopHeaderPlacement')\n  handleDesktopHeaderPlacementChange() {\n    this.observeHeader(this.desktopHeaderExternal ? null : this.findHeader());\n    this.syncPageHeaderBlockSize();\n  }\n\n  componentDidLoad() {\n    this.hasLoaded = true;\n    this.connectRuntime();\n  }\n\n  componentDidRender() {\n    this.syncHeaderVariant();\n    this.syncPageHeaderBlockSize();\n  }\n\n  connectedCallback() {\n    if (!this.hasLoaded) return;\n    if (this.reconnectFrame !== null) cancelAnimationFrame(this.reconnectFrame);\n    this.reconnectFrame = requestAnimationFrame(() => {\n      this.reconnectFrame = null;\n      if (this.el.isConnected) this.connectRuntime();\n    });\n  }\n\n  disconnectedCallback() {\n    if (this.reconnectFrame !== null) cancelAnimationFrame(this.reconnectFrame);\n    this.reconnectFrame = null;\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.pageHeaderResizeObserver?.disconnect();\n    this.pageHeaderResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.headerEl?.style.removeProperty('--ds-bar-title-divider-inset');\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = null;\n  }\n\n  private connectRuntime() {\n    this.observePageHeaderGeometry();\n    this.observeHeader(this.responsiveMode === 'mobile' ? null : this.findHeader());\n    this.connectScrollRoot();\n  }\n\n  private get effectiveVariant(): BarTitleVariant {\n    if (this.desktopHeaderExternal) return 'compact';\n    return resolveShellPageHeaderVariant(\n      this.headerPresentation,\n      this.headerCapacity ?? 'roomy',\n      this.effectiveScrollCompaction ? this.pageTopVisible : true\n    );\n  }\n\n  private get desktopHeaderExternal(): boolean {\n    return this.responsiveMode !== 'mobile' && this.desktopHeaderPlacement === 'shell-bar';\n  }\n\n  private get effectiveScrollCompaction(): boolean {\n    return this.scrollCompaction && !this.desktopHeaderExternal;\n  }\n\n  private get headerContractResolved(): boolean {\n    return this.headerPresentation !== 'auto' || this.headerCapacity !== undefined;\n  }\n\n  private get isScrollCompacted(): boolean {\n    return (\n      this.effectiveScrollCompaction &&\n      this.headerPresentation === 'auto' &&\n      this.headerCapacity === 'roomy' &&\n      !this.pageTopVisible\n    );\n  }\n\n  private get contentInsetStyles(): { [name: string]: string } {\n    const styles: { [name: string]: string } = {};\n    const expanded = this.contentInsetBlockStartSize?.trim();\n    const compact = this.compactContentInsetBlockStartSize?.trim();\n    if (expanded) styles['--ds-shell-page-content-block-start-inset'] = expanded;\n    if (compact) styles['--ds-shell-page-compact-content-block-start-inset'] = compact;\n    return styles;\n  }\n\n  private composedParent(element: Element): Element | null {\n    return (element as HTMLElement).assignedSlot?.parentElement ?? element.parentElement;\n  }\n\n  private findScrollRoot(): HTMLElement | Window {\n    let ancestor = this.composedParent(this.el);\n    while (ancestor && ancestor !== document.documentElement) {\n      const overflow = getComputedStyle(ancestor).overflowY;\n      if (overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay') {\n        return ancestor as HTMLElement;\n      }\n      ancestor = this.composedParent(ancestor);\n    }\n    return window;\n  }\n\n  private connectScrollRoot() {\n    const next = this.findScrollRoot();\n    if (next === this.scrollRoot) return;\n    this.scrollRoot?.removeEventListener('scroll', this.handleScroll);\n    this.scrollRoot = next;\n    this.scrollRoot.addEventListener('scroll', this.handleScroll, { passive: true });\n    this.handleScroll();\n  }\n\n  private get scrollRootResolved(): boolean {\n    const shell = this.el.closest('ds-shell-app');\n    if (!shell) return true;\n    const expected = shell.querySelector<HTMLElement>('.shell-app__content');\n    return expected !== null && this.scrollRoot === expected;\n  }\n\n  private handleScroll = () => {\n    if (!this.sentinelEl || !this.scrollRoot) return;\n    const rootTop =\n      this.scrollRoot === window ? 0 : (this.scrollRoot as HTMLElement).getBoundingClientRect().top;\n    this.syncHeaderDividerInset(rootTop);\n    const nextPageTopVisible = this.sentinelEl.getBoundingClientRect().top >= rootTop;\n    if (\n      this.effectiveScrollCompaction &&\n      !nextPageTopVisible &&\n      this.pageTopVisible &&\n      this.headerEl?.classList.contains(this.variantClass('expanded'))\n    ) {\n      this.captureExpandedHeaderGeometry(this.headerEl);\n      this.expandedGeometryFrozen = true;\n    }\n    if (\n      nextPageTopVisible &&\n      this.expandedGeometryFrozen &&\n      this.el.getBoundingClientRect().top >= rootTop\n    ) {\n      this.expandedGeometryFrozen = false;\n      if (this.headerEl?.classList.contains(this.variantClass('expanded'))) {\n        this.captureExpandedHeaderGeometry(this.headerEl);\n      }\n    }\n    this.pageTopVisible = nextPageTopVisible;\n  };\n\n  private findHeader(): BarTitleElement | null {\n    return this.el.querySelector<BarTitleElement>('ds-bar-title');\n  }\n\n  private get compactHeaderHeight(): number {\n    return resolveCssLengthPx('--dimension-size-600', 0);\n  }\n\n  private syncHeaderDividerInset(rootTop?: number) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    const ownsScrollTransition =\n      this.effectiveScrollCompaction &&\n      this.headerPresentation === 'auto' &&\n      this.headerCapacity === 'roomy';\n    const expandedInset = resolveCssLengthPx('--dimension-space-400', 0);\n    if (\n      !ownsScrollTransition ||\n      !this.sentinelEl ||\n      !this.scrollRoot ||\n      this.headerTravel <= 0 ||\n      expandedInset <= 0\n    ) {\n      header.style.removeProperty('--ds-bar-title-divider-inset');\n      return;\n    }\n\n    const scrollRootTop =\n      rootTop ??\n      (this.scrollRoot === window\n        ? 0\n        : (this.scrollRoot as HTMLElement).getBoundingClientRect().top);\n    const remainingTravel = this.sentinelEl.getBoundingClientRect().top - scrollRootTop;\n    const progress = Math.min(1, Math.max(0, 1 - remainingTravel / this.headerTravel));\n    header.style.setProperty('--ds-bar-title-divider-inset', `${expandedInset * (1 - progress)}px`);\n  }\n\n  private setHeaderTravel(distance: number) {\n    const next = Math.max(0, distance);\n    if (Math.abs(next - this.headerTravel) < 0.5) return;\n    this.headerTravel = next;\n    this.el.style.setProperty('--ds-shell-page-header-travel', `${next}px`);\n    this.handleScroll();\n  }\n\n  private measureHeaderTravel(header: BarTitleElement) {\n    const anchor = header.querySelector<HTMLElement>('[data-shell-page-header-anchor]');\n    const compactHeight = this.compactHeaderHeight;\n    if (!anchor || compactHeight <= 0) return;\n\n    const headerRect = header.getBoundingClientRect();\n    const anchorRect = anchor.getBoundingClientRect();\n    if (headerRect.height <= 0 || anchorRect.height <= 0) return;\n\n    const expandedAnchorTop = anchorRect.top - headerRect.top;\n    const compactAnchorTop = Math.max(0, (compactHeight - anchorRect.height) / 2);\n    this.setHeaderTravel(expandedAnchorTop - compactAnchorTop);\n  }\n\n  private captureExpandedHeaderGeometry(header: BarTitleElement) {\n    // Keep the largest observed expanded geometry for this header instance.\n    // During a variant handoff Chromium can briefly report the compact box\n    // before the child host class mutation is delivered; that transient must\n    // not erase the flow reservation captured at the roomy page top.\n    this.expandedHeaderHeight = Math.max(\n      this.expandedHeaderHeight,\n      header.getBoundingClientRect().height\n    );\n    this.measureHeaderTravel(header);\n  }\n\n  private setSpacerHeight(height: number) {\n    if (!this.spacerEl) return;\n    this.spacerEl.style.setProperty('--ds-shell-page-flow-spacer', `${Math.max(0, height)}px`);\n  }\n\n  private variantClass(variant: BarTitleVariant): string {\n    return `bar-title-host--${variant}`;\n  }\n\n  private setStickyHeaderOffset(renderedVariant: BarTitleVariant) {\n    this.stickyHeaderEl?.style.setProperty(\n      '--ds-shell-page-sticky-offset',\n      renderedVariant === 'expanded' &&\n        this.effectiveScrollCompaction &&\n        this.headerPresentation === 'auto' &&\n        this.headerCapacity === 'roomy'\n        ? `${-this.headerTravel}px`\n        : '0px'\n    );\n  }\n\n  private syncPageHeaderBlockSize() {\n    if (this.desktopHeaderExternal) {\n      this.el.style.setProperty('--ds-shell-page-sticky-header-block-size', '0px');\n      return;\n    }\n    const renderedHeight = this.stickyHeaderEl?.getBoundingClientRect().height ?? 0;\n    if (renderedHeight > 0) {\n      this.el.style.setProperty('--ds-shell-page-sticky-header-block-size', `${renderedHeight}px`);\n    } else {\n      this.el.style.removeProperty('--ds-shell-page-sticky-header-block-size');\n    }\n  }\n\n  private observePageHeaderGeometry() {\n    this.pageHeaderResizeObserver?.disconnect();\n    this.pageHeaderResizeObserver = null;\n    this.syncPageHeaderBlockSize();\n\n    if (!this.stickyHeaderEl || typeof ResizeObserver === 'undefined') return;\n    this.pageHeaderResizeObserver = new ResizeObserver(() => {\n      this.syncPageHeaderBlockSize();\n    });\n    this.pageHeaderResizeObserver.observe(this.stickyHeaderEl);\n  }\n\n  private syncRenderedHeaderGeometry(header: BarTitleElement) {\n    const renderedVariant = this.effectiveVariant;\n    if (!header.classList.contains(this.variantClass(renderedVariant))) return;\n\n    this.syncPageHeaderBlockSize();\n\n    // Update both flow-preservation pieces before reading layout. Otherwise a\n    // reverse compact → expanded render can briefly contain the tall header and\n    // the compact spacer together, giving browser scroll anchoring a transient\n    // height change to compensate.\n    this.setSpacerHeight(\n      this.isScrollCompacted ? this.expandedHeaderHeight - this.compactHeaderHeight : 0\n    );\n    this.setStickyHeaderOffset(renderedVariant);\n\n    if (renderedVariant === 'expanded' && !this.expandedGeometryFrozen) {\n      this.captureExpandedHeaderGeometry(header);\n      this.setStickyHeaderOffset(renderedVariant);\n    }\n  }\n\n  private cancelHeaderGeometrySync() {\n    if (this.headerGeometryFrame !== null) cancelAnimationFrame(this.headerGeometryFrame);\n    this.headerGeometryFrame = null;\n  }\n\n  private scheduleHeaderGeometrySync(header: BarTitleElement) {\n    this.cancelHeaderGeometrySync();\n    let framesRemaining = ShellPage.MAX_HEADER_GEOMETRY_FRAMES;\n    let framesElapsed = 0;\n    const sync = () => {\n      if (this.headerEl !== header) return;\n      framesRemaining -= 1;\n      framesElapsed += 1;\n      // In WebKit a child's componentDidLoad can precede its assignment into\n      // the parent's rendered slot. Revalidate after ShellApp has had a frame\n      // to expose the actual content scroller.\n      this.connectScrollRoot();\n      this.syncRenderedHeaderGeometry(header);\n      const geometryReady =\n        this.effectiveVariant !== 'expanded' ||\n        (this.expandedHeaderHeight > 0 && this.headerTravel > 0);\n      if (\n        (geometryReady && this.scrollRootResolved && framesElapsed >= 2) ||\n        framesRemaining <= 0\n      ) {\n        this.headerGeometryFrame = null;\n        return;\n      }\n      this.headerGeometryFrame = requestAnimationFrame(sync);\n    };\n    this.headerGeometryFrame = requestAnimationFrame(sync);\n  }\n\n  private cancelHeaderReveal() {\n    if (this.headerRevealFrame !== null) cancelAnimationFrame(this.headerRevealFrame);\n    this.headerRevealFrame = null;\n    this.headerEl?.removeAttribute('data-shell-page-syncing');\n  }\n\n  private revealHeaderWhenSynced(header: BarTitleElement, variant: BarTitleVariant) {\n    // Stencil normally re-renders within a frame or two of a prop change. Stop\n    // polling at the cap, but fail closed: a stale variant must never paint.\n    let framesRemaining = ShellPage.MAX_HEADER_REVEAL_FRAMES;\n    const reveal = () => {\n      if (this.headerEl !== header) {\n        header.removeAttribute('data-shell-page-syncing');\n        return;\n      }\n      framesRemaining -= 1;\n      if (header.classList.contains(this.variantClass(variant))) {\n        header.removeAttribute('data-shell-page-syncing');\n        this.headerRevealFrame = null;\n        return;\n      }\n      if (framesRemaining <= 0) {\n        this.headerRevealFrame = null;\n        return;\n      }\n      this.headerRevealFrame = requestAnimationFrame(reveal);\n    };\n    this.headerRevealFrame = requestAnimationFrame(reveal);\n  }\n\n  private syncHeaderVariant(concealUntilSynced = false) {\n    const header = this.headerEl;\n    if (!header) return;\n\n    this.syncHeaderDividerInset();\n    if (!this.headerContractResolved) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n      return;\n    }\n\n    const next = this.effectiveVariant;\n    const renderedVariantIsStale = !header.classList.contains(this.variantClass(next));\n    if (!renderedVariantIsStale) this.syncRenderedHeaderGeometry(header);\n    if (renderedVariantIsStale && this.isScrollCompacted) {\n      // Preserve the expanded flow before asking BarTitle to become compact.\n      // This prevents the sentinel from moving back into view during the\n      // parent/child render handoff and keeps the variant transition stable.\n      this.setSpacerHeight(this.expandedHeaderHeight - this.compactHeaderHeight);\n      this.setStickyHeaderOffset(next);\n    }\n    if (concealUntilSynced) {\n      this.cancelHeaderReveal();\n      header.setAttribute('data-shell-page-syncing', '');\n    }\n    if (header.variant !== next) {\n      header.variant = next;\n      // The child update and its MutationObserver callback can land in\n      // different phases across engines. Poll the rendered class as the\n      // authoritative handoff before committing sticky/spacer geometry.\n      this.scheduleHeaderGeometrySync(header);\n    }\n    if (concealUntilSynced) {\n      this.revealHeaderWhenSynced(header, next);\n    }\n  }\n\n  private observeHeader(header: BarTitleElement | null) {\n    this.cancelHeaderReveal();\n    this.cancelHeaderGeometrySync();\n    this.headerResizeObserver?.disconnect();\n    this.headerResizeObserver = null;\n    this.headerMutationObserver?.disconnect();\n    this.headerMutationObserver = null;\n    this.headerEl?.style.removeProperty('--ds-bar-title-divider-inset');\n    this.headerEl = header;\n    this.expandedHeaderHeight = 0;\n    this.expandedGeometryFrozen = false;\n    this.setHeaderTravel(0);\n    this.setSpacerHeight(0);\n    this.stickyHeaderEl?.style.setProperty('--ds-shell-page-sticky-offset', '0px');\n\n    if (!header) return;\n    if (header.classList.contains(this.variantClass('expanded'))) {\n      this.captureExpandedHeaderGeometry(header);\n    }\n    if (typeof ResizeObserver !== 'undefined') {\n      this.headerResizeObserver = new ResizeObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerResizeObserver.observe(header);\n    }\n    if (typeof MutationObserver !== 'undefined') {\n      this.headerMutationObserver = new MutationObserver(() => {\n        this.syncRenderedHeaderGeometry(header);\n      });\n      this.headerMutationObserver.observe(header, {\n        attributes: true,\n        attributeFilter: ['class'],\n        childList: true,\n        subtree: true,\n      });\n    }\n    this.syncHeaderVariant(true);\n    this.scheduleHeaderGeometrySync(header);\n  }\n\n  private handleHeaderSlotChange = (event: Event) => {\n    if (this.responsiveMode === 'mobile') return;\n    const slot = event.target as HTMLSlotElement;\n    const header = slot\n      .assignedElements()\n      .find(element => element.tagName.toLowerCase() === 'ds-bar-title');\n    this.observeHeader((header as BarTitleElement | undefined) ?? null);\n  };\n\n  render() {\n    const mobile = this.responsiveMode === 'mobile';\n    return (\n      <Host\n        role=\"main\"\n        style={this.contentInsetStyles}\n        class={{\n          'shell-page-host--inset-default': this.contentInset === 'default',\n          'shell-page-host--inset-none': this.contentInset === 'none',\n          'shell-page-host--block-start-inset-none': this.contentInsetBlockStart === 'none',\n          'shell-page-host--surface-primary': this.contentSurface === 'primary',\n          'shell-page-host--surface-secondary': this.contentSurface === 'secondary',\n          'shell-page-host--mobile': mobile,\n          'shell-page-host--desktop-header-shell-bar': this.desktopHeaderExternal,\n          [`shell-page-host--header-${this.effectiveVariant}`]: true,\n        }}\n      >\n        <div\n          ref={el => {\n            this.sentinelEl = el ?? null;\n          }}\n          class=\"shell-page__scroll-sentinel\"\n          aria-hidden=\"true\"\n        />\n        <div\n          ref={el => {\n            this.stickyHeaderEl = el ?? null;\n          }}\n          class=\"shell-page__sticky-header\"\n        >\n          <div\n            class=\"shell-page__desktop-header\"\n            hidden={mobile}\n            aria-hidden={mobile ? 'true' : undefined}\n            inert={mobile ? true : undefined}\n          >\n            <slot name=\"header\" onSlotchange={this.handleHeaderSlotChange} />\n          </div>\n          <div\n            class=\"shell-page__mobile-header\"\n            hidden={!mobile}\n            aria-hidden={!mobile ? 'true' : undefined}\n            inert={!mobile ? true : undefined}\n          >\n            <slot name=\"mobile-header\" />\n          </div>\n        </div>\n        <div\n          ref={el => {\n            this.spacerEl = el ?? null;\n          }}\n          class=\"shell-page__flow-spacer\"\n          aria-hidden=\"true\"\n        />\n        <div class=\"shell-page__content\">\n          <slot />\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {
@@ -336,7 +356,7 @@
     },
     {
       "path": "src/wc/components/ShellPage/shell-page-types.ts",
-      "content": "import type { BarTitleVariant } from '../BarTitle/bar-title-types';\n\nexport type ShellPageHeaderPresentation = 'auto' | BarTitleVariant;\n\nexport type ShellPageContentInset = 'default' | 'none';\n\nexport type ShellPageContentSurface = 'primary' | 'secondary';\n\nexport type ShellPageCapacity = 'roomy' | 'compact' | 'constrained';\n",
+      "content": "import type { BarTitleVariant } from '../BarTitle/bar-title-types';\n\nexport type ShellPageHeaderPresentation = 'auto' | BarTitleVariant;\n\nexport type ShellPageDesktopHeaderPlacement = 'page' | 'shell-bar';\n\nexport type ShellPageContentInset = 'default' | 'none';\n\nexport type ShellPageContentSurface = 'primary' | 'secondary';\n\nexport type ShellPageCapacity = 'roomy' | 'compact' | 'constrained';\n",
       "type": "registry:ui"
     }
   ]

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

@@ -66,6 +66,7 @@
         "A missing, empty, inactive, or unknown selected value is invalid when enabled tabs exist; the component does not choose a fallback selection.",
         "Selection is singular and follows keyboard focus.",
         "Width follows the shared control contract: hug keeps the track content-sized, while fill occupies the parent width and distributes available space equally across selectable segments; dividers remain fixed-width separators.",
+        "hasContainer defaults to true. Set it to false only when a parent surface owns the track background and boundary; the outer fill, border, and inset disappear while selected-pill, interaction, focus, density, and keyboard behavior remain unchanged.",
         "Small, medium, and large use the shared 24px, 32px, and 40px control-density recipes for the outer track. Each segment uses the same-size inset recipe at 20px, 28px, and 36px while preserving that density's typography, icon, gap, and label metrics.",
         "Use one consistent content variant across every selectable tab in a group.",
         "Omitted background is for primary and secondary surfaces; pass the faint context explicitly on faint surfaces.",
@@ -120,6 +121,15 @@
           "required": false,
           "mutable": false
         },
+        "hasContainer": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "has-container",
+          "default": "true",
+          "required": false,
+          "mutable": false,
+          "description": "Show the segmented control's outer background, border, and inset."
+        },
         "size": {
           "type": "TabGroupSize",
           "resolvedType": "\"lg\" | \"md\" | \"sm\"",
@@ -189,6 +199,15 @@
         "required": false,
         "mutable": false
       },
+      "hasContainer": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "has-container",
+        "default": "true",
+        "required": false,
+        "mutable": false,
+        "description": "Show the segmented control's outer background, border, and inset."
+      },
       "size": {
         "type": "TabGroupSize",
         "resolvedType": "\"lg\" | \"md\" | \"sm\"",
@@ -282,12 +301,12 @@
   "files": [
     {
       "path": "src/wc/components/TabGroup/TabGroup.css",
-      "content": "@import '../../utils/control-density.css';\n@import '../../utils/control-density-inset.css';\n@import '../../utils/control-width.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/interaction-fill.css';\n@import '../../utils/control-inactive.css';\n\n:host {\n  display: block;\n  --_tab-group-surface-border: var(--color-border-tertiary);\n  --_tab-group-divider: var(--color-border-secondary);\n}\n\n:host(.tab-group-host--on-faint) {\n  --_tab-group-selected-fill: var(--color-interaction-active);\n}\n\n:host(.tab-group-host--on-medium) {\n  --_tab-group-surface-border: var(--color-border-on-medium-background-tertiary);\n  --_tab-group-divider: var(--color-border-on-medium-background-secondary);\n  --_tab-group-selected-fill: var(--color-interaction-on-medium-background-active);\n}\n\n:host(.tab-group-host--on-bold) {\n  --_tab-group-surface-border: var(--color-border-on-bold-background-tertiary);\n  --_tab-group-divider: var(--color-border-on-bold-background-secondary);\n  --_tab-group-selected-fill: var(--color-interaction-on-bold-background-active);\n}\n\n:host(.tab-group-host--on-strong) {\n  --_tab-group-surface-border: var(--color-border-on-strong-background-tertiary);\n  --_tab-group-divider: var(--color-border-on-strong-background-secondary);\n  --_tab-group-selected-fill: var(--color-interaction-on-strong-background-active);\n}\n\n:host(.tab-group-host--on-translucent) {\n  --_tab-group-surface-border: var(--color-translucent-border-tertiary);\n  --_tab-group-divider: var(--color-translucent-border-secondary);\n  --_tab-group-selected-fill: var(--color-translucent-interaction-active);\n}\n\n:host(.tab-group-host--on-inverted) {\n  --_tab-group-surface-border: var(--color-inverted-border-tertiary);\n  --_tab-group-divider: var(--color-inverted-border-secondary);\n  --_tab-group-selected-fill: var(--color-inverted-interaction-active);\n}\n\n:host(.tab-group-host--on-media) {\n  --_tab-group-surface-border: var(--color-media-border-tertiary);\n  --_tab-group-divider: var(--color-media-border-secondary);\n  --_tab-group-selected-fill: var(--color-media-interaction-active);\n}\n\n:host(.tab-group-host--on-always-dark) {\n  --_tab-group-surface-border: var(--color-always-dark-border-tertiary);\n  --_tab-group-divider: var(--color-always-dark-border-secondary);\n  --_tab-group-selected-fill: var(--color-always-dark-interaction-active);\n}\n\n.tab-list {\n  display: flex;\n  align-items: center;\n  gap: var(--ds-control-gap);\n  position: relative;\n  width: max-content;\n  max-width: 100%;\n  height: var(--ds-control-height);\n  padding: calc(var(--dimension-space-025) - var(--dimension-stroke-width-012));\n  background-color: var(--color-background-secondary);\n  border: var(--dimension-stroke-width-012) solid var(--_tab-group-surface-border);\n  border-radius: var(--dimension-radius-half);\n  box-sizing: border-box;\n}\n\n:host(.ds-control-width--fill) .tab-list {\n  width: 100%;\n}\n\n:host(.tab-group-host--surface) .tab-list {\n  background-color: transparent;\n}\n\n.tab {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  gap: var(--ds-control-gap);\n  padding: 0 var(--ds-control-padding-inline);\n  background-color: transparent;\n  border: none;\n  border-radius: var(--dimension-radius-half);\n  cursor: default;\n  -webkit-user-select: none;\n  user-select: none;\n  color: var(--color-foreground-secondary);\n  transition: color var(--effect-motion-short-2);\n  flex-shrink: 0;\n  height: var(--ds-control-height);\n  min-width: var(--ds-control-height);\n  box-sizing: border-box;\n  --_dot: var(--color-foreground-bold-brand);\n  /* Hover/press: `.ds-interaction-fill` fills cover the complete segment. */\n}\n\n:host(.ds-control-width--fill) .tab {\n  flex: 1 1 0;\n  min-width: 0;\n  overflow: hidden;\n}\n\n:host(.ds-control-width--fill) .tab__content {\n  max-width: 100%;\n  overflow: hidden;\n}\n\n:host(.ds-control-width--fill) .tab__label {\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n\n.tab--selected {\n  color: var(--color-foreground-primary);\n  background-color: var(--color-background-primary);\n  /* Inset stroke on interaction-fill ::after — stays above hover wash. */\n  --ds-interaction-border-width: var(--dimension-stroke-width-012);\n  --ds-interaction-border-color: var(--_tab-group-surface-border);\n}\n\n:host(.tab-group-host--surface) .tab--selected {\n  background-color: var(--_tab-group-selected-fill);\n}\n\n.tab--selected:not(.ds-interaction-fill) {\n  box-shadow: inset 0 0 0 var(--ds-interaction-border-width) var(--ds-interaction-border-color);\n}\n\n/* Inactive: `.ds-control-inactive` (50% opacity) — applied via class in TSX. */\n\n.tab__content {\n  position: relative;\n  z-index: 2;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  gap: var(--ds-control-gap);\n  min-width: 0;\n}\n\n.tab__content--dot {\n  padding-right: var(--dimension-space-050);\n}\n\n.tab__label {\n  padding: 0 var(--ds-control-label-inset);\n  white-space: nowrap;\n}\n\n.tab__icon {\n  flex-shrink: 0;\n}\n\n.tab__dot {\n  position: absolute;\n  top: 0;\n  right: 0;\n  z-index: 2;\n  pointer-events: none;\n}\n\n.on-medium {\n  color: var(--color-foreground-on-medium-background-secondary);\n}\n\n.on-medium.tab--selected {\n  color: var(--color-foreground-on-medium-background-primary);\n}\n\n.on-bold {\n  color: var(--color-foreground-on-bold-background-secondary);\n}\n\n.on-bold.tab--selected {\n  color: var(--color-foreground-on-bold-background-primary);\n}\n\n.on-strong {\n  color: var(--color-foreground-on-strong-background-secondary);\n}\n\n.on-strong.tab--selected {\n  color: var(--color-foreground-on-strong-background-primary);\n}\n\n.on-translucent {\n  color: var(--color-translucent-foreground-secondary);\n}\n\n.on-translucent.tab--selected {\n  color: var(--color-translucent-foreground-primary);\n}\n\n.on-inverted {\n  color: var(--color-inverted-foreground-secondary);\n}\n\n.on-inverted.tab--selected {\n  color: var(--color-inverted-foreground-primary);\n}\n\n.on-media {\n  color: var(--color-media-foreground-secondary);\n}\n\n.on-media.tab--selected {\n  color: var(--color-media-foreground-primary);\n}\n\n.on-always-dark {\n  color: var(--color-always-dark-foreground-secondary);\n}\n\n.on-always-dark.tab--selected {\n  color: var(--color-always-dark-foreground-primary);\n}\n\n.tab-divider {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  width: var(--dimension-stroke-width-012);\n  align-self: center;\n  padding: 0;\n  flex-shrink: 0;\n  pointer-events: none;\n}\n\n.tab-divider__line {\n  width: var(--dimension-stroke-width-012);\n  height: var(--typography-lineheight-sm);\n  flex-shrink: 0;\n  background-color: var(--_tab-group-divider);\n}\n",
+      "content": "@import '../../utils/control-density.css';\n@import '../../utils/control-density-inset.css';\n@import '../../utils/control-width.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/interaction-fill.css';\n@import '../../utils/control-inactive.css';\n\n:host {\n  display: block;\n  --_tab-group-surface-border: var(--color-border-tertiary);\n  --_tab-group-divider: var(--color-border-secondary);\n}\n\n:host(.tab-group-host--on-faint) {\n  --_tab-group-selected-fill: var(--color-interaction-active);\n}\n\n:host(.tab-group-host--on-medium) {\n  --_tab-group-surface-border: var(--color-border-on-medium-background-tertiary);\n  --_tab-group-divider: var(--color-border-on-medium-background-secondary);\n  --_tab-group-selected-fill: var(--color-interaction-on-medium-background-active);\n}\n\n:host(.tab-group-host--on-bold) {\n  --_tab-group-surface-border: var(--color-border-on-bold-background-tertiary);\n  --_tab-group-divider: var(--color-border-on-bold-background-secondary);\n  --_tab-group-selected-fill: var(--color-interaction-on-bold-background-active);\n}\n\n:host(.tab-group-host--on-strong) {\n  --_tab-group-surface-border: var(--color-border-on-strong-background-tertiary);\n  --_tab-group-divider: var(--color-border-on-strong-background-secondary);\n  --_tab-group-selected-fill: var(--color-interaction-on-strong-background-active);\n}\n\n:host(.tab-group-host--on-translucent) {\n  --_tab-group-surface-border: var(--color-translucent-border-tertiary);\n  --_tab-group-divider: var(--color-translucent-border-secondary);\n  --_tab-group-selected-fill: var(--color-translucent-interaction-active);\n}\n\n:host(.tab-group-host--on-inverted) {\n  --_tab-group-surface-border: var(--color-inverted-border-tertiary);\n  --_tab-group-divider: var(--color-inverted-border-secondary);\n  --_tab-group-selected-fill: var(--color-inverted-interaction-active);\n}\n\n:host(.tab-group-host--on-media) {\n  --_tab-group-surface-border: var(--color-media-border-tertiary);\n  --_tab-group-divider: var(--color-media-border-secondary);\n  --_tab-group-selected-fill: var(--color-media-interaction-active);\n}\n\n:host(.tab-group-host--on-always-dark) {\n  --_tab-group-surface-border: var(--color-always-dark-border-tertiary);\n  --_tab-group-divider: var(--color-always-dark-border-secondary);\n  --_tab-group-selected-fill: var(--color-always-dark-interaction-active);\n}\n\n.tab-list {\n  display: flex;\n  align-items: center;\n  gap: var(--ds-control-gap);\n  position: relative;\n  width: max-content;\n  max-width: 100%;\n  height: var(--ds-control-height);\n  padding: calc(var(--dimension-space-025) - var(--dimension-stroke-width-012));\n  background-color: var(--color-background-secondary);\n  border: var(--dimension-stroke-width-012) solid var(--_tab-group-surface-border);\n  border-radius: var(--dimension-radius-half);\n  box-sizing: border-box;\n}\n\n:host(.ds-control-width--fill) .tab-list {\n  width: 100%;\n}\n\n:host(.tab-group-host--surface) .tab-list {\n  background-color: transparent;\n}\n\n:host(.tab-group-host--containerless) .tab-list {\n  padding: 0;\n  border: 0;\n  background-color: transparent;\n}\n\n.tab {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  gap: var(--ds-control-gap);\n  padding: 0 var(--ds-control-padding-inline);\n  background-color: transparent;\n  border: none;\n  border-radius: var(--dimension-radius-half);\n  cursor: default;\n  -webkit-user-select: none;\n  user-select: none;\n  color: var(--color-foreground-secondary);\n  transition: color var(--effect-motion-short-2);\n  flex-shrink: 0;\n  height: var(--ds-control-height);\n  min-width: var(--ds-control-height);\n  box-sizing: border-box;\n  --_dot: var(--color-foreground-bold-brand);\n  /* Hover/press: `.ds-interaction-fill` fills cover the complete segment. */\n}\n\n:host(.ds-control-width--fill) .tab {\n  flex: 1 1 0;\n  min-width: 0;\n  overflow: hidden;\n}\n\n:host(.ds-control-width--fill) .tab__content {\n  max-width: 100%;\n  overflow: hidden;\n}\n\n:host(.ds-control-width--fill) .tab__label {\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n\n.tab--selected {\n  color: var(--color-foreground-primary);\n  background-color: var(--color-background-primary);\n  /* Inset stroke on interaction-fill ::after — stays above hover wash. */\n  --ds-interaction-border-width: var(--dimension-stroke-width-012);\n  --ds-interaction-border-color: var(--_tab-group-surface-border);\n}\n\n:host(.tab-group-host--surface) .tab--selected {\n  background-color: var(--_tab-group-selected-fill);\n}\n\n.tab--selected:not(.ds-interaction-fill) {\n  box-shadow: inset 0 0 0 var(--ds-interaction-border-width) var(--ds-interaction-border-color);\n}\n\n/* Inactive: `.ds-control-inactive` (50% opacity) — applied via class in TSX. */\n\n.tab__content {\n  position: relative;\n  z-index: 2;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  gap: var(--ds-control-gap);\n  min-width: 0;\n}\n\n.tab__content--dot {\n  padding-right: var(--dimension-space-050);\n}\n\n.tab__label {\n  padding: 0 var(--ds-control-label-inset);\n  white-space: nowrap;\n}\n\n.tab__icon {\n  flex-shrink: 0;\n}\n\n.tab__dot {\n  position: absolute;\n  top: 0;\n  right: 0;\n  z-index: 2;\n  pointer-events: none;\n}\n\n.on-medium {\n  color: var(--color-foreground-on-medium-background-secondary);\n}\n\n.on-medium.tab--selected {\n  color: var(--color-foreground-on-medium-background-primary);\n}\n\n.on-bold {\n  color: var(--color-foreground-on-bold-background-secondary);\n}\n\n.on-bold.tab--selected {\n  color: var(--color-foreground-on-bold-background-primary);\n}\n\n.on-strong {\n  color: var(--color-foreground-on-strong-background-secondary);\n}\n\n.on-strong.tab--selected {\n  color: var(--color-foreground-on-strong-background-primary);\n}\n\n.on-translucent {\n  color: var(--color-translucent-foreground-secondary);\n}\n\n.on-translucent.tab--selected {\n  color: var(--color-translucent-foreground-primary);\n}\n\n.on-inverted {\n  color: var(--color-inverted-foreground-secondary);\n}\n\n.on-inverted.tab--selected {\n  color: var(--color-inverted-foreground-primary);\n}\n\n.on-media {\n  color: var(--color-media-foreground-secondary);\n}\n\n.on-media.tab--selected {\n  color: var(--color-media-foreground-primary);\n}\n\n.on-always-dark {\n  color: var(--color-always-dark-foreground-secondary);\n}\n\n.on-always-dark.tab--selected {\n  color: var(--color-always-dark-foreground-primary);\n}\n\n.tab-divider {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  width: var(--dimension-stroke-width-012);\n  align-self: center;\n  padding: 0;\n  flex-shrink: 0;\n  pointer-events: none;\n}\n\n.tab-divider__line {\n  width: var(--dimension-stroke-width-012);\n  height: var(--typography-lineheight-sm);\n  flex-shrink: 0;\n  background-color: var(--_tab-group-divider);\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/TabGroup/TabGroup.tsx",
-      "content": "import {\n  Component,\n  Prop,\n  Event,\n  EventEmitter,\n  Element,\n  Listen,\n  Watch,\n  h,\n  Host,\n} from '@stencil/core';\nimport { controlWidthClass, CONTROL_TEXT_VARIANT, type ControlWidth } from '../../utils';\nimport {\n  getSelectableTabs,\n  isTabDivider,\n  type TabGroupItem,\n  type TabItemTab,\n} from './tab-item-utils';\n\nexport type TabBackground =\n  | 'faint'\n  | 'medium'\n  | 'bold'\n  | 'strong'\n  | 'translucent'\n  | 'inverted'\n  | 'media'\n  | 'always-dark';\n\nexport type TabGroupSize = 'sm' | 'md' | 'lg';\nexport type TabGroupWidth = ControlWidth;\n\n@Component({\n  tag: 'ds-tab-group',\n  styleUrl: 'TabGroup.css',\n  scoped: true,\n})\nexport class TabGroup {\n  @Element() el!: HTMLElement;\n\n  @Prop({ mutable: true }) value: string = '';\n  @Prop() tabs: TabGroupItem[] = [];\n  /** Control density: 24px small, 32px medium, or 40px large track. */\n  @Prop() size: TabGroupSize = 'md';\n  /** Width fit — hug content (default) or fill the parent with equal-width segments. */\n  @Prop() width: TabGroupWidth = 'hug';\n  @Prop() background: TabBackground | undefined;\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  @Prop({ attribute: 'aria-labelledby' }) ariaLabelledby: string | undefined;\n\n  @Event() dsChange!: EventEmitter<string>;\n\n  private get selectableTabs(): TabItemTab[] {\n    return getSelectableTabs(this.tabs);\n  }\n\n  private get focusableTabId(): string {\n    return this.selectableTabs.some(tab => tab.id === this.value && !tab.isInactive)\n      ? this.value\n      : (this.selectableTabs.find(tab => !tab.isInactive)?.id ?? '');\n  }\n\n  private selectTab(id: string, options?: { focus?: boolean }) {\n    this.value = id;\n    this.dsChange.emit(id);\n    if (options?.focus !== false) {\n      this.focusTab(id);\n    }\n  }\n\n  private focusTab(id: string) {\n    const btn = this.el.querySelector(`[data-tab-id=\"${id}\"]`) as HTMLElement | null;\n    btn?.focus({ preventScroll: true });\n  }\n\n  /** Keep focus on the selected tab when value changes externally (e.g. BarNav menu). */\n  @Watch('value')\n  onValueChange(next: string, prev: string | undefined) {\n    if (prev === undefined || next === prev) return;\n\n    requestAnimationFrame(() => {\n      const active = document.activeElement as HTMLElement | null;\n      if (!active || !this.el.contains(active)) return;\n\n      const activeId = active.getAttribute('data-tab-id');\n      if (activeId === next) return;\n\n      const focusId = this.selectableTabs.some(tab => tab.id === next && !tab.isInactive)\n        ? next\n        : this.focusableTabId;\n      const nextTab = this.el.querySelector(`[data-tab-id=\"${focusId}\"]`) as HTMLElement | null;\n      if (nextTab) {\n        nextTab.focus({ preventScroll: true });\n      } else {\n        active.blur();\n      }\n    });\n  }\n\n  /**\n   * Find the next non-inactive tab index relative to `from`, stepping by `step`.\n   * Returns `from` unchanged if no other enabled tab exists.\n   */\n  private findEnabled(from: number, step: 1 | -1): number {\n    const tabs = this.selectableTabs;\n    const len = tabs.length;\n    for (let n = 0; n < len; n++) {\n      const i = (from + step * (n + 1) + len * (n + 1)) % len;\n      if (!tabs[i]?.isInactive) return i;\n    }\n    return from;\n  }\n\n  @Listen('keydown')\n  handleKeyDown(e: KeyboardEvent) {\n    const tabs = this.selectableTabs;\n    if (!tabs.length) return;\n\n    const focusedId = (e.target as Element | null)?.closest<HTMLElement>('[data-tab-id]')?.dataset[\n      'tabId'\n    ];\n    const currentIdx = tabs.findIndex(t => t.id === (focusedId ?? this.focusableTabId));\n\n    let nextIdx: number | null = null;\n\n    if (e.key === 'ArrowRight') {\n      nextIdx = this.findEnabled(currentIdx, 1);\n    } else if (e.key === 'ArrowLeft') {\n      nextIdx = this.findEnabled(currentIdx, -1);\n    }\n\n    if (e.key === 'Home') {\n      const first = tabs.findIndex(t => !t.isInactive);\n      nextIdx = first === -1 ? null : first;\n    } else if (e.key === 'End') {\n      const lastEnabled = [...tabs].reverse().findIndex(t => !t.isInactive);\n      nextIdx = lastEnabled === -1 ? null : tabs.length - 1 - lastEnabled;\n    }\n\n    if (nextIdx !== null) {\n      e.preventDefault();\n      const next = tabs[nextIdx];\n      this.selectTab(next.id);\n    }\n  }\n\n  private getBgClass(): string {\n    if (!this.background) return '';\n    if (this.background === 'always-dark') return 'on-always-dark';\n    return `on-${this.background}`;\n  }\n\n  render() {\n    const bgClass = this.getBgClass();\n    const focusableTabId = this.focusableTabId;\n\n    return (\n      <Host\n        class={{\n          'tab-group-host': true,\n          [`tab-group-host--${this.size}`]: true,\n          [`ds-control--${this.size}`]: true,\n          'tab-group-host--surface': !!bgClass,\n          [`tab-group-host--${bgClass}`]: !!bgClass,\n          ...controlWidthClass(this.width),\n        }}\n      >\n        <div\n          role=\"tablist\"\n          class=\"tab-list\"\n          aria-label={this.ariaLabel}\n          aria-labelledby={this.ariaLabelledby}\n        >\n          {this.tabs.map((tab, index) => {\n            if (isTabDivider(tab)) {\n              return (\n                <div key={`divider-${index}`} class=\"tab-divider\" aria-hidden=\"true\">\n                  <div class=\"tab-divider__line\" />\n                </div>\n              );\n            }\n\n            const isSelected = tab.id === this.value;\n            const variant = tab.variant ?? 'label';\n            const showIcon = variant === 'icon' || variant === 'icon-label';\n            const showLabel = variant === 'label' || variant === 'icon-label';\n            const emphasizeLabel = isSelected && !bgClass;\n            return (\n              <button\n                key={tab.id}\n                type=\"button\"\n                role=\"tab\"\n                data-tab-id={tab.id}\n                class={{\n                  tab: true,\n                  'tab--selected': isSelected,\n                  [`ds-control--${this.size}`]: true,\n                  'ds-control--inset': true,\n                  'ds-focus-ring-inset': true,\n                  'ds-interaction-fill': !tab.isInactive,\n                  'ds-interaction-fill--on-faint': bgClass === 'on-faint',\n                  'ds-interaction-fill--on-medium': bgClass === 'on-medium',\n                  'ds-interaction-fill--on-bold': bgClass === 'on-bold',\n                  'ds-interaction-fill--on-strong': bgClass === 'on-strong',\n                  'ds-interaction-fill--on-translucent': bgClass === 'on-translucent',\n                  'ds-interaction-fill--on-inverted': bgClass === 'on-inverted',\n                  'ds-interaction-fill--on-media': bgClass === 'on-media',\n                  'ds-interaction-fill--on-always-dark': bgClass === 'on-always-dark',\n                  'ds-control-inactive': !!tab.isInactive,\n                  [bgClass]: !!bgClass,\n                }}\n                aria-label={variant === 'icon' ? tab.label : undefined}\n                aria-selected={String(isSelected)}\n                aria-disabled={tab.isInactive ? 'true' : undefined}\n                aria-controls={tab.panelId ?? undefined}\n                disabled={tab.isInactive}\n                tabIndex={tab.id === focusableTabId ? 0 : -1}\n                onClick={() => !tab.isInactive && this.selectTab(tab.id)}\n              >\n                <span\n                  class={{\n                    tab__content: true,\n                    [`tab__content--${variant}`]: true,\n                    'tab__content--dot': !!tab.dot,\n                  }}\n                >\n                  {showIcon && (\n                    <ds-icon class=\"tab__icon\" name={tab.icon} size={this.size} color=\"inherit\" />\n                  )}\n                  {showLabel && (\n                    <ds-text\n                      class=\"tab__label\"\n                      as=\"span\"\n                      variant={CONTROL_TEXT_VARIANT[this.size]}\n                      emphasis={emphasizeLabel}\n                      color=\"inherit\"\n                    >\n                      {tab.label}\n                    </ds-text>\n                  )}\n                  {tab.dot && (\n                    <ds-badge\n                      class=\"tab__dot\"\n                      variant=\"dot\"\n                      hasRing={false}\n                      label=\"\"\n                      aria-hidden=\"true\"\n                    />\n                  )}\n                </span>\n              </button>\n            );\n          })}\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import {\n  Component,\n  Prop,\n  Event,\n  EventEmitter,\n  Element,\n  Listen,\n  Watch,\n  h,\n  Host,\n} from '@stencil/core';\nimport { controlWidthClass, CONTROL_TEXT_VARIANT, type ControlWidth } from '../../utils';\nimport {\n  getSelectableTabs,\n  isTabDivider,\n  type TabGroupItem,\n  type TabItemTab,\n} from './tab-item-utils';\n\nexport type TabBackground =\n  | 'faint'\n  | 'medium'\n  | 'bold'\n  | 'strong'\n  | 'translucent'\n  | 'inverted'\n  | 'media'\n  | 'always-dark';\n\nexport type TabGroupSize = 'sm' | 'md' | 'lg';\nexport type TabGroupWidth = ControlWidth;\n\n@Component({\n  tag: 'ds-tab-group',\n  styleUrl: 'TabGroup.css',\n  scoped: true,\n})\nexport class TabGroup {\n  @Element() el!: HTMLElement;\n\n  @Prop({ mutable: true }) value: string = '';\n  @Prop() tabs: TabGroupItem[] = [];\n  /** Control density: 24px small, 32px medium, or 40px large track. */\n  @Prop() size: TabGroupSize = 'md';\n  /** Width fit — hug content (default) or fill the parent with equal-width segments. */\n  @Prop() width: TabGroupWidth = 'hug';\n  /** Show the segmented control's outer background, border, and inset. */\n  @Prop() hasContainer: boolean = true;\n  @Prop() background: TabBackground | undefined;\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  @Prop({ attribute: 'aria-labelledby' }) ariaLabelledby: string | undefined;\n\n  @Event() dsChange!: EventEmitter<string>;\n\n  private get selectableTabs(): TabItemTab[] {\n    return getSelectableTabs(this.tabs);\n  }\n\n  private get focusableTabId(): string {\n    return this.selectableTabs.some(tab => tab.id === this.value && !tab.isInactive)\n      ? this.value\n      : (this.selectableTabs.find(tab => !tab.isInactive)?.id ?? '');\n  }\n\n  private selectTab(id: string, options?: { focus?: boolean }) {\n    this.value = id;\n    this.dsChange.emit(id);\n    if (options?.focus !== false) {\n      this.focusTab(id);\n    }\n  }\n\n  private focusTab(id: string) {\n    const btn = this.el.querySelector(`[data-tab-id=\"${id}\"]`) as HTMLElement | null;\n    btn?.focus({ preventScroll: true });\n  }\n\n  /** Keep focus on the selected tab when value changes externally (e.g. BarNav menu). */\n  @Watch('value')\n  onValueChange(next: string, prev: string | undefined) {\n    if (prev === undefined || next === prev) return;\n\n    requestAnimationFrame(() => {\n      const active = document.activeElement as HTMLElement | null;\n      if (!active || !this.el.contains(active)) return;\n\n      const activeId = active.getAttribute('data-tab-id');\n      if (activeId === next) return;\n\n      const focusId = this.selectableTabs.some(tab => tab.id === next && !tab.isInactive)\n        ? next\n        : this.focusableTabId;\n      const nextTab = this.el.querySelector(`[data-tab-id=\"${focusId}\"]`) as HTMLElement | null;\n      if (nextTab) {\n        nextTab.focus({ preventScroll: true });\n      } else {\n        active.blur();\n      }\n    });\n  }\n\n  /**\n   * Find the next non-inactive tab index relative to `from`, stepping by `step`.\n   * Returns `from` unchanged if no other enabled tab exists.\n   */\n  private findEnabled(from: number, step: 1 | -1): number {\n    const tabs = this.selectableTabs;\n    const len = tabs.length;\n    for (let n = 0; n < len; n++) {\n      const i = (from + step * (n + 1) + len * (n + 1)) % len;\n      if (!tabs[i]?.isInactive) return i;\n    }\n    return from;\n  }\n\n  @Listen('keydown')\n  handleKeyDown(e: KeyboardEvent) {\n    const tabs = this.selectableTabs;\n    if (!tabs.length) return;\n\n    const focusedId = (e.target as Element | null)?.closest<HTMLElement>('[data-tab-id]')?.dataset[\n      'tabId'\n    ];\n    const currentIdx = tabs.findIndex(t => t.id === (focusedId ?? this.focusableTabId));\n\n    let nextIdx: number | null = null;\n\n    if (e.key === 'ArrowRight') {\n      nextIdx = this.findEnabled(currentIdx, 1);\n    } else if (e.key === 'ArrowLeft') {\n      nextIdx = this.findEnabled(currentIdx, -1);\n    }\n\n    if (e.key === 'Home') {\n      const first = tabs.findIndex(t => !t.isInactive);\n      nextIdx = first === -1 ? null : first;\n    } else if (e.key === 'End') {\n      const lastEnabled = [...tabs].reverse().findIndex(t => !t.isInactive);\n      nextIdx = lastEnabled === -1 ? null : tabs.length - 1 - lastEnabled;\n    }\n\n    if (nextIdx !== null) {\n      e.preventDefault();\n      const next = tabs[nextIdx];\n      this.selectTab(next.id);\n    }\n  }\n\n  private getBgClass(): string {\n    if (!this.background) return '';\n    if (this.background === 'always-dark') return 'on-always-dark';\n    return `on-${this.background}`;\n  }\n\n  render() {\n    const bgClass = this.getBgClass();\n    const focusableTabId = this.focusableTabId;\n\n    return (\n      <Host\n        class={{\n          'tab-group-host': true,\n          [`tab-group-host--${this.size}`]: true,\n          [`ds-control--${this.size}`]: true,\n          'tab-group-host--containerless': !this.hasContainer,\n          'tab-group-host--surface': !!bgClass,\n          [`tab-group-host--${bgClass}`]: !!bgClass,\n          ...controlWidthClass(this.width),\n        }}\n      >\n        <div\n          role=\"tablist\"\n          class=\"tab-list\"\n          aria-label={this.ariaLabel}\n          aria-labelledby={this.ariaLabelledby}\n        >\n          {this.tabs.map((tab, index) => {\n            if (isTabDivider(tab)) {\n              return (\n                <div key={`divider-${index}`} class=\"tab-divider\" aria-hidden=\"true\">\n                  <div class=\"tab-divider__line\" />\n                </div>\n              );\n            }\n\n            const isSelected = tab.id === this.value;\n            const variant = tab.variant ?? 'label';\n            const showIcon = variant === 'icon' || variant === 'icon-label';\n            const showLabel = variant === 'label' || variant === 'icon-label';\n            const emphasizeLabel = isSelected && !bgClass;\n            return (\n              <button\n                key={tab.id}\n                type=\"button\"\n                role=\"tab\"\n                data-tab-id={tab.id}\n                class={{\n                  tab: true,\n                  'tab--selected': isSelected,\n                  [`ds-control--${this.size}`]: true,\n                  'ds-control--inset': true,\n                  'ds-focus-ring-inset': true,\n                  'ds-interaction-fill': !tab.isInactive,\n                  'ds-interaction-fill--on-faint': bgClass === 'on-faint',\n                  'ds-interaction-fill--on-medium': bgClass === 'on-medium',\n                  'ds-interaction-fill--on-bold': bgClass === 'on-bold',\n                  'ds-interaction-fill--on-strong': bgClass === 'on-strong',\n                  'ds-interaction-fill--on-translucent': bgClass === 'on-translucent',\n                  'ds-interaction-fill--on-inverted': bgClass === 'on-inverted',\n                  'ds-interaction-fill--on-media': bgClass === 'on-media',\n                  'ds-interaction-fill--on-always-dark': bgClass === 'on-always-dark',\n                  'ds-control-inactive': !!tab.isInactive,\n                  [bgClass]: !!bgClass,\n                }}\n                aria-label={variant === 'icon' ? tab.label : undefined}\n                aria-selected={String(isSelected)}\n                aria-disabled={tab.isInactive ? 'true' : undefined}\n                aria-controls={tab.panelId ?? undefined}\n                disabled={tab.isInactive}\n                tabIndex={tab.id === focusableTabId ? 0 : -1}\n                onClick={() => !tab.isInactive && this.selectTab(tab.id)}\n              >\n                <span\n                  class={{\n                    tab__content: true,\n                    [`tab__content--${variant}`]: true,\n                    'tab__content--dot': !!tab.dot,\n                  }}\n                >\n                  {showIcon && (\n                    <ds-icon class=\"tab__icon\" name={tab.icon} size={this.size} color=\"inherit\" />\n                  )}\n                  {showLabel && (\n                    <ds-text\n                      class=\"tab__label\"\n                      as=\"span\"\n                      variant={CONTROL_TEXT_VARIANT[this.size]}\n                      emphasis={emphasizeLabel}\n                      color=\"inherit\"\n                    >\n                      {tab.label}\n                    </ds-text>\n                  )}\n                  {tab.dot && (\n                    <ds-badge\n                      class=\"tab__dot\"\n                      variant=\"dot\"\n                      hasRing={false}\n                      label=\"\"\n                      aria-hidden=\"true\"\n                    />\n                  )}\n                </span>\n              </button>\n            );\n          })}\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {

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

@@ -2,7 +2,7 @@
   "$schema": "https://ui.shadcn.com/schema/registry-item.json",
   "name": "table-filter",
   "title": "TableFilter",
-  "description": "Standard table-toolbar Filter control that owns the shared trigger, filter menu UI, accessible defaults, and compact-caption behavior while the application controls data and values.",
+  "description": "Standard table-toolbar Filter control that owns the shared trigger, searchable non-date filter options, accessible defaults, and compact-caption behavior while the application controls data and values.",
   "type": "registry:ui",
   "meta": {
     "library": "@ds-mo/ui",
@@ -13,7 +13,7 @@
     "intent": {
       "audience": "general",
       "status": "stable",
-      "summary": "Standard table-toolbar Filter control that owns the shared trigger, filter menu UI, accessible defaults, and compact-caption behavior while the application controls data and values.",
+      "summary": "Standard table-toolbar Filter control that owns the shared trigger, searchable non-date filter options, accessible defaults, and compact-caption behavior while the application controls data and values.",
       "useWhen": [
         "A table toolbar should expose the standard singular Filter control and shared filter-menu interaction.",
         "A product supplies filter definitions and controlled values but should not recreate the toolbar trigger, category navigation, or responsive treatment."
@@ -43,12 +43,14 @@
       "accessibility": [
         "The trigger is an icon-label combobox named Filter table unless a product aria-label supplies the table context. Compact caption widths preserve that accessible name after the visible label and chevron are omitted.",
         "The popup retains ds-filter-menu category navigation, option semantics, focus entry, dismissal, and focus return, and aligns its start edge with the trigger.",
-        "Localize label, menuLabel, categoriesLabel, and clearLabel together so visible and accessible wording remains consistent."
+        "Localize label, menuLabel, categoriesLabel, clearLabel, searchPlaceholder, and noResultsText together so visible and accessible wording remains consistent."
       ],
       "states": [
-        "filters, values, and activeFilterId are controlled. dsChange, dsClear, and dsActiveFilterChange report intent without changing those inputs; the application applies query consequences and returns replacement values.",
+        "filters, values, matchModes, and activeFilterId are controlled. dsChange, dsMatchModeChange, dsClear, and dsActiveFilterChange report intent without changing those inputs; the application applies query consequences and returns replacement values.",
         "The visible trigger label stays singular Filter without appending an active-count suffix. Active criteria promote only the visible label from secondary to primary, matching the other table caption controls without redefining generic button active semantics.",
         "The popup reserves a visually empty footer row inside the category pane for every state. Active criteria reveal its divider and only a left-aligned Clear action, without adding popup height or showing redundant selected-count copy; the option pane retains its full column.",
+        "Every multiple-choice category exposes a right-pane footer where the blue any or all word toggles its controlled match mode. any is the default OR mode; the application applies the requested mode to its query.",
+        "Every non-date category exposes a 40px secondary-background search header that filters its displayed option labels and descriptions without changing controlled filter values. Date retains only its Relative and Range header.",
         "Date categories use the shared compact-header Range and Relative experience. Persist relative values semantically and resolve them from the product's current date whenever rows or saved views are applied.",
         "Popup visibility follows the same mutable open and dsOpenChange contract as ds-filter-menu."
       ],
@@ -58,13 +60,13 @@
       ],
       "frameworkCaveats": {
         "customElements": [
-          "Assign filters, values, and activeFilterId as JavaScript properties. Replace controlled values in response to dsChange and dsClear."
+          "Assign filters, values, matchModes, and activeFilterId as JavaScript properties. Replace controlled values and modes in response to dsChange, dsMatchModeChange, and dsClear."
         ],
         "react": [
-          "Keep filters and values in application state and replace values from the typed dsChange and dsClear events."
+          "Keep filters, values, and matchModes in application state and replace them from the typed dsChange, dsMatchModeChange, and dsClear events."
         ],
         "angular": [
-          "Import the generated DsTableFilter adapter, bind filters and values, and handle dsChange, dsClear, and dsActiveFilterChange."
+          "Import the generated DsTableFilter adapter, bind filters, values, and matchModes, and handle dsChange, dsMatchModeChange, dsClear, and dsActiveFilterChange."
         ]
       },
       "references": [
@@ -132,6 +134,14 @@
           "mutable": false,
           "description": "Visible trigger label."
         },
+        "matchModes": {
+          "type": "FilterMenuMatchModes",
+          "resolvedType": "{ [x: string]: FilterMenuMatchMode | undefined; }",
+          "default": "{}",
+          "required": false,
+          "mutable": false,
+          "description": "Controlled any/all match mode keyed by multiple-choice filter id. Defaults to any."
+        },
         "menuLabel": {
           "type": "string | null",
           "resolvedType": "null | string",
@@ -141,6 +151,15 @@
           "mutable": false,
           "description": "Accessible name for the non-modal filter dialog. Defaults to the trigger name."
         },
+        "noResultsText": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "no-results-text",
+          "default": "'No results'",
+          "required": false,
+          "mutable": false,
+          "description": "Empty-state text shown when an option search has no matches."
+        },
         "open": {
           "type": "boolean",
           "resolvedType": "boolean",
@@ -150,6 +169,15 @@
           "mutable": true,
           "description": "Controlled popup visibility."
         },
+        "searchPlaceholder": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "search-placeholder",
+          "default": "'Search'",
+          "required": false,
+          "mutable": false,
+          "description": "Placeholder shown in each non-date option search header."
+        },
         "values": {
           "type": "FilterMenuValues",
           "resolvedType": "{ [x: string]: FilterMenuValue | undefined; }",
@@ -200,6 +228,14 @@
           "composed": true,
           "description": "Requests that the controlled popup close."
         },
+        {
+          "name": "dsMatchModeChange",
+          "detail": "FilterMenuMatchModeChangeDetail",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true,
+          "description": "Requests a controlled any/all mode replacement for a multiple-choice filter."
+        },
         {
           "name": "dsOpenChange",
           "detail": "boolean",
@@ -265,6 +301,14 @@
         "mutable": false,
         "description": "Visible trigger label."
       },
+      "matchModes": {
+        "type": "FilterMenuMatchModes",
+        "resolvedType": "{ [x: string]: FilterMenuMatchMode | undefined; }",
+        "default": "{}",
+        "required": false,
+        "mutable": false,
+        "description": "Controlled any/all match mode keyed by multiple-choice filter id. Defaults to any."
+      },
       "menuLabel": {
         "type": "string | null",
         "resolvedType": "null | string",
@@ -274,6 +318,15 @@
         "mutable": false,
         "description": "Accessible name for the non-modal filter dialog. Defaults to the trigger name."
       },
+      "noResultsText": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "no-results-text",
+        "default": "'No results'",
+        "required": false,
+        "mutable": false,
+        "description": "Empty-state text shown when an option search has no matches."
+      },
       "open": {
         "type": "boolean",
         "resolvedType": "boolean",
@@ -283,6 +336,15 @@
         "mutable": true,
         "description": "Controlled popup visibility."
       },
+      "searchPlaceholder": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "search-placeholder",
+        "default": "'Search'",
+        "required": false,
+        "mutable": false,
+        "description": "Placeholder shown in each non-date option search header."
+      },
       "values": {
         "type": "FilterMenuValues",
         "resolvedType": "{ [x: string]: FilterMenuValue | undefined; }",
@@ -333,6 +395,14 @@
         "composed": true,
         "description": "Requests that the controlled popup close."
       },
+      {
+        "name": "dsMatchModeChange",
+        "detail": "FilterMenuMatchModeChangeDetail",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true,
+        "description": "Requests a controlled any/all mode replacement for a multiple-choice filter."
+      },
       {
         "name": "dsOpenChange",
         "detail": "boolean",
@@ -369,7 +439,7 @@
         "import": "import { DsTableFilter } from '@ds-mo/ui/angular/ds-table-filter';",
         "example": "<ds-table-filter></ds-table-filter>"
       },
-      "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: filters, values.",
+      "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: filters, matchModes, values.",
       "peerDependencies": {
         "required": [
           "@ds-mo/tokens ^6.5.0",
@@ -394,7 +464,7 @@
     },
     {
       "path": "src/wc/components/TableFilter/TableFilter.tsx",
-      "content": "import { Component, Event, EventEmitter, h, Host, Prop } from '@stencil/core';\nimport type {\n  FilterMenuChangeDetail,\n  FilterMenuFilter,\n  FilterMenuValues,\n} from '../FilterMenu/FilterMenu';\n\n@Component({\n  tag: 'ds-table-filter',\n  styleUrl: 'TableFilter.css',\n  scoped: true,\n})\nexport class TableFilter {\n  /** Controlled popup visibility. */\n  @Prop({ mutable: true }) open: boolean = false;\n  /** Product-owned filter categories and option definitions. */\n  @Prop() filters: FilterMenuFilter[] = [];\n  /** Controlled values keyed by filter id. */\n  @Prop() values: FilterMenuValues = {};\n  /** Controlled category shown in the option pane. */\n  @Prop() activeFilterId: string | undefined;\n  /** Visible trigger label. */\n  @Prop() label: string = 'Filter';\n  /** Accessible name for the trigger. Defaults to Filter table. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  /** Accessible name for the non-modal filter dialog. Defaults to the trigger name. */\n  @Prop() menuLabel: string | null = null;\n  /** Accessible name for the category tab list. */\n  @Prop() categoriesLabel: string = 'Filter categories';\n  /** Footer action and date-clear accessible label. */\n  @Prop() clearLabel: string = 'Clear';\n\n  /** Requests a controlled value replacement without closing the popup. */\n  @Event() dsChange!: EventEmitter<FilterMenuChangeDetail>;\n  /** Requests that the consumer clear every filter value. */\n  @Event() dsClear!: EventEmitter<void>;\n  /** Requests a controlled active-category replacement. */\n  @Event() dsActiveFilterChange!: EventEmitter<string>;\n  /** Requests that the controlled popup close. */\n  @Event() dsClose!: EventEmitter<void>;\n  /** Emitted whenever trigger activation changes popup visibility. */\n  @Event() dsOpenChange!: EventEmitter<boolean>;\n  /** Emitted after exit motion and rendered popup removal complete. */\n  @Event() dsAfterClose!: EventEmitter<void>;\n\n  render() {\n    const name = this.ariaLabel?.trim() || 'Filter table';\n    const menuName = this.menuLabel?.trim() || name;\n\n    return (\n      <Host>\n        <ds-filter-menu\n          open={this.open}\n          triggerLabel={this.label}\n          showSelectedCount={false}\n          icon=\"Filters\"\n          size=\"md\"\n          width=\"hug\"\n          hasBorder={true}\n          activeFill={false}\n          collapseLabel={true}\n          align=\"start\"\n          aria-label={name}\n          filters={this.filters}\n          values={this.values}\n          activeFilterId={this.activeFilterId}\n          menuLabel={menuName}\n          categoriesLabel={this.categoriesLabel}\n          clearLabel={this.clearLabel}\n          footerLayout=\"categories-clear\"\n          onDsChange={event => this.forward(event, this.dsChange)}\n          onDsClear={event => this.forward(event, this.dsClear)}\n          onDsActiveFilterChange={event => this.forward(event, this.dsActiveFilterChange)}\n          onDsClose={event => this.forward(event, this.dsClose)}\n          onDsOpenChange={event => {\n            event.stopPropagation();\n            this.open = event.detail;\n            this.dsOpenChange.emit(event.detail);\n          }}\n          onDsAfterClose={event => this.forward(event, this.dsAfterClose)}\n        />\n      </Host>\n    );\n  }\n\n  private forward<T>(event: CustomEvent<T>, emitter: EventEmitter<T>): void {\n    event.stopPropagation();\n    emitter.emit(event.detail);\n  }\n}\n",
+      "content": "import { Component, Event, EventEmitter, h, Host, Prop } from '@stencil/core';\nimport type {\n  FilterMenuChangeDetail,\n  FilterMenuFilter,\n  FilterMenuMatchModeChangeDetail,\n  FilterMenuMatchModes,\n  FilterMenuValues,\n} from '../FilterMenu/FilterMenu';\n\n@Component({\n  tag: 'ds-table-filter',\n  styleUrl: 'TableFilter.css',\n  scoped: true,\n})\nexport class TableFilter {\n  /** Controlled popup visibility. */\n  @Prop({ mutable: true }) open: boolean = false;\n  /** Product-owned filter categories and option definitions. */\n  @Prop() filters: FilterMenuFilter[] = [];\n  /** Controlled values keyed by filter id. */\n  @Prop() values: FilterMenuValues = {};\n  /** Controlled any/all match mode keyed by multiple-choice filter id. Defaults to any. */\n  @Prop() matchModes: FilterMenuMatchModes = {};\n  /** Controlled category shown in the option pane. */\n  @Prop() activeFilterId: string | undefined;\n  /** Visible trigger label. */\n  @Prop() label: string = 'Filter';\n  /** Accessible name for the trigger. Defaults to Filter table. */\n  @Prop({ attribute: 'aria-label' }) ariaLabel: string | null = null;\n  /** Accessible name for the non-modal filter dialog. Defaults to the trigger name. */\n  @Prop() menuLabel: string | null = null;\n  /** Accessible name for the category tab list. */\n  @Prop() categoriesLabel: string = 'Filter categories';\n  /** Footer action and date-clear accessible label. */\n  @Prop() clearLabel: string = 'Clear';\n  /** Placeholder shown in each non-date option search header. */\n  @Prop() searchPlaceholder: string = 'Search';\n  /** Empty-state text shown when an option search has no matches. */\n  @Prop() noResultsText: string = 'No results';\n\n  /** Requests a controlled value replacement without closing the popup. */\n  @Event() dsChange!: EventEmitter<FilterMenuChangeDetail>;\n  /** Requests that the consumer clear every filter value. */\n  @Event() dsClear!: EventEmitter<void>;\n  /** Requests a controlled any/all mode replacement for a multiple-choice filter. */\n  @Event() dsMatchModeChange!: EventEmitter<FilterMenuMatchModeChangeDetail>;\n  /** Requests a controlled active-category replacement. */\n  @Event() dsActiveFilterChange!: EventEmitter<string>;\n  /** Requests that the controlled popup close. */\n  @Event() dsClose!: EventEmitter<void>;\n  /** Emitted whenever trigger activation changes popup visibility. */\n  @Event() dsOpenChange!: EventEmitter<boolean>;\n  /** Emitted after exit motion and rendered popup removal complete. */\n  @Event() dsAfterClose!: EventEmitter<void>;\n\n  render() {\n    const name = this.ariaLabel?.trim() || 'Filter table';\n    const menuName = this.menuLabel?.trim() || name;\n\n    return (\n      <Host>\n        <ds-filter-menu\n          open={this.open}\n          triggerLabel={this.label}\n          showSelectedCount={false}\n          icon=\"Filters\"\n          size=\"md\"\n          width=\"hug\"\n          hasBorder={true}\n          activeFill={false}\n          collapseLabel={true}\n          align=\"start\"\n          aria-label={name}\n          filters={this.filters}\n          values={this.values}\n          matchModes={this.matchModes}\n          activeFilterId={this.activeFilterId}\n          menuLabel={menuName}\n          categoriesLabel={this.categoriesLabel}\n          clearLabel={this.clearLabel}\n          searchPlaceholder={this.searchPlaceholder}\n          noResultsText={this.noResultsText}\n          footerLayout=\"categories-clear\"\n          onDsChange={event => this.forward(event, this.dsChange)}\n          onDsClear={event => this.forward(event, this.dsClear)}\n          onDsMatchModeChange={event => this.forward(event, this.dsMatchModeChange)}\n          onDsActiveFilterChange={event => this.forward(event, this.dsActiveFilterChange)}\n          onDsClose={event => this.forward(event, this.dsClose)}\n          onDsOpenChange={event => {\n            event.stopPropagation();\n            this.open = event.detail;\n            this.dsOpenChange.emit(event.detail);\n          }}\n          onDsAfterClose={event => this.forward(event, this.dsAfterClose)}\n        />\n      </Host>\n    );\n  }\n\n  private forward<T>(event: CustomEvent<T>, emitter: EventEmitter<T>): void {\n    event.stopPropagation();\n    emitter.emit(event.detail);\n  }\n}\n",
       "type": "registry:ui"
     }
   ]