@ds-mo/ui 12.6.2 → 12.8.0

package/README.md

@@ -2,22 +2,16 @@
 
 [![npm version](https://img.shields.io/npm/v/@ds-mo/ui.svg)](https://www.npmjs.com/package/@ds-mo/ui)
 
-Composable web UI components (Stencil custom elements) styled with [TokoMo](https://github.com/zainadeel/TokoMo) design tokens. Works in any framework — ships **Stencil-generated** Angular proxies and React wrappers alongside the `<ds-*>` custom elements.
+Framework-neutral Stencil web components styled with TokoMo tokens. CompoMo
+ships custom elements plus generated Angular and React adapters.
 
 ## Install
 
 ```bash
-npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons
+npm install @ds-mo/tokens @ds-mo/icons @ds-mo/ui
 ```
 
-**Required peer dependencies:**
-
-- **`@ds-mo/tokens`** — CSS custom properties (colors, dimensions, typography, effects). Components will not render correctly without it.
-- **`@ds-mo/icons`** — SVG sources for `<ds-icon>` and built-in icon props. Resolved at **your app bundle time** from your installed IcoMo version (not baked into `@ds-mo/ui`).
-
-## Setup
-
-Import TokoMo tokens globally (once, at your app root):
+Import TokoMo once at the application root:
 
 ```ts
 import '@ds-mo/tokens';
@@ -25,131 +19,66 @@ import '@ds-mo/tokens/reset';
 import '@ds-mo/tokens/globals';
 ```
 
-Register the custom elements you render (each import auto-defines its tag):
+## Use
+
+Custom elements auto-define when their module is imported:
 
 ```ts
 import '@ds-mo/ui/dist/components/ds-button-filled.js';
-import '@ds-mo/ui/dist/components/ds-button-unfilled.js';
-import '@ds-mo/ui/dist/components/ds-bar-nav.js';
-// …import only the <ds-*> tags your app uses
 ```
 
-Your app bundler must resolve `@ds-mo/icons` when it bundles `ds-icon` — install `@ds-mo/icons` alongside `@ds-mo/ui`.
-
-### Framework wrappers (optional)
-
-| Host | Import | Usage |
-| --- | --- | --- |
-| **Angular** | `@ds-mo/ui/angular` | Stencil proxy directives — property/event bindings in templates |
-| **React** | `@ds-mo/ui/react` | `DsButtonFilled`, `DsBarNav`, … — thin wrappers around the same custom elements |
-| **Any** | `@ds-mo/ui/dist/components/ds-*.js` | Use `<ds-*>` directly (motive-webapp-lab pattern) |
-
-There is **no** published `@ds-mo/ui/loader` or global `@ds-mo/ui/css` bundle — styles ship scoped inside each custom-element module.
-
-**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"
+```html
+<ds-button-filled label="Save"></ds-button-filled>
 ```
 
-Or let npm obtain the latest public package when the MCP client starts:
+Angular applications should prefer per-component standalone adapters:
 
-```toml
-[mcp_servers.compomo]
-command = "npx"
-args = ["-y", "--package", "@ds-mo/ui@latest", "compomo-mcp"]
+```ts
+import { DsButtonFilled } from '@ds-mo/ui/angular/ds-button-filled';
 ```
 
-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.
-
-Registry-oriented tools return both readable Markdown and schema-validated
-`structuredContent`. Compatible MCP clients can consume the generated component
-API, authored design intent, dependencies, and executable pattern recipes as JSON
-without reparsing prose; text content remains available for older clients. Every
-tool is annotated as read-only, idempotent, and closed-world.
-
-## Components
+React applications use the generated wrappers:
 
-All tags are `ds-*` custom elements. Grouped by role (see Storybook for props and stories):
-
-### Primitives
-- **Text**, **Icon**, **Divider**, **Loader**, **Skeleton**
-- **ButtonFilled** — filled button; `variant` (label / icon / icon-label) + `size` + intent×contrast
-- **ButtonUnfilled** — unfilled button; same variants/sizes; surface-aware chrome through `background`
-- **Tag** (static metadata or compact menu trigger), **Chip** (removable metadata on primary surfaces), **Badge**
-
-### Controls
-- **Toggle**, **Checkbox**, **Radio**, **Input**, **Slider**, **Field**
-
-### Overlays
-- **Modal**, **Menu**, **Tooltip**, **Select**, **Toast**
-
-### Navigation
-- **Breadcrumb** (hierarchical page ancestors), **TabGroup** (horizontal local views), **PanelSubNav** (vertical local views)
-- **ShellApp**, **ShellPage**, **PanelNav**, **BarNav**, **BarTitle**, **BarWorkflow**, **PanelTools**
-
-### Status & layout
-- **EmptyState**, **Loader**, **Skeleton**, **CardSetting**, **CardDataVizDonut**, **CardDataVizLine**
-
-## Token dependency
-
-All styling uses TokoMo CSS custom properties. No hardcoded colors, sizes, or shadows — everything maps to the token system. Components will render unstyled if `@ds-mo/tokens` is not imported.
-
-## Semantic prose
-
-Safe semantic DOM produced by Markdown, CMS, or documentation renderers can use the renderer-neutral prose stylesheet:
-
-```css
-@import '@ds-mo/ui/prose.css';
+```tsx
+import { DsButtonFilled } from '@ds-mo/ui/react';
 ```
 
-```html
-<article class="ds-prose">
-  <h2>Summary</h2>
-  <p>Renderer-owned semantic content.</p>
-</article>
-```
+Install `@ds-mo/icons` in the consuming application. `ds-icon` resolves exact
+canonical IcoMo export names at application bundle time.
 
-The application remains responsible for parsing and content safety. Use `data-ds-prose="off"` on embedded product UI, and wrap wide tables in `.ds-prose__table-scroll`. See the [prose foundation decision](docs/prose-foundation.md).
+## Public support surfaces
 
-## Elevated control wrappers
+- `@ds-mo/ui/shell` — framework-neutral shell contracts.
+- `@ds-mo/ui/toast` — toast manager.
+- `@ds-mo/ui/utils` — generic helpers such as `registerIcons`.
+- `@ds-mo/ui/prose.css` — renderer-neutral semantic prose styling.
+- `@ds-mo/ui/control-elevation.css` — elevated outer control wrappers.
 
-When a control needs elevation on an outer wrapper, use the split-shadow utility so an opaque child cannot cover TokoMo's inset highlight:
+There is no global component CSS bundle; styles ship with each custom element.
 
-```css
-@import '@ds-mo/ui/control-elevation.css';
-```
+## Agent recipes
 
-```html
-<div class="my-control-shell ds-control-elevation ds-control-elevation--md">
-  <ds-button-filled label="Create" has-border="false"></ds-button-filled>
-</div>
-```
+The package includes the local `compomo-mcp` executable with generated
+component metadata and executable Custom Elements, Angular, and React
+composition recipes.
 
-The wrapper owns its radius, surface, outer shadow, and topmost highlight. Keep the wrapped control's optional resting border off; focus, error, selected, hover, and press strokes remain owned and rendered by the control beneath that highlight.
+```toml
+# .codex/config.toml
+[mcp_servers.compomo]
+command = "./node_modules/.bin/compomo-mcp"
+```
 
-## Icon pattern
+Use registry tools when component selection or a composition contract is
+unclear. API facts come from Stencil metadata; curated intent comes from
+co-located component agent JSON and executable patterns.
 
-Components that accept icons use a named `icon` slot:
+## Documentation
 
-```html
-<ds-button-filled variant="icon" icon="Check" intent="brand" aria-label="Save"></ds-button-filled>
-<ds-button-unfilled variant="icon" icon="Pencil" aria-label="Edit"></ds-button-unfilled>
-<ds-button-filled label="Save" intent="brand"></ds-button-filled>
-```
+- [Storybook introduction and usage](src/docs/Introduction.mdx)
+- [Framework integration](docs/framework-integration.md)
+- [Maintainer documentation router](docs/index.md)
+- [Repository instructions](AGENTS.md)
 
-`icon` / `name` must be a canonical IcoMo export key (`ArrowRight`, `Bell`, …).
+Package versions, components, props, events, and exports are intentionally not
+duplicated here. Read `package.json`, Storybook, or the generated registry for
+current facts.

package/dist/.build-stamp

@@ -1 +1 @@
-1785039338009
+1785353002857

package/dist/agent-patterns.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "12.6.2",
+  "packageVersion": "12.8.0",
   "kind": "patterns",
   "entries": [
     {
@@ -322,7 +322,8 @@
         "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."
+        "Let the containing product select drawer or full-width layout while keeping transcript measure readable and rich content horizontally scrollable.",
+        "When history and transcript are simultaneously visible, establish one shared master-detail layout contract for pane width, divider, transcript measure, composer containment, and empty-region placement; do not independently recreate that geometry for each conversation channel."
       ],
       "implementations": {
         "customElements": {
@@ -346,16 +347,18 @@
       },
       "references": [
         "src/wc/components/ConversationList/ConversationList.stories.ts",
-        "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+        "src/wc/components/MessageScroller/MessageScroller.stories.ts",
+        "docs/layout-recipe-foundation.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.",
+      "summary": "Connect a button 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."
+        "A compact button should show the current view or mode and let the user choose another one from a menu.",
+        "A row, card, or toolbar needs an overflow or more-options menu."
       ],
       "avoidWhen": [
         "The choice is a submitted form value with a field label or validation; use Select.",
@@ -366,24 +369,36 @@
       "components": [
         {
           "component": "component:ds-button-unfilled",
-          "role": "Provides the visible trigger, popup relationship attributes, and focus target.",
+          "role": "Provides the visible trigger, popup relationship attributes, and focus target. Carries both shapes, and is the only component that carries the icon-only overflow role.",
           "required": true
         },
         {
           "component": "component:ds-menu",
           "role": "Owns anchored placement, menu semantics, keyboard navigation, viewport clamping, selection, and close behavior.",
           "required": true
+        },
+        {
+          "component": "component:ds-button-filled",
+          "role": "Substitutes for the trigger when the menu belongs to the single primary action in a local decision area, using the label or icon-label shape only.",
+          "required": false
         }
       ],
       "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.",
+        "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 its pressed wash for the popup's rendered lifecycle from expanded alone, so never also set isActive to represent an open menu.",
         "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.",
+        "A button either has a menu or is a menu, and the trigger's variant selects between the two shapes.",
+        "Has a menu: a label or icon-label action that opens a menu. Set hasMenu, which implies aria-haspopup of menu and renders the trailing chevron that communicates the popup. Both button primitives support this shape.",
+        "Is a menu: an icon-only overflow or more-options control. Set hasMenu, which adds no chevron, so the glyph must convey the menu alone; use Ellipses. Only ButtonUnfilled carries this shape, because the role is chrome rather than a primary action.",
+        "Never pair hasMenu with an icon-only glyph that does not read as a menu on its own; there is no chevron to fall back on.",
+        "Set controls to the Menu id and expanded from the same open state passed to Menu.",
+        "Give an icon-only trigger an accessible name that states the role, such as More options, because no visible label or chevron carries it.",
+        "Use haspopup directly instead of hasMenu for a non-menu popup such as a listbox or dialog; those cases get no chevron.",
         "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.",
@@ -406,7 +421,7 @@
                 {
                   "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>"
+                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  label=\"View · Overview\"\n  has-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>\n\n<!-- Overflow shape: the Ellipses glyph conveys the menu, so no chevron is added. -->\n<ds-button-unfilled\n  id=\"row-menu-trigger\"\n  variant=\"icon\"\n  icon=\"Ellipses\"\n  aria-label=\"More options\"\n  has-menu\n  controls=\"row-menu\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"row-menu\"\n  anchor-id=\"row-menu-trigger\"\n  menu-label=\"More options\"\n  align=\"end\"\n></ds-menu>"
                 },
                 {
                   "path": "view-menu.ts",
@@ -436,7 +451,7 @@
                 {
                   "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}"
+                  "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}"
                 }
               ],
               "notes": [
@@ -461,7 +476,7 @@
                 {
                   "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>"
+                  "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>"
                 },
                 {
                   "path": "view-menu.component.ts",