@kerfjs/ui 5.0.0-beta.55 → 5.0.0-beta.56

package/ai/component-catalog.json

@@ -33,11 +33,11 @@
         "neutral, brand, pop, success, warning, or danger tone",
         "quiet, solid, or outline appearance",
         "pill or rounded shape",
-        "compact or default size",
+        "compact or default size, or a text-free dot (size: 'dot')",
         "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.",
+        "Badge is non-interactive. Supply label when visible content is abbreviated, and ariaHidden when it repeats an accessible name owned by the surrounding component. A text-free dot must take either label (exposed as an image) or ariaHidden, which the types enforce.",
         "Keep meaningful text visible because tone is supplementary."
       ],
       "geometry": {
@@ -133,6 +133,31 @@
       "publicExports": [
         "DisclosureArrow"
       ],
+      "cssValueProps": [
+        {
+          "path": "size",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "size={remify(24)}"
+          ]
+        }
+      ],
       "useWhen": [
         "Add a shortest-path rotating indicator to a control that owns open and closed state; author replacement icon content facing right before direction transforms are applied."
       ],
@@ -331,18 +356,6 @@
         "--kui-color-danger-on-normal",
         "--kui-color-danger-on-loud",
         "--kui-color-danger-on-fill",
-        "--kui-color-border",
-        "--kui-color-border-quiet",
-        "--kui-color-accent",
-        "--kui-color-accent-text",
-        "--kui-color-pop",
-        "--kui-color-pop-text",
-        "--kui-color-success",
-        "--kui-color-success-text",
-        "--kui-color-warning",
-        "--kui-color-warning-text",
-        "--kui-color-danger",
-        "--kui-color-danger-text",
         "--kui-focus-ring",
         "--kui-shadow-s",
         "--kui-shadow-l"
@@ -421,7 +434,9 @@
       "kind": "composition",
       "source": "kerf",
       "description": "Unpadded panes, 24px content stacks, and self-contained 8/1/8 content items for application layout boundaries.",
-      "uses": [],
+      "uses": [
+        "content-item"
+      ],
       "purpose": "Provide one reusable pane, toolbar, content stack, and content-item geometry across sidebars, main areas, and dialogs.",
       "publicExports": [],
       "useWhen": [
@@ -442,8 +457,6 @@
       "variants": [
         "toolbar + content",
         "toolbar + content + footer",
-        "rounded content item",
-        "pill content item",
         "hidden inline-start pane restored from main-toolbar leading",
         "hidden inline-end pane restored from main-toolbar trailing"
       ],
@@ -465,8 +478,6 @@
       "wiring": [],
       "publicClasses": [
         "kui-content",
-        "kui-content-item",
-        "kui-content-item--pill",
         "kui-control-cluster",
         "kui-inline-metadata",
         "kui-scroll-owner"
@@ -581,11 +592,14 @@
       "source": "kerf",
       "description": "A controlled one-pane navigation stack that keeps prior views mounted, slides content on push and pop, cross-fades per-view chrome, and moves/restores focus.",
       "uses": [
+        "toolbar",
+        "toolbar-control-group",
         "toolbar-text"
       ],
       "purpose": "Present a single linear or drill-down flow while preserving each prior view's state, scroll position, and place in the stack.",
       "publicExports": [
         "NavStackView",
+        "NavStackToolbarConfig",
         "NavStackProps",
         "NavStack"
       ],
@@ -614,17 +628,22 @@
         "view content and titles",
         "push and pop actions",
         "preferred initial focus targets when DOM order is insufficient",
-        "per-view bottom toolbar content or a persistent fallback"
+        "per-view bottom toolbar content or a persistent fallback",
+        "per-view leading, center, and trailing top-toolbar groups",
+        "top-toolbar configuration, title size, and heading level"
       ],
       "variants": [
         "single root view",
         "pushed detail view",
         "toolbar hidden",
+        "configured top toolbar",
+        "custom back icon or visible back text",
         "per-view bottom toolbar",
         "persistent bottom-toolbar fallback"
       ],
       "accessibility": [
-        "Give the stack region an accessible label and every back control a stable action label.",
+        "Give the stack region an accessible label and every back control a stable action label; visible backText names the control itself.",
+        "Set toolbarConfig.headingLevel when the view title is the page's or section's heading landmark.",
         "Use wireNavStack so each controlled push moves focus into the new top view and each pop restores the revealed view's remembered descendant.",
         "Mark a preferred initial heading or control with data-nav-focus when the first enabled focusable descendant is not the right target."
       ],
@@ -675,11 +694,8 @@
         "kui-nav-stack__chrome-copy",
         "kui-nav-stack__chrome-copy--bottom",
         "kui-nav-stack__chrome-copy--exiting",
-        "kui-nav-stack__lead",
-        "kui-nav-stack__back",
-        "kui-nav-stack__back-icon",
+        "kui-nav-stack__toolbar",
         "kui-nav-stack__title",
-        "kui-nav-stack__actions",
         "kui-nav-stack__viewport",
         "kui-nav-stack__view",
         "kui-nav-stack__view--entering",
@@ -709,7 +725,9 @@
       "publicExports": [
         "SplitView",
         "SplitViewProps",
-        "SplitViewResizable"
+        "SplitViewResizable",
+        "SplitViewCompactStack",
+        "SplitViewCompactViewToolbars"
       ],
       "useWhen": [
         "Selection in a primary list updates a related detail pane and both should remain visible on roomy device classes.",
@@ -736,13 +754,17 @@
         "selected item and detail-active state",
         "list and detail content",
         "optional list width and persistence",
+        "optional list collapse state and its restore control",
+        "compact list and detail toolbar groups and toolbar configuration",
         "back action"
       ],
       "variants": [
         "fixed roomy split",
         "resizable roomy split",
+        "collapsed resizable list with a restore control",
         "compact list",
-        "compact detail"
+        "compact detail",
+        "compact stack with configured toolbars"
       ],
       "accessibility": [
         "Give the overall split and both meaningful panes accessible labels.",
@@ -826,7 +848,9 @@
       "kind": "component",
       "source": "kerf",
       "description": "A controlled compact-device bottom tab scaffold that keeps every tab scene mounted so its navigation and scroll state survive selection changes.",
-      "uses": [],
+      "uses": [
+        "badge"
+      ],
       "purpose": "Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.",
       "publicExports": [
         "TabScaffoldTab",
@@ -856,17 +880,20 @@
       "appOwns": [
         "controlled active tab id",
         "tab labels, icons, and content",
+        "tab badge counts or dots and their localized badgeLabel phrases",
         "routing and persistence",
         "responsive replacement on larger device classes"
       ],
       "variants": [
         "text-only tabs",
         "icon and text tabs",
+        "badged tabs (count or text-free dot)",
         "one NavStack per tab"
       ],
       "accessibility": [
         "Give the tablist an accessible label and keep exactly the active tab in the sequential focus order.",
-        "Wire selection through the controlled active id while leaving inactive scenes mounted and hidden."
+        "Wire selection through the controlled active id while leaving inactive scenes mounted and hidden.",
+        "A tab badge is aria-hidden; supply badgeLabel so the tab's accessible name becomes \"<label>, <badgeLabel>\" (it defaults to the badge text). The dot form, badge: true, has no text, so its badgeLabel is required."
       ],
       "geometry": {
         "margin": "none",
@@ -897,6 +924,7 @@
         "kui-tab-scaffold__bar",
         "kui-tab-scaffold__tab",
         "kui-tab-scaffold__tab-icon",
+        "kui-tab-scaffold__tab-badge",
         "kui-tab-scaffold__tab-label"
       ],
       "publicTokens": [],
@@ -1309,7 +1337,7 @@
         "kui-toolbar__trailing"
       ],
       "publicTokens": [
-        "--kui-color-border",
+        "--kui-color-neutral-border-normal",
         "--kui-font-sans",
         "--kui-toolbar-divider-color"
       ],
@@ -1380,7 +1408,8 @@
         "contained avatar background on a single group or selected multi-button highlight"
       ],
       "accessibility": [
-        "Name the group when its relationship is not evident from context."
+        "Name the group when its relationship is not evident from context.",
+        "Name an icon-only button or link with aria-label, not title. Once any help-tag installer is imported (select/register, popup-menu/register, or help-tags/register), it shows an aria-hidden Web Awesome help tag repeating that name after a 500ms hover and at once on keyboard focus, hidden on a press and on Escape, and never joins aria-labelledby. A native title keeps the browser tooltip and gets no second tag."
       ],
       "geometry": {
         "margin": "none",
@@ -1515,6 +1544,31 @@
       "publicExports": [
         "FloatingToolbar"
       ],
+      "cssValueProps": [
+        {
+          "path": "inset",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "inset={space(\"xs\")}"
+          ]
+        }
+      ],
       "useWhen": [
         "Float a small cluster of controls (e.g. a drawer restore) over scrolling content without covering dialogs."
       ],
@@ -1713,7 +1767,7 @@
         "kui-text"
       ],
       "publicTokens": [
-        "--kui-color-danger-text",
+        "--kui-color-danger-on-quiet",
         "--kui-color-text-quiet",
         "--kui-font-mono",
         "--kui-font-xs",
@@ -1834,7 +1888,7 @@
         "kui-value-table__label"
       ],
       "publicTokens": [
-        "--kui-color-border",
+        "--kui-color-neutral-border-normal",
         "--kui-color-surface-lowered",
         "--kui-color-text",
         "--kui-color-text-quiet",
@@ -2468,7 +2522,7 @@
         "kui-list"
       ],
       "publicTokens": [
-        "--kui-color-border",
+        "--kui-color-neutral-border-normal",
         "--kui-layout-item-gap",
         "--kui-list-divider-color",
         "--kui-list-gap"
@@ -2900,8 +2954,7 @@
       ],
       "variants": [
         "all-side inset by default",
-        "top/right/bottom/left inset combinations",
-        "deprecated horizontalOnly compatibility alias for sides=\"rl\""
+        "top/right/bottom/left inset combinations"
       ],
       "accessibility": [
         "A layout wrapper only; it adds no role or name."
@@ -2920,8 +2973,7 @@
       },
       "wiring": [],
       "publicClasses": [
-        "kui-list-inset-text",
-        "kui-list-inset-text--horizontal"
+        "kui-list-inset-text"
       ],
       "publicTokens": [],
       "links": {
@@ -2930,6 +2982,97 @@
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
+    {
+      "id": "content-item",
+      "name": "ContentItem",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "One self-contained content child with the shared 8px margin + 1px border + 8px padding geometry, a typed frame, and a rounded or pill shape.",
+      "uses": [],
+      "purpose": "Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.",
+      "publicExports": [
+        "ContentItem"
+      ],
+      "useWhen": [
+        "An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.",
+        "A content item marks a real distinction and must read as visibly bounded: pass frame=\"framed\" (the border is always reserved, so geometry does not change).",
+        "A content item should follow a pill control's 22px radius: pass shape=\"pill\"."
+      ],
+      "avoidWhen": [
+        "Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.",
+        "Do not frame an item only to make it look contained; hierarchy comes from alignment, spacing, and type first.",
+        "Do not use it as a filled or lowered card; use SunkenPanel for a lowered surface.",
+        "Do not use it for bare text alone; use ListInsetText, which adds the same inset without claiming a surface."
+      ],
+      "alternatives": [
+        {
+          "id": "list-inset-text",
+          "relationship": "nearest",
+          "when": "Use ListInsetText when bare text only needs to align with neighboring content items."
+        },
+        {
+          "id": "sunken-panel",
+          "relationship": "nearest",
+          "when": "Use SunkenPanel for a lowered, filled surface around a vertical stack."
+        },
+        {
+          "id": "layout",
+          "relationship": "composes-with",
+          "when": "Place ContentItem children in a Pane or .kui-content stack, which owns the 24px major rhythm."
+        }
+      ],
+      "appOwns": [
+        "the item content",
+        "whether the item marks a real distinction that warrants a visible frame",
+        "corner shape",
+        "region semantics and accessible name",
+        "whether the item is a programmatic focus target"
+      ],
+      "variants": [
+        "unframed rounded item",
+        "framed rounded item",
+        "pill item",
+        "framed pill item",
+        "named focus-target region"
+      ],
+      "accessibility": [
+        "An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role=\"region\").",
+        "focusTarget makes the item a programmatic focus target (tabindex=\"-1\", never a tab stop), such as a NavStack view's data-nav-focus target.",
+        "The frame is decorative and never the only signal of state."
+      ],
+      "geometry": {
+        "margin": "self",
+        "border": "self",
+        "padding": "self",
+        "notes": [
+          "The 1px border is always reserved and transparent unless frame=\"framed\", so framed and unframed items share the same geometry."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/content-item",
+        "manualCssImport": "@kerfjs/ui/content-item.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-content-item",
+        "kui-content-item--pill",
+        "kui-content-item--framed"
+      ],
+      "publicTokens": [
+        "--kui-content-item-border",
+        "--kui-content-item-radius",
+        "--kui-content-item-background"
+      ],
+      "links": {
+        "catalogRoute": "?component=content-item",
+        "documentation": "docs/layout.md",
+        "recipe": "docs/layout.md#content-items"
+      }
+    },
     {
       "id": "application-tabs",
       "name": "Application tabs",
@@ -3412,9 +3555,9 @@
         "kui-token-search__trailing"
       ],
       "publicTokens": [
-        "--kui-color-accent",
-        "--kui-color-accent-text",
-        "--kui-color-border",
+        "--kui-color-brand-fill-normal",
+        "--kui-color-brand-on-quiet",
+        "--kui-color-neutral-border-normal",
         "--kui-color-text-link",
         "--kui-color-surface",
         "--kui-color-text",
@@ -3544,7 +3687,7 @@
         "kui-resizable-region__restore"
       ],
       "publicTokens": [
-        "--kui-color-border",
+        "--kui-color-neutral-border-normal",
         "--kui-color-neutral-on-quiet",
         "--kui-color-text-link",
         "--kui-focus-ring",
@@ -3571,9 +3714,10 @@
       "category": "Controls",
       "kind": "component",
       "source": "kerf",
-      "description": "Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.",
+      "description": "Controlled Web Awesome select with typed single or multiple values and form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.",
       "uses": [
         "lucide-icon",
+        "badge",
         "wa-select",
         "wa-option"
       ],
@@ -3643,13 +3787,18 @@
         "default or compact size",
         "label or icon-only selected presentation",
         "select- or group-owned focus ring",
-        "label maximum width and truncation"
+        "label maximum width and truncation",
+        "multiple selection",
+        "multiple icon-only filter trigger with a fixed triggerIcon"
       ],
       "accessibility": [
         "Verify the live value, standard events, focus, and rendered output.",
         "A nonempty label names the internal combobox; otherwise ariaLabel supplies a visually hidden label without adding control height, including custom selected content.",
         "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."
+        "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.",
+        "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."
       ],
       "geometry": {
         "margin": "none",
@@ -3677,8 +3826,6 @@
         "kui-select__icon"
       ],
       "publicTokens": [
-        "--kui-color-brand-fill-normal",
-        "--kui-color-brand-on-fill",
         "--kui-color-neutral-border-quiet",
         "--kui-color-neutral-on-quiet",
         "--kui-disclosure-icon-scale",
@@ -3740,7 +3887,8 @@
         "placement"
       ],
       "accessibility": [
-        "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. Web Awesome provides menu roles, arrow-key navigation, typeahead, and Escape."
+        "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. Web Awesome provides menu roles, arrow-key navigation, typeahead, and Escape.",
+        "Once registered, an icon-only trigger shows its label as an aria-hidden Web Awesome help tag after a 500ms hover and at once on keyboard focus; it hides while the menu is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip."
       ],
       "geometry": {
         "margin": "none",
@@ -7095,7 +7243,8 @@
         "toolbar",
         "toolbar-control-group",
         "lucide-icon",
-        "layout"
+        "layout",
+        "content-item"
       ],
       "useWhen": [
         "A workspace sidebar needs the shared toolbar/content/footer pane model, 24px major section rhythm, and 44px row and utility-action targets."
@@ -7368,7 +7517,8 @@
         "row",
         "text",
         "lucide-icon",
-        "layout"
+        "layout",
+        "content-item"
       ],
       "useWhen": [
         "A flow drills from a list into detail and back on one pane, at any device size or inside a dialog."
@@ -7466,7 +7616,8 @@
         "toolbar-text",
         "value-table",
         "lucide-icon",
-        "layout"
+        "layout",
+        "content-item"
       ],
       "useWhen": [
         "A rail or drawer must collapse and expand outside a full Workbench shell, keeping the app's collapsed signals, sizes, and content while the wire owns toggle, focus, the compact overlay, and persistence."