@godxjp/ui 13.17.4 → 14.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godxjp/ui",
-  "version": "13.17.4",
+  "version": "14.0.1",
   "type": "module",
   "packageManager": "pnpm@10.29.1",
   "sideEffects": false,
@@ -8,7 +8,14 @@
   "files": [
     "dist",
     "scripts/ui-audit.mjs",
-    "README.md"
+    "README.md",
+    "scripts/visual-audit.mjs",
+    "scripts/visual-audit-rules.mjs",
+    "scripts/audit-hook.mjs",
+    "scripts/init-agent-kit.mjs",
+    "scripts/postinstall.mjs",
+    "scripts/_agent-setup.mjs",
+    "scripts/cli.mjs"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -51,6 +58,10 @@
       "types": "./dist/components/data-grid/index.d.ts",
       "import": "./dist/components/data-grid/index.js"
     },
+    "./charts": {
+      "types": "./dist/components/charts/index.d.ts",
+      "import": "./dist/components/charts/index.js"
+    },
     "./ui": {
       "types": "./dist/components/ui/index.d.ts",
       "import": "./dist/components/ui/index.js"
@@ -266,8 +277,8 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "check:example-imports": "node scripts/check-example-imports.mjs",
-    "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm test",
-    "verify:release": "pnpm typecheck && pnpm lint && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:mcp-prop-sync && pnpm test",
+    "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm test",
+    "verify:release": "pnpm typecheck && pnpm lint && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm test",
     "check:mcp-sync": "node scripts/check-mcp-sync.mjs",
     "check:mcp-orphans": "node scripts/check-mcp-orphans.mjs",
     "check:mcp-prop-sync": "node scripts/check-mcp-prop-sync.mjs",
@@ -284,9 +295,14 @@
     "preview:build": "vite build --config preview/vite.config.ts",
     "docs:sync-primitives": "node preview/scripts/sync-primitive-docs.mjs && prettier --write \"docs/primitives/**/*.tsx\"",
     "audit": "node scripts/ui-audit.mjs",
+    "audit:examples": "node scripts/ui-audit.mjs docs",
     "build": "tsup && tsc -p tsconfig.build.json && node scripts/copy-styles.mjs",
     "dev": "node scripts/dev.mjs",
-    "prepublishOnly": "pnpm run build"
+    "prepublishOnly": "pnpm run build",
+    "check:audit-sync": "node scripts/check-audit-sync.mjs",
+    "visual-audit": "node scripts/visual-audit.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "init-agent": "node scripts/init-agent-kit.mjs"
   },
   "peerDependencies": {
     "@hookform/resolvers": "^5.2.0",
@@ -296,12 +312,28 @@
     "react-dom": ">=19.0.0",
     "react-hook-form": "^7.76.0",
     "react-router-dom": ">=7.0.0",
+    "recharts": "^2.13.0 || ^3.0.0",
     "tailwindcss": ">=4.0.0",
-    "zod": "^4.4.0"
+    "zod": "^4.4.0",
+    "playwright": "*",
+    "@axe-core/playwright": "*",
+    "axe-core": "*"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-table": {
       "optional": true
+    },
+    "recharts": {
+      "optional": true
+    },
+    "playwright": {
+      "optional": true
+    },
+    "@axe-core/playwright": {
+      "optional": true
+    },
+    "axe-core": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -348,6 +380,7 @@
     "vaul": "^1.1.2"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.12.1",
     "@eslint/js": "^9.39.4",
     "@hookform/resolvers": "^5.2.2",
     "@tailwindcss/vite": "^4.2.4",
@@ -361,17 +394,20 @@
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "@vitest/coverage-v8": "^4.1.5",
+    "axe-core": "^4.12.1",
     "eslint": "^9.39.2",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
     "globals": "^15.15.0",
     "jsdom": "^29.1.1",
+    "playwright": "^1.61.1",
     "prettier": "^3.6.2",
     "prettier-plugin-tailwindcss": "^0.6.14",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "react-hook-form": "^7.76.0",
     "react-router-dom": "^7.15.0",
+    "recharts": "^3.8.1",
     "tailwindcss": "^4.2.4",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
@@ -382,7 +418,7 @@
     "zod": "^4.4.3"
   },
   "bin": {
-    "godxjp-ui-audit": "scripts/ui-audit.mjs"
+    "godxjp-ui": "scripts/cli.mjs"
   },
   "module": "./dist/index.js"
 }

package/scripts/_agent-setup.mjs

@@ -0,0 +1,145 @@
+/**
+ * Shared agent-setup helpers — used by both postinstall.mjs (auto, on install) and
+ * init-agent-kit.mjs (explicit, full kit). Every writer is IDEMPOTENT and
+ * NON-DESTRUCTIVE: it only creates a missing file or ADDS a missing key, never
+ * overwrites existing config.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** The godxjp-ui MCP server — pulled on demand via npx (no extra dependency to ship). */
+export const MCP_SERVER = { command: "npx", args: ["@godxjp/ui-mcp"] };
+export const MCP_KEY = "godx-ui";
+
+/** Commands wired into the consumer's .claude/settings.json. */
+export const AUDIT_HOOK_CMD = "node node_modules/@godxjp/ui/scripts/audit-hook.mjs";
+export const PRIMER_CMD = "cat .claude/godxjp-ui-workflow.md";
+
+/** The per-session workflow mandate the SessionStart hook injects into the agent. */
+export const WORKFLOW_MD = `# @godxjp/ui — mandatory workflow (read every session)
+
+You are building UI in an app that uses @godxjp/ui. Follow this EVERY time you create
+or change a component, page, or form — no exceptions.
+
+## Before writing UI
+1. **MCP-first.** Consult the godx-ui MCP: \`get_component <Name>\`, \`search_components\`,
+   \`list_audit_rules\`, \`list_visual_checks\`. Never guess a prop; never hand-roll what a
+   primitive already does.
+2. **Real primitives only.** No raw \`<input>/<select>/<button>/<textarea>/<table>\`, no
+   styled-div fakes. A labelled control ALWAYS goes in \`<FormField label=…>\` (it owns the
+   label↔control wiring, error/aria, AND the field rhythm). Never pair a bare \`<Label>\`
+   with an \`<Input>\`.
+3. **Tokens, not literals.** Semantic colour tokens (bg-primary, text-muted-foreground),
+   token spacing/size/radius/type — no raw palette (bg-blue-600), no hex, no arbitrary
+   \`[13px]\`. No emoji in product UI. Logical CSS (ms-/me-/ps-/pe-) for RTL.
+
+## After writing UI
+4. **Audit (runs automatically too).** \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs\`
+   — fix every finding. A PostToolUse hook also runs it on each edit and feeds findings back.
+5. **Before a visual review**, run the runtime audit against the running app:
+   \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\` (axe + contrast + layout).
+`;
+
+/** Delimited block appended to the consumer's CLAUDE.md — loaded into the agent's context
+ * every turn (the most reliable "ensure it reads the rules"). Markers keep it idempotent. */
+export const CLAUDE_MD_BLOCK = `<!-- godxjp-ui:start (managed by @godxjp/ui — edit .claude/godxjp-ui-workflow.md instead) -->
+## @godxjp/ui — mandatory UI workflow (do NOT skip)
+
+This app uses @godxjp/ui. EVERY time you build or change UI:
+
+1. **MCP-first.** Consult the \`godx-ui\` MCP — \`get_component\`, \`search_components\`,
+   \`list_audit_rules\`, \`list_visual_checks\`. Never guess a prop; never hand-roll what a
+   primitive already does.
+2. **Real primitives only.** No raw \`<input>/<select>/<button>/<textarea>/<table>\`. A labelled
+   control ALWAYS goes in \`<FormField label=…>\` — never a bare \`<Label>\`+\`<Input>\`. Semantic
+   tokens, not raw palette/hex/arbitrary values. No emoji in product UI. Logical CSS for RTL.
+3. **Scan after writing.** \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs <files>\` and fix
+   every finding (a PostToolUse hook runs this automatically and feeds findings back). Before a
+   visual review: \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\` (axe + layout).
+
+Full guide: \`.claude/godxjp-ui-workflow.md\`.
+<!-- godxjp-ui:end -->
+`;
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Ensure `.mcp.json` registers the godx-ui MCP server. Returns 'created' | 'added' | 'present'. */
+export function ensureMcpJson(root) {
+  const path = join(root, ".mcp.json");
+  const json = readJson(path) ?? {};
+  json.mcpServers = json.mcpServers ?? {};
+  if (json.mcpServers[MCP_KEY]) return "present";
+  const created = !existsSync(path);
+  json.mcpServers[MCP_KEY] = MCP_SERVER;
+  writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
+  return created ? "created" : "added";
+}
+
+/** Ensure `.claude/settings.json` has the audit PostToolUse + workflow SessionStart hooks. */
+export function ensureClaudeHooks(root) {
+  const path = join(root, ".claude", "settings.json");
+  mkdirSync(dirname(path), { recursive: true });
+  const json = readJson(path) ?? {};
+  json.hooks = json.hooks ?? {};
+  const added = [];
+
+  const has = (arr, cmd) =>
+    (arr ?? []).some((g) => (g.hooks ?? []).some((h) => (h.command ?? "").includes(cmd)));
+
+  json.hooks.PostToolUse = json.hooks.PostToolUse ?? [];
+  if (!has(json.hooks.PostToolUse, "audit-hook.mjs")) {
+    json.hooks.PostToolUse.push({
+      matcher: "Write|Edit|MultiEdit",
+      hooks: [{ type: "command", command: AUDIT_HOOK_CMD }],
+    });
+    added.push("PostToolUse:auto-audit");
+  }
+
+  json.hooks.SessionStart = json.hooks.SessionStart ?? [];
+  if (!has(json.hooks.SessionStart, "godxjp-ui-workflow.md")) {
+    json.hooks.SessionStart.push({ hooks: [{ type: "command", command: PRIMER_CMD }] });
+    added.push("SessionStart:workflow-primer");
+  }
+
+  writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
+  return added;
+}
+
+/** Write the workflow mandate the SessionStart hook reads (only if absent). */
+export function writeWorkflowMd(root) {
+  const path = join(root, ".claude", "godxjp-ui-workflow.md");
+  mkdirSync(dirname(path), { recursive: true });
+  if (existsSync(path)) return false;
+  writeFileSync(path, WORKFLOW_MD);
+  return true;
+}
+
+/** Append the godxjp-ui mandate to the consumer's CLAUDE.md (created if absent). Idempotent
+ * via the markers. Returns 'created' | 'appended' | 'present'. */
+export function ensureClaudeMd(root) {
+  const path = join(root, "CLAUDE.md");
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+  if (existing?.includes("godxjp-ui:start")) return "present";
+  if (existing == null) {
+    writeFileSync(path, CLAUDE_MD_BLOCK);
+    return "created";
+  }
+  writeFileSync(path, existing.replace(/\s*$/, "") + "\n\n" + CLAUDE_MD_BLOCK);
+  return "appended";
+}
+
+/** True when setup should be SKIPPED (CI, opted out, or installing the library itself). */
+export function shouldSkip(root) {
+  if (process.env.CI || process.env.GODXJP_UI_SKIP_SETUP) return "ci-or-optout";
+  if (!root) return "no-consumer";
+  const pkg = readJson(join(root, "package.json"));
+  if (!pkg) return "no-package";
+  if (pkg.name === "@godxjp/ui" || pkg.name === "@godxjp/ui-mcp") return "self";
+  return null;
+}

package/scripts/audit-hook.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PostToolUse hook — the FORCING FUNCTION.
+ *
+ * Wired by `init-agent-kit.mjs` into a consumer's `.claude/settings.json` so that
+ * after EVERY Write/Edit/MultiEdit of a .tsx/.ts file, the godxjp-ui static audit
+ * runs on that file and its findings are fed straight back to the agent. The agent
+ * cannot skip it — the harness runs the hook, not the agent's goodwill — so a
+ * hand-rolled <label>+<Input>, a raw <button>, a loud palette colour, or an emoji
+ * is surfaced the instant it is written, and the agent self-corrects.
+ *
+ * Contract: reads the hook JSON on stdin ({ tool_input: { file_path } }). Prints
+ * findings to stderr and exits 2 when any are found (Claude Code feeds stderr back
+ * to the model); exits 0 (silent) when the file is clean or irrelevant. Non-fatal —
+ * it never blocks the edit, it just makes the agent SEE the issue.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const AUDIT = join(HERE, "ui-audit.mjs");
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8")); // fd 0 = the hook payload piped by Claude Code
+  } catch {
+    return null;
+  }
+}
+
+const payload = readStdin();
+const file = payload?.tool_input?.file_path ?? payload?.tool_input?.filePath;
+if (!file || !/\.(tsx|ts)$/.test(file) || /\.(test|stories|d)\.tsx?$/.test(file)) process.exit(0);
+
+// ui-audit exits 1 when it finds errors — execFileSync throws, but the JSON is still on
+// e.stdout. Capture it either way; only a truly broken run (no stdout) is ignored.
+let out;
+try {
+  out = execFileSync("node", [AUDIT, "--format", "json", file], { encoding: "utf8" });
+} catch (e) {
+  out = e.stdout?.toString();
+}
+let result;
+try {
+  result = JSON.parse(out);
+} catch {
+  process.exit(0); // never let an audit error break the edit flow
+}
+
+const findings = result.findings ?? [];
+if (findings.length === 0) process.exit(0);
+
+const lines = [
+  `godxjp-ui audit flagged ${findings.length} issue(s) in this file — fix before moving on:`,
+];
+for (const f of findings) {
+  lines.push(`  [${f.severity}] ${f.rule} (line ${f.line})${f.standard ? ` · ${f.standard}` : ""}`);
+  lines.push(`    ${f.message}`);
+}
+lines.push(
+  "Consult the godxjp-ui MCP (get_component / list_audit_rules) and use the real primitive — do not hand-roll.",
+);
+process.stderr.write(lines.join("\n") + "\n");
+process.exit(2); // exit 2 → Claude Code surfaces stderr to the agent

package/scripts/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * @godxjp/ui CLI — `npx @godxjp/ui <command>`.
+ *   init-agent     scaffold the agent forcing-kit (MCP + auto-audit hook + mandate)
+ *   audit          static UI audit (regex over source)
+ *   visual-audit   runtime audit (Playwright + axe-core) against a running app
+ */
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAP = {
+  "init-agent": "init-agent-kit.mjs",
+  audit: "ui-audit.mjs",
+  "visual-audit": "visual-audit.mjs",
+};
+
+const [cmd, ...rest] = process.argv.slice(2);
+const script = MAP[cmd];
+if (!script) {
+  console.error("usage: godxjp-ui <init-agent | audit | visual-audit> [args]");
+  process.exit(1);
+}
+const r = spawnSync("node", [join(HERE, script), ...rest], { stdio: "inherit" });
+process.exit(r.status ?? 0);

package/scripts/init-agent-kit.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * init-agent-kit — the FULL forcing-kit. Run once from a consumer app:
+ *   npx @godxjp/ui init-agent
+ *
+ * Scaffolds (idempotent, non-destructive) the harness-enforced workflow so an agent
+ * follows the whole godxjp-ui process every time it touches UI:
+ *   1. .mcp.json            — registers the godx-ui MCP (component + audit guidance)
+ *   2. .claude/settings.json — PostToolUse hook auto-runs the audit on every .tsx edit
+ *                              and feeds findings back; SessionStart injects the mandate
+ *   3. .claude/godxjp-ui-workflow.md — the per-session mandate the SessionStart hook reads
+ *
+ * Existing config is preserved (hooks are appended only if absent). It then prints the
+ * optional pre-commit / CI snippets.
+ */
+import {
+  ensureClaudeHooks,
+  ensureClaudeMd,
+  ensureMcpJson,
+  shouldSkip,
+  writeWorkflowMd,
+} from "./_agent-setup.mjs";
+
+const root = process.env.INIT_CWD || process.cwd();
+
+const skip = shouldSkip(root);
+if (skip === "self") {
+  console.error("init-agent is for CONSUMER apps, not the @godxjp/ui repo itself.");
+  process.exit(1);
+}
+
+const mcp = ensureMcpJson(root);
+const hooks = ensureClaudeHooks(root);
+const md = writeWorkflowMd(root);
+const claudeMd = ensureClaudeMd(root);
+
+console.log("\n  @godxjp/ui agent-kit installed:");
+console.log(`    • .mcp.json — godx-ui MCP (${mcp})`);
+console.log(
+  `    • .claude/settings.json — ${hooks.length ? hooks.join(", ") : "hooks already present"}`,
+);
+console.log(`    • .claude/godxjp-ui-workflow.md — ${md ? "created" : "already present"}`);
+console.log(`    • CLAUDE.md — godxjp-ui mandate (${claudeMd})`);
+console.log(`
+  The auto-audit hook now runs on every Write/Edit of a .tsx file and feeds findings
+  back to the agent — it cannot skip the audit. Restart your agent to load the MCP + hooks.
+
+  Optional hard gate (block bad UI from landing):
+    • pre-commit:  node node_modules/@godxjp/ui/scripts/ui-audit.mjs resources/js || exit 1
+    • CI step:     node node_modules/@godxjp/ui/scripts/ui-audit.mjs --quiet <your-ui-dirs>
+`);
+process.exit(0);

package/scripts/postinstall.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * postinstall — runs when a consumer installs @godxjp/ui. Auto-registers the godx-ui
+ * MCP server in the consumer's `.mcp.json` so the agent gets live access to the
+ * component catalog + audit rules WITHOUT any manual step. Non-destructive (only adds
+ * a missing server entry) and guarded so it never runs in CI or in the library's own repo.
+ *
+ * The heavier forcing-kit (the auto-audit PostToolUse hook + the workflow mandate) is
+ * left to an EXPLICIT `npx @godxjp/ui init-agent`, since hooks change the dev loop and
+ * should be opted into, not forced on install. Set GODXJP_UI_SKIP_SETUP=1 to disable.
+ */
+import { ensureMcpJson, shouldSkip } from "./_agent-setup.mjs";
+
+const root = process.env.INIT_CWD || process.cwd();
+
+const skip = shouldSkip(root);
+if (skip) process.exit(0); // silent: CI / opt-out / self-install / no consumer project
+
+try {
+  const r = ensureMcpJson(root);
+  if (r === "present") process.exit(0); // already configured — stay quiet
+  console.log(
+    `\n  @godxjp/ui → registered the godx-ui MCP in .mcp.json (${r}).\n` +
+      "  Your agent now has live component + audit guidance. Restart it to pick up the MCP.\n" +
+      "  For the full forcing-kit (auto-audit on every edit + workflow mandate):\n" +
+      "    npx @godxjp/ui init-agent\n",
+  );
+} catch {
+  // Never fail an install over optional setup.
+}
+process.exit(0);