@handamade/psi-mcp 0.12.0 → 0.13.1

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 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.
+MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 32 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.12.0",
+ "version": "0.13.1",
  "themes": [
   "light",
   "dark",
@@ -1249,6 +1249,183 @@
    ],
    "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"
+  },
+  {
+   "name": "Tabs",
+   "description": "Tab set root (D67) — holds no selection state of its own, following D50, D53 and D62: `value` and `onValueChange` are required and there is no `defaultValue`. Values are strings rather than indices because an index breaks the moment a tab is inserted, and real tab sets map to ids. `Tab` and `TabPanel` pair by value, so their source order need not match. Activation is automatic: arrow keys move focus and selection together. That is the APG default where panel content is already available, and manual activation is deliberately not offered as a mode — a consumer for whom activating a panel is expensive already controls what the panel renders.",
+   "props": [
+    {
+     "name": "value",
+     "type": "string",
+     "required": true,
+     "default": null,
+     "description": "Controlled selected tab, matched against each `Tab`/`TabPanel` value."
+    },
+    {
+     "name": "onValueChange",
+     "type": "(value: string) => void",
+     "required": true,
+     "default": null,
+     "description": "Fires with the newly selected value; the consumer flips `value`."
+    },
+    {
+     "name": "orientation",
+     "type": "\"horizontal\" | \"vertical\"",
+     "required": false,
+     "default": "horizontal",
+     "description": "Axis of the tab list, which also picks the arrow keys."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "A `TabList` and one `TabPanel` per tab."
+    },
+    {
+     "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 wrapper `<div>`."
+    }
+   ],
+   "slots": [
+    {
+     "name": "body",
+     "accepts": {
+      "components": [
+       "TabList",
+       "TabPanel"
+      ]
+     },
+     "cardinality": "1..*",
+     "order": 1
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Tabs\n\nTab set root (D67) — holds no selection state of its own, following D50, D53 and D62: `value` and `onValueChange` are required and there is no `defaultValue`. Values are strings rather than indices because an index breaks the moment a tab is inserted, and real tab sets map to ids. `Tab` and `TabPanel` pair by value, so their source order need not match. Activation is automatic: arrow keys move focus and selection together. That is the APG default where panel content is already available, and manual activation is deliberately not offered as a mode — a consumer for whom activating a panel is expensive already controls what the panel renders.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | Controlled selected tab, matched against each `Tab`/`TabPanel` value. |\n| `onValueChange` | `(value: string) => void` | — | yes | Fires with the newly selected value; the consumer flips `value`. |\n| `orientation` | `\"horizontal\" \\| \"vertical\"` | horizontal | no | Axis of the tab list, which also picks the arrow keys. |\n| `children` | `ReactNode` | — | yes | A `TabList` and one `TabPanel` per tab. |\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 wrapper `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Enters the tab list at its selected tab (one stop for the whole list), then moves on to the active panel. |\n\nControlled-only (D67): value and onValueChange are required and Tabs never selects itself. Tab and TabPanel pair by string value, not index, so their source order need not match. Every panel renders and unselected ones carry `hidden`, so aria-controls always resolves and panel DOM state survives a switch.\n\n## Theming\n\nOverride `--psi-tabs-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\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": "TabList",
+   "description": "The `role=\"tablist\"` container (D67). Owns the roving tabindex: the whole list is one Tab stop, and the arrow keys move between tabs inside it.",
+   "props": [
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Accessible name for the tab set. Declared here rather than inherited so\ndocgen keeps it in the manifest (D60) — a tablist without a name is\nannounced as an unlabelled group, and the prop would otherwise be\ninvisible to an agent reading the manifest."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "One `Tab` per view."
+    },
+    {
+     "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 tablist element."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TabList\n\nThe `role=\"tablist\"` container (D67). Owns the roving tabindex: the whole list is one Tab stop, and the arrow keys move between tabs inside it.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `aria-label` | `string` | — | no | Accessible name for the tab set. Declared here rather than inherited so docgen keeps it in the manifest (D60) — a tablist without a name is announced as an unlabelled group, and the prop would otherwise be invisible to an agent reading the manifest. |\n| `children` | `ReactNode` | — | yes | One `Tab` per view. |\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 tablist element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Arrow Left / Arrow Right | Horizontal orientation: moves to the previous/next enabled tab, wrapping at both ends. Selection follows focus (automatic activation). |\n| Arrow Up / Arrow Down | Vertical orientation: the same, on the block axis. The cross-axis arrows are ignored rather than swallowed. |\n| Home / End | Jumps to the first or last enabled tab. |\n\nRenders role=\"tablist\" with aria-orientation. Requires an accessible name — pass aria-label, which is promoted onto its own props interface (D60) so the manifest shows it. Owns the roving tabindex: exactly one tab is in the page tab order at a time.\n\n## Theming\n\nThis component has no `--psi-tab-list-*` 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": "Tab",
+   "description": "One `role=\"tab\"` (D67). Renders a real `<button>`. `disabled` sets `aria-disabled` rather than the `disabled` attribute, so the tab stays discoverable to assistive tech while being skipped by roving navigation — the same choice MenuItem made in D53.",
+   "props": [
+    {
+     "name": "value",
+     "type": "string",
+     "required": true,
+     "default": null,
+     "description": "Pairs this tab with the `TabPanel` of the same value."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "Label — keep it to one or two words."
+    },
+    {
+     "name": "disabled",
+     "type": "boolean",
+     "required": false,
+     "default": false,
+     "description": "Skipped by arrow navigation and not selectable, but still announced."
+    },
+    {
+     "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<HTMLButtonElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the underlying `<button>`."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Tab\n\nOne `role=\"tab\"` (D67). Renders a real `<button>`. `disabled` sets `aria-disabled` rather than the `disabled` attribute, so the tab stays discoverable to assistive tech while being skipped by roving navigation — the same choice MenuItem made in D53.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | Pairs this tab with the `TabPanel` of the same value. |\n| `children` | `ReactNode` | — | yes | Label — keep it to one or two words. |\n| `disabled` | `boolean` | false | no | Skipped by arrow navigation and not selectable, but still announced. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLButtonElement>` | — | no | Forwarded ref to the underlying `<button>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Enter / Space | Activates (native button behavior); arrow keys already select on focus. |\n\nRenders a real <button> with role=\"tab\", aria-selected and aria-controls. disabled sets aria-disabled (not the disabled attribute) so the tab stays discoverable to assistive tech while being skipped by roving navigation and refused for selection — the same choice MenuItem made in D53.\n\n## Theming\n\nThis component has no `--psi-tab-*` 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": "TabPanel",
+   "description": "One `role=\"tabpanel\"` (D67). Every panel renders; unselected ones carry `hidden`. Returning null instead would leave `aria-controls` on every unselected tab pointing at an element that does not exist, and would throw away DOM state — a half-filled form in a panel would lose its values on each tab switch. The cost is a heavier DOM when panels are large; the answer to that is rendering less inside the panel, not unmounting it behind the consumer's back. `tabIndex={0}` because a panel whose content has no focusable element would otherwise be unreachable by keyboard.",
+   "props": [
+    {
+     "name": "value",
+     "type": "string",
+     "required": true,
+     "default": null,
+     "description": "Pairs this panel with the `Tab` of the same value."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "The view for this tab. Rendered even when unselected, then `hidden`."
+    },
+    {
+     "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 panel element."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TabPanel\n\nOne `role=\"tabpanel\"` (D67). Every panel renders; unselected ones carry `hidden`. Returning null instead would leave `aria-controls` on every unselected tab pointing at an element that does not exist, and would throw away DOM state — a half-filled form in a panel would lose its values on each tab switch. The cost is a heavier DOM when panels are large; the answer to that is rendering less inside the panel, not unmounting it behind the consumer's back. `tabIndex={0}` because a panel whose content has no focusable element would otherwise be unreachable by keyboard.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | Pairs this panel with the `Tab` of the same value. |\n| `children` | `ReactNode` | — | yes | The view for this tab. Rendered even when unselected, then `hidden`. |\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 panel element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | The panel itself is a tab stop (tabIndex=0), so a panel whose content has no focusable element is still reachable. |\n\nRenders role=\"tabpanel\" with aria-labelledby pointing back at its tab. Unselected panels stay in the DOM with `hidden`.\n\n## Theming\n\nThis component has no `--psi-tab-panel-*` 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": [
@@ -3387,11 +3564,45 @@
      "orientation": "{param:orientation}"
     },
     "slots": {
-     "list": [
-      "{content:tabs-note}"
-     ],
-     "panels": [
-      "{content:panels-note}"
+     "body": [
+      {
+       "component": "TabList",
+       "props": {
+        "aria-label": "Views"
+       },
+       "slots": {
+        "body": [
+         {
+          "component": "Tab",
+          "props": {
+           "value": "all"
+          },
+          "content": "first-label"
+         },
+         {
+          "component": "Tab",
+          "props": {
+           "value": "flagged"
+          },
+          "content": "second-label"
+         }
+        ]
+       }
+      },
+      {
+       "component": "TabPanel",
+       "props": {
+        "value": "all"
+       },
+       "content": "first-panel"
+      },
+      {
+       "component": "TabPanel",
+       "props": {
+        "value": "flagged"
+       },
+       "content": "second-panel"
+      }
      ]
     }
    },
@@ -3407,14 +3618,14 @@
     }
    ],
    "content": {
-    "tabs-note": "[one tab per view; keep labels to one or two words]",
-    "panels-note": "[one panel per tab, in the same order]"
+    "first-label": "All",
+    "second-label": "Flagged",
+    "first-panel": "[the default view]",
+    "second-panel": "[the second view; one panel per tab, paired by value]"
    },
-   "gaps": [
-    "Tabs"
-   ],
-   "blocked": true,
-   "preset": null
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Tabs\n  orientation=\"horizontal\"\n>\n  <TabList\n    aria-label=\"Views\"\n  >\n    <Tab value=\"all\">All</Tab>\n    <Tab value=\"flagged\">Flagged</Tab>\n  </TabList>\n  <TabPanel value=\"all\">[the default view]</TabPanel>\n  <TabPanel value=\"flagged\">[the second view; one panel per tab, paired by value]</TabPanel>\n</Tabs>\n"
   },
   {
    "id": "table-pagination",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handamade/psi-mcp",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "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.12.0",
-    "@handamade/psi-react": "0.12.0"
+    "@handamade/psi-tokens": "0.13.1",
+    "@handamade/psi-react": "0.13.1"
   },
   "scripts": {
     "build": "tsx scripts/build-index.ts && tsc -p tsconfig.build.json"