@grampro/kit 2.4.4 → 2.6.0

package/source/components/tabs/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/navigation.ts",
@@ -21,7 +21,7 @@
       "react/Tabs.tsx",
       "react/context.ts"
     ],
-    "sourceHash": "sha256:af648a096e1a1c4e3f61c57b4e61a6c115c3d2351d5f2c8c6b4519348ae80dfc"
+    "sourceHash": "sha256:3d8e29857c59101e547f234c45735db68cc87ee143cc87d841372ec612e2c663"
   },
   "props": [
     {
@@ -124,7 +124,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "An icon before the tab's text.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "id",
@@ -155,7 +157,9 @@
       "type": "function",
       "signature": "((value: string) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The newly selected tab. Not fired when the same tab is clicked again.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "orientation",
@@ -305,9 +309,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 25,
-    "propsDescribed": 7,
-    "describedPct": 28,
+    "propsTotal": 11,
+    "propsDescribed": 9,
+    "describedPct": 82,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/tabs/react/Tabs.tsx

@@ -33,6 +33,7 @@ export interface TabsProps extends Omit<
   value?: string;
   /** Selected tab at first. Without either, the first enabled tab is selected. */
   defaultValue?: string;
+  /** The newly selected tab. Not fired when the same tab is clicked again. */
   onValueChange?(value: string): void;
   /** Default `horizontal`. */
   orientation?: TabsOrientation;
@@ -221,6 +222,7 @@ export interface TabProps extends Omit<
 > {
   /** Identifies the tab and its panel. */
   value: string;
+  /** An icon before the tab's text. */
   icon?: ReactNode;
   /** A small count or label after the text, e.g. unread items. */
   badge?: ReactNode;

package/source/components/textarea/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/count.ts",
       "core/index.ts",
@@ -19,7 +19,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:35a538fdd2522c310be181bbb598fdc6eebb99fc5dd1a0ffab3cccf8d84ac43a"
+    "sourceHash": "sha256:a586004558fc7c4059756daa252c36028f3f9b1f4cf55fcccb9b5af2ce1e21e9"
   },
   "props": [
     {
@@ -93,7 +93,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A hint under the label, linked as the field's description.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "disabled",
@@ -137,7 +139,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The field's name, shown above it and linked to it.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "localeText",
@@ -267,7 +271,9 @@
       "typeText": "FieldSize | undefined",
       "required": false,
       "default": "md",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "style",
@@ -372,9 +378,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 35,
-    "propsDescribed": 8,
-    "describedPct": 23,
+    "propsTotal": 12,
+    "propsDescribed": 10,
+    "describedPct": 83,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/textarea/react/Textarea.tsx

@@ -28,10 +28,13 @@ export interface TextareaProps
   defaultValue?: string;
   /** The new text on every change. The native `onChange` fires as well. */
   onValueChange?(value: string): void;
+  /** The field's name, shown above it and linked to it. */
   label?: ReactNode;
+  /** A hint under the label, linked as the field's description. */
   description?: ReactNode;
   /** Message below the field; also marks it invalid. */
   error?: ReactNode;
+  /** Default `md`. */
   size?: FieldSize;
   /** Grow and shrink with the text, between `minRows` and `maxRows`. Default false. */
   autoResize?: boolean;

package/source/components/toaster/passport.json

@@ -11,7 +11,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/api.ts",
       "core/index.ts",
@@ -26,7 +26,7 @@
       "react/props.ts",
       "react/useToasts.ts"
     ],
-    "sourceHash": "sha256:ac828195f4d7ced89c99eb2bd78bb2581ba7a81d62dcfb892b9acef75bddda77"
+    "sourceHash": "sha256:976553d5d606c12b441caba76badad73812eea6dde400b51eb3ee17d05db7871"
   },
   "props": [
     {
@@ -63,7 +63,9 @@
       ],
       "typeText": "'ltr' | 'rtl' | 'auto' | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Writing direction, which decides which corner `position` means.\nDefault `auto`, taken from the document.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "duration",
@@ -211,9 +213,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 12,
-    "propsDescribed": 7,
-    "describedPct": 58,
+    "propsTotal": 8,
+    "propsDescribed": 8,
+    "describedPct": 100,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/toaster/react/Toaster.tsx

@@ -36,6 +36,10 @@ export interface ToasterProps {
   icons?: Partial<Record<ToastType, ReactNode>>;
   /** A store from `createToastStore()`. Defaults to the one behind `toast()`. */
   store?: ToastStore;
+  /**
+   * Writing direction, which decides which corner `position` means.
+   * Default `auto`, taken from the document.
+   */
   dir?: "ltr" | "rtl" | "auto";
   className?: string;
   classNames?: Partial<Record<ToasterSlot, string>>;

package/source/components/tooltip/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/types.ts",
@@ -160,9 +160,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 12,
+    "propsTotal": 9,
     "propsDescribed": 7,
-    "describedPct": 58,
+    "describedPct": 78,
     "authoredSections": [
       "accessibility"
     ]

package/tools/mcp/README.md

@@ -4,31 +4,90 @@ Serves the component catalogue to a coding agent, so it writes against the
 real contract instead of recalling one.
 
 > **Beta.** The tools work and are tested, but their names and shapes may
-> change before this settles. The Figma token handling in particular is not
-> where it should be — see *Credentials* below.
+> change before this settles.
+
+## Setup
+
+```bash
+npx @grampro/kit mcp install
+```
+
+That writes the configuration for every agent it knows about — Claude Code,
+Codex and Cursor — and tells you which files it touched. Restrict it with
+`--for codex` (or `claude`, `cursor`, or a comma-separated list).
+
+It is worth using rather than editing the files by hand: it writes UTF-8
+without a byte-order mark and with LF endings, which is the one thing that
+reliably goes wrong. PowerShell's `Out-File -Encoding utf8` adds a BOM, and
+every JSON parser then rejects the file with an error that names the first
+character and explains nothing.
+
+Running it again is safe. It merges into whatever is already there, leaves
+other servers alone, and says `unchanged` when there is nothing to do.
+
+It writes to the project root — the nearest folder up from you with a `.git`
+or a `package.json` — and prints which one it chose, because an agent reads
+these files from the folder it has open and writing to a subdirectory is the
+one way this can quietly do nothing.
+
+### If the server does not appear
+
+The file being written is not the same as the server being loaded, and in
+Claude Code two things stand between them.
+
+**It needs approving.** A `.mcp.json` server is project-scoped, and Claude
+Code asks before trusting one — until you say yes it sits at `Pending
+approval`, and nothing asks twice. `claude mcp reset-project-choices` brings
+the prompt back if it was dismissed.
+
+**It needs a fresh session.** The configuration is read when a session
+starts, so an editor window that was already open sees nothing. In the VS
+Code extension, run *Developer: Reload Window*.
+
+`/mcp` lists the servers and their state, which is the quickest way to tell
+"not configured" from "configured, not approved".
+
+To skip both, install it for yourself rather than for the project:
+
+```bash
+claude mcp add -s user grampro -- npx -y @grampro/kit mcp
+```
+
+User scope lives in `~/.claude.json`, loads in every project, and needs no
+approval because it is yours rather than the repository's. Project scope is
+the better choice when you want the rest of the team to get it from a commit.
+
+### What it writes
+
+| agent | file | format |
+| --- | --- | --- |
+| Claude Code | `.mcp.json` | `mcpServers.grampro` |
+| Codex | `.codex/config.toml` | `[mcp_servers.grampro]` |
+| Cursor | `.cursor/mcp.json` | `mcpServers.grampro` |
+
+The Codex config is project-scoped. For every project instead, put the same
+`[mcp_servers.grampro]` block in `~/.codex/config.toml`.
+
+A project that already has the package installed gets a direct `node`
+invocation; anywhere else the config uses `npx -y @grampro/kit mcp`, which
+works without an install but re-resolves the package on every start.
+
+### By hand, if you prefer
 
 ```bash
 claude mcp add grampro -- npx -y @grampro/kit mcp
 ```
 
-Codex, Cursor and anything else that speaks MCP take the same command; it is
-a stdio server with no configuration. Without the CLI, write `.mcp.json` in
-your project:
-
-```json
-{
-  "mcpServers": {
-    "grampro": {
-      "command": "node",
-      "args": ["node_modules/@grampro/kit/index.cjs", "mcp"]
-    }
-  }
-}
+```toml
+# ~/.codex/config.toml
+[mcp_servers.grampro]
+command = "npx"
+args = ["-y", "@grampro/kit", "mcp"]
 ```
 
 MCP servers are not invoked by name. There is no `/grampro`; the model calls
-the tools itself when they are relevant. Use `/mcp` to check the server is
-connected.
+the tools itself when they are relevant. In Claude Code, `/mcp` shows whether
+the server connected.
 
 ## Why
 
@@ -49,7 +108,7 @@ document pasted into the prompt.
 | `get_component` | Props with types and allowed values, which are required, handler signatures, slots, states, composition rules |
 | `get_example` | Working usage from the component's README |
 | `get_guidance` | Authored notes on forms, overlays, the grid, pickers, styling, accessibility |
-| `figma_frame` | A design's structure, text, repeated regions and theme variables |
+| `figma_frame` | A design's structure, text, repeated regions and theme variables, from a `designFile` path, a pasted `design`, or a Figma `url` |
 | `install_component` | Copies components into the project being worked in |
 | `validate_usage` | Whether the JSX an agent wrote matches the passports |
 
@@ -66,18 +125,55 @@ invention, and this catches it:
   dismissible — not a prop of this component. Did you mean: onDismiss
 ```
 
+## A whole design at once
+
+In Figma, **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:
+
+```bash
+npx @grampro/kit design ./design.json
+```
+
+```text
+Wrote 3 screen(s) to design/
+  purchase-orders.json         Purchase orders (Product) — 22 nodes
+  suppliers.json               Suppliers (Product) — 16 nodes
+  settings.json                Settings (Admin) — 12 nodes
+  index.json                   the plan: every screen, shared theme
+```
+
+A browser cannot write a directory and a plugin is an iframe, so the
+plugin hands over one file and the CLI does the filesystem work. Each
+screen is written in the shape a single-frame export has, so `figma_frame`
+reads one with `designFile` and no special case.
+
+`index.json` is the plan: every screen with its size, node count and
+repeated regions, plus the shared theme. Have an agent map regions to
+components from that and correct it before any code exists — a guess that
+`Action` is a Card rather than a Button costs one sentence there and five
+screens of rework later. Then build one screen at a time, validating each.
+
 ## From a Figma design
 
-Two routes, and the second needs no credentials.
+Three routes, and only the first needs credentials.
 
 **By URL.** Pass a `figma.com/design/...` link. Called with just the URL it
 lists the frames in the file; called again with `frame` it returns that
-screen. Needs a token.
+screen. A link that already carries a `node-id` — which is what Figma copies
+when you right-click a frame — skips straight to that frame in one call.
+Needs a token.
 
 **By plugin export.** In Figma, run **Grampro Kit → Export selection for an
 agent**, then pass the JSON as `design`. The plugin reads the scene graph
-directly, so this works on any file you can open and asks for no token at
-all.
+directly, so this works on any file you can open, asks for no token, and
+never touches the REST API — which also means it cannot be rate limited.
+
+**By file.** Press **Save .json** in that panel and pass the path as
+`designFile`. Prefer this for anything but a small frame: a chat input
+caps at around fifty thousand characters, and a pasted export sits in the
+conversation twice — once as the argument, again inside the tool call —
+where a file appears only in the answer.
 
 Either way the answer is the same shape: the structure, the text, the
 regions whose names repeat — eight `Status cell` nodes are a column — and
@@ -94,21 +190,51 @@ is the body text, and a near-black navy scores high on saturation, so both
 "most common" and "most saturated" pick the wrong thing. Lightness and
 saturation together find the accent.
 
+### Rate limits
+
+Figma's limits on file reads are cost-based, and the cost is the size of the
+response. Asking for a whole file to answer a question about one frame is
+what earns a 429, and the lockout is long — a `Retry-After` of 395274 has
+been observed on a single token.
+
+So nothing here fetches a whole file. Listing the frames uses `depth=1`,
+which returns the document's outline rather than its contents, and the frame
+itself is then fetched by id. A URL carrying a `node-id` skips the listing
+altogether. Responses are held for five minutes, so the natural two-call
+flow — list, then read — costs one listing and one frame.
+
+If a token is already locked out, the plugin export route still works.
+
 ## Credentials
 
-**This is the weakest part of the current design, and it is temporary.**
+The URL route needs a Figma personal access token. Store it where the
+operating system keeps credentials:
 
-The URL route reads `FIGMA_TOKEN` from the environment, or from a `.env`
-file beside the project. That means a long-lived credential sitting in a
-file, which is not where it belongs.
+```bash
+npx @grampro/kit secret set figma
+```
 
-A future release will keep it in the editor's own secret storage — VS Code's
-`SecretStorage` for the extension, and the equivalent elsewhere — so the
-token is held by the host rather than the repository. Until then:
+It prompts, with the echo off, and never takes the value as an argument —
+arguments land in shell history and in every process listing on the machine.
+Piping works too, for a script: `echo "$TOKEN" | npx @grampro/kit secret set figma`.
 
-- prefer the plugin export route, which needs no token at all;
-- if you do use a token, give it only `File content: read`;
-- keep `.env` out of version control.
+| platform | where it goes |
+| --- | --- |
+| Windows | Data Protection API, tied to your Windows account |
+| macOS | the keychain |
+| Linux | Secret Service (GNOME Keyring, KWallet) |
+| anything else | a 0600 file in your config directory, and it says so |
+
+`secret list` shows what is stored, masked, and names the backend in use.
+`secret remove figma` deletes it. Create the token at Figma → Settings →
+Security → Personal access tokens, with `File content: read` and nothing
+else.
+
+The token is read from `FIGMA_TOKEN` in the environment first, then the
+store, then a `.env` — the last only so that an upgrade does not break a
+project set up the old way. Reading from a `.env` prints a note saying to
+move it. A credential in a file inside a working tree is one `git add -A`
+away from being published, which is why this moved.
 
 ## Suggested use
 
@@ -123,10 +249,11 @@ No dependencies. MCP is newline-delimited JSON-RPC over stdio, which is a
 few hundred lines, and a server shipped inside a library that every consumer
 installs should not drag an SDK along with it.
 
+Start-up is about the cost of an empty Node process. An agent spawns the
+server once per session, and `index.cjs` routes `mcp` before loading the
+CLI's own dependencies, which are no use to a JSON-RPC loop and cost around
+70ms. The passports are indexed on the first question and not re-read after.
+
 The catalogue it serves is the one in this package, not the components
 copied into your project — so an agent can see a component before you
 install it, and `install_component` puts it in place.
-
-A Figma file is fetched once and held for five minutes. The natural flow is
-two calls, list then read, and refetching a large file in between is what
-earns a rate limit.

package/tools/mcp/design.cjs

@@ -0,0 +1,154 @@
+/*
+ * `grampro-kit design <file>` — a whole-file Figma export, split into a folder.
+ *
+ * The plugin downloads one file because a browser cannot write a directory.
+ * Splitting it is filesystem work, which belongs in the CLI rather than in a
+ * plugin iframe, and it is what makes the result usable: an agent reads the
+ * index to plan, then opens one screen at a time, instead of loading every
+ * screen to build any of them.
+ *
+ * Each screen is written in the same shape a single-frame export has, so
+ * `figma_frame` reads one with no special case.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { themeFrom } = require("./figma.cjs");
+
+/** A file name from a screen name: lowercase, dashes, nothing exotic. */
+const slug = (name) =>
+  String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "") || "screen";
+
+/** Names a designer repeated are the ones that mean something. */
+function countNames(node, counts) {
+  counts.set(node.name, (counts.get(node.name) || 0) + 1);
+  for (const child of node.children || []) countNames(child, counts);
+}
+
+const repeatedIn = (nodes) => {
+  const counts = new Map();
+  for (const node of nodes) countNames(node, counts);
+  return [...counts.entries()]
+    .filter(([, n]) => n > 2)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 12)
+    .map(([name, times]) => ({ name, times }));
+};
+
+/** Component instances found anywhere in a screen. */
+function componentsIn(nodes) {
+  const found = new Set();
+  const visit = (node) => {
+    if (node.component) found.add(node.component);
+    for (const child of node.children || []) visit(child);
+  };
+  for (const node of nodes) visit(node);
+  return [...found];
+}
+
+const countNodes = (nodes) =>
+  nodes.reduce((n, node) => n + 1 + countNodes(node.children || []), 0);
+
+/**
+ * Split an export into `dest`.
+ *
+ * Returns what it wrote rather than printing, so the CLI owns the words and
+ * this stays testable.
+ */
+function splitDesign(file, dest) {
+  const source = path.resolve(file);
+  if (!fs.existsSync(source)) return { error: `No file at ${source}.` };
+
+  let design;
+  try {
+    design = JSON.parse(fs.readFileSync(source, "utf8").replace(/^/, ""));
+  } catch (error) {
+    return { error: `${source} is not JSON: ${error.message}` };
+  }
+
+  /*
+   * A single-frame export is accepted too, as one screen. Someone who ran the
+   * wrong menu item should get a folder, not a lecture.
+   */
+  const screens = Array.isArray(design.screens)
+    ? design.screens
+    : Array.isArray(design.nodes)
+      ? [{ name: design.frame || "screen", page: "", nodes: design.nodes }]
+      : null;
+
+  if (!screens) {
+    return {
+      error:
+        "Expected the output of the Figma plugin's 'Export all screens for an agent' " +
+        "(or 'Export selection'). This file has neither `screens` nor `nodes`.",
+    };
+  }
+  if (screens.length === 0) return { error: "That export contains no screens." };
+
+  const out = path.resolve(dest);
+  fs.mkdirSync(out, { recursive: true });
+
+  const tokens = design.tokens || {};
+  const colours = new Map((tokens.colours || []).map((c) => [c.value, c.uses]));
+  const radii = new Map((tokens.radii || []).map((r) => [r.value, r.uses]));
+  const fontSizes = new Map((tokens.fontSizes || []).map((f) => [f.value, f.uses]));
+
+  const taken = new Set();
+  const written = [];
+
+  for (const screen of screens) {
+    // Two screens may share a name across pages; the second gets a suffix
+    // rather than quietly overwriting the first.
+    let name = slug(screen.name);
+    if (taken.has(name)) {
+      let n = 2;
+      while (taken.has(`${name}-${n}`)) n += 1;
+      name = `${name}-${n}`;
+    }
+    taken.add(name);
+
+    const fileName = `${name}.json`;
+    fs.writeFileSync(
+      path.join(out, fileName),
+      `${JSON.stringify({ frame: screen.name, nodes: screen.nodes, tokens }, null, 2)}\n`,
+      "utf8",
+    );
+
+    written.push({
+      name: screen.name,
+      page: screen.page || undefined,
+      file: fileName,
+      size: screen.size,
+      nodes: countNodes(screen.nodes),
+      repeatedRegions: repeatedIn(screen.nodes),
+      componentsNamed: componentsIn(screen.nodes),
+    });
+  }
+
+  /*
+   * The index is what an agent reads first: every screen, how big it is, the
+   * regions whose names repeat, and one theme for all of them. Enough to
+   * propose a component for each region before any code is written, which is
+   * where a wrong guess is cheap to correct.
+   */
+  const index = {
+    screens: written,
+    theme: themeFrom(colours, radii, fontSizes),
+    builtFromLibrary: written.some((s) => s.componentsNamed.length > 0),
+    howToUse:
+      "Read this index first and say which kit component each repeated region maps to, " +
+      "so the mapping can be corrected before any screen is built. Then take one screen " +
+      "at a time: figma_frame with designFile set to its file, get_component for each " +
+      "component before writing it, install_component for what is missing, and " +
+      "validate_usage on the JSX before moving to the next screen.",
+  };
+  fs.writeFileSync(path.join(out, "index.json"), `${JSON.stringify(index, null, 2)}\n`, "utf8");
+
+  return { dest: out, index, written };
+}
+
+module.exports = { splitDesign, slug };