@ds-mo/ui 14.27.1 → 14.29.0

package/dist/.package-ready.json

@@ -1 +1 @@
-{"schemaVersion":1,"package":"@ds-mo/ui","version":"14.27.1","components":79,"digest":"fa3e35d6fdc4c435453c66bbb097639ac08154f8958d3dc77f83c6ef1e1e509e","completedAt":"2026-09-03T17:37:14.629Z"}
+{"schemaVersion":1,"package":"@ds-mo/ui","version":"14.29.0","components":81,"digest":"a6bac8343e279f3c65ca013b620cd8ce2c9486a0a4cf2b82bdbf21551e7d9fe3","completedAt":"2026-09-04T16:44:56.274Z"}

package/dist/agent-patterns.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "14.27.1",
+  "packageVersion": "14.29.0",
   "kind": "patterns",
   "entries": [
     {
@@ -209,7 +209,8 @@
         "The application owns account menus, tool product data, page actions, and the consequences of every emitted intent event.",
         "The application owns viewport and theme-color metadata, the dynamic-viewport framework root, and containing document overscroll so body never becomes a second application scroller; ShellApp fills that owner and keeps its existing internal scrollers.",
         "The application resolves competing global messages to one Banner and owns its actions, controlled open state, orientation for the available shell capacity, dismissal persistence, and removal after exit motion.",
-        "Use composition=\"slotted\" only when a team intentionally needs to assemble the public lower-level chrome components itself."
+        "Use composition=\"slotted\" only when a team intentionally needs to assemble the public lower-level chrome components itself.",
+        "Keep external surface ownership separate from selected routes, toggled modes, and inline expansion. Forward surfaceOpen on header actions while their associated menu or panel remains rendered, including exit motion; clear it after closing. Internal popup controls manage this relationship themselves."
       ],
       "accessibility": [
         "Render exactly one managed ShellApp and one active routed main landmark.",
@@ -229,7 +230,7 @@
         "An optional Banner spans the complete application above desktop navigation, workspace, tools, and mobile global surfaces while remaining below the operating-system top safe area.",
         "Desktop and tablet may render governed direct-action rail accessories. Mobile intentionally omits them, so applications provide equivalent persistent status in the top Banner lane when the product requires it.",
         "Switching breakpoints changes presentation and inert state without recreating route or tool elements.",
-        "Switching sectionNavigation changes only desktop and tablet chrome; mobile composition, current route, routed content, and tool state remain stable.",
+        "Switching sectionNavigation changes where route sections live: panel expands them inside MobileSheetNav on mobile and combines the page title with any active local subsection in one sheet trigger. Detail pages use this combined trigger in both modes. The current route, routed content, and tool state remain stable.",
         "Search, Activity, Messages, and Agents use direct mobile destinations; products may explicitly group review tools under Inbox instead."
       ],
       "implementations": {
@@ -328,7 +329,8 @@
       "references": [
         "src/wc/components/ShellApp/ShellApp.mdx",
         "docs/framework-integration.md",
-        "docs/migrations/v13.md"
+        "docs/migrations/v13.md",
+        "src/docs/SurfaceOwnership.mdx"
       ]
     },
     {
@@ -475,12 +477,13 @@
       "stateOwnership": [
         "The application owns the selected command or view value and derives the trigger label and each item's isSelected state from it.",
         "The application synchronizes one open boolean to the trigger's expanded prop and Menu.open.",
-        "An open popup is a transient pressed state, not a selected one. The trigger holds only its pressed wash for the popup's rendered lifecycle from expanded alone, without changing foreground, so never also set isActive to represent an open menu.",
+        "The trigger owns a visible contextual surface, even when it appears far away. Set surfaceOpen when opening, retain it through exit motion, and clear it on dsAfterClose unless the surface reopened. This holds only the pressed wash; do not use isActive or a pressed toggle to represent the open menu.",
         "Menu owns popup placement and keyboard navigation; the application never calculates popup coordinates or applies positional CSS.",
         "On dsSelect from a command or single-selection row, update the selected value, close the Menu, and restore focus to the trigger.",
         "For button split mode, restore focus to the menu segment after a menu choice; the primary segment remains an independent command.",
         "Switch rows and reorderable rows report dsSelect or dsReorder without closing; replace the items array from those events.",
-        "On dsClose, synchronize the application open state to false."
+        "On dsClose, synchronize the application open state to false.",
+        "Inline expansion does not establish surface ownership. Expanded controls accessibility disclosure; surfaceOpen independently tracks the rendered contextual surface. In split mode only the menu segment holds the wash."
       ],
       "accessibility": [
         "A button either has a menu or is a menu, and the trigger's variant selects between the two shapes.",
@@ -518,12 +521,13 @@
                 {
                   "path": "view-menu.ts",
                   "language": "typescript",
-                  "content": "import '@ds-mo/ui/components/ds-button-unfilled.js'\nimport '@ds-mo/ui/components/ds-menu.js'\nimport type { MenuItemData } from '@ds-mo/ui'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nconst trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')!\nconst menu = document.querySelector<HTMLDsMenuElement>('#view-menu')!\nlet selectedValue = 'overview'\n\nfunction render() {\n  const selected = choices.find(item => item.value === selectedValue) ?? choices[0]\n  trigger.label = `View · ${selected.label}`\n  menu.items = choices.map(item => ({ ...item, isSelected: item.value === selectedValue }))\n}\n\nfunction setOpen(open: boolean) {\n  trigger.expanded = open\n  menu.open = open\n}\n\ntrigger.addEventListener('dsClick', event => {\n  const mouseEvent = (event as CustomEvent<MouseEvent>).detail\n  menu.initialFocusVisible = mouseEvent.detail === 0\n  setOpen(!menu.open)\n})\nmenu.addEventListener('dsClose', () => setOpen(false))\nmenu.addEventListener('dsSelect', event => {\n  selectedValue = (event as CustomEvent<MenuItemData>).detail.value ?? selectedValue\n  render()\n  setOpen(false)\n  requestAnimationFrame(() => trigger.setFocus())\n})\n\nrender()"
+                  "content": "import '@ds-mo/ui/components/ds-button-unfilled.js'\nimport '@ds-mo/ui/components/ds-menu.js'\nimport type { MenuItemData } from '@ds-mo/ui'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nconst trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')!\nconst menu = document.querySelector<HTMLDsMenuElement>('#view-menu')!\nlet selectedValue = 'overview'\n\nfunction render() {\n  const selected = choices.find(item => item.value === selectedValue) ?? choices[0]\n  trigger.label = `View · ${selected.label}`\n  menu.items = choices.map(item => ({ ...item, isSelected: item.value === selectedValue }))\n}\n\nfunction setOpen(open: boolean) {\n  trigger.expanded = open\n  if (open) trigger.surfaceOpen = true\n  menu.open = open\n}\n\ntrigger.addEventListener('dsClick', event => {\n  const mouseEvent = (event as CustomEvent<MouseEvent>).detail\n  menu.initialFocusVisible = mouseEvent.detail === 0\n  setOpen(!menu.open)\n})\ntrigger.surfaceOpen = false\nmenu.addEventListener('dsAfterClose', () => {\n  if (!menu.open) trigger.surfaceOpen = false\n})\nmenu.addEventListener('dsClose', () => setOpen(false))\nmenu.addEventListener('dsSelect', event => {\n  selectedValue = (event as CustomEvent<MenuItemData>).detail.value ?? selectedValue\n  render()\n  setOpen(false)\n  requestAnimationFrame(() => trigger.setFocus())\n})\n\nrender()"
                 }
               ],
               "notes": [
                 "Assign Menu.items as a JavaScript property; complex arrays cannot be expressed as an HTML attribute.",
-                "Do not add positioning styles to either element."
+                "Do not add positioning styles to either element.",
+                "Keep surfaceOpen true through exit motion and release it on dsAfterClose; expanded follows the logical open state."
               ]
             }
           ],
@@ -543,12 +547,13 @@
                 {
                   "path": "ViewMenu.tsx",
                   "language": "tsx",
-                  "content": "import { useState } from 'react'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled, DsMenu } from '@ds-mo/ui/react'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nexport function ViewMenu() {\n  const [selectedValue, setSelectedValue] = useState('overview')\n  const [open, setOpen] = useState(false)\n  const [initialFocusVisible, setInitialFocusVisible] = useState(false)\n  const selected = choices.find(item => item.value === selectedValue) ?? choices[0]\n  const items = choices.map(item => ({ ...item, isSelected: item.value === selectedValue }))\n\n  function focusTrigger() {\n    requestAnimationFrame(() => {\n      const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n      trigger?.setFocus()\n    })\n  }\n\n  return (\n    <>\n      <DsButtonUnfilled\n        id=\"view-menu-trigger\"\n        label={`View · ${selected.label}`}\n        hasMenu\n        controls=\"view-menu\"\n        expanded={open}\n        onDsClick={event => {\n          setInitialFocusVisible(event.detail.detail === 0)\n          setOpen(current => !current)\n        }}\n      />\n      <DsMenu\n        id=\"view-menu\"\n        anchorId=\"view-menu-trigger\"\n        menuLabel=\"Choose view\"\n        items={items}\n        open={open}\n        initialFocusVisible={initialFocusVisible}\n        onDsClose={() => setOpen(false)}\n        onDsSelect={event => {\n          setSelectedValue(event.detail.value ?? selectedValue)\n          setOpen(false)\n          focusTrigger()\n        }}\n      />\n    </>\n  )\n}"
+                  "content": "import { useState } from 'react'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled, DsMenu } from '@ds-mo/ui/react'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nexport function ViewMenu() {\n  const [selectedValue, setSelectedValue] = useState('overview')\n  const [open, setOpen] = useState(false)\n  const [surfaceOpen, setSurfaceOpen] = useState(false)\n  const [initialFocusVisible, setInitialFocusVisible] = useState(false)\n  const selected = choices.find(item => item.value === selectedValue) ?? choices[0]\n  const items = choices.map(item => ({ ...item, isSelected: item.value === selectedValue }))\n\n  function focusTrigger() {\n    requestAnimationFrame(() => {\n      const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n      trigger?.setFocus()\n    })\n  }\n\n  return (\n    <>\n      <DsButtonUnfilled\n        id=\"view-menu-trigger\"\n        label={`View · ${selected.label}`}\n        hasMenu\n        controls=\"view-menu\"\n        expanded={open}\n        surfaceOpen={surfaceOpen}\n        onDsClick={event => {\n          setInitialFocusVisible(event.detail.detail === 0)\n          if (!open) setSurfaceOpen(true)\n          setOpen(current => !current)\n        }}\n      />\n      <DsMenu\n        id=\"view-menu\"\n        anchorId=\"view-menu-trigger\"\n        menuLabel=\"Choose view\"\n        items={items}\n        open={open}\n        initialFocusVisible={initialFocusVisible}\n        onDsClose={() => setOpen(false)}\n        onDsAfterClose={() => { if (!open) setSurfaceOpen(false) }}\n        onDsSelect={event => {\n          setSelectedValue(event.detail.value ?? selectedValue)\n          setOpen(false)\n          focusTrigger()\n        }}\n      />\n    </>\n  )\n}"
                 }
               ],
               "notes": [
                 "Use one React state value for both the trigger expanded prop and Menu open prop.",
-                "Keep the stable trigger and menu ids unique when rendering more than one composition."
+                "Keep the stable trigger and menu ids unique when rendering more than one composition.",
+                "Keep surfaceOpen true through exit motion and release it on dsAfterClose; expanded follows the logical open state."
               ]
             }
           ],
@@ -568,12 +573,13 @@
                 {
                   "path": "ViewMenu.vue",
                   "language": "vue",
-                  "content": "<script setup lang=\"ts\">\nimport { computed, ref } from 'vue'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled, DsMenu } from '@ds-mo/ui/vue'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nconst selectedValue = ref('overview')\nconst open = ref(false)\nconst initialFocusVisible = ref(false)\nconst selected = computed(() => choices.find(item => item.value === selectedValue.value) ?? choices[0])\nconst items = computed(() => choices.map(item => ({ ...item, isSelected: item.value === selectedValue.value })))\n\nfunction focusTrigger() {\n  requestAnimationFrame(() => {\n    const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n    trigger?.setFocus()\n  })\n}\n\nfunction toggleMenu(event: CustomEvent<MouseEvent>) {\n  initialFocusVisible.value = event.detail.detail === 0\n  open.value = !open.value\n}\n\nfunction selectView(event: CustomEvent<MenuItemData>) {\n  selectedValue.value = event.detail.value ?? selectedValue.value\n  open.value = false\n  focusTrigger()\n}\n</script>\n\n<template>\n  <DsButtonUnfilled\n    id=\"view-menu-trigger\"\n    :label=\"`View · ${selected.label}`\"\n    has-menu\n    controls=\"view-menu\"\n    :expanded=\"open\"\n    @ds-click=\"toggleMenu\"\n  />\n  <DsMenu\n    id=\"view-menu\"\n    anchor-id=\"view-menu-trigger\"\n    menu-label=\"Choose view\"\n    :items=\"items\"\n    :open=\"open\"\n    :initial-focus-visible=\"initialFocusVisible\"\n    @ds-close=\"open = false\"\n    @ds-select=\"selectView\"\n  />\n</template>"
+                  "content": "<script setup lang=\"ts\">\nimport { computed, ref } from 'vue'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled, DsMenu } from '@ds-mo/ui/vue'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nconst selectedValue = ref('overview')\nconst open = ref(false)\nconst surfaceOpen = ref(false)\nconst initialFocusVisible = ref(false)\nconst selected = computed(() => choices.find(item => item.value === selectedValue.value) ?? choices[0])\nconst items = computed(() => choices.map(item => ({ ...item, isSelected: item.value === selectedValue.value })))\n\nfunction focusTrigger() {\n  requestAnimationFrame(() => {\n    const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n    trigger?.setFocus()\n  })\n}\n\nfunction toggleMenu(event: CustomEvent<MouseEvent>) {\n  initialFocusVisible.value = event.detail.detail === 0\n  if (!open.value) surfaceOpen.value = true\n  open.value = !open.value\n}\n\nfunction selectView(event: CustomEvent<MenuItemData>) {\n  selectedValue.value = event.detail.value ?? selectedValue.value\n  open.value = false\n  focusTrigger()\n}\n</script>\n\n<template>\n  <DsButtonUnfilled\n    id=\"view-menu-trigger\"\n    :label=\"`View · ${selected.label}`\"\n    has-menu\n    controls=\"view-menu\"\n    :expanded=\"open\"\n    :surface-open=\"surfaceOpen\"\n    @ds-click=\"toggleMenu\"\n  />\n  <DsMenu\n    id=\"view-menu\"\n    anchor-id=\"view-menu-trigger\"\n    menu-label=\"Choose view\"\n    :items=\"items\"\n    :open=\"open\"\n    :initial-focus-visible=\"initialFocusVisible\"\n    @ds-close=\"open = false\"\n    @ds-after-close=\"!open && (surfaceOpen = false)\"\n    @ds-select=\"selectView\"\n  />\n</template>"
                 }
               ],
               "notes": [
                 "Use one Vue ref for both the trigger expanded prop and Menu open prop.",
-                "Keep the stable trigger and menu ids unique when rendering more than one composition."
+                "Keep the stable trigger and menu ids unique when rendering more than one composition.",
+                "Keep surfaceOpen true through exit motion and release it on dsAfterClose; expanded follows the logical open state."
               ]
             }
           ],
@@ -593,17 +599,18 @@
                 {
                   "path": "view-menu.component.html",
                   "language": "html",
-                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  [label]=\"'View · ' + selectedLabel\"\n  has-menu\n  controls=\"view-menu\"\n  [expanded]=\"open\"\n  (dsClick)=\"toggleMenu($event)\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"view-menu\"\n  anchorId=\"view-menu-trigger\"\n  menuLabel=\"Choose view\"\n  [items]=\"menuItems\"\n  [open]=\"open\"\n  [initialFocusVisible]=\"initialFocusVisible\"\n  (dsClose)=\"open = false\"\n  (dsSelect)=\"selectView($event)\"\n></ds-menu>"
+                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  [label]=\"'View · ' + selectedLabel\"\n  has-menu\n  controls=\"view-menu\"\n  [expanded]=\"open\"\n  [surfaceOpen]=\"surfaceOpen\"\n  (dsClick)=\"toggleMenu($event)\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"view-menu\"\n  anchorId=\"view-menu-trigger\"\n  menuLabel=\"Choose view\"\n  [items]=\"menuItems\"\n  [open]=\"open\"\n  [initialFocusVisible]=\"initialFocusVisible\"\n  (dsClose)=\"open = false\"\n  (dsAfterClose)=\"!open && (surfaceOpen = false)\"\n  (dsSelect)=\"selectView($event)\"\n></ds-menu>"
                 },
                 {
                   "path": "view-menu.component.ts",
                   "language": "typescript",
-                  "content": "import { Component } from '@angular/core'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled } from '@ds-mo/ui/angular/ds-button-unfilled'\nimport { DsMenu } from '@ds-mo/ui/angular/ds-menu'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\n@Component({\n  selector: 'app-view-menu',\n  standalone: true,\n  imports: [DsButtonUnfilled, DsMenu],\n  templateUrl: './view-menu.component.html',\n})\nexport class ViewMenuComponent {\n  selectedValue = 'overview'\n  open = false\n  initialFocusVisible = false\n\n  get selectedLabel() {\n    return choices.find(item => item.value === this.selectedValue)?.label ?? choices[0].label\n  }\n\n  get menuItems() {\n    return choices.map(item => ({ ...item, isSelected: item.value === this.selectedValue }))\n  }\n\n  toggleMenu(event: CustomEvent<MouseEvent>) {\n    this.initialFocusVisible = event.detail.detail === 0\n    this.open = !this.open\n  }\n\n  selectView(event: CustomEvent<MenuItemData>) {\n    this.selectedValue = event.detail.value ?? this.selectedValue\n    this.open = false\n    requestAnimationFrame(() => {\n      const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n      trigger?.setFocus()\n    })\n  }\n}"
+                  "content": "import { Component } from '@angular/core'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled } from '@ds-mo/ui/angular/ds-button-unfilled'\nimport { DsMenu } from '@ds-mo/ui/angular/ds-menu'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\n@Component({\n  selector: 'app-view-menu',\n  standalone: true,\n  imports: [DsButtonUnfilled, DsMenu],\n  templateUrl: './view-menu.component.html',\n})\nexport class ViewMenuComponent {\n  selectedValue = 'overview'\n  open = false\n  surfaceOpen = false\n  initialFocusVisible = false\n\n  get selectedLabel() {\n    return choices.find(item => item.value === this.selectedValue)?.label ?? choices[0].label\n  }\n\n  get menuItems() {\n    return choices.map(item => ({ ...item, isSelected: item.value === this.selectedValue }))\n  }\n\n  toggleMenu(event: CustomEvent<MouseEvent>) {\n    this.initialFocusVisible = event.detail.detail === 0\n    if (!this.open) this.surfaceOpen = true\n    this.open = !this.open\n  }\n\n  selectView(event: CustomEvent<MenuItemData>) {\n    this.selectedValue = event.detail.value ?? this.selectedValue\n    this.open = false\n    requestAnimationFrame(() => {\n      const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n      trigger?.setFocus()\n    })\n  }\n}"
                 }
               ],
               "notes": [
                 "Bind items as a property and import both generated standalone adapters.",
-                "Keep the stable trigger and menu ids unique when rendering more than one composition."
+                "Keep the stable trigger and menu ids unique when rendering more than one composition.",
+                "Keep surfaceOpen true through exit motion and release it on dsAfterClose; expanded follows the logical open state."
               ]
             }
           ],
@@ -616,7 +623,8 @@
       "references": [
         "src/wc/components/Tag/Tag.stories.ts",
         "src/wc/components/Menu/Menu.agent.json",
-        "docs/framework-integration.md"
+        "docs/framework-integration.md",
+        "src/docs/SurfaceOwnership.mdx"
       ]
     },
     {
@@ -659,7 +667,8 @@
         "The application replaces pageChrome from completed route state and handles ShellApp page intent events.",
         "ShellApp owns ShellPage, BarTitle, MobileHeader, the content scroller, sticky presentation, and responsive switching.",
         "The default slot contains application-owned routed content and is not recreated for header compaction or breakpoint changes.",
-        "Use a directly slotted ShellPage only inside composition=\"slotted\"."
+        "Use a directly slotted ShellPage only inside composition=\"slotted\".",
+        "Keep external surface ownership separate from selected routes, toggled modes, and inline expansion. Forward surfaceOpen on header actions while their associated menu or panel remains rendered, including exit motion; clear it after closing. Internal popup controls manage this relationship themselves."
       ],
       "accessibility": [
         "Keep exactly one active routed main landmark, supplied by the managed ShellPage.",
@@ -764,7 +773,8 @@
       "references": [
         "src/wc/components/ShellPage/ShellPage.agent.json",
         "src/wc/components/BarTitle/BarTitle.agent.json",
-        "src/wc/components/ShellApp/ShellApp.agent.json"
+        "src/wc/components/ShellApp/ShellApp.agent.json",
+        "src/docs/SurfaceOwnership.mdx"
       ]
     }
   ]