@kerfjs/ui 5.0.0-beta.22 → 5.0.0-beta.24

package/README.md

@@ -122,6 +122,7 @@ as a `New` marker.
 | `ToolbarControlGroup`                                               | `@kerfjs/ui/toolbar-control-group`      | `@kerfjs/ui/toolbar-control-group.css` |
 | `FloatingToolbar`                                                   | `@kerfjs/ui/floating-toolbar`           | `@kerfjs/ui/floating-toolbar.css`      |
 | `ToolbarText`                                                       | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`          |
+| `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                  |
 | `ListActionRow`                                                     | `@kerfjs/ui/list-action-row`            | `@kerfjs/ui/list-action-row.css`       |
 | `ListItem`                                                          | `@kerfjs/ui/list-item`                  | `@kerfjs/ui/list-item.css`             |
 | `ListHeader`                                                        | `@kerfjs/ui/list-header`                | `@kerfjs/ui/list-header.css`           |
@@ -146,6 +147,13 @@ as a `New` marker.
 | `PanelHeader`                                                       | `@kerfjs/ui/panel-header`               | `@kerfjs/ui/panel-header.css`          |
 | `ValueTable`, `ValueTableRow`                                       | `@kerfjs/ui/value-table`                | `@kerfjs/ui/value-table.css`           |
 
+Opt-in application layouts keep JavaScript and CSS explicit. For the
+desktop-class multi-panel shell, import `Workbench` from
+`@kerfjs/ui/workbench` and load `@kerfjs/ui/workbench.css`; its supported
+classes and size tokens are cataloged under the `workbench` entry. See
+[`docs/workbench.md`](./docs/workbench.md) for panel ownership and responsive
+replacement guidance.
+
 `PanelHeader` is a plain `Toolbar` used as a panel, dialog, or page heading: an
 optional icon control group (given a brand fill with a matching border), the
 title as extra-large `ToolbarText`, the app's trailing action controls, and an
@@ -331,9 +339,10 @@ that convenience import, also import `@kerfjs/ui/styles.css`, which deliberately
 contains the complete layer. Non-browser/SSR tools resolve the pure `import`
 condition automatically; `@kerfjs/ui/unstyled` is the explicit CSS-free root
 entry for a browser build with a custom styling pipeline. The exported
-`foundation.css` and component CSS paths remain available for fully manual
-delivery. Load application overrides after package styles, or scope `--kui-*`
-variables directly on a component instance.
+`@kerfjs/ui/foundation.css` and component CSS paths remain available for fully
+manual delivery. Its complete supported `--kui-*` token surface is cataloged
+under the `foundation` entry. Load application overrides after package styles,
+or scope variables directly on a component instance.
 
 ## Pane and content geometry
 

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

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

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

@@ -93,21 +93,14 @@
     ]
   },
   "@kerfjs/ui:list": {
-    "_source": "docs/component-selection.md#correct-composition-and-duplicated-markup-trap",
-    "contexts": ["navigation-list"],
+    "_source": "docs/component-selection.md#problem-to-component-matrix",
+    "contexts": ["application-ui", "navigation-list", "vertical-layout"],
     "children": {
-      "mode": "listed",
-      "concepts": ["list-header", "list-item", "list-action-row"],
+      "mode": "any",
+      "concepts": [],
       "requiredConcepts": []
     },
-    "zones": [
-      {
-        "id": "rows",
-        "accepts": ["list-header", "list-item", "list-action-row"],
-        "cardinality": { "min": 1, "max": "unbounded" },
-        "exclusiveWith": []
-      }
-    ]
+    "zones": []
   },
   "@kerfjs/ui:list-header": {
     "_source": "docs/accessibility.md#shared-rules",

package/ai/component-catalog-v2.json

@@ -141,6 +141,157 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:foundation",
+      "package": "@kerfjs/ui",
+      "id": "foundation",
+      "name": "Foundation tokens",
+      "kind": "composition",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "application theme overrides",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "responsive policy at the cataloged device-class breakpoints",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["foundation"],
+        "geometry": { "margin": "none", "border": "none", "padding": "none" }
+      },
+      "accessibility": {
+        "obligations": [
+          "Preserve semantic contrast relationships and the visible focus ring when overriding foundation colors."
+        ]
+      },
+      "boundaries": {
+        "rootClass": null,
+        "publicClasses": [],
+        "publicTokens": [
+          "--kui-font-sans",
+          "--kui-font-mono",
+          "--kui-font-2xs",
+          "--kui-font-xs",
+          "--kui-font-s",
+          "--kui-font-m",
+          "--kui-font-l",
+          "--kui-font-2xl",
+          "--kui-font-weight-semibold",
+          "--kui-space-none",
+          "--kui-space-2xs",
+          "--kui-space-xs",
+          "--kui-space-s",
+          "--kui-space-m",
+          "--kui-space-l",
+          "--kui-space-xl",
+          "--kui-bp-mobile",
+          "--kui-bp-tablet",
+          "--kui-bp-desktop",
+          "--kui-bp-xl-desktop",
+          "--kui-layout-inline-margin",
+          "--kui-layout-item-border-width",
+          "--kui-layout-item-padding",
+          "--kui-layout-item-gap",
+          "--kui-layout-content-gap",
+          "--kui-layout-control-gap",
+          "--kui-layout-metadata-gap",
+          "--kui-layout-rounded-radius",
+          "--kui-layout-pill-radius",
+          "--kui-toolbar-group-inner-size",
+          "--kui-toolbar-group-size",
+          "--kui-toolbar-gap",
+          "--kui-radius-s",
+          "--kui-radius-m",
+          "--kui-radius-l",
+          "--kui-radius-circle",
+          "--kui-radius-pill",
+          "--kui-disclosure-icon-scale",
+          "--kui-color-surface",
+          "--kui-color-surface-raised",
+          "--kui-color-surface-lowered",
+          "--kui-color-text",
+          "--kui-color-text-quiet",
+          "--kui-color-text-link",
+          "--kui-color-neutral-fill-quiet",
+          "--kui-color-neutral-fill-normal",
+          "--kui-color-neutral-fill-loud",
+          "--kui-color-neutral-border-quiet",
+          "--kui-color-neutral-border-normal",
+          "--kui-color-neutral-border-loud",
+          "--kui-color-neutral-on-quiet",
+          "--kui-color-neutral-on-normal",
+          "--kui-color-neutral-on-loud",
+          "--kui-color-brand-fill-loud",
+          "--kui-color-brand-fill-quiet",
+          "--kui-color-brand-fill-normal",
+          "--kui-color-brand-border-quiet",
+          "--kui-color-brand-border-normal",
+          "--kui-color-brand-border-loud",
+          "--kui-color-brand-on-quiet",
+          "--kui-color-brand-on-normal",
+          "--kui-color-brand-on-loud",
+          "--kui-color-brand-on-fill",
+          "--kui-color-success-fill-loud",
+          "--kui-color-success-fill-quiet",
+          "--kui-color-success-fill-normal",
+          "--kui-color-success-border-quiet",
+          "--kui-color-success-border-normal",
+          "--kui-color-success-border-loud",
+          "--kui-color-success-on-quiet",
+          "--kui-color-success-on-normal",
+          "--kui-color-success-on-loud",
+          "--kui-color-success-on-fill",
+          "--kui-color-warning-fill-loud",
+          "--kui-color-warning-fill-quiet",
+          "--kui-color-warning-fill-normal",
+          "--kui-color-warning-border-quiet",
+          "--kui-color-warning-border-normal",
+          "--kui-color-warning-border-loud",
+          "--kui-color-warning-on-quiet",
+          "--kui-color-warning-on-normal",
+          "--kui-color-warning-on-loud",
+          "--kui-color-warning-on-fill",
+          "--kui-color-danger-fill-loud",
+          "--kui-color-danger-fill-quiet",
+          "--kui-color-danger-fill-normal",
+          "--kui-color-danger-border-quiet",
+          "--kui-color-danger-border-normal",
+          "--kui-color-danger-border-loud",
+          "--kui-color-danger-on-quiet",
+          "--kui-color-danger-on-normal",
+          "--kui-color-danger-on-loud",
+          "--kui-color-border",
+          "--kui-color-border-quiet",
+          "--kui-color-accent",
+          "--kui-color-accent-text",
+          "--kui-color-success",
+          "--kui-color-success-text",
+          "--kui-color-warning",
+          "--kui-color-warning-text",
+          "--kui-color-danger",
+          "--kui-color-danger-text",
+          "--kui-focus-ring",
+          "--kui-shadow-s",
+          "--kui-shadow-l"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:layout",
       "package": "@kerfjs/ui",
@@ -282,6 +433,78 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:workbench",
+      "package": "@kerfjs/ui",
+      "id": "workbench",
+      "name": "Workbench",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "panel presence and content",
+          "owner": "application",
+          "required": false
+        },
+        { "id": "collapsed state", "owner": "application", "required": false },
+        { "id": "panel sizes", "owner": "application", "required": false },
+        {
+          "id": "responsive replacement below desktop",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "collapse controls and focus policy",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "geometry": {
+          "margin": "none",
+          "border": "self",
+          "padding": "child",
+          "notes": [
+            "Workbench owns the rail and drawer separators; each region's content owns its internal padding and scroll behavior."
+          ]
+        }
+      },
+      "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."
+        ]
+      },
+      "boundaries": {
+        "rootClass": "kui-workbench",
+        "publicClasses": [
+          "kui-workbench",
+          "kui-workbench__rail",
+          "kui-workbench__rail--left",
+          "kui-workbench__rail--right",
+          "kui-workbench__center",
+          "kui-workbench__main",
+          "kui-workbench__drawer",
+          "kui-workbench__panel-content"
+        ],
+        "publicTokens": [
+          "--kui-workbench-rail-width",
+          "--kui-workbench-drawer-height"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:sunken-panel",
       "package": "@kerfjs/ui",
@@ -299,6 +522,7 @@
           "owner": "application",
           "required": false
         },
+        { "id": "corner shape", "owner": "application", "required": false },
         { "id": "scroll ownership", "owner": "application", "required": false },
         {
           "id": "child ordering and content",
@@ -397,7 +621,7 @@
           "border": "conditional",
           "padding": "self",
           "notes": [
-            "Padding belongs to the toolbar; the optional divider variant also owns its border."
+            "Padding belongs to the toolbar; dividerSides selects any canonical combination of its physical top, right, bottom, and left edges."
           ]
         }
       },
@@ -414,7 +638,11 @@
           "kui-toolbar__leading",
           "kui-toolbar__trailing"
         ],
-        "publicTokens": ["--kui-color-border", "--kui-font-sans"]
+        "publicTokens": [
+          "--kui-color-border",
+          "--kui-font-sans",
+          "--kui-toolbar-divider-color"
+        ]
       },
       "diagnostics": [
         {
@@ -765,33 +993,26 @@
       "key": "@kerfjs/ui:list",
       "package": "@kerfjs/ui",
       "id": "list",
-      "name": "List composition",
-      "kind": "composition",
+      "name": "List",
+      "kind": "component",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
-      "contexts": ["navigation-list"],
-      "zones": [
-        {
-          "id": "rows",
-          "accepts": ["list-header", "list-item", "list-action-row"],
-          "cardinality": { "min": 1, "max": "unbounded" },
-          "exclusiveWith": []
-        }
-      ],
-      "children": {
-        "mode": "listed",
-        "concepts": ["list-header", "list-item", "list-action-row"],
-        "requiredConcepts": []
-      },
+      "contexts": ["application-ui", "navigation-list", "vertical-layout"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
       "state": [
         {
-          "id": "information architecture",
+          "id": "child semantics and content",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "the bounded height needed for scrolling",
           "owner": "application",
           "required": false
         },
-        { "id": "routing", "owner": "application", "required": false },
         {
-          "id": "responsive shell behavior",
+          "id": "gap, flex, and divider choices",
           "owner": "application",
           "required": false
         }
@@ -800,28 +1021,35 @@
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
         "roles": ["navigation"],
-        "geometry": { "margin": "child", "border": "child", "padding": "child" }
+        "geometry": {
+          "margin": "none",
+          "border": "conditional",
+          "padding": "none",
+          "notes": [
+            "List adds no margin or padding; dividerSides draws only the selected physical edges without changing box geometry."
+          ]
+        }
       },
       "accessibility": {
         "obligations": [
-          "Use native links for link navigation, retain ListItem button semantics for actions, and keep standalone header and toolbar actions at least 44px square.",
-          "A ListHeader disclosure controls real content, keeps a stable accessible name and aria-expanded state, and uses the production DisclosureArrow visual."
+          "List adds layout only and no list role; children retain responsibility for their native or ARIA semantics.",
+          "Give a scrollable List a bounded block size and keep keyboard focus visible as its contents scroll."
         ]
       },
       "boundaries": {
-        "rootClass": "kui-content",
-        "publicClasses": ["kui-content", "kui-content-item"],
+        "rootClass": "kui-list",
+        "publicClasses": ["kui-list"],
         "publicTokens": [
-          "--kui-layout-content-gap",
-          "--kui-layout-inline-margin",
-          "--kui-layout-item-padding",
-          "--kui-layout-rounded-radius"
+          "--kui-color-border",
+          "--kui-layout-item-gap",
+          "--kui-list-divider-color",
+          "--kui-list-gap"
         ]
       },
       "diagnostics": [],
       "provenance": {
         "selection": "ai/component-catalog.json",
-        "composition": "docs/component-selection.md#correct-composition-and-duplicated-markup-trap"
+        "composition": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
     {
@@ -1576,6 +1804,7 @@
       "zones": [],
       "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
       "state": [
+        { "id": "badge content", "owner": "application", "required": false },
         { "id": "state mapping", "owner": "application", "required": false },
         { "id": "message lifetime", "owner": "application", "required": false },
         { "id": "retry behavior", "owner": "application", "required": false },
@@ -1589,7 +1818,8 @@
       },
       "accessibility": {
         "obligations": [
-          "Use alert urgency only for an attention-requiring failure."
+          "Use alert urgency only for an attention-requiring failure.",
+          "Keep optional badge content terse and do not rely on its tone alone for meaning."
         ]
       },
       "boundaries": {
@@ -1597,7 +1827,9 @@
         "publicClasses": [
           "kui-state-banner",
           "kui-state-banner__action",
+          "kui-state-banner__badge",
           "kui-state-banner__copy",
+          "kui-state-banner__detail",
           "kui-state-banner__icon"
         ],
         "publicTokens": [
@@ -1624,6 +1856,8 @@
           "--kui-state-banner-action-background",
           "--kui-state-banner-action-hover-background",
           "--kui-state-banner-background",
+          "--kui-state-banner-badge-background",
+          "--kui-state-banner-badge-foreground",
           "--kui-state-banner-border",
           "--kui-state-banner-danger-background",
           "--kui-state-banner-danger-border",