@kerfjs/ui 5.0.0-beta.55 → 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.
 
@@ -168,8 +168,8 @@ The same property-specific boundary applies beyond spacing: use `flex()` (or a
 finite keyword) for `Row.flex`, `Grid.flex`, and `List.flex`; length builders and intrinsic-size keywords for
 `Skeleton.width`/`height`; length builders for `Skeleton.radius`; and
 a foreground color for `SelectChoice.color` — `uiColor()` with a foreground
-token such as `success-on-quiet`, or `foregroundColorVar()` (fill aliases such
-as `uiColor('success')` are rejected). These grammars are not
+token such as `success-on-quiet`, or `foregroundColorVar()` (fill tokens such
+as `uiColor('success-fill-quiet')` are rejected). These grammars are not
 interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 `style` declarations; use `className`, public tokens, and component props.
 
@@ -197,6 +197,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `ListHeader`                                                        | `@kerfjs/ui/list-header`                | `@kerfjs/ui/list-header.css`           |
 | `ListInsetControl`                                                  | `@kerfjs/ui/list-inset-control`         | `@kerfjs/ui/list-inset-control.css`    |
 | `ListInsetText`                                                     | `@kerfjs/ui/list-inset-text`            | `@kerfjs/ui/list-inset-text.css`       |
+| `ContentItem`                                                       | `@kerfjs/ui/content-item`               | `@kerfjs/ui/content-item.css`          |
 | `Pane`                                                              | `@kerfjs/ui/pane`                       | `@kerfjs/ui/pane.css`                  |
 | `NavStack`                                                          | `@kerfjs/ui/nav-stack`                  | `@kerfjs/ui/nav-stack.css`             |
 | `wireNavStack`                                                      | `@kerfjs/ui/wire-nav-stack`             | —                                      |
@@ -213,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`          |
@@ -249,9 +251,9 @@ moving focus or DOM identity. When a product wants fewer visible commands at
 narrow widths, it chooses them: render a lower-priority command inside an
 app-owned "More" `PopupMenu` (in a `single` group with `nestedDropdown`).
 
-`DisclosureArrow` defaults to an 18px root-scaled decorative visual. Override
-`--kui-disclosure-arrow-size` at the narrowest useful scope when a consumer
-needs another size; the owning control still supplies interaction, naming, and
+`DisclosureArrow` defaults to an 18px root-scaled decorative visual. Pass a
+typed `size` (for example `size={remify(24)}` from `@kerfjs/ui/css-values`)
+when a consumer needs another size; the owning control still supplies interaction, naming, and
 expanded state. Kerf `Select` retains its independent Web Awesome expand-glyph
 scale of `.5` through `--kui-disclosure-icon-scale`. Author replacement
 `DisclosureArrow` icon content facing right before its configured direction
@@ -270,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,
@@ -290,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
@@ -313,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.
 
@@ -326,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
@@ -349,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,
@@ -375,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).
 
@@ -434,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
@@ -460,28 +482,35 @@ 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>
-    <div class="kui-content-item">Workspace details</div>
-  </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 `.kui-content-item`: 8px inline margin, a real 1px border
-(transparent by default), 8px padding, and 12px rounded corners. The pill
-modifier uses a 22px radius. A component can expose a transparent border or
+Ordinary children use `ContentItem` (`@kerfjs/ui/content-item`): 8px inline
+margin, a real 1px border (transparent by default), 8px padding, and 12px
+rounded corners. `shape="pill"` uses a 22px radius, and `frame="framed"` paints
+the neutral border only when the item marks a real distinction. A component can expose a transparent border or
 background without changing layout. `ListHeader` follows the same rule while
 keeping its dormant title and count-or-badge cluster separate from its optional
 44px action.
@@ -551,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
@@ -646,7 +679,7 @@ import "@kerfjs/ui/webawesome.css";
 import "@kerfjs/ui/select/register";
 ```
 
-That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it. `PopupMenu` follows the same rule: import `@kerfjs/ui/popup-menu/register` once to register the dropdown, item, button, and divider elements it renders.
+That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it. `PopupMenu` follows the same rule: import `@kerfjs/ui/popup-menu/register` once to register the dropdown, item, button, and divider elements it renders. Either registration also installs help tags: an icon-only Select, PopupMenu, or `aria-label`-named `<button>` in a `ToolbarControlGroup` shows its name in an `aria-hidden` tooltip on hover and keyboard focus. A toolbar with icon-only buttons but neither control imports `@kerfjs/ui/help-tags/register`, which registers only the tooltip.
 Use `label` for a visible label or `ariaLabel` for a visually hidden name. A
 nonempty visible label takes precedence when both are supplied. Kerf names the
 actual shadow combobox without adding visible label spacing; this also works

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;

package/ai/compile-time-contracts-v1.json

@@ -79,7 +79,7 @@
       "id": "KUI-T010",
       "publicImport": "@kerfjs/ui",
       "symbols": [
-        "DividerSides",
+        "Sides",
         "StateBannerUrgency",
         "TabActivation",
         "TextVariant",
@@ -89,7 +89,7 @@
         "ToolbarControlGroupTone"
       ],
       "kind": "finite-vocabulary",
-      "summary": "Finite public variant vocabularies, including canonical divider-edge combinations, are named exported unions rather than anonymous string sets."
+      "summary": "Finite public variant vocabularies, including canonical edge combinations, are named exported unions rather than anonymous string sets."
     },
     {
       "id": "KUI-T011",