@kerfjs/ui 5.0.0-beta.7 → 5.0.0-beta.9

package/README.md

@@ -23,9 +23,9 @@ npm install kerfjs @kerfjs/ui
 ```
 
 ```tsx
-import { MenuItem } from '@kerfjs/ui/menu-item';
-import { MenuHeader } from '@kerfjs/ui/menu-header';
-import { MenuActionRow } from '@kerfjs/ui/menu-action-row';
+import { ListItem } from '@kerfjs/ui/list-item';
+import { ListHeader } from '@kerfjs/ui/list-header';
+import { ListActionRow } from '@kerfjs/ui/list-action-row';
 import { Toolbar } from '@kerfjs/ui/toolbar';
 import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
 import { ToolbarText } from '@kerfjs/ui/toolbar-text';
@@ -33,7 +33,7 @@ import { ToolbarText } from '@kerfjs/ui/toolbar-text';
 mount(root, () => <>
   <Toolbar label="Document" leading={<ToolbarControlGroup appearance="borderless" single><ToolbarText text="Notes" /></ToolbarControlGroup>} />
   <section>
-    <MenuHeader
+    <ListHeader
       label="Workspace"
       action="show-workspace-actions"
       actionLabel="Workspace actions"
@@ -45,13 +45,13 @@ mount(root, () => <>
         'aria-haspopup': 'dialog',
       }}
     />
-    <MenuItem
+    <ListItem
       action="open-notes"
       label="Notes"
       selected
       rootAttributes={{ 'data-command-color': 'blue', 'data-drop-status': 'ready' }}
     />
-    <MenuActionRow
+    <ListActionRow
       action="open-file"
       itemId="src/main.ts"
       label="src/main.ts"
@@ -66,17 +66,17 @@ mount(root, () => <>
 
 Components return Kerf `SafeHtml`. They do not own application state or attach transient listeners. Actions are stable `data-action` hooks; the application wires them once with `delegate()` or `delegateActions()` and retains the disposer.
 
-`MenuItem.rootAttributes`, `MenuHeader.rootAttributes`,
-`MenuActionRow.rootAttributes`, and `AppTab.rootAttributes` carry typed
+`ListItem.rootAttributes`, `ListHeader.rootAttributes`,
+`ListActionRow.rootAttributes`, and `AppTab.rootAttributes` carry typed
 application `data-*` metadata without
-teaching the package domain fields. `MenuHeader.triggerAttributes` and
-`MenuActionRow.trailingActionAttributes` additionally support native popover
+teaching the package domain fields. `ListHeader.triggerAttributes` and
+`ListActionRow.trailingActionAttributes` additionally support native popover
 target and relationship attributes. Roles and component-owned action, selection,
 disclosure, naming, disabled, and icon semantics remain protected props; an
 isolated `role="menuitem"` is not an extension shortcut.
 The slots are also filtered at runtime, so structurally widened objects and
 JavaScript callers cannot bypass those protections with case-variant names.
-`MenuItem.trailing` is dormant metadata. Use `MenuActionRow` when a row needs
+`ListItem.trailing` is dormant metadata. Use `ListActionRow` when a row needs
 sibling primary and trailing native-button actions with independent names,
 disabled states, focus, and click ownership. Its `label`, `icon`, and
 `trailingActionIcon` slots are dormant content and must not contain controls.
@@ -99,9 +99,9 @@ as a `New` marker.
 | `Toolbar` | `@kerfjs/ui/toolbar` | `@kerfjs/ui/toolbar.css` |
 | `ToolbarControlGroup` | `@kerfjs/ui/toolbar-control-group` | `@kerfjs/ui/toolbar-control-group.css` |
 | `ToolbarText` | `@kerfjs/ui/toolbar-text` | `@kerfjs/ui/toolbar-text.css` |
-| `MenuActionRow` | `@kerfjs/ui/menu-action-row` | `@kerfjs/ui/menu-action-row.css` |
-| `MenuItem` | `@kerfjs/ui/menu-item` | `@kerfjs/ui/menu-item.css` |
-| `MenuHeader` | `@kerfjs/ui/menu-header` | `@kerfjs/ui/menu-header.css` |
+| `ListActionRow` | `@kerfjs/ui/list-action-row` | `@kerfjs/ui/list-action-row.css` |
+| `ListItem` | `@kerfjs/ui/list-item` | `@kerfjs/ui/list-item.css` |
+| `ListHeader` | `@kerfjs/ui/list-header` | `@kerfjs/ui/list-header.css` |
 | Pane, content, and navigation composition | — | `@kerfjs/ui/layout.css` |
 | `ResizableRegion` | `@kerfjs/ui/resizable-region` | `@kerfjs/ui/resizable-region.css` |
 | `wireResizableRegions` | `@kerfjs/ui/wire-resizable-regions` | — |
@@ -135,14 +135,14 @@ scale of `.5` through `--kui-disclosure-icon-scale`. Author replacement
 transform is applied. Direction changes take the shortest rotation path; a
 180-degree closed-to-open tie uses counterclockwise rotation.
 
-`MenuHeader` supplies that production `DisclosureArrow` automatically when
+`ListHeader` supplies that production `DisclosureArrow` automatically when
 `toggle` is true and `actionIcon` is omitted. Keep `expanded` synchronized with
 real controlled content and preserve the button's stable label; ordinary
 navigation must not display a disclosure arrow. A custom `actionIcon` remains
 an escape hatch and replaces the default arrow entirely. The header fills its
 available inline width, keeping a separate action at the logical end in a 44px
 target. Its visible action glyph defaults to 18px through
-`--kui-menu-header-action-icon-size`.
+`--kui-list-header-action-icon-size`.
 
 ## Machine-readable catalog
 
@@ -205,9 +205,9 @@ Add `.kui-content` to make its major children a vertical stack with 24px gaps.
   <div class="kui-pane__toolbar"><Toolbar label="Workspace" ... /></div>
   <nav class="kui-pane__content kui-content">
     <section>
-      <MenuHeader label="Workspace" count={3} countLabel="3 workspaces" />
-      <MenuItem action="open" label="Inbox" icon={inboxIcon} />
-      <MenuItem action="open" label="Drafts" />
+      <ListHeader label="Workspace" count={3} countLabel="3 workspaces" />
+      <ListItem action="open" label="Inbox" icon={inboxIcon} />
+      <ListItem action="open" label="Drafts" />
     </section>
     <div class="kui-content-item">Workspace details</div>
   </nav>
@@ -217,7 +217,7 @@ Add `.kui-content` to make its major children a vertical stack with 24px gaps.
 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
-background without changing layout. `MenuHeader` follows the same rule while
+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.
 

package/ai/component-catalog.json

@@ -488,7 +488,9 @@
         "small",
         "placeholder (loading)"
       ],
-      "accessibility": [],
+      "accessibility": [
+        "Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title."
+      ],
       "delivery": {
         "browserImport": "@kerfjs/ui/toolbar-text",
         "manualCssImport": "@kerfjs/ui/toolbar-text.css",
@@ -614,11 +616,13 @@
         "optional summary",
         "icon",
         "actions",
-        "placeholder (loading)"
+        "placeholder (loading)",
+        "page heading (headingLevel)"
       ],
       "accessibility": [
         "Connect the title id and any provided summary id to the dialog or panel host.",
-        "Pass the trailing actions as a labeled ToolbarControlGroup when the group needs an accessible name."
+        "Pass the trailing actions as a labeled ToolbarControlGroup when the group needs an accessible name.",
+        "For a page/view title pass headingLevel (usually 1) so the title exposes role=heading + aria-level as a heading landmark; omit it for a dialog title, which is referenced via aria-labelledby to titleId."
       ],
       "delivery": {
         "browserImport": "@kerfjs/ui/panel-header",
@@ -717,21 +721,21 @@
       }
     },
     {
-      "id": "menu",
-      "name": "Menu composition",
+      "id": "list",
+      "name": "List composition",
       "category": "Navigation",
       "kind": "composition",
       "source": "kerf",
       "description": "Navigation rows and section headers composed as ordinary content items inside a pane.",
       "uses": [
-        "menu-header",
-        "menu-action-row",
-        "menu-item"
+        "list-header",
+        "list-action-row",
+        "list-item"
       ],
-      "purpose": "Compose navigation with the same pane, content stack, item, and toolbar geometry used throughout the application, including a controlled MenuHeader disclosure only when it reveals real content.",
+      "purpose": "Compose navigation with the same pane, content stack, item, and toolbar geometry used throughout the application, including a controlled ListHeader disclosure only when it reveals real content.",
       "publicExports": [],
       "useWhen": [
-        "Compose navigation sections in a .kui-content stack, using MenuHeader, MenuItem, and MenuActionRow children plus optional .kui-content-item surfaces."
+        "Compose navigation sections in a .kui-content stack, using ListHeader, ListItem, and ListActionRow children plus optional .kui-content-item surfaces."
       ],
       "avoidWhen": [
         "Do not add sidebar-specific wrapper padding or use the pattern for unrelated inline controls.",
@@ -751,8 +755,8 @@
         "pane toolbar or footer"
       ],
       "accessibility": [
-        "Use native links for link navigation, retain MenuItem button semantics for actions, and keep standalone header and toolbar actions at least 44px square.",
-        "A MenuHeader disclosure controls real content, keeps a stable accessible name and aria-expanded state, and uses the production DisclosureArrow visual."
+        "Use native links for link navigation, retain ListItem button semantics for actions, and keep standalone header and toolbar actions at least 44px square.",
+        "A ListHeader disclosure controls real content, keeps a stable accessible name and aria-expanded state, and uses the production DisclosureArrow visual."
       ],
       "delivery": {
         "manualCssImport": "@kerfjs/ui/layout.css",
@@ -773,14 +777,14 @@
         "--kui-layout-rounded-radius"
       ],
       "links": {
-        "catalogRoute": "?component=menu",
+        "catalogRoute": "?component=list",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#correct-composition-and-duplicated-markup-trap"
       }
     },
     {
-      "id": "menu-header",
-      "name": "MenuHeader",
+      "id": "list-header",
+      "name": "ListHeader",
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
@@ -791,7 +795,7 @@
       ],
       "purpose": "Fill the available section width while splitting a dormant title and mutually exclusive semantic count or legacy badge from an optional logical-end 44px action with an 18px visual, or render that title cluster as a disclosure button with a default production DisclosureArrow.",
       "publicExports": [
-        "MenuHeader"
+        "ListHeader"
       ],
       "useWhen": [
         "Label a navigation section with an optional semantic count, non-count badge, action, or disclosure state; toggle mode supplies an 18px DisclosureArrow unless actionIcon replaces it."
@@ -828,22 +832,22 @@
         "The application controls and updates disclosure state and the revealed content; the default DisclosureArrow mirrors expanded while the button name stays stable. triggerAttributes can describe the controlled relationship but cannot replace the owned accessible name or expanded state."
       ],
       "delivery": {
-        "browserImport": "@kerfjs/ui/menu-header",
-        "manualCssImport": "@kerfjs/ui/menu-header.css",
+        "browserImport": "@kerfjs/ui/list-header",
+        "manualCssImport": "@kerfjs/ui/list-header.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-menu-header",
-        "kui-menu-header__action",
-        "kui-menu-header__action-layer",
-        "kui-menu-header__badge",
-        "kui-menu-header__count",
-        "kui-menu-header__label",
-        "kui-menu-header__title",
-        "kui-menu-header__toggle"
+        "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",
@@ -851,24 +855,24 @@
         "--kui-color-neutral-on-quiet",
         "--kui-focus-ring",
         "--kui-font-xs",
-        "--kui-menu-header-action-icon-size",
-        "--kui-menu-header-color",
+        "--kui-list-header-action-icon-size",
+        "--kui-list-header-color",
         "--kui-layout-inline-margin",
         "--kui-layout-item-gap",
         "--kui-layout-item-padding",
         "--kui-layout-pill-radius",
-        "--kui-menu-header-count-font-size",
-        "--kui-menu-header-hover-background"
+        "--kui-list-header-count-font-size",
+        "--kui-list-header-hover-background"
       ],
       "links": {
-        "catalogRoute": "?component=menu-header",
+        "catalogRoute": "?component=list-header",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
     {
-      "id": "menu-action-row",
-      "name": "MenuActionRow",
+      "id": "list-action-row",
+      "name": "ListActionRow",
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
@@ -878,17 +882,17 @@
       ],
       "purpose": "Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.",
       "publicExports": [
-        "MenuActionRow"
+        "ListActionRow"
       ],
       "useWhen": [
         "A navigation or item row needs both a primary selectable action and an independently focusable trailing action."
       ],
       "avoidWhen": [
-        "Use MenuItem when trailing content is dormant metadata; use AppTab only for tablist semantics and ToolbarControlGroup only for toolbar controls."
+        "Use ListItem when trailing content is dormant metadata; use AppTab only for tablist semantics and ToolbarControlGroup only for toolbar controls."
       ],
       "alternatives": [
         {
-          "id": "menu-item",
+          "id": "list-item",
           "relationship": "nearest",
           "when": "Trailing content is noninteractive."
         },
@@ -915,22 +919,22 @@
       ],
       "accessibility": [
         "The noninteractive root contains two sibling native buttons in primary-then-trailing focus order; each button has its own action, item identity, accessible name, and disabled state.",
-        "Selection semantics are exposed only by the primary button; label, icon, and trailingActionIcon are dormant SafeHtml and must not contain interactive descendants; never place an interactive descendant in MenuItem.trailing."
+        "Selection semantics are exposed only by the primary button; label, icon, and trailingActionIcon are dormant SafeHtml and must not contain interactive descendants; never place an interactive descendant in ListItem.trailing."
       ],
       "delivery": {
-        "browserImport": "@kerfjs/ui/menu-action-row",
-        "manualCssImport": "@kerfjs/ui/menu-action-row.css",
+        "browserImport": "@kerfjs/ui/list-action-row",
+        "manualCssImport": "@kerfjs/ui/list-action-row.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-menu-action-row",
-        "kui-menu-action-row__icon",
-        "kui-menu-action-row__label",
-        "kui-menu-action-row__primary",
-        "kui-menu-action-row__trailing-action"
+        "kui-list-action-row",
+        "kui-list-action-row__icon",
+        "kui-list-action-row__label",
+        "kui-list-action-row__primary",
+        "kui-list-action-row__trailing-action"
       ],
       "publicTokens": [
         "--kui-color-brand-border-quiet",
@@ -946,25 +950,25 @@
         "--kui-layout-item-padding",
         "--kui-layout-rounded-radius",
         "--kui-radius-pill",
-        "--kui-menu-action-row-background",
-        "--kui-menu-action-row-border",
-        "--kui-menu-action-row-color",
-        "--kui-menu-action-row-hover-background",
-        "--kui-menu-action-row-hover-border",
-        "--kui-menu-action-row-selected-background",
-        "--kui-menu-action-row-selected-border",
-        "--kui-menu-action-row-selected-color",
-        "--kui-menu-action-row-trailing-hover-background"
+        "--kui-list-action-row-background",
+        "--kui-list-action-row-border",
+        "--kui-list-action-row-color",
+        "--kui-list-action-row-hover-background",
+        "--kui-list-action-row-hover-border",
+        "--kui-list-action-row-selected-background",
+        "--kui-list-action-row-selected-border",
+        "--kui-list-action-row-selected-color",
+        "--kui-list-action-row-trailing-hover-background"
       ],
       "links": {
-        "catalogRoute": "?component=menu-action-row",
+        "catalogRoute": "?component=list-action-row",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
     {
-      "id": "menu-item",
-      "name": "MenuItem",
+      "id": "list-item",
+      "name": "ListItem",
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
@@ -974,17 +978,17 @@
       ],
       "purpose": "Selectable, disabled, trailing, and multiline navigation rows.",
       "publicExports": [
-        "MenuItem"
+        "ListItem"
       ],
       "useWhen": [
         "Render a selectable, disabled, trailing, or multiline sidebar/navigation action row."
       ],
       "avoidWhen": [
-        "Do not use for an ordinary inline link, form button, isolated ARIA menuitem, or an interactive trailing action; use MenuActionRow for sibling row actions."
+        "Do not use for an ordinary inline link, form button, isolated ARIA menuitem, or an interactive trailing action; use ListActionRow for sibling row actions."
       ],
       "alternatives": [
         {
-          "id": "menu-action-row",
+          "id": "list-action-row",
           "relationship": "nearest",
           "when": "The trailing region must be independently interactive."
         }
@@ -1008,18 +1012,18 @@
         "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."
       ],
       "delivery": {
-        "browserImport": "@kerfjs/ui/menu-item",
-        "manualCssImport": "@kerfjs/ui/menu-item.css",
+        "browserImport": "@kerfjs/ui/list-item",
+        "manualCssImport": "@kerfjs/ui/list-item.css",
         "sideEffects": [
           "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-menu-item",
-        "kui-menu-item__icon",
-        "kui-menu-item__label",
-        "kui-menu-item__trailing"
+        "kui-list-item",
+        "kui-list-item__icon",
+        "kui-list-item__label",
+        "kui-list-item__trailing"
       ],
       "publicTokens": [
         "--kui-color-brand-fill-normal",
@@ -1028,17 +1032,17 @@
         "--kui-color-neutral-on-normal",
         "--kui-color-neutral-on-quiet",
         "--kui-focus-ring",
-        "--kui-menu-item-color",
-        "--kui-menu-item-hover-background",
-        "--kui-menu-item-selected-background",
-        "--kui-menu-item-selected-color",
+        "--kui-list-item-color",
+        "--kui-list-item-hover-background",
+        "--kui-list-item-selected-background",
+        "--kui-list-item-selected-color",
         "--kui-layout-inline-margin",
         "--kui-layout-item-gap",
         "--kui-layout-item-padding",
         "--kui-layout-rounded-radius"
       ],
       "links": {
-        "catalogRoute": "?component=menu-item",
+        "catalogRoute": "?component=list-item",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
@@ -4358,8 +4362,8 @@
         "toolbar",
         "toolbar-text",
         "toolbar-control-group",
-        "menu-header",
-        "menu-item",
+        "list-header",
+        "list-item",
         "panel-header",
         "resize",
         "value-table",
@@ -4399,8 +4403,8 @@
       "source": "kerf",
       "purpose": "Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.",
       "uses": [
-        "menu-header",
-        "menu-item",
+        "list-header",
+        "list-item",
         "toolbar",
         "toolbar-control-group"
       ],
@@ -4469,16 +4473,16 @@
       }
     },
     {
-      "id": "recipe-master-detail-dialog",
-      "name": "Master-detail dialog",
+      "id": "recipe-list-detail-dialog",
+      "name": "List-detail dialog",
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
       "purpose": "Production modal containing a PanelHeader, navigable record master list, and ValueTable detail.",
       "uses": [
         "panel-header",
-        "menu-header",
-        "menu-item",
+        "list-header",
+        "list-item",
         "value-table",
         "wa-dialog",
         "wa-button"
@@ -4505,9 +4509,9 @@
         ]
       },
       "links": {
-        "catalogRoute": "?component=recipe-master-detail-dialog",
-        "documentation": "docs/recipes.md#master-detail-dialog",
-        "recipe": "docs/recipes.md#master-detail-dialog"
+        "catalogRoute": "?component=recipe-list-detail-dialog",
+        "documentation": "docs/recipes.md#list-detail-dialog",
+        "recipe": "docs/recipes.md#list-detail-dialog"
       }
     },
     {
@@ -4643,8 +4647,8 @@
       "source": "kerf",
       "purpose": "A push/pop navigation stack drill-down with animated slides and a live device class.",
       "uses": [
-        "menu-header",
-        "menu-item",
+        "list-header",
+        "list-item",
         "lucide-icon",
         "layout"
       ],
@@ -4673,6 +4677,49 @@
         "documentation": "docs/recipes.md#navigation-stack",
         "recipe": "docs/recipes.md#navigation-stack"
       }
+    },
+    {
+      "id": "recipe-loading-inspector",
+      "name": "Loading inspector",
+      "category": "Recipes",
+      "kind": "recipe",
+      "source": "kerf",
+      "purpose": "A record inspector whose per-record values load asynchronously \u2014 every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.",
+      "uses": [
+        "panel-header",
+        "value-table",
+        "select",
+        "segmented-control",
+        "list-item",
+        "state-banner",
+        "skeleton",
+        "lucide-icon"
+      ],
+      "useWhen": [
+        "A detail or inspector view must render its real chrome while its per-record values are still loading, then swap to the populated record without duplicating markup."
+      ],
+      "avoidWhen": [
+        "Do not hand-build a separate empty-state layout, and do not use it for known progress \u2014 use LoadingSpinner for that."
+      ],
+      "appOwns": [
+        "loading lifecycle",
+        "which values are unknown",
+        "fetching, transport, and domain data"
+      ],
+      "accessibility": [
+        "Each component marks itself aria-busy and disables its own controls while loading; the composition keeps labels and structure stable across the transition."
+      ],
+      "delivery": {
+        "sideEffects": [
+          "lazy-recipe-css",
+          "individual-custom-element-registration"
+        ]
+      },
+      "links": {
+        "catalogRoute": "?component=recipe-loading-inspector",
+        "documentation": "docs/recipes.md#loading-inspector",
+        "recipe": "docs/recipes.md#loading-inspector"
+      }
     }
   ]
 }