@grampro/kit 0.0.0-stage → 2.4.0

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@grampro/kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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"
+  }
+}

package/schema/passport-v1.schema.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gramprokit.dev/schema/passport/1.json",
+  "title": "GramproKit Component Passport v1",
+  "description": "Machine-readable contract for one component. Generated from TypeScript source and merged with authored semantics. Published so external tooling can validate without depending on the generator.",
+  "type": "object",
+  "required": ["passportVersion", "identity", "source", "props", "events", "slots", "states", "coverage"],
+  "additionalProperties": false,
+  "properties": {
+    "passportVersion": { "const": "1.0.0" },
+
+    "identity": {
+      "type": "object",
+      "required": ["component", "folder", "exports"],
+      "additionalProperties": false,
+      "properties": {
+        "component": { "type": "string", "description": "Primary exported component name." },
+        "folder": { "type": "string", "description": "Install folder under component-lib/." },
+        "exports": { "type": "array", "items": { "type": "string" } },
+        "since": { "type": "string" }
+      }
+    },
+
+    "source": {
+      "type": "object",
+      "required": ["libraryVersion", "files", "sourceHash"],
+      "additionalProperties": false,
+      "description": "Provenance. sourceHash covers file contents only — no timestamps — so regeneration is byte-stable and CI comparison is meaningful.",
+      "properties": {
+        "libraryVersion": { "type": "string" },
+        "files": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "sourceHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      }
+    },
+
+    "purpose": { "type": "string", "description": "Authored. What the component is for." },
+
+    "props": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "type", "required", "origin"],
+        "properties": {
+          "name": { "type": "string" },
+          "type": { "enum": ["string", "number", "boolean", "enum", "function", "other"] },
+          "values": { "type": "array", "items": { "type": "string" }, "description": "Present when type is enum." },
+          "signature": { "type": "string", "description": "Present when type is function." },
+          "typeText": { "type": "string", "description": "The TypeScript type as written." },
+          "required": { "type": "boolean" },
+          "default": { "description": "Derived from the component's destructuring default, when present." },
+          "origin": {
+            "enum": ["derived", "inherited", "manual", "local"],
+            "description": "derived = this project's source; inherited = a library type (React DOM) confirmed by the TypeChecker; manual/local = added by an overlay."
+          },
+          "description": { "type": "string" },
+          "descriptionOrigin": { "enum": ["jsdoc", "readme", "manual", "local"] },
+          "note": { "type": "string", "description": "Authored annotation from propNotes." },
+          "deprecated": { "type": ["boolean", "string"] }
+        },
+        "allOf": [
+          { "if": { "properties": { "type": { "const": "enum" } }, "required": ["type"] },
+            "then": { "required": ["values"] } },
+          { "if": { "required": ["description"] },
+            "then": { "required": ["descriptionOrigin"] } }
+        ]
+      }
+    },
+
+    "inherits": {
+      "type": "array",
+      "description": "External (library) base types. Deliberately NOT flattened: resolving ButtonHTMLAttributes yields hundreds of DOM props and buries the real API. A policy allowlist surfaces the useful ones inline with origin=inherited.",
+      "items": {
+        "type": "object",
+        "required": ["from"],
+        "additionalProperties": false,
+        "properties": {
+          "from": { "type": "string" },
+          "omitted": { "type": "array", "items": { "type": "string" } },
+          "passthrough": { "type": "boolean" }
+        }
+      }
+    },
+
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "signature": { "type": "string" },
+          "description": { "type": "string" }
+        }
+      }
+    },
+
+    "slots": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "classNames slot keys, in declaration order."
+    },
+
+    "states": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["attr"],
+        "additionalProperties": false,
+        "properties": {
+          "attr": { "type": "string", "pattern": "^data-" },
+          "values": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+
+    "accessibility": {
+      "type": "object",
+      "description": "Authored. What the component supplies versus what the consumer must still provide.",
+      "additionalProperties": false,
+      "properties": {
+        "supplied": { "type": "array", "items": { "type": "string" } },
+        "required": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+
+    "composition": {
+      "type": "object",
+      "description": "Authored. Structural rules a generator or agent must respect.",
+      "properties": {
+        "requiresAncestor": { "type": ["string", "null"] },
+        "allowedChildren": { "type": "array", "items": { "type": "string" } },
+        "mustNotContain": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": "string" }
+      }
+    },
+
+    "operations": {
+      "type": "object",
+      "description": "Authoritative, validator-compatible. Only declared where the component genuinely exposes a deterministic operation surface. An operation is never claimed because an AI use case sounds plausible.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["summary", "apiMethod"],
+        "properties": {
+          "summary": { "type": "string" },
+          "apiMethod": { "type": "string", "description": "Method on the component's imperative API." },
+          "input": { "type": "object", "description": "JSON Schema fragment for the operation's arguments." },
+          "effects": { "type": "array", "items": { "type": "string" } },
+          "reversible": { "type": "boolean" },
+          "requiresConfirmation": { "type": "boolean" }
+        }
+      }
+    },
+
+    "intentDomains": {
+      "type": "array",
+      "description": "Advisory routing hints only. Never a substitute for operations, and carrying no execution semantics.",
+      "items": {
+        "enum": ["Query", "Extraction", "TemporalInterpretation", "ActionIntent", "Summarization", "Classification", "Recommendation"]
+      }
+    },
+
+    "safeMutations": {
+      "type": "object",
+      "description": "Authored. Which props an agent may change without altering behaviour.",
+      "additionalProperties": false,
+      "properties": {
+        "allowed": { "type": "array", "items": { "type": "string" } },
+        "forbidden": { "type": "array", "items": { "type": "string" } },
+        "rationale": { "type": "string" }
+      }
+    },
+
+    "examples": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "type": "string" },
+          {
+            "type": "object",
+            "required": ["title", "file"],
+            "properties": {
+              "title": { "type": "string" },
+              "file": { "type": "string" },
+              "description": { "type": "string" }
+            }
+          }
+        ]
+      }
+    },
+
+    "coverage": {
+      "type": "object",
+      "required": ["propsTotal", "propsDescribed", "describedPct"],
+      "additionalProperties": false,
+      "properties": {
+        "propsTotal": { "type": "integer", "minimum": 0 },
+        "propsDescribed": { "type": "integer", "minimum": 0 },
+        "describedPct": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "authoredSections": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/source/components/accordion/README.md

@@ -0,0 +1,45 @@
+# Accordion
+
+Sections that open and close, built on native `<details>` and `<summary>`, for
+React 19 and styled to match the rest of the library. No runtime dependencies
+besides React.
+
+```ts
+import { Accordion, AccordionItem } from "@/components/accordion";
+import "@/components/accordion/styles.css";
+```
+
+```tsx
+<Accordion
+  defaultValue={["shipping"]}
+  items={[
+    { value: "shipping", title: "Shipping", content: <p>Two to five days.</p> },
+    { value: "returns", title: "Returns", content: <p>Thirty days, no questions.</p> },
+  ]}
+/>
+
+<Accordion multiple variant="contained">
+  <AccordionItem value="one" title="Details" meta={<Badge count={3} />}>
+    …
+  </AccordionItem>
+</Accordion>
+```
+
+**Accordion:** `value` / `defaultValue` / `onValueChange` (string arrays),
+`items` or `<AccordionItem>` children, `multiple`, `collapsible`, `variant`
+(`separated` `contained` `plain`), `size`, `iconPosition`, `classNames`, `ref`.
+
+**AccordionItem:** `value`, `title`, `description`, `children`, `meta`, `icon`,
+`disabled`, `classNames` (`root` `header` `title` `description` `icon`
+`content` `body`), `ref` (the `<details>`).
+
+The browser owns the disclosure: the header is focusable, Enter and Space work,
+the panel is out of the accessibility tree while closed, and Ctrl+F finds text
+inside a closed panel where the browser supports it. What the component owns is
+the group — which panel is open, and whether the last one may be closed —
+because `<details name>` alone cannot express that and gives no value to store.
+
+Opening animates in browsers that have `interpolate-size` and
+`::details-content`, and simply shows and hides everywhere else.
+
+`toggleOpen` and `normalizeOpen` are exported from the framework-free `core`.

package/source/components/accordion/core/index.ts

@@ -0,0 +1,2 @@
+export { normalizeOpen, toggleOpen, type ToggleOptions } from "./open";
+export type * from "./types";

package/source/components/accordion/core/open.ts

@@ -0,0 +1,56 @@
+/**
+ * Which panels are open after a header is pressed.
+ *
+ * Three rules, and every accordion gets at least one of them wrong at some
+ * point, which is why they are here rather than spread through the component:
+ *
+ * `multiple` decides whether opening one closes the others. `collapsible`
+ * decides whether the open one can be closed by pressing it again — a
+ * non-collapsible accordion always has exactly one panel open, which is what
+ * you want when the panels are the whole content of the page and an empty page
+ * would be a dead end.
+ *
+ * Order is kept as panels were opened, so a caller storing the value can tell
+ * which one was opened last.
+ */
+export interface ToggleOptions {
+  multiple?: boolean;
+  collapsible?: boolean;
+}
+
+export function toggleOpen(
+  open: readonly string[],
+  value: string,
+  { multiple = false, collapsible = true }: ToggleOptions = {},
+): string[] {
+  const isOpen = open.includes(value);
+
+  if (!multiple) {
+    if (!isOpen) return [value];
+    return collapsible ? [] : [value];
+  }
+
+  if (!isOpen) return [...open, value];
+  // The last panel of a non-collapsible accordion stays put; closing any other
+  // one is fine, because something is still open afterwards.
+  if (!collapsible && open.length === 1) return [...open];
+  return open.filter((item) => item !== value);
+}
+
+/**
+ * The starting value, trimmed to what the settings allow.
+ *
+ * A single accordion given three open panels, or a non-collapsible one given
+ * none, would otherwise start in a state it can never return to once the user
+ * touches it.
+ */
+export function normalizeOpen(
+  open: readonly string[],
+  values: readonly string[],
+  { multiple = false, collapsible = true }: ToggleOptions = {},
+): string[] {
+  const known = open.filter((value) => values.includes(value));
+  const trimmed = multiple ? known : known.slice(0, 1);
+  if (trimmed.length === 0 && !collapsible && values.length > 0) return [values[0]];
+  return trimmed;
+}

package/source/components/accordion/core/types.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+
+export type AccordionVariant = "separated" | "contained" | "plain";
+
+export type AccordionSize = "sm" | "md" | "lg";
+
+/** Which side of the header the chevron sits on. */
+export type AccordionIconPosition = "start" | "end";
+
+export interface AccordionItemData {
+  value: string;
+  title: ReactNode;
+  /** A second line under the title. */
+  description?: ReactNode;
+  content: ReactNode;
+  disabled?: boolean;
+}

package/source/components/accordion/index.ts

@@ -0,0 +1,8 @@
+export { Accordion } from "./react/Accordion";
+export type { AccordionProps } from "./react/Accordion";
+export { AccordionItem } from "./react/AccordionItem";
+export type { AccordionItemProps } from "./react/AccordionItem";
+export { AccordionContext, useAccordionContext } from "./react/context";
+export type { AccordionContextValue } from "./react/context";
+export type { AccordionItemSlot, AccordionSlot } from "./react/props";
+export * from "./core";

package/source/components/accordion/passport.json

@@ -0,0 +1,259 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Accordion",
+    "folder": "accordion",
+    "exports": [
+      "Accordion",
+      "AccordionContext",
+      "AccordionItem"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/index.ts",
+      "core/open.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Accordion.tsx",
+      "react/AccordionItem.tsx",
+      "react/context.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:cb253f4bd818d48805735b4f44c3a25fc66c3a074239558ccc97de1b4ed948bb"
+  },
+  "props": [
+    {
+      "name": "children",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<'root', string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "collapsible",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Allow the open panel to be closed again. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "defaultValue",
+      "type": "other",
+      "typeText": "string[] | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "A second line under the title.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Replaces the chevron.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "iconPosition",
+      "type": "enum",
+      "values": [
+        "end",
+        "start"
+      ],
+      "typeText": "AccordionIconPosition | undefined",
+      "required": false,
+      "default": "end",
+      "origin": "derived",
+      "description": "Which side the chevron sits on. Default `end`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "items",
+      "type": "other",
+      "typeText": "readonly AccordionItemData[] | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Render these panels, or pass `<AccordionItem>` children.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "meta",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Something at the end of the header: a badge, a count.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "multiple",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Allow more than one panel open at a time. Default false.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "onValueChange",
+      "type": "function",
+      "signature": "((value: string[]) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLDivElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "AccordionSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "title",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": true,
+      "origin": "derived"
+    },
+    {
+      "name": "value",
+      "type": "other",
+      "typeText": "string[] | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Open panels, by value (controlled).",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "contained",
+        "plain",
+        "separated"
+      ],
+      "typeText": "AccordionVariant | undefined",
+      "required": false,
+      "default": "separated",
+      "origin": "derived",
+      "description": "Default `separated`.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "events": [
+    {
+      "name": "onValueChange",
+      "signature": "((value: string[]) => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "header",
+    "title",
+    "description",
+    "icon",
+    "content",
+    "body"
+  ],
+  "states": [
+    {
+      "attr": "data-disabled"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "contained",
+        "plain"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 19,
+    "propsDescribed": 10,
+    "describedPct": 53,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}