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

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/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.
@@ -51,6 +51,8 @@ Exact prop names and types: [`@kerfjs/ui/select`](../public-api-signatures-v1.md
 - 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 +85,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.
 

package/ai/components/tabs.md

@@ -4,9 +4,11 @@
 
 `@kerfjs/ui:tabs` · Kerf UI · component · Navigation
 
+Roving-tabindex-ready tabs with typed compact, segmented, icon-only, drop-target, pinned, and name-overflow presentations.
+
 ## When to use
 
-Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.
+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.
 
 - Render one controlled application tab inside TabBar.
 
@@ -40,7 +42,9 @@ Exact prop names and types: [`@kerfjs/ui/app-tab`](../public-api-signatures-v1.m
 - compact size
 - segmented presentation
 - icon-only accessible presentation
-- label maximum width and truncation
+- label maximum width and ellipsis or visible name overflow
+- drop-target highlight
+- pinned leading position within a scrolling tablist
 - attention name color
 
 ## Composition
@@ -58,7 +62,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 ## State and wiring
 
-**The app owns:** tab identity; selection; close policy; content; application data attribute values; outer placement.
+**The app owns:** tab identity; selection; drop-target state; close policy; content; application data attribute values; outer placement.
 
 No wiring helper.
 
@@ -80,7 +84,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-app-tab`, `kui-app-tab__close`, `kui-app-tab__close-icon`, `kui-app-tab__name`, `kui-app-tab__select`, `kui-app-tab__trailing` on an element you write; render `AppTab` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-app-tab-attention-color`, `--kui-app-tab-color`, `--kui-app-tab-drop-indicator`, `--kui-app-tab-hover-background`, `--kui-app-tab-selected-background`, `--kui-app-tab-selected-border`, `--kui-app-tab-selected-color`, `--kui-color-brand-border-normal`, `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-color-text`, `--kui-focus-ring`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-shadow-s`, `--kui-space-2xs`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--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`, `--kui-color-brand-border-normal`, `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-color-text`, `--kui-focus-ring`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-shadow-s`, `--kui-space-2xs`, `--kui-space-xs`. 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/toolbar.md

@@ -36,6 +36,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.m
 - center priority for an expanded center control
 - trailing priority for an expanded trailing control at compact or narrow widths
 - trailing groups wrap instead of clipping
+- outer inset independently configurable from zone gap
 - app bar or bottom bar claiming its screen edges (safeAreaEdges)
 
 ## Composition
@@ -66,7 +67,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 Margin: none · border: conditional · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- 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.
 
 ## Accessibility
@@ -81,7 +82,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-toolbar`, `kui-toolbar__center`, `kui-toolbar__leading`, `kui-toolbar__trailing` on an element you write; render `Toolbar` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-font-sans`, `--kui-toolbar-center-padding-inline`, `--kui-toolbar-divider-color`, `--kui-toolbar-leading-min-width`, `--kui-toolbar-leading-padding-inline`, `--kui-toolbar-trailing-gap`, `--kui-toolbar-trailing-justify`, `--kui-toolbar-trailing-justify-self`, `--kui-toolbar-trailing-padding-inline`, `--kui-toolbar-zone-padding-inline`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-neutral-border-normal`, `--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`, `--kui-toolbar-trailing-justify`, `--kui-toolbar-trailing-justify-self`, `--kui-toolbar-trailing-padding-inline`, `--kui-toolbar-zone-padding-inline`. 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/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.60` and `kerfjs@5.0.0-beta.60`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.61` and `kerfjs@5.0.0-beta.61`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -424,8 +424,8 @@ interface PopupMenuItem {
     disabledReason?: string;
     /** Application `data-*` metadata such as a record id. */
     attributes?: PopupMenuDataAttributes;
-    /** Child commands opened by hover or keyboard navigation. */
-    submenu?: readonly PopupMenuItem[];
+    /** Child commands, headings, and dividers opened by hover or keyboard navigation. */
+    submenu?: readonly PopupMenuEntry[];
 }
 /** A labeled group heading; items that follow it belong to the group. */
 interface PopupMenuHeading {
@@ -783,9 +783,19 @@ interface ListItemProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+interface ListItemLinkProps extends Omit<ListItemProps, 'action' | 'pressed'> {
+    /** Native destination for this navigation row. */
+    href: string;
+    /** Open in a new tab with a safe rel and announce that behavior. */
+    external?: boolean;
+    action?: never;
+    pressed?: never;
+}
 declare function ListItem({ label, description, icon, trailing, status, busy, density, divider, selected, action, itemId, className, pressed, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, rootAttributes, slot, }: ListItemProps): SafeHtml;
+/** A navigation row with native link activation and ListItem geometry. */
+declare function ListItemLink({ href, external, label, description, icon, trailing, status, busy, density, divider, selected, itemId, className, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, rootAttributes, slot, }: ListItemLinkProps): SafeHtml;
 
-export { ListItem, type ListItemProps };
+export { ListItem, ListItemLink, type ListItemLinkProps, type ListItemProps };
 ```
 
 ## `@kerfjs/ui/list-inset-control`
@@ -948,15 +958,23 @@ type AppTabRootAttributes = Readonly<Record<`data-${string}`, string | undefined
     'data-tab-dragging'?: never;
     'data-tab-drop-position'?: never;
     'data-attention'?: never;
+    'data-drop-target'?: never;
+    'data-name-overflow'?: never;
+    'data-pinned'?: never;
 }>;
 type AppTabPresentation = 'pill' | 'segmented' | 'icon-only';
 type AppTabSize = 'default' | 'compact';
+type AppTabNameOverflow = 'ellipsis' | 'visible';
 interface AppTabProps {
     id: string;
     name: string;
     selected?: boolean;
     /** Emphasize the visible tab name with the attention color token. */
     attention?: boolean;
+    /** Highlight this tab as the target of a drag over its content. */
+    dropTarget?: boolean;
+    /** Keep the leading tab visible within its TabBar tablist while peers scroll. */
+    pinned?: boolean;
     closable?: boolean;
     draggable?: boolean;
     leading?: KerfUiContent;
@@ -967,6 +985,8 @@ interface AppTabProps {
     size?: AppTabSize;
     /** Maximum visible label width in CSS pixels before ellipsis. */
     labelMaxWidth?: number;
+    /** Keep the full name visible for an inline loading treatment. */
+    nameOverflow?: AppTabNameOverflow;
     /** Decorative dormant content for the close button. Must not contain interactive descendants. */
     closeIcon?: SafeHtml;
     selectAction?: string;
@@ -989,9 +1009,9 @@ interface AppTabProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function AppTab({ id, name, selected, attention, closable, draggable, leading, trailing, presentation, size, labelMaxWidth, closeIcon, selectAction, closeAction, className, placeholder, pending, rootAttributes, slot, }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, attention, dropTarget, pinned, closable, draggable, leading, trailing, presentation, size, labelMaxWidth, nameOverflow, closeIcon, selectAction, closeAction, className, placeholder, pending, rootAttributes, slot, }: AppTabProps): SafeHtml;
 
-export { AppTab, type AppTabPresentation, type AppTabProps, type AppTabSize };
+export { AppTab, type AppTabNameOverflow, type AppTabPresentation, type AppTabProps, type AppTabSize };
 ```
 
 ## `@kerfjs/ui/tab-bar`
@@ -2548,6 +2568,10 @@ interface SelectChoice<Value extends string = string> {
      */
     color?: CssForegroundColor;
     group?: string;
+    /** Keep an unavailable choice visible but prevent selection. */
+    disabled?: boolean;
+    /** Optional explanation exposed as the disabled option's native tooltip. */
+    disabledReason?: string;
     /**
      * Draw a divider between this choice and the previous choice in the same
      * list. A group boundary is already a separator, so the first choice of a
@@ -2599,6 +2623,8 @@ interface SelectSingleValueProps<Value extends string = string> {
     /** Show only the selected choice icon while retaining the Select's accessible name. */
     selectedPresentation?: SelectSelectedPresentation;
     triggerIcon?: never;
+    selectAllLabel?: never;
+    clearLabel?: never;
 }
 /**
  * Any number of chosen values. The popup stays open while the person toggles
@@ -2611,6 +2637,10 @@ interface SelectMultipleLabelProps<Value extends string = string> {
     renderSelected?: never;
     selectedPresentation?: 'label';
     triggerIcon?: never;
+    /** Opt in to a footer action that selects every enabled choice. */
+    selectAllLabel?: string;
+    /** Opt in to a footer action that clears the current selection. */
+    clearLabel?: string;
 }
 /**
  * A multiple Select drawn as an icon-only toolbar trigger, such as a
@@ -2629,6 +2659,10 @@ interface SelectMultipleIconProps<Value extends string = string> {
      * purpose (a funnel for a filter), independent of the selection.
      */
     triggerIcon: KerfUiContent;
+    /** Opt in to a footer action that selects every enabled choice. */
+    selectAllLabel?: string;
+    /** Opt in to a footer action that clears the current selection. */
+    clearLabel?: string;
 }
 type SelectMultipleValueProps<Value extends string = string> = SelectMultipleLabelProps<Value> | SelectMultipleIconProps<Value>;
 type SelectProps<Value extends string = string> = SelectBaseProps<Value> & SelectAccessibleName & (SelectSingleValueProps<Value> | SelectMultipleValueProps<Value>);
@@ -2777,14 +2811,14 @@ export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ```ts
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
-export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-CCke1yvQ.js';
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-DvgFLhLL.js';
 ```
 
 ## `@kerfjs/ui/wire-token-search-fields`
 
 ```ts
 import { Signal } from 'kerfjs';
-import { d as TokenSearchModel } from './token-search-field-CCke1yvQ.js';
+import { d as TokenSearchModel } from './token-search-field-DvgFLhLL.js';
 import './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchSubmit {
@@ -3034,6 +3068,40 @@ declare function Badge(props: BadgeProps): SafeHtml;
 export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTextProps, type BadgeTone };
 ```
 
+## `@kerfjs/ui/chip`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { BadgeTone, BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
+
+interface ChipCommonProps {
+    /** Visible, non-interactive chip content. */
+    children: SafeHtml | string | number;
+    tone?: BadgeTone;
+    appearance?: BadgeAppearance;
+    shape?: BadgeShape;
+    size?: BadgeSize;
+    disabled?: boolean;
+    /** Record identifier available to an application delegated action handler. */
+    itemId?: string;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/** A removable chip needs both a delegated action and a specific accessible name. */
+type ChipProps = ChipCommonProps & ({
+    removeAction: string;
+    removeLabel: string;
+} | {
+    removeAction?: never;
+    removeLabel?: never;
+});
+/** A short label with an optional native remove button. The application owns removal. */
+declare function Chip({ children, tone, appearance, shape, size, disabled, itemId, className, slot, ...remove }: ChipProps): SafeHtml;
+
+export { Chip, type ChipProps };
+```
+
 ## `@kerfjs/ui/lucide-icon`
 
 ```ts
@@ -3196,13 +3264,12 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-columns'?: never;
+    'data-min-column-width'?: never;
     'data-flex'?: never;
     'data-fill'?: never;
 }>;
-interface GridProps {
+interface GridCommonProps {
     children?: KerfUiContent;
-    /** Number of equal-width columns. Must be a positive safe integer. */
-    columns: number;
     /** A named UI spacing token or typed CSS length. Defaults to xs. */
     gap?: UiSpaceName | CssLength;
     /** Allow this grid to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
@@ -3219,8 +3286,17 @@ interface GridProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-/** A fixed-count grid whose columns share the available width equally. */
-declare function Grid({ children, columns, gap, flex, fill, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
+type GridProps = GridCommonProps & ({
+    /** Number of equal-width columns. Must be a positive safe integer. */
+    columns: number;
+    minColumnWidth?: never;
+} | {
+    columns?: never;
+    /** Fit equal columns of at least this width; collapse as the container narrows. */
+    minColumnWidth: CssLength;
+});
+/** Render equal tracks with a fixed count or a responsive minimum width. */
+declare function Grid({ children, columns, minColumnWidth, gap, flex, fill, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, UiSpaceName };
 ```
@@ -3252,6 +3328,6 @@ export { CssLength, Spacer, type SpacerProps, UiSpaceName };
 
 ```ts
 import 'kerfjs';
-export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, k as createTokenSearchModel } from './token-search-field-CCke1yvQ.js';
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, k as createTokenSearchModel } from './token-search-field-DvgFLhLL.js';
 import './semantic-content-BbzjvSu9.js';
 ```