create-kerf-component 5.0.0-beta.8 → 5.0.0-beta.81

package/README.md

@@ -11,6 +11,8 @@ npm create kerf-component@latest my-widgets
 cd my-widgets
 npm install
 npm run build
+npm run catalog:check
+npm run check:styles
 ```
 
 Run it with **no argument** (`npm create kerf-component`) and it prompts for the
@@ -20,7 +22,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 +37,57 @@ 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.
+- **A stylesheet that owns only its component** (`src/counter.css`, exported as
+  `./counter.css`): it styles `.kerf-counter` and its own internals, writes only
+  `--_kerf-counter-*` private variables (the context it gives its buttons is
+  named after Counter), exposes a typed `size` prop and one public token
+  (`--kerf-counter-gap`) as its configuration, and adapts itself inside a Kerf
+  UI Toolbar from its own stylesheet (`.kui-toolbar .kerf-counter`). `npm run
+check:styles` runs `kerf-ui-analyze` (from the `@kerfjs/ui` dev dependency)
+  over `src/`, so a rule that restyles another package's component, touches
+  its private variables, overrides a token a typed prop sets, or uses a hook
+  class (`KUI-L019`–`KUI-L022`) fails before `prepublishOnly` publishes.
+- **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-composition.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`.
+  `boundaries.placeableClasses` (optional) names the public classes an app may
+  write onto its own elements; every other public class is the component's
+  rendered anatomy, which `eslint-plugin-kerfjs` reports on an app-owned
+  element as `KUI-L103` with the component to render. `boundaries.rootElement`
+  names the element the component itself renders around its placeable classes,
+  so a plain element of that tag carrying them is reported too. Placeable
+  classes must be public; `rootElement` requires them.
+  A wrapper that renders a cataloged component declares it under
+  `composition.rendersAs` (for example
+  `["@kerfjs/ui:toolbar-control-group"]`), so the `ui-composition` lint treats
+  it as that root. Every key must resolve to an entry generated in the same run
+  or to an installed package's catalog.
+  Each `publicExports` item names a `package.json#exports` subpath that maps to
+  the `src/` file exporting it. A private, bundled application
+  (`package.json#private: true`) has no per-file `dist/` entries and is never
+  imported by package name, so its items may omit `subpath`
+  (`{ "name": "DemandSegmentsControl" }`); the checker then verifies the name
+  against the component's `source` file, which is how the UI lint resolves the
+  wrapper. A subpath it does declare is still checked against `exports`.
+  `private: true` is the only opt-in: a `.kerf-ui-profile.json` `scope` does
+  not change this. An application that is published to npm (an app shell), or
+  whose manifest omits `private`, either declares a real `subpath` for each
+  item or sets `"private": true`.
 
 ## Layout produced
 
@@ -43,13 +96,32 @@ 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-composition.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-composition.schema.json # emitted-catalog schema used by the checker
 ├── LICENSE             # MIT license with the package contributor notice
 ├── .gitignore
 ├── README.md
 └── src/
     ├── index.ts        # public barrel
-    └── counter.tsx     # factory + component + wire() disposer
+    ├── counter.tsx     # factory + component + wire() disposer
+    └── counter.css     # styles only Counter; configured by props and tokens
 ```
 
 This package is part of the kerf repository and releases in lockstep with
-`kerfjs`.
+`kerfjs`. The 5.0.0 template targets `kerfjs` and `@kerfjs/ui` on the 5.x
+line; the generated package keeps Kerf as a peer dependency and uses UI only
+for its authoring checks.
+
+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.