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

package/README.md

@@ -11,6 +11,7 @@ npm create kerf-component@latest my-widgets
 cd my-widgets
 npm install
 npm run build
+npm run catalog:check
 ```
 
 Run it with **no argument** (`npm create kerf-component`) and it prompts for the
@@ -20,7 +21,7 @@ directory's basename is used as the package name.
 ## What you get
 
 A ready-to-publish component package that encodes the rules from the kerf docs
-(*Building reusable component packages*):
+(_Building reusable component packages_):
 
 - **`kerfjs` as a `peerDependency`, `external` in the tsup build** — never
   bundled, so `isSafeHtml` brand checks and signal identity stay intact across
@@ -35,6 +36,24 @@ A ready-to-publish component package that encodes the rules from the kerf docs
   component needs:
   - **per-instance state via a factory + props** (`createCounter` → `<Counter store={…} />`), and
   - **a `wire(root)` delegation disposer** (`wireCounter`) instead of inline event handlers.
+- **Author-owned AI metadata** in `kerf.components.json`, with explicit purpose,
+  exports, composition, geometry, public `rootClass`, tokens, accessibility,
+  and source links. Run
+  `npm run catalog:generate` to emit the package-qualified
+  `component-catalog-v2.json`; `npm run catalog:check` fails on drift, deleted
+  sources, renamed exports, duplicate ids, an omitted author decision, or any
+  source/output field that violates the shipped schemas. Export verification
+  uses the TypeScript/TSX syntax tree, so JSX text, nested scopes, comments, and
+  string/template/regular-expression literals cannot masquerade as public
+  exports. The scaffold already declares TypeScript; run `npm install` before
+  invoking its copied local checker in a fresh offline directory.
+  A component whose wiring helper writes runtime `data-*` state onto its DOM
+  can declare it under `composition.wiring.stateAttributes` — each item is
+  `{ name, on, helper, meaning }`, where `name` is a `data-*` name, `on` is the
+  element that carries it, and `helper` is one of `wiring.helpers`. Apps must
+  not render, remove, or treat those attributes as their own state. The field
+  is optional; names must be unique per component, and the checker rejects a
+  helper that is not listed in `wiring.helpers`.
 
 ## Layout produced
 
@@ -43,6 +62,12 @@ my-widgets/
 ├── package.json        # peerDependencies.kerfjs, exports map, publish files
 ├── tsconfig.json       # jsxImportSource: "kerfjs"
 ├── tsup.config.ts      # external: ['kerfjs'], format esm, dts
+├── kerf.components.json # explicit source metadata (never inferred from pixels)
+├── component-catalog-v2.json # deterministic generated AI catalog
+├── scripts/
+│   ├── kerf-component-catalog.mjs # local generator + check mode
+│   ├── component-metadata.schema.json # author-source schema used by the checker
+│   └── component-catalog-v2.schema.json # emitted-catalog schema used by the checker
 ├── LICENSE             # MIT license with the package contributor notice
 ├── .gitignore
 ├── README.md
@@ -53,3 +78,13 @@ my-widgets/
 
 This package is part of the kerf repository and releases in lockstep with
 `kerfjs`.
+
+The package also exposes `kerf-component-catalog`. It accepts `--write` (the
+default), `--check`, and `--root <path>`. A root package with npm `workspaces`
+generates every child package that declares `package.json#kerfComponentCatalog`,
+in deterministic package and component order.
+
+Application projects do not need this package scaffold. `npx kerfjs setup
+--ui` creates an empty, schema-valid author metadata file, wires this catalog
+command, and publishes the generated app catalog through the workspace UI
+profile.