create-kerf-component 5.0.0-beta.55 → 5.0.0-beta.57

package/README.md

@@ -12,6 +12,7 @@ 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
@@ -36,11 +37,21 @@ 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-catalog-v2.json`; `npm run catalog:check` fails on drift, deleted
+  `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
@@ -54,6 +65,13 @@ A ready-to-publish component package that encodes the rules from the kerf docs
   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
@@ -79,17 +97,18 @@ my-widgets/
 ├── 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
+├── 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-catalog-v2.schema.json # emitted-catalog 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

package/catalog.js

@@ -20,7 +20,7 @@ const metadataSchema = JSON.parse(
   readFileSync(join(scriptRoot, 'component-metadata.schema.json'), 'utf8'),
 );
 const catalogSchema = JSON.parse(
-  readFileSync(join(scriptRoot, 'component-catalog-v2.schema.json'), 'utf8'),
+  readFileSync(join(scriptRoot, 'component-composition.schema.json'), 'utf8'),
 );
 
 export class CatalogError extends Error {
@@ -619,6 +619,31 @@ function validateComponent(
     diagnostics.push(
       `${at}.boundaries.rootClass: expected null or one publicClasses entry`,
     );
+  // An application may place only the declared subset of public classes on
+  // its own elements; every other public class is the component's rendered
+  // anatomy (eslint-plugin-kerfjs KUI-L103). `rootElement` names the element
+  // the component renders around its placeable classes.
+  if (component.boundaries && 'placeableClasses' in component.boundaries) {
+    validateStringList(
+      component.boundaries.placeableClasses,
+      `${at}.boundaries.placeableClasses`,
+      diagnostics,
+    );
+    for (const className of Array.isArray(component.boundaries.placeableClasses)
+      ? component.boundaries.placeableClasses
+      : [])
+      if (!component.boundaries.publicClasses?.includes(className))
+        diagnostics.push(
+          `${at}.boundaries.placeableClasses: ${className} is not one of publicClasses`,
+        );
+  }
+  if (
+    component.boundaries?.rootElement !== undefined &&
+    !component.boundaries.placeableClasses?.length
+  )
+    diagnostics.push(
+      `${at}.boundaries.rootElement: requires a non-empty placeableClasses`,
+    );
   validateStringList(
     component.boundaries?.publicTokens,
     `${at}.boundaries.publicTokens`,
@@ -697,7 +722,7 @@ function dependencyCatalogKeys(packageRoot, packageName, cache) {
       } catch {
         // An unreadable manifest leaves the package unresolved below.
       }
-      catalogPath ??= join(dependencyRoot, 'ai', 'component-catalog-v2.json');
+      catalogPath ??= join(dependencyRoot, 'ai', 'component-composition.json');
       try {
         const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
         keys = new Set(
@@ -800,11 +825,11 @@ export function generateCatalogs(root = process.cwd()) {
       .map((component) => toEntry(packageJson.name, component));
     const catalog = {
       $schema:
-        'https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-catalog-extension-v2.schema.json',
-      schemaVersion: 2,
+        'https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-composition-extension.schema.json',
+      schemaVersion: 1,
       package: packageJson.name,
       compatibility: {
-        v1Catalog: metadata.v1Catalog ?? 'not-applicable',
+        componentCatalog: metadata.componentCatalog ?? 'not-applicable',
         identity: 'package:id',
       },
       entries,

package/{component-catalog-v2.schema.json → component-composition.schema.json}

@@ -1,18 +1,25 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-catalog-v2.schema.json",
-  "title": "Kerf UI composition catalog v2",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-composition.schema.json",
+  "title": "Kerf UI composition catalog",
   "type": "object",
   "required": ["schemaVersion", "package", "compatibility", "entries"],
   "properties": {
     "$schema": { "type": "string" },
-    "schemaVersion": { "const": 2 },
+    "schemaVersion": {
+      "const": 1,
+      "description": "Version of the composition catalog format itself, independent of component-catalog.json's own schemaVersion."
+    },
     "package": { "type": "string", "minLength": 1 },
     "compatibility": {
       "type": "object",
-      "required": ["v1Catalog", "identity"],
+      "required": ["componentCatalog", "identity"],
       "properties": {
-        "v1Catalog": { "type": "string", "minLength": 1 },
+        "componentCatalog": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Relative path to the component (selection) catalog this composition layer describes, or \"not-applicable\" when the package publishes none."
+        },
         "identity": { "const": "package:id" }
       },
       "additionalProperties": false
@@ -274,6 +281,15 @@
               ]
             },
             "publicClasses": { "$ref": "#/$defs/stringList" },
+            "placeableClasses": {
+              "$ref": "#/$defs/stringList",
+              "description": "The subset of publicClasses an application may place on its own elements. Absent means none: every public class is the component's rendered anatomy, reached by rendering the component."
+            },
+            "rootElement": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+              "description": "The intrinsic element the component renders at its root. A placeableClasses class on a plain element of this tag recreates the component; the class stays placeable on any other carrier element."
+            },
             "publicTokens": { "$ref": "#/$defs/stringList" },
             "publicParts": { "$ref": "#/$defs/stringList" }
           },

package/component-metadata.schema.json

@@ -7,7 +7,11 @@
   "properties": {
     "$schema": { "type": "string" },
     "schemaVersion": { "const": 1 },
-    "v1Catalog": { "type": "string", "minLength": 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" }
@@ -121,6 +125,15 @@
               ]
             },
             "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

package/index.js

@@ -136,7 +136,7 @@ async function main(argv) {
   );
   for (const schema of [
     'component-metadata.schema.json',
-    'component-catalog-v2.schema.json',
+    'component-composition.schema.json',
   ])
     copyFileSync(
       join(dirname(fileURLToPath(import.meta.url)), schema),
@@ -162,8 +162,9 @@ async function main(argv) {
       '  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 and kerf.components.json, 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.55",
+  "version": "5.0.0-beta.57",
   "description": "Scaffold a publishable kerf component package that already follows kerf's hard packaging rules.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "index.js",
     "catalog.js",
     "component-metadata.schema.json",
-    "component-catalog-v2.schema.json",
+    "component-composition.schema.json",
     "template",
     "README.md",
     "LICENSE"

package/template/README.md

@@ -9,7 +9,8 @@ scaffolded with `create-kerf-component`.
 npm install
 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
+npm run catalog:check # verify component-composition.json is current
+npm run check:styles # each component styles only itself (kerf-ui-analyze)
 ```
 
 ## Use it
@@ -20,11 +21,12 @@ 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 "__PKG_NAME__/counter.css";
 
 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)
 ```
@@ -44,6 +46,14 @@ 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
@@ -66,7 +76,14 @@ the metadata/catalog pair, the README, and the license.
 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
+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
@@ -75,7 +92,7 @@ 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:generate # write component-composition.json
 npm run catalog:check    # no writes; fail when metadata, source, or output drift
 ```
 

package/template/{component-catalog-v2.json → component-composition.json}

@@ -1,9 +1,9 @@
 {
-  "$schema": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-catalog-extension-v2.schema.json",
-  "schemaVersion": 2,
+  "$schema": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-composition-extension.schema.json",
+  "schemaVersion": 1,
   "package": "__PKG_NAME__",
   "compatibility": {
-    "v1Catalog": "not-applicable",
+    "componentCatalog": "not-applicable",
     "identity": "package:id"
   },
   "entries": [
@@ -130,7 +130,9 @@
         "publicClasses": [
           "kerf-counter"
         ],
-        "publicTokens": []
+        "publicTokens": [
+          "--kerf-counter-gap"
+        ]
       },
       "diagnostics": [],
       "provenance": {

package/template/kerf.components.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/brianwestphal/kerf/main/create-kerf-component/component-metadata.schema.json",
   "schemaVersion": 1,
-  "v1Catalog": "not-applicable",
+  "componentCatalog": "not-applicable",
   "components": [
     {
       "id": "counter",
@@ -54,7 +54,7 @@
       "boundaries": {
         "rootClass": "kerf-counter",
         "publicClasses": ["kerf-counter"],
-        "publicTokens": []
+        "publicTokens": ["--kerf-counter-gap"]
       },
       "accessibility": {
         "obligations": [

package/template/package.json

@@ -12,11 +12,13 @@
     "./counter": {
       "types": "./dist/counter.d.ts",
       "import": "./dist/counter.js"
-    }
+    },
+    "./counter.css": "./src/counter.css"
   },
   "files": [
     "dist",
-    "component-catalog-v2.json",
+    "src/counter.css",
+    "component-composition.json",
     "kerf.components.json",
     "README.md",
     "LICENSE"
@@ -25,18 +27,20 @@
     "build": "tsup",
     "catalog:generate": "node scripts/kerf-component-catalog.mjs --write",
     "catalog:check": "node scripts/kerf-component-catalog.mjs --check",
+    "check:styles": "kerf-ui-analyze --root . src",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run catalog:check && npm run build"
+    "prepublishOnly": "npm run catalog:check && npm run check:styles && npm run build"
   },
   "kerfComponentCatalog": {
     "source": "./kerf.components.json",
-    "output": "./component-catalog-v2.json"
+    "output": "./component-composition.json"
   },
   "peerDependencies": {
     "kerfjs": "^5.0.0-0"
   },
   "devDependencies": {
-    "kerfjs": "^5.0.0-beta.55",
+    "kerfjs": "^5.0.0-beta.57",
+    "@kerfjs/ui": "^5.0.0-beta.57",
     "tsup": "^8",
     "typescript": "^5 || ^6"
   }

package/template/src/counter.css

@@ -0,0 +1,38 @@
+/*
+ * Counter owns this stylesheet, and this stylesheet styles only Counter.
+ *
+ * - It selects `.kerf-counter` and Counter's own internals, never another
+ *   component's class, `[data-component]` root, `wa-*` element, or `::part()`.
+ * - It writes only Counter's own `--_kerf-counter-*` private variables. The
+ *   context Counter hands its buttons is named after Counter, the provider.
+ * - Consumers configure Counter through its typed props (`size`) and its one
+ *   public theme token (`--kerf-counter-gap`), never by restyling
+ *   `.kerf-counter` from their own CSS. A need with no prop is a gap to add to
+ *   Counter, not an override for the consumer to write.
+ */
+.kerf-counter {
+  --_kerf-counter-gap: var(--kerf-counter-gap, 0.5rem);
+  --_kerf-counter-control-size: 2rem;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--_kerf-counter-gap);
+}
+
+.kerf-counter[data-size="compact"] {
+  --_kerf-counter-control-size: 1.5rem;
+}
+
+.kerf-counter > button {
+  inline-size: var(--_kerf-counter-control-size);
+  block-size: var(--_kerf-counter-control-size);
+}
+
+/*
+ * Parent context: when a Counter sits in a Kerf UI Toolbar, Counter adapts
+ * itself here, in its own stylesheet. The parent appears only as an ancestor
+ * and Counter stays the subject, so the Toolbar never styles Counter and
+ * Counter never styles the Toolbar.
+ */
+.kui-toolbar .kerf-counter {
+  --_kerf-counter-control-size: 1.75rem;
+}

package/template/src/counter.tsx

@@ -28,6 +28,11 @@ export type CounterStore = ReturnType<typeof createCounter>;
 export interface CounterProps {
   store: CounterStore;
   label?: string;
+  /**
+   * Control density. A typed prop is how consumers configure the component's
+   * look; they never restyle `.kerf-counter` from their own CSS.
+   */
+  size?: 'standard' | 'compact';
 }
 
 /**
@@ -35,10 +40,17 @@ export interface CounterProps {
  * `data-action` hooks instead of inline event handlers — inline `onClick={...}`
  * handlers don't survive kerf's morph (and the `no-inline-jsx-event-handlers`
  * lint rule flags them). The host wires the events; see `wireCounter` below.
+ *
+ * Its look lives in `counter.css` (the `./counter.css` export), which styles
+ * only Counter; `size` is the configuration consumers use instead of CSS.
  */
-export function Counter({ store, label = 'Count' }: CounterProps): SafeHtml {
+export function Counter({
+  store,
+  label = 'Count',
+  size = 'standard',
+}: CounterProps): SafeHtml {
   return (
-    <div class="kerf-counter">
+    <div class="kerf-counter" data-size={size}>
       <button type="button" data-action="counter:dec" aria-label="Decrement">
         −
       </button>