@grampro/kit 0.0.0-stage → 2.4.1

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

@@ -0,0 +1,83 @@
+# Pickers
+
+Select, MultiSelect, DatePicker, DateRangePicker and FileUploader. They share the
+field contract in `forms.md` (`label`, `description`, `error`, `size`,
+`classNames`, `localeText`) but all four use **`onChange`**, not `onValueChange`.
+
+## Select and MultiSelect
+
+Import both from `component-lib/combobox`.
+
+```ts
+interface ComboboxOption<V = string> {
+  value: V;              // string or number
+  label: string;
+  description?: string;  // second line
+  group?: string;        // heading, in first-seen order
+  disabled?: boolean;
+  icon?: ReactNode;
+  keywords?: string[];   // extra search terms
+}
+```
+
+Shared props: `options` (required), `mode` (`client` | `server`), `loading`,
+`onSearchChange`, `searchDebounce` (250), `searchable` (true), `hasMore`,
+`onLoadMore`, `filterFn`, `renderOption`, `allowCreate`, `onCreate`, `label`,
+`description`, `error`, `placeholder` ("Select…"), `required`, `disabled`,
+`clearable` (true), `size`, `name`, `maxHeight` (280), `virtualize` (true above
+80 options), `emptyMessage`, `className`, `style`, `localeText`,
+`onOpenChange`, `ref`, and `classNames` (`root` `label` `control` `value` `tag`
+`popover` `search` `list` `option` `footer`).
+
+`Select` adds `value`/`defaultValue` (`V | null`) and `closeOnSelect` (true).
+`MultiSelect` adds `value`/`defaultValue` (`V[]`), `max`, `maxVisibleTags` (3),
+`showSelectAll` (true) and `closeOnSelect` (false).
+
+`ref` gives `open()`, `close()`, `toggle()`, `focus()`, `clear()`, `getValue()`,
+`getSelectedOptions()`.
+
+```tsx
+<Select label="Country" options={countries} value={country} onChange={setCountry} />
+<MultiSelect label="Tags" options={tagOptions} value={tags} onChange={setTags} max={5} />
+```
+
+Server mode: set `mode="server"`, feed the current results as `options`, and
+handle `onSearchChange` (fires once on open, then debounced) and `onLoadMore`.
+There is no async "load option by value" — pass options that already include the
+selected values.
+
+## DatePicker and DateRangePicker
+
+`value`, `defaultValue`, `min` and `max` accept a `Date`, an ISO `yyyy-mm-dd`
+string or a timestamp. `onChange` always gives `Date` objects at local midnight.
+`DateRangePicker.onChange` also receives a `complete` flag, `false` after the
+first of two clicks.
+
+Shared props: `min`, `max`, `isDateDisabled`, `locale`, `weekStartsOn`,
+`format`, `numberOfMonths`, `showWeekNumbers`, `showToday`, `allowInput` (true),
+`fixedWeeks` (true), `label`, `description`, `error`, `placeholder`, `required`,
+`disabled`, `readOnly`.
+
+```tsx
+<DatePicker label="Start date" value={date} onChange={setDate} />
+<DateRangePicker label="Period" value={range} onChange={setRange} />
+```
+
+## FileUploader
+
+`multiple`, `accept`, `maxSize`, `endpoint`, `autoUpload`, `params`,
+`fieldNames`, `onChange`, `onUploadComplete`, plus `label`, `description`,
+`error`. Without an `endpoint` the files post with the surrounding form.
+
+Each chunk is a `multipart/form-data` POST carrying `uploadId`, `fileName`,
+`chunkIndex`, `totalChunks`, `fileSize`, `additionalParams` and `chunk`. Answer
+2xx; the last body becomes `item.response`. 5xx/408/429 and network errors retry
+with backoff; other 4xx fail the file.
+
+```tsx
+<FileUploader label="Attachments" multiple accept=".pdf,image/*"
+  maxSize={20 * 1024 * 1024} endpoint="/api/upload"
+  onUploadComplete={(items) => console.log(items.map((i) => i.response))} />
+```
+
+`useFileUploader()` exposes the same engine for a custom UI.

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

@@ -0,0 +1,246 @@
+# Styling
+
+These components are styled. They ship a default look, and you replace it at
+three levels: CSS variables, slot classes, and state attributes. Nothing is
+`!important` and nothing needs overriding by specificity.
+
+## 1. Stylesheets are per component
+
+Each folder has its own `styles.css`. Put the ones you use in the project's
+**global** stylesheet — `src/index.css` in Vite, the root layout's CSS in Next —
+once each:
+
+```css
+@import "../component-lib/button/styles.css";
+```
+
+**Never import a stylesheet from a component file.** `import
+"component-lib/button/styles.css"` inside a `.tsx` does bundle, but it makes CSS
+order depend on module import order — which decides whether Tailwind utilities
+still beat the component's own rules — and a lazy-loaded component then pulls its
+styles in late, flashing unstyled. One global import per component, nowhere else.
+
+Nothing renders correctly without it — the components emit class names only.
+
+## 2. Theme with `--gbs-*` on `:root`
+
+One set of variables themes every component at once. This is the whole theming
+API; reach for the other levels only when it is not enough.
+
+```css
+:root {
+  --gbs-accent: #7c3aed;
+  --gbs-accent-soft: #f3e8ff;
+  --gbs-radius: 10px;
+  --gbs-font-size: 14px;
+}
+```
+
+Set them on `:root`, not inside a component — components read them through
+inheritance, so anything set on an ancestor reaches every control beneath it.
+
+### Resolution order
+
+Each component variable falls through this chain, stopping at the first set:
+
+1. **The component's own variable** — `--in-accent`, `--dg-accent`, `--ck-border`.
+   Set this to change one component, or one instance.
+2. **The shared variable** — `--gbs-accent`. The one you normally set.
+3. **The DataGrid's variable** — `--dg-accent`, when the grid's stylesheet is
+   loaded. Kept for projects that themed the grid before the shared variables existed.
+4. **The built-in default** — a `light-dark()` pair, so it follows the page's
+   colour scheme.
+
+```css
+.in-root { --in-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa))); }
+```
+
+### The shared variables
+
+Defaults written light / dark.
+
+**Surfaces and text:** `--gbs-bg` (`#ffffff`/`#0b0b0e`), `--gbs-fg`
+(`#18181b`/`#f4f4f5`), `--gbs-muted` (`#71717a`/`#a1a1aa`), `--gbs-subtle`
+(`#f4f4f5`/`#1c1c20`), `--gbs-hover` (`#f4f4f5`/`#1f1f23`), `--gbs-input-bg`
+(`#ffffff`/`#121216`), `--gbs-readonly-bg` (`#fafafa`/`#0e0e12`),
+`--gbs-header-bg` (`#fafafa`/`#111114`), `--gbs-header-fg` (`#3f3f46`/`#d4d4d8`).
+
+**Borders and shape:** `--gbs-border` (`#e4e4e7`/`#27272a`),
+`--gbs-border-subtle` (`#f0f0f2`/`#1c1c20`), `--gbs-border-control`
+(`#a1a1aa`/`#52525b`), `--gbs-radius` (`8px`), `--gbs-font-size` (`13px`),
+`--gbs-shadow`, `--gbs-backdrop`.
+
+**Accent and status:** `--gbs-accent`, `--gbs-accent-soft`,
+`--gbs-accent-strong`, `--gbs-accent-fg`, `--gbs-focus`, `--gbs-danger`,
+`--gbs-danger-fg`, `--gbs-success`, `--gbs-warning`, `--gbs-info`.
+
+**Grid-specific:** `--gbs-row-alt`, `--gbs-row-hover`, `--gbs-row-selected`,
+`--gbs-row-selected-hover`, `--gbs-cell-px`, `--gbs-pin-shadow`,
+`--gbs-skeleton`, `--gbs-tab-fg`, `--gbs-tooltip-bg`, `--gbs-tooltip-fg`.
+
+### Per-component prefixes
+
+To change one component only, set its own prefix on its root class:
+
+| Component | Prefix | Root class |
+| --- | --- | --- |
+| DataGrid | `--dg-*` | `.dg-root` |
+| Combobox | `--cb-*` | `.cb-root` |
+| Toaster | `--ts-*` | `.ts-region` |
+| Input | `--in-*` | `.in-root` |
+| Button | `--bt-*` | `.bt-root` |
+
+```css
+.cb-root { --cb-accent: #7c3aed; --cb-radius: 12px; }
+```
+
+Toasts render on `<body>`, so grid/shared values they inherit must be set on
+`:root`.
+
+## 3. Slot classes
+
+`className` goes to the root element only. To reach an inner part, use
+`classNames`, a map of slot name to class string:
+
+```tsx
+<Input label="Email" classNames={{ root: "mb-4", label: "font-semibold", input: "font-mono" }} />
+```
+
+Slots are per component and listed in each `react/props.ts` and in this skill's
+`forms.md` / `overlays.md` / `data-display.md`. Passing a slot that does not
+exist is silently ignored, so check the list.
+
+Classes are joined with `cx` from `shared/core/cx.ts`, which drops falsy values
+— a conditional that evaluates to `undefined` contributes nothing.
+
+## 4. Cascade layers and Tailwind
+
+Every `styles.css` ships **unlayered** — no `@layer` wrapper anywhere:
+
+```css
+.bt-root { /* the component's rules */ }
+```
+
+That is deliberate. An unlayered rule beats every layered rule regardless of
+specificity, so a layered library loses to any unlayered reset: Tailwind v3's
+preflight and Bootstrap's Reboot both strip borders, padding and radii off
+layered component rules. Unlayered, a class selector beats `*` on ordinary
+specificity and both work with no setup.
+
+The app imports the generated barrel once:
+
+```css
+@import "./component-lib/gbs.css";
+```
+
+With **Tailwind v4** — and only v4, which layers its own utilities — import it
+after the framework and into Tailwind's components layer, so utilities still
+win:
+
+```css
+@import "tailwindcss";
+@import "./component-lib/gbs.css" layer(components);
+```
+
+Both the order and the `layer()` matter. Imported before the framework, the
+`components` layer registers first and Tailwind's preflight lands after it,
+which strips the component rules. Imported without `layer()`, the unlayered
+rules outrank the utilities and `className` stops overriding them.
+
+Tailwind **v3** needs neither: it emits utilities unlayered, after our CSS, so
+source order already decides. A project with no CSS framework needs neither.
+
+```tsx
+<Button className="w-full sm:w-auto" classNames={{ content: "gap-3" }}>Save</Button>
+```
+
+Do not use `!important`, and do not write selectors against internal class names
+(`.bt-root`, `.dg-cell`) in app CSS — they are implementation detail. Use the
+variables or the slots.
+
+## 4b. Scrollbars
+
+Every scrolling surface in the kit is thin by default, using the standard
+`scrollbar-width` / `scrollbar-color` properties (Baseline since December 2024)
+rather than `::-webkit-scrollbar`. Four tokens control all of them:
+
+```css
+:root {
+  --gbs-scrollbar-width: thin;        /* auto | thin | none */
+  --gbs-scrollbar-thumb: ...;         /* derived from --gbs-accent */
+  --gbs-scrollbar-thumb-hover: ...;
+  --gbs-scrollbar-track: transparent;
+}
+```
+
+Set them on `:root` to restyle every scrollbar, or on one element for one.
+`scrollbar-width` takes no length — only `auto | thin | none`.
+
+For your own scrolling areas, add `class="gbs-scroll"` to match. The kit never
+touches scrollbars it was not asked to: an unrelated scroll container keeps the
+browser default.
+
+## 5. Unlayered resets (Bootstrap, Normalize)
+
+Any stylesheet that ships **unlayered** beats every layered rule regardless of
+specificity — the cascade settles layers before specificity. So Bootstrap's
+Reboot (`button { border-radius: 0 }`, `button, input, textarea { font-size:
+inherit }`) overrides our classes, and import order does not help.
+
+Fix it in the project's global CSS by giving the reset its own layer, named
+before `gbs`:
+
+```css
+@layer bootstrap, gbs, app, utilities;
+@import url("bootstrap/dist/css/bootstrap.min.css") layer(bootstrap);
+```
+
+Only components whose root is a native form element are affected (Button,
+Textarea). Class names never collide — ours are two-letter prefixed.
+
+## 6. State attributes
+
+Components expose their state as `data-*` attributes, so you can style states
+without tracking them in React.
+
+| Attribute | Where |
+| --- | --- |
+| `data-state="open"` / `"closing"` | Combobox, Popover, Menu, Modal, toasts |
+| `data-side` | Popover, Menu, Tooltip — the side it settled on after flipping |
+| `data-size` | Controls that take a `size` |
+| `data-invalid`, `data-disabled` | Form controls |
+| `data-active`, `data-selected` | Combobox options, grid cells and rows |
+| `data-editing`, `data-pinned`, `data-density` | DataGrid |
+| `data-type`, `data-custom`, `data-swiping` | Toasts |
+| `data-position` | Toaster region |
+| `aria-sort` | DataGrid header cells |
+
+```css
+.cb-option[data-active] { outline: 2px solid var(--gbs-focus); }
+```
+
+## 7. Dark mode
+
+Colours are `light-dark()` pairs driven by the page's `color-scheme`, so the
+default is whatever the device prefers. To pin it, set `color-scheme` — the
+components follow:
+
+```css
+:root { color-scheme: light dark; }          /* follow the device */
+:root[data-theme="dark"] { color-scheme: dark; }
+:root[data-theme="light"] { color-scheme: light; }
+```
+
+The DataGrid additionally treats a `.dark` or `[data-theme="dark"]` ancestor as
+forcing a scheme.
+
+Do not maintain a second palette for dark mode. Override the `--gbs-*` variables
+with `light-dark()` pairs, or set them inside your own `[data-theme="dark"]`
+block, and every component follows.
+
+## 8. Right-to-left
+
+The components use logical properties and read `dir` from the document, so RTL
+works without configuration. Arrow keys in Menu, Switch and Tabs mirror
+automatically. The Toaster takes an explicit `dir` prop if one region needs to
+differ from the page.

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

@@ -0,0 +1,57 @@
+# Toaster and toast
+
+Notifications. `toast()` is callable from anywhere — components, event
+handlers, data layers, even outside React. No hook, context or provider.
+
+Mount `<Toaster />` **once**; call `toast()` from anywhere — components, event
+handlers, data layers, even outside React. No hook, context or provider.
+
+**Import from one path everywhere.** `toast()` and `<Toaster />` meet through a
+shared module-level store; two import paths can create two stores.
+
+```tsx
+// once, near the root
+import { Toaster } from "component-lib/toaster";
+<Toaster />
+
+// anywhere
+import { toast } from "component-lib/toaster";
+
+toast("Event created", { description: "Monday, 10:00" });
+toast.success("Saved");
+toast.error("Upload failed", { action: { label: "Retry", onClick: retry } });
+toast.warning("Storage almost full");
+toast.info("New version available");
+const id = toast.loading("Uploading…");     // stays until updated
+toast.update(id, { type: "success", title: "Uploaded" });
+toast.dismiss(id);                          // or toast.dismiss() for all
+
+toast.promise(saveUser(data), {
+  loading: "Saving…",
+  success: (user) => `${user.name} saved`,
+  error: (error) => `Could not save: ${(error as Error).message}`,
+});
+
+toast.custom(({ dismiss }) => <MyCard onClose={dismiss} />);
+```
+
+Every call returns the toast's id; reusing an on-screen id updates that toast.
+
+**Toast options:** `id`, `type` (`default` `success` `error` `warning` `info`
+`loading`), `description`, `duration` (5000; `0`/`Infinity` stays),
+`dismissible`, `action` / `cancel` (`{ label, onClick }`), `icon`, `className`,
+`render`, `onDismiss`, `onAutoClose`.
+
+**Toaster props:** `position` (`top-right`), `limit` (3), `duration` (5000),
+`closeButton` (true), `hotkey` (`["altKey","KeyT"]`), `icons`, `store`, `dir`,
+`className`, `classNames`, `style`, `localeText`.
+
+Slots: `region`, `list`, `toast`, `icon`, `content`, `title`, `description`,
+`actions`, `action`, `cancel`, `close`.
+
+Timers pause while the pointer is over the stack, while focus is inside it, and
+while the tab is hidden. The list is a polite live region; error toasts use
+`role="alert"`. **Alt+T** moves focus to the notifications.
+
+`toast()` does nothing during a server render — call it in the browser, e.g.
+after a Server Action resolves.

package/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+## 2.4.1
+
+### Fixed
+
+**The stylesheet import printed after an install is now one you can paste.**
+
+2.4.0 could put the components under `src/`, and printed the path to the
+barrel from the project root -- which is correct from nowhere in particular.
+In a Next.js app it read:
+
+```css
+@import "./src/component-lib/gbs.css" layer(components);
+```
+
+while the file to edit was `src/app/globals.css`, two directories away. You
+had to work out the `../` yourself.
+
+The installer now finds your global stylesheet in the usual places
+(`src/app/globals.css`, `app/globals.css`, `src/styles/globals.css`,
+`src/index.css` and friends), names it, and writes the path from there:
+
+```
+Add this to src/app/globals.css:
+
+  @import "tailwindcss";
+  @import "../component-lib/gbs.css" layer(components);
+```
+
+Where no stylesheet is found it falls back to the path from the project root,
+as before. The header inside the generated `gbs.css` follows the same rule.
+
+Nothing about the installed components changed; this is the installer's
+output only.
+
+## 2.4.0
+
+The first release published as **`@grampro/kit`**. `gbs-add-block` keeps
+working for now and installs the same components, but new work happens here.
+
+### The package has a new name
+
+```bash
+npx @grampro/kit add DataGrid
+```
+
+`npx gbs-add-block` still resolves, and the `gbs-add-block` binary is still
+installed, so existing scripts keep running. Both will stay for a few
+releases before the old name is deprecated.
+
+### Commands read as commands
+
+`add`, `list`, `skill` and `passport` are verbs now:
+
+```bash
+npx @grampro/kit add Button DataGrid
+npx @grampro/kit list
+npx @grampro/kit skill --for claude
+npx @grampro/kit passport --check
+```
+
+The old flag spellings (`-a Button`, `-skill`, `-passport`) still work and
+print the new spelling once. `--legacy` reaches the 1.x component set, which
+is where `--beta` went: it used to opt *in* to the current components, and
+there is nothing left to opt into.
+
+### You choose where components land
+
+The destination was fixed at `component-lib/` in the directory you ran the
+command from, which put it beside `src/` rather than inside it for most
+projects. Now:
+
+- `--dest <path>` puts them wherever you want.
+- Failing that, an install already in the project wins, so a second `add`
+  lands beside the first. That is how a custom `--dest` is remembered; no
+  config file is written into your project.
+- Failing that, a project with a `src/` folder gets `src/component-lib/`,
+  and everything else keeps `component-lib/` at the root.
+
+Nothing moves on its own: if you already have `component-lib/`, that is
+still where components go.
+
+The stylesheet import printed after an install now names the path the files
+actually landed at, relative to your project root.
+
+### Fixed
+
+- `add Button --dest app/ui` tried to install a component called `app/ui`.
+  A flag's value was being read as a component name; the same was true of
+  `--for`.
+
+### Internal
+
+The library source moved from `source/beta-components` to
+`source/components`, and the 1.x set from `source/components` to
+`source/legacy-components`. This changes nothing for installed components —
+the files you receive and their import paths are identical — but every
+`passport.json` has a new `sourceHash`, because that hash covers
+repo-relative paths.
+
+## 2.3.0
+
+Published as a minor, but **it contains one breaking change to styling**. Read
+the upgrade note below before updating.
+
+### Breaking: component CSS is no longer in a cascade layer
+
+Component rules used to live in `@layer gbs`, and 2.1.0 asked Tailwind v4
+projects to add `@layer gbs, utilities;` to their global CSS. Both are gone.
+
+A cascade layer loses to *any* unlayered stylesheet regardless of specificity,
+and Tailwind v3's preflight and Bootstrap's Reboot are both unlayered. Measured
+on 2.2.0: under Tailwind v3 the components rendered with `border: 0` and
+`padding-left: 0`; under Bootstrap every button was square. No host-side
+declaration could fix either, because nothing layered can outrank unlayered CSS.
+
+Component CSS now ships unlayered and wins on ordinary specificity, so Tailwind
+v3, Bootstrap and framework-free projects work with no setup at all.
+
+**What to change:**
+
+- Delete any `@layer gbs, utilities;` (or similar) line you added for 2.1.0.
+- Import the generated barrel instead of individual stylesheets:
+  `@import "./component-lib/gbs.css";`
+- **Tailwind v4 only** — import it after the framework and into its components
+  layer, or utilities stop overriding component rules:
+  ```css
+  @import "tailwindcss";
+  @import "./component-lib/gbs.css" layer(components);
+  ```
+
+The installer detects which line you need and prints it.
+
+### Added
+
+- **`<DataGrid ai />`** — a natural-language input above the grid, driven by an
+  adapter the application supplies through `<GramproAIProvider>`. No model is
+  bundled, downloaded or named, and with no provider the prop renders nothing.
+- **WebMCP** — `registerGridTool(agent)` exposes one tool, `operate_grid`, to a
+  browser agent. Its schema is generated from the live grid. Needs no model.
+- **Generated stylesheet barrel** — the CLI writes `component-lib/gbs.css` on
+  every install, so the import list stays correct as you add components.
+- **Thin scrollbars** across every scrolling surface, themeable from `:root`
+  via `--gbs-scrollbar-width`, `--gbs-scrollbar-thumb`,
+  `--gbs-scrollbar-thumb-hover` and `--gbs-scrollbar-track`. Add
+  `class="gbs-scroll"` to your own scroll areas to match. Scroll containers the
+  kit does not own are left alone.
+
+### Security
+
+- Pinned `dompurify` to `^3.4.16` via `overrides`, clearing two DOM XSS
+  advisories reachable through `@grampro/headless-helpers → jspdf`. The 2.0 beta
+  components never used that chain. `npm audit` is now clean.
+- Removed the `path` dependency. `require("path")` resolves to Node's built-in,
+  so the npm package was inert — a deprecated userland shim sitting in the
+  dependency tree for no reason.
+
+### Documentation
+
+- Documented what leaves the page with a remote AI adapter: the runtime contract
+  carries real values from low-cardinality columns. Mark personal columns
+  `semantics: { email: { pii: true } }` — a PII column is denied *and* never
+  summarised — or pass `stats: false`. Note that `policy.denyFilter` governs what
+  may be *done* with a column, not whether it may be *described*.
+- Corrected the agent skill's install instructions, which still told agents to
+  import each stylesheet individually with no `layer()`.
+
+### Packaging
+
+- Test files are no longer published (35 files, 233 KB). They were filtered out
+  at install time anyway.
+- Added `repository`, `homepage` and `bugs` metadata.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Grampro Business Services
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.