@ds-mo/ui 8.3.1 → 9.1.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):
@@ -61,9 +89,6 @@ All tags are `ds-*` custom elements. Grouped by role (see Storybook for props an
 ### Controls
 - **Toggle**, **Checkbox**, **Radio**, **Input**, **Slider**, **Field**
 
-### Data display
-- **Table**, **Pagination**
-
 ### Overlays
 - **Modal**, **Menu**, **Tooltip**, **Select**, **Banner**
 

package/dist/.build-stamp

@@ -1 +1 @@
-1784320108642
+1784331945246

package/dist/agent-patterns.json

@@ -0,0 +1,233 @@
+{
+  "schemaVersion": "1.0.0",
+  "package": "@ds-mo/ui",
+  "packageVersion": "9.1.0",
+  "kind": "patterns",
+  "entries": [
+    {
+      "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: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"
+      ]
+    }
+  ]
+}