create-kerf-component 5.0.0-beta.9 → 6.0.0-beta.1

package/component-metadata.schema.json

@@ -0,0 +1,282 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/create-kerf-component/component-metadata.schema.json",
+  "title": "Kerf consumer component metadata source",
+  "type": "object",
+  "required": ["schemaVersion", "components"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "componentCatalog": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Relative path to the package's component (selection) catalog, copied into the generated composition catalog's compatibility.componentCatalog; defaults to \"not-applicable\"."
+    },
+    "components": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/component" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "stateAttribute": {
+      "type": "object",
+      "required": ["name", "on", "helper", "meaning"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^data-[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "on": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The element that carries it: a public class, or the element passed to the helper."
+        },
+        "helper": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The helper, one of wiring.helpers, that writes it."
+        },
+        "meaning": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What its presence or value means."
+        }
+      },
+      "additionalProperties": false
+    },
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "cardinality": {
+      "type": "object",
+      "required": ["min", "max"],
+      "properties": {
+        "min": { "type": "integer", "minimum": 0 },
+        "max": {
+          "anyOf": [
+            { "type": "integer", "minimum": 1 },
+            { "const": "unbounded" }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": ["id", "severity", "when", "message"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^KUI-C[0-9]{3}$" },
+        "severity": { "enum": ["error", "warning"] },
+        "when": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "component": {
+      "type": "object",
+      "required": [
+        "id",
+        "name",
+        "kind",
+        "purpose",
+        "source",
+        "publicExports",
+        "sourceLinks",
+        "composition",
+        "boundaries",
+        "accessibility",
+        "diagnostics",
+        "provenance"
+      ],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["component", "composition", "recipe"] },
+        "purpose": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "publicExports": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Each export's name and package.json#exports subpath. A private application (package.json#private) may omit subpath; the name is then verified against the component's source file.",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "subpath": { "type": "string", "pattern": "^\\." }
+            },
+            "additionalProperties": false
+          }
+        },
+        "sourceLinks": { "$ref": "#/$defs/stringList" },
+        "composition": { "$ref": "#/$defs/composition" },
+        "boundaries": {
+          "type": "object",
+          "required": ["rootClass", "publicClasses", "publicTokens"],
+          "properties": {
+            "rootClass": {
+              "oneOf": [
+                { "type": "string", "minLength": 1 },
+                { "type": "null" }
+              ]
+            },
+            "publicClasses": { "$ref": "#/$defs/stringList" },
+            "placeableClasses": {
+              "$ref": "#/$defs/stringList",
+              "description": "The subset of publicClasses an application may place on its own elements (a layout utility, item geometry on another carrier). Absent means none: every public class is the component's rendered anatomy, which eslint-plugin-kerfjs reports on an application-owned element as KUI-L103 with the component to render."
+            },
+            "rootElement": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+              "description": "The intrinsic element the component renders around its own placeableClasses. A placeable class on a plain element of this tag is the component recreated (KUI-L103); another carrier element keeps it. Requires placeableClasses."
+            },
+            "publicTokens": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "accessibility": {
+          "type": "object",
+          "required": ["obligations"],
+          "properties": { "obligations": { "$ref": "#/$defs/stringList" } },
+          "additionalProperties": false
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/diagnostic" }
+        },
+        "provenance": {
+          "type": "object",
+          "required": ["selection", "composition"],
+          "properties": {
+            "selection": { "type": "string", "minLength": 1 },
+            "composition": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "composition": {
+      "type": "object",
+      "required": [
+        "parents",
+        "contexts",
+        "zones",
+        "children",
+        "state",
+        "wiring",
+        "responsive",
+        "layout"
+      ],
+      "properties": {
+        "rendersAs": {
+          "description": "For a wrapper component: the cataloged roots it renders (package-qualified keys such as @kerfjs/ui:toolbar-control-group), any one of them or nothing. UI composition checks treat the wrapper as each declared root.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[^:]+:[^:]+$" },
+          "uniqueItems": true
+        },
+        "parents": {
+          "type": "object",
+          "required": ["mode", "entries"],
+          "properties": {
+            "mode": { "enum": ["any", "root", "listed"] },
+            "entries": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "contexts": { "$ref": "#/$defs/stringList" },
+        "zones": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "accepts", "cardinality", "exclusiveWith"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "accepts": { "$ref": "#/$defs/stringList" },
+              "cardinality": { "$ref": "#/$defs/cardinality" },
+              "exclusiveWith": { "$ref": "#/$defs/stringList" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "children": {
+          "type": "object",
+          "required": ["mode", "concepts", "requiredConcepts"],
+          "properties": {
+            "mode": { "enum": ["any", "none", "listed"] },
+            "concepts": { "$ref": "#/$defs/stringList" },
+            "requiredConcepts": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "state": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "owner", "required"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "owner": { "enum": ["application", "controlled", "component"] },
+              "required": { "type": "boolean" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "wiring": {
+          "type": "object",
+          "required": ["required", "helpers", "obligations"],
+          "properties": {
+            "required": { "type": "boolean" },
+            "helpers": { "$ref": "#/$defs/stringList" },
+            "obligations": { "$ref": "#/$defs/stringList" },
+            "stateAttributes": {
+              "description": "Optional wiring-owned state attributes: data-* attributes a wiring helper writes at runtime, which the application must not render, remove, or treat as its own state.",
+              "type": "array",
+              "items": { "$ref": "#/$defs/stateAttribute" }
+            }
+          },
+          "additionalProperties": false
+        },
+        "responsive": {
+          "type": "object",
+          "required": ["owner", "behaviors"],
+          "properties": {
+            "owner": {
+              "enum": ["application", "component", "shared", "not-applicable"]
+            },
+            "behaviors": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "layout": {
+          "type": "object",
+          "required": ["roles", "geometry"],
+          "properties": {
+            "roles": { "$ref": "#/$defs/stringList" },
+            "geometry": {
+              "type": "object",
+              "required": ["margin", "border", "padding"],
+              "properties": {
+                "margin": { "$ref": "#/$defs/geometryOwner" },
+                "border": { "$ref": "#/$defs/geometryOwner" },
+                "padding": { "$ref": "#/$defs/geometryOwner" },
+                "notes": { "$ref": "#/$defs/stringList" }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "geometryOwner": {
+      "enum": ["self", "parent", "child", "none", "conditional", "composed"]
+    }
+  }
+}

package/index.js

@@ -17,8 +17,18 @@
 // kerf-component` alone just works. No third-party dependencies — the
 // initializer is plain Node so `npm create` runs it with zero install latency.
 
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
+import process from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
 
@@ -41,7 +51,9 @@ const USAGE =
 async function promptForTarget() {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = await rl.question(`Directory (\`.\` for current) [${DEFAULT_NAME}]: `);
+    const answer = await rl.question(
+      `Directory (\`.\` for current) [${DEFAULT_NAME}]: `,
+    );
     return answer.trim() || DEFAULT_NAME;
   } finally {
     rl.close();
@@ -117,6 +129,19 @@ async function main(argv) {
   // verbatim (`_gitignore` → `.gitignore`).
   mkdirSync(targetDir, { recursive: true });
   cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
+  mkdirSync(join(targetDir, 'scripts'), { recursive: true });
+  copyFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), 'catalog.js'),
+    join(targetDir, 'scripts', 'kerf-component-catalog.mjs'),
+  );
+  for (const schema of [
+    'component-metadata.schema.json',
+    'component-composition.schema.json',
+  ])
+    copyFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), schema),
+      join(targetDir, 'scripts', schema),
+    );
 
   for (const file of walk(targetDir)) {
     const text = readFileSync(file, 'utf8');
@@ -136,8 +161,10 @@ async function main(argv) {
       cdHint +
       '  npm install\n' +
       '  npm run build      # tsup → ESM + .d.ts (kerfjs stays external)\n' +
+      '  npm run catalog:check # verify AI metadata and public exports\n' +
+      '  npm run check:styles  # each component styles only itself (kerf-ui-analyze)\n' +
       '  npm run typecheck\n\n' +
-      'Edit src/counter.tsx, then publish with `npm publish --access public`.\n',
+      'Edit src/counter.tsx, src/counter.css, and kerf.components.json, then publish with `npm publish --access public`.\n',
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kerf-component",
-  "version": "5.0.0-beta.9",
+  "version": "6.0.0-beta.1",
   "description": "Scaffold a publishable kerf component package that already follows kerf's hard packaging rules.",
   "type": "module",
   "license": "MIT",
@@ -26,15 +26,22 @@
     "node": ">=18.0.0"
   },
   "bin": {
-    "create-kerf-component": "index.js"
+    "create-kerf-component": "index.js",
+    "kerf-component-catalog": "catalog.js"
   },
   "files": [
     "index.js",
+    "catalog.js",
+    "component-metadata.schema.json",
+    "component-composition.schema.json",
     "template",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "node --test tests/*.test.js"
+  },
+  "dependencies": {
+    "typescript": "^5.0.0 || ^6.0.0"
   }
 }

package/template/README.md

@@ -1,4 +1,4 @@
-# __PKG_NAME__
+# **PKG_NAME**
 
 A reusable [kerf](https://github.com/brianwestphal/kerf) component package,
 scaffolded with `create-kerf-component`.
@@ -7,8 +7,10 @@ scaffolded with `create-kerf-component`.
 
 ```bash
 npm install
-npm run build       # tsup → dist/ (ESM + .d.ts); kerfjs stays external
+npm run build # tsup → dist/ (ESM + .d.ts); kerfjs stays external
 npm run typecheck
+npm run catalog:check # verify component-composition.json is current
+npm run check:styles # each component styles only itself (kerf-ui-analyze)
 ```
 
 ## Use it
@@ -17,13 +19,14 @@ A kerf app that already has `jsxImportSource: "kerfjs"` configured can import an
 render the component like any local function — there's no extra toolchain:
 
 ```tsx
-import { mount } from 'kerfjs';
-import { Counter, createCounter, wireCounter } from '__PKG_NAME__';
+import { mount } from "kerfjs";
+import { Counter, createCounter, wireCounter } from "__PKG_NAME__";
+import "__PKG_NAME__/counter.css";
 
-const counter = createCounter(0);          // per-instance state (a factory)
-const root = document.getElementById('app')!;
+const counter = createCounter(0); // per-instance state (a factory)
+const root = document.getElementById("app")!;
 
-mount(root, () => <Counter store={counter} label="Clicks" />);
+mount(root, () => <Counter store={counter} label="Clicks" size="compact" />);
 
 const dispose = wireCounter(root, counter); // delegation disposer (call on teardown)
 ```
@@ -31,7 +34,7 @@ const dispose = wireCounter(root, counter); // delegation disposer (call on tear
 ## The rules this package follows
 
 These are kerf's hard packaging rules (see the kerf docs,
-*Building reusable component packages*). The scaffold encodes them so you don't
+_Building reusable component packages_). The scaffold encodes them so you don't
 have to:
 
 - **`kerfjs` is a `peerDependency` and is `external` in the build — never
@@ -43,9 +46,17 @@ have to:
 - **No inline JSX event handlers.** Components are pure `(props) => SafeHtml`
   string-builders; emit `data-action` hooks and let the host wire events with
   `delegate()` (see `wireCounter`), which returns a disposer.
+- **Each component owns its styles; configure, never override.** `counter.css`
+  styles only `.kerf-counter` and its own internals and writes only
+  `--_kerf-counter-*` private variables (context it provides is named after
+  Counter). Consumers configure it through props (`size`) and its public token
+  (`--kerf-counter-gap`); when it must adapt inside a parent, Counter does so
+  in its own stylesheet (`.kui-toolbar .kerf-counter`). A needed variation with
+  no prop is a gap to add here, not an override for consumers.
+  `npm run check:styles` enforces this with `kerf-ui-analyze`.
 - **Build emits ESM + `.d.ts`; `tsconfig` sets `jsxImportSource: "kerfjs"`.**
 - **Never import `kerfjs/dev`.** kerf's dev diagnostics install global hooks, so
-  installing them is the consuming *app's* call, not a library's — the app
+  installing them is the consuming _app's_ call, not a library's — the app
   writes `if (import.meta.env.DEV) await import('kerfjs/dev')` in its own entry.
   To get the diagnostics while developing this package, add that line to your own
   test harness or demo page instead (it belongs to the harness, not to `src/`).
@@ -56,4 +67,36 @@ have to:
 npm publish --access public
 ```
 
-`prepublishOnly` runs the build first; `files` ships only `dist/` + docs.
+`prepublishOnly` checks the catalog and runs the build; `files` ships `dist/`,
+the metadata/catalog pair, the README, and the license.
+
+## AI component metadata
+
+`kerf.components.json` is the author-owned source for the component's purpose,
+public exports, composition rules, geometry ownership, tokens, accessibility,
+and source links. `boundaries.rootClass` explicitly names the public class that
+owns runtime geometry (or is `null` when none does); `publicClasses` order has no
+semantic meaning. Every public class is the component's rendered anatomy unless
+`boundaries.placeableClasses` lists it: once an app's `.kerf-ui-profile.json`
+declares this package's catalog under `catalogs`, `eslint-plugin-kerfjs`
+reports an app that writes `kerf-counter` onto its own `<div>` (`KUI-L103`) and
+tells it to render `Counter` instead. List a class there only when apps may legitimately
+place it themselves (a layout utility, item geometry on another carrier), and
+add `rootElement` when the component itself renders those classes on that tag.
+Keep decisions explicit: the generator deliberately does not
+derive semantic or geometry ownership from rendered appearance. It validates
+both this source and the generated catalog against the schema copies beside the
+checker, including rejection of unknown fields. Named exports must exist in
+the TypeScript/TSX syntax tree; JSX text, nested scopes, comments, and literals
+are not exports. The checker uses this package's installed TypeScript compiler,
+so run `npm install` before the first local catalog command.
+
+```bash
+npm run catalog:generate # write component-composition.json
+npm run catalog:check    # no writes; fail when metadata, source, or output drift
+```
+
+The generated catalog ships with the package. AI tools join each entry to
+Kerf's catalog by its `package:id` key, search this package first for
+application-specific concepts, and retain both packages' identities when
+following cross-catalog composition references.

package/template/component-composition.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-composition-extension.schema.json",
+  "schemaVersion": 1,
+  "package": "__PKG_NAME__",
+  "compatibility": {
+    "componentCatalog": "not-applicable",
+    "identity": "package:id"
+  },
+  "entries": [
+    {
+      "key": "__PKG_NAME__:counter",
+      "package": "__PKG_NAME__",
+      "id": "counter",
+      "name": "Counter",
+      "kind": "component",
+      "purpose": "Render a controlled counter with delegated increment and decrement actions.",
+      "publicExports": [
+        {
+          "name": "Counter",
+          "subpath": "."
+        },
+        {
+          "name": "CounterProps",
+          "subpath": "."
+        },
+        {
+          "name": "CounterState",
+          "subpath": "."
+        },
+        {
+          "name": "CounterStore",
+          "subpath": "."
+        },
+        {
+          "name": "createCounter",
+          "subpath": "."
+        },
+        {
+          "name": "wireCounter",
+          "subpath": "."
+        },
+        {
+          "name": "Counter",
+          "subpath": "./counter"
+        },
+        {
+          "name": "CounterProps",
+          "subpath": "./counter"
+        },
+        {
+          "name": "CounterState",
+          "subpath": "./counter"
+        },
+        {
+          "name": "CounterStore",
+          "subpath": "./counter"
+        },
+        {
+          "name": "createCounter",
+          "subpath": "./counter"
+        },
+        {
+          "name": "wireCounter",
+          "subpath": "./counter"
+        }
+      ],
+      "sourceLinks": [
+        "README.md#use-it",
+        "src/counter.tsx"
+      ],
+      "source": "src/counter.tsx",
+      "parents": {
+        "mode": "any",
+        "entries": []
+      },
+      "contexts": [
+        "controlled-counter"
+      ],
+      "zones": [],
+      "children": {
+        "mode": "listed",
+        "concepts": [
+          "decrement-control",
+          "value",
+          "increment-control"
+        ],
+        "requiredConcepts": [
+          "decrement-control",
+          "value",
+          "increment-control"
+        ]
+      },
+      "state": [
+        {
+          "id": "count",
+          "owner": "controlled",
+          "required": true
+        }
+      ],
+      "wiring": {
+        "required": true,
+        "helpers": [
+          "wireCounter"
+        ],
+        "obligations": [
+          "Retain and call the disposer returned by wireCounter."
+        ]
+      },
+      "responsive": {
+        "owner": "not-applicable",
+        "behaviors": []
+      },
+      "layout": {
+        "roles": [
+          "counter"
+        ],
+        "geometry": {
+          "margin": "none",
+          "border": "none",
+          "padding": "none"
+        }
+      },
+      "accessibility": {
+        "obligations": [
+          "Keep increment and decrement controls named and expose the current count as output."
+        ]
+      },
+      "boundaries": {
+        "rootClass": "kerf-counter",
+        "publicClasses": [
+          "kerf-counter"
+        ],
+        "publicTokens": [
+          "--kerf-counter-gap"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "README.md#use-it",
+        "composition": "README.md#the-rules-this-package-follows"
+      }
+    }
+  ]
+}