@grampro/kit 2.6.2 → 2.7.0

package/source/components/tabs/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.2",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/index.ts",
       "core/navigation.ts",
@@ -23,6 +23,7 @@
     ],
     "sourceHash": "sha256:3d8e29857c59101e547f234c45735db68cc87ee143cc87d841372ec612e2c663"
   },
+  "purpose": "Tabs in underline, pill or segmented styles, horizontal or vertical, with panels that can stay mounted when hidden.",
   "props": [
     {
       "name": "activation",
@@ -36,7 +37,8 @@
       "default": "automatic",
       "origin": "derived",
       "description": "Default `automatic`: arrow keys select as they move.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "`automatic` selects as focus moves; `manual` waits for Enter or Space."
     },
     {
       "name": "aria-describedby",
@@ -143,7 +145,8 @@
       "default": false,
       "origin": "derived",
       "description": "Overrides `keepMounted` on `Tabs` for this panel.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Keeps hidden panels in the DOM, so form state and scroll position survive a switch. Costs the render."
     },
     {
       "name": "name",
@@ -300,20 +303,58 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the tabs pattern: role=tablist with one tab stop, arrow keys between tabs, Home and End to the ends",
+      "each tab is linked to its panel by aria-controls and aria-labelledby",
+      "`activation` chooses whether moving focus selects, or whether Enter is needed"
+    ],
+    "required": [
+      "tab labels that make sense read out of context, since that is how they are announced",
+      "manual `activation` when switching a tab is expensive, so arrowing past one does not load it"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "TabList",
+      "Tab",
+      "TabPanel"
+    ],
+    "notes": "Every Tab needs a TabPanel with the matching value. Tabs are not a substitute for navigation between URLs."
   },
-  "composition": {},
   "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "size",
+      "orientation",
+      "icon",
+      "badge",
+      "keepMounted",
+      "activation"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "onValueChange",
+      "name",
+      "disabled"
+    ],
+    "rationale": "Styling and layout are safe. The selected tab is application state."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 11,
     "propsDescribed": 9,
     "describedPct": 82,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/tabs/passport.manual.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Tabs",
+  "purpose": "Tabs in underline, pill or segmented styles, horizontal or vertical, with panels that can stay mounted when hidden.",
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "accessibility": {
+    "supplied": [
+      "the tabs pattern: role=tablist with one tab stop, arrow keys between tabs, Home and End to the ends",
+      "each tab is linked to its panel by aria-controls and aria-labelledby",
+      "`activation` chooses whether moving focus selects, or whether Enter is needed"
+    ],
+    "required": [
+      "tab labels that make sense read out of context, since that is how they are announced",
+      "manual `activation` when switching a tab is expensive, so arrowing past one does not load it"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "TabList",
+      "Tab",
+      "TabPanel"
+    ],
+    "notes": "Every Tab needs a TabPanel with the matching value. Tabs are not a substitute for navigation between URLs."
+  },
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "size",
+      "orientation",
+      "icon",
+      "badge",
+      "keepMounted",
+      "activation"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "onValueChange",
+      "name",
+      "disabled"
+    ],
+    "rationale": "Styling and layout are safe. The selected tab is application state."
+  },
+  "propNotes": {
+    "keepMounted": "Keeps hidden panels in the DOM, so form state and scroll position survive a switch. Costs the render.",
+    "activation": "`automatic` selects as focus moves; `manual` waits for Enter or Space."
+  }
+}

package/source/components/textarea/core/agent.ts

@@ -0,0 +1,34 @@
+/*
+ * Textarea's agent contract.
+ *
+ * Identical to Input but for the element behind it, which is why both go
+ * through the same executor.
+ *
+ * Pure: no React, no DOM. The contract is what this instance will accept, and
+ * the validator in shared/core/agent decides everything from it. Build it from
+ * props on every render so that a field which has just become read-only stops
+ * accepting writes immediately.
+ */
+
+import type { FieldContract } from "../../shared/core/agent";
+
+export interface TextareaAgentProps {
+  label?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  maxLength?: number;
+}
+
+export function textareaContract(props: TextareaAgentProps = {}): FieldContract {
+  return {
+    component: "Textarea",
+    kind: "text",
+    operations: ["setValue", "clear", "focus"],
+    label: props.label,
+    disabled: props.disabled,
+    readOnly: props.readOnly,
+    required: props.required,
+    maxLength: props.maxLength,
+  };
+}

package/source/components/textarea/core/index.ts

@@ -2,3 +2,5 @@
 export { countCharacters } from "./count";
 export { fitHeight, heightForRows } from "./size";
 export type * from "./types";
+// The agent contract: what a model may ask this field to do.
+export { textareaContract, type TextareaAgentProps } from "./agent";

package/source/components/textarea/passport.json

@@ -8,8 +8,9 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.2",
+    "libraryVersion": "2.7.0",
     "files": [
+      "core/agent.ts",
       "core/count.ts",
       "core/index.ts",
       "core/size.ts",
@@ -19,8 +20,9 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:a586004558fc7c4059756daa252c36028f3f9b1f4cf55fcccb9b5af2ce1e21e9"
+    "sourceHash": "sha256:161bed57c97bbdede609bde754dcbae8452083825fea7749ee035ce1ace510dc"
   },
+  "purpose": "A multi-line text field that can grow with its content, with the same label, hint, error and counter wiring as Input.",
   "props": [
     {
       "name": "aria-describedby",
@@ -58,7 +60,8 @@
       "default": false,
       "origin": "derived",
       "description": "Grow and shrink with the text, between `minRows` and `maxRows`. Default false.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Grows the field to its content between `minRows` and `maxRows`. Ignored when `resize` lets the user drag."
     },
     {
       "name": "className",
@@ -369,20 +372,90 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the label is a real <label> bound to the textarea",
+      "description and error are linked by aria-describedby",
+      "aria-invalid while `error` is set",
+      "the character counter is announced as a live region when `showCount` is on"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the field is visually unlabelled",
+      "a `maxLength` that matches whatever the server enforces, so the counter does not promise room that does not exist"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "label",
+      "textarea"
+    ],
+    "notes": "It renders its own <label> and <textarea>; wrapping it in a second label misbinds the text."
+  },
+  "operations": {
+    "setValue": {
+      "summary": "Write a value into the field, as though a person had entered it.",
+      "effects": [
+        "replaces the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "clear": {
+      "summary": "Empty the field.",
+      "effects": [
+        "discards the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    }
+  },
+  "intentDomains": [
+    "ActionIntent",
+    "Summarization"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placeholder",
+      "description",
+      "rows",
+      "minRows",
+      "maxRows",
+      "autoResize",
+      "resize",
+      "showCount"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "required",
+      "disabled",
+      "readOnly",
+      "maxLength",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "Height and hints are presentation. `maxLength` is a contract with the server, and `error` is the host's validation result."
   },
-  "composition": {},
-  "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
   "examples": [],
   "coverage": {
     "propsTotal": 12,
     "propsDescribed": 10,
     "describedPct": 83,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "operations",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/textarea/passport.manual.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Textarea",
+  "purpose": "A multi-line text field that can grow with its content, with the same label, hint, error and counter wiring as Input.",
+  "intentDomains": [
+    "ActionIntent",
+    "Summarization"
+  ],
+  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap.",
+  "operations": {
+    "setValue": {
+      "summary": "Write a value into the field, as though a person had entered it.",
+      "effects": [
+        "replaces the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "clear": {
+      "summary": "Empty the field.",
+      "effects": [
+        "discards the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    }
+  },
+  "accessibility": {
+    "supplied": [
+      "the label is a real <label> bound to the textarea",
+      "description and error are linked by aria-describedby",
+      "aria-invalid while `error` is set",
+      "the character counter is announced as a live region when `showCount` is on"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the field is visually unlabelled",
+      "a `maxLength` that matches whatever the server enforces, so the counter does not promise room that does not exist"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "label",
+      "textarea"
+    ],
+    "notes": "It renders its own <label> and <textarea>; wrapping it in a second label misbinds the text."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placeholder",
+      "description",
+      "rows",
+      "minRows",
+      "maxRows",
+      "autoResize",
+      "resize",
+      "showCount"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "required",
+      "disabled",
+      "readOnly",
+      "maxLength",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "Height and hints are presentation. `maxLength` is a contract with the server, and `error` is the host's validation result."
+  },
+  "propNotes": {
+    "autoResize": "Grows the field to its content between `minRows` and `maxRows`. Ignored when `resize` lets the user drag."
+  }
+}

package/source/components/toaster/passport.json

@@ -11,7 +11,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.2",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/api.ts",
       "core/index.ts",
@@ -28,6 +28,7 @@
     ],
     "sourceHash": "sha256:976553d5d606c12b441caba76badad73812eea6dde400b51eb3ee17d05db7871"
   },
+  "purpose": "Short notifications you mount once and call from anywhere, with no hook, context or provider. For things that happened, not things that must be decided.",
   "props": [
     {
       "name": "className",
@@ -102,7 +103,8 @@
       "required": false,
       "origin": "derived",
       "description": "Open toasts on screen at once; the rest wait their turn. Default 3.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "How many are visible at once; the rest queue rather than being dropped."
     },
     {
       "name": "localeText",
@@ -204,20 +206,51 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "a live region that announces new toasts without moving focus",
+      "a hotkey to jump to the toast region, for keyboard users who heard one arrive",
+      "the close button is reachable and labelled",
+      "timers pause on hover and on focus, so a toast cannot expire while it is being read"
+    ],
+    "required": [
+      "never put the only copy of something important in a toast — it leaves",
+      "a `duration` long enough to read the message, or none at all when it carries an action"
+    ]
+  },
+  "composition": {
+    "notes": "Mount one Toaster near the root. A second one gives two live regions and duplicate announcements; the store is module-level, so one is all that is needed."
   },
-  "composition": {},
   "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
+  "intentDomains": [
+    "Summarization",
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "position",
+      "duration",
+      "closeButton",
+      "icons",
+      "limit",
+      "dir"
+    ],
+    "forbidden": [
+      "store",
+      "hotkey"
+    ],
+    "rationale": "Placement and timing are presentation. `store` is the module-level queue; replacing it detaches every existing `toast()` call from the thing on screen."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 8,
     "propsDescribed": 8,
     "describedPct": 100,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/toaster/passport.manual.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Toaster",
+  "purpose": "Short notifications you mount once and call from anywhere, with no hook, context or provider. For things that happened, not things that must be decided.",
+  "intentDomains": [
+    "Summarization",
+    "ActionIntent"
+  ],
+  "accessibility": {
+    "supplied": [
+      "a live region that announces new toasts without moving focus",
+      "a hotkey to jump to the toast region, for keyboard users who heard one arrive",
+      "the close button is reachable and labelled",
+      "timers pause on hover and on focus, so a toast cannot expire while it is being read"
+    ],
+    "required": [
+      "never put the only copy of something important in a toast — it leaves",
+      "a `duration` long enough to read the message, or none at all when it carries an action"
+    ]
+  },
+  "composition": {
+    "notes": "Mount one Toaster near the root. A second one gives two live regions and duplicate announcements; the store is module-level, so one is all that is needed."
+  },
+  "safeMutations": {
+    "allowed": [
+      "position",
+      "duration",
+      "closeButton",
+      "icons",
+      "limit",
+      "dir"
+    ],
+    "forbidden": [
+      "store",
+      "hotkey"
+    ],
+    "rationale": "Placement and timing are presentation. `store` is the module-level queue; replacing it detaches every existing `toast()` call from the thing on screen."
+  },
+  "propNotes": {
+    "limit": "How many are visible at once; the rest queue rather than being dropped."
+  }
+}

package/source/components/tooltip/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.2",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/index.ts",
       "core/types.ts",
@@ -19,6 +19,7 @@
     ],
     "sourceHash": "sha256:b7a7aefbc8fcb4c9f4063dd0bc312ca2316ac848946c3055c8e69a8fe8780916"
   },
+  "purpose": "A short label on hover or keyboard focus, with a delay, Escape to dismiss, and the accessibility wiring that makes it readable rather than decorative.",
   "props": [
     {
       "name": "align",
@@ -151,20 +152,52 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the trigger is described by the tooltip, so it is announced with the control rather than as stray text",
+      "it opens on keyboard focus, not only on hover",
+      "Escape dismisses it without moving focus",
+      "a delay before opening, so moving the pointer across a toolbar does not flash every label"
+    ],
+    "required": [
+      "never put essential information only in a tooltip — it is unreachable on touch and gone on blur",
+      "an interactive trigger. A tooltip on a non-focusable element cannot be reached by keyboard"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "button",
+      "a",
+      "input"
+    ],
+    "notes": "Tooltip content must not be interactive: it disappears on blur, so nothing inside it can be reached. Use a Popover when the panel has controls."
   },
-  "composition": {},
   "operations": {},
   "intentDomains": [],
-  "safeMutations": {},
+  "safeMutations": {
+    "allowed": [
+      "side",
+      "align",
+      "gap",
+      "delay",
+      "closeDelay"
+    ],
+    "forbidden": [
+      "content",
+      "disabled",
+      "children"
+    ],
+    "rationale": "Placement and timing are presentation. The content is the message."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 9,
     "propsDescribed": 7,
     "describedPct": 78,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/tooltip/passport.manual.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Tooltip",
+  "purpose": "A short label on hover or keyboard focus, with a delay, Escape to dismiss, and the accessibility wiring that makes it readable rather than decorative.",
+  "intentDomains": [],
+  "accessibility": {
+    "supplied": [
+      "the trigger is described by the tooltip, so it is announced with the control rather than as stray text",
+      "it opens on keyboard focus, not only on hover",
+      "Escape dismisses it without moving focus",
+      "a delay before opening, so moving the pointer across a toolbar does not flash every label"
+    ],
+    "required": [
+      "never put essential information only in a tooltip — it is unreachable on touch and gone on blur",
+      "an interactive trigger. A tooltip on a non-focusable element cannot be reached by keyboard"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "button",
+      "a",
+      "input"
+    ],
+    "notes": "Tooltip content must not be interactive: it disappears on blur, so nothing inside it can be reached. Use a Popover when the panel has controls."
+  },
+  "safeMutations": {
+    "allowed": [
+      "side",
+      "align",
+      "gap",
+      "delay",
+      "closeDelay"
+    ],
+    "forbidden": [
+      "content",
+      "disabled",
+      "children"
+    ],
+    "rationale": "Placement and timing are presentation. The content is the message."
+  }
+}

package/tools/mcp/README.md

@@ -127,7 +127,15 @@ invention, and this catches it:
 
 ## A whole design at once
 
-Install [Grampro Kit from the Figma Community](https://www.figma.com/community/plugin/1692828324805361551). Then
+Install [Grampro Kit from the Figma Community](https://www.figma.com/community/plugin/1692828324805361551).
+
+> The listing is in review, which Figma is quoting at a few weeks. Until it
+> clears: clone the repository and, in the Figma **desktop** app, use
+> **Plugins → Development → Import plugin from manifest...** on
+> `figma-plugin/manifest.json`. The build is committed, so there is nothing
+> to compile.
+
+Then
 **Grampro Kit → Export all screens for an agent** walks every
 page and exports each top-level frame, with one set of theme values read
 across the whole design rather than guessed per frame. Save it, then:

package/tools/mcp/design.cjs

@@ -67,7 +67,12 @@ function splitDesign(file, dest) {
   try {
     design = JSON.parse(fs.readFileSync(source, "utf8").replace(/^/, ""));
   } catch (error) {
-    return { error: `${source} is not JSON: ${error.message}` };
+    // The parse error carries a slice of the file; name the file instead.
+    return {
+      error:
+        `${source} is not JSON. Expected the Figma plugin's export — ` +
+        "run Grampro Kit -> Export all screens for an agent and save that.",
+    };
   }
 
   /*