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

package/README.md

@@ -168,8 +168,8 @@ The same property-specific boundary applies beyond spacing: use `flex()` (or a
 finite keyword) for `Row.flex`, `Grid.flex`, and `List.flex`; length builders and intrinsic-size keywords for
 `Skeleton.width`/`height`; length builders for `Skeleton.radius`; and
 a foreground color for `SelectChoice.color` — `uiColor()` with a foreground
-token such as `success-on-quiet`, or `foregroundColorVar()` (fill aliases such
-as `uiColor('success')` are rejected). These grammars are not
+token such as `success-on-quiet`, or `foregroundColorVar()` (fill tokens such
+as `uiColor('success-fill-quiet')` are rejected). These grammars are not
 interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 `style` declarations; use `className`, public tokens, and component props.
 
@@ -184,6 +184,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `ToolbarControlGroup`, `ToolbarActionLink`                          | `@kerfjs/ui/toolbar-control-group`      | `@kerfjs/ui/toolbar-control-group.css` |
 | `DialogSurface`, `PopupSurface`                                     | `@kerfjs/ui/surface-scaffold`           | `@kerfjs/ui/surface-scaffold.css`      |
 | `FloatingToolbar`                                                   | `@kerfjs/ui/floating-toolbar`           | `@kerfjs/ui/floating-toolbar.css`      |
+| `PopupMenu` (register with `@kerfjs/ui/popup-menu/register`)        | `@kerfjs/ui/popup-menu`                 | `@kerfjs/ui/popup-menu.css`            |
 | `ToolbarText`                                                       | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`          |
 | `Text`                                                              | `@kerfjs/ui/text`                       | `@kerfjs/ui/text.css`                  |
 | `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                  |
@@ -196,6 +197,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `ListHeader`                                                        | `@kerfjs/ui/list-header`                | `@kerfjs/ui/list-header.css`           |
 | `ListInsetControl`                                                  | `@kerfjs/ui/list-inset-control`         | `@kerfjs/ui/list-inset-control.css`    |
 | `ListInsetText`                                                     | `@kerfjs/ui/list-inset-text`            | `@kerfjs/ui/list-inset-text.css`       |
+| `ContentItem`                                                       | `@kerfjs/ui/content-item`               | `@kerfjs/ui/content-item.css`          |
 | `Pane`                                                              | `@kerfjs/ui/pane`                       | `@kerfjs/ui/pane.css`                  |
 | `NavStack`                                                          | `@kerfjs/ui/nav-stack`                  | `@kerfjs/ui/nav-stack.css`             |
 | `wireNavStack`                                                      | `@kerfjs/ui/wire-nav-stack`             | —                                      |
@@ -246,11 +248,11 @@ onto another trailing-aligned row under every `responsive` policy, and a
 same way. Wrapping keeps every command visible at its full 44px target without
 moving focus or DOM identity. When a product wants fewer visible commands at
 narrow widths, it chooses them: render a lower-priority command inside an
-app-owned "More" popup menu (a `single` group around a `wa-dropdown`).
+app-owned "More" `PopupMenu` (in a `single` group with `nestedDropdown`).
 
-`DisclosureArrow` defaults to an 18px root-scaled decorative visual. Override
-`--kui-disclosure-arrow-size` at the narrowest useful scope when a consumer
-needs another size; the owning control still supplies interaction, naming, and
+`DisclosureArrow` defaults to an 18px root-scaled decorative visual. Pass a
+typed `size` (for example `size={remify(24)}` from `@kerfjs/ui/css-values`)
+when a consumer needs another size; the owning control still supplies interaction, naming, and
 expanded state. Kerf `Select` retains its independent Web Awesome expand-glyph
 scale of `.5` through `--kui-disclosure-icon-scale`. Author replacement
 `DisclosureArrow` icon content facing right before its configured direction
@@ -473,14 +475,15 @@ Add `.kui-content` to make its major children a vertical stack with 24px gaps.
       <ListItem action="open" label="Inbox" icon={inboxIcon} />
       <ListItem action="open" label="Drafts" />
     </section>
-    <div class="kui-content-item">Workspace details</div>
+    <ContentItem>Workspace details</ContentItem>
   </nav>
 </aside>
 ```
 
-Ordinary children use `.kui-content-item`: 8px inline margin, a real 1px border
-(transparent by default), 8px padding, and 12px rounded corners. The pill
-modifier uses a 22px radius. A component can expose a transparent border or
+Ordinary children use `ContentItem` (`@kerfjs/ui/content-item`): 8px inline
+margin, a real 1px border (transparent by default), 8px padding, and 12px
+rounded corners. `shape="pill"` uses a 22px radius, and `frame="framed"` paints
+the neutral border only when the item marks a real distinction. A component can expose a transparent border or
 background without changing layout. `ListHeader` follows the same rule while
 keeping its dormant title and count-or-badge cluster separate from its optional
 44px action.
@@ -645,7 +648,7 @@ import "@kerfjs/ui/webawesome.css";
 import "@kerfjs/ui/select/register";
 ```
 
-That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it.
+That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it. `PopupMenu` follows the same rule: import `@kerfjs/ui/popup-menu/register` once to register the dropdown, item, button, and divider elements it renders. Either registration also installs help tags: an icon-only Select, PopupMenu, or `aria-label`-named `<button>` in a `ToolbarControlGroup` shows its name in an `aria-hidden` tooltip on hover and keyboard focus. A toolbar with icon-only buttons but neither control imports `@kerfjs/ui/help-tags/register`, which registers only the tooltip.
 Use `label` for a visible label or `ariaLabel` for a visually hidden name. A
 nonempty visible label takes precedence when both are supplied. Kerf names the
 actual shadow combobox without adding visible label spacing; this also works

package/ai/compile-time-contracts-v1.json

@@ -79,7 +79,7 @@
       "id": "KUI-T010",
       "publicImport": "@kerfjs/ui",
       "symbols": [
-        "DividerSides",
+        "Sides",
         "StateBannerUrgency",
         "TabActivation",
         "TextVariant",
@@ -89,7 +89,7 @@
         "ToolbarControlGroupTone"
       ],
       "kind": "finite-vocabulary",
-      "summary": "Finite public variant vocabularies, including canonical divider-edge combinations, are named exported unions rather than anonymous string sets."
+      "summary": "Finite public variant vocabularies, including canonical edge combinations, are named exported unions rather than anonymous string sets."
     },
     {
       "id": "KUI-T011",

package/ai/component-catalog-v2.json

@@ -44,7 +44,7 @@
       },
       "accessibility": {
         "obligations": [
-          "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."
         ]
       },
@@ -139,7 +139,19 @@
           "The arrow is decorative; expose expanded state through aria-expanded on its owning control and keep that control's accessible name stable."
         ]
       },
-      "cssValueProps": [],
+      "cssValueProps": [
+        {
+          "path": "size",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["size={remify(24)}"]
+        }
+      ],
       "boundaries": {
         "rootClass": "kui-disclosure-arrow",
         "publicClasses": ["kui-disclosure-arrow"],
@@ -306,18 +318,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"
@@ -434,8 +434,6 @@
         "rootClass": "kui-content",
         "publicClasses": [
           "kui-content",
-          "kui-content-item",
-          "kui-content-item--pill",
           "kui-control-cluster",
           "kui-inline-metadata",
           "kui-scroll-owner"
@@ -614,6 +612,16 @@
           "id": "per-view bottom toolbar content or a persistent fallback",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "per-view leading, center, and trailing top-toolbar groups",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "top-toolbar configuration, title size, and heading level",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -655,7 +663,8 @@
       },
       "accessibility": {
         "obligations": [
-          "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."
         ]
@@ -671,11 +680,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",
@@ -736,6 +742,16 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "optional list collapse state and its restore control",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "compact list and detail toolbar groups and toolbar configuration",
+          "owner": "application",
+          "required": false
+        },
         { "id": "back action", "owner": "application", "required": false }
       ],
       "wiring": {
@@ -832,6 +848,11 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "tab badge counts or dots and their localized badgeLabel phrases",
+          "owner": "application",
+          "required": false
+        },
         {
           "id": "routing and persistence",
           "owner": "application",
@@ -864,7 +885,8 @@
       "accessibility": {
         "obligations": [
           "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."
         ]
       },
       "cssValueProps": [],
@@ -877,6 +899,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": []
@@ -1007,7 +1030,8 @@
           "--kui-workbench-overlay-max-width",
           "--kui-workbench-overlay-max-height",
           "--kui-workbench-restore-inset",
-          "--kui-workbench-restore-z"
+          "--kui-workbench-restore-z",
+          "--kui-workbench-overlay-dismiss-margin"
         ]
       },
       "diagnostics": [],
@@ -1282,7 +1306,7 @@
           "kui-toolbar__trailing"
         ],
         "publicTokens": [
-          "--kui-color-border",
+          "--kui-color-neutral-border-normal",
           "--kui-font-sans",
           "--kui-toolbar-divider-color"
         ]
@@ -1346,7 +1370,8 @@
       },
       "accessibility": {
         "obligations": [
-          "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."
         ]
       },
       "cssValueProps": [],
@@ -1473,7 +1498,19 @@
           "Give the toolbar an accessible name (label is required — it exposes role=\"toolbar\")."
         ]
       },
-      "cssValueProps": [],
+      "cssValueProps": [
+        {
+          "path": "inset",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["inset={space(\"xs\")}"]
+        }
+      ],
       "boundaries": {
         "rootClass": "kui-floating-toolbar",
         "publicClasses": ["kui-floating-toolbar"],
@@ -1597,7 +1634,7 @@
         "rootClass": "kui-text",
         "publicClasses": ["kui-text"],
         "publicTokens": [
-          "--kui-color-danger-text",
+          "--kui-color-danger-on-quiet",
           "--kui-color-text-quiet",
           "--kui-font-mono",
           "--kui-font-xs",
@@ -1696,7 +1733,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",
@@ -2070,7 +2107,7 @@
         "rootClass": "kui-list",
         "publicClasses": ["kui-list"],
         "publicTokens": [
-          "--kui-color-border",
+          "--kui-color-neutral-border-normal",
           "--kui-layout-item-gap",
           "--kui-list-divider-color",
           "--kui-list-gap"
@@ -2412,11 +2449,83 @@
       "cssValueProps": [],
       "boundaries": {
         "rootClass": "kui-list-inset-text",
+        "publicClasses": ["kui-list-inset-text"],
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
+    {
+      "key": "@kerfjs/ui:content-item",
+      "package": "@kerfjs/ui",
+      "id": "content-item",
+      "name": "ContentItem",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        { "id": "the item content", "owner": "application", "required": false },
+        {
+          "id": "whether the item marks a real distinction that warrants a visible frame",
+          "owner": "application",
+          "required": false
+        },
+        { "id": "corner shape", "owner": "application", "required": false },
+        {
+          "id": "region semantics and accessible name",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "whether the item is a programmatic focus target",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "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."
+          ]
+        }
+      },
+      "accessibility": {
+        "obligations": [
+          "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."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-content-item",
         "publicClasses": [
-          "kui-list-inset-text",
-          "kui-list-inset-text--horizontal"
+          "kui-content-item",
+          "kui-content-item--pill",
+          "kui-content-item--framed"
         ],
-        "publicTokens": []
+        "publicTokens": [
+          "--kui-content-item-border",
+          "--kui-content-item-radius",
+          "--kui-content-item-background"
+        ]
       },
       "diagnostics": [],
       "provenance": {
@@ -2848,9 +2957,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",
@@ -2943,7 +3052,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",
@@ -3002,7 +3111,10 @@
           "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."
         ]
       },
       "cssValueProps": [
@@ -3034,8 +3146,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",
@@ -3055,6 +3165,63 @@
         "composition": "README.md#web-awesome-theme"
       }
     },
+    {
+      "key": "@kerfjs/ui:popup-menu",
+      "package": "@kerfjs/ui",
+      "id": "popup-menu",
+      "name": "PopupMenu",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "commands and their delegated actions",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "which items are enabled",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "reactions to the menu opening or closing",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["controls"],
+        "geometry": { "margin": "none", "border": "child", "padding": "child" }
+      },
+      "accessibility": {
+        "obligations": [
+          "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."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-popup-menu",
+        "publicClasses": ["kui-popup-menu", "kui-popup-menu__label"],
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:feedback",
       "package": "@kerfjs/ui",