@grampro/kit 2.7.2 → 2.7.3

package/.gbs/skills/gbs-components/SKILL.md

@@ -1,209 +1,233 @@
----
-name: gbs-components
-description: Builds UI with the GramproKit component library (@grampro/kit). Use when adding or changing UI in apps that have a component-lib/ folder.
-autoAttach: ["src/**/*.tsx", "src/**/*.jsx", "app/**/*.tsx", "components/**/*.tsx"]
----
-
-# GBS components (2.x)
-
-## If the MCP server is connected
-
-This file is a summary. The `grampro` MCP server answers from passports
-generated from the component source, so where the two differ it is right
-and this is stale. When its tools are available:
-
-- **`get_component <Name>`** before writing a component — every prop with
-  its type, the values a union accepts, which props are required, handler
-  signatures. Do not write a prop you have not read there.
-- **`validate_usage`** on the JSX before reporting back. It catches props
-  invented from memory, which is the one failure a passport cannot prevent.
-- **`figma_frame`** to read a design, from a `designFile` path or a Figma
-  URL, when building from one.
-
-Neither needs the other installed. Without the server this file is what
-you have, and everything below still applies.
-## Install before you import
-
-Not an npm dependency — the CLI **copies source into the repo**:
-
-```bash
-npx @grampro/kit add Button,Input,Modal
-```
-
-Writes `component-lib/<folder>/` plus `component-lib/shared/`. No flag is
-needed: the 2.x components are the default. A component the project has
-edited is never overwritten — if `add` says it kept one, tell the user and
-suggest `npx @grampro/kit doctor <Component>`; **never retry with `--force`**,
-which discards their work. Import the barrel in your component:
-
-```ts
-import { Button } from "component-lib/button";
-```
-
-Styles are **one line** in the global CSS (Vite: `src/index.css`), never in a
-component file. The CLI generates `component-lib/gbs.css` listing every
-stylesheet you installed, and rewrites it on each install:
-
-```css
-@import "./component-lib/gbs.css";
-```
-
-With **Tailwind v4 only**, import it after the framework and into Tailwind's
-components layer, or utilities stop overriding component rules:
-
-```css
-@import "tailwindcss";
-@import "./component-lib/gbs.css" layer(components);
-```
-
-The installer prints whichever line applies. Component CSS is unlayered, so
-Tailwind v3, Bootstrap and no-framework projects need nothing extra.
-
-Folder = lowercased name, except `data-grid`, `date-picker`, `file-uploader`,
-`number-input`, `radio-group`.
-
-## Rules most often missed
-
-1. **Change handlers are named per component.** `onValueChange`: Input,
-   OtpInput, Textarea, NumberInput, CheckboxGroup, RadioGroup, Tabs, Accordion,
-   MenuRadioGroup. `onCheckedChange`: Checkbox, Switch, MenuCheckboxItem.
-   `onChange`: Select, MultiSelect, DatePicker, DateRangePicker, FileUploader.
-   `onOpenChange`: Modal, Popover, Menu.
-2. **Never hand-roll `<label>`, hint or error markup.** Fields take `label`,
-   `description` and `error`; `error` also marks the control invalid and wires
-   `aria-describedby`. A `<label>` wrapper breaks it.
-3. **Style via `classNames` slots** (`classNames={{ root, label }}`);
-   `className` hits the root only. Theme globally with `--gbs-*` on `:root`.
-4. **Mount `<Toaster />` and `<DialogHost />` once at the app root**, or
-   `toast()` and `dialog.confirm()` do nothing.
-5. **All are client components** (`"use client"`); a Next.js Server Component
-   can render them but not pass function props.
-6. **Compound families throw outside their parent**: Tab/TabList/TabPanel need
-   Tabs, AccordionItem needs Accordion, MenuItem needs Menu.
-
-## Inventory (required props in parens)
-
-**Forms** — Input, Textarea, NumberInput (locale-aware), OtpInput; Checkbox +
-CheckboxGroup; Radio (`value`) + RadioGroup; Switch (applies immediately);
-Select and MultiSelect (`options`; searchable, client or server); DatePicker and
-DateRangePicker; FileUploader (chunked).
-
-**Actions** — Button: variants, sizes, icons, auto-loading from a returned
-promise; `render` draws a router link.
-
-**Overlays** — Modal (native `<dialog>`, also drawers); `dialog` + DialogHost
-(`await dialog.confirm/alert/prompt`); Popover (`trigger`); Menu (`trigger`) with
-MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuGroup,
-MenuSeparator, MenuSub; Tooltip (`content`); `toast` + Toaster.
-
-**Data** — DataGrid (`data`, `columns`) + createColumnHelper: virtualized;
-sort, filter, edit, CSV/Excel/PDF export. Optional agent surface: `ai` renders a
-natural-language box, and `registerGridTool` exposes the grid to a browser agent
-over WebMCP (see "Agent surface").
-
-**Display** — Tabs/TabList/Tab (`value`)/TabPanel (`value`); Accordion +
-AccordionItem (`value`); Card/CardHeader/CardBody/CardFooter/Stat; Alert; Badge
-and Tag; Avatar and AvatarGroup; Progress and CircularProgress (`value={null}`
-is indeterminate); Skeleton and Empty; Spinner; Breadcrumb (`items`,
-`renderLink`).
-
-## Example
-
-```tsx
-"use client";
-import { useState } from "react";
-import { Button } from "component-lib/button";
-import { Input } from "component-lib/input";
-import { Select } from "component-lib/combobox";
-import { Modal } from "component-lib/modal";
-import { toast } from "component-lib/toaster";
-
-const ROLES = [{ value: "admin", label: "Admin" }, { value: "dev", label: "Dev" }];
-
-export function InviteButton() {
-  const [open, setOpen] = useState(false);
-  const [email, setEmail] = useState("");
-  const [role, setRole] = useState<string | null>(null);
-  const invalid = !!email && !email.includes("@");
-
-  return (
-    <>
-      <Button onClick={() => setOpen(true)}>Invite</Button>
-      <Modal open={open} onOpenChange={setOpen} title="Invite a teammate"
-        footer={({ close }) => (
-          <Button disabled={!email || invalid} onClick={async () => {
-            await invite({ email, role });
-            toast.success("Invitation sent");
-            close();
-          }}>Send</Button>
-        )}>
-        <Input label="Email" type="email" value={email} onValueChange={setEmail}
-          required error={invalid ? "Enter a valid email" : undefined} />
-        <Select label="Role" options={ROLES} value={role} onChange={setRole} />
-      </Modal>
-    </>
-  );
-}
-```
-
-## Agent surface (DataGrid, optional)
-
-Entirely opt-in. Without it, nothing changes and nothing is downloaded.
-
-**A person typing.** `ai` renders a box above the grid. It needs a provider
-supplying an adapter; with no provider it renders nothing at all.
-
-```tsx
-import { GramproAIProvider } from "component-lib/shared";
-import { DataGrid } from "component-lib/data-grid";
-
-<GramproAIProvider adapter={myAdapter}>
-  <DataGrid data={rows} columns={cols} ai semantics={SEMANTICS} />
-</GramproAIProvider>
-```
-
-`adapter` is one function — `(utterance, contract, responseSchema) => envelope`.
-No model is bundled, downloaded or named; the app brings its own, and the key
-belongs on the app's server, never in client JavaScript.
-
-**A browser agent.** `registerGridTool(agent)` registers one WebMCP tool,
-`operate_grid`, whose schema is generated from the live grid. Requires no model
-at all.
-
-**Both go through the same validator**, which refuses an unknown column, an
-operator the type lacks, a policy-denied column, or an irreversible operation
-with no confirmation — and returns the reason. A producer proposes; it never
-acts. Do not add repair, retries or a second execution path.
-
-**Data leaves the page with a remote adapter.** The contract carries real
-values from low-cardinality columns, so the model can map "Kerala" to `region`.
-Mark personal columns `semantics: { email: { pii: true } }` — a PII column is
-denied *and* never summarised — or pass `stats: false` to summarise nothing.
-`policy.denyFilter` does **not** stop a column being described.
-
-**`semantics` is where most quality comes from**: per column, give `synonyms`,
-`description`, `unit`, `higherIsBetter`, `pii`. Reach for it before reaching for
-a bigger model.
-
-## Don't
-
-- Raw `<button>`, `<input>`, `<select>`, `<table>`, `<dialog>`, or a hand-built
-  modal/menu/tooltip, when a component exists.
-- Deep imports (`.../input/react/Input`); import the barrel. Only `<name>/core`
-  is also public.
-- Editing `component-lib/shared/`; the CLI replaces it on update.
-- Invented props: no `asChild`, no `variant` on Input, no `onChange` on Switch.
-- `!important` or internal class selectors; set `--gbs-*` or pass `classNames`.
-- A Tooltip as a name; icon buttons need `aria-label`.
-
-## Details (in `references/`)
-
-- `install.md` — CLI flags, folders, 1.x vs 2.x.
-- `forms.md` — fields, controlled state, form posting.
-- `pickers.md` — Select, MultiSelect, DatePicker, Uploader.
-- `overlays.md` — Modal, dialog, Popover, Menu, Tooltip.
-- `toaster.md` — `toast()` and `<Toaster />`.
-- `data-grid.md` — columns, API, export.
-- `data-display.md` — Card, Tabs, Accordion, Badge, Avatar.
-- `styling.md` — tokens, layers, slots, `data-*`, dark.
-- `accessibility.md` — what is supplied, what you add.
+---
+name: gbs-components
+description: Builds UI with the GramproKit component library (@grampro/kit). Use when adding or changing UI in apps that have a component-lib/ folder.
+autoAttach: ["src/**/*.tsx", "src/**/*.jsx", "app/**/*.tsx", "components/**/*.tsx"]
+---
+
+# GBS components (2.x)
+
+## If the MCP server is connected
+
+This file is a summary. The `grampro` MCP server answers from passports
+generated from the component source, so where the two differ it is right
+and this is stale. When its tools are available:
+
+- **`get_component <Name>`** before writing a component — every prop with
+  its type, the values a union accepts, which props are required, handler
+  signatures. Do not write a prop you have not read there.
+- **`validate_usage`** on the JSX before reporting back. It catches props
+  invented from memory, which is the one failure a passport cannot prevent.
+- **`figma_frame`** to read a design, from a `designFile` path or a Figma
+  URL, when building from one.
+
+Neither needs the other installed. Without the server this file is what
+you have, and everything below still applies.
+## Install before you import
+
+Not an npm dependency — the CLI **copies source into the repo**:
+
+```bash
+npx @grampro/kit add Button,Input,Modal
+```
+
+Writes `component-lib/<folder>/` plus `component-lib/shared/`. No flag is
+needed: the 2.x components are the default. A component the project has
+edited is never overwritten — if `add` says it kept one, tell the user and
+suggest `npx @grampro/kit doctor <Component>`; **never retry with `--force`**,
+which discards their work. Import the barrel in your component:
+
+```ts
+import { Button } from "component-lib/button";
+```
+
+Styles are **one line** in the global CSS (Vite: `src/index.css`), never in a
+component file. The CLI generates `component-lib/gbs.css` listing every
+stylesheet you installed, and rewrites it on each install:
+
+```css
+@import "./component-lib/gbs.css";
+```
+
+With **Tailwind v4 only**, import it after the framework and into Tailwind's
+components layer, or utilities stop overriding component rules:
+
+```css
+@import "tailwindcss";
+@import "./component-lib/gbs.css" layer(components);
+```
+
+The installer prints whichever line applies. Component CSS is unlayered, so
+Tailwind v3, Bootstrap and no-framework projects need nothing extra.
+
+Folder = lowercased name, except `data-grid`, `date-picker`, `file-uploader`,
+`number-input`, `radio-group`.
+
+## Rules most often missed
+
+1. **Change handlers are named per component.** `onValueChange`: Input,
+   OtpInput, Textarea, NumberInput, CheckboxGroup, RadioGroup, Tabs, Accordion,
+   MenuRadioGroup. `onCheckedChange`: Checkbox, Switch, MenuCheckboxItem.
+   `onChange`: Select, MultiSelect, DatePicker, DateRangePicker, FileUploader.
+   `onOpenChange`: Modal, Popover, Menu.
+2. **Never hand-roll `<label>`, hint or error markup.** Fields take `label`,
+   `description` and `error`; `error` also marks the control invalid and wires
+   `aria-describedby`. A `<label>` wrapper breaks it.
+3. **Style via `classNames` slots** (`classNames={{ root, label }}`);
+   `className` hits the root only. Theme globally with `--gbs-*` on `:root`.
+4. **Mount `<Toaster />` and `<DialogHost />` once at the app root**, or
+   `toast()` and `dialog.confirm()` do nothing.
+5. **All are client components** (`"use client"`); a Next.js Server Component
+   can render them but not pass function props.
+6. **Compound families throw outside their parent**: Tab/TabList/TabPanel need
+   Tabs, AccordionItem needs Accordion, MenuItem needs Menu.
+
+## Inventory (required props in parens)
+
+**Forms** — Input, Textarea, NumberInput (locale-aware), OtpInput; Checkbox +
+CheckboxGroup; Radio (`value`) + RadioGroup; Switch (applies immediately);
+Select and MultiSelect (`options`; searchable, client or server); DatePicker and
+DateRangePicker; FileUploader (chunked).
+
+**Actions** — Button: variants, sizes, icons, auto-loading from a returned
+promise; `render` draws a router link.
+
+**Overlays** — Modal (native `<dialog>`, also drawers); `dialog` + DialogHost
+(`await dialog.confirm/alert/prompt`); Popover (`trigger`); Menu (`trigger`) with
+MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuGroup,
+MenuSeparator, MenuSub; Tooltip (`content`); `toast` + Toaster.
+
+**Data** — DataGrid (`data`, `columns`) + createColumnHelper: virtualized;
+sort, filter, edit, CSV/Excel/PDF export. Optional agent surface: `ai` renders a
+natural-language box, and `registerGridTool` exposes the grid to a browser agent
+over WebMCP (see "Agent surface"). Inside an `<AgentSurface>` the grid joins the
+page's one tool instead (see "Page surface").
+
+**Display** — Tabs/TabList/Tab (`value`)/TabPanel (`value`); Accordion +
+AccordionItem (`value`); Card/CardHeader/CardBody/CardFooter/Stat; Alert; Badge
+and Tag; Avatar and AvatarGroup; Progress and CircularProgress (`value={null}`
+is indeterminate); Skeleton and Empty; Spinner; Breadcrumb (`items`,
+`renderLink`).
+
+## Example
+
+```tsx
+"use client";
+import { useState } from "react";
+import { Button } from "component-lib/button";
+import { Input } from "component-lib/input";
+import { Select } from "component-lib/combobox";
+import { Modal } from "component-lib/modal";
+import { toast } from "component-lib/toaster";
+
+const ROLES = [{ value: "admin", label: "Admin" }, { value: "dev", label: "Dev" }];
+
+export function InviteButton() {
+  const [open, setOpen] = useState(false);
+  const [email, setEmail] = useState("");
+  const [role, setRole] = useState<string | null>(null);
+  const invalid = !!email && !email.includes("@");
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Invite</Button>
+      <Modal open={open} onOpenChange={setOpen} title="Invite a teammate"
+        footer={({ close }) => (
+          <Button disabled={!email || invalid} onClick={async () => {
+            await invite({ email, role });
+            toast.success("Invitation sent");
+            close();
+          }}>Send</Button>
+        )}>
+        <Input label="Email" type="email" value={email} onValueChange={setEmail}
+          required error={invalid ? "Enter a valid email" : undefined} />
+        <Select label="Role" options={ROLES} value={role} onChange={setRole} />
+      </Modal>
+    </>
+  );
+}
+```
+
+## Page surface (optional): `<AgentSurface>`
+
+To make a page operable by a browser agent, wrap it — do not write WebMCP tools
+by hand:
+
+```tsx
+import { AgentSurface } from "component-lib/shared";
+
+<AgentSurface>
+  <Input label="Name" maxLength={80} />
+  <Select label="Team" options={teams} />
+  <DataGrid aria-label="Customers" data={rows} columns={cols} />
+</AgentSurface>
+```
+
+Input, Textarea, NumberInput, Checkbox, Switch, RadioGroup, Select,
+MultiSelect, DatePicker, DateRangePicker and DataGrid register themselves, with
+what they accept, and one tool `operate_page` (`describe`, then `operate` by
+id) is registered when WebMCP exists. Ids come from the label, so give every
+field a text `label` (a grid an `aria-label`). Every action goes through the
+component's own validator; password, hidden and file inputs are never offered.
+`useAgentSurface()` returns the same surface for an app's own agent loop.
+
+## Agent surface (DataGrid, optional)
+
+Entirely opt-in. Without it, nothing changes and nothing is downloaded.
+
+**A person typing.** `ai` renders a box above the grid. It needs a provider
+supplying an adapter; with no provider it renders nothing at all.
+
+```tsx
+import { GramproAIProvider } from "component-lib/shared";
+import { DataGrid } from "component-lib/data-grid";
+
+<GramproAIProvider adapter={myAdapter}>
+  <DataGrid data={rows} columns={cols} ai semantics={SEMANTICS} />
+</GramproAIProvider>
+```
+
+`adapter` is one function — `(utterance, contract, responseSchema) => envelope`.
+No model is bundled, downloaded or named; the app brings its own, and the key
+belongs on the app's server, never in client JavaScript.
+
+**A browser agent.** `registerGridTool(agent)` registers one WebMCP tool,
+`operate_grid`, whose schema is generated from the live grid. Requires no model
+at all.
+
+**Both go through the same validator**, which refuses an unknown column, an
+operator the type lacks, a policy-denied column, or an irreversible operation
+with no confirmation — and returns the reason. A producer proposes; it never
+acts. Do not add repair, retries or a second execution path.
+
+**Data leaves the page with a remote adapter.** The contract carries real
+values from low-cardinality columns, so the model can map "Kerala" to `region`.
+Mark personal columns `semantics: { email: { pii: true } }` — a PII column is
+denied *and* never summarised — or pass `stats: false` to summarise nothing.
+`policy.denyFilter` does **not** stop a column being described.
+
+**`semantics` is where most quality comes from**: per column, give `synonyms`,
+`description`, `unit`, `higherIsBetter`, `pii`. Reach for it before reaching for
+a bigger model.
+
+## Don't
+
+- Raw `<button>`, `<input>`, `<select>`, `<table>`, `<dialog>`, or a hand-built
+  modal/menu/tooltip, when a component exists.
+- Deep imports (`.../input/react/Input`); import the barrel. Only `<name>/core`
+  is also public.
+- Editing `component-lib/shared/`; the CLI replaces it on update.
+- Invented props: no `asChild`, no `variant` on Input, no `onChange` on Switch.
+- `!important` or internal class selectors; set `--gbs-*` or pass `classNames`.
+- A Tooltip as a name; icon buttons need `aria-label`.
+
+## Details (in `references/`)
+
+- `install.md` — CLI flags, folders, 1.x vs 2.x.
+- `forms.md` — fields, controlled state, form posting.
+- `pickers.md` — Select, MultiSelect, DatePicker, Uploader.
+- `overlays.md` — Modal, dialog, Popover, Menu, Tooltip.
+- `toaster.md` — `toast()` and `<Toaster />`.
+- `data-grid.md` — columns, API, export.
+- `data-display.md` — Card, Tabs, Accordion, Badge, Avatar.
+- `styling.md` — tokens, layers, slots, `data-*`, dark.
+- `accessibility.md` — what is supplied, what you add.

package/.gbs/skills/gbs-components/references/data-grid.md

@@ -114,3 +114,12 @@ use `print()` for those.
 
 Set `mode="server"`, pass the current page as `data` and the total as
 `rowCount`, and fetch in `onQueryChange`.
+
+## Inside an AgentSurface
+
+A DataGrid inside `<AgentSurface>` builds its agent and joins the page's one
+WebMCP tool (`operate_page`) by itself, with its columns and operations; there
+is no need to call `createGridAgent` or `registerGridTool`. Give it an
+`aria-label` — it becomes the grid's id there. `semantics` and `agentPolicy`
+apply exactly as with `ai`. Outside a surface and without `ai`, no agent is
+built.

package/.gbs/skills/gbs-components/references/forms.md

@@ -200,3 +200,15 @@ There is no form library here. Compute the message yourself and pass it as
 `error`; the component handles `aria-invalid`, `aria-describedby` and the
 styling. With React Hook Form or similar, wire `value` and the component's own
 handler name, and pass `error={errors.field?.message}`.
+
+## Operable by a browser agent
+
+Wrap the form in `<AgentSurface>` (from `shared`) and every field in it joins
+one WebMCP tool, `operate_page`, describing what it accepts from its own props:
+`maxLength`, `min`/`max`, options and which are disabled. Nothing else to
+write. Give each field a text `label`: the label becomes its id
+(`"Due date"` → `due-date`), and a field labelled only by a ReactNode falls
+back to `aria-label`, then `name`, then `placeholder`. Password, hidden and file inputs are never
+offered. Writes fire the same handlers a person's input does, so controlled
+state updates as usual. Without WebMCP, `useAgentSurface()` returns the same
+surface for the app's own agent loop.

package/.gbs/skills/gbs-components/references/install.md

@@ -18,7 +18,7 @@ other runtime dependencies.
 ```bash
 npx @grampro/kit add Button                 # one component
 npx @grampro/kit add Button,Input,Modal     # several
-npx @grampro/kit -i                         # interactive picker
+npx @grampro/kit add                        # interactive picker (a person at a terminal)
 npx @grampro/kit -l                         # list available
 npx @grampro/kit doctor                     # what changed locally and upstream
 npx @grampro/kit doctor Button --json       # one component, for reading programmatically
@@ -29,7 +29,7 @@ npx @grampro/kit skill --for claude         # only the Claude Code copy
 | Flag | Alias | Meaning |
 | --- | --- | --- |
 | `--add` | `-a` | Component, or comma-separated list. Case-insensitive. |
-| `--interactive` | `-i` | Pick from a menu. |
+| `--interactive` | `-i` | Pick from a menu; same as `add` with no names. Needs a terminal. |
 | `--list` | `-l` | Print available components. |
 | `--legacy` | — | Install from the 1.x set instead. Unmaintained; see below. |
 | `--skill` | — | Install this skill at the project root. `-skill` and `-a skill` also work. |
@@ -37,6 +37,11 @@ npx @grampro/kit skill --for claude         # only the Claude Code copy
 | `--force` | — | Replace a component, `shared/` or `.gbs/` even though the project has edited it. Never pass it on the user's behalf. |
 | `--json` | — | With `doctor`: print the report as JSON. |
 
+**An agent always names the components.** The picker needs a real terminal:
+run without one, `add` with no names only prints a hint and `-i` exits with an
+error, so neither installs anything. Output is in colour only on a terminal,
+and never with `NO_COLOR` set — read it piped and it is plain text.
+
 ## Components the project has changed
 
 Copied components are meant to be edited, so `add` treats an edited one as
@@ -168,6 +173,10 @@ Rules the installer enforces:
 
 - `shared/` only moves forward. If the project has a newer version than the CLI
   carries, the install aborts rather than downgrading it.
+- The same version is updated anyway when its files differ from the CLI's, so a
+  release that changed `shared/` without a version bump still reaches the
+  project. (2.7.0 did; projects that had shared 1.3.0 kept the old files until
+  2.7.3, which is shared 1.4.0.)
 - A file you edited since the CLI wrote it is never replaced without `--force`.
   It tracks this with sha256 hashes in `component-lib/shared/.install-manifest.json`.
 
@@ -176,7 +185,9 @@ is replaced on update. Put your changes in your own module instead.
 
 `shared` exports `cx`, `countCharacters`, `describeField`,
 `useControllableState`, `AnchoredPopover`, `placePopover`, `icons` and
-`sharedVersion`.
+`sharedVersion`; the agent runtime (`createFieldAgent`, `useFieldAgent`,
+`GramproAIProvider`); and `AgentSurface` with `useAgentSurface`, which make a
+page operable by a browser agent (see SKILL.md, "Page surface").
 
 ## Importing