@kerfjs/ui 5.0.0-beta.52 → 5.0.0-beta.54

package/README.md

@@ -203,6 +203,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `TabScaffold`                                                       | `@kerfjs/ui/tab-scaffold`               | `@kerfjs/ui/tab-scaffold.css`          |
 | `wireTabScaffold`                                                   | `@kerfjs/ui/wire-tab-scaffold`          | —                                      |
 | `Workbench`                                                         | `@kerfjs/ui/workbench`                  | `@kerfjs/ui/workbench.css`             |
+| `wireWorkbench`                                                     | `@kerfjs/ui/wire-workbench`             | —                                      |
 | `CollapsiblePanel`, `CollapsiblePanelToggle`                        | `@kerfjs/ui/collapsible-panel`          | `@kerfjs/ui/collapsible-panel.css`     |
 | `wireSidebar`                                                       | `@kerfjs/ui/wire-sidebar`               | —                                      |
 | Content and navigation composition                                  | —                                       | `@kerfjs/ui/layout.css`                |

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

@@ -46,6 +46,7 @@
     "KUI-L015",
     "KUI-L016",
     "KUI-L017",
+    "KUI-L018",
     "KUI-L090",
     "KUI-L101",
     "KUI-L102",

package/ai/component-catalog-v2.d.ts

@@ -49,6 +49,9 @@ export interface CatalogCompositionEntryV2 {
   publicExports?: Array<{ name: string; subpath: string }>;
   sourceLinks?: string[];
   source: string;
+  /** For a wrapper component: the cataloged roots it renders (any one of
+   *  them, or nothing). Composition checks treat its elements as each root. */
+  rendersAs?: CatalogQualifiedKey[];
   parents: { mode: 'any' | 'root' | 'listed'; entries: CatalogQualifiedKey[] };
   contexts: string[];
   zones: Array<{

package/ai/component-catalog-v2.json

@@ -305,6 +305,7 @@
           "--kui-color-danger-on-quiet",
           "--kui-color-danger-on-normal",
           "--kui-color-danger-on-loud",
+          "--kui-color-danger-on-fill",
           "--kui-color-border",
           "--kui-color-border-quiet",
           "--kui-color-accent",
@@ -328,6 +329,64 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:document-baseline",
+      "package": "@kerfjs/ui",
+      "id": "document-baseline",
+      "name": "Document baseline",
+      "kind": "composition",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "the one direct mount container",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "application overrides loaded after the baseline",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["foundation"],
+        "geometry": {
+          "margin": "none",
+          "border": "none",
+          "padding": "none",
+          "notes": [
+            "The body margin is removed; .kui-app-root only sets height: 100% and owns no inset."
+          ]
+        }
+      },
+      "accessibility": {
+        "obligations": [
+          "Links keep the semantic link color at zero specificity so application focus and link styles still apply."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-app-root",
+        "publicClasses": ["kui-app-root"],
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:layout",
       "package": "@kerfjs/ui",
@@ -886,9 +945,22 @@
       ],
       "wiring": {
         "required": false,
-        "helpers": [],
+        "helpers": ["wireWorkbench"],
         "obligations": [],
-        "stateAttributes": []
+        "stateAttributes": [
+          {
+            "name": "data-handle-inset",
+            "on": "kui-workbench__rail",
+            "helper": "wireWorkbench",
+            "meaning": "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."
+          },
+          {
+            "name": "data-resizing",
+            "on": "kui-workbench__rail",
+            "helper": "wireWorkbench",
+            "meaning": "Present on a resizable rail or the drawer while a pointer drag resizes it."
+          }
+        ]
       },
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
@@ -905,7 +977,10 @@
       "accessibility": {
         "obligations": [
           "Give the Workbench and each meaningful rail or drawer an accessible label.",
-          "Keep collapse controls outside the disappearing region and move focus when a controlled rerender replaces a collapse control with its restore control."
+          "Keep collapse controls outside the disappearing region and move focus when a controlled rerender replaces a collapse control with its restore control.",
+          "A resizable panel's separator is a focusable role=\"separator\" with its size in aria-valuenow and limits in aria-valuemin/aria-valuemax; arrow keys resize by 16px, Shift+arrow by 64px, and Home/End jump to the limits. It leaves the tab order while its panel is collapsed or not inline.",
+          "Given a panel's collapsed signal, wireWorkbench closes an open overlay panel on Escape or an outside press and, however the panel closed, returns focus stranded inside it to the control that opened it, else to its restore control.",
+          "An overlay panel can cover the toolbar toggle that opened it (a narrow right rail covers an editor toolbar's trailing toggle), so give every panel that may overlay its own close control in its header: a Pane header Toolbar with a single ToolbarControlGroup around the collapsiblePanelToggleIcon(side, false) button."
         ]
       },
       "cssValueProps": [],
@@ -920,6 +995,8 @@
           "kui-workbench__center",
           "kui-workbench__main",
           "kui-workbench__panel-content",
+          "kui-workbench__handle",
+          "kui-workbench__handle-icon",
           "kui-workbench__restore"
         ],
         "publicTokens": [
@@ -929,8 +1006,8 @@
           "--kui-workbench-overlay-z",
           "--kui-workbench-overlay-max-width",
           "--kui-workbench-overlay-max-height",
-          "--kui-workbench-restore-z",
-          "--kui-workbench-restore-inset"
+          "--kui-workbench-restore-inset",
+          "--kui-workbench-restore-z"
         ]
       },
       "diagnostics": [],
@@ -1034,8 +1111,8 @@
           "--kui-collapsible-panel-height",
           "--kui-collapsible-panel-popup-z",
           "--kui-collapsible-panel-overlay-z",
-          "--kui-collapsible-panel-restore-z",
           "--kui-collapsible-panel-restore-inset",
+          "--kui-collapsible-panel-restore-z",
           "--kui-collapsible-panel-backdrop-z"
         ]
       },
@@ -3091,10 +3168,11 @@
           "--kui-color-pop-on-fill",
           "--kui-color-danger-border-quiet",
           "--kui-color-danger-fill-quiet",
-          "--kui-color-danger-on-quiet",
+          "--kui-color-danger-on-fill",
           "--kui-color-neutral-border-normal",
           "--kui-color-neutral-fill-quiet",
           "--kui-color-neutral-on-normal",
+          "--kui-color-neutral-on-quiet",
           "--kui-color-success-border-normal",
           "--kui-color-success-fill-quiet",
           "--kui-color-success-on-fill",

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

@@ -137,10 +137,11 @@
         "kind": { "enum": ["component", "composition", "recipe"] },
         "purpose": { "type": "string", "minLength": 1 },
         "publicExports": {
+          "description": "Each export's name and the package.json#exports subpath that serves it. An entry from a private application omits subpath: the application is bundled, never imported by package name, so the name resolves through the entry's source file.",
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["name", "subpath"],
+            "required": ["name"],
             "properties": {
               "name": { "type": "string", "minLength": 1 },
               "subpath": { "type": "string", "pattern": "^\\." }
@@ -151,6 +152,13 @@
         },
         "sourceLinks": { "$ref": "#/$defs/stringList" },
         "source": { "type": "string", "minLength": 1 },
+        "rendersAs": {
+          "description": "For a wrapper component: the cataloged roots it renders (package-qualified keys), any one of them or nothing. Composition checks treat an element of this entry as each declared root: a zone accepts it only if it accepts every root, and each root's parent contract applies to where it is placed.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[^:]+:[^:]+$" },
+          "uniqueItems": true
+        },
         "parents": {
           "type": "object",
           "required": ["mode", "entries"],

package/ai/component-catalog.json

@@ -330,6 +330,7 @@
         "--kui-color-danger-on-quiet",
         "--kui-color-danger-on-normal",
         "--kui-color-danger-on-loud",
+        "--kui-color-danger-on-fill",
         "--kui-color-border",
         "--kui-color-border-quiet",
         "--kui-color-accent",
@@ -352,6 +353,67 @@
         "recipe": "docs/component-selection.md#foundation-tokens"
       }
     },
+    {
+      "id": "document-baseline",
+      "name": "Document baseline",
+      "category": "Foundation",
+      "kind": "composition",
+      "source": "kerf",
+      "description": "Opt-in document-level defaults: border-box sizing, body margin/font/surface, link color, and the html → body → .kui-app-root full-height chain.",
+      "uses": [],
+      "purpose": "Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.",
+      "publicExports": [],
+      "useWhen": [
+        "An application wants Kerf UI to own document-level box sizing, body typography, surface, and link color.",
+        "A full-height shell (Workbench, SplitView, NavStack, or TabScaffold) mounts into one direct container: put .kui-app-root on that container."
+      ],
+      "avoidWhen": [
+        "Do not put .kui-app-root on several sibling containers; each requests the full available document height.",
+        "Do not import it where the host page already owns document-level defaults it would override."
+      ],
+      "alternatives": [
+        {
+          "id": "foundation",
+          "relationship": "composes-with",
+          "when": "Import the foundation tokens the baseline reads; the baseline itself adds only global document selectors."
+        }
+      ],
+      "appOwns": [
+        "the one direct mount container",
+        "application overrides loaded after the baseline"
+      ],
+      "variants": [
+        "document-flow page (no .kui-app-root)",
+        "full-height application root"
+      ],
+      "accessibility": [
+        "Links keep the semantic link color at zero specificity so application focus and link styles still apply."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none",
+        "notes": [
+          "The body margin is removed; .kui-app-root only sets height: 100% and owns no inset."
+        ]
+      },
+      "delivery": {
+        "manualCssImport": "@kerfjs/ui/document.css",
+        "sideEffects": [
+          "css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-app-root"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=document-baseline",
+        "documentation": "docs/document-baseline.md",
+        "recipe": "docs/document-baseline.md"
+      }
+    },
     {
       "id": "layout",
       "name": "Application layout",
@@ -850,20 +912,24 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "A desktop-class multi-panel workspace with independently collapsible left and right rails and a bottom drawer around one central work area.",
+      "description": "A desktop-class multi-panel workspace with independently collapsible, optionally drag-resizable left and right rails and a bottom drawer around one central work area.",
       "uses": [],
       "purpose": "Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.",
       "publicExports": [
         "Workbench",
         "WorkbenchPanel",
-        "WorkbenchProps"
+        "WorkbenchPanelResizable",
+        "WorkbenchProps",
+        "WorkbenchResponsiveOverlayAt"
       ],
       "useWhen": [
-        "A desktop-class tool needs a central work area plus independently collapsible navigator, inspector, or console regions."
+        "A desktop-class tool needs a central work area plus independently collapsible navigator, inspector, or console regions.",
+        "A desktop-class tool should let people size its peripheral panels by dragging or with the keyboard; opt each panel in with resizable and wire it with wireWorkbench."
       ],
       "avoidWhen": [
         "Do not shrink the full multi-panel shell onto compact devices; present peripheral content through NavStack or overlay drawers instead.",
-        "Do not use Workbench for one standalone collapsible rail or drawer; use CollapsiblePanel."
+        "Do not use Workbench for one standalone collapsible rail or drawer; use CollapsiblePanel.",
+        "Do not offer resizing where rails present as compact overlay drawers or are replaced; set a panel's responsiveOverlayAt, or pass deviceClass so wireWorkbench suspends resizing on compact classes."
       ],
       "alternatives": [
         {
@@ -886,6 +952,10 @@
         "bottom drawer",
         "all panels",
         "independently collapsed panels",
+        "opt-in drag and keyboard resizable panels with min/max limits",
+        "resizable rails that leave the work area a minimum width and shrink in proportion when the Workbench narrows",
+        "rails or a drawer that present as overlays below a narrow or compact Workbench container breakpoint",
+        "transient overlay panels wired with wireWorkbench: collapsed on entering the breakpoint, closed by Escape or an outside press",
         "hidden separator",
         "slide, fade-slide, or instant content",
         "clipped, scrolling, or popup-visible content",
@@ -895,7 +965,10 @@
       ],
       "accessibility": [
         "Give the Workbench and each meaningful rail or drawer an accessible label.",
-        "Keep collapse controls outside the disappearing region and move focus when a controlled rerender replaces a collapse control with its restore control."
+        "Keep collapse controls outside the disappearing region and move focus when a controlled rerender replaces a collapse control with its restore control.",
+        "A resizable panel's separator is a focusable role=\"separator\" with its size in aria-valuenow and limits in aria-valuemin/aria-valuemax; arrow keys resize by 16px, Shift+arrow by 64px, and Home/End jump to the limits. It leaves the tab order while its panel is collapsed or not inline.",
+        "Given a panel's collapsed signal, wireWorkbench closes an open overlay panel on Escape or an outside press and, however the panel closed, returns focus stranded inside it to the control that opened it, else to its restore control.",
+        "An overlay panel can cover the toolbar toggle that opened it (a narrow right rail covers an editor toolbar's trailing toggle), so give every panel that may overlay its own close control in its header: a Pane header Toolbar with a single ToolbarControlGroup around the collapsiblePanelToggleIcon(side, false) button."
       ],
       "geometry": {
         "margin": "none",
@@ -912,7 +985,25 @@
           "manual-css"
         ]
       },
-      "wiring": [],
+      "wiring": [
+        {
+          "export": "wireWorkbench",
+          "import": "@kerfjs/ui/wire-workbench",
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-handle-inset",
+              "on": "kui-workbench__rail",
+              "meaning": "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."
+            },
+            {
+              "name": "data-resizing",
+              "on": "kui-workbench__rail",
+              "meaning": "Present on a resizable rail or the drawer while a pointer drag resizes it."
+            }
+          ]
+        }
+      ],
       "publicClasses": [
         "kui-workbench",
         "kui-workbench__rail",
@@ -922,6 +1013,8 @@
         "kui-workbench__center",
         "kui-workbench__main",
         "kui-workbench__panel-content",
+        "kui-workbench__handle",
+        "kui-workbench__handle-icon",
         "kui-workbench__restore"
       ],
       "publicTokens": [
@@ -931,8 +1024,8 @@
         "--kui-workbench-overlay-z",
         "--kui-workbench-overlay-max-width",
         "--kui-workbench-overlay-max-height",
-        "--kui-workbench-restore-z",
-        "--kui-workbench-restore-inset"
+        "--kui-workbench-restore-inset",
+        "--kui-workbench-restore-z"
       ],
       "links": {
         "catalogRoute": "?component=workbench",
@@ -1056,8 +1149,8 @@
         "--kui-collapsible-panel-height",
         "--kui-collapsible-panel-popup-z",
         "--kui-collapsible-panel-overlay-z",
-        "--kui-collapsible-panel-restore-z",
         "--kui-collapsible-panel-restore-inset",
+        "--kui-collapsible-panel-restore-z",
         "--kui-collapsible-panel-backdrop-z"
       ],
       "links": {
@@ -3491,7 +3584,10 @@
           "canonicalShorthands": [],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["color: uiColor(\"success-on-quiet\")", "color: foregroundColorVar(\"--app-choice-color\")"]
+          "examples": [
+            "color: uiColor(\"success-on-quiet\")",
+            "color: foregroundColorVar(\"--app-choice-color\")"
+          ]
         }
       ],
       "useWhen": [
@@ -3741,10 +3837,11 @@
         "--kui-color-pop-on-fill",
         "--kui-color-danger-border-quiet",
         "--kui-color-danger-fill-quiet",
-        "--kui-color-danger-on-quiet",
+        "--kui-color-danger-on-fill",
         "--kui-color-neutral-border-normal",
         "--kui-color-neutral-fill-quiet",
         "--kui-color-neutral-on-normal",
+        "--kui-color-neutral-on-quiet",
         "--kui-color-success-border-normal",
         "--kui-color-success-fill-quiet",
         "--kui-color-success-on-fill",