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

package/docs/workbench.md

@@ -65,7 +65,8 @@ const navCollapsed = signal(false);
 />;
 ```
 
-Each `WorkbenchPanel` takes `content`, an optional `collapsed`, an optional
+Each `WorkbenchPanel` takes `content`, an optional `toolbar` and `footer` (see
+[Panel toolbars](#panel-toolbars)), an optional `collapsed`, an optional
 `size` (rail width or drawer height in px, overriding the CSS default —
 `--kui-workbench-rail-width` 280px, `--kui-workbench-drawer-height` 220px), and
 an optional `label`. Common shell behavior is configured rather than restyled:
@@ -81,10 +82,20 @@ an optional `label`. Common shell behavior is configured rather than restyled:
   each exactly at its configured size (its separator border included, as in
   flow) up to the viewport-relative overlay maximum; the content fills the
   panel inside its border, so it is clamped with it;
-- `responsiveOverlayAt: "narrow" | "compact"` presents a rail or the bottom
-  drawer as an overlay below a Workbench container breakpoint — 704px or less
-  for `narrow`, 448px or less for `compact`, the breakpoints of
-  `ResizableRegion`'s `responsiveFillAt` — and inline above it. The CSS
+- `responsiveOverlayAt: "narrow" | "compact" | "never"` presents a rail or the
+  bottom drawer as an overlay below a Workbench container breakpoint — 704px
+  or less for `narrow`, 448px or less for `compact`, the breakpoints of
+  `ResizableRegion`'s `responsiveFillAt` — and inline above it. **Rails
+  default to `narrow`**, so on a small screen a sidebar covers the work area
+  (and an open drawer) instead of squeezing it; pass `never` to keep a rail
+  inline. The drawer stays inline unless it opts in. On a compact (448px or
+  less) Workbench an overlay rail fills the Workbench less a dismiss strip on
+  the side away from its edge — `--kui-workbench-overlay-dismiss-margin`,
+  44px, one touch target — so a press beside it closes it;
+  `compactOverlay: "full"` (per rail) fills the Workbench instead, which
+  usually wants app-level handling of its own. Pass each rail's `collapsed`
+  signal to `wireWorkbench` so only one overlay is open at a time and a press
+  outside closes it. The CSS
   decides, so the app needs no `deviceClass` check for presentation; a
   collapsed overlay drops its surface and shadow so nothing covers the work
   area, and the work area keeps the safe-area inset of the edge the overlay
@@ -96,10 +107,18 @@ an optional `label`. Common shell behavior is configured rather than restyled:
   defaults to two less than the overlay z-index (39), so they sit beneath
   every overlay: an open overlay covers another panel's restore control as
   it covers the rest of the work area, and a collapsed overlay, which drops
-  its pointer events, leaves the control beneath it usable;
+  its pointer events, leaves the control beneath it usable. While a rail
+  overlay is open (static, or a responsive one whose breakpoint applies), the
+  work area's floating controls — restore corners and any `FloatingToolbar`
+  in `main` — are also hidden outright (out of the tab order and the
+  accessibility tree), so they can never paint over the rail whatever
+  stacking context the app gives the work area; they return as it closes.
+  The rail's own floating controls stay, and a drawer overlay hides nothing;
 - `restoreControl` places an application-owned restore affordance in a
-  corner of the Workbench itself while the panel is collapsed
-  (`restorePosition` chooses the corner), inset by
+  corner of the Workbench itself while the panel is collapsed. Prefer a
+  `toolbar.toggle`, which the Workbench relocates for you; keep
+  `restoreControl` for a custom affordance. `restorePosition` chooses the
+  corner, inset by
   `--kui-workbench-restore-inset` (16px) plus the unsafe area of each edge the
   corner reaches. A rail's control sits in the Workbench's corner; the
   drawer's sits in the corner of the work-area column it restores into, so it
@@ -117,8 +136,8 @@ an optional `label`. Common shell behavior is configured rather than restyled:
   carrying `collapsiblePanelToggleIcon(side, true)` — rather than a bare
   button. To give it `FloatingToolbar`'s toolbar role and floating look, wrap
   that group in a `FloatingToolbar` whose `position` matches the corner: the
-  corner owns the inset (it sets `--kui-floating-toolbar-inset` to 0), so the
-  toolbar floats from the corner instead of doubling it.
+  corner owns the inset (it zeroes the toolbar's default inset), so omit
+  `inset` there and the toolbar floats from the corner instead of doubling it.
 
 - `resizable: true | { min, max }` opts the panel in to drag and keyboard
   resizing, driven by `wireWorkbench` (off by default).
@@ -127,6 +146,108 @@ The same policy props are available on `ResizableRegion` and
 `CollapsiblePanel`, so a resizable application shell does not need to reach
 into `.kui-resizable-region__content`.
 
+## Panel toolbars
+
+A panel's controls follow it open and closed when the Workbench composes the
+toolbars. Give a panel a `toolbar` and the work area a `mainToolbar` (and, for
+a drawer, optionally a `mainBottomToolbar`); the Workbench renders each as a
+standard `Toolbar` over a `Pane`, and moves groups between them as panels open
+and close. A panel's `toolbar` has four parts:
+
+- `title` — the panel's `ToolbarText` (the quiet default size in a rail).
+- `panelOnly` — groups that make sense only while the panel is open. They lead
+  its toolbar, after the title, and are unavailable while it is closed.
+- `constant` — groups that stay available either way. They trail the panel's
+  toolbar while it is open and move to the work area's toolbar while it is
+  closed.
+- `toggle: { action, name, showLabel?, hideLabel? }` — the standard collapse
+  toggle, which the Workbench renders: the per-side panel glyph,
+  `aria-controls` naming the panel, `aria-expanded`, a "Show …"/"Hide …"
+  label (or your localized `showLabel` / `hideLabel`), and the `data-action`
+  the app handles. It is always the last group.
+- `center` — optional panel-only center content.
+
+While a panel is closed, its `constant` groups and then its toggle go to:
+
+| Panel         | Where they go                                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------------------------- |
+| Left rail     | The leading edge of `mainToolbar`, before its `title`                                                           |
+| Right rail    | The trailing edge of `mainToolbar`, after its `trailing` groups, so the toggle is the toolbar's last group      |
+| Bottom drawer | The trailing edge of `mainBottomToolbar`; without one, a `FloatingToolbar` in the work area's bottom-end corner |
+
+A rail with no `mainToolbar` floats its groups in its corner the same way, so
+a closed panel can always be reopened. An open overlay panel carries its own
+toggle, so it never depends on a control it covers. An app's own
+`restoreControl` still wins over the floating fallback.
+
+```tsx
+<Workbench
+  id="studio"
+  label="Studio"
+  mainToolbar={{ label: "Editor", title: <ToolbarText text="Editor" size="xlarge" /> }}
+  main={<Editor />}
+  leftRail={{
+    label: "Navigator",
+    toolbar: {
+      label: "Navigator",
+      title: <ToolbarText text="Navigator" />,
+      panelOnly: <NewFileGroup />,
+      constant: <SearchGroup />,
+      toggle: { action: "toggle-navigator", name: "navigator" },
+    },
+    content: <Files />,
+    collapsed: navCollapsed.value,
+  }}
+/>
+```
+
+The work area's `Pane` can carry more fixed chrome: `mainHeader` renders under
+`mainToolbar` (supporting copy) and `mainFooter` over `mainBottomToolbar` (a status
+line or a resource toolbar), each divided from the scrolling `main`.
+`mainHeaderPlacement` and `mainFooterPlacement` (`"fixed"` by default, or
+`"scroll"`) let that header or footer chrome scroll away with `main` instead —
+useful where large text would leave pinned chrome little room. `"auto"` keeps
+it pinned while the work area is tall enough and lets it scroll with `main`
+when the work area is short (the Pane's `chromePlacement="auto"`; it applies to
+the pinned header and footer together).
+
+Every toolbar the Workbench composes — `mainToolbar`, `mainBottomToolbar`, and
+each panel's `toolbar` — takes the `Toolbar`'s configuration (`ToolbarConfig`):
+`dividerSides`, `centerAlign`, `responsive`, `responsiveAt`, and
+`safeAreaEdges`. Configure the toolbar through these props rather than styling
+it. By default a panel toolbar keeps its bottom divider, and the work area draws
+one divider under its header chrome and one over its footer chrome, wherever
+that chrome ends; set `dividerSides: ""` to drop a toolbar's divider, for
+example. `responsive: "wrap"` keeps a long title whole and wraps its actions
+below it. `mainBottomToolbar` also takes a `center`. A panel's
+`restorePosition` also places its floating restore controls.
+
+The `Pane`s and `List`s the Workbench composes around your content are
+configurable the same way:
+
+- `mainPane` (`PaneConfig`: `contentElement`, `contentLabel`, `separators`,
+  `safeAreaEdges`) configures the work area's `Pane`, which exists whenever the
+  work area has a toolbar, `mainHeader`, or `mainFooter`;
+- a panel's `pane` configures the `Pane` a `toolbar` panel's `content` renders
+  in — for example `{ contentElement: "nav", contentLabel: "Files" }` for a
+  navigator rail;
+- `mainHeaderList` / `mainFooterList` (`ListConfig`: `gap`, `hAlign`,
+  `vAlign`, `dividerSides`, `textInsets`, `controlInsets`) configure the
+  `List`s holding `mainHeader` / `mainFooter`.
+
+An omitted or `undefined` field keeps today's default, including the header
+and footer dividers described above.
+
+Size a rail so its title and groups fit at its narrowest (a resizable rail's
+`min`); a toolbar that cannot hold them drops the title rather than
+truncating it. `constant` content renders in both places while the panel is
+closed (the panel's copy is inert), so give it no `id`s. With `wireWorkbench`
+given the panel's `collapsed` signal, focus follows the toggle: closing a
+panel from its own toggle focuses the relocated toggle in the work area, and
+opening it from there focuses the panel's own toggle. A panel's optional
+`footer` renders below its content, for a sidebar's bottom toolbar. Without a
+`toolbar` or `mainToolbar`, `content` and `main` render exactly as given.
+
 ## Resizable panels
 
 Resizing is **opt-in per panel**. Give a panel `resizable` — `true` for the

package/llms.txt

@@ -102,11 +102,16 @@ the folder modules, and CSS only imports their owner stylesheets.
   without an application customization layer. Before adding `padding`, `margin`,
   `width`, `height`, `border`, `background`, a wrapper card, or a decoration,
   check whether the component, pane, or content-item already owns it. Prefer a
-  component prop or documented `--kui-*` token. CSS for genuinely new structure
+  component prop — `FloatingToolbar inset`, `DisclosureArrow size`, `ListHeader
+headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
+  visibly bounded content item — over overriding its `--kui-*` token. CSS for genuinely new structure
   belongs to the application-owned component that renders it and must not select
   nested Kerf or Web Awesome components.
 - **Never double-inset.** A `.kui-pane` has no padding; its `.kui-content` children
-  own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
+  own the geometry (8px inline margin + 1px border + 8px padding). Render an
+  ordinary surface-like child as `ContentItem` (`@kerfjs/ui/content-item`) with
+  typed `frame` (`none`/`framed`) and `shape` (`rounded`/`pill`) props instead
+  of hand-writing `<div class="kui-content-item">`. Do not add a
   container padding on top of a content-item's own margin — pick one owner. Use
   `.kui-content` for 24px major vertical rhythm.
 - **Opt into document globals explicitly.** Import `@kerfjs/ui/document.css`
@@ -129,7 +134,7 @@ the folder modules, and CSS only imports their owner stylesheets.
   `@kerfjs/ui/css-values` builders; raw CSS strings are rejected. Use `flex()`
   for List flex, typed lengths for Skeleton geometry, and
   foreground colors for choice icons: `uiColor()` with an `*-on-*`/text token
-  or `foregroundColorVar()`; fill aliases such as `uiColor('success')` do not
+  or `foregroundColorVar()`; fill tokens such as `uiColor('success-fill-quiet')` do not
   type-check. These brands are intentionally
   not interchangeable; rows use classes/tokens/props rather than raw `style`.
 - **Use `Grid` for a fixed positive count of equal-width columns.** It uses
@@ -170,7 +175,21 @@ the folder modules, and CSS only imports their owner stylesheets.
   label uses the same uppercase xs/650 treatment and its label and hint share
   that 9px alignment.
 - `Select` requires a visible `label` or an `ariaLabel` for a visually hidden
-  accessible name. The package names the internal combobox, including custom
+  accessible name. Set `multiple` with an array `value` for any number of
+  choices: the popup stays open while choices toggle and closes on an outside
+  press or Escape, and the closed control summarizes the chosen labels. A
+  toolbar filter menu adds `selectedPresentation="icon-only"` and a fixed
+  `triggerIcon`: the trigger shows that icon plus a count badge while any
+  choice is chosen, and its accessible name ends with the chosen labels.
+  Icon-only Selects (single or multiple) and icon-only `PopupMenu`s show an
+  `aria-hidden` Web Awesome help tag repeating that name (and a Select's
+  choice) on hover and keyboard focus, hidden while the popup is open; the
+  register import installs it, so do not add a `title` or tooltip of your own.
+  The same installer tags an icon-only `<button>` or link inside a
+  `ToolbarControlGroup` named by `aria-label` (no visible text or `title`);
+  import `@kerfjs/ui/help-tags/register` once when a toolbar has such buttons
+  but no registered Select or PopupMenu.
+  The package names the internal combobox, including custom
   selected content; consumers do not need shadow-DOM naming workarounds.
   Import `select/register` once for the canonical animation lifecycle: stale
   close/show completions cannot override a later request. Consumers must not
@@ -187,10 +206,10 @@ the folder modules, and CSS only imports their owner stylesheets.
   `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. For an
   ordinary icon/action control inside the group use a **plain `<button>`** (the
   group styles it fully) — that is the default; reach for `wa-button` only when you
-  need a Web Awesome feature, chiefly the `slot="trigger"` button of a `wa-dropdown`
-  popup menu. A toolbar popup menu is a `single` `ToolbarControlGroup` around a
-  `wa-dropdown` (its `slot="trigger"` `wa-button` is the toolbar button, kept under
-  `data-morph-skip-children`). Let the group size the trigger from its icon,
+  need a Web Awesome feature. A toolbar popup menu is a `PopupMenu`
+  (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`)
+  in a `single` `ToolbarControlGroup` with `nestedDropdown`; never hand-write
+  `wa-dropdown` markup for a menu. Let the group size the trigger from its icon,
   localized text, and caret; do not force a dropdown or button width. Compact
   mixed groups keep standard item padding and raised selected chrome without an
   internal separator; the selected item paints over the outer border. For an
@@ -227,6 +246,11 @@ the folder modules, and CSS only imports their owner stylesheets.
   scrolling `.kui-pane__content`, optional `.kui-pane__footer`). A visible pane owns
   its collapse control; a hidden pane's restore moves to the adjacent main
   toolbar's matching edge — no icon-only rail. Keep one scroll owner per region.
+  While a side overlay is open (a Workbench rail overlay, a `wireSidebar` compact
+  overlay, an overlay `CollapsiblePanel` or horizontal `ResizableRegion`), the
+  layout hides the covered work area's `FloatingToolbar`s and restore corners
+  itself (unfocusable, out of the accessibility tree) until it closes — do not
+  hide them from overlay state yourself.
 - **State and behavior live in the app.** Components take semantic `data-action`
   strings and controlled values; wire them once with `delegate()`/`delegateActions()`
   or the disposer-returning `wire…` helpers, and own domain copy, transport, and
@@ -249,7 +273,8 @@ the folder modules, and CSS only imports their owner stylesheets.
   editor focus before the next input task, so shortcut-letter typing stays in search.
   Select All deletion does the same; deletion
   restoration finishes before the next keystroke rather than on a delayed frame.
-  Persist both query and remaining tokens read from an edited field. The one richer case is `wireTokenSearchFields`, which manages the
+  Persist both query and remaining tokens read from an edited field; change
+  `revision` to replace its DOM-owned text programmatically. The one richer case is `wireTokenSearchFields`, which manages the
   collapsible field's expand/collapse/focus by default (on, per-behavior opt-out) and
   exposes the `expanded` signal on its handle — bind it in render or hand in your own
   via `collapsible.signals`. Do not hand-roll open/collapse/focus that helper
@@ -289,6 +314,10 @@ the folder modules, and CSS only imports their owner stylesheets.
 - **Use `Badge` for compact non-interactive metadata.** Configure its semantic
   tone, appearance, shape, and size instead of creating badge CSS in an app or
   consuming component. Use a real button or link for interactive content.
+  For new content without a count, use the text-free `size="dot"` form: it
+  takes no children, and needs a `label` (announced as an image) or
+  `ariaHidden` when its owner announces it. A `TabScaffold` tab shows the dot
+  with `badge: true` plus its required `badgeLabel`.
 
 ## Public exports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.54",
+  "version": "5.0.0-beta.56",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,9 @@
   "sideEffects": [
     "**/*.css",
     "./dist/browser/*.js",
-    "./dist/select-register.js"
+    "./dist/select-register.js",
+    "./dist/popup-menu-register.js",
+    "./dist/help-tags-register.js"
   ],
   "exports": {
     ".": {
@@ -138,6 +140,11 @@
       "browser": "./dist/browser/list-inset-text.js",
       "import": "./dist/list-inset-text.js"
     },
+    "./content-item": {
+      "types": "./dist/content-item.d.ts",
+      "browser": "./dist/browser/content-item.js",
+      "import": "./dist/content-item.js"
+    },
     "./resizable-region": {
       "types": "./dist/resizable-region.d.ts",
       "browser": "./dist/browser/resizable-region.js",
@@ -268,10 +275,23 @@
       "types": "./dist/wire-token-search-fields.d.ts",
       "import": "./dist/wire-token-search-fields.js"
     },
+    "./popup-menu": {
+      "types": "./dist/popup-menu.d.ts",
+      "browser": "./dist/browser/popup-menu.js",
+      "import": "./dist/popup-menu.js"
+    },
+    "./popup-menu/register": {
+      "types": "./dist/popup-menu-register.d.ts",
+      "import": "./dist/popup-menu-register.js"
+    },
     "./select/register": {
       "types": "./dist/select-register.d.ts",
       "import": "./dist/select-register.js"
     },
+    "./help-tags/register": {
+      "types": "./dist/help-tags-register.d.ts",
+      "import": "./dist/help-tags-register.js"
+    },
     "./webawesome": {
       "types": "./dist/webawesome.d.ts",
       "import": "./dist/webawesome.js"
@@ -318,6 +338,7 @@
     "./list-header.css": "./dist/styles/list-header.css",
     "./list-inset-control.css": "./dist/styles/list-inset-control.css",
     "./list-inset-text.css": "./dist/styles/list-inset-text.css",
+    "./content-item.css": "./dist/styles/content-item.css",
     "./resizable-region.css": "./dist/styles/resizable-region.css",
     "./app-tab.css": "./dist/styles/app-tab.css",
     "./catalog.css": "./dist/styles/catalog.css",
@@ -330,6 +351,7 @@
     "./tab-scaffold.css": "./dist/styles/tab-scaffold.css",
     "./loading-spinner.css": "./dist/styles/loading-spinner.css",
     "./select.css": "./dist/styles/select.css",
+    "./popup-menu.css": "./dist/styles/popup-menu.css",
     "./skeleton.css": "./dist/styles/skeleton.css",
     "./sunken-panel.css": "./dist/styles/sunken-panel.css",
     "./segmented-control.css": "./dist/styles/segmented-control.css",