@ds-mo/ui 14.21.0 → 14.22.1

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/table-search.json

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