@ds-mo/ui 15.1.0 → 15.2.0

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

@@ -87,7 +87,7 @@
         "On desktop, PanelNav defaults expanded, permits user collapse or expansion, and respects the locally persisted desktop preference.",
         "On tablet, ShellApp keeps PanelNav permanently collapsed and prevents user expansion without overwriting the desktop preference.",
         "On desktop and tablet, panel section navigation replaces BarNav with BarPageTitle; collapsed PanelNav exposes child sections through its anchored flyout.",
-        "When panel section navigation moves BarPageTitle into the shell bar, routed content starts at the standard 32px desktop or 16px tablet gutter and ShellPage reports no page-local sticky-header height.",
+        "When panel section navigation moves BarPageTitle into the shell bar, routed content starts at the standard 16px desktop and tablet gutter and ShellPage reports no page-local sticky-header height.",
         "On mobile, ShellApp hides and inerts desktop chrome, uses a solid primary stage, and composes MobileHeader, MobileSheetNav, ShellTools, and the persistent MobileBarNav around the same application-owned content.",
         "The section-navigation preference also selects mobile navigation: bar preserves flat area selection and the header section picker; panel expands child routes inline in MobileSheetNav and combines the page title with any local subsection in one sheet trigger.",
         "Opening MobileSheetNav temporarily overlays the active routed page or global tool; closing it without selecting an area restores that same destination and its nested state. The sheet exposes the router-derived current area only while the routed area owns the mobile stage, so a global tool never leaves an underlying route highlighted.",

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

@@ -73,7 +73,7 @@
         "A ShellPage-managed BarTitle remains concealed until headerCapacity is available and its rendered variant matches the resolved presentation, preventing a default-variant flash during route activation.",
         "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.",
+        "The default content inset is balanced at 16px on every side in desktop, 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.",
@@ -347,12 +347,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: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-overlay);\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-200);\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-overlay);\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-200);\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  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",
+      "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-200', 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"
     },
     {

package/dist/react/components.d.ts

@@ -52,6 +52,8 @@ export { DsInputDate } from "./ds-input-date.js";
 export { DsInputTime } from "./ds-input-time.js";
 export { DsInput } from "./ds-input.js";
 export { DsLoader } from "./ds-loader.js";
+export { DsMapClusterMarker } from "./ds-map-cluster-marker.js";
+export { DsMapEntityMarker } from "./ds-map-entity-marker.js";
 export { DsMarkdown } from "./ds-markdown.js";
 export { DsMenu } from "./ds-menu.js";
 export { DsMessageActions } from "./ds-message-actions.js";

package/dist/react/components.js

@@ -53,6 +53,8 @@ export { DsInputDate } from "./ds-input-date.js";
 export { DsInputTime } from "./ds-input-time.js";
 export { DsInput } from "./ds-input.js";
 export { DsLoader } from "./ds-loader.js";
+export { DsMapClusterMarker } from "./ds-map-cluster-marker.js";
+export { DsMapEntityMarker } from "./ds-map-entity-marker.js";
 export { DsMarkdown } from "./ds-markdown.js";
 export { DsMenu } from "./ds-menu.js";
 export { DsMessageActions } from "./ds-message-actions.js";

package/dist/react/ds-map-cluster-marker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This file was automatically generated by the Stencil React Output Target.
+ * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+import type { EventName, StencilReactComponent } from './react-runtime.js';
+import { type DsMapClusterMarkerCustomEvent } from "@ds-mo/ui";
+import type { Components } from "@ds-mo/ui/dist/components";
+import { DsMapClusterMarker as DsMapClusterMarkerElement } from "@ds-mo/ui/dist/components/ds-map-cluster-marker.js";
+export type DsMapClusterMarkerEvents = {
+    onDsClick: EventName<DsMapClusterMarkerCustomEvent<MouseEvent>>;
+};
+export declare const DsMapClusterMarker: StencilReactComponent<DsMapClusterMarkerElement, DsMapClusterMarkerEvents, Components.DsMapClusterMarker, 'label'>;

package/dist/react/ds-map-cluster-marker.js

@@ -0,0 +1,12 @@
+'use client';
+import { createComponent } from './react-runtime.js';
+import React from 'react';
+import { DsMapClusterMarker as DsMapClusterMarkerElement, defineCustomElement as defineDsMapClusterMarker } from "@ds-mo/ui/dist/components/ds-map-cluster-marker.js";
+export const DsMapClusterMarker = /*@__PURE__*/ createComponent({
+    tagName: 'ds-map-cluster-marker',
+    elementClass: DsMapClusterMarkerElement,
+    // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
+    react: React,
+    events: { onDsClick: 'dsClick' },
+    defineCustomElement: defineDsMapClusterMarker
+});

package/dist/react/ds-map-entity-marker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This file was automatically generated by the Stencil React Output Target.
+ * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+import type { EventName, StencilReactComponent } from './react-runtime.js';
+import { type DsMapEntityMarkerCustomEvent } from "@ds-mo/ui";
+import type { Components } from "@ds-mo/ui/dist/components";
+import { DsMapEntityMarker as DsMapEntityMarkerElement } from "@ds-mo/ui/dist/components/ds-map-entity-marker.js";
+export type DsMapEntityMarkerEvents = {
+    onDsClick: EventName<DsMapEntityMarkerCustomEvent<MouseEvent>>;
+};
+export declare const DsMapEntityMarker: StencilReactComponent<DsMapEntityMarkerElement, DsMapEntityMarkerEvents, Components.DsMapEntityMarker, 'label'>;

package/dist/react/ds-map-entity-marker.js

@@ -0,0 +1,12 @@
+'use client';
+import { createComponent } from './react-runtime.js';
+import React from 'react';
+import { DsMapEntityMarker as DsMapEntityMarkerElement, defineCustomElement as defineDsMapEntityMarker } from "@ds-mo/ui/dist/components/ds-map-entity-marker.js";
+export const DsMapEntityMarker = /*@__PURE__*/ createComponent({
+    tagName: 'ds-map-entity-marker',
+    elementClass: DsMapEntityMarkerElement,
+    // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
+    react: React,
+    events: { onDsClick: 'dsClick' },
+    defineCustomElement: defineDsMapEntityMarker
+});

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

@@ -0,0 +1,19 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+export declare class MapClusterMarker {
+    /** Accessible action label. Describe the cluster and what activation does. */
+    label: string;
+    /** Short visible cluster identifier revealed on hover or keyboard focus. */
+    caption: string;
+    /** Number of represented entities, compacted at one thousand and above. */
+    count: number;
+    /** De-emphasizes this cluster when an owner-managed selection is active elsewhere. */
+    dimmed: boolean;
+    /** Fired when the cluster's native button is activated. */
+    dsClick: EventEmitter<MouseEvent>;
+    private buttonEl?;
+    /** Moves keyboard focus to the cluster button. */
+    setFocus(): Promise<void>;
+    private handleClick;
+    render(): any;
+}
+//# sourceMappingURL=MapClusterMarker.d.ts.map

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

@@ -0,0 +1,26 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+export type MapEntityMarkerState = 'in-motion' | 'idling' | 'stationary' | 'immobilized' | 'stale';
+export declare class MapEntityMarker {
+    /** Accessible action label. Describe what activating the marker opens. */
+    label: string;
+    /** Short visible identifier revealed on hover or keyboard focus. */
+    caption: string;
+    /** Canonical IcoMo icon name for the represented map entity. Immobilized state uses MapKey. */
+    icon: string;
+    /** Semantic operating state that selects the marker background. */
+    state: MapEntityMarkerState;
+    /** Adds the stale-data outline while preserving the last known operating state. */
+    stale: boolean;
+    /** Clockwise map heading for travel-group and vehicle icons. Values are normalized to 0–359. */
+    heading: number;
+    /** De-emphasizes this marker when an owner-managed selection is active elsewhere. */
+    dimmed: boolean;
+    /** Fired when the marker's native button is activated. */
+    dsClick: EventEmitter<MouseEvent>;
+    private buttonEl?;
+    /** Moves keyboard focus to the marker button. */
+    setFocus(): Promise<void>;
+    private handleClick;
+    render(): any;
+}
+//# sourceMappingURL=MapEntityMarker.d.ts.map

package/dist/types/components.d.ts

@@ -52,6 +52,7 @@ import { InputSize, InputTextAlign, InputType, InputWidth } from "./components/I
 import { InputDateSize, InputDateWidth } from "./components/InputDate/InputDate";
 import { InputTimeSize, InputTimeWidth } from "./components/InputTime/InputTime";
 import { LoaderColor, LoaderSize } from "./components/Loader/Loader";
+import { MapEntityMarkerState } from "./components/MapEntityMarker/MapEntityMarker";
 import { MenuSelectionMode, MenuSize } from "./components/Menu/Menu";
 import { MenuAlign, MenuSide } from "./components/Menu/menu-position";
 import { MessageBubbleVariant } from "./components/MessageBubble/MessageBubble";
@@ -134,6 +135,7 @@ export { InputSize, InputTextAlign, InputType, InputWidth } from "./components/I
 export { InputDateSize, InputDateWidth } from "./components/InputDate/InputDate";
 export { InputTimeSize, InputTimeWidth } from "./components/InputTime/InputTime";
 export { LoaderColor, LoaderSize } from "./components/Loader/Loader";
+export { MapEntityMarkerState } from "./components/MapEntityMarker/MapEntityMarker";
 export { MenuSelectionMode, MenuSize } from "./components/Menu/Menu";
 export { MenuAlign, MenuSide } from "./components/Menu/menu-position";
 export { MessageBubbleVariant } from "./components/MessageBubble/MessageBubble";
@@ -2395,6 +2397,71 @@ export namespace Components {
          */
         "size": LoaderSize;
     }
+    interface DsMapClusterMarker {
+        /**
+          * Short visible cluster identifier revealed on hover or keyboard focus.
+          * @default ''
+         */
+        "caption": string;
+        /**
+          * Number of represented entities, compacted at one thousand and above.
+          * @default 0
+         */
+        "count": number;
+        /**
+          * De-emphasizes this cluster when an owner-managed selection is active elsewhere.
+          * @default false
+         */
+        "dimmed": boolean;
+        /**
+          * Accessible action label. Describe the cluster and what activation does.
+         */
+        "label": string;
+        /**
+          * Moves keyboard focus to the cluster button.
+         */
+        "setFocus": () => Promise<void>;
+    }
+    interface DsMapEntityMarker {
+        /**
+          * Short visible identifier revealed on hover or keyboard focus.
+          * @default ''
+         */
+        "caption": string;
+        /**
+          * De-emphasizes this marker when an owner-managed selection is active elsewhere.
+          * @default false
+         */
+        "dimmed": boolean;
+        /**
+          * Clockwise map heading for travel-group and vehicle icons. Values are normalized to 0–359.
+          * @default 0
+         */
+        "heading": number;
+        /**
+          * Canonical IcoMo icon name for the represented map entity. Immobilized state uses MapKey.
+          * @default 'MapEntityTravelGroup'
+         */
+        "icon": string;
+        /**
+          * Accessible action label. Describe what activating the marker opens.
+         */
+        "label": string;
+        /**
+          * Moves keyboard focus to the marker button.
+         */
+        "setFocus": () => Promise<void>;
+        /**
+          * Adds the stale-data outline while preserving the last known operating state.
+          * @default false
+         */
+        "stale": boolean;
+        /**
+          * Semantic operating state that selects the marker background.
+          * @default 'in-motion'
+         */
+        "state": MapEntityMarkerState;
+    }
     interface DsMarkdown {
         /**
           * @default ''
@@ -4836,6 +4903,14 @@ export interface DsInputTimeCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLDsInputTimeElement;
 }
+export interface DsMapClusterMarkerCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsMapClusterMarkerElement;
+}
+export interface DsMapEntityMarkerCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsMapEntityMarkerElement;
+}
 export interface DsMenuCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLDsMenuElement;
@@ -5718,6 +5793,40 @@ declare global {
         prototype: HTMLDsLoaderElement;
         new (): HTMLDsLoaderElement;
     };
+    interface HTMLDsMapClusterMarkerElementEventMap {
+        "dsClick": MouseEvent;
+    }
+    interface HTMLDsMapClusterMarkerElement extends Components.DsMapClusterMarker, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsMapClusterMarkerElementEventMap>(type: K, listener: (this: HTMLDsMapClusterMarkerElement, ev: DsMapClusterMarkerCustomEvent<HTMLDsMapClusterMarkerElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsMapClusterMarkerElementEventMap>(type: K, listener: (this: HTMLDsMapClusterMarkerElement, ev: DsMapClusterMarkerCustomEvent<HTMLDsMapClusterMarkerElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsMapClusterMarkerElement: {
+        prototype: HTMLDsMapClusterMarkerElement;
+        new (): HTMLDsMapClusterMarkerElement;
+    };
+    interface HTMLDsMapEntityMarkerElementEventMap {
+        "dsClick": MouseEvent;
+    }
+    interface HTMLDsMapEntityMarkerElement extends Components.DsMapEntityMarker, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsMapEntityMarkerElementEventMap>(type: K, listener: (this: HTMLDsMapEntityMarkerElement, ev: DsMapEntityMarkerCustomEvent<HTMLDsMapEntityMarkerElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsMapEntityMarkerElementEventMap>(type: K, listener: (this: HTMLDsMapEntityMarkerElement, ev: DsMapEntityMarkerCustomEvent<HTMLDsMapEntityMarkerElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsMapEntityMarkerElement: {
+        prototype: HTMLDsMapEntityMarkerElement;
+        new (): HTMLDsMapEntityMarkerElement;
+    };
     interface HTMLDsMarkdownElement extends Components.DsMarkdown, HTMLStencilElement {
     }
     var HTMLDsMarkdownElement: {
@@ -6431,6 +6540,8 @@ declare global {
         "ds-input-date": HTMLDsInputDateElement;
         "ds-input-time": HTMLDsInputTimeElement;
         "ds-loader": HTMLDsLoaderElement;
+        "ds-map-cluster-marker": HTMLDsMapClusterMarkerElement;
+        "ds-map-entity-marker": HTMLDsMapEntityMarkerElement;
         "ds-markdown": HTMLDsMarkdownElement;
         "ds-menu": HTMLDsMenuElement;
         "ds-message": HTMLDsMessageElement;
@@ -8923,6 +9034,71 @@ declare namespace LocalJSX {
          */
         "size"?: LoaderSize;
     }
+    interface DsMapClusterMarker {
+        /**
+          * Short visible cluster identifier revealed on hover or keyboard focus.
+          * @default ''
+         */
+        "caption"?: string;
+        /**
+          * Number of represented entities, compacted at one thousand and above.
+          * @default 0
+         */
+        "count"?: number;
+        /**
+          * De-emphasizes this cluster when an owner-managed selection is active elsewhere.
+          * @default false
+         */
+        "dimmed"?: boolean;
+        /**
+          * Accessible action label. Describe the cluster and what activation does.
+         */
+        "label": string;
+        /**
+          * Fired when the cluster's native button is activated.
+         */
+        "onDsClick"?: (event: DsMapClusterMarkerCustomEvent<MouseEvent>) => void;
+    }
+    interface DsMapEntityMarker {
+        /**
+          * Short visible identifier revealed on hover or keyboard focus.
+          * @default ''
+         */
+        "caption"?: string;
+        /**
+          * De-emphasizes this marker when an owner-managed selection is active elsewhere.
+          * @default false
+         */
+        "dimmed"?: boolean;
+        /**
+          * Clockwise map heading for travel-group and vehicle icons. Values are normalized to 0–359.
+          * @default 0
+         */
+        "heading"?: number;
+        /**
+          * Canonical IcoMo icon name for the represented map entity. Immobilized state uses MapKey.
+          * @default 'MapEntityTravelGroup'
+         */
+        "icon"?: string;
+        /**
+          * Accessible action label. Describe what activating the marker opens.
+         */
+        "label": string;
+        /**
+          * Fired when the marker's native button is activated.
+         */
+        "onDsClick"?: (event: DsMapEntityMarkerCustomEvent<MouseEvent>) => void;
+        /**
+          * Adds the stale-data outline while preserving the last known operating state.
+          * @default false
+         */
+        "stale"?: boolean;
+        /**
+          * Semantic operating state that selects the marker background.
+          * @default 'in-motion'
+         */
+        "state"?: MapEntityMarkerState;
+    }
     interface DsMarkdown {
         /**
           * @default ''
@@ -11927,6 +12103,21 @@ declare namespace LocalJSX {
         "color": LoaderColor;
         "label": string | undefined;
     }
+    interface DsMapClusterMarkerAttributes {
+        "label": string;
+        "caption": string;
+        "count": number;
+        "dimmed": boolean;
+    }
+    interface DsMapEntityMarkerAttributes {
+        "label": string;
+        "caption": string;
+        "icon": string;
+        "state": MapEntityMarkerState;
+        "stale": boolean;
+        "heading": number;
+        "dimmed": boolean;
+    }
     interface DsMarkdownAttributes {
         "content": string;
         "streaming": boolean;
@@ -12493,6 +12684,8 @@ declare namespace LocalJSX {
         "ds-input-date": Omit<DsInputDate, keyof DsInputDateAttributes> & { [K in keyof DsInputDate & keyof DsInputDateAttributes]?: DsInputDate[K] } & { [K in keyof DsInputDate & keyof DsInputDateAttributes as `attr:${K}`]?: DsInputDateAttributes[K] } & { [K in keyof DsInputDate & keyof DsInputDateAttributes as `prop:${K}`]?: DsInputDate[K] };
         "ds-input-time": Omit<DsInputTime, keyof DsInputTimeAttributes> & { [K in keyof DsInputTime & keyof DsInputTimeAttributes]?: DsInputTime[K] } & { [K in keyof DsInputTime & keyof DsInputTimeAttributes as `attr:${K}`]?: DsInputTimeAttributes[K] } & { [K in keyof DsInputTime & keyof DsInputTimeAttributes as `prop:${K}`]?: DsInputTime[K] };
         "ds-loader": Omit<DsLoader, keyof DsLoaderAttributes> & { [K in keyof DsLoader & keyof DsLoaderAttributes]?: DsLoader[K] } & { [K in keyof DsLoader & keyof DsLoaderAttributes as `attr:${K}`]?: DsLoaderAttributes[K] } & { [K in keyof DsLoader & keyof DsLoaderAttributes as `prop:${K}`]?: DsLoader[K] };
+        "ds-map-cluster-marker": Omit<DsMapClusterMarker, keyof DsMapClusterMarkerAttributes> & { [K in keyof DsMapClusterMarker & keyof DsMapClusterMarkerAttributes]?: DsMapClusterMarker[K] } & { [K in keyof DsMapClusterMarker & keyof DsMapClusterMarkerAttributes as `attr:${K}`]?: DsMapClusterMarkerAttributes[K] } & { [K in keyof DsMapClusterMarker & keyof DsMapClusterMarkerAttributes as `prop:${K}`]?: DsMapClusterMarker[K] } & OneOf<"label", DsMapClusterMarker["label"], DsMapClusterMarkerAttributes["label"]>;
+        "ds-map-entity-marker": Omit<DsMapEntityMarker, keyof DsMapEntityMarkerAttributes> & { [K in keyof DsMapEntityMarker & keyof DsMapEntityMarkerAttributes]?: DsMapEntityMarker[K] } & { [K in keyof DsMapEntityMarker & keyof DsMapEntityMarkerAttributes as `attr:${K}`]?: DsMapEntityMarkerAttributes[K] } & { [K in keyof DsMapEntityMarker & keyof DsMapEntityMarkerAttributes as `prop:${K}`]?: DsMapEntityMarker[K] } & OneOf<"label", DsMapEntityMarker["label"], DsMapEntityMarkerAttributes["label"]>;
         "ds-markdown": Omit<DsMarkdown, keyof DsMarkdownAttributes> & { [K in keyof DsMarkdown & keyof DsMarkdownAttributes]?: DsMarkdown[K] } & { [K in keyof DsMarkdown & keyof DsMarkdownAttributes as `attr:${K}`]?: DsMarkdownAttributes[K] } & { [K in keyof DsMarkdown & keyof DsMarkdownAttributes as `prop:${K}`]?: DsMarkdown[K] };
         "ds-menu": Omit<DsMenu, keyof DsMenuAttributes> & { [K in keyof DsMenu & keyof DsMenuAttributes]?: DsMenu[K] } & { [K in keyof DsMenu & keyof DsMenuAttributes as `attr:${K}`]?: DsMenuAttributes[K] } & { [K in keyof DsMenu & keyof DsMenuAttributes as `prop:${K}`]?: DsMenu[K] };
         "ds-message": Omit<DsMessage, keyof DsMessageAttributes> & { [K in keyof DsMessage & keyof DsMessageAttributes]?: DsMessage[K] } & { [K in keyof DsMessage & keyof DsMessageAttributes as `attr:${K}`]?: DsMessageAttributes[K] } & { [K in keyof DsMessage & keyof DsMessageAttributes as `prop:${K}`]?: DsMessage[K] };
@@ -12612,6 +12805,8 @@ declare module "@stencil/core" {
             "ds-input-date": LocalJSX.IntrinsicElements["ds-input-date"] & JSXBase.HTMLAttributes<HTMLDsInputDateElement>;
             "ds-input-time": LocalJSX.IntrinsicElements["ds-input-time"] & JSXBase.HTMLAttributes<HTMLDsInputTimeElement>;
             "ds-loader": LocalJSX.IntrinsicElements["ds-loader"] & JSXBase.HTMLAttributes<HTMLDsLoaderElement>;
+            "ds-map-cluster-marker": LocalJSX.IntrinsicElements["ds-map-cluster-marker"] & JSXBase.HTMLAttributes<HTMLDsMapClusterMarkerElement>;
+            "ds-map-entity-marker": LocalJSX.IntrinsicElements["ds-map-entity-marker"] & JSXBase.HTMLAttributes<HTMLDsMapEntityMarkerElement>;
             "ds-markdown": LocalJSX.IntrinsicElements["ds-markdown"] & JSXBase.HTMLAttributes<HTMLDsMarkdownElement>;
             "ds-menu": LocalJSX.IntrinsicElements["ds-menu"] & JSXBase.HTMLAttributes<HTMLDsMenuElement>;
             "ds-message": LocalJSX.IntrinsicElements["ds-message"] & JSXBase.HTMLAttributes<HTMLDsMessageElement>;

package/dist/vue/components.d.ts

@@ -52,6 +52,8 @@ export { DsInput } from './ds-input.js';
 export { DsInputDate } from './ds-input-date.js';
 export { DsInputTime } from './ds-input-time.js';
 export { DsLoader } from './ds-loader.js';
+export { DsMapClusterMarker } from './ds-map-cluster-marker.js';
+export { DsMapEntityMarker } from './ds-map-entity-marker.js';
 export { DsMarkdown } from './ds-markdown.js';
 export { DsMenu } from './ds-menu.js';
 export { DsMessage } from './ds-message.js';

package/dist/vue/components.js

@@ -54,6 +54,8 @@ export { DsInput } from './ds-input.js';
 export { DsInputDate } from './ds-input-date.js';
 export { DsInputTime } from './ds-input-time.js';
 export { DsLoader } from './ds-loader.js';
+export { DsMapClusterMarker } from './ds-map-cluster-marker.js';
+export { DsMapEntityMarker } from './ds-map-entity-marker.js';
 export { DsMarkdown } from './ds-markdown.js';
 export { DsMenu } from './ds-menu.js';
 export { DsMessage } from './ds-message.js';

package/dist/vue/ds-map-cluster-marker.d.ts

@@ -0,0 +1,3 @@
+import { type StencilVueComponent } from './vue-runtime.js';
+import type { JSX } from '@ds-mo/ui/components';
+export declare const DsMapClusterMarker: StencilVueComponent<JSX.DsMapClusterMarker>;

package/dist/vue/ds-map-cluster-marker.js

@@ -0,0 +1,14 @@
+/* eslint-disable */
+/* tslint:disable */
+/* auto-generated vue proxies */
+import { defineContainer } from './vue-runtime.js';
+import { defineCustomElement as defineDsMapClusterMarker } from '@ds-mo/ui/components/ds-map-cluster-marker.js';
+export const DsMapClusterMarker = /*@__PURE__*/ defineContainer('ds-map-cluster-marker', defineDsMapClusterMarker, [
+    'label',
+    'caption',
+    'count',
+    'dimmed',
+    'dsClick'
+], [
+    'dsClick'
+]);

package/dist/vue/ds-map-entity-marker.d.ts

@@ -0,0 +1,3 @@
+import { type StencilVueComponent } from './vue-runtime.js';
+import type { JSX } from '@ds-mo/ui/components';
+export declare const DsMapEntityMarker: StencilVueComponent<JSX.DsMapEntityMarker>;

package/dist/vue/ds-map-entity-marker.js

@@ -0,0 +1,17 @@
+/* eslint-disable */
+/* tslint:disable */
+/* auto-generated vue proxies */
+import { defineContainer } from './vue-runtime.js';
+import { defineCustomElement as defineDsMapEntityMarker } from '@ds-mo/ui/components/ds-map-entity-marker.js';
+export const DsMapEntityMarker = /*@__PURE__*/ defineContainer('ds-map-entity-marker', defineDsMapEntityMarker, [
+    'label',
+    'caption',
+    'icon',
+    'state',
+    'stale',
+    'heading',
+    'dimmed',
+    'dsClick'
+], [
+    'dsClick'
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds-mo/ui",
-  "version": "15.1.0",
+  "version": "15.2.0",
   "description": "CompoMo — composable web components styled with TokoMo design tokens",
   "keywords": [
     "web-components",