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

package/docs/accessibility.md

@@ -16,7 +16,7 @@ These are normative contracts for package components and consuming applications.
 - `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure. Its optional `badge` is persistent inline status/count content beside the title and is announced as part of the banner; keep it terse and do not rely on color alone for its meaning.
 - `EmptyState` reports busy state through `aria-busy` and never relies on an illustration as its label.
 - `Select` follows the Web Awesome host's standard `input`/`change` events. Application tests verify the live `value`, focus, and events—not attributes alone. Its decorative option icons and value-dependent selected content remain present after controlled rerenders, so the visible choice does not silently lose its non-text cue.
-- `DisclosureArrow` is an 18px root-scaled decorative visual by default, not an interaction target. Its owning native control supplies a stable accessible name, pointer and keyboard interaction, and `aria-expanded`; multiple arrows keep independently controlled state. Consumers may override `--kui-disclosure-arrow-size` without changing that ownership. Configured directions animate over the shortest path; a 180-degree closed-to-open tie uses counterclockwise rotation.
+- `DisclosureArrow` is an 18px root-scaled decorative visual by default, not an interaction target. Its owning native control supplies a stable accessible name, pointer and keyboard interaction, and `aria-expanded`; multiple arrows keep independently controlled state. Consumers may resize it with the typed `size` prop without changing that ownership. Configured directions animate over the shortest path; a 180-degree closed-to-open tie uses counterclockwise rotation.
 - `List` is layout-only and adds no `list` role. Children own their native or ARIA semantics. Give a scrollable List a bounded block size, avoid nested scroll owners, and keep focused children visible while scrolling.
 
 ## Select
@@ -30,6 +30,27 @@ adding height or spacing. This also applies to `renderSelected`: selected conten
 stays separate from the control's stable accessible name. Applications do not
 need shadow-DOM patches or extra label styling.
 
+Set `multiple` (with an array `value`) to let the person choose any number
+of choices. The popup stays open while they toggle choices with the pointer,
+Enter, or Space, and closes on an outside press, Escape, or focus leaving,
+returning focus to the combobox. The listbox is `aria-multiselectable`, each
+chosen option shows its check, and the closed control reads the chosen labels
+in choice order as one short localized list (the `placeholderText` when none
+are chosen) instead of a removable tag per choice. `change` and `input` report
+the value array; in a form, every chosen value is submitted under `name`.
+
+A toolbar filter menu (a "Filter by label" funnel) is a multiple Select with
+`selectedPresentation="icon-only"` and a fixed `triggerIcon`; the types accept
+`triggerIcon` only there, and require it there, because no single chosen
+choice has an icon to show. The trigger keeps the icon-only pill geometry
+below: the fixed icon, then, while any choice is chosen, a compact brand
+`Badge` with the count 4px after it, then the caret. The badge is hidden from
+assistive technology; instead the combobox's accessible name ends with the
+chosen labels in choice order ("Filter by label: Bug, Docs", just "Filter by
+label" when none are chosen), and its hidden value text stays empty so screen
+readers do not announce the list twice. With a visible `label` the same summary
+reads in the label, standing in for the hidden value.
+
 Use `presentation="toolbar-borderless"` inside a `ToolbarControlGroup`, with
 `size="compact"` in a compact group; set `focusRingOwner="group"` when that
 parent paints the composed focus ring. `selectedPresentation="icon-only"` hides
@@ -41,7 +62,12 @@ trigger (8px inline padding on both sides, 12px from the icon to the caret, a
 choice list. Inside a group the trigger is inset evenly on every side (2px in a
 default group, 1px in a compact one) with a concentric radius; the group grows
 to the trigger's width, so a single group is wider than it is tall and its
-focus ring follows the pill while focused and while its listbox is open.
+focus ring follows the pill while focused. While the listbox is open the
+trigger drops its ring, as a `PopupMenu` trigger does: the open popup and its
+current option show where focus is, and the ring returns when the listbox
+closes with focus still on the control. A group that owns the ring
+(`focusRing="outline"` or `"halo"`) drops it the same way while a Select
+listbox or `PopupMenu` inside the group is open.
 Beside other controls in one group, the icon-only trigger is one more segment:
 it keeps the group's gap and its siblings' block inset, height, item radius,
 and hover pill. In a group with per-control rings (`focusRing="control"`, the
@@ -81,6 +107,79 @@ repeated and out-of-order completions, cancellation, instance isolation, and
 removal. `tests/browser/select-lifecycle.spec.ts` repeats animation/resize/reopen
 sequences at wide and narrow widths in Chromium, Firefox, and WebKit.
 
+### Help tags on icon-only triggers
+
+An icon-only control has no visible title, so sighted pointer and keyboard users
+would otherwise see only its icon (and a filter's count). Following the Apple
+HIG convention for toolbar items, three kinds of icon-only control show a help
+tag: a Web Awesome `wa-tooltip` in the theme's tooltip palette, below the
+control.
+
+- an icon-only `Select` (`selectedPresentation="icon-only"`, single or
+  `multiple`);
+- an icon-only `PopupMenu` (named by `label` rather than visible `text`);
+- an icon-only `<button>` or link (`<a href>`) inside a `ToolbarControlGroup`,
+  named by a non-empty `aria-label`, with no visible text, no native `title`,
+  and no Web Awesome tooltip `for` it.
+
+Tags are on by default and take no props. One document-level installer covers
+all three kinds, and any of `@kerfjs/ui/select/register`,
+`@kerfjs/ui/popup-menu/register`, or `@kerfjs/ui/help-tags/register` installs
+it (once per document, however many are imported). An application whose
+toolbars have icon-only buttons but no registered `Select` or `PopupMenu`
+imports `@kerfjs/ui/help-tags/register`, which registers only the tooltip
+element. Pure `SafeHtml` rendering stays zero-JS: without an installer, nothing
+shows a tag.
+
+- **Text.** The tag says what the accessible name says: a filter's name and
+  chosen labels ("Filter by label: Bug, Docs", or "Filter by label" when none
+  are chosen), a single Select's name and current choice ("Rendering balance:
+  Balanced"), a menu's `label` ("Sort tickets"), or a toolbar button's
+  `aria-label` ("Pin view"). It updates with the selection.
+- **Showing.** It appears after the pointer rests on the control for 500ms, at
+  once when a neighboring tag closed moments ago (so scanning along a toolbar
+  stays quick, across buttons, Selects, and menus alike), and immediately on
+  keyboard focus (`:focus-visible`). A pointer press that focuses the control
+  and touch input never show it.
+- **Hiding.** It hides when the pointer and keyboard focus have both left the
+  control, on a press, on Escape, and whenever a popup opens. It does not come
+  back when the popup closes and focus returns to the trigger, or while the
+  pointer stays on a pressed button; it returns after the pointer moves onto
+  something else or focus leaves and comes back.
+- **Assistive technology.** The tag is `aria-hidden` and never joins the
+  control's `aria-labelledby` or `aria-describedby` (kerf anchors it directly
+  rather than through `for`), so the accessible name is unchanged and announced
+  once; the accessibility tree is identical with the tag open or closed.
+- **Isolation.** A Select's or PopupMenu's tag lives in the control's own
+  shadow root, so the morph never touches it and light-DOM `:has([open])`
+  selectors do not see it. A plain button cannot host a shadow root, so its tag
+  lives in one `aria-hidden`, `data-morph-skip` layer at the end of `<body>`
+  (fixed and zero-sized, so it never joins a grid or flex body's flow, and
+  re-attached if a body re-render drops it) and leaves that layer once hidden.
+  It copies the button's `color-scheme`, so it matches a subtree theme, and its
+  popup renders in the browser's top layer, so it shows above a modal dialog
+  that holds the button. Tags' `wa-show` / `wa-hide` lifecycle events stop at
+  the tag, so a listener on the control (or a delegated one above it) hears only
+  the popup; a document capture-phase listener still observes them. A long tag
+  wraps at the tooltip's maximum width and keeps 8px clear of the viewport
+  edge.
+
+A labeled Select, a `PopupMenu` with visible `text`, and a toolbar button with
+visible text get no tag: their visible text already names them. A button that
+carries a native `title`, or that the application has already given a
+`wa-tooltip` `for` its `id`, keeps that and gets no second tag, so nothing is
+shown twice. Zero-JS components that name an icon control with a native `title`
+(the `ListHeader` action, the `AppTab` close button, the `TokenSearchField`
+reveal and clear buttons, and `SegmentedControl` choice titles) keep the
+browser's own tooltip, which needs no script; the installer deliberately skips
+them rather than stacking a second tag on the first. Icon-only buttons outside
+a `ToolbarControlGroup` are application markup and keep whatever naming the
+application gives them.
+`tests/unit/help-tag.test.ts` walks the hover, focus, press, Escape, popup, and
+warm-window transitions for every kind; `tests/browser/select-help-tag.spec.ts`
+and `tests/browser/toolbar-help-tag.spec.ts` check the real elements in
+Chromium.
+
 ## PopupMenu
 
 `PopupMenu` renders a Web Awesome dropdown, so the menu roles, arrow-key and
@@ -88,8 +187,13 @@ typeahead navigation, Escape, and focus return to the trigger come from
 `wa-dropdown`. Kerf's part is the trigger's name. A Web Awesome button takes its
 name from its content and ignores an `aria-label` on the host, so an icon-only
 trigger requires `label`, which renders as visually hidden text inside the
-button; a trigger with visible `text` is named by that text. Group headings render as the dropdown's native menu labels, and
-dividers are presentational. A disabled item stays in the menu but cannot be
+button; a trigger with visible `text` is named by that text. An icon-only
+trigger also shows its `label` as an `aria-hidden` help tag on hover and
+keyboard focus (see [Help tags on icon-only triggers](#help-tags-on-icon-only-triggers)). Group headings
+render as the same uppercase group titles a grouped `Select` shows, and dividers
+are presentational. A keyboard-focused item is the menu's current row, painted
+with the Select's current-option fill rather than a second focus ring inside the
+open popup. A disabled item stays in the menu but cannot be
 chosen; disable the whole trigger only when every command is unavailable.
 
 ## ListActionRow
@@ -183,10 +287,15 @@ forced to a dark color scheme, but it is **not** in the top layer, so it never
 covers dialogs, popovers, or other overlays. Its children are the app's controls
 (normally `ToolbarControlGroup`s), which keep their own names, focus, and
 keyboard behavior; the application owns their actions, the toolbar's visibility,
-and — via `position` and `--kui-floating-toolbar-inset`, set on the toolbar
-or an ancestor — where it sits. Inside a `Workbench`, `CollapsiblePanel`, or
+and — via `position` and the typed `inset` prop — where it sits. Inside a `Workbench`, `CollapsiblePanel`, or
 `ResizableRegion` `restoreControl` the restore corner owns the inset, so the
-toolbar floats from that corner.
+toolbar floats from that corner. While one of those layouts has a side overlay
+open over the toolbar's region (a Workbench rail overlay, a `wireSidebar`
+compact overlay, an overlay `CollapsiblePanel` or horizontal
+`ResizableRegion`), the toolbar is hidden (`visibility: hidden`), so it is
+unfocusable and out of the accessibility tree rather than a control stranded
+behind the overlay's focus trap; it returns when the overlay closes. The
+overlay's own floating toolbars stay.
 
 ## Tabs
 

package/docs/app-layouts.md

@@ -79,13 +79,15 @@ nothing routes that edge, while the bar's surface and divider still reach the
 screen edge. A claimed toolbar inside a `Pane` header or footer adds nothing
 extra, because the pane already owns those edges.
 
-Pass `safeAreaEdges={[]}` for a pane that never sits at a screen edge. For a
-region you own, set `--kui-edge-inset-block-start`, `--kui-edge-inset-block-end`,
-`--kui-edge-inset-inline-start`, or `--kui-edge-inset-inline-end` to `0px` on the
-region for each edge it does not reach, and kerf descendants follow. A
-`CollapsiblePanel` does this for its direct flex siblings automatically. A
-panel wrapped in your own grid cell cannot see its siblings, so route those
-edges yourself.
+Pass `safeAreaEdges={[]}` for a pane that never sits at a screen edge. In an
+arrangement you own, give each `Pane` (and each edge-claiming `Toolbar`)
+`safeAreaEdges` listing only the sides its region reaches. The toolbar
+configurations layouts accept (a Workbench `mainToolbar` / `mainBottomToolbar`,
+and a Workbench panel's or `CollapsiblePanel`'s `toolbar`) forward
+`safeAreaEdges` to their `Toolbar` the same way.
+A `CollapsiblePanel` clears the edge it covers for its direct flex siblings
+automatically; a panel wrapped in your own grid cell cannot see its siblings,
+so pass the neighboring panes' `safeAreaEdges` yourself.
 
 The device insets come from `--kui-safe-area-block-start`, `-block-end`,
 `-inline-start`, and `-inline-end`, which default to `env(safe-area-inset-*)`.

package/docs/catalog.md

@@ -396,9 +396,23 @@ revealCatalogEntry(app, initial, { block: "center" });
   Pass the same signal as `wireCatalog`'s `collapsed` option so the sidebar is
   wired as a Workbench rail (transient on small screens, focus handed to the
   relocated toggle).
-- **`headerPlacement` / `footerPlacement`** choose whether the entry toolbar and the
-  status + resource footer stay pinned (`fixed`, default) or scroll with the preview
-  (`scroll`) — useful where large text would leave pinned chrome little room.
+- **`headerPlacement` / `footerPlacement`** choose whether the entry toolbar and
+  description, and the status + resource footer, stay pinned (`fixed`), scroll with
+  the preview (`scroll`), or stay pinned while the entry pane is tall enough and
+  scroll with the preview when it is short (`auto`, the default) — so a short
+  window or large text never squeezes the preview out.
+- **`sidebar`** configures the sidebar rail — it forwards to the Workbench's left
+  rail: `size` (default 288px), `resizable` (`true` or `{ min, max }`),
+  `separator`, `collapseMotion`, `presentation`, `responsiveOverlayAt` (default
+  `narrow`), `compactOverlay` (default `inset`), and `toolbar` (the sidebar
+  header's `ToolbarConfig`). A resizable sidebar's width is app state like
+  `collapsed`: render your size signal as `sidebar.size` and pass the same signal
+  as `wireCatalog`'s `sidebarSize` (plus `sidebarStorageKey` to remember it).
+- **`mainToolbar` / `footerToolbar`** take the entry toolbar's and the resource
+  footer toolbar's `ToolbarConfig` (`dividerSides`, `centerAlign`, `responsive`,
+  `responsiveAt`, `safeAreaEdges`). The defaults are a wrapping entry toolbar
+  and a divider-free footer toolbar that stacks at `narrow`; an omitted or
+  `undefined` field keeps them. Configure these instead of styling the shell.
 - **`theme`** is a global preference — the app's signal; `wireCatalog` only reports
   the toggle, the app applies the theme (the shell reads `theme` to show the toggle's
   opposite-state label). Omit `theme` to hide the toggle entirely.

package/docs/collapsible-panel.md

@@ -57,7 +57,15 @@ Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.
   the rest of the page, including under the compact overlay's backdrop. The
   control takes `--kui-collapsible-panel-restore-z`, which defaults to two less
   than `--kui-collapsible-panel-overlay-z` (38); the backdrop defaults to one
-  less (39), so moving the overlay z-index moves both. Escape, a backdrop
+  less (39), so moving the overlay z-index moves both. While a left or right
+  overlay is open (the `wireSidebar` compact overlay, or
+  `presentation="overlay"`), the content's floating controls — restore
+  corners and any `FloatingToolbar` — are also hidden outright (out of the
+  tab order and the accessibility tree), so they never paint over the overlay
+  whatever stacking context the app creates; they return as it closes. The
+  overlay's own floating controls stay, and a bottom overlay hides nothing. A
+  horizontal `presentation="overlay"` `ResizableRegion` does the same for its
+  siblings. Escape, a backdrop
   press, or the panel's own close control reveals the control again, and a
   collapsed overlay leaves it clickable. `ResizableRegion`'s `restoreControl`
   follows the same rules, two below `--kui-resizable-region-overlay-z` (39).
@@ -118,8 +126,19 @@ Give a panel a `toolbar` (the same roles as a
 [Workbench panel toolbar](workbench.md#panel-toolbars)) and it composes its own
 top toolbar over a `Pane`, with an optional `footer` below its content:
 
-- `title` and `panelOnly` groups lead it and are available only while it is open;
-- `constant` groups and the standard `toggle: { action, name }` trail it.
+- `title` and `panelOnly` groups lead it and are available only while it is open,
+  as is optional `center` content;
+- `constant` groups and the standard `toggle: { action, name, showLabel?,
+hideLabel? }` trail it.
+
+The toolbar also takes the `Toolbar`'s configuration (`dividerSides`,
+`centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`); it keeps its
+bottom divider unless `dividerSides` says otherwise. The `Pane` under it takes
+the panel's `pane` (`PaneConfig`: `contentElement`, `contentLabel`,
+`separators`, `safeAreaEdges`) — for example `{ contentElement: "nav",
+contentLabel: "Sections" }` for a navigation rail. An omitted or `undefined`
+field keeps the `Pane` default; without a `toolbar` there is no `Pane`, so
+`pane` is ignored.
 
 A standalone panel does not own the rest of the screen, so the app places a
 `CollapsiblePanelRelocated` in its own work-area toolbar: it renders the panel's
@@ -289,10 +308,10 @@ panel to the compact overlay (`wireSidebar`) where the viewport cannot hold it.
 
 A panel grows by the unsafe inset of the edge it docks to and pads its content
 for every edge it touches except its interior edge. While expanded inline, it
-also clears that edge for its direct flex siblings, so a neighboring pane gains
-the inset when the panel collapses. When you wrap the panel in your own grid
-cell, set `--kui-edge-inset-*: 0px` on the sibling regions yourself (or pass
-`safeAreaEdges` to a sibling `Pane`). See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+also clears that edge for every other direct child of its container, so a
+neighboring pane gains the inset when the panel collapses. When you wrap the panel in your own grid
+cell, pass each sibling `Pane` a `safeAreaEdges` that omits the edge the panel
+covers. See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
 
 ## When to use which
 

package/docs/component-contract.md

@@ -258,11 +258,15 @@ rows align that 18px visual with the first inherited text line. The row clips
 descendant painting to its rounded root so labels, status, and dormant trailing
 content cannot escape its visible boundary. Rows with descriptions grow enough
 to keep their owned two-line label stack readable; use `multiline` when the
-primary label should wrap rather than truncate.
-
-`DisclosureArrow` uses an 18px root-scaled visual by default. Override
-`--kui-disclosure-arrow-size` on the component or its containing scope when a
-consumer needs another size. Kerf `Select` uses a separate Web Awesome expand
+primary label should wrap rather than truncate. A single-line row ends its
+primary label and description with an ellipsis before the trailing status
+slot, even when the label is one long word; a `multiline` row wraps instead,
+breaking a word wider than the label column (a long component or file name)
+rather than letting it run under the trailing slot. `ListActionRow` labels
+follow the same single-line and `multiline` rules before the trailing action.
+
+`DisclosureArrow` uses an 18px root-scaled visual by default. Pass its typed
+`size` prop when a consumer needs another size. Kerf `Select` uses a separate Web Awesome expand
 glyph contract, `--kui-disclosure-icon-scale: .5`; changing one contract does
 not implicitly change the other. Direction changes take the shortest rotation
 path; a 180-degree closed-to-open tie uses counterclockwise rotation.
@@ -341,9 +345,10 @@ and do not type-check there. Never exchange these property grammars. List rows e
 `className`, public tokens, and semantic props instead of unrestricted `style`
 declarations.
 `.kui-content` gives major children 24px vertical separation.
-`.kui-content-item` gives one child 8px inline margin, a real 1px border,
-8px padding, and 12px corners; border and background may be transparent without
-changing geometry. `.kui-content-item--pill` selects the 22px radius.
+`ContentItem` (`@kerfjs/ui/content-item`, rendering `.kui-content-item`) gives
+one child 8px inline margin, a real 1px border, 8px padding, and 12px corners;
+the border stays transparent unless `frame="framed"`, so framing never changes
+geometry. `shape="pill"` selects the 22px radius.
 
 `ToolbarControlGroup` is the unit of toolbar organization, even for dormant
 text. Each group reserves `calc(2px + remify(42px))`, or 44px, with 8px between
@@ -363,7 +368,13 @@ can remain square. A compact icon `<button>` is a 32px circle, so a selected
 compact segment never becomes an oval. An icon-only `Select` joins a group as
 one more segment with its siblings' inset, radius, hover, and focus ring; only a
 lone Select grows the group to its icon-and-caret pill. Set `menuInset` to configure the dropdown menu surface
-without application `::part(menu)` CSS. Compact mixed controls retain the standard
+without application `::part(menu)` CSS; the default `standard` keeps each menu's
+own inset (8px for a raw `wa-dropdown`, the Select listbox's 4px for a
+`PopupMenu`), while `compact` and `list-zero` apply to every nested menu. A
+`PopupMenu` and a `Select` draw one popup: the same caret that turns to face the
+open popup, fade-in surface, surface inset, row height and padding, reserved
+check column, current-row fill, and group titles, all read from one private
+popup-choice contract in `foundation.css`. Compact mixed controls retain the standard
 item padding, omit an internal separator, and let the raised selected item paint
 over the outer border instead of shrinking to an inset highlight. The Web
 Awesome trigger's shadow base owns max-content sizing, so icons, localized text,
@@ -374,7 +385,12 @@ choose `responsive="stack"` with `responsiveAt="compact" | "narrow"`,
 `responsive="wrap"` for a heading whose title must stay whole, or
 `responsive="center-priority"` instead of selecting its zone classes from a
 parent stylesheet. No policy clips an action: the trailing zone, and a stacked
-center zone, wrap whole groups onto another row.
+center zone, wrap whole groups onto another row. The center zone never
+compresses below its content width, so when the leading identity, center, and
+trailing zones share a row that is too narrow, the leading title is what gives
+way: it truncates with an ellipsis (as a platform toolbar's title does) instead
+of the center group painting over it. When everything fits, the center group
+keeps its place, centered in the track between the leading and trailing zones.
 `ListHeader` similarly separates its dormant title and
 optional count or badge from its optional 44px action. Use the mutually
 exclusive `count`/`countLabel` pair for non-negative safe-integer section
@@ -400,6 +416,16 @@ padding + 24px icon + 8px gap) and 8px from the right edge for an icon-bearing
 row. Applications own the values, formatting, and whether an icon is decorative
 or meaningfully labeled.
 
+A row follows the settings-style key/value priority: the value keeps its
+content and the label gives way. The label and value are two content-sized
+columns that share the row's free space equally, each stopping once its content
+fits. A short value therefore stays whole on one line beside any label, and a
+long label takes the remaining width, wrapping at its spaces and ending a word
+wider than its column (a long component or file name) in an ellipsis before the
+value rather than running under it. A short label keeps its width beside a
+long value, which wraps; when both are long they split the row, so neither is
+starved.
+
 ## Imports and side effects
 
 Every component has an explicit JS and CSS subpath. In CSS-aware browser builds,