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

package/README.md

@@ -181,6 +181,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | ------------------------------------------------------------------- | --------------------------------------- | -------------------------------------- |
 | `LucideIcon`                                                        | `@kerfjs/ui/lucide-icon`                | `@kerfjs/ui/lucide-icon.css`           |
 | `Badge`                                                             | `@kerfjs/ui/badge`                      | `@kerfjs/ui/badge.css`                 |
+| `Chip`                                                              | `@kerfjs/ui/chip`                       | `@kerfjs/ui/chip.css`                  |
 | `DisclosureArrow`                                                   | `@kerfjs/ui/disclosure-arrow`           | `@kerfjs/ui/disclosure-arrow.css`      |
 | `Toolbar`                                                           | `@kerfjs/ui/toolbar`                    | `@kerfjs/ui/toolbar.css`               |
 | `ToolbarControlGroup`, `ToolbarActionLink`                          | `@kerfjs/ui/toolbar-control-group`      | `@kerfjs/ui/toolbar-control-group.css` |

package/ai/component-catalog.json

@@ -63,6 +63,65 @@
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
+    {
+      "id": "chip",
+      "name": "Chip",
+      "category": "Foundation",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A short tag with semantic tone and an optional accessible remove button, including compact and disabled variants.",
+      "uses": [],
+      "purpose": "Render removable tags without application rules on Web Awesome internals.",
+      "publicExports": [
+        "Chip"
+      ],
+      "useWhen": [
+        "Show a short tag that the application can remove through a delegated action, including a compact or disabled tag."
+      ],
+      "avoidWhen": [
+        "Use Badge for non-interactive status and count metadata.",
+        "Do not use the remove button without a specific accessible name."
+      ],
+      "alternatives": [],
+      "appOwns": [
+        "tag text and identity",
+        "remove action and list update",
+        "disabled policy"
+      ],
+      "variants": [
+        "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"
+      ],
+      "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."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/chip",
+        "manualCssImport": "@kerfjs/ui/chip.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-chip"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=chip",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "lucide-icon",
       "name": "LucideIcon",
@@ -523,7 +582,8 @@
       "useWhen": [
         "An application column needs shared header, content, and optional footer organization with exactly one scrolling content owner.",
         "A pane boundary needs an opt-in separator on any combination of logical sides.",
-        "Pinned chrome needs a divider from the scrolling content only while content is scrolled beneath it (wireScrollDividers)."
+        "Pinned chrome needs a divider from the scrolling content only while content is scrolled beneath it (wireScrollDividers).",
+        "A lowered background must cover the scrolling work viewport and blank space after short content without a second scroll container (appearance: sunken)."
       ],
       "avoidWhen": [
         "Do not use Pane as a padded card or add a competing scroll owner around its content slot.",
@@ -543,7 +603,8 @@
         "which logical boundaries show separators",
         "which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges)",
         "responsive placement and visibility",
-        "whether the chrome dividers follow the scroll, always show, or never show (chromeDividers)"
+        "whether the chrome dividers follow the scroll, always show, or never show (chromeDividers)",
+        "default or sunken scrolling work surface (appearance)"
       ],
       "variants": [
         "content only",
@@ -608,7 +669,9 @@
         "--kui-edge-inset-inline-end",
         "--kui-edge-inset-inline-start",
         "--kui-pane-separator-color",
-        "--kui-pane-separator-width"
+        "--kui-pane-separator-width",
+        "--kui-pane-chrome-background",
+        "--kui-sunken-panel-background"
       ],
       "links": {
         "catalogRoute": "?component=pane",
@@ -1422,6 +1485,7 @@
         "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)"
       ],
       "accessibility": [
@@ -1432,7 +1496,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."
         ]
       },
@@ -1473,6 +1537,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",
@@ -1789,7 +1854,7 @@
       ],
       "avoidWhen": [
         "Do not omit headingLevel when the text is the page or section heading.",
-        "Do not use a size below xlarge as a normal-color subsection title: large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section."
+        "Large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use xlarge-fixed for a normal-color toolbar heading at the fixed font-l step; use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section."
       ],
       "alternatives": [
         {
@@ -1809,6 +1874,7 @@
       ],
       "variants": [
         "xlarge",
+        "xlarge-fixed (fixed font-l heading)",
         "large",
         "default",
         "small",
@@ -2224,13 +2290,36 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "A fixed positive number of evenly distributed minmax columns with a typed xs gap by default and optional flex participation.",
+      "description": "Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, and optional flex participation.",
       "uses": [],
-      "purpose": "Arrange related siblings in equal-width columns without repeating application-owned grid-template-columns CSS.",
+      "purpose": "Arrange related siblings in equal-width columns with either a fixed count or automatic container-width collapse.",
       "publicExports": [
         "Grid"
       ],
       "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",
@@ -2300,13 +2389,14 @@
       ],
       "useWhen": [
         "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."
       ],
       "avoidWhen": [
-        "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": [
@@ -2328,11 +2418,12 @@
       ],
       "appOwns": [
         "child semantics and content",
-        "column count and responsive changes",
+        "fixed column count or responsive minimum width",
         "typed gap and flex choices"
       ],
       "variants": [
         "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",
@@ -2341,14 +2432,14 @@
       ],
       "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."
       ],
       "geometry": {
         "margin": "none",
         "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."
         ]
       },
       "delivery": {
@@ -2941,14 +3032,15 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Configurable native-button navigation rows with structured labels, status/busy metadata, density, group dividers, protected domain metadata hooks, and rounded-boundary overflow clipping.",
+      "description": "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.",
       "uses": [
         "lucide-icon",
         "loading-spinner"
       ],
-      "purpose": "Selectable, disabled, trailing, and multiline navigation rows.",
+      "purpose": "Selectable, disabled, trailing, and multiline action or link rows.",
       "publicExports": [
-        "ListItem"
+        "ListItem",
+        "ListItemLink"
       ],
       "cssValueProps": [
         {
@@ -2965,7 +3057,7 @@
         }
       ],
       "useWhen": [
-        "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."
       ],
       "avoidWhen": [
         "Do not use for an ordinary inline link, form button, isolated ARIA menuitem, or an interactive trailing action; use ListActionRow for sibling row actions.",
@@ -2980,12 +3072,14 @@
       ],
       "appOwns": [
         "routing",
+        "link destinations",
         "selection",
         "permissions",
         "action handling",
         "domain data attributes"
       ],
       "variants": [
+        "native link and external link",
         "selected",
         "pressed",
         "disabled",
@@ -3001,12 +3095,15 @@
         "before, after, or paired group divider"
       ],
       "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."
       ],
       "geometry": {
         "margin": "self",
         "border": "self",
-        "padding": "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."
+        ]
       },
       "delivery": {
         "browserImport": "@kerfjs/ui/list-item",
@@ -3027,22 +3124,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",
@@ -3052,6 +3154,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",
@@ -3343,11 +3446,11 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.",
+      "description": "Roving-tabindex-ready tabs with typed compact, segmented, icon-only, drop-target, pinned, and name-overflow presentations.",
       "uses": [
         "lucide-icon"
       ],
-      "purpose": "Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.",
+      "purpose": "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.",
       "publicExports": [
         "AppTab"
       ],
@@ -3366,6 +3469,7 @@
       "appOwns": [
         "tab identity",
         "selection",
+        "drop-target state",
         "close policy",
         "content",
         "application data attribute values",
@@ -3382,7 +3486,9 @@
         "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"
       ],
       "accessibility": [
@@ -3415,7 +3521,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",
@@ -3495,7 +3606,8 @@
         "overflow dividers on each side with tabs scrolled out of view (wired by wireScrollDividers)"
       ],
       "accessibility": [
-        "Keep exactly one selected tab at tabindex 0 and preserve the wiring keyboard model."
+        "Keep exactly one selected tab at tabindex 0 and preserve the wiring keyboard model.",
+        "Call wireTabBars for keyboard focus and selection, including the pinned leading tab's WebKit RTL scroll correction."
       ],
       "geometry": {
         "margin": "none",
@@ -3973,14 +4085,14 @@
       "category": "Controls",
       "kind": "component",
       "source": "kerf",
-      "description": "Controlled Web Awesome select with typed single or multiple values and form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.",
+      "description": "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.",
       "uses": [
         "lucide-icon",
         "badge",
         "wa-select",
         "wa-option"
       ],
-      "purpose": "Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.",
+      "purpose": "Choose one or more controlled values, keep unavailable choices visible, and optionally select all enabled choices or clear a multiple selection.",
       "publicExports": [
         "Select",
         "uiColor",
@@ -4030,6 +4142,7 @@
         "value",
         "validation",
         "choices",
+        "localized bulk-action labels",
         "hint copy",
         "domain mapping",
         "outer placement"
@@ -4045,11 +4158,14 @@
         "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"
       ],
       "accessibility": [
@@ -4058,6 +4174,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-rules.json

@@ -79,6 +79,14 @@
   },
   "@kerfjs/ui:toolbar-control-group": {
     "_source": "docs/component-selection.md#toolbar-composition",
+    "jsxExports": {
+      "ToolbarActionLink": {
+        "parents": {
+          "mode": "listed",
+          "entries": ["@kerfjs/ui:toolbar-control-group"]
+        }
+      }
+    },
     "parents": {
       "mode": "listed",
       "entries": ["@kerfjs/ui:toolbar"]

package/ai/component-composition.d.ts

@@ -52,6 +52,16 @@ export interface CatalogCompositionEntry {
   /** For a wrapper component: the cataloged roots it renders (any one of
    *  them, or nothing). Composition checks treat its elements as each root. */
   rendersAs?: CatalogQualifiedKey[];
+  /** Additional JSX exports in this selection entry with their own placement. */
+  jsxExports?: Record<
+    string,
+    {
+      parents: {
+        mode: 'any' | 'root' | 'listed';
+        entries: CatalogQualifiedKey[];
+      };
+    }
+  >;
   parents: { mode: 'any' | 'root' | 'listed'; entries: CatalogQualifiedKey[] };
   contexts: string[];
   zones: Array<{