gbs-add-block 2.1.0 → 2.3.0

package/README.md

@@ -1,14 +1,92 @@
-# GBS Building Blocks 2.0 (v2.1.0)
+# GramproKit
 
-Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
+**An agent-native UI runtime for React.**
+
+React components you own — styled, dependency-free, and machine-readable. Each
+component arrives in your project as source, with its stylesheet, and with a
+contract describing what it is and what can safely be done to it.
+
+```bash
+npx gbs-add-block@latest -a DataGrid --beta
+```
+
+The source lands in `component-lib/`. There is no runtime package to depend on,
+and nothing to wait for upstream when you need a change.
+
+> **Upgrading from 2.1.0 or 2.2.0 — one line to change.** Component CSS no
+> longer lives in a cascade layer, because a layer loses to any unlayered reset
+> and that broke Tailwind v3 and Bootstrap outright. Delete any
+> `@layer gbs, utilities;` you added, and import the generated barrel:
+> `@import "./component-lib/gbs.css";` — with Tailwind v4, after the framework
+> and `layer(components)`. The installer prints the line you need, and
+> [`CHANGELOG.md`](CHANGELOG.md) has the detail.
+
+## What "agent-native" means here
+
+Most component libraries are built for a human reading documentation. These are
+built to be operable by a program as well — a coding agent writing your UI, or
+a model driving a grid at runtime — without either one guessing.
+
+Three things make that true, and all three ship today:
+
+**A passport per component.** `passport.json` is generated from the TypeScript
+source and drift-checked in CI: every prop with its real type, the events, the
+slots, the `data-*` states, and the operations the component actually supports.
+Generated, so it cannot quietly stop being true.
+→ [`docs/component-passport.md`](docs/component-passport.md)
+
+**A runtime contract.** The passport says what a DataGrid *is*. The runtime
+contract says what *this* grid can do right now: these columns, these operators,
+this state, this many rows. Counts and bounded summaries only — never your data.
+→ [`docs/grid-agent-runtime.md`](docs/grid-agent-runtime.md)
+
+**A validator between intent and action.** Five layers — schema, reference,
+coercion, policy, plausibility — stand between a requested operation and
+anything happening. `"1 lakh"` becomes `100000` deterministically rather than by
+a model's arithmetic. An operation on a column the host restricted is refused
+with a reason. Nothing that fails validation runs.
+
+### What that buys you with no AI at all
+
+The runtime ships no model, and most of it is useful anyway:
+
+- **Saved views** and **shareable URLs** — the grid's whole state in a link
+- **Undo and redo** across every operation, by snapshot
+- **An audit trail** of what changed, in readable labels
+- **Confirmation before anything irreversible**, with the affected row count
+  computed from a real dry run
+
+A model, when one is added, plugs into the front of that pipeline. It produces
+an intent, and the validator treats it exactly as it treats any other untrusted
+input. That is the point of the ordering.
+
+## Not headless — styled, and replaceable
+
+An earlier version of this README called these components headless. They are
+not. They ship 27 stylesheets with a default look, theming and dark mode, and
+the word elsewhere in the ecosystem means *no styles at all*.
+
+What is true is that the styling gets out of your way at three levels: CSS
+variables, slot classes, and `data-*` state attributes. Nothing is
+`!important`, and nothing needs beating on specificity.
+
+Each component also has a **framework-free core** — `createDialogStore()`,
+`createGridEngine()` — with no React imports, usable on a server. That part is
+genuinely headless, and the component READMEs document it under "Headless use".
 
 ## Documentation
 
-For detailed documentation on usage and props, Please visit: [Building Block Documentation](https://gramprokit.vercel.app)
+[kit.gramproindia.com](https://kit.gramproindia.com) — usage and props per
+component.
 
-## Beta Components
+In this repository:
 
-New 2.0.0 beta (current version) is available for testing and feedback, Please visit: [Building Block Documentation v2.0.0 beta](https://gramprokit.vercel.app)
+| | |
+| --- | --- |
+| [`docs/component-passport.md`](docs/component-passport.md) | the generated contract, and why its text is data rather than instructions |
+| [`docs/grid-agent-runtime.md`](docs/grid-agent-runtime.md) | runtime contract, intent schema, the five validation layers, undo, saved views |
+| [`docs/grid-agent-evaluation.md`](docs/grid-agent-evaluation.md) | the 230-case corpus and how a model gets measured against it |
+| [`docs/agent-native-architecture.md`](docs/agent-native-architecture.md) | where this is going, and which parts are still proposal |
 
 ## Agent skill
 
@@ -33,28 +111,81 @@ Pick a subset with `--for claude,codex`, or `--for none` for just `.gbs/`.
 Commit the result so everyone's agent picks it up. Re-run to update; a file you
 have edited is never replaced without `--force`.
 
-## What's New 🎉 (Ver 2.1.0)
+## Status
+
+The 2.x line is in active development and the next release will be a major
+version. What is built and tested:
+
+- 27 beta components, source-first, zero runtime dependencies
+- Passports for all 27, generated and drift-checked
+- The DataGrid agent runtime: 21 operations, five validation layers, snapshot
+  undo, and a frozen 231-case evaluation corpus
+- **`<DataGrid ai />`** — a natural-language box, driven by an adapter the
+  application supplies. No model is bundled, downloaded or named.
+- **WebMCP** — one tool, `operate_grid`, exposing the same validated boundary to
+  a browser agent. Needs no model at all.
+- A model evaluation harness, with the measurements that justify both
+
+Every producer — a model, a browser agent, a form — proposes. The validator
+authorizes. The executor mutates state. That boundary is the architecture, and
+it is why no AI path gets a second route into the component.
+
+Still open: operations for DatePicker and Combobox (both are controlled
+components with no imperative write API, which the executor abstraction is meant
+to solve but has not yet proven), and the remaining authored passport metadata.
+The roadmap and its unresolved questions are in
+[`docs/agent-native-architecture.md`](docs/agent-native-architecture.md).
+
+## Styles
+
+Install a component and the CLI writes `gbs.css` next to it, importing every
+component stylesheet you actually installed. Add one line to your global CSS:
+
+```css
+@import "./component-lib/gbs.css";
+```
+
+That is all, for Tailwind v3, Bootstrap, and projects with no CSS framework.
+
+**Tailwind v4** is the one exception, because it puts its own utilities in a
+cascade layer. Import ours after the framework, inside Tailwind's components
+layer, so utilities still win:
+
+```css
+@import "tailwindcss";
+@import "./component-lib/gbs.css" layer(components);
+```
 
-**The application now owns CSS cascade order.** Component rules moved out of the
-`components` layer into a layer of their own, `gbs`, and the stylesheets no
-longer declare a global layer order.
+The installer detects which of these you need and prints it. `gbs.css` is
+rewritten on every install, so the list stays correct as you add components.
 
-Previously every `styles.css` opened with
-`@layer theme, base, components, utilities;` — a leaf file asserting the order
-of the whole document. Whichever stylesheet the bundler emitted first silently
-won that argument. It also meant a Tailwind v3 build failed outright, and
-Bootstrap's Reboot could not be put in front of the components.
+**Why it works this way.** Component CSS ships *unlayered*. An unlayered rule
+beats every layered rule regardless of specificity, so a library that puts its
+rules in a cascade layer loses to any unlayered reset — Tailwind v3's preflight
+and Bootstrap's Reboot both qualify. Unlayered, our rules win on ordinary
+specificity (a class beats `*`), and your own CSS and utilities still override
+them the normal way. `layer(components)` on the import is native CSS, and is
+the standard way to place third-party CSS under Tailwind v4.
 
-- Tailwind **v3** projects now build. Utilities override components there too,
-  with no setup.
-- Tailwind **v4** projects add one line to their global CSS:
-  `@layer gbs, utilities;` — **without it, utilities no longer override
-  component styles.** This is the migration step.
-- Bootstrap, Normalize or any unlayered reset can now be placed before the
-  components: `@layer bootstrap, gbs, app, utilities;`
-- Projects with no CSS framework need no change.
+If you forget it on v4, the failure is small and local: the component renders
+correctly, but a utility passed through `className` will not override it.
+
+### Scrollbars
+
+Every scrolling surface in the kit is thin by default, using the standard
+`scrollbar-width` / `scrollbar-color` properties. Restyle them all from `:root`:
+
+```css
+:root {
+  --gbs-scrollbar-width: auto;              /* auto | thin | none */
+  --gbs-scrollbar-thumb: var(--gbs-accent); /* defaults to a muted accent */
+  --gbs-scrollbar-track: transparent;
+}
+```
 
-See the Theming page, "Cascade layers", for the full model.
+Add `class="gbs-scroll"` to your own scrolling areas to match. Scroll containers
+the kit does not own keep the browser default — it never restyles scrollbars it
+was not asked to.
 
 ## Authors
 

package/index.cjs

@@ -77,7 +77,7 @@ const CONFIG = {
   dependencies: {
     FormRenderer: ["Select", "MultiSelect", "Input", "DatePicker"],
   },
-  docs: "https://gramprokit.vercel.app/",
+  docs: "https://kit.gramproindia.com/",
 };
 
 const { version: PACKAGE_VERSION } = require("./package.json");
@@ -131,6 +131,7 @@ const MANIFEST_FILE = ".install-manifest.json";
  * component-lib.
  */
 const TESTS_DIR = "__tests__";
+
 const isTestPath = (filePath) => filePath.split(/[\\/]/).includes(TESTS_DIR);
 
 const normalizeComponent = (component, availableComponents) =>
@@ -147,6 +148,109 @@ const getSourcePath = (beta = false) => (beta ? BETA_SOURCE_PATH : SOURCE_PATH);
 const folderFor = (component, beta = false) =>
   (beta && CONFIG.betaFolders[component]) || component.toLowerCase();
 
+
+/*
+ * The stylesheet list, written for the project rather than left to it.
+ *
+ * Component CSS ships unlayered, which is what makes this boring: unlayered
+ * rules beat a framework reset on ordinary specificity, so Tailwind v3,
+ * Bootstrap and a project with no framework all need nothing beyond importing
+ * the file. Tailwind v4 is the exception, because it puts its own utilities in
+ * a cascade layer, and an unlayered rule would outrank them - so a v4 project
+ * imports this inside Tailwind's `components` layer, after the framework,
+ * which is the standard way to place third-party CSS.
+ */
+const writeStyleBarrel = async (destPath, beta) => {
+  if (!beta) return null;
+
+  // Whatever is on disk now, not whatever this run happened to install: the
+  // barrel has to stay correct across repeated and partial installs.
+  const folders = fs
+    .readdirSync(destPath, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((folder) => fs.existsSync(path.join(destPath, folder, "styles.css")))
+    .sort();
+
+  const dir = path.basename(destPath);
+  const lines = [
+    "/*",
+    " * Generated by gbs-add-block. Rewritten on every install.",
+    " *",
+    " * 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);',
+    " *",
+    " * With Tailwind v3, Bootstrap, or no framework, the plain import is all",
+    " * you need:",
+    " *",
+    ' *   @import "./' + dir + '/gbs.css";',
+    " *",
+    " * A component with no styles.css is not listed, which is normal - not",
+    " * every component ships CSS.",
+    " */",
+    ...folders.map((folder) => '@import "./' + folder + '/styles.css";'),
+    "",
+  ];
+
+  await fs.writeFile(path.join(destPath, "gbs.css"), lines.join(NL));
+
+  // Read the project's own Tailwind major, so the printed line is the one they
+  // actually need rather than both of them with a decision attached.
+  let tailwindMajor = null;
+  try {
+    const pkg = readJson(path.join(process.cwd(), "package.json"));
+    const range =
+      (pkg && pkg.dependencies && pkg.dependencies.tailwindcss) ||
+      (pkg && pkg.devDependencies && pkg.devDependencies.tailwindcss) ||
+      null;
+    const found = range && String(range).match(/(\d+)/);
+    if (found) tailwindMajor = Number(found[1]);
+  } catch {
+    /* No package.json, or unreadable: fall through to showing both. */
+  }
+
+  return { count: folders.length, dir, tailwindMajor };
+};
+
+/** Printed after an install, so the one manual step is impossible to miss. */
+const reportStyleBarrel = (barrel) => {
+  if (!barrel) return;
+  console.log(
+    NL + "Styles: wrote gbs.css, importing " + barrel.count + " stylesheet(s).",
+  );
+  console.log("Add this to your global CSS:");
+
+  if (barrel.tailwindMajor === null) {
+    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);",
+    );
+    return;
+  }
+
+  if (barrel.tailwindMajor >= 4) {
+    console.log(NL + "  @import \"tailwindcss\";");
+    console.log(
+      "  @import \"./" + barrel.dir + "/gbs.css\" layer(components);",
+    );
+    console.log(
+      NL + "  (after the framework, and in its components layer - Tailwind v4" +
+        " layers its utilities)",
+    );
+    return;
+  }
+
+  console.log(NL + "  @import \"./" + barrel.dir + "/gbs.css\";");
+  console.log(NL + "  (Tailwind v" + barrel.tailwindMajor + ": nothing else to do)");
+};
+
 const copyCommonFiles = async (destPath) => {
   const commonFiles = [
     { src: ["..", "utils.ts"], dest: "utils.ts" },
@@ -434,9 +538,10 @@ const writeAgentsPointer = async (root) => {
   const block = [
     BLOCK_START,
     "",
-    "## GBS components",
+    "## GramproKit components",
     "",
-    "This project uses the GBS headless component library. Before adding or",
+    "This project uses GramproKit components (gbs-add-block). They are copied",
+    "into the project with their styles, so you own them. Before adding or",
     "changing UI, read `" + skillPath + "` and follow it.",
     "",
     "It covers the import rule (components are copied into `component-lib/`, not",
@@ -600,6 +705,82 @@ const parseSkillTargets = (value) => {
   return wanted;
 };
 
+/* ------------------------------------------------------------- passports */
+
+/**
+ * Regenerate or verify passports for the components copied into this project.
+ *
+ * Reads the consumer's own source, so a modified component gets a passport that
+ * describes the modification. `passport.local.json` is read as an overlay and
+ * never written.
+ */
+const runPassport = async ({ check: checkOnly }) => {
+  const dest = DEFAULT_DEST_PATH;
+
+  if (!fs.existsSync(dest)) {
+    console.error(
+      `No ${path.basename(dest)}/ folder here. Install a component first:` +
+        `${NL}  npx gbs-add-block -a Button --beta`,
+    );
+    process.exit(1);
+  }
+
+  let passport;
+  try {
+    passport = require("./tools/passport/index.cjs");
+  } catch {
+    console.error(
+      "Passport tooling is not available in this installation of the CLI.",
+    );
+    process.exit(1);
+  }
+
+  const pkgPath = path.join(process.cwd(), "package.json");
+  const libraryVersion = fs.existsSync(pkgPath)
+    ? readJson(pkgPath, {}).version || "unknown"
+    : "unknown";
+
+  const options = {
+    libRoot: dest,
+    repoRoot: process.cwd(),
+    libraryVersion,
+    includeLocal: true,
+    coverageThreshold: undefined,
+  };
+
+  try {
+    if (checkOnly) {
+      const { report, errors, warnings } = passport.check(options);
+      for (const row of report) {
+        if (row.problems.length === 0) {
+          console.log(`  ${row.component}: OK`);
+          continue;
+        }
+        for (const issue of row.problems) {
+          console.log(`  ${issue.level === "error" ? "✗" : "!"} ${issue.component}: ${issue.message}`);
+        }
+      }
+      console.log(`${NL}${report.length} component(s) · ${errors} error(s) · ${warnings} warning(s)`);
+      if (errors > 0) process.exit(1);
+      return;
+    }
+
+    const { results, written } = passport.generate(options);
+    const errors = results.flatMap((r) => r.issues.filter((i) => i.level === "error"));
+    for (const issue of errors) console.error(`  ✗ ${issue.component}: ${issue.message}`);
+    console.log(
+      `${NL}✓ ${results.length} passport(s) regenerated · ${written.length} changed`,
+    );
+    if (errors.length > 0) process.exit(1);
+  } catch (error) {
+    if (error.code === "ETYPESCRIPT_MISSING" || error.code === "EBADJSON") {
+      console.error(error.message);
+      process.exit(1);
+    }
+    throw error;
+  }
+};
+
 /** `-a skill` is accepted as well as `--skill`, since both read naturally. */
 const isSkillWord = (value) =>
   typeof value === "string" && value.trim().toLowerCase() === "skill";
@@ -637,6 +818,9 @@ const copyComponent = async (component, destPath, beta = false) => {
       );
     }
 
+    // The whole folder travels, which includes passport.json and
+    // passport.manual.json. The passport is part of the component contract,
+    // not an add-on — a contract you opt into is not a contract.
     await fs.copy(componentSrc, componentDest, {
       overwrite: true,
       filter: (source) => !isTestPath(path.relative(componentSrc, source)),
@@ -689,6 +873,8 @@ const installComponentWithDependencies = async (
     });
   }
 
+  reportStyleBarrel(await writeStyleBarrel(destPath, beta));
+
   console.log(`\nFor documentation visit: ${CONFIG.docs}`);
 };
 
@@ -741,6 +927,8 @@ const installMultipleComponents = async (
     });
   }
 
+  reportStyleBarrel(await writeStyleBarrel(destPath, beta));
+
   console.log(`\nFor documentation visit: ${CONFIG.docs}`);
 };
 
@@ -869,6 +1057,7 @@ const main = async () => {
   const args = hideBin(process.argv).map((arg) => {
     if (arg === "-beta") return "--beta";
     if (arg === "-skill") return "--skill";
+    if (arg === "-passport") return "--passport";
     return arg;
   });
   const argv = yargs(args)
@@ -904,6 +1093,17 @@ const main = async () => {
         "With --skill: which agents to write adapters for (claude, codex, antigravity, or none)",
       type: "string",
     })
+    .option("passport", {
+      describe:
+        "Regenerate component passports from the source in this project (needs a local typescript)",
+      type: "boolean",
+      default: false,
+    })
+    .option("check", {
+      describe: "With --passport: verify passports match the source; writes nothing",
+      type: "boolean",
+      default: false,
+    })
     .option("force", {
       describe: "Replace files you have edited locally in shared/ or the skill",
       type: "boolean",
@@ -917,6 +1117,8 @@ const main = async () => {
     .example("$0 -skill --for claude", "Only the Claude Code copy")
     .example("$0 -skill --for none", "Only .gbs/, no adapters")
     .example("$0 -a DataGrid -beta -skill", "Install a component and the skill")
+    .example("$0 -passport", "Regenerate passports for your copied components")
+    .example("$0 -passport --check", "Fail if a passport is stale (CI)")
     .example("$0 -i", "Interactive selection mode")
     .help().argv;
 
@@ -965,6 +1167,13 @@ const main = async () => {
     return;
   }
 
+  // Passports are regenerated in place against the project's own copied
+  // source, so a fork's passport describes the fork.
+  if (argv.passport) {
+    await runPassport({ check: argv.check });
+    return;
+  }
+
   // The skill goes to the project root, not component-lib, so it is handled
   // before anything reaches the component installer.
   if (argv.skill || isSkillWord(argv.add)) {

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "gbs-add-block",
-  "version": "2.1.0",
-  "description": "React Component Library",
+  "version": "2.3.0",
+  "description": "GramproKit — an agent-native UI runtime for React. Components you own, with a machine-readable contract.",
   "type": "module",
   "files": [
     "index.cjs",
     "source",
-    ".gbs"
+    ".gbs",
+    "tools",
+    "schema",
+    "!tools/eval",
+    "!source/**/__tests__",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=17"
@@ -15,23 +22,47 @@
     "gbs-add-block": "index.cjs"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "pnpm -C demo-showroom test",
+    "passport": "node tools/passport/cli.cjs",
+    "passport:check": "node tools/passport/cli.cjs --check",
+    "eval:grid": "node tools/eval/grid/cli.cjs"
   },
-  "keywords": [],
+  "keywords": [
+    "react",
+    "components",
+    "agent-native",
+    "ui-runtime",
+    "copy-in",
+    "data-grid",
+    "accessibility"
+  ],
   "author": "Anandhu Remanan",
   "license": "ISC",
   "dependencies": {
-    "fs-extra": "^11.0.4",
-    "path": "^0.12.7",
-    "yargs": "^17.7.2",
     "@grampro/headless-helpers": "^1.0.21",
-    "tailwind-merge": "^3.6.0"
+    "fs-extra": "^11.0.4",
+    "tailwind-merge": "^3.6.0",
+    "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "@types/fs-extra": "^11.0.4"
+    "@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/anandhuremanan/headless-gbs-components.git"
+  },
+  "homepage": "https://kit.gramproindia.com",
+  "bugs": {
+    "url": "https://github.com/anandhuremanan/headless-gbs-components/issues"
   }
 }