@grampro/kit 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -1,139 +1,214 @@
-# Changelog
-
-## 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.
+# Changelog
+
+## 2.4.2
+
+### Fixed
+
+**Your own class now beats a component's variant.**
+
+Restyling a variant used to fail silently. A rule like
+
+```css
+.btn-brand { --bt-fill: #7c3aed; }
+```
+
+worked on a plain button and was ignored the moment anyone wrote
+`variant="outline"`, because the shipped rule named two things
+(`.bt-root[data-variant="outline"]`) where yours named one, and the browser
+prefers the more specific selector. No error, nothing in devtools -- the
+colour simply did not apply.
+
+Selectors that carry an option you chose -- `variant`, `size`, `orientation`,
+`appearance`, `placement` and the rest -- are now written so they add no
+weight of their own. One class from you is enough, on any variant, in any
+setup:
+
+```tsx
+<Button variant="outline" className="btn-brand">Save</Button>
+```
+
+**State deliberately still wins.** Disabled, invalid, selected, loading and
+the other runtime states keep their weight, because a brand colour has no
+business painting over a disabled control. To restyle a state, name the
+state: `.btn-brand[data-disabled] { ... }`.
+
+215 selectors across 26 stylesheets. Verified by capturing the computed
+styles of 3,716 elements across every demo in light and dark before and
+after: the only differences were opacity on the shimmer and spinner, which
+differ between two runs of the same build because they are mid-animation.
+Nothing else moved.
+
+Nothing in your code needs to change. If you had already worked around this
+with a more specific selector, that still wins.
+
+## 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/index.cjs

@@ -222,6 +222,36 @@ const folderFor = (component, beta = false) =>
  * imports this inside Tailwind's `components` layer, after the framework,
  * which is the standard way to place third-party CSS.
  */
+/**
+ * The stylesheet a project imports globally, in the usual places.
+ *
+ * Ordered so the framework conventions come first: whichever exists is the
+ * file the printed import line is written relative to, so it can be pasted
+ * as-is rather than counting `../` by hand.
+ */
+const GLOBAL_CSS_CANDIDATES = [
+  "src/app/globals.css",
+  "app/globals.css",
+  "src/styles/globals.css",
+  "styles/globals.css",
+  "src/app/global.css",
+  "src/index.css",
+  "src/main.css",
+  "src/global.css",
+];
+
+const findGlobalStylesheet = () =>
+  GLOBAL_CSS_CANDIDATES.map((rel) => path.join(process.cwd(), rel)).find((file) =>
+    fs.existsSync(file),
+  ) ?? null;
+
+/** The folder's path as written from inside `file`, posix-style. */
+const relativeFrom = (file, dir) => {
+  const rel = path.relative(path.dirname(file), dir).split(path.sep).join("/");
+  if (!rel) return ".";
+  return rel.startsWith(".") ? rel : "./" + rel;
+};
+
 const writeStyleBarrel = async (destPath, beta) => {
   if (!beta) return null;
 
@@ -234,28 +264,27 @@ const writeStyleBarrel = async (destPath, beta) => {
     .filter((folder) => fs.existsSync(path.join(destPath, folder, "styles.css")))
     .sort();
 
-  // The path from the project root, not just the folder name: with the
-  // components under src/ the bare name would point somewhere they are not.
-  const dir =
+  const fromRoot =
     path.relative(process.cwd(), destPath).split(path.sep).join("/") ||
     path.basename(destPath);
+  const globalCss = findGlobalStylesheet();
+  const dir = globalCss ? relativeFrom(globalCss, destPath) : fromRoot;
   const lines = [
     "/*",
     " * Generated by @grampro/kit. Rewritten on every install.",
     " *",
-    " * Import this once in your global CSS. The paths below are written from",
-    " * the project root, so adjust them if your global CSS sits deeper.",
+    " * Import this once in your global CSS:",
     " *",
     " * With Tailwind v4, import it after the framework and inside its",
     " * components layer:",
     " *",
     ' *   @import "tailwindcss";',
-    ' *   @import "./' + dir + '/gbs.css" layer(components);',
+    ' *   @import "' + dir + '/gbs.css" layer(components);',
     " *",
     " * With Tailwind v3, Bootstrap, or no framework, the plain import is all",
     " * you need:",
     " *",
-    ' *   @import "./' + dir + '/gbs.css";',
+    ' *   @import "' + dir + '/gbs.css";',
     " *",
     " * A component with no styles.css is not listed, which is normal - not",
     " * every component ships CSS.",
@@ -281,7 +310,14 @@ const writeStyleBarrel = async (destPath, beta) => {
     /* No package.json, or unreadable: fall through to showing both. */
   }
 
-  return { count: folders.length, dir, tailwindMajor };
+  return {
+    count: folders.length,
+    dir,
+    tailwindMajor,
+    globalCss: globalCss
+      ? path.relative(process.cwd(), globalCss).split(path.sep).join("/")
+      : null,
+  };
 };
 
 /** Printed after an install, so the one manual step is impossible to miss. */
@@ -290,16 +326,20 @@ const reportStyleBarrel = (barrel) => {
   console.log(
     NL + "Styles: wrote gbs.css, importing " + barrel.count + " stylesheet(s).",
   );
-  console.log("Add this to your global CSS (paths from the project root):");
+  console.log(
+    barrel.globalCss
+      ? "Add this to " + barrel.globalCss + ":"
+      : "Add this to your global CSS (paths from the project root):",
+  );
 
   if (barrel.tailwindMajor === null) {
-    console.log(NL + "  @import \"./" + barrel.dir + "/gbs.css\";");
+    console.log(NL + "  @import \"" + barrel.dir + "/gbs.css\";");
     console.log(
       NL + "  With Tailwind v4, put it after the framework and in its layer:",
     );
     console.log("  @import \"tailwindcss\";");
     console.log(
-      "  @import \"./" + barrel.dir + "/gbs.css\" layer(components);",
+      "  @import \"" + barrel.dir + "/gbs.css\" layer(components);",
     );
     return;
   }
@@ -307,7 +347,7 @@ const reportStyleBarrel = (barrel) => {
   if (barrel.tailwindMajor >= 4) {
     console.log(NL + "  @import \"tailwindcss\";");
     console.log(
-      "  @import \"./" + barrel.dir + "/gbs.css\" layer(components);",
+      "  @import \"" + barrel.dir + "/gbs.css\" layer(components);",
     );
     console.log(
       NL + "  (after the framework, and in its components layer - Tailwind v4" +
@@ -316,7 +356,7 @@ const reportStyleBarrel = (barrel) => {
     return;
   }
 
-  console.log(NL + "  @import \"./" + barrel.dir + "/gbs.css\";");
+  console.log(NL + "  @import \"" + barrel.dir + "/gbs.css\";");
   console.log(NL + "  (Tailwind v" + barrel.tailwindMajor + ": nothing else to do)");
 };
 

package/package.json

@@ -1,76 +1,77 @@
-{
-  "name": "@grampro/kit",
-  "version": "2.4.0",
-  "description": "GramproKit \u2014 an agent-native UI runtime for React. Copy-in components you own, each publishing a contract that software can read.",
-  "type": "module",
-  "files": [
-    "index.cjs",
-    "source",
-    ".gbs",
-    "tools",
-    "schema",
-    "!tools/eval",
-    "!source/**/__tests__",
-    "!**/*.test.ts",
-    "!**/*.test.tsx",
-    "CHANGELOG.md"
-  ],
-  "engines": {
-    "node": ">=17"
-  },
-  "bin": {
-    "grampro-kit": "index.cjs",
-    "gbs-add-block": "index.cjs"
-  },
-  "scripts": {
-    "prepublishOnly": "npm test && npm run passport:check",
-    "test": "pnpm -C playground test",
-    "passport": "node tools/passport/cli.cjs",
-    "passport:check": "node tools/passport/cli.cjs --check",
-    "eval:grid": "node tools/eval/grid/cli.cjs"
-  },
-  "keywords": [
-    "react",
-    "react-19",
-    "component-library",
-    "agent-native",
-    "ui-runtime",
-    "ai-agents",
-    "webmcp",
-    "data-grid",
-    "copy-in",
-    "accessibility"
-  ],
-  "author": "Anandhu Remanan",
-  "license": "ISC",
-  "dependencies": {
-    "@grampro/headless-helpers": "^1.0.21",
-    "fs-extra": "^11.0.4",
-    "tailwind-merge": "^3.6.0",
-    "yargs": "^17.7.2"
-  },
-  "devDependencies": {
-    "@huggingface/transformers": "^4.3.1",
-    "@huggingface/transformers-structured-output": "^4.3.1",
-    "@types/fs-extra": "^11.0.4",
-    "typescript": "^6.0.3"
-  },
-  "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
-  },
-  "overrides": {
-    "dompurify": "^3.4.16"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/gramproindia/kit.git"
-  },
-  "homepage": "https://kit.gramproindia.com",
-  "bugs": {
-    "url": "https://github.com/gramproindia/kit/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@grampro/kit",
+  "version": "2.4.2",
+  "description": "GramproKit \u2014 an agent-native UI runtime for React. Copy-in components you own, each publishing a contract that software can read.",
+  "type": "module",
+  "files": [
+    "index.cjs",
+    "source",
+    ".gbs",
+    "tools",
+    "schema",
+    "!tools/eval",
+    "!source/**/__tests__",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=17"
+  },
+  "bin": {
+    "grampro-kit": "index.cjs",
+    "gbs-add-block": "index.cjs"
+  },
+  "scripts": {
+    "prepublishOnly": "npm test && npm run passport:check",
+    "version": "npm run passport && git add -A source",
+    "test": "pnpm -C playground test",
+    "passport": "node tools/passport/cli.cjs",
+    "passport:check": "node tools/passport/cli.cjs --check",
+    "eval:grid": "node tools/eval/grid/cli.cjs"
+  },
+  "keywords": [
+    "react",
+    "react-19",
+    "component-library",
+    "agent-native",
+    "ui-runtime",
+    "ai-agents",
+    "webmcp",
+    "data-grid",
+    "copy-in",
+    "accessibility"
+  ],
+  "author": "Anandhu Remanan",
+  "license": "ISC",
+  "dependencies": {
+    "@grampro/headless-helpers": "^1.0.21",
+    "fs-extra": "^11.0.4",
+    "tailwind-merge": "^3.6.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@huggingface/transformers": "^4.3.1",
+    "@huggingface/transformers-structured-output": "^4.3.1",
+    "@types/fs-extra": "^11.0.4",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "overrides": {
+    "dompurify": "^3.4.16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gramproindia/kit.git"
+  },
+  "homepage": "https://kit.gramproindia.com",
+  "bugs": {
+    "url": "https://github.com/gramproindia/kit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}