@kerfjs/ui 5.0.0-beta.60 → 5.0.0-beta.62

package/ai/component-composition.json

@@ -60,6 +60,59 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:chip",
+      "package": "@kerfjs/ui",
+      "id": "chip",
+      "name": "Chip",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "tag text and identity",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "remove action and list update",
+          "owner": "application",
+          "required": false
+        },
+        { "id": "disabled policy", "owner": "application", "required": false }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["foundation"],
+        "geometry": { "margin": "none", "border": "self", "padding": "self" }
+      },
+      "accessibility": {
+        "obligations": [
+          "The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.",
+          "Keep meaningful tag text visible because tone is supplementary."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-chip",
+        "publicClasses": ["kui-chip"],
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:lucide-icon",
       "package": "@kerfjs/ui",
@@ -536,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": {
@@ -592,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": [],
@@ -1383,7 +1443,7 @@
           "border": "conditional",
           "padding": "self",
           "notes": [
-            "Padding belongs to the toolbar; dividerSides selects any canonical combination of its physical top, right, bottom, and left edges.",
+            "Padding belongs to the toolbar; --kui-toolbar-inset controls outer padding and minimum height independently of --kui-toolbar-gap. dividerSides selects any canonical combination of its physical top, right, bottom, and left edges.",
             "Safe areas: a Pane header or footer hands a sole Toolbar its inline edges; an app bar or bottom bar at a screen edge claims its sides with safeAreaEdges and pads each claimed side by the --kui-edge-inset-* context or the full device inset, while its box and dividers paint through."
           ]
         }
@@ -1407,6 +1467,7 @@
           "--kui-font-sans",
           "--kui-toolbar-center-padding-inline",
           "--kui-toolbar-divider-color",
+          "--kui-toolbar-inset",
           "--kui-toolbar-leading-min-width",
           "--kui-toolbar-leading-padding-inline",
           "--kui-toolbar-trailing-gap",
@@ -1481,7 +1542,7 @@
       },
       "cssValueProps": [],
       "boundaries": {
-        "rootClass": "kui-toolbar-action-link",
+        "rootClass": "kui-toolbar-control-group",
         "publicClasses": [
           "kui-toolbar-action-link",
           "kui-toolbar-control-group"
@@ -1518,6 +1579,14 @@
       "provenance": {
         "selection": "ai/component-catalog.json",
         "composition": "docs/component-selection.md#toolbar-composition"
+      },
+      "jsxExports": {
+        "ToolbarActionLink": {
+          "parents": {
+            "mode": "listed",
+            "entries": ["@kerfjs/ui:toolbar-control-group"]
+          }
+        }
       }
     },
     {
@@ -1976,7 +2045,7 @@
           "required": false
         },
         {
-          "id": "column count and responsive changes",
+          "id": "fixed column count or responsive minimum width",
           "owner": "application",
           "required": false
         },
@@ -2000,17 +2069,28 @@
           "border": "none",
           "padding": "none",
           "notes": [
-            "Every track uses minmax(0, 1fr), so unequal intrinsic widths cannot break equal distribution."
+            "Fixed tracks use minmax(0, 1fr); responsive tracks use auto-fit with a minimum width capped at 100%, preserving equal distribution without narrow overflow."
           ]
         }
       },
       "accessibility": {
         "obligations": [
           "Grid adds layout only and no grid role; children retain responsibility for native or ARIA semantics.",
-          "Responsive column-count changes must preserve source and focus order."
+          "Responsive column-count changes preserve source and focus order."
         ]
       },
       "cssValueProps": [
+        {
+          "path": "minColumnWidth",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["minColumnWidth={px(376)}"]
+        },
         {
           "path": "gap",
           "grammar": "length",
@@ -2430,6 +2510,11 @@
       "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
       "state": [
         { "id": "routing", "owner": "application", "required": false },
+        {
+          "id": "link destinations",
+          "owner": "application",
+          "required": false
+        },
         { "id": "selection", "owner": "application", "required": false },
         { "id": "permissions", "owner": "application", "required": false },
         { "id": "action handling", "owner": "application", "required": false },
@@ -2448,11 +2533,18 @@
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
         "roles": ["navigation"],
-        "geometry": { "margin": "self", "border": "self", "padding": "self" }
+        "geometry": {
+          "margin": "self",
+          "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."
+          ]
+        }
       },
       "accessibility": {
         "obligations": [
-          "Uses native button activation; selected maps to aria-current and pressed to aria-pressed; rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls."
+          "ListItem uses native button activation and pressed maps to aria-pressed; ListItemLink uses native anchor activation and external opens a new tab with safe rel and an announced default label. Both map selected to aria-current; disabled or loading links omit href and leave the tab order. rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls."
         ]
       },
       "cssValueProps": [
@@ -2480,22 +2572,27 @@
         ],
         "publicTokens": [
           "--kui-color-brand-border-normal",
+          "--kui-color-brand-border-quiet",
           "--kui-color-brand-fill-quiet",
           "--kui-color-brand-fill-normal",
           "--kui-color-neutral-fill-quiet",
           "--kui-color-neutral-on-normal",
           "--kui-color-neutral-on-quiet",
           "--kui-color-neutral-border-quiet",
+          "--kui-color-neutral-border-normal",
           "--kui-focus-ring",
           "--kui-list-item-color",
+          "--kui-list-item-background",
           "--kui-list-item-align-items",
           "--kui-list-item-border-width",
+          "--kui-list-item-border",
           "--kui-list-item-columns",
           "--kui-list-item-drag-target-background",
           "--kui-list-item-drag-target-outline",
           "--kui-list-item-drag-target-outline-offset",
           "--kui-list-item-gap",
           "--kui-list-item-hover-background",
+          "--kui-list-item-hover-border",
           "--kui-list-item-icon-color",
           "--kui-list-item-icon-size",
           "--kui-list-item-label-max-width",
@@ -2505,6 +2602,7 @@
           "--kui-list-item-padding-inline",
           "--kui-list-item-radius",
           "--kui-list-item-selected-background",
+          "--kui-list-item-selected-border",
           "--kui-list-item-selected-color",
           "--kui-list-item-trailing-color",
           "--kui-list-group-divider-color",
@@ -2778,6 +2876,11 @@
       "state": [
         { "id": "tab identity", "owner": "application", "required": false },
         { "id": "selection", "owner": "application", "required": false },
+        {
+          "id": "drop-target state",
+          "owner": "application",
+          "required": false
+        },
         { "id": "close policy", "owner": "application", "required": false },
         { "id": "content", "owner": "application", "required": false },
         {
@@ -2820,7 +2923,12 @@
           "--kui-app-tab-attention-color",
           "--kui-app-tab-color",
           "--kui-app-tab-drop-indicator",
+          "--kui-app-tab-drop-target-background",
+          "--kui-app-tab-drop-target-color",
+          "--kui-app-tab-drop-target-ring",
           "--kui-app-tab-hover-background",
+          "--kui-app-tab-pinned-background",
+          "--kui-app-tab-pinned-hover-background",
           "--kui-app-tab-selected-background",
           "--kui-app-tab-selected-border",
           "--kui-app-tab-selected-color",
@@ -3312,6 +3420,7 @@
           "Hint text is visible below the control through Web Awesome's native hint relationship; placeholderText remains the empty value inside the closed control.",
           "Import select/register once; its scoped lifecycle adapter keeps the latest open/close request authoritative across animation reversals, canceled transitions, and removal. Do not add consumer popup timing or position repairs.",
           "With multiple, the popup stays open while choices toggle (pointer, Enter, or Space) and closes on an outside press, Escape, or focus leaving; each chosen option shows a check, and the closed control summarizes the chosen labels in choice order.",
+          "Disabled choices stay visible but cannot be selected; disabledReason exposes a tooltip. A multiple Select can opt in to localized select-all and clear buttons, which skip disabled choices and publish ordinary input/change events for changed values.",
           "A multiple icon-only trigger shows its fixed triggerIcon and, while any choice is chosen, an aria-hidden count Badge; the combobox's accessible name ends with the chosen labels in choice order, and its hidden value stays empty.",
           "Once registered, an icon-only trigger (single or multiple) shows an aria-hidden Web Awesome help tag repeating its accessible name (a single Select adds its current choice) after a 500ms hover and at once on keyboard focus; it hides while the popup is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip."
         ]

package/ai/component-composition.schema.json

@@ -166,6 +166,27 @@
           "items": { "type": "string", "pattern": "^[^:]+:[^:]+$" },
           "uniqueItems": true
         },
+        "jsxExports": {
+          "description": "Placement contracts for additional JSX exports from one selection entry. These exports do not stand for the entry's root or its zones.",
+          "type": "object",
+          "propertyNames": { "pattern": "^[A-Z][A-Za-z0-9]*$" },
+          "additionalProperties": {
+            "type": "object",
+            "required": ["parents"],
+            "properties": {
+              "parents": {
+                "type": "object",
+                "required": ["mode", "entries"],
+                "properties": {
+                  "mode": { "enum": ["any", "root", "listed"] },
+                  "entries": { "$ref": "#/$defs/stringList" }
+                },
+                "additionalProperties": false
+              }
+            },
+            "additionalProperties": false
+          }
+        },
         "parents": {
           "type": "object",
           "required": ["mode", "entries"],

package/ai/components/README.md

@@ -9,6 +9,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 ## Kerf UI — Foundation
 
 - [Badge](./badge.md) — Present compact metadata without application-authored badge CSS or consumer styling of component internals.
+- [Chip](./chip.md) — Render removable tags without application rules on Web Awesome internals.
 - [LucideIcon](./lucide-icon.md) — Decorative and meaningfully labeled Lucide-compatible icons.
 - [DisclosureArrow](./disclosure-arrow.md) — Indicate whether a disclosure control is open with an overridable 18px root-scaled visual and shortest-path rotation behavior.
 - [Foundation tokens](./foundation.md) — Provide the shared semantic token foundation for application themes and every styled Kerf UI component.
@@ -33,7 +34,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Headers](./headers.md) — Page, dialog, and definition-list hierarchy.
 - [ValueTable](./value-table.md) — Key/value rows with optional icons and aligned separators.
 - [Row](./row.md) — Arrange related content horizontally with consistent spacing, optional physical-side text/control insets, and explicit left/center/right/full plus top/middle/bottom/full/baseline alignment instead of application-owned flex wrappers.
-- [Grid](./grid.md) — Arrange related siblings in equal-width columns without repeating application-owned grid-template-columns CSS.
+- [Grid](./grid.md) — Arrange related siblings in equal-width columns with either a fixed count or automatic container-width collapse.
 - [Spacer](./spacer.md) — Express an intentional empty dimension or consume remaining flex space without application-owned spacer markup or raw CSS lengths.
 - [ListInsetControl](./list-inset-control.md) — Apply the standard 8px outer margin to all physical sides of a self-bordered control by default, or only the sides selected with the canonical Sides contract.
 - [ListInsetText](./list-inset-text.md) — Apply the full 8px margin + 1px transparent border + 8px padding to all physical sides of bare text by default, or only the sides selected with the canonical Sides contract.
@@ -44,9 +45,9 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [List](./list.md) — Standardize vertical component layout, optional physical-side text/control insets, and scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.
 - [ListHeader](./list-header.md) — Fill the available section width by default, or shrink-wrap without outer geometry when inline, while splitting a dormant title and mutually exclusive semantic count or badge from an optional logical-end action with an 18px visual; disclosure mode renders the title cluster as a button with a default production DisclosureArrow.
 - [ListActionRow](./list-action-row.md) — Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.
-- [ListItem](./list-item.md) — Selectable, disabled, trailing, and multiline navigation rows.
+- [ListItem](./list-item.md) — Selectable, disabled, trailing, and multiline action or link rows.
 - [Application tabs](./application-tabs.md) — Show AppTab and TabBar in a complete controlled composition.
-- [AppTab](./tabs.md) — Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.
+- [AppTab](./tabs.md) — Render a controlled application tab with compact or icon-only presentation, a visible drop target, optional full-name display, and an optional pinned leading position.
 - [TabBar](./tab-bar.md) — Controlled tab strips whose tabs shrink and scroll while fixed leading, trailing, and far-edge end actions remain visible.
 
 ## Kerf UI — Controls
@@ -54,7 +55,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [SegmentedControl](./segmented-control.md) — Controlled exclusive choices in toolbar, rounded-rectangle, and pill presentations.
 - [TokenSearchField](./token-search-field.md) — Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
 - [ResizableRegion](./resize.md) — Pointer and keyboard-operable split region with a customizable handle icon.
-- [Select](./select.md) — Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
+- [Select](./select.md) — Choose one or more controlled values, keep unavailable choices visible, and optionally select all enabled choices or clear a multiple selection.
 - [PopupMenu](./popup-menu.md) — A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.
 
 ## Kerf UI — Feedback

package/ai/components/chip.md

@@ -0,0 +1,72 @@
+# Chip
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:chip` · Kerf UI · component · Foundation
+
+A short tag with semantic tone and an optional accessible remove button, including compact and disabled variants.
+
+## When to use
+
+Render removable tags without application rules on Web Awesome internals.
+
+- Show a short tag that the application can remove through a delegated action, including a compact or disabled tag.
+
+**Not when:**
+
+- Use Badge for non-interactive status and count metadata.
+- Do not use the remove button without a specific accessible name.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/chip` — exports `Chip`.
+- CSS: the browser build of `@kerfjs/ui/chip` pulls its CSS automatically; import `@kerfjs/ui/chip.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#kerfjsuichip) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, brand, pop, success, warning, or danger tone
+- quiet, solid, or outline appearance
+- pill or rounded shape
+- compact or default size
+- removable or plain, enabled or disabled
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** tag text and identity; remove action and list update; disabled policy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.
+- Keep meaningful tag text visible because tone is supplementary.
+
+## Styling boundary
+
+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-chip`.
+
+Never put `kui-chip` on an element you write; render `Chip` instead (`KUI-L103`).
+
+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`).
+
+## Related
+
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=chip`.

package/ai/components/grid.md

@@ -4,21 +4,22 @@
 
 `@kerfjs/ui:grid` · Kerf UI · component · Structure
 
-A fixed positive number of evenly distributed minmax columns with a typed xs gap by default and optional flex participation.
+Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, and optional flex participation.
 
 ## When to use
 
-Arrange related siblings in equal-width columns without repeating application-owned grid-template-columns CSS.
+Arrange related siblings in equal-width columns with either a fixed count or automatic container-width collapse.
 
 - Arrange related siblings into a fixed positive number of equal-width columns.
+- Fit equal-width columns down to a typed minimum and collapse as the container narrows.
 - Prevent wider intrinsic content from making one fractional track wider than its peers.
 - Use a finite flex keyword or the flex() builder when Grid participates in a flexible parent layout.
 
 **Not when:**
 
-- Do not use Grid for intrinsic, asymmetric, spanning, auto-fit, or masonry tracks; use application-owned CSS grid.
+- Do not use Grid for intrinsic, asymmetric, spanning, or masonry tracks; use application-owned CSS grid.
 - Do not use Grid when columns need a user-operable separator; use ResizableRegion.
-- Do not expect Grid to choose responsive breakpoints or change the column count; the application owns that policy.
+- Do not combine fixed columns with minColumnWidth; choose one layout mode.
 - Do not pass raw CSS strings to gap or flex, mix their distinct grammars, or use s/xl spacing steps without a deliberate exception.
 
 **Alternatives:**
@@ -40,6 +41,7 @@ Exact prop names and types: [`@kerfjs/ui/grid`](../public-api-signatures-v1.md#k
 **Variants (configure, do not restyle):**
 
 - any positive safe-integer equal-track count
+- typed minimum column width with automatic container-width collapse
 - named none/2xs/xs/s/m/l/xl token gap
 - typed CssLength gap
 - boolean, finite-keyword, or typed CssFlex flex
@@ -48,6 +50,7 @@ Exact prop names and types: [`@kerfjs/ui/grid`](../public-api-signatures-v1.md#k
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
 
+- `minColumnWidth`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `minColumnWidth={px(376)}`
 - `gap`: length grammar; raw values: forbid; shorthands `none`, `2xs`, `xs`, `m`, `l`; exceptional (justify) `s`, `xl`; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `gap="m"`
 - `flex`: flex grammar; raw values: forbid; shorthands `none`, `auto`, `initial`; helpers `flex` — e.g. `flex`
 
@@ -59,7 +62,7 @@ Exact prop names and types: [`@kerfjs/ui/grid`](../public-api-signatures-v1.md#k
 
 ## State and wiring
 
-**The app owns:** child semantics and content; column count and responsive changes; typed gap and flex choices.
+**The app owns:** child semantics and content; fixed column count or responsive minimum width; typed gap and flex choices.
 
 No wiring helper.
 
@@ -67,12 +70,12 @@ No wiring helper.
 
 Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- Every track uses minmax(0, 1fr), so unequal intrinsic widths cannot break equal distribution.
+- Fixed tracks use minmax(0, 1fr); responsive tracks use auto-fit with a minimum width capped at 100%, preserving equal distribution without narrow overflow.
 
 ## Accessibility
 
 - Grid adds layout only and no grid role; children retain responsibility for native or ARIA semantics.
-- Responsive column-count changes must preserve source and focus order.
+- Responsive column-count changes preserve source and focus order.
 
 ## Styling boundary
 

package/ai/components/list-item.md

@@ -4,13 +4,13 @@
 
 `@kerfjs/ui:list-item` · Kerf UI · component · Navigation
 
-Configurable native-button navigation rows with structured labels, status/busy metadata, density, group dividers, protected domain metadata hooks, and rounded-boundary overflow clipping.
+Configurable native-button action rows and native-anchor navigation rows with structured labels, status/busy metadata, density, group dividers, protected domain metadata hooks, and rounded-boundary overflow clipping.
 
 ## When to use
 
-Selectable, disabled, trailing, and multiline navigation rows.
+Selectable, disabled, trailing, and multiline action or link rows.
 
-- Render a selectable, disabled, trailing, or multiline sidebar/navigation action row whose descendants must remain clipped to the rounded row boundary.
+- Render a selectable, disabled, trailing, or multiline sidebar action row whose descendants must remain clipped to the rounded row boundary; use ListItemLink when the destination has an href and needs native link activation.
 
 **Not when:**
 
@@ -23,7 +23,7 @@ Selectable, disabled, trailing, and multiline navigation rows.
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/list-item` — exports `ListItem`.
+- JavaScript: `@kerfjs/ui/list-item` — exports `ListItem`, `ListItemLink`.
 - CSS: the browser build of `@kerfjs/ui/list-item` pulls its CSS automatically; import `@kerfjs/ui/list-item.css` manually only without the `browser` export condition.
 - Declared side effects: browser-condition-css.
 
@@ -33,6 +33,7 @@ Exact prop names and types: [`@kerfjs/ui/list-item`](../public-api-signatures-v1
 
 **Variants (configure, do not restyle):**
 
+- native link and external link
 - selected
 - pressed
 - disabled
@@ -60,7 +61,7 @@ Exact prop names and types: [`@kerfjs/ui/list-item`](../public-api-signatures-v1
 
 ## State and wiring
 
-**The app owns:** routing; selection; permissions; action handling; domain data attributes.
+**The app owns:** routing; link destinations; selection; permissions; action handling; domain data attributes.
 
 No wiring helper.
 
@@ -68,9 +69,11 @@ 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.
+
 ## Accessibility
 
-- Uses native button activation; selected maps to aria-current and pressed to aria-pressed; rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls.
+- ListItem uses native button activation and pressed maps to aria-pressed; ListItemLink uses native anchor activation and external opens a new tab with safe rel and an announced default label. Both map selected to aria-current; disabled or loading links omit href and leave the tab order. rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls.
 
 ## Styling boundary
 
@@ -80,7 +83,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-list-item`, `kui-list-item__icon`, `kui-list-item__label`, `kui-list-item__primary-label`, `kui-list-item__description`, `kui-list-item__status`, `kui-list-item__trailing` on an element you write; render `ListItem` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-brand-border-normal`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-quiet`, `--kui-focus-ring`, `--kui-list-item-color`, `--kui-list-item-align-items`, `--kui-list-item-border-width`, `--kui-list-item-columns`, `--kui-list-item-drag-target-background`, `--kui-list-item-drag-target-outline`, `--kui-list-item-drag-target-outline-offset`, `--kui-list-item-gap`, `--kui-list-item-hover-background`, `--kui-list-item-icon-color`, `--kui-list-item-icon-size`, `--kui-list-item-label-max-width`, `--kui-list-item-label-weight`, `--kui-list-item-min-height`, `--kui-list-item-padding-block`, `--kui-list-item-padding-inline`, `--kui-list-item-radius`, `--kui-list-item-selected-background`, `--kui-list-item-selected-color`, `--kui-list-item-trailing-color`, `--kui-list-group-divider-color`, `--kui-font-xs`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-brand-border-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-focus-ring`, `--kui-list-item-color`, `--kui-list-item-background`, `--kui-list-item-align-items`, `--kui-list-item-border-width`, `--kui-list-item-border`, `--kui-list-item-columns`, `--kui-list-item-drag-target-background`, `--kui-list-item-drag-target-outline`, `--kui-list-item-drag-target-outline-offset`, `--kui-list-item-gap`, `--kui-list-item-hover-background`, `--kui-list-item-hover-border`, `--kui-list-item-icon-color`, `--kui-list-item-icon-size`, `--kui-list-item-label-max-width`, `--kui-list-item-label-weight`, `--kui-list-item-min-height`, `--kui-list-item-padding-block`, `--kui-list-item-padding-inline`, `--kui-list-item-radius`, `--kui-list-item-selected-background`, `--kui-list-item-selected-border`, `--kui-list-item-selected-color`, `--kui-list-item-trailing-color`, `--kui-list-group-divider-color`, `--kui-font-xs`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`. 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/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

@@ -4,11 +4,11 @@
 
 `@kerfjs/ui:select` · Kerf UI · component · Controls
 
-Controlled Web Awesome select with typed single or multiple values and form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
+Controlled Web Awesome select with typed single or multiple values, disabled choices, optional bulk actions, and form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
 
 ## When to use
 
-Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
+Choose one or more controlled values, keep unavailable choices visible, and optionally select all enabled choices or clear a multiple selection.
 
 - Choose a controlled value from a moderate or long list, including grouped and icon-bearing choices.
 - Color an optional choice icon with a CssForegroundColor: uiColor() with a foreground token such as success-on-quiet, or foregroundColorVar() for an app-owned property. Fill tokens such as success are backgrounds that leave the icon nearly invisible, so they, lengths, raw color strings, and unqualified colorVar() values are rejected.
@@ -46,11 +46,14 @@ 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
 - custom selected content typography and ellipsis
 - multiple selection
+- disabled choice with an optional reason
+- opt-in select-all and clear actions for multiple selection
 - multiple icon-only filter trigger with a fixed triggerIcon
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
@@ -83,6 +86,7 @@ Margin: none · border: self · padding: self (layout role: controls). `self` me
 - Hint text is visible below the control through Web Awesome's native hint relationship; placeholderText remains the empty value inside the closed control.
 - Import select/register once; its scoped lifecycle adapter keeps the latest open/close request authoritative across animation reversals, canceled transitions, and removal. Do not add consumer popup timing or position repairs.
 - With multiple, the popup stays open while choices toggle (pointer, Enter, or Space) and closes on an outside press, Escape, or focus leaving; each chosen option shows a check, and the closed control summarizes the chosen labels in choice order.
+- Disabled choices stay visible but cannot be selected; disabledReason exposes a tooltip. A multiple Select can opt in to localized select-all and clear buttons, which skip disabled choices and publish ordinary input/change events for changed values.
 - A multiple icon-only trigger shows its fixed triggerIcon and, while any choice is chosen, an aria-hidden count Badge; the combobox's accessible name ends with the chosen labels in choice order, and its hidden value stays empty.
 - Once registered, an icon-only trigger (single or multiple) shows an aria-hidden Web Awesome help tag repeating its accessible name (a single Select adds its current choice) after a 500ms hover and at once on keyboard focus; it hides while the popup is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip.