@kerfjs/ui 5.0.0-beta.18 → 5.0.0-beta.21

package/README.md

@@ -4,6 +4,13 @@ Accessible, composable UI primitives for [kerf](https://github.com/brianwestphal
 
 Start interface work with the [need-first component selection matrix](./docs/component-selection.md). It distinguishes direct reuse, composition, thin application adapters, and genuinely custom semantics, with imports, required wiring, application ownership, alternatives, and recipes for every public primitive.
 
+When authoring a component gallery, follow the single
+[Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)
+for focused-versus-composition modes, helper nesting, specimen selection,
+geometry inspection, and metadata ownership. AI tools can discover that
+contract and its public imports through the shipped
+[`catalog-authoring.json`](./ai/catalog-authoring.json) artifact.
+
 For connective application patterns, use the seven [production composition
 recipes](./docs/recipes.md). Each has a stable catalog route, runnable state,
 public-subpath source, semantic layout ownership, and explicit application
@@ -81,12 +88,13 @@ mount(root, () => (
 Components return Kerf `SafeHtml`. They do not own application state or attach transient listeners. Actions are stable `data-action` hooks; the application wires them once with `delegate()` or `delegateActions()` and retains the disposer.
 
 `ListItem.rootAttributes`, `ListHeader.rootAttributes`,
-`ListActionRow.rootAttributes`, and `AppTab.rootAttributes` carry typed
+`ListActionRow.rootAttributes`, `AppTab.rootAttributes`,
+`CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` carry typed
 application `data-*` metadata without
 teaching the package domain fields. `ListHeader.triggerAttributes` and
 `ListActionRow.trailingActionAttributes` additionally support native popover
 target and relationship attributes. Roles and component-owned action, selection,
-disclosure, naming, disabled, and icon semantics remain protected props; an
+disclosure, naming, disabled, icon, and catalog-structure semantics remain protected props; an
 isolated `role="menuitem"` is not an extension shortcut.
 The slots are also filtered at runtime, so structurally widened objects and
 JavaScript callers cannot bypass those protections with case-variant names.
@@ -119,7 +127,8 @@ as a `New` marker.
 | `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`       |
-| Pane, content, and navigation composition                           | —                                       | `@kerfjs/ui/layout.css`                |
+| `Pane`                                                              | `@kerfjs/ui/pane`                       | `@kerfjs/ui/pane.css`                  |
+| Content and navigation composition                                  | —                                       | `@kerfjs/ui/layout.css`                |
 | `ResizableRegion`                                                   | `@kerfjs/ui/resizable-region`           | `@kerfjs/ui/resizable-region.css`      |
 | `wireResizableRegions`                                              | `@kerfjs/ui/wire-resizable-regions`     | —                                      |
 | `AppTab`                                                            | `@kerfjs/ui/app-tab`                    | `@kerfjs/ui/app-tab.css`               |
@@ -127,6 +136,7 @@ as a `New` marker.
 | `wireTabBars`, `reorderTabs`                                        | `@kerfjs/ui/wire-tab-bars`              | —                                      |
 | `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`          |
 | `Select`                                                            | `@kerfjs/ui/select`                     | `@kerfjs/ui/select.css`                |
 | `SegmentedControl`                                                  | `@kerfjs/ui/segmented-control`          | `@kerfjs/ui/segmented-control.css`     |
 | `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret` | `@kerfjs/ui/token-search-field`         | `@kerfjs/ui/token-search-field.css`    |
@@ -174,6 +184,24 @@ the versioned format. Every visual entry also declares who owns its margin,
 border, and padding, so a generator can fit it into Kerf's alignment model
 without guessing from a screenshot or private CSS.
 
+Catalog demo authoring is deliberately separate from the entry inventory. Load
+[`catalog-authoring.json`](./ai/catalog-authoring.json) to discover the
+authoritative [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract),
+the exact API-signature context, public imports/helpers, and sanctioned metadata
+slot. 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
+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
+the same contract.
+
 Applications and downstream design systems should publish the same facts for
 their own components. Start from the reusable
 [`component-catalog-extension.schema.json`](./ai/component-catalog-extension.schema.json)
@@ -186,6 +214,89 @@ identity alongside each input when ids could collide. This makes a combined
 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),
+its shipped TypeScript types, and the checked
+[`component-catalog-extension-v2.json`](./docs/examples/component-catalog-extension-v2.json)
+example. Preserve each catalog's package and qualify every identity and
+cross-catalog reference as `package:id`; never merge entries by bare id.
+
+[`compile-time-contracts-v1.json`](./ai/compile-time-contracts-v1.json) is the
+matching declaration contract: stable `KUI-T###` ids identify the invalid prop,
+state, identity, accessibility, and protected-attribute combinations TypeScript
+rejects. The package gate compiles one positive/negative consumer fixture against
+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
+`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
+entries and this catalog by full key, reject duplicate full keys, search the
+consumer package first, and retain package identity across every reference.
+They must not infer missing semantics or geometry from rendered appearance.
+
+### Application UI profile
+
+Applications can check in `.kerf-ui-profile.json` so tools do not have to infer
+project-wide UI policy. Start from the shipped
+[`application-ui-profile.defaults.json`](./ai/application-ui-profile.defaults.json)
+and the checked
+[`application-ui-profile.json`](./docs/examples/application-ui-profile.json)
+workspace example. The versioned
+[`application-ui-profile.schema.json`](./ai/application-ui-profile.schema.json)
+and [`application-ui-profile.d.ts`](./ai/application-ui-profile.d.ts) cover
+catalog locations, concept preferences, allowed theme/density choices, semantic
+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
+packages generated with composition-only metadata omit `selection`;
+`@kerfjs/ui` continues to require its v1 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,
+then the workspace profile, then directory profiles from parent to child;
+`mergeApplicationUiProfiles()` applies later scalar/map values, replaces a
+catalog by package and an exception by id, and preserves source provenance.
+`loadApplicationUiProfile()` resolves catalogs and returns diagnostics with the
+originating file plus JSON path. Unknown/stale components, tokens, rules, and
+catalog locations are errors. Every layer is checked against its then-effective
+catalogs, including parent references and catalog paths later overridden by a
+child profile. Synchronous integrations can require the shipped
+`application-ui-profile-sync.cjs` projection and call
+`loadApplicationUiProfileSync()` with already-discovered layers. Consumers that define additional stable
+diagnostics pass their ids through the additive `knownRules` option; those ids
+are merged with catalog diagnostics before exception validation.
+
+### Static CSS and layout ownership analysis
+
+Run `kerf-ui-analyze --root . src` (or import
+`@kerfjs/ui/analyzer`) to evaluate cross-file integration facts against the
+composition catalogs and application profile. It catches provable private
+selector reach-through, unknown tokens, competing geometry owners, and nested
+scroll owners; it reports forced dimensions, repeated insets, off-scale literal
+spacing, 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).
+
+### Browser-backed integration evaluation
+
+Run `kerf-ui-evaluate --url <running-app>` (or import
+`@kerfjs/ui/evaluator`) after the static analyzer. Its Playwright-backed
+wide/intermediate/narrow/200%-zoom, light/dark, and reduced-motion matrix checks
+rendered overflow, clipping, reachability, focus/keyboard behavior, accessible
+names, contrast, hit targets, scrolling, alignment, and cataloged runtime
+geometry. The versioned report carries stable `KUI-B###` diagnostics, focused
+DOM/computed-style evidence, hashed screenshot artifacts, explicit timeout and
+retention policy, and a separate unscored human-visual rubric. See the
+[browser evaluator guide](./docs/ui-evaluator.md).
+
+### Unified repair-loop doctor
+
+Use `kerf-ui-doctor` for the supported application repair loop across profile/catalog validation, TypeScript, the Kerf UI ESLint preset, static layout analysis, and an optional explicitly authorized browser evaluation. It emits one portable versioned JSON report with deterministic exit codes, exact suppressions, monorepo package selection, changed/full modes, caching, and local-path redaction. See the [UI doctor guide](./docs/ui-doctor.md).
+
 For code generation, pair catalog selection guidance with the checked-in
 [`public-api-signatures-v1.md`](./ai/public-api-signatures-v1.md) declaration
 snapshot. It is generated from the emitted `@kerfjs/ui` declarations and the

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

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": 1,
+  "ids": [
+    "KUI-B001",
+    "KUI-B010",
+    "KUI-B011",
+    "KUI-B012",
+    "KUI-B020",
+    "KUI-B021",
+    "KUI-B022",
+    "KUI-B023",
+    "KUI-B030",
+    "KUI-B040",
+    "KUI-B050",
+    "KUI-B060",
+    "KUI-B070",
+    "KUI-B080",
+    "KUI-C101",
+    "KUI-C102",
+    "KUI-C103",
+    "KUI-C104",
+    "KUI-C105",
+    "KUI-C106",
+    "KUI-C107",
+    "KUI-C108",
+    "KUI-D001",
+    "KUI-D002",
+    "KUI-D003",
+    "KUI-D010",
+    "KUI-D011",
+    "KUI-D020",
+    "KUI-L001",
+    "KUI-L002",
+    "KUI-L003",
+    "KUI-L004",
+    "KUI-L005",
+    "KUI-L006",
+    "KUI-L007",
+    "KUI-L008",
+    "KUI-L009",
+    "KUI-L090",
+    "KUI-L101",
+    "KUI-L102",
+    "KUI-L201",
+    "KUI-L202",
+    "KUI-L203",
+    "KUI-L301",
+    "KUI-L401",
+    "KUI-L402",
+    "KUI-P001",
+    "KUI-P002",
+    "KUI-P003",
+    "KUI-P004",
+    "KUI-P005",
+    "KUI-P006",
+    "KUI-P007",
+    "KUI-P008",
+    "KUI-P009",
+    "KUI-P010",
+    "KUI-P011",
+    "KUI-P012",
+    "KUI-P013",
+    "KUI-P014",
+    "KUI-P015",
+    "KUI-P016",
+    "KUI-P017",
+    "KUI-P018",
+    "KUI-P019",
+    "KUI-P020",
+    "KUI-P021",
+    "KUI-P022",
+    "KUI-P023",
+    "KUI-P024",
+    "KUI-P025",
+    "KUI-P026",
+    "KUI-P027",
+    "KUI-P028",
+    "KUI-P029",
+    "KUI-P030",
+    "KUI-T001",
+    "KUI-T002",
+    "KUI-T003",
+    "KUI-T004",
+    "KUI-T005",
+    "KUI-T006",
+    "KUI-T007",
+    "KUI-T008",
+    "KUI-T009",
+    "KUI-T010",
+    "KUI-T011"
+  ]
+}