@kerfjs/ui 5.0.0-beta.56 → 5.0.0-beta.57

package/README.md

@@ -97,7 +97,7 @@ primary region, while semantic positions and replacement content use explicit
 named `SafeHtml` props such as `header`, `footer`, `leading`, `trailing`,
 `icon`, and `action`. These named `SafeHtml` prop slots are ordinary typed
 function-component props—not native `<slot>` elements, wrapper slot
-components, or a generic `slots` object. The v2 composition catalog publishes
+components, or a generic `slots` object. The composition catalog publishes
 sound prop bindings as `zone.jsx.prop`, allowing ESLint to validate statically
 visible content and cardinality without guessing from zone names.
 
@@ -214,6 +214,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `AppTab`                                                            | `@kerfjs/ui/app-tab`                    | `@kerfjs/ui/app-tab.css`               |
 | `TabBar`                                                            | `@kerfjs/ui/tab-bar`                    | `@kerfjs/ui/tab-bar.css`               |
 | `wireTabBars`, `reorderTabs`                                        | `@kerfjs/ui/wire-tab-bars`              | —                                      |
+| `wireScrollDividers`                                                | `@kerfjs/ui/wire-scroll-dividers`       | —                                      |
 | `LoadingSpinner`                                                    | `@kerfjs/ui/loading-spinner`            | `@kerfjs/ui/loading-spinner.css`       |
 | `Skeleton`                                                          | `@kerfjs/ui/skeleton`                   | `@kerfjs/ui/skeleton.css`              |
 | `SunkenPanel`                                                       | `@kerfjs/ui/sunken-panel`               | `@kerfjs/ui/sunken-panel.css`          |
@@ -271,7 +272,19 @@ action at the logical end. Its visible action glyph defaults to 18px through
 
 ## Machine-readable catalog
 
-AI tools can retrieve the shipped [`ai/component-catalog.json`](./ai/component-catalog.json)
+AI assistants should start from the generated markdown reference,
+[`ai/components/README.md`](./ai/components/README.md): a one-line index of
+every entry grouped like the catalog, plus one short page per entry
+(`ai/components/<id>.md`) covering when to use and avoid it, imports and
+CSS/registration side effects, where its exact props live, legal parents,
+zones with their JSX props and child counts, app- and wiring-owned state,
+geometry ownership, accessibility obligations, the styling boundary
+(configure through props; never override internals), and its composition
+diagnostics. The pages are projected from the two JSON catalogs by
+`scripts/sync-component-docs.mjs` (`npm run catalog:sync`), and
+`npm run check:catalog` fails when any page drifts.
+
+Tools can retrieve the shipped [`ai/component-catalog.json`](./ai/component-catalog.json)
 for the exhaustive component and composition inventory. It is the canonical
 source for ids, public exports, purpose and selection guidance, relationships,
 delivery and side effects, companion wiring, application-owned policy,
@@ -291,14 +304,16 @@ Keeping this as a companion artifact prevents per-entry selection facts from
 duplicating presentation rules.
 
 Tools that evaluate composition may additionally load
-[`component-catalog-v2.json`](./ai/component-catalog-v2.json). It is a
-deterministic, package-qualified projection of every v1 entry with formal
-parent/context, zone/cardinality, child, state ownership, wiring, responsive,
-layout, accessibility, public-boundary, and stable-diagnostic fields. V1
-remains the selection and delivery compatibility surface. V2 defaults are
+[`component-composition.json`](./ai/component-composition.json). It is a
+generated composition layer beside `component-catalog.json`, not a newer
+version of it: a deterministic, package-qualified projection of every
+component-catalog entry with formal parent/context, zone/cardinality, child,
+state ownership, wiring, responsive, layout, accessibility, public-boundary,
+and stable-diagnostic fields. `component-catalog.json` remains the selection
+and delivery surface. Composition defaults are
 deliberately permissive; only documented objective rules receive an
 authoritative override and enforceable diagnostic. The adjacent schema and
-[`component-catalog-v2.d.ts`](./ai/component-catalog-v2.d.ts) types describe
+[`component-composition.d.ts`](./ai/component-composition.d.ts) types describe
 the same contract.
 
 Applications and downstream design systems should publish the same facts for
@@ -314,9 +329,9 @@ tool reason about both sides of a composition using one vocabulary without
 pretending app-local components are `@kerfjs/ui` exports.
 
 Composition-aware consumers use
-[`component-catalog-extension-v2.schema.json`](./ai/component-catalog-extension-v2.schema.json),
+[`component-composition-extension.schema.json`](./ai/component-composition-extension.schema.json),
 its shipped TypeScript types, and the checked
-[`component-catalog-extension-v2.json`](./docs/examples/component-catalog-extension-v2.json)
+[`component-composition-extension.json`](./docs/examples/component-composition-extension.json)
 example. Preserve each catalog's package and qualify every identity and
 cross-catalog reference as `package:id`; never merge entries by bare id.
 
@@ -327,7 +342,7 @@ rejects. The package gate compiles one positive/negative consumer fixture agains
 both source and declarations extracted from the real packed tarball. The
 [compile-time contract guide](./docs/type-contracts.md) documents migrations and
 the dynamic DOM/children relationships that remain runtime or catalog checks.
-Packages scaffolded by `create-kerf-component` maintain this v2 input from
+Packages scaffolded by `create-kerf-component` maintain this composition input from
 `kerf.components.json`: `npm run catalog:generate` emits the catalog and
 `npm run catalog:check` verifies source files, named public exports, explicit
 author decisions, and byte-for-byte drift. Tools index the generated consumer
@@ -350,9 +365,9 @@ token overrides, layout/responsive conventions, and narrow rule exceptions.
 Profiles contain policy only—never product records, user data, or broad styling
 waivers.
 
-Catalog declarations always provide a v2 `composition` location. Consumer
+Catalog declarations always provide a `composition` location. Consumer
 packages generated with composition-only metadata omit `selection`;
-`@kerfjs/ui` continues to require its v1 selection catalog.
+`@kerfjs/ui` continues to require its `component-catalog.json` selection catalog.
 
 Node-based AI and static-analysis tools may import the shipped discovery API
 from `@kerfjs/ui/ai/application-ui-profile.mjs`. It discovers package defaults,
@@ -376,9 +391,12 @@ Run `kerf-ui-analyze --root . src` (or import
 composition catalogs and application profile. It catches provable private
 selector reach-through, unknown tokens, competing geometry owners, nested
 scroll owners, and cataloged CSS-value violations in JavaScript/TypeScript
-component calls and JSX. It reports forced dimensions, repeated insets,
-exceptional spacing shorthands, and dynamic classes separately as review
-findings. Text, versioned JSON,
+component calls and JSX, plus component-ownership overrides: CSS that makes
+another package's component its subject, touches its private variables,
+overrides a token its typed prop sets, or styles it through a hook class on
+its root (`KUI-L019`–`KUI-L022`; forcing a component's dimensions is one such
+restyle). It reports repeated insets, exceptional spacing shorthands, and
+dynamic classes separately as review findings. Text, versioned JSON,
 and SARIF outputs carry stable `KUI-L###` ids, repository-relative locations,
 evidence, and ownership chains. See the [analyzer guide](./docs/ui-analyzer.md).
 
@@ -435,7 +453,10 @@ file.
 
 `npm run check:css-ownership` keeps that boundary honest: application CSS may
 style only application-owned structure, never package component classes or
-Web Awesome descendants. The UX catalog's `style.css` contains document-shell
+Web Awesome descendants, and a package component's stylesheet styles only
+itself (in a composing parent's context when needed) — never another kerf
+component's root, the `wa-*` tags it renders, its variables, or a hook class on
+its root. The UX catalog's `style.css` contains document-shell
 mechanics only, recipes ship no stylesheets (`npm run check:recipes` rejects
 route stylesheets, inline styles, and styling-only classes), and `catalog.css`
 remains a
@@ -461,23 +482,29 @@ component browser imports. See [Document baseline](./docs/document-baseline.md).
 
 ## Pane and content geometry
 
-Import `@kerfjs/ui/layout.css` and use the same structural vocabulary for a
-sidebar, main area, inspector, or dialog. `.kui-pane` is unpadded and contains
-an optional toolbar, one scrolling `.kui-pane__content`, and an optional footer.
-Add `.kui-content` to make its major children a vertical stack with 24px gaps.
+Render `Pane` (`@kerfjs/ui/pane`) for a sidebar, main area, inspector, or
+dialog: the same structural vocabulary everywhere. Its `.kui-pane` root is
+unpadded and contains an optional header, one scrolling `.kui-pane__content`,
+and an optional footer; the content slot already carries `.kui-content`, which
+makes its major children a vertical stack with 24px gaps. Choose landmark
+semantics with `element` / `contentElement` rather than writing the pane
+classes onto your own elements — `eslint-plugin-kerfjs` reports a component's
+anatomy class on an application-owned element as `KUI-L103`.
 
 ```tsx
-<aside class="kui-pane">
-  <div class="kui-pane__toolbar"><Toolbar label="Workspace" ... /></div>
-  <nav class="kui-pane__content kui-content">
-    <section>
-      <ListHeader label="Workspace" count={3} countLabel="3 workspaces" />
-      <ListItem action="open" label="Inbox" icon={inboxIcon} />
-      <ListItem action="open" label="Drafts" />
-    </section>
-    <ContentItem>Workspace details</ContentItem>
-  </nav>
-</aside>
+<Pane
+  element="aside"
+  label="Workspace"
+  contentElement="nav"
+  header={<Toolbar label="Workspace" ... />}
+>
+  <section>
+    <ListHeader label="Workspace" count={3} countLabel="3 workspaces" />
+    <ListItem action="open" label="Inbox" icon={inboxIcon} />
+    <ListItem action="open" label="Drafts" />
+  </section>
+  <ContentItem>Workspace details</ContentItem>
+</Pane>
 ```
 
 Ordinary children use `ContentItem` (`@kerfjs/ui/content-item`): 8px inline
@@ -553,6 +580,10 @@ arrays support diagnostics, tooling, browser assertions, and package-owned
 composition; they are not an application styling API. Application-owned CSS may
 style new structure rendered by its own component, but it must not select a
 nested Kerf or Web Awesome component. Add missing configuration to the owner.
+Markup follows the same rule: write only an entry's `placeableClasses` (layout
+utilities, `kui-app-root`, `kui-content-item` on a non-div carrier) onto your
+own elements; any other public class recreates a component by class, which
+`eslint-plugin-kerfjs` reports as `KUI-L103` with the component to render.
 
 `StateBanner` has opinionated `neutral`, `info`, `pop`, `success`, `warning`,
 and `danger` palettes. Override an individual banner with

package/ai/application-ui-diagnostic-ids-v1.json

@@ -47,9 +47,14 @@
     "KUI-L016",
     "KUI-L017",
     "KUI-L018",
+    "KUI-L019",
+    "KUI-L020",
+    "KUI-L021",
+    "KUI-L022",
     "KUI-L090",
     "KUI-L101",
     "KUI-L102",
+    "KUI-L103",
     "KUI-L201",
     "KUI-L202",
     "KUI-L203",
@@ -97,5 +102,8 @@
     "KUI-T009",
     "KUI-T010",
     "KUI-T011"
-  ]
+  ],
+  "retired": {
+    "KUI-L005": "Folded into KUI-L019: any application rule whose subject is a cataloged component, forced dimensions included. Kept in ids so existing profile exceptions that name it still load."
+  }
 }

package/ai/application-ui-profile-sync.cjs

@@ -202,7 +202,7 @@ function validateApplicationUiProfile(profile, options = {}) {
       add(
         'KUI-P005',
         `${path}.selection`,
-        'The @kerfjs/ui catalog requires its v1 selection location.',
+        'The @kerfjs/ui catalog requires its component-catalog.json selection location.',
       );
     for (const kind of ['selection', 'composition']) {
       if (kind === 'selection' && !catalog[kind]) continue;

package/ai/application-ui-profile.defaults.json

@@ -5,22 +5,77 @@
   "catalogs": [
     {
       "package": "@kerfjs/ui",
-      "selection": { "path": "./component-catalog.json", "schemaVersion": 1 },
+      "selection": {
+        "path": "./component-catalog.json",
+        "schemaVersion": 1
+      },
       "composition": {
-        "path": "./component-catalog-v2.json",
-        "schemaVersion": 2
+        "path": "./component-composition.json",
+        "schemaVersion": 1
       }
     }
   ],
   "preferences": {
-    "application-shell": { "preferred": "@kerfjs/ui:recipe-app-shell" },
+    "application-shell": {
+      "preferred": "@kerfjs/ui:recipe-app-shell"
+    },
+    "application-tabs": {
+      "preferred": "@kerfjs/ui:tab-bar",
+      "avoid": [
+        "@kerfjs/ui:wa-tab-group",
+        "@kerfjs/ui:wa-tab",
+        "@kerfjs/ui:wa-tab-panel"
+      ],
+      "rationale": "Render TabBar (or SegmentedControl for a view switch) instead of composing Web Awesome tabs directly."
+    },
+    "command-menu": {
+      "preferred": "@kerfjs/ui:popup-menu",
+      "avoid": ["@kerfjs/ui:wa-dropdown", "@kerfjs/ui:wa-dropdown-item"],
+      "rationale": "Render PopupMenu, which wraps wa-dropdown with the shared popup contract; use Select when choosing a value."
+    },
+    "embedded-media": {
+      "preferred": "@kerfjs/ui:content-item",
+      "avoid": [
+        "@kerfjs/ui:wa-animated-image",
+        "@kerfjs/ui:wa-comparison",
+        "@kerfjs/ui:wa-zoomable-frame"
+      ],
+      "rationale": "Keep media behavior application-owned: place a native img, video, or iframe in a ContentItem. Record a narrow KUI-L301 profile exception only when a concrete product requirement needs this Web Awesome element."
+    },
     "exclusive-choice": {
       "preferred": "@kerfjs/ui:segmented-control",
-      "avoid": ["@kerfjs/ui:wa-button-group"]
+      "avoid": ["@kerfjs/ui:wa-button-group"],
+      "rationale": "Render SegmentedControl for one-of-N choices instead of a Web Awesome button group."
+    },
+    "hierarchy-navigation": {
+      "preferred": "@kerfjs/ui:list",
+      "avoid": ["@kerfjs/ui:wa-tree", "@kerfjs/ui:wa-tree-item"],
+      "rationale": "Present hierarchy as List rows (or NavStack drill-in levels). Record a narrow KUI-L301 profile exception only when the product requires tree behavior."
+    },
+    "icon": {
+      "preferred": "@kerfjs/ui:lucide-icon",
+      "avoid": ["@kerfjs/ui:wa-icon"],
+      "rationale": "Render LucideIcon; Web Awesome icons are not part of the Kerf icon contract."
     },
-    "navigation-row": { "preferred": "@kerfjs/ui:list-item" },
-    "panel-heading": { "preferred": "@kerfjs/ui:toolbar" },
-    "structured-search": { "preferred": "@kerfjs/ui:token-search-field" }
+    "navigation-row": {
+      "preferred": "@kerfjs/ui:list-item"
+    },
+    "panel-heading": {
+      "preferred": "@kerfjs/ui:toolbar"
+    },
+    "resizable-pane": {
+      "preferred": "@kerfjs/ui:resize",
+      "avoid": ["@kerfjs/ui:wa-split-panel"],
+      "rationale": "Render ResizableRegion for application panes instead of a Web Awesome split panel."
+    },
+    "structured-search": {
+      "preferred": "@kerfjs/ui:token-search-field"
+    },
+    "value-selection": {
+      "preferred": "@kerfjs/ui:select",
+      "avoid": ["@kerfjs/ui:wa-select", "@kerfjs/ui:wa-option"],
+      "rationale": "Render Select, which wraps wa-select and wa-option with Kerf's popup and spacing contract."
+    }
   },
   "theme": {
     "colorScheme": "light",

package/ai/application-ui-profile.mjs

@@ -289,7 +289,7 @@ export function validateApplicationUiProfile(
       add(
         'KUI-P005',
         `${path}.selection`,
-        'The @kerfjs/ui catalog requires its v1 selection location.',
+        'The @kerfjs/ui catalog requires its component-catalog.json selection location.',
       );
     for (const kind of ['selection', 'composition']) {
       if (kind === 'selection' && !catalog?.selection) continue;