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

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

@@ -6,6 +6,15 @@ footer that the kerf UI catalog itself uses. Point it at your own components and
 you get the same shell without rebuilding it. Like the app layouts, it is a
 subpath-only, tree-shakeable module that adds nothing to the main barrel.
 
+The shell is a [`Workbench`](workbench.md) built entirely from `@kerfjs/ui`
+components: the sidebar is its left rail and the active entry its work area. So
+the sidebar behaves like any Workbench rail — its standard toggle moves into the
+entry toolbar while it is collapsed, and on a small screen (a Workbench narrower
+than 704px) it overlays the stage, one tap from the entry toolbar, filling the
+width less a 44px strip that closes it, instead of squeezing the stage. Pass the
+app's `collapsed` signal to `wireCatalog` so that overlay closes on Escape, on a
+press outside, and when an entry is chosen from it.
+
 ```bash
 npm install @kerfjs/ui # kerfjs is a peer; @kerfjs/ui/select/register is needed only if entries use `related`
 ```
@@ -36,9 +45,9 @@ expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
   sidebar content), and `status` (a footer status line).
 
 Per-entry `resources` render as "open in new tab" links in the footer, and
-`related` renders a "Related entries" popup menu — a `single` `ToolbarControlGroup`
-around a `wa-dropdown` (grouped by each entry's `group`), so register its elements
-with `@kerfjs/ui/select/register` when you use it.
+`related` renders a "Related entries" `PopupMenu` in a `single`
+`ToolbarControlGroup` (grouped by each entry's `group`), so register its elements
+with `@kerfjs/ui/popup-menu/register` when you use it.
 
 ## Catalog demo authoring contract
 
@@ -249,8 +258,8 @@ Set `revealSelection: true` on `wireCatalog` for a long desktop sidebar. After
 `onSelect` updates controlled state, the helper waits one animation frame, finds
 the exact matching `data-item-id`, and scrolls it into view without changing
 focus. A newer selection or disposal cancels the pending reveal. The default
-media guard is the Catalog desktop layout (`min-width: 52.01rem`), so compact
-layouts keep their existing scroll position.
+media guard follows the Workbench's inline sidebar (`min-width: 44.01rem`), so a
+closed phone overlay is never scrolled behind the user's back.
 
 Pass an options object instead of `true` to customize `block`, `inline`,
 `behavior`, or `media`; `media: false` deliberately enables the behavior at all
@@ -384,6 +393,26 @@ revealCatalogEntry(app, initial, { block: "center" });
 - **`active`** is domain state (which entry is shown) — the app's signal, updated in
   `onSelect`, read to compute `content`.
 - **`collapsed`** is transient UI — the app's signal, flipped in `onToggleSidebar`.
+  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
+  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.
@@ -397,7 +426,10 @@ matching options on `wireCatalog`) if they collide with your own action table.
 
 ## CSS
 
-`Catalog` composes public primitives (`Toolbar`, `ListHeader`, `ListItem`, `Select`,
-…). Import `@kerfjs/ui/styles.css` for the whole layer, or `@kerfjs/ui/catalog.css`
-plus each composed primitive's CSS. The shell is theme-aware and responsive: it
-stacks the sidebar above the detail below ~832px and hides it when collapsed.
+`Catalog` composes public components (`Workbench`, `Pane`, `Toolbar`, `List`,
+`ListHeader`, `ListItem`, `ListInsetText`, `Text`, …) and owns only the preview stage
+(the checkerboard and centered canvas), the geometry overlay, the example viewport
+options, and the brand mark's size. Import `@kerfjs/ui/styles.css` for the whole
+layer, or `@kerfjs/ui/catalog.css` plus `@kerfjs/ui/workbench.css` and each composed
+primitive's CSS. Like any Workbench it needs a definite containing height — the
+`@kerfjs/ui/document.css` baseline's `.kui-app-root`.

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).
@@ -112,6 +120,72 @@ Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.
 
   Returns a disposer. Retain it and call it on teardown.
 
+## Panel toolbars and relocated controls
+
+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,
+  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
+`constant` groups and toggle while the panel is collapsed, and nothing while it
+is open. Put it first in the leading zone for a left rail, last in the trailing
+zone for a right rail, and last in a bottom toolbar for a bottom drawer. With no
+bottom toolbar, pass it inside a `FloatingToolbar` as the drawer's
+`restoreControl`.
+
+```tsx
+const toolbar: CollapsiblePanelToolbar = {
+  label: "Navigator",
+  panelOnly: <NewFileGroup />,
+  constant: <SearchGroup />,
+  toggle: { action: "toggle-nav", name: "navigator" },
+};
+
+<Row fill gap="none">
+  <CollapsiblePanel id="nav" side="left" collapsed={navCollapsed.value} toolbar={toolbar}>
+    <Files />
+  </CollapsiblePanel>
+  <List flex>
+    <Pane
+      header={
+        <Toolbar
+          label="Editor"
+          leading={
+            <>
+              <CollapsiblePanelRelocated panelId="nav" side="left" collapsed={navCollapsed.value} toolbar={toolbar} />
+              <ToolbarText text="Editor" size="xlarge" />
+            </>
+          }
+        />
+      }
+    >
+      <Editor />
+    </Pane>
+  </List>
+</Row>;
+```
+
+Wire it with `wireSidebar` (`toggleAction` is the toggle's `action`): closing the
+panel from its own toggle hands focus to the relocated toggle, even when the app
+renders it a frame later, and opening it moves focus into the panel. Each toggle
+carries a stable `data-key`, so the morph never reuses a focused toggle's button
+for another control as it moves.
+
 ## Compact initial state
 
 A compact overlay is transient chrome the user summons, like a slide-over
@@ -234,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
@@ -356,14 +361,20 @@ stay inside the available toolbar width. Set `visibility="compact-only"` for a
 group that replaces wider toolbar controls below the Toolbar's compact container
 breakpoint; do not hide the group with an application class. Reach for
 `wa-button` only when you need
-a Web Awesome feature, chiefly the `slot="trigger"` button of a `wa-dropdown`
-popup menu. For a compact mixed-content group, set `nestedDropdown`; a
+a Web Awesome feature; a popup menu is a `PopupMenu`, which renders its own
+trigger. For a compact mixed-content group, set `nestedDropdown`; a
 text-and-caret trigger grows to its intrinsic width while an icon-only trigger
 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,