@kerfjs/ui 5.0.0-beta.61 → 5.0.0-beta.63

package/README.md

@@ -342,6 +342,10 @@ guidance, public hooks, and explicit geometry ownership; then concatenate its
 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.
+For a consumer UX demo, `@kerfjs/ui/catalog-projection` derives rows and
+relationships from that extension; `kerf-catalog-demo --write` emits a typed
+module and `--check` catches drift. See the [catalog guide](./docs/catalog.md)
+for repository base and source path configuration.
 
 Composition-aware consumers use
 [`component-composition-extension.schema.json`](./ai/component-composition-extension.schema.json),

package/ai/component-catalog-extension.schema.json

@@ -52,6 +52,14 @@
           "items": { "type": "string" },
           "uniqueItems": true
         },
+        "uses": {
+          "description": "Directly composed Kerf or consumer catalog entry ids.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "source": { "$ref": "#/$defs/repositoryPath" },
+        "demoSource": { "$ref": "#/$defs/repositoryPath" },
         "geometry": { "$ref": "#/$defs/geometry" },
         "documentation": { "type": "string", "minLength": 1 }
       },
@@ -74,6 +82,11 @@
     },
     "geometryOwner": {
       "enum": ["self", "parent", "child", "none", "conditional"]
+    },
+    "repositoryPath": {
+      "description": "A repository-relative POSIX path without traversal or empty segments.",
+      "type": "string",
+      "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$"
     }
   }
 }

package/ai/component-catalog.json

@@ -582,7 +582,8 @@
       "useWhen": [
         "An application column needs shared header, content, and optional footer organization with exactly one scrolling content owner.",
         "A pane boundary needs an opt-in separator on any combination of logical sides.",
-        "Pinned chrome needs a divider from the scrolling content only while content is scrolled beneath it (wireScrollDividers)."
+        "Pinned chrome needs a divider from the scrolling content only while content is scrolled beneath it (wireScrollDividers).",
+        "A lowered background must cover the scrolling work viewport and blank space after short content without a second scroll container (appearance: sunken)."
       ],
       "avoidWhen": [
         "Do not use Pane as a padded card or add a competing scroll owner around its content slot.",
@@ -602,7 +603,8 @@
         "which logical boundaries show separators",
         "which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges)",
         "responsive placement and visibility",
-        "whether the chrome dividers follow the scroll, always show, or never show (chromeDividers)"
+        "whether the chrome dividers follow the scroll, always show, or never show (chromeDividers)",
+        "default or sunken scrolling work surface (appearance)"
       ],
       "variants": [
         "content only",
@@ -667,7 +669,9 @@
         "--kui-edge-inset-inline-end",
         "--kui-edge-inset-inline-start",
         "--kui-pane-separator-color",
-        "--kui-pane-separator-width"
+        "--kui-pane-separator-width",
+        "--kui-pane-chrome-background",
+        "--kui-sunken-panel-background"
       ],
       "links": {
         "catalogRoute": "?component=pane",
@@ -1161,6 +1165,11 @@
           "import": "@kerfjs/ui/wire-workbench",
           "required": false,
           "stateAttributes": [
+            {
+              "name": "data-responsive-overlay-active",
+              "on": "kui-workbench__rail and kui-workbench__drawer",
+              "meaning": "Present while a panel's numeric responsiveOverlayAt threshold applies to the Workbench width; the same measurement drives overlay layout and collapsed-state transitions."
+            },
             {
               "name": "data-handle-inset",
               "on": "kui-workbench__rail",
@@ -1202,7 +1211,8 @@
         "kui-workbench__panel-content",
         "kui-workbench__handle",
         "kui-workbench__handle-icon",
-        "kui-workbench__restore"
+        "kui-workbench__restore",
+        "kui-workbench__backdrop"
       ],
       "publicTokens": [
         "--kui-workbench-rail-width",
@@ -1850,7 +1860,7 @@
       ],
       "avoidWhen": [
         "Do not omit headingLevel when the text is the page or section heading.",
-        "Do not use a size below xlarge as a normal-color subsection title: large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section."
+        "Large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use xlarge-fixed for a normal-color toolbar heading at the fixed font-l step; use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section."
       ],
       "alternatives": [
         {
@@ -1870,6 +1880,7 @@
       ],
       "variants": [
         "xlarge",
+        "xlarge-fixed (fixed font-l heading)",
         "large",
         "default",
         "small",
@@ -3097,7 +3108,7 @@
         "border": "self",
         "padding": "self",
         "notes": [
-          "Public resting background and border, hover border, and selected border tokens can be scoped to a row or its containing list without changing the default tones."
+          "Public resting, hover, and selected text, fill, and border tokens can be scoped to a row or its containing list without changing the default tones."
         ]
       },
       "delivery": {
@@ -3601,7 +3612,8 @@
         "overflow dividers on each side with tabs scrolled out of view (wired by wireScrollDividers)"
       ],
       "accessibility": [
-        "Keep exactly one selected tab at tabindex 0 and preserve the wiring keyboard model."
+        "Keep exactly one selected tab at tabindex 0 and preserve the wiring keyboard model.",
+        "Call wireTabBars for keyboard focus and selection, including the pinned leading tab's WebKit RTL scroll correction."
       ],
       "geometry": {
         "margin": "none",
@@ -4152,6 +4164,7 @@
         "form, toolbar-borderless, or navigation presentation",
         "default or compact size",
         "label or icon-only selected presentation",
+        "optional caret-free round icon-only trigger",
         "select- or group-owned focus ring",
         "label maximum width and truncation",
         "fit-content, max-content, or fill trigger width",

package/ai/component-composition.json

@@ -589,6 +589,11 @@
           "id": "whether the chrome dividers follow the scroll, always show, or never show (chromeDividers)",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "default or sunken scrolling work surface (appearance)",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -645,7 +650,9 @@
           "--kui-edge-inset-inline-end",
           "--kui-edge-inset-inline-start",
           "--kui-pane-separator-color",
-          "--kui-pane-separator-width"
+          "--kui-pane-separator-width",
+          "--kui-pane-chrome-background",
+          "--kui-sunken-panel-background"
         ]
       },
       "diagnostics": [],
@@ -1084,6 +1091,12 @@
         "helpers": ["wireWorkbench", "wireScrollDividers"],
         "obligations": [],
         "stateAttributes": [
+          {
+            "name": "data-responsive-overlay-active",
+            "on": "kui-workbench__rail and kui-workbench__drawer",
+            "helper": "wireWorkbench",
+            "meaning": "Present while a panel's numeric responsiveOverlayAt threshold applies to the Workbench width; the same measurement drives overlay layout and collapsed-state transitions."
+          },
           {
             "name": "data-handle-inset",
             "on": "kui-workbench__rail",
@@ -1145,7 +1158,8 @@
           "kui-workbench__panel-content",
           "kui-workbench__handle",
           "kui-workbench__handle-icon",
-          "kui-workbench__restore"
+          "kui-workbench__restore",
+          "kui-workbench__backdrop"
         ],
         "publicTokens": [
           "--kui-workbench-rail-width",
@@ -2531,7 +2545,7 @@
           "border": "self",
           "padding": "self",
           "notes": [
-            "Public resting background and border, hover border, and selected border tokens can be scoped to a row or its containing list without changing the default tones."
+            "Public resting, hover, and selected text, fill, and border tokens can be scoped to a row or its containing list without changing the default tones."
           ]
         }
       },

package/ai/components/list-item.md

@@ -69,7 +69,7 @@ No wiring helper.
 
 Margin: self · border: self · padding: self (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- Public resting background and border, hover border, and selected border tokens can be scoped to a row or its containing list without changing the default tones.
+- Public resting, hover, and selected text, fill, and border tokens can be scoped to a row or its containing list without changing the default tones.
 
 ## Accessibility
 

package/ai/components/pane.md

@@ -13,6 +13,7 @@ Organize a sidebar, main area, inspector, or dialog column into fixed vertical h
 - An application column needs shared header, content, and optional footer organization with exactly one scrolling content owner.
 - A pane boundary needs an opt-in separator on any combination of logical sides.
 - Pinned chrome needs a divider from the scrolling content only while content is scrolled beneath it (wireScrollDividers).
+- A lowered background must cover the scrolling work viewport and blank space after short content without a second scroll container (appearance: sunken).
 
 **Not when:**
 
@@ -60,7 +61,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 ## State and wiring
 
-**The app owns:** root and content semantics; accessible labels; header, content, and footer children; which logical boundaries show separators; which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges); responsive placement and visibility; whether the chrome dividers follow the scroll, always show, or never show (chromeDividers).
+**The app owns:** root and content semantics; accessible labels; header, content, and footer children; which logical boundaries show separators; which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges); responsive placement and visibility; whether the chrome dividers follow the scroll, always show, or never show (chromeDividers); default or sunken scrolling work surface (appearance).
 
 **Wiring:** `wireScrollDividers` is optional.
 
@@ -89,7 +90,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-pane`, `kui-pane__content`, `kui-pane__footer`, `kui-pane__header`, `kui-pane__toolbar` on an element you write; render `Pane` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-edge-inset-block-end`, `--kui-edge-inset-block-start`, `--kui-edge-inset-inline-end`, `--kui-edge-inset-inline-start`, `--kui-pane-separator-color`, `--kui-pane-separator-width`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-edge-inset-block-end`, `--kui-edge-inset-block-start`, `--kui-edge-inset-inline-end`, `--kui-edge-inset-inline-start`, `--kui-pane-separator-color`, `--kui-pane-separator-width`, `--kui-pane-chrome-background`, `--kui-sunken-panel-background`. Set a token only where its public contract allows; prefer a prop.
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 

package/ai/components/select.md

@@ -46,6 +46,7 @@ Exact prop names and types: [`@kerfjs/ui/select`](../public-api-signatures-v1.md
 - form, toolbar-borderless, or navigation presentation
 - default or compact size
 - label or icon-only selected presentation
+- optional caret-free round icon-only trigger
 - select- or group-owned focus ring
 - label maximum width and truncation
 - fit-content, max-content, or fill trigger width

package/ai/components/toolbar-text.md

@@ -13,7 +13,7 @@ Extra-large through extra-small toolbar identity text.
 **Not when:**
 
 - Do not omit headingLevel when the text is the page or section heading.
-- Do not use a size below xlarge as a normal-color subsection title: large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section.
+- Large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use xlarge-fixed for a normal-color toolbar heading at the fixed font-l step; use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section.
 
 **Alternatives:**
 
@@ -33,6 +33,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures
 **Variants (configure, do not restyle):**
 
 - xlarge
+- xlarge-fixed (fixed font-l heading)
 - large
 - default
 - small

package/ai/components/workbench.md

@@ -76,6 +76,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 **Wiring-owned state attributes** — never render, remove, or branch on these as app state:
 
+- `data-responsive-overlay-active` on `kui-workbench__rail and kui-workbench__drawer` (`wireWorkbench`): Present while a panel's numeric responsiveOverlayAt threshold applies to the Workbench width; the same measurement drives overlay layout and collapsed-state transitions.
 - `data-handle-inset` on `kui-workbench__rail` (`wireWorkbench`): Written by the shared resize wiring when the work-area minimum or a parent clamp holds a rail's maximum near its size. It carries no Workbench styling; the Workbench handle stays at the rail's inner edge.
 - `data-resizing` on `kui-workbench__rail` (`wireWorkbench`): Present on a resizable rail or the drawer while a pointer drag resizes it.
 - `data-scroll-overflow` on `kui-pane__content of each panel and work-area Pane` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
@@ -99,9 +100,9 @@ Margin: none · border: self · padding: child (layout role: structure). `self`
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public class hooks (select for layout placement only, never to change the component's look): `kui-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore`, `kui-workbench__backdrop`.
 
-Never put `kui-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore` on an element you write; render `Workbench` instead (`KUI-L103`).
+Never put `kui-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore`, `kui-workbench__backdrop` on an element you write; render `Workbench` instead (`KUI-L103`).
 
 Public tokens it reads: `--kui-workbench-rail-width`, `--kui-workbench-drawer-height`, `--kui-workbench-popup-z`, `--kui-workbench-overlay-z`, `--kui-workbench-overlay-max-width`, `--kui-workbench-overlay-max-height`, `--kui-workbench-restore-inset`, `--kui-workbench-restore-z`, `--kui-workbench-overlay-dismiss-margin`. Set a token only where its public contract allows; prefer a prop.