@ds-mo/ui 9.0.0 → 9.2.0

package/README.md

@@ -48,6 +48,34 @@ There is **no** published `@ds-mo/ui/loader` or global `@ds-mo/ui/css` bundle
 
 **SPA hosts (Angular / React):** `ds-panel-nav` and `ds-bar-nav` need a [first-paint integration contract](docs/framework-integration.md) on hard reload — seed bar-nav state and stamp `data-nav-style` before custom elements upgrade.
 
+## Agent recipes through MCP
+
+The package includes a local stdio MCP server that exposes component metadata and
+executable Custom Elements, React, and Angular composition recipes. It runs on the
+developer's machine; no hosted MCP service or API key is required.
+
+When `@ds-mo/ui` is installed in the consuming project, point Codex at the package binary:
+
+```toml
+# .codex/config.toml
+[mcp_servers.compomo]
+command = "./node_modules/.bin/compomo-mcp"
+```
+
+Or let npm obtain the latest public package when the MCP client starts:
+
+```toml
+[mcp_servers.compomo]
+command = "npx"
+args = ["-y", "--package", "@ds-mo/ui@latest", "compomo-mcp"]
+```
+
+The server provides `list_components`, `get_component`, `get_setup_guide`,
+`get_component_source`, `list_patterns`, and `get_pattern`. Add a repository
+instruction telling agents to retrieve the applicable pattern before composing
+multiple design-system components; connecting the MCP makes recipes available,
+while the instruction makes their use consistent.
+
 ## Components
 
 All tags are `ds-*` custom elements. Grouped by role (see Storybook for props and stories):

package/dist/.build-stamp

@@ -1 +1 @@
-1784322516816
+1784503227826

package/dist/agent-patterns.json

@@ -0,0 +1,397 @@
+{
+  "schemaVersion": "1.0.0",
+  "package": "@ds-mo/ui",
+  "packageVersion": "9.2.0",
+  "kind": "patterns",
+  "entries": [
+    {
+      "id": "pattern:agent-chat",
+      "status": "experimental",
+      "summary": "Extend the generic conversation pattern with ordered agent response parts while keeping transport and product behavior outside the design system.",
+      "useWhen": [
+        "A chat presents rich agent output including Markdown, safe activity, display-only tool calls, attachments, or sources."
+      ],
+      "avoidWhen": [
+        "The channel is person-to-person or the component would be expected to execute models, tools, approvals, or persistence."
+      ],
+      "components": [
+        {
+          "component": "component:ds-message-scroller",
+          "role": "Provides generic transcript movement and live-edge behavior.",
+          "required": true
+        },
+        {
+          "component": "component:ds-message",
+          "role": "Renders participant turns with channel-neutral semantics.",
+          "required": true
+        },
+        {
+          "component": "component:ds-message-bubble",
+          "role": "Renders participant copy with the shared body-medium regular message baseline.",
+          "required": true
+        },
+        {
+          "component": "component:ds-agent-response",
+          "role": "Renders ordered normalized agent response parts.",
+          "required": true
+        },
+        {
+          "component": "component:ds-message-composer",
+          "role": "Emits participant submission and stop intent.",
+          "required": true
+        }
+      ],
+      "stateOwnership": [
+        "The application owns scripted or real transport, immutable response parts, retry, stop, generated titles, and persistence.",
+        "Participant turns use MessageBubble's body-medium regular default; the application does not promote ordinary sent-message copy to body-large.",
+        "AgentResponse owns ordered display only and never reveals private reasoning.",
+        "Tool-call components display execution state but do not request participant approval."
+      ],
+      "accessibility": [
+        "Agent activity must be concise user-safe summaries, never hidden chain-of-thought.",
+        "Sources use descriptive external links and unsafe schemes remain non-interactive.",
+        "Streaming and tool states remain available as text without relying on animation."
+      ],
+      "responsiveBehavior": [
+        "Use wider ghost responses for rich content while retaining readable text measure and horizontal scrolling for code or tables."
+      ],
+      "implementations": {
+        "customElements": {
+          "status": "planned",
+          "references": [
+            "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          ]
+        },
+        "react": {
+          "status": "planned",
+          "references": [
+            "src/react/components.ts"
+          ]
+        },
+        "angular": {
+          "status": "planned",
+          "references": [
+            "src/angular/index.ts"
+          ]
+        }
+      },
+      "references": [
+        "agent/patterns/conversation/pattern.agent.json",
+        "src/wc/components/AgentResponse/AgentResponse.tsx"
+      ]
+    },
+    {
+      "id": "pattern:application-shell",
+      "status": "experimental",
+      "summary": "Required base-page composition for standard authenticated applications, with one AppShell coordinating primary destinations, secondary route sections, tools chrome, responsive modes, and stable main content geometry.",
+      "useWhen": [
+        "Building any standard authenticated product or workspace page with CompoMo.",
+        "Application navigation and tools must remain consistent around changing route content.",
+        "Creating a reusable base-page template for CompoMo applications."
+      ],
+      "avoidWhen": [
+        "Building authentication, onboarding, public, marketing, print, error, or intentionally focused full-screen experiences.",
+        "The page is already rendered inside an AppShell.",
+        "A nested or second application shell is being considered."
+      ],
+      "components": [
+        {
+          "component": "component:ds-app-shell",
+          "role": "Provides the single workspace root and coordinates shell composition, shared chrome, responsive modes, and stable content geometry.",
+          "required": true
+        },
+        {
+          "component": "component:ds-panel-nav",
+          "role": "Provides the application's one primary navigation with top-level destinations and standard Dashboard/Settings and account footer controls.",
+          "required": true
+        },
+        {
+          "component": "component:ds-bar-nav",
+          "role": "Provides secondary route-section navigation or the active primary destination label while preserving shell height.",
+          "required": true
+        },
+        {
+          "component": "component:ds-panel-tools",
+          "role": "Provides required tools chrome with Search and Help as the minimum standard tools and optional additional product tools.",
+          "required": true
+        }
+      ],
+      "stateOwnership": [
+        "The application router owns the current route, Dashboard or Settings context, authorization filtering, destination and section collections, localized labels, and navigation execution.",
+        "AppShell owns desktop, tablet, and mobile composition, shell geometry, navStyle propagation, gradient alignment, chrome transitions, metrics, and shell shortcuts.",
+        "PanelNav owns primary-destination presentation and the user-controlled desktop collapse preference.",
+        "BarNav derives the active secondary route from currentUrl and basePath and receives the active PanelNav destination label as heading.",
+        "PanelTools owns tool-rail and drawer interaction while the application owns available tool content and active-tool state.",
+        "PanelNav groups and BarNav dividers visually organize peers and never introduce nested navigation hierarchy."
+      ],
+      "accessibility": [
+        "Render one main landmark in the default content region.",
+        "Use PanelNav exclusively for primary destinations and BarNav exclusively for secondary route sections.",
+        "Keep localized visible labels and accessible names available when navigation is collapsed or moved into overflow.",
+        "Provide Search and Help as the minimum accessible PanelTools actions.",
+        "Preserve keyboard focus and route state across responsive and Dashboard/Settings context changes."
+      ],
+      "responsiveBehavior": [
+        "Use fixed system breakpoints: desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
+        "Desktop permits PanelNav expansion and collapse and restores the persisted user preference.",
+        "Tablet keeps PanelNav permanently collapsed and does not overwrite the desktop preference.",
+        "Mobile keeps AppShell as the root while replacing desktop navigation with a future dedicated mobile navigation design.",
+        "Keep BarNav height, PanelTools chrome, and main-content origin stable across route changes.",
+        "Treat the complete responsive composition as an intended contract that is not yet fully implemented by the current AppShell runtime."
+      ],
+      "implementations": {
+        "customElements": {
+          "status": "verified",
+          "references": [
+            "src/wc/components/AppShell/AppShell.stories.ts",
+            "docs/framework-integration.md"
+          ]
+        },
+        "react": {
+          "status": "planned",
+          "references": [
+            "scripts/verify-package-imports.mjs",
+            "docs/framework-integration.md"
+          ]
+        },
+        "angular": {
+          "status": "verified",
+          "references": [
+            "scripts/verify-package-imports.mjs",
+            "docs/framework-integration.md"
+          ]
+        }
+      },
+      "references": [
+        "src/wc/components/AppShell/AppShell.mdx",
+        "docs/framework-integration.md"
+      ]
+    },
+    {
+      "id": "pattern:conversation",
+      "status": "experimental",
+      "summary": "Compose channel-neutral history, transcript, message surfaces, attachments, and composer behavior for reusable conversations.",
+      "useWhen": [
+        "A product needs threaded conversation UX that may serve agent or person-to-person channels."
+      ],
+      "avoidWhen": [
+        "The experience is a static activity feed or form without conversational turns."
+      ],
+      "components": [
+        {
+          "component": "component:ds-conversation-list",
+          "role": "Owns history scrolling, empty layout, and floating action placement.",
+          "required": true
+        },
+        {
+          "component": "component:ds-panel-tool-search",
+          "role": "Collects a product-owned conversation history search query when the conversation is presented as a PanelTools product.",
+          "required": false
+        },
+        {
+          "component": "component:ds-message-scroller",
+          "role": "Owns transcript position and live-edge following.",
+          "required": true
+        },
+        {
+          "component": "component:ds-message",
+          "role": "Owns each turn's direction, grouping, and metadata.",
+          "required": true
+        },
+        {
+          "component": "component:ds-message-bubble",
+          "role": "Owns the visible content surface and body-medium default independently of row semantics.",
+          "required": true
+        },
+        {
+          "component": "component:ds-message-composer",
+          "role": "Emits draft, submit, and stop intent without transport ownership.",
+          "required": true
+        },
+        {
+          "component": "component:ds-attachment-list",
+          "role": "Displays existing attachment metadata when present.",
+          "required": false
+        }
+      ],
+      "stateOwnership": [
+        "The application owns conversations, messages, selection, drafts, persistence, transport, unread policy, and any history search query or matching policy. ConversationListItem presents every positive unreadCount as one dot aligned with the title row; unread titles are primary and read titles are secondary.",
+        "The application owns contextual row-menu commands such as pin, rename, members, and delete; ConversationListItem supplies the sibling actions slot and hover/focus/touch presentation.",
+        "When history search is present, distinguish an empty history from a populated history with no matching conversations.",
+        "Plain incoming and outgoing message copy uses MessageBubble's body-medium regular default; the application must not promote ordinary conversation turns to body-large.",
+        "MessageScroller owns reader-relative transcript position and follow behavior. Compose MessageComposer in its overlay slot so transcript content moves behind the surface while measured bottom clearance keeps the latest turn readable.",
+        "MessageComposer emits intent while the application controls its value and status. Its submit action defaults to brand for agent and person-to-person channels; select another submitIntent only for a different semantic consequence, never merely to identify AI content."
+      ],
+      "accessibility": [
+        "Give history and transcript regions distinct localized names.",
+        "Preserve message author, order, time, status, and delivery meaning in text.",
+        "Do not force the reader back to the live edge after deliberate transcript interaction."
+      ],
+      "responsiveBehavior": [
+        "Let the containing product select drawer or full-width layout while keeping transcript measure readable and rich content horizontally scrollable."
+      ],
+      "implementations": {
+        "customElements": {
+          "status": "planned",
+          "references": [
+            "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          ]
+        },
+        "react": {
+          "status": "planned",
+          "references": [
+            "src/react/components.ts"
+          ]
+        },
+        "angular": {
+          "status": "planned",
+          "references": [
+            "src/angular/index.ts"
+          ]
+        }
+      },
+      "references": [
+        "src/wc/components/ConversationList/ConversationList.stories.ts",
+        "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+      ]
+    },
+    {
+      "id": "pattern:menu-trigger",
+      "status": "stable",
+      "summary": "Connect a ButtonUnfilled trigger to an anchored Menu for a compact command or view-selection popup without application-authored positioning.",
+      "useWhen": [
+        "A button should reveal a short contextual collection of commands.",
+        "A compact button should show the current view or mode and let the user choose another one from a menu."
+      ],
+      "avoidWhen": [
+        "The choice is a submitted form value with a field label or validation; use Select.",
+        "The available local views can remain visible; use TabGroup.",
+        "The choices are primary or secondary application destinations; use the matching navigation component.",
+        "The popup contains substantial content, confirmation, or a form; use Modal."
+      ],
+      "components": [
+        {
+          "component": "component:ds-button-unfilled",
+          "role": "Provides the visible trigger, popup relationship attributes, and focus target.",
+          "required": true
+        },
+        {
+          "component": "component:ds-menu",
+          "role": "Owns anchored placement, menu semantics, keyboard navigation, viewport clamping, selection, and close behavior.",
+          "required": true
+        }
+      ],
+      "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 ButtonUnfilled.expanded and Menu.open.",
+        "Menu owns popup placement and keyboard navigation; the application never calculates popup coordinates or applies positional CSS.",
+        "On dsSelect, update the selected value, close the Menu, and restore focus to the trigger.",
+        "On dsClose, synchronize the application open state to false."
+      ],
+      "accessibility": [
+        "Set ButtonUnfilled.haspopup to menu, controls to the Menu id, and expanded from the same open state passed to Menu.",
+        "Give Menu a concise menuLabel describing the available commands or views.",
+        "Set Menu.initialFocusVisible only when the trigger MouseEvent detail is zero, indicating keyboard activation.",
+        "Keep visible selected styling synchronized with the application's selected value; Menu exposes the selected command through aria-current.",
+        "Return focus to the trigger after selection; Menu already restores it for Escape and outside dismissal."
+      ],
+      "responsiveBehavior": [
+        "Keep Menu's default choice-cell anchor alignment unless deliberate custom frame geometry is required.",
+        "Let Menu clamp to the viewport and avoid application-authored fixed or absolute positioning.",
+        "Use a concise trigger label that can fit the owning layout without hiding the selected meaning."
+      ],
+      "implementations": {
+        "customElements": {
+          "status": "verified",
+          "recipes": [
+            {
+              "id": "selected-view-menu",
+              "title": "Selected view menu",
+              "summary": "A ButtonUnfilled displays the active view and opens a Menu whose selected row updates that view.",
+              "files": [
+                {
+                  "path": "view-menu.html",
+                  "language": "html",
+                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  label=\"View · Overview\"\n  haspopup=\"menu\"\n  controls=\"view-menu\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"view-menu\"\n  anchor-id=\"view-menu-trigger\"\n  menu-label=\"Choose view\"\n></ds-menu>"
+                },
+                {
+                  "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()"
+                }
+              ],
+              "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."
+              ]
+            }
+          ],
+          "references": [
+            "src/wc/components/Tag/Tag.stories.ts",
+            "src/wc/components/Menu/Menu.stories.ts"
+          ]
+        },
+        "react": {
+          "status": "verified",
+          "recipes": [
+            {
+              "id": "selected-view-menu",
+              "title": "Selected view menu",
+              "summary": "A controlled React composition using generated ButtonUnfilled and Menu wrappers.",
+              "files": [
+                {
+                  "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        haspopup=\"menu\"\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}"
+                }
+              ],
+              "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."
+              ]
+            }
+          ],
+          "references": [
+            "src/react/ds-button-unfilled.ts",
+            "src/react/ds-menu.ts"
+          ]
+        },
+        "angular": {
+          "status": "verified",
+          "recipes": [
+            {
+              "id": "selected-view-menu",
+              "title": "Selected view menu",
+              "summary": "A controlled Angular composition using generated standalone ButtonUnfilled and Menu adapters.",
+              "files": [
+                {
+                  "path": "view-menu.component.html",
+                  "language": "html",
+                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  [label]=\"'View · ' + selectedLabel\"\n  haspopup=\"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>"
+                },
+                {
+                  "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}"
+                }
+              ],
+              "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."
+              ]
+            }
+          ],
+          "references": [
+            "src/angular/ds-button-unfilled.ts",
+            "src/angular/ds-menu.ts"
+          ]
+        }
+      },
+      "references": [
+        "src/wc/components/Tag/Tag.stories.ts",
+        "src/wc/components/Menu/Menu.agent.json",
+        "docs/framework-integration.md"
+      ]
+    }
+  ]
+}