@handamade/psi-mcp 0.10.0 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @handamade/psi-mcp
 
-MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 25 React 19 components, 13 composition patterns (D47) that recipe them together with gap-annotated compose trees, every semantic token with its OKLCH derivation formula resolved across all four themes, and the usage guidance — through two read-only tools. It does not write code.
+MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 28 React 19 components, 13 composition patterns (D47) that recipe them together with gap-annotated compose trees, every semantic token with its OKLCH derivation formula resolved across all four themes, and the usage guidance — through two read-only tools. It does not write code.
 
 ## Connect
 

package/dist/psi-index.json

@@ -1,5 +1,5 @@
 {
- "version": "0.10.0",
+ "version": "0.11.0",
  "themes": [
   "light",
   "dark",
@@ -1086,6 +1086,162 @@
    ],
    "slots": [],
    "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Pagination\n\nNumbered pager with ellipsis truncation (D63). Standalone rather than a Table family member: `table-pagination` composes it as a Toolbar sibling of the page-size Select.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `page` | `number` | — | yes | Current page, 1-based. |\n| `pageCount` | `number` | — | yes | Total number of pages. |\n| `onPageChange` | `(page: number) => void` | — | yes | Called with the requested page. Required — unlike Table's `onSortChange`/ `onSelectionChange`, which are optional because `sortable`/`selectable` gate whether they're meaningful, `Pagination` has no such gating boolean: the prop is unconditionally meaningful, so a `Pagination` without it is a dead control (final review finding, D62). |\n| `siblingCount` | `number` | 1 | no | Pages shown either side of the current one before truncating. |\n| `aria-label` | `string` | Pagination | no | Accessible name for the nav landmark. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-pagination-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "Toast",
+   "description": "A single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.",
+   "props": [
+    {
+     "name": "variant",
+     "type": "\"neutral\" | \"success\" | \"warning\" | \"danger\"",
+     "required": false,
+     "default": "neutral",
+     "description": "Status variant."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "The message."
+    },
+    {
+     "name": "action",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "Trailing affordance — a ghost Button (Undo, Retry, View)."
+    },
+    {
+     "name": "onDismiss",
+     "type": "(() => void)",
+     "required": false,
+     "default": null,
+     "description": "When provided, renders the dismiss button and calls this. Toast does not\nremove itself; the owner disposes."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the underlying `<div>`."
+    }
+   ],
+   "slots": [
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "1..*",
+     "order": 1
+    },
+    {
+     "name": "action",
+     "accepts": {
+      "components": [
+       "Button"
+      ],
+      "contracts": [
+       "inline-content"
+      ]
+     },
+     "cardinality": "0..1",
+     "order": 2
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Toast\n\nA single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `variant` | `\"neutral\" \\| \"success\" \\| \"warning\" \\| \"danger\"` | neutral | no | Status variant. |\n| `children` | `ReactNode` | — | yes | The message. |\n| `action` | `ReactNode` | — | no | Trailing affordance — a ghost Button (Undo, Retry, View). |\n| `onDismiss` | `(() => void)` | — | no | When provided, renders the dismiss button and calls this. Toast does not remove itself; the owner disposes. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the underlying `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Reaches the action and the dismiss button in DOM order. Esc is not a dismissal — a toast is not modal and traps nothing. |\n| Enter / Space | Activates the focused action or dismiss button. |\n\nPresentational and controlled (D64): onDismiss reports and the owner disposes; Toast never removes itself. It carries no role/aria-live of its own — politeness belongs to ToastRegion's two persistent wrappers. The variant's meaning is announced by a visually hidden status word (\"Success:\", \"Warning:\", \"Error:\"), never by colour and icon shape alone; the icon is aria-hidden. neutral has no status and gets no prefix. The dismiss button requires no props — it is labelled \"Dismiss notification\".\n\n## Theming\n\nOverride `--psi-toast-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "ToastRegion",
+   "description": "The positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover=\"manual\"`, not `\"auto\"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `variant` off each child, the same Children.map technique Table uses for select-all injection. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group.",
+   "props": [
+    {
+     "name": "placement",
+     "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
+     "required": false,
+     "default": "bottom-end",
+     "description": "Corner the stack occupies."
+    },
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": "Notifications",
+     "description": "Accessible name for the region."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "The toast stack — `Toast` elements, routed to a live wrapper by variant."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the region element."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# ToastRegion\n\nThe positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover=\"manual\"`, not `\"auto\"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `variant` off each child, the same Children.map technique Table uses for select-all injection. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `placement` | `\"top-start\" \\| \"top-end\" \\| \"bottom-start\" \\| \"bottom-end\"` | bottom-end | no | Corner the stack occupies. |\n| `aria-label` | `string` | Notifications | no | Accessible name for the region. |\n| `children` | `ReactNode` | — | yes | The toast stack — `Toast` elements, routed to a live wrapper by variant. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the region element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Moves into the stacked toasts' controls in DOM order; the region itself is not focusable. |\n\nRenders two always-present live wrappers — role=\"status\"/aria-live=\"polite\" and role=\"alert\"/aria-live=\"assertive\" — and routes each toast into one by variant (neutral/success polite, warning/danger assertive). Both stay in the DOM when the queue is empty: a live region announces mutations to a subtree that already existed, so a wrapper mounting with its first toast would leave that toast unannounced. Sits on the native top layer via popover=\"manual\", so a toast raised from inside a modal Dialog is still painted above the backdrop and still announced — though showModal() makes everything outside the dialog inert, so it cannot be clicked until the dialog closes; manual (not auto) means no light dismiss, so the click that raised the toast cannot close it. The region is click-through (pointer-events: none) and each toast takes its own clicks back.\n\n## Theming\n\nThis component has no `--psi-toast-region-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "ToastProvider",
+   "description": "Owns the toast queue, its auto-dismiss timers, and the single ToastRegion (D65). This is the library's one stateful container, and the exception is deliberately narrow. D50 and D53 rejected internal state for Dialog and Menu because the consumer already owned the state that decided visibility — a menu is open because a user clicked a trigger the consumer rendered. A toast has no such owner: it is created by an outcome, not by a UI state, and it disappears on a timer nobody is watching. The rule that survives is the useful half — presentational components stay controlled (`Toast` still holds nothing), a stateful container may exist when the state has no natural owner, and it must be opt-in. Timers pause while the pointer or focus is inside the region (WCAG 2.2.1), and resume with the time *remaining* rather than a fresh full duration — restarting would let a user hold a toast open indefinitely by jiggling the mouse.",
+   "props": [
+    {
+     "name": "limit",
+     "type": "number",
+     "required": false,
+     "default": 3,
+     "description": "Max simultaneous toasts; the oldest is evicted first."
+    },
+    {
+     "name": "duration",
+     "type": "number",
+     "required": false,
+     "default": 5000,
+     "description": "Auto-dismiss for toasts with no action, in ms."
+    },
+    {
+     "name": "actionDuration",
+     "type": "number",
+     "required": false,
+     "default": 10000,
+     "description": "Auto-dismiss for toasts carrying an action, in ms. An affordance that\nvanishes before it can be reached is not an affordance."
+    },
+    {
+     "name": "placement",
+     "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
+     "required": false,
+     "default": "bottom-end",
+     "description": "Corner the stack occupies."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "The subtree that may call `useToast()`. The region is rendered alongside it."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# ToastProvider\n\nOwns the toast queue, its auto-dismiss timers, and the single ToastRegion (D65). This is the library's one stateful container, and the exception is deliberately narrow. D50 and D53 rejected internal state for Dialog and Menu because the consumer already owned the state that decided visibility — a menu is open because a user clicked a trigger the consumer rendered. A toast has no such owner: it is created by an outcome, not by a UI state, and it disappears on a timer nobody is watching. The rule that survives is the useful half — presentational components stay controlled (`Toast` still holds nothing), a stateful container may exist when the state has no natural owner, and it must be opt-in. Timers pause while the pointer or focus is inside the region (WCAG 2.2.1), and resume with the time *remaining* rather than a fresh full duration — restarting would let a user hold a toast open indefinitely by jiggling the mouse.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `limit` | `number` | 3 | no | Max simultaneous toasts; the oldest is evicted first. |\n| `duration` | `number` | 5000 | no | Auto-dismiss for toasts with no action, in ms. |\n| `actionDuration` | `number` | 10000 | no | Auto-dismiss for toasts carrying an action, in ms. An affordance that vanishes before it can be reached is not an affordance. |\n| `placement` | `\"top-start\" \\| \"top-end\" \\| \"bottom-start\" \\| \"bottom-end\"` | bottom-end | no | Corner the stack occupies. |\n| `children` | `ReactNode` | — | yes | The subtree that may call `useToast()`. The region is rendered alongside it. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Focus entering the region pauses every auto-dismiss timer; leaving resumes them. |\n\nOwns the queue, the auto-dismiss timers and the single ToastRegion (D65). Timers pause while the pointer or focus is inside the region and resume with the time remaining, satisfying WCAG 2.2.1 for content that disappears on a timer. Toasts carrying an action get a longer default lifetime, so the affordance cannot vanish before it is reached. useToast() throws outside a provider rather than silently no-opping.\n\n## Theming\n\nThis component has no `--psi-toast-provider-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   }
  ],
  "tokens": [
@@ -2623,6 +2779,7 @@
      "ask": "What kind of outcome is being confirmed?",
      "options": [
       "success",
+      "warning",
       "danger",
       "neutral"
      ],
@@ -2633,11 +2790,9 @@
     "message": "[what just happened]",
     "undo-label": "Undo"
    },
-   "gaps": [
-    "Toast"
-   ],
-   "blocked": true,
-   "preset": null
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Toast action={<Button variant=\"ghost\">Undo</Button>} variant=\"success\">[what just happened]</Toast>\n"
   },
   {
    "id": "bulk-action-bar",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handamade/psi-mcp",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "license": "MIT",
   "description": "MCP server and agent-context generator for the Psi (Ψ) design system",
   "type": "module",
@@ -33,8 +33,8 @@
     "tsx": "^4.22.4",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6",
-    "@handamade/psi-tokens": "0.10.0",
-    "@handamade/psi-react": "0.10.0"
+    "@handamade/psi-tokens": "0.11.0",
+    "@handamade/psi-react": "0.11.0"
   },
   "scripts": {
     "build": "tsx scripts/build-index.ts && tsc -p tsconfig.build.json"