kerfjs 5.0.0-beta.54 → 5.0.0-beta.56

package/CHANGELOG.md

@@ -6,6 +6,457 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+- **`@kerfjs/ui` `Badge` has a text-free dot, and `TabScaffold` tabs can show
+  it.** `Badge` takes `size="dot"`: an 8px solid circle in the badge's tone,
+  with no children, appearance, or shape. Because a dot has no text, its props
+  require either a `label` (announced as an image, for example
+  `label="New activity"`) or `ariaHidden` when the owning component already
+  announces it. `TabScaffoldTab` accepts `badge: true` for the iOS tab-bar dot
+  (new content without a count), centered on the icon's top-trailing corner;
+  its `badgeLabel` is required and joins the tab's accessible name
+  ("Settings, Update available"). `BadgeTextProps` and `BadgeDotProps` are
+  exported from the root barrel.
+
+- **`@kerfjs/ui` `Toolbar` truncates the leading title instead of letting the
+  center zone cover it.** When a leading identity, a `center` group, and
+  trailing actions no longer fit one row, the center zone keeps its whole
+  content width and the leading title ends in an ellipsis. Previously the
+  center track could shrink below its group, which then painted over the
+  title — a pushed `NavStack` view with a center group did this at 390px. The
+  fix holds under every `responsive` policy and both `centerAlign` values, and
+  a toolbar that fits lays out exactly as before.
+
+- **`@kerfjs/ui` `ValueTableRow` keeps its value readable beside a long
+  label.** A long single-word label (such as `ConnectionStateBanner` in a
+  390px-wide table) no longer squeezes the value to 0px wide, where it wrapped
+  one character per line while the label ran underneath it. The label and value
+  now share the row as two content-sized columns: a short value stays whole on
+  one line, the label wraps at its spaces and ends an over-long word in an
+  ellipsis before the value, and when both are long they split the row.
+
+- **`@kerfjs/ui` pinned chrome can give way in a short pane.** `Pane` takes
+  `chromePlacement="auto"`: its header and footer stay pinned while the pane is
+  at least 480px (30rem) tall, and below that the whole pane scrolls as one
+  column so tall chrome never squeezes the content to nothing.
+  `WorkbenchChromePlacement` gains `"auto"` for `mainHeaderPlacement` /
+  `mainFooterPlacement`, and `Catalog` now defaults `headerPlacement` /
+  `footerPlacement` to `"auto"`. Its entry description is pinned under the
+  toolbar, which at 200% text size on a short window had left the preview 0px
+  tall.
+
+- **`@kerfjs/ui` `TabScaffold` tabs can show a badge.** Give a
+  `TabScaffoldTab` a `badge` (a count or short string) to show the iOS tab-bar
+  badge — a compact, solid danger `Badge` at the top-trailing corner of the
+  tab's icon. The badge is hidden from assistive technology; the tab's
+  accessible name becomes `"<label>, <badgeLabel>"` (for example
+  "Inbox, 3 unread"), with `badgeLabel` defaulting to the badge text. Tabs
+  without a badge are unchanged.
+
+- **`@kerfjs/ui` `ListItem` and `ListActionRow` labels stay out of the
+  trailing slot.** A long single-word primary label (such as a Catalog sidebar
+  entry named `ConnectionStateBanner` in a narrow rail) no longer runs
+  underneath trailing status text. Single-line rows now end the primary label
+  and description with a real ellipsis (previously the text was cut mid-glyph
+  with no "…"), and `multiline` rows break a word wider than the label column
+  onto the next line.
+
+- **Custom elements keep the `role` and `aria-*` they set on themselves across
+  re-renders.** Web components conventionally own their host's ARIA (Web
+  Awesome's `wa-option` sets `role="option"` / `aria-selected`, `wa-divider`
+  sets `role="separator"`; Shoelace and FAST do the same), but a template never
+  mentions them, so the morph and the keyed-list attribute fast path stripped
+  them on the next re-render. On any custom element (hyphenated tag), `role`
+  and `aria-*` are now element-owned like `open`: never removed just because
+  the template omits them. The template can still set or change them, a signal
+  binding set to `null` / `false` still removes them, and plain elements are
+  unchanged. Trade-off: omitting one from a static template no longer removes
+  it from a custom element — render an explicit value (`aria-pressed="false"`)
+  instead.
+
+- **`@kerfjs/ui` layout regions no longer slow edits to long lists inside
+  them.** The rule that clears the safe-area context for the children of a
+  Workbench main area or panel, SplitView list or detail, NavStack view,
+  TabScaffold scene, or CollapsiblePanel content made each child re-check the
+  region in Chromium on every DOM change. A 1000-row list placed directly in
+  one of these regions took about 46ms per style recalculation (2ms with the
+  list one level down), and now takes about 0.2ms. Layout and insets are
+  unchanged.
+
+- **`@kerfjs/ui` `CollapsiblePanel` no longer slows insertions into long
+  lists.** An expanded inline panel clears its screen edge for its siblings;
+  the rules that did so selected the siblings themselves
+  (`:has(~ panel)` and `panel ~ *`), which in Chromium made each row inserted
+  into or removed from a long list restyle the list's other rows — about
+  14.6ms instead of 0.2ms per insertion beside a 1000-row list. The panel's
+  container now carries a flag that a CSS style query reads, so a list pays
+  nothing. The edge still clears for the panel's siblings and returns when it
+  collapses; the one difference is that a sibling placed before a left panel
+  or after a right or bottom panel now loses the edge too.
+
+- **`@kerfjs/ui` restore corners and covered floating controls no longer slow
+  every style recalculation.** The `CollapsiblePanel` / `ResizableRegion`
+  restore-corner anchor scope (`:has(> restore) > * > * > *`) and the static
+  side-overlay covered flag (`:has(> open overlay) > :not(overlay)`) put a
+  universal selector after a `:has()` container, which in Chromium restyled
+  the children of every ancestor of each DOM change — about 85ms instead of
+  1ms per edit beside a 1000-row list. The drawer now publishes its anchor
+  only beside a restore control's container (or its work-area column), and
+  the covered flag is set on the overlay's container and cleared on its
+  overlay children. Restore-corner placement and covered-control hiding are
+  unchanged; a new CSS unit test rejects the costly `:has()` shapes.
+
+- **`@kerfjs/ui` adds `ContentItem`.** Import it from
+  `@kerfjs/ui/content-item` to render one self-contained pane child with the
+  shared 8px margin, 1px border, and 8px padding. Framing and shape are typed
+  props instead of hand-written modifier classes:
+  - `frame="framed"` paints the neutral border in the 1px the item always
+    reserves, so its geometry does not change (replacing
+    `class="kui-content-item kui-content-item--framed"`);
+  - `shape="pill"` selects the 22px radius.
+  - `ariaLabel` names a distinct region, and `focusTarget` makes the item a
+    programmatic focus target (`tabindex="-1"`), such as a NavStack view's
+    `data-nav-focus` target.
+
+  The `.kui-content-item` classes stay public for elements that must carry the
+  geometry themselves; their CSS now lives in `content-item.css`, which
+  `layout.css` still imports. There is no filled variant — use `SunkenPanel`
+  for a lowered surface. The catalog, demos, and recipes use the component.
+
+- **`@kerfjs/ui` icon-only toolbar buttons show the same help tag.** An
+  icon-only `<button>` or link inside a `ToolbarControlGroup`, named by
+  `aria-label` with no visible text, now shows the help tag icon-only Selects
+  and PopupMenus show, with the same 500ms hover delay, keyboard-focus-only
+  display, press/Escape dismissal, and quick scanning along a toolbar. The tag
+  is `aria-hidden` and never renames the button. A button with a native
+  `title`, or with its own Web Awesome tooltip, keeps that and gets no second
+  tag. The `select/register` and `popup-menu/register` imports install it; a
+  toolbar with icon-only buttons but neither control imports the new
+  `@kerfjs/ui/help-tags/register` subpath, which registers only the tooltip.
+
+- **`@kerfjs/ui` icon-only Select and PopupMenu triggers show a help tag.**
+  An icon-only `Select` (single or `multiple` with `triggerIcon`) and an
+  icon-only `PopupMenu` now show a Web Awesome tooltip naming the control on
+  hover (after 500ms) and on keyboard focus: a filter reads "Filter by label:
+  Bug, Docs", a single Select its name and current choice, a menu its `label`.
+  It hides while the popup is open, on a press, and on Escape. The tag repeats
+  the accessible name, so it is `aria-hidden` and never joins
+  `aria-labelledby`; screen readers still hear the name once. It is installed
+  by the existing `select/register` and `popup-menu/register` imports, needs no
+  props, and never appears for labeled Selects or text menu triggers.
+
+- **`@kerfjs/ui` toolbar groups drop their focus ring while a popup is open.**
+  A `ToolbarControlGroup` that owns the ring (`focusRing="outline"` or
+  `"halo"`) no longer paints it while a Select listbox or `PopupMenu` inside it
+  is open; the open popup shows focus, and the ring returns when the popup
+  closes with focus still in the group. This matches the per-control Select
+  and PopupMenu triggers.
+
+- **`@kerfjs/ui` multiple `Select` can be an icon-only toolbar filter menu.**
+  Set `selectedPresentation: 'icon-only'` on a `multiple` Select together with
+  a fixed `triggerIcon` (for example a funnel `LucideIcon`); the types require
+  `triggerIcon` there and reject it everywhere else. The trigger keeps the
+  icon-only caret pill used in a `ToolbarControlGroup`, and:
+  - shows the fixed icon whatever is chosen;
+  - adds a compact count `Badge` while any choice is chosen;
+  - ends the combobox's accessible name with the chosen labels in choice order
+    ("Filter by label: Bug, Docs"), leaving the hidden value text empty so the
+    list is not announced twice.
+
+  The popup still stays open while choices toggle.
+
+- **`@kerfjs/ui` `Select` options keep their accessibility semantics across
+  re-renders.** Re-rendering a Select (for example after its `change` handler
+  updates the controlling signal) removed the `role="option"` and
+  `aria-selected` Web Awesome sets on each option, so screen readers lost every
+  option's role and selected state. They now survive in single and `multiple`
+  Selects through the core rule below (custom elements own their `role` /
+  `aria-*`), with no Select-specific restore.
+
+- **`@kerfjs/ui` `Select` dividers keep their separator role across
+  re-renders.** The `wa-divider` a `separatorBefore` choice adds lost the
+  `role="separator"` and `aria-orientation` Web Awesome sets on it the first
+  time the enclosing mount re-rendered, and never got them back, so assistive
+  technology stopped announcing the break between option runs. The Select now
+  renders both attributes itself.
+
+- **`@kerfjs/ui` `Select` and `PopupMenu` re-renders no longer force Web
+  Awesome updates.** Web Awesome reflects its default `size`, `appearance`,
+  `placement`, and `orientation` onto `wa-select`, `wa-dropdown`, and
+  `wa-divider`; the templates omitted them, so every re-render of the enclosing
+  mount stripped them and each host ran a full Lit update to put them back. The
+  templates now render those defaults (`wa-select size="m"
+appearance="outlined" placement="bottom"`, `wa-dropdown size="m"`, divider
+  `orientation="horizontal"`), so an unchanged re-render leaves the hosts
+  alone. No visual change. The `@kerfjs/ui/webawesome` JSX declarations type
+  these attributes.
+
+- **`@kerfjs/ui` Workbench and CollapsiblePanel panes and chrome lists are
+  configurable.** The `Pane`s these layouts compose around app content now
+  take the new `PaneConfig` type (`contentElement`, `contentLabel`,
+  `separators`, `safeAreaEdges`): a Workbench panel's or `CollapsiblePanel`'s
+  `pane`, and the Workbench's `mainPane`. The `List`s holding `mainHeader` /
+  `mainFooter` take the new `ListConfig` type (`gap`, `hAlign`, `vAlign`,
+  `dividerSides`, `textInsets`, `controlInsets`) through `mainHeaderList` /
+  `mainFooterList`. Previously this configuration was hard-coded, so, for
+  example, a navigator rail could not render its content as a `nav` landmark
+  without restyling. Omitted or `undefined` fields keep today's defaults, and
+  the default markup is unchanged.
+
+- **`@kerfjs/ui` `SplitView` forwards its `ResizableRegion` and compact
+  `NavStack` configuration.** `resizable` now also takes the list region's
+  `separator`, `handleIcon`, `contentOverflow`, and collapse options
+  (`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`,
+  `restorePosition`), so an app can hide the list and float a restore control
+  without leaving `SplitView`. The new `compactStack` prop forwards the compact
+  stack's `toolbarConfig`, `backIcon`, `backText`, `hideToolbar`, and
+  persistent `bottomToolbar`, and gives the list and detail views their own
+  toolbar groups (`list` / `detail`: `leading`, `center`, `toolbar`,
+  `bottomToolbar`). Omitted options keep today's defaults.
+
+- **`@kerfjs/ui` `NavStack` renders its top chrome as a real `Toolbar`.** The
+  back control is a borderless `ToolbarControlGroup` and the title a
+  `ToolbarText` in the leading zone, and the stack now forwards:
+  - `toolbarConfig` — the `Toolbar` configuration (`dividerSides`,
+    `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) plus `label`,
+    `titleSize` (default `large`), and `headingLevel`;
+  - per-view `leading` and `center` groups beside the existing trailing
+    `toolbar`;
+  - `backIcon` and visible `backText` for the back control.
+
+  The defaults keep today's bar: no divider, one 44px band, and the top and
+  side safe-area edges claimed. The hand-rolled `kui-nav-stack__lead` and
+  `kui-nav-stack__actions` wrappers are gone (their content now sits in the
+  toolbar's zones), and `kui-nav-stack__back` / `kui-nav-stack__back-icon`
+  are no longer styled by the stack.
+
+- **`@kerfjs/ui` configures with props instead of token overrides.** Five
+  settings apps previously reached through raw `--kui-*` overrides now have a
+  typed prop or modifier; each defaults to today's rendering, and the
+  underlying tokens keep working:
+  - `FloatingToolbar` `inset` (a `CssLength`, default `--kui-space-m`) moves
+    it from the container edges. Omit it inside a restore corner, which owns
+    the inset.
+  - `DisclosureArrow` `size` (a `CssLength`, default 18px root-scaled).
+  - `ListHeader` `headingLevel` (1–6, default 2) sets the label's native
+    heading element for passive and trailing-action headers; a toggle header
+    has no heading and rejects it at compile time.
+  - `TokenSearchField` `clearIcon` replaces the clear action's glyph.
+  - `.kui-content-item--framed` paints the standard neutral border on a
+    content item that marks a real distinction, with no geometry change.
+
+  The docs and AI guidance also stop recommending `--kui-edge-inset-*`
+  overrides: an app-owned arrangement passes `safeAreaEdges` to its panes and
+  edge-claiming toolbars (including the layout toolbar configurations, which
+  forward it).
+
+- **`@kerfjs/ui` hides a work area's floating controls under an open side
+  overlay.** While a side overlay is open — a Workbench rail (static
+  `presentation: "overlay"`, or a responsive overlay whose breakpoint applies),
+  a `wireSidebar` compact overlay or `presentation="overlay"`
+  `CollapsiblePanel`, or a horizontal `presentation="overlay"`
+  `ResizableRegion` — the covered work area's `FloatingToolbar`s and the
+  layouts' restore corners are now hidden (`visibility: hidden`, so they also
+  leave the tab order and the accessibility tree) instead of relying on
+  stacking order alone. A phone-width app could otherwise paint the main
+  column's floating drawer toggle over its open inspector. They come back as
+  the overlay closes; the overlay's own floating controls and a bottom
+  drawer's overlay are unaffected.
+
+- **`@kerfjs/ui` `Select` supports multiple selection.** Set `multiple: true`
+  and pass the chosen values as an array `value`; the props are typed so an
+  array value requires `multiple`. Behavior:
+  - The popup stays open while the person toggles choices with the pointer,
+    Enter, or Space, and closes only on an outside press, Escape, or focus
+    leaving.
+  - Each chosen option shows a check.
+  - The closed control summarizes the chosen labels in choice order as a short
+    localized list, or shows `placeholderText` when none are chosen.
+  - `change` / `input` report the value array, and a form submits every chosen
+    value under `name`.
+  - Re-rendering with a different `value` updates the selection even after the
+    person has interacted.
+
+  `renderSelected` and `selectedPresentation="icon-only"` stay single-value
+  only.
+
+- **`@kerfjs/ui` `PopupMenu` now looks exactly like `Select`.** Both read one
+  shared popup contract, so a command menu beside a value list in a toolbar
+  draws the same popup. `PopupMenu` changes:
+  - its caret turns to face the open menu;
+  - its menu fades in without scaling;
+  - it takes the Select listbox's 4px inset (also under the default
+    `menuInset="standard"`);
+  - its rows use the Select option's height, padding, and reserved check
+    column, and its icons use the same 16px size and 8px gap;
+  - a keyboard-focused item takes the Select's current-option fill instead of
+    a focus ring;
+  - headings render as the Select's uppercase group titles rather than slotted
+    `h3` elements.
+
+  An open `Select` also no longer paints its trigger focus ring. The open
+  listbox shows focus, and the ring returns when it closes.
+
+- **`@kerfjs/ui` `Catalog` exposes its sidebar and toolbar configuration.** New
+  `sidebar` prop (size, `resizable`, `separator`, `collapseMotion`,
+  `presentation`, `responsiveOverlayAt`, `compactOverlay`, and the header
+  `toolbar`'s `ToolbarConfig`) forwarded to its Workbench rail, plus
+  `mainToolbar` / `footerToolbar` `ToolbarConfig` props. `wireCatalog` takes
+  `sidebarSize` / `sidebarStorageKey` to wire a resizable sidebar. Today's
+  288px fixed sidebar and toolbar policies remain the defaults.
+
+- **`@kerfjs/ui` composed toolbars are configurable.** `WorkbenchMainToolbar`,
+  `WorkbenchMainBottomToolbar`, and the panel `toolbar` of a Workbench panel or
+  `CollapsiblePanel` now take the `Toolbar`'s configuration: the new
+  `ToolbarConfig` type, covering `dividerSides`, `centerAlign`, `responsive`,
+  `responsiveAt`, and `safeAreaEdges`. Previously their dividers were
+  hard-coded, so for example dropping the line between a toolbar and its
+  content took CSS. Today's dividers remain the defaults. Also:
+  - `mainBottomToolbar` and panel toolbars take a `center`;
+  - panel toggles take localized `showLabel` / `hideLabel`;
+  - a Workbench panel's floating restore controls follow its
+    `restorePosition`.
+
+- **Breaking (`@kerfjs/ui`): removed the pre-release compatibility surface.**
+  - The `DividerSides` type is gone; use `Sides`, from the renamed `sides`
+    module.
+  - `ListInsetText.horizontalOnly` and its `kui-list-inset-text--horizontal`
+    class are gone; pass `sides="rl"` instead.
+  - The legacy color tokens are gone, both as `--kui-color-*` properties and
+    as `uiColor()` names. Replace them with their canonical tokens:
+
+    | Removed                                       | Use instead             |
+    | --------------------------------------------- | ----------------------- |
+    | `border`                                      | `neutral-border-normal` |
+    | `border-quiet`                                | `neutral-border-quiet`  |
+    | `accent`                                      | `brand-fill-normal`     |
+    | `accent-text`                                 | `brand-on-quiet`        |
+    | `pop`                                         | `pop-fill-quiet`        |
+    | `pop-text`                                    | `pop-on-fill`           |
+    | `success`, `warning`, `danger`                | `*-fill-quiet`          |
+    | `success-text`, `warning-text`, `danger-text` | `*-on-quiet`            |
+
+- **New `@kerfjs/ui` `PopupMenu` (`@kerfjs/ui/popup-menu`).** It renders a
+  trigger and typed commands, headings, and dividers over the Web Awesome
+  dropdown. Put it in a `single` `ToolbarControlGroup` with `nestedDropdown`, or
+  wrap it in a `PopupSurface`. Register it once with
+  `@kerfjs/ui/popup-menu/register`. It replaces hand-written `wa-dropdown`
+  markup, which the catalog discourages: the guidance, the toolbar demos, and
+  the Catalog's "Components" menu now use it. It also fixes two defects that
+  hand-written menus had:
+  - Icon-only triggers were unnamed, because a Web Awesome button ignores an
+    `aria-label` on its host. PopupMenu renders `label` as visually hidden text
+    inside the button.
+  - A keyboard choice (Enter or Space) never reached click-delegated
+    `data-action` handlers. PopupMenu's registration routes it through the
+    item's click.
+- The UX catalog's application-layout demo no longer uses the discouraged
+  `wa-button-group`.
+
+- **`@kerfjs/ui`'s `TokenSearchField` takes a `revision` prop for programmatic
+  text replacement.** The editor's text is DOM-owned, so a new `query` with the
+  same tokens was silently ignored, for example when reseeding a persistent
+  dialog's field on reopen. Changing `revision` rebuilds the editor from `query`
+  and `tokens`, so consumers no longer need to re-key a wrapper element.
+
+- **`@kerfjs/ui`'s `TabBar` strip no longer scrolls vertically.** The strip set
+  only `overflow-x: auto`, so any vertical excess (consumer padding, focus-ring
+  insets, taller tabs under larger text) let it scroll up and down on touch. It
+  now scrolls only horizontally, and it takes a `min-height` so it grows to fit
+  taller tabs instead of clipping them.
+
+- **The `@kerfjs/ui` desktop app-shell recipe is a `Workbench`.** The old
+  pane switcher that showed one pane at a time below desktop sizes is gone. The
+  navigation and inspector are now resizable Workbench rails with their own
+  toolbars, and their show toggles relocate into the work-area toolbar. On a
+  narrow container the rails overlay the task list one at a time. The
+  collapsible-sidebar recipe composes each panel's `toolbar` and uses
+  `CollapsiblePanelRelocated` for its restore controls.
+
+- **`@kerfjs/ui`'s `CollapsiblePanel` composes a panel toolbar and relocates its
+  controls.** A panel takes the same `toolbar` roles as a `Workbench` panel
+  (`title`, `panelOnly`, `constant`, and a standard `toggle`) plus a `footer`,
+  and the new `CollapsiblePanelRelocated` renders a collapsed panel's constant
+  groups and toggle wherever the app's work-area toolbar holds them.
+  `wireSidebar` hands focus to that relocated toggle when the panel closes, even
+  when the app renders it a frame late. `collapsiblePanelToggleIcon` is
+  unchanged.
+
+- **`@kerfjs/ui`'s `Catalog` is built on `Workbench` and dogfoods the package's
+  components.** The sidebar is a Workbench left rail with the standard toggle
+  (labels "Show/Hide {brand} catalog"), which moves into the entry toolbar while
+  collapsed; on a small screen the sidebar overlays the stage instead of the
+  former stacked two-column navigation, which is gone. The sidebar, sections,
+  footer, and example notes are `List` / `ListHeader` / `ListInsetText` / `Text`
+  compositions, and most catalog CSS (and every viewport media query in the
+  shell) is removed. New: `Catalog`'s `id`, `headerPlacement`, and
+  `footerPlacement`; `wireCatalog`'s `collapsed` and `id` options (the sidebar is
+  wired like a Workbench rail and an open overlay closes on a selection);
+  `Workbench`'s `mainHeader`, `mainFooter`, `mainHeaderPlacement`,
+  `mainFooterPlacement`, and `mainToolbar.responsive` / `responsiveAt`;
+  `ListInsetText`'s `rootAttributes`. `wireWorkbench` now also re-checks panel
+  breakpoints when the root font size changes, and hands focus to a panel's
+  relocated toggle when an unfocused click on its own toggle closes it (WebKit).
+
+- **`@kerfjs/ui`'s `Workbench` rails overlay the work area on small screens by
+  default.** A rail's `responsiveOverlayAt` now defaults to `"narrow"` (704px
+  of Workbench width; the new `"never"` keeps it inline), so a sidebar covers
+  the work area and any open drawer instead of squeezing it, one at a time
+  with `wireWorkbench`. On a compact (448px) Workbench an open overlay rail
+  fills the width less a 44px dismiss strip
+  (`--kui-workbench-overlay-dismiss-margin`) on the side away from its edge;
+  the new per-rail `compactOverlay: "full"` fills it. The bottom drawer's
+  behavior is unchanged. `WorkbenchPanelToolbar` and the other panel-toolbar
+  types are now exported from `@kerfjs/ui/workbench`.
+
+- **`@kerfjs/ui`'s `Workbench` composes panel toolbars and moves a closed
+  panel's controls into the work area.** A panel takes an optional `toolbar`
+  (`title`, `panelOnly`, `constant`, and a standard `toggle: { action, name }`
+  the Workbench renders) and `footer`; the Workbench takes `mainToolbar` and
+  `mainBottomToolbar`. While a panel is closed its constant groups and toggle
+  move to the work area — a left rail's lead the main toolbar, a right rail's
+  end it, a drawer's trail the bottom toolbar or float in a corner
+  `FloatingToolbar` — and its panel-only groups stay behind. `wireWorkbench`
+  keeps focus with the toggle as it moves. Panels without a `toolbar` render
+  exactly as before, and a region's only-child `Pane` or layout now fills it.
+
+- **`@kerfjs/ui`'s list-detail dialog guidance is Workbench-shaped.** On roomy
+  devices the list is a full-height sidebar and the detail a full-height main
+  column, each a `Pane` with its own top `Toolbar`; the main column carries
+  the primary title, the close control (`data-dialog="close"` in a
+  `without-header` Web Awesome dialog), and the record actions, instead of a
+  dialog header spanning both columns. The recipe, `docs/recipes.md`, and the
+  shipped AI skill say so; compact devices keep the full-screen drill-down
+  sheet.
+
+- **`@kerfjs/ui`'s `ToolbarControlGroup` centers a direct icon tile.** A
+  non-interactive icon placed directly in a group — a heading's identity
+  glyph — now takes an icon button's 40px slot and 16px visual, so it centers
+  in the group. It previously sat at the group's start edge, which pushed
+  apps to wrap it in a focusable `<button>` that did nothing.
+
+- **`@kerfjs/ui`'s `Toolbar` keeps its controls in a top control band.** A
+  toolbar now reserves one 44px band at its top: each zone item no taller than
+  the band is centered in it by its own size, and a taller item — a wrapped
+  `ToolbarText` title, a multi-line search, a second trailing row — starts at
+  the band's top and grows down without moving the others. A wrapped title
+  centers its first line in the band, so trailing controls stay beside that
+  line instead of dropping to the middle of the whole title.
+
+- **`@kerfjs/ui`'s segmented `TabBar` ends its strip concentric with the pill
+  track.** The first tab's leading corners, and with `allocation="fill"` the
+  last tab's trailing corners, now follow the track's curve instead of keeping
+  the small segment radius, and compact tabs are inset from the track's ends
+  by the same distance as from its top and bottom. Corners between tabs are
+  unchanged.
+
+- **`@kerfjs/ui`'s `StateBanner` keeps its title, badge, and detail on one
+  baseline in Safari.** The truncating detail was a clipped `inline-block`,
+  which WebKit baselines at its bottom edge: the detail rose about 2px above
+  the title and pushed the title and badge down, so the banner's contents
+  looked vertically misaligned. The detail is now an inline flex wrapper
+  around a clipped inner `<span>`, which takes its text baseline in every
+  engine; truncation and the narrow-width detail line are unchanged.
+
 - **`@kerfjs/ui`'s `wireTabBars` reveals a tab the application selects.** A
   tab added and selected by the app in an overflowing `TabBar` stayed
   off-screen, because the wiring revealed a selection only at wire-up, on

package/ai/manifest.json

@@ -1,5 +1,5 @@
 {
-  "kerfjsVersion": "5.0.0-beta.54",
+  "kerfjsVersion": "5.0.0-beta.56",
   "files": [
     {
       "name": "skill",

package/dist/{chunk-WMRFXSLG.js → chunk-TLL3KXT6.js}

@@ -294,7 +294,10 @@ function restoreFocus(snap) {
 
 // src/utils/isUserAgentOwnedAttr.ts
 function isUserAgentOwnedAttr(tagNameUpper, name) {
-  return name === "open" && (tagNameUpper === "DETAILS" || tagNameUpper === "DIALOG" || tagNameUpper.includes("-"));
+  if (tagNameUpper.includes("-")) {
+    return name === "open" || name === "role" || name.startsWith("aria-");
+  }
+  return name === "open" && (tagNameUpper === "DETAILS" || tagNameUpper === "DIALOG");
 }
 
 // src/utils/moveNode.ts
@@ -1511,4 +1514,4 @@ function resultToSegment(result) {
 
 export { captureFocus, each, morph, mount, moveNode, restoreFocus };
 
-//# sourceMappingURL=chunk-WMRFXSLG.js.map
+//# sourceMappingURL=chunk-TLL3KXT6.js.map