@kerfjs/ui 5.0.0-beta.48 → 5.0.0-beta.50

package/ai/component-catalog.json

@@ -4,6 +4,65 @@
   "package": "@kerfjs/ui",
   "description": "Machine-readable selection, composition, delivery, ownership, and accessibility metadata for Kerf UI and its supported Web Awesome set.",
   "entries": [
+    {
+      "id": "badge",
+      "name": "Badge",
+      "category": "Foundation",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Self-styled, non-interactive status, count, and category metadata configured through semantic tone, appearance, shape, and size props.",
+      "uses": [],
+      "purpose": "Present compact metadata without application-authored badge CSS or consumer styling of component internals.",
+      "publicExports": [
+        "Badge"
+      ],
+      "useWhen": [
+        "Show a short status, count, category, or metadata label whose presentation should be configured rather than restyled."
+      ],
+      "avoidWhen": [
+        "Do not use Badge as a button, link, or removable chip; choose an interactive control with the correct native semantics.",
+        "Do not rely on tone alone to communicate meaning."
+      ],
+      "alternatives": [],
+      "appOwns": [
+        "metadata text",
+        "semantic tone mapping",
+        "accessible label for abbreviated content"
+      ],
+      "variants": [
+        "neutral, brand, pop, success, warning, or danger tone",
+        "quiet, solid, or outline appearance",
+        "pill or rounded shape",
+        "compact or default size",
+        "labeled or decorative duplicate"
+      ],
+      "accessibility": [
+        "Badge is non-interactive. Supply label when visible content is abbreviated, and ariaHidden when it repeats an accessible name owned by the surrounding component.",
+        "Keep meaningful text visible because tone is supplementary."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/badge",
+        "manualCssImport": "@kerfjs/ui/badge.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-badge"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=badge",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "lucide-icon",
       "name": "LucideIcon",
@@ -630,7 +689,6 @@
       "publicClasses": [
         "kui-split-view",
         "kui-split-view__list",
-        "kui-resizable-region",
         "kui-split-view__detail",
         "kui-split-view--compact"
       ],
@@ -776,6 +834,7 @@
         "slide, fade-slide, or instant content",
         "clipped, scrolling, or popup-visible content",
         "inline, overlay, or hidden responsive presentation",
+        "narrow or compact single-track responsive fill",
         "safe-area restore control"
       ],
       "accessibility": [
@@ -1082,17 +1141,19 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Typed toolbar groups for compact, mixed, selected, dropdown, and avatar controls.",
+      "description": "Typed toolbar groups for buttons, semantic action links, compact mixed controls, selected states, dropdown surfaces, and avatar controls.",
       "uses": [
         "lucide-icon",
         "segmented-control"
       ],
-      "purpose": "Typed toolbar groups for compact, mixed, selected, dropdown, and avatar controls.",
+      "purpose": "Provide complete toolbar action geometry through configuration, including semantic anchors, overflow containment, and dropdown menu insets without application CSS.",
       "publicExports": [
+        "ToolbarActionLink",
         "ToolbarControlGroup"
       ],
       "useWhen": [
         "Group related controls inside a toolbar with a supported visual treatment.",
+        "Use ToolbarActionLink for navigation or external resources that must retain native anchor semantics inside a group.",
         "Fill it with plain <button> controls (the group styles > button fully); use wa-button only for a Web Awesome feature such as a wa-dropdown popup trigger.",
         "For an avatar control, set content=avatar and avatarImage instead of inserting an img; one button paints the group and multiple buttons paint only the pressed highlight."
       ],
@@ -1112,6 +1173,7 @@
       ],
       "appOwns": [
         "actions",
+        "link destination and copy",
         "pressed state",
         "expanded state",
         "avatar image URL"
@@ -1127,6 +1189,9 @@
         "raised, filled, or outline selected chrome",
         "brand, neutral, or pop selected tone",
         "nested dropdown trigger",
+        "standard, compact, or list-zero dropdown menu inset",
+        "visible or horizontally scrollable overflow",
+        "always visible or compact-only responsive visibility",
         "avatar scrim",
         "contained avatar background on a single group or selected multi-button highlight"
       ],
@@ -1147,6 +1212,7 @@
       },
       "wiring": [],
       "publicClasses": [
+        "kui-toolbar-action-link",
         "kui-toolbar-control-group"
       ],
       "publicTokens": [
@@ -1457,7 +1523,7 @@
     },
     {
       "id": "headers",
-      "name": "Header composition",
+      "name": "Headers",
       "category": "Structure",
       "kind": "composition",
       "source": "kerf",
@@ -1680,6 +1746,104 @@
         "recipe": "docs/layout.md#row-and-list-alignment"
       }
     },
+    {
+      "id": "grid",
+      "name": "Grid",
+      "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.",
+      "uses": [],
+      "purpose": "Arrange related siblings in equal-width columns without repeating application-owned grid-template-columns CSS.",
+      "publicExports": ["Grid"],
+      "cssValueProps": [
+        {
+          "path": "gap",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": ["gap=\"m\"", "gap={space(\"m\")}", "gap={calc(plus(rem(0.25), pct(10)))}"]
+        },
+        {
+          "path": "flex",
+          "grammar": "flex",
+          "helpers": ["flex"],
+          "shorthands": ["none", "auto", "initial"],
+          "canonicalShorthands": ["none", "auto", "initial"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["flex", "flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
+        }
+      ],
+      "useWhen": [
+        "Arrange related siblings into a fixed positive number of equal-width columns.",
+        "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 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 pass raw CSS strings to gap or flex, mix their distinct grammars, or use s/xl spacing steps without a deliberate exception."
+      ],
+      "alternatives": [
+        {
+          "id": "row",
+          "relationship": "axis-alternative",
+          "when": "Use Row for one horizontal flex line, alignment, or wrapping rather than fixed equal tracks."
+        },
+        {
+          "id": "list",
+          "relationship": "axis-alternative",
+          "when": "Use List when the main layout axis is vertical."
+        },
+        {
+          "id": "resize",
+          "relationship": "interactive-alternative",
+          "when": "Use ResizableRegion when people must adjust the boundary between tracks."
+        }
+      ],
+      "appOwns": [
+        "child semantics and content",
+        "column count and responsive changes",
+        "typed gap and flex choices"
+      ],
+      "variants": [
+        "any positive safe-integer equal-track count",
+        "named none/2xs/xs/s/m/l/xl token gap",
+        "typed CssLength gap",
+        "boolean, finite-keyword, or typed CssFlex flex"
+      ],
+      "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."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none",
+        "notes": [
+          "Every track uses minmax(0, 1fr), so unequal intrinsic widths cannot break equal distribution."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/grid",
+        "manualCssImport": "@kerfjs/ui/grid.css",
+        "sideEffects": ["browser-condition-css"]
+      },
+      "wiring": [],
+      "publicClasses": ["kui-grid"],
+      "publicTokens": ["--kui-grid-gap", "--kui-layout-item-gap"],
+      "links": {
+        "catalogRoute": "?component=grid",
+        "documentation": "docs/layout.md",
+        "recipe": "docs/layout.md#grid"
+      }
+    },
     {
       "id": "spacer",
       "name": "Spacer",
@@ -1894,11 +2058,12 @@
       "source": "kerf",
       "description": "Configurable section headings with full-width or shrink-wrapped inline presentation, semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.",
       "uses": [
+        "badge",
         "lucide-icon",
         "disclosure-arrow",
         "text"
       ],
-      "purpose": "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 legacy 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.",
+      "purpose": "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.",
       "publicExports": [
         "ListHeader"
       ],
@@ -1957,16 +2122,12 @@
         "kui-list-header",
         "kui-list-header__action",
         "kui-list-header__action-layer",
-        "kui-list-header__badge",
-        "kui-list-header__count",
         "kui-list-header__label",
         "kui-list-header__title",
         "kui-list-header__toggle"
       ],
       "publicTokens": [
         "--kui-color-neutral-border-quiet",
-        "--kui-color-neutral-fill-quiet",
-        "--kui-color-neutral-on-quiet",
         "--kui-focus-ring",
         "--kui-font-xs",
         "--kui-list-header-action-icon-size",
@@ -1974,15 +2135,8 @@
         "--kui-layout-inline-margin",
         "--kui-layout-item-gap",
         "--kui-layout-item-padding",
-        "--kui-layout-pill-radius",
-        "--kui-list-header-count-font-size",
         "--kui-list-header-hover-background",
-        "--kui-list-group-divider-color",
-        "--kui-color-brand-on-normal",
-        "--kui-color-pop-fill-normal",
-        "--kui-color-pop-on-normal",
-        "--kui-color-danger-fill-normal",
-        "--kui-color-danger-on-normal"
+        "--kui-list-group-divider-color"
       ],
       "links": {
         "catalogRoute": "?component=list-header",
@@ -2345,7 +2499,7 @@
     },
     {
       "id": "application-tabs",
-      "name": "Application tabs composition",
+      "name": "Application tabs",
       "category": "Navigation",
       "kind": "composition",
       "source": "kerf",
@@ -2503,12 +2657,12 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Controlled tab strips with typed rail, segmented, and inspector presentation plus intrinsic or fill allocation.",
+      "description": "Controlled tab strips with typed presentation and allocation, a scroll-owning tab region, an optional adjacent trailing action, and a separately pinned far-edge end action.",
       "uses": [
         "tabs",
         "toolbar-control-group"
       ],
-      "purpose": "Controlled tab strips with typed rail, segmented, and inspector presentation plus intrinsic or fill allocation.",
+      "purpose": "Controlled tab strips whose tabs shrink and scroll while fixed leading, trailing, and far-edge end actions remain visible.",
       "publicExports": [
         "TabBar",
         "wireTabBars",
@@ -2549,7 +2703,8 @@
         "reorderable",
         "rail, segmented, and inspector presentation",
         "intrinsic or fill allocation",
-        "separate or adjacent trailing action"
+        "separate or adjacent trailing action",
+        "far-edge end action"
       ],
       "accessibility": [
         "Keep exactly one selected tab at tabindex 0 and preserve the wiring keyboard model."
@@ -2557,7 +2712,10 @@
       "geometry": {
         "margin": "none",
         "border": "self",
-        "padding": "self"
+        "padding": "self",
+        "notes": [
+          "TabBar owns inline flex allocation: tabs shrink and scroll, an adjacent trailing action follows the tab strip, and the end action stays pinned at the far edge; leading, trailing, and end actions do not shrink."
+        ]
       },
       "delivery": {
         "browserImport": "@kerfjs/ui/tab-bar",
@@ -2582,7 +2740,8 @@
         "kui-tab-bar",
         "kui-tab-bar__leading",
         "kui-tab-bar__tabs",
-        "kui-tab-bar__trailing"
+        "kui-tab-bar__trailing",
+        "kui-tab-bar__end"
       ],
       "publicTokens": [
         "--kui-tab-bar-background",
@@ -3048,7 +3207,7 @@
     },
     {
       "id": "feedback",
-      "name": "Feedback composition",
+      "name": "Feedback",
       "category": "Feedback",
       "kind": "composition",
       "source": "kerf",
@@ -3125,6 +3284,7 @@
       "source": "kerf",
       "description": "Polite status and assertive alert feedback with semantic tones, plus non-status pop emphasis for featured or novel content.",
       "uses": [
+        "badge",
         "lucide-icon"
       ],
       "purpose": "Present persistent inline feedback or attractive non-status emphasis with a named semantic tone.",
@@ -3191,7 +3351,6 @@
       "publicClasses": [
         "kui-state-banner",
         "kui-state-banner__action",
-        "kui-state-banner__badge",
         "kui-state-banner__copy",
         "kui-state-banner__detail",
         "kui-state-banner__icon"
@@ -3223,8 +3382,6 @@
         "--kui-state-banner-action-background",
         "--kui-state-banner-action-hover-background",
         "--kui-state-banner-background",
-        "--kui-state-banner-badge-background",
-        "--kui-state-banner-badge-foreground",
         "--kui-state-banner-border",
         "--kui-state-banner-danger-background",
         "--kui-state-banner-danger-border",