create-kerf-component 5.0.0-beta.5 → 5.0.0-beta.51

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,9 @@ 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-catalog-v2.json is current
 ```
 
 ## Use it
@@ -17,11 +18,11 @@ 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__";
 
-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" />);
 
@@ -31,7 +32,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
@@ -45,7 +46,7 @@ have to:
   `delegate()` (see `wireCounter`), which returns a disposer.
 - **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 +57,29 @@ 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. 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-catalog-v2.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-catalog-v2.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-catalog-extension-v2.schema.json",
+  "schemaVersion": 2,
+  "package": "__PKG_NAME__",
+  "compatibility": {
+    "v1Catalog": "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": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "README.md#use-it",
+        "composition": "README.md#the-rules-this-package-follows"
+      }
+    }
+  ]
+}

package/template/kerf.components.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://raw.githubusercontent.com/brianwestphal/kerf/main/create-kerf-component/component-metadata.schema.json",
+  "schemaVersion": 1,
+  "v1Catalog": "not-applicable",
+  "components": [
+    {
+      "id": "counter",
+      "name": "Counter",
+      "kind": "component",
+      "purpose": "Render a controlled counter with delegated increment and decrement actions.",
+      "source": "src/counter.tsx",
+      "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"],
+      "composition": {
+        "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" }
+        }
+      },
+      "boundaries": {
+        "rootClass": "kerf-counter",
+        "publicClasses": ["kerf-counter"],
+        "publicTokens": []
+      },
+      "accessibility": {
+        "obligations": [
+          "Keep increment and decrement controls named and expose the current count as output."
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "README.md#use-it",
+        "composition": "README.md#the-rules-this-package-follows"
+      }
+    }
+  ]
+}

package/template/package.json

@@ -16,19 +16,27 @@
   },
   "files": [
     "dist",
+    "component-catalog-v2.json",
+    "kerf.components.json",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsup",
+    "catalog:generate": "node scripts/kerf-component-catalog.mjs --write",
+    "catalog:check": "node scripts/kerf-component-catalog.mjs --check",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run catalog:check && npm run build"
+  },
+  "kerfComponentCatalog": {
+    "source": "./kerf.components.json",
+    "output": "./component-catalog-v2.json"
   },
   "peerDependencies": {
     "kerfjs": "^5.0.0-0"
   },
   "devDependencies": {
-    "kerfjs": "^5.0.0-beta.5",
+    "kerfjs": "^5.0.0-beta.51",
     "tsup": "^8",
     "typescript": "^5 || ^6"
   }

package/template/src/counter.tsx

@@ -61,7 +61,10 @@ export function Counter({ store, label = 'Count' }: CounterProps): SafeHtml {
  * single listener survives every re-render. Returns the disposer `delegate()`
  * hands back — call it when the host unmounts.
  */
-export function wireCounter(root: HTMLElement, store: CounterStore): () => void {
+export function wireCounter(
+  root: HTMLElement,
+  store: CounterStore,
+): () => void {
   return delegate(root, 'click', '[data-action^="counter:"]', (_event, el) => {
     const action = el.getAttribute('data-action');
     if (action === 'counter:inc') store.actions.inc();