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

package/dist/workbench.d.ts

@@ -1,32 +1,189 @@
 import { SafeHtml } from 'kerfjs';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { a as PanelToolbar, b as PanelToggle } from './panel-toolbar-BFQxFITu.js';
+import { ToolbarProps } from './toolbar.js';
+import './lucide-icon.js';
+import 'lucide';
+import './divider-sides-BzB6rphT.js';
+import './pane.js';
 
+/** The standard toggle a Workbench renders for a panel (see {@link PanelToggle}). */
+type WorkbenchPanelToggle = PanelToggle;
+/**
+ * A Workbench panel's top toolbar, composed by the Workbench so its groups can
+ * follow the panel's open state (see {@link PanelToolbar} for the roles).
+ * A collapsed rail's `constant` groups and toggle go to the leading edge of
+ * `mainToolbar` (left rail) or its trailing edge (right rail); a collapsed
+ * drawer's go to the trailing edge of `mainBottomToolbar`, else to a
+ * `FloatingToolbar` in the work area's bottom-end corner.
+ */
+type WorkbenchPanelToolbar = PanelToolbar;
+/** The work area's top toolbar; collapsed rails add their groups to it. */
+interface WorkbenchMainToolbar {
+    label: string;
+    /** The work area's title, usually an extra-large `ToolbarText`. */
+    title?: KerfUiContent;
+    /** Groups after the title. */
+    leading?: KerfUiContent;
+    center?: KerfUiContent;
+    /** Groups at the trailing edge, before a collapsed right rail's groups. */
+    trailing?: KerfUiContent;
+    /** The toolbar's narrow-width policy (see `Toolbar.responsive`). */
+    responsive?: ToolbarProps['responsive'];
+    responsiveAt?: ToolbarProps['responsiveAt'];
+}
+/** The work area's bottom toolbar; a collapsed drawer adds its groups to it. */
+interface WorkbenchMainBottomToolbar {
+    label: string;
+    leading?: KerfUiContent;
+    trailing?: KerfUiContent;
+}
+/**
+ * The work area: the app's `main` under `mainToolbar` (and above
+ * `mainBottomToolbar`), with each collapsed panel's groups added to the
+ * toolbar on its side. Without either toolbar, `main` renders as given.
+ */
+/**
+ * Whether the work area's header or footer chrome stays pinned (`fixed`) or
+ * scrolls away with the content (`scroll`).
+ */
+type WorkbenchChromePlacement = 'fixed' | 'scroll';
+
+/**
+ * The Workbench container breakpoint below which a panel presents as an
+ * overlay: `narrow` (704px or less) or `compact` (448px or less) — the same
+ * breakpoints as `ResizableRegion`'s `responsiveFillAt` — or `never` to keep
+ * it inline at every width.
+ */
+type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never';
+/**
+ * How wide a rail's overlay is in a compact (448px or less) Workbench: `inset`
+ * fills the Workbench less a dismiss margin on the side away from the rail's
+ * edge, so a press beside it closes it; `full` fills the Workbench.
+ */
+type WorkbenchCompactOverlay = 'inset' | 'full';
+/** Drag-resize limits for a resizable Workbench panel, in px. */
+interface WorkbenchPanelResizable {
+    /** Smallest size (default 180 for a rail, 120 for the drawer). */
+    min?: number;
+    /** Largest size (default 480). */
+    max?: number;
+}
 /** A collapsible Workbench panel — a side rail or the bottom drawer. */
 interface WorkbenchPanel {
     content: KerfUiContent;
+    /**
+     * The panel's top toolbar, composed by the Workbench: its `constant` groups
+     * and standard `toggle` move to the work area's toolbar while the panel is
+     * collapsed. With it, `content` renders in a `Pane` below the toolbar.
+     */
+    toolbar?: WorkbenchPanelToolbar;
+    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    footer?: KerfUiContent;
     /** Whether the panel is currently collapsed (the app owns this). */
     collapsed?: boolean;
-    /** Rail width, or drawer height, in px. Overrides the CSS default. */
+    /**
+     * Rail width, or drawer height, in px. Overrides the CSS default. For a
+     * resizable panel it is the current size (default 280 for a rail, 220 for
+     * the drawer), clamped to the limits; the app owns it and `wireWorkbench`
+     * reports each resize.
+     */
     size?: number;
+    /**
+     * Opt in to drag and keyboard resizing on the panel's inner separator:
+     * `true` for the default limits, or `{ min, max }`. Off by default. Pair it
+     * with `wireWorkbench` from `@kerfjs/ui/wire-workbench`.
+     */
+    resizable?: boolean | WorkbenchPanelResizable;
     /** Accessible name for the panel region. */
     label?: string;
     separator?: ResizableRegionSeparator;
     collapseMotion?: ResizableRegionCollapseMotion;
     contentOverflow?: ResizableRegionContentOverflow;
     presentation?: ResizableRegionPresentation;
-    /** Control shown in a safe-area-aware viewport corner while collapsed. */
+    /**
+     * Present the panel as an overlay, without a separator, below a Workbench
+     * container breakpoint, and inline above it — the CSS decides, so the app
+     * needs no device-class check. A rail overlays from its side at full
+     * height, over the work area and an open drawer; the bottom drawer
+     * overlays the bottom of the work-area column. Rails default to `narrow`
+     * (pass `never` to keep one inline); the drawer defaults to inline.
+     */
+    responsiveOverlayAt?: WorkbenchResponsiveOverlayAt;
+    /**
+     * A rail's overlay width in a compact Workbench (default `inset`: the
+     * Workbench less `--kui-workbench-overlay-dismiss-margin`, 44px). Ignored
+     * by the drawer.
+     */
+    compactOverlay?: WorkbenchCompactOverlay;
+    /**
+     * Control shown while collapsed, in a safe-area-aware corner of the
+     * Workbench (not the viewport); the bottom drawer's sits in the work-area
+     * column. Prefer `toolbar.toggle`, which the Workbench relocates into the
+     * work area's toolbar (or this corner when that toolbar is absent).
+     */
     restoreControl?: SafeHtml;
     restorePosition?: ResizableRegionRestorePosition;
 }
 interface WorkbenchProps {
+    /**
+     * The Workbench's `id`. Each panel's `id` derives from it —
+     * `<id>-left-rail`, `<id>-right-rail`, `<id>-bottom-drawer` — so a toggle
+     * can name the panel it shows and hides with `aria-controls`.
+     */
     id: string;
     label: string;
     /** The central work area. */
     main: KerfUiContent;
+    /**
+     * The work area's top toolbar. A collapsed left rail's `constant` groups
+     * and toggle lead it; a collapsed right rail's trail it. With it, `main`
+     * renders in a `Pane` below the toolbar.
+     */
+    mainToolbar?: WorkbenchMainToolbar;
+    /**
+     * Fixed content under `mainToolbar` — supporting copy such as a
+     * description — divided from the scrolling `main` below it.
+     */
+    mainHeader?: KerfUiContent;
+    /**
+     * Fixed content over `mainBottomToolbar` — a status line or a resource
+     * toolbar — divided from the scrolling `main` above it.
+     */
+    mainFooter?: KerfUiContent;
+    /**
+     * The work area's bottom toolbar. A collapsed drawer's `constant` groups and
+     * toggle trail it; without it they float in the work area's corner.
+     */
+    mainBottomToolbar?: WorkbenchMainBottomToolbar;
+    /**
+     * Whether `mainToolbar` and `mainHeader` stay pinned (`fixed`, default) or
+     * scroll away with `main` (`scroll`) — useful where large text would leave
+     * pinned chrome little room.
+     */
+    mainHeaderPlacement?: WorkbenchChromePlacement;
+    /** The same for `mainFooter` and `mainBottomToolbar` (default `fixed`). */
+    mainFooterPlacement?: WorkbenchChromePlacement;
     leftRail?: WorkbenchPanel;
     rightRail?: WorkbenchPanel;
     bottomDrawer?: WorkbenchPanel;
+    /**
+     * Minimum width, in px, the work area keeps beside the inline rails, fixed
+     * or `resizable` (default 320; `0` turns it off). Resizing a rail stops
+     * where the work area would drop below it, and inline rails shrink
+     * proportionally when the Workbench gets narrower. Workbenches without a
+     * rail ignore it.
+     */
+    mainMinSize?: number;
+    /**
+     * Minimum height, in px, the work area keeps above an inline bottom drawer,
+     * fixed or `resizable` (default 120; `0` turns it off) — the drawer's
+     * counterpart of `mainMinSize`. Resizing the drawer stops where the work
+     * area would drop below it, and the drawer shrinks when the Workbench gets
+     * shorter. Workbenches without a drawer ignore it.
+     */
+    mainMinHeight?: number;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -38,9 +195,12 @@ interface WorkbenchProps {
  * a composited transform — the instant-width / sliding-content technique, so the
  * work area relayouts once, not per frame. Bottom-drawer content stays anchored
  * to the shell's stable bottom edge throughout that transition. The app owns
- * each `collapsed` flag; the collapse is pure CSS (no wire). See
- * `docs/23-app-layouts.md` §3.3.
+ * each `collapsed` flag; the collapse is pure CSS. A collapsed panel renders
+ * `inert` and `aria-hidden`, so neither Tab nor assistive technology reaches
+ * controls that have slid out of view or an empty landmark (its restore control
+ * lives outside it and stays reachable). A panel may opt in to drag and keyboard resizing with
+ * `resizable`, which `wireWorkbench` drives. See `docs/23-app-layouts.md` §3.3.
  */
-declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className, slot, }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainMinSize, mainMinHeight, className, slot, }: WorkbenchProps): SafeHtml;
 
-export { Workbench, type WorkbenchPanel, type WorkbenchProps };
+export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };

package/dist/workbench.js

@@ -1,108 +1,15 @@
-import { jsxs, jsx } from 'kerfjs/jsx-runtime';
+export { Workbench } from './chunk-EAX2GSS4.js';
+
+
+
+
+
+
+
+
+
+
 
-// src/workbench.tsx
-function Workbench({
-  id,
-  label,
-  main,
-  leftRail,
-  rightRail,
-  bottomDrawer,
-  className = "",
-  slot
-}) {
-  return /* @__PURE__ */ jsxs(
-    "section",
-    {
-      class: `kui-workbench ${className}`.trim(),
-      id,
-      "data-component": "workbench",
-      "aria-label": label,
-      slot,
-      children: [
-        leftRail && /* @__PURE__ */ jsx(
-          "aside",
-          {
-            class: "kui-workbench__rail kui-workbench__rail--left",
-            "data-workbench-rail": "left",
-            "data-collapsed": String(leftRail.collapsed ?? false),
-            "data-separator": leftRail.separator ?? "auto",
-            "data-collapse-motion": leftRail.collapseMotion ?? "slide",
-            "data-content-overflow": leftRail.contentOverflow ?? "clip",
-            "data-presentation": leftRail.presentation ?? "inline",
-            "aria-label": leftRail.label || void 0,
-            "aria-hidden": leftRail.presentation === "hidden" ? "true" : void 0,
-            style: leftRail.size ? `--kui-workbench-rail-width: ${leftRail.size}px` : void 0,
-            children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: leftRail.content })
-          }
-        ),
-        leftRail?.collapsed && leftRail.restoreControl && leftRail.presentation !== "hidden" && /* @__PURE__ */ jsx(
-          "div",
-          {
-            class: "kui-workbench__restore",
-            "data-panel": "left",
-            "data-position": leftRail.restorePosition ?? "bottom-start",
-            children: leftRail.restoreControl
-          }
-        ),
-        /* @__PURE__ */ jsxs("div", { class: "kui-workbench__center", children: [
-          /* @__PURE__ */ jsx("div", { class: "kui-workbench__main", "data-workbench-main": true, children: main }),
-          bottomDrawer && /* @__PURE__ */ jsx(
-            "section",
-            {
-              class: "kui-workbench__drawer",
-              "data-workbench-drawer": true,
-              "data-collapsed": String(bottomDrawer.collapsed ?? false),
-              "data-separator": bottomDrawer.separator ?? "auto",
-              "data-collapse-motion": bottomDrawer.collapseMotion ?? "slide",
-              "data-content-overflow": bottomDrawer.contentOverflow ?? "clip",
-              "data-presentation": bottomDrawer.presentation ?? "inline",
-              "aria-label": bottomDrawer.label || void 0,
-              "aria-hidden": bottomDrawer.presentation === "hidden" ? "true" : void 0,
-              style: bottomDrawer.size ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px` : void 0,
-              children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: bottomDrawer.content })
-            }
-          ),
-          bottomDrawer?.collapsed && bottomDrawer.restoreControl && bottomDrawer.presentation !== "hidden" && /* @__PURE__ */ jsx(
-            "div",
-            {
-              class: "kui-workbench__restore",
-              "data-panel": "bottom",
-              "data-position": bottomDrawer.restorePosition ?? "bottom-end",
-              children: bottomDrawer.restoreControl
-            }
-          )
-        ] }),
-        rightRail && /* @__PURE__ */ jsx(
-          "aside",
-          {
-            class: "kui-workbench__rail kui-workbench__rail--right",
-            "data-workbench-rail": "right",
-            "data-collapsed": String(rightRail.collapsed ?? false),
-            "data-separator": rightRail.separator ?? "auto",
-            "data-collapse-motion": rightRail.collapseMotion ?? "slide",
-            "data-content-overflow": rightRail.contentOverflow ?? "clip",
-            "data-presentation": rightRail.presentation ?? "inline",
-            "aria-label": rightRail.label || void 0,
-            "aria-hidden": rightRail.presentation === "hidden" ? "true" : void 0,
-            style: rightRail.size ? `--kui-workbench-rail-width: ${rightRail.size}px` : void 0,
-            children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: rightRail.content })
-          }
-        ),
-        rightRail?.collapsed && rightRail.restoreControl && rightRail.presentation !== "hidden" && /* @__PURE__ */ jsx(
-          "div",
-          {
-            class: "kui-workbench__restore",
-            "data-panel": "right",
-            "data-position": rightRail.restorePosition ?? "bottom-end",
-            children: rightRail.restoreControl
-          }
-        )
-      ]
-    }
-  );
-}
 
-export { Workbench };
 
 //# sourceMappingURL=workbench.js.map

package/dist/workbench.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/workbench.tsx"],"names":[],"mappings":"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","file":"workbench.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nimport type {\n  ResizableRegionCollapseMotion,\n  ResizableRegionContentOverflow,\n  ResizableRegionPresentation,\n  ResizableRegionRestorePosition,\n  ResizableRegionSeparator,\n} from './resizable-region.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\n/** A collapsible Workbench panel — a side rail or the bottom drawer. */\nexport interface WorkbenchPanel {\n  content: KerfUiContent;\n  /** Whether the panel is currently collapsed (the app owns this). */\n  collapsed?: boolean;\n  /** Rail width, or drawer height, in px. Overrides the CSS default. */\n  size?: number;\n  /** Accessible name for the panel region. */\n  label?: string;\n  separator?: ResizableRegionSeparator;\n  collapseMotion?: ResizableRegionCollapseMotion;\n  contentOverflow?: ResizableRegionContentOverflow;\n  presentation?: ResizableRegionPresentation;\n  /** Control shown in a safe-area-aware viewport corner while collapsed. */\n  restoreControl?: SafeHtml;\n  restorePosition?: ResizableRegionRestorePosition;\n}\n\nexport interface WorkbenchProps {\n  id: string;\n  label: string;\n  /** The central work area. */\n  main: KerfUiContent;\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  bottomDrawer?: WorkbenchPanel;\n  className?: string;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\n/**\n * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and\n * bottom drawer around a central work area (any absent). Collapsing snaps the\n * panel's track to zero in one reflow while its fixed-size content slides out via\n * a composited transform — the instant-width / sliding-content technique, so the\n * work area relayouts once, not per frame. Bottom-drawer content stays anchored\n * to the shell's stable bottom edge throughout that transition. The app owns\n * each `collapsed` flag; the collapse is pure CSS (no wire). See\n * `docs/23-app-layouts.md` §3.3.\n */\nexport function Workbench({\n  id,\n  label,\n  main,\n  leftRail,\n  rightRail,\n  bottomDrawer,\n  className = '',\n  slot,\n}: WorkbenchProps) {\n  return (\n    <section\n      class={`kui-workbench ${className}`.trim()}\n      id={id}\n      data-component=\"workbench\"\n      aria-label={label}\n      slot={slot}\n    >\n      {leftRail && (\n        <aside\n          class=\"kui-workbench__rail kui-workbench__rail--left\"\n          data-workbench-rail=\"left\"\n          data-collapsed={String(leftRail.collapsed ?? false)}\n          data-separator={leftRail.separator ?? 'auto'}\n          data-collapse-motion={leftRail.collapseMotion ?? 'slide'}\n          data-content-overflow={leftRail.contentOverflow ?? 'clip'}\n          data-presentation={leftRail.presentation ?? 'inline'}\n          aria-label={leftRail.label || undefined}\n          aria-hidden={leftRail.presentation === 'hidden' ? 'true' : undefined}\n          style={\n            leftRail.size\n              ? `--kui-workbench-rail-width: ${leftRail.size}px`\n              : undefined\n          }\n        >\n          <div class=\"kui-workbench__panel-content\">{leftRail.content}</div>\n        </aside>\n      )}\n      {leftRail?.collapsed &&\n        leftRail.restoreControl &&\n        leftRail.presentation !== 'hidden' && (\n          <div\n            class=\"kui-workbench__restore\"\n            data-panel=\"left\"\n            data-position={leftRail.restorePosition ?? 'bottom-start'}\n          >\n            {leftRail.restoreControl}\n          </div>\n        )}\n      <div class=\"kui-workbench__center\">\n        <div class=\"kui-workbench__main\" data-workbench-main>\n          {main}\n        </div>\n        {bottomDrawer && (\n          <section\n            class=\"kui-workbench__drawer\"\n            data-workbench-drawer\n            data-collapsed={String(bottomDrawer.collapsed ?? false)}\n            data-separator={bottomDrawer.separator ?? 'auto'}\n            data-collapse-motion={bottomDrawer.collapseMotion ?? 'slide'}\n            data-content-overflow={bottomDrawer.contentOverflow ?? 'clip'}\n            data-presentation={bottomDrawer.presentation ?? 'inline'}\n            aria-label={bottomDrawer.label || undefined}\n            aria-hidden={\n              bottomDrawer.presentation === 'hidden' ? 'true' : undefined\n            }\n            style={\n              bottomDrawer.size\n                ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px`\n                : undefined\n            }\n          >\n            <div class=\"kui-workbench__panel-content\">\n              {bottomDrawer.content}\n            </div>\n          </section>\n        )}\n        {bottomDrawer?.collapsed &&\n          bottomDrawer.restoreControl &&\n          bottomDrawer.presentation !== 'hidden' && (\n            <div\n              class=\"kui-workbench__restore\"\n              data-panel=\"bottom\"\n              data-position={bottomDrawer.restorePosition ?? 'bottom-end'}\n            >\n              {bottomDrawer.restoreControl}\n            </div>\n          )}\n      </div>\n      {rightRail && (\n        <aside\n          class=\"kui-workbench__rail kui-workbench__rail--right\"\n          data-workbench-rail=\"right\"\n          data-collapsed={String(rightRail.collapsed ?? false)}\n          data-separator={rightRail.separator ?? 'auto'}\n          data-collapse-motion={rightRail.collapseMotion ?? 'slide'}\n          data-content-overflow={rightRail.contentOverflow ?? 'clip'}\n          data-presentation={rightRail.presentation ?? 'inline'}\n          aria-label={rightRail.label || undefined}\n          aria-hidden={rightRail.presentation === 'hidden' ? 'true' : undefined}\n          style={\n            rightRail.size\n              ? `--kui-workbench-rail-width: ${rightRail.size}px`\n              : undefined\n          }\n        >\n          <div class=\"kui-workbench__panel-content\">{rightRail.content}</div>\n        </aside>\n      )}\n      {rightRail?.collapsed &&\n        rightRail.restoreControl &&\n        rightRail.presentation !== 'hidden' && (\n          <div\n            class=\"kui-workbench__restore\"\n            data-panel=\"right\"\n            data-position={rightRail.restorePosition ?? 'bottom-end'}\n          >\n            {rightRail.restoreControl}\n          </div>\n        )}\n    </section>\n  );\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"workbench.js"}

package/docs/accessibility.md

@@ -12,6 +12,7 @@ These are normative contracts for package components and consuming applications.
 - `wireNavStack` moves focus into every newly active top view and remembers the last focused descendant of each mounted view for pop restoration. Mark a preferred initial heading or control with `data-nav-focus` (and `tabindex="-1"` when it is not normally tabbable); otherwise the helper uses the first enabled focusable descendant, then a programmatically focusable view-container fallback.
 - In any `.kui-pane`, menu rows, `ListHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `ListHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-list-header-action-icon-size` inside a fitted 36px hover square; a transparent hit layer extends the pointer target to at least 44 × 44 around that square without moving layout or enlarging the painted surface. Compact headers are 36px tall like the rest of the compact List family, so their action target is 44px wide and clamped to the 36px header height instead of reaching into a neighboring row. Do not reduce the target to the visible icon, and do not force the button itself to 44px.
 - `LoadingSpinner` is either labeled (`role="img"`) or hidden. Its rotation stops for reduced motion.
+- An unlabeled `Skeleton` (including the value slots a component's `placeholder` prop renders) is decorative loading chrome: it is `aria-hidden`, conveys no information a user needs to act on, and is deliberately exempt from the WCAG 3:1 non-text-contrast target. Inside a solid `Badge` it stays subtle (about 2.1–4.4:1 in light, 2.4–2.8:1 in dark, depending on tone); `tests/browser/tone-contrast.spec.ts` holds those values as a regression floor rather than an accessibility threshold. Announce loading through a labeled `Skeleton`, `LoadingSpinner`, or `aria-busy` on the owning region, never through the skeleton's visibility.
 - `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.
@@ -34,7 +35,7 @@ Use `presentation="toolbar-borderless"` inside a `ToolbarControlGroup`, with
 parent paints the composed focus ring. `selectedPresentation="icon-only"` hides
 only the visible selected label—the required `label` or `ariaLabel` still names
 the combobox. An icon-only trigger keeps its disclosure caret: the selected icon
-and caret form one pill with the same geometry as a popup-menu `wa-dropdown`
+and caret form one pill with the same geometry as a `PopupMenu`
 trigger (8px inline padding on both sides, 12px from the icon to the caret, a
 40px default or 32px compact control height), so the caret still signals a
 choice list. Inside a group the trigger is inset evenly on every side (2px in a
@@ -80,6 +81,17 @@ 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.
 
+## PopupMenu
+
+`PopupMenu` renders a Web Awesome dropdown, so the menu roles, arrow-key and
+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
+chosen; disable the whole trigger only when every command is unavailable.
+
 ## ListActionRow
 
 `ListActionRow` renders a noninteractive visual root containing primary and
@@ -120,6 +132,15 @@ The handle exposes separator role, orientation, name, minimum, maximum, and curr
   them after a re-render writes the rendered props back, so assistive
   technology never reads an unclamped size between interactions (the
   disposer disconnects both observers);
+- a truthful value below the minimum: when the container shows the track at
+  less than `min` (a narrowing `Workbench` squeezes its resizable rails), the
+  handle reports that shown size in `aria-valuenow` and pins `aria-valuemin`
+  and `aria-valuemax` to it — WAI-ARIA requires the value to lie inside the
+  range, and the separator cannot move a track its container holds. A pinned
+  separator — squeezed, or with a reachable range collapsed to one size —
+  commits nothing: arrow keys, Home/End, and drags leave the app's size (and
+  its storage) as it was, so the track returns to it, with the rendered range,
+  once it has room;
 - a whole hit target and focus ring at a clamped edge: when the separator has
   less room past it than the handle's 10px overhang (a parent clamps the track
   to its own edge), the region carries `data-handle-inset` and the handle sits
@@ -162,7 +183,10 @@ 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` — where it sits.
+and — via `position` and `--kui-floating-toolbar-inset`, set on the toolbar
+or an ancestor — where it sits. Inside a `Workbench`, `CollapsiblePanel`, or
+`ResizableRegion` `restoreControl` the restore corner owns the inset, so the
+toolbar floats from that corner.
 
 ## Tabs
 
@@ -180,8 +204,11 @@ that geometry; applications must not override its anatomy to create the split.
 presentations. Icon-only tabs keep the required `name` as the tab button's
 accessible name while visually hiding the duplicate label. A `pending` tab (known,
 still opening) keeps its visible name as the tab button's accessible name, so a
-trailing spinner's own label is not folded into it; like `placeholder`, it is
-`aria-busy`, disabled, out of the tab order, and not draggable. These props own
+trailing spinner's own label is not folded into it. It is `aria-busy` and stays
+selectable (in the roving tab order like a live tab), so the application can
+show placeholder content in its panel until loading completes; its close
+button is disabled and hidden and it is not draggable. A `placeholder` tab
+(unknown) is instead disabled, out of the tab order, and not draggable. These props own
 component appearance only; the application still owns the bar's outer placement.
 `AppTab.rootAttributes` accepts application `data-*` metadata only; runtime
 filtering rejects roles plus case variants of component- or wiring-owned
@@ -192,8 +219,11 @@ and must not contain interactive descendants.
 activation, same-bar pointer reordering, `Alt+Shift+ArrowLeft/ArrowRight`
 reordering, focus restoration, scroll-into-view, and pointer-proximity
 autoscroll at either horizontal edge. Edge autoscroll is direct manipulation,
-stops on drop/drag end/disposal, and does not change keyboard behavior. It
-returns a disposer.
+stops on drop/drag end/disposal, and does not change keyboard behavior. When
+the application changes a bar's selected tab without focus (adding and
+selecting a tab), the wiring scrolls that tab's strip — never the page — so
+the new selection is fully visible; a re-render that keeps the same selection
+leaves a strip the user scrolled where it is. It returns a disposer.
 
 Arrow / Home / End follow the ARIA Tabs **automatic-activation** pattern by
 default: they move roving focus and select the focused tab. If selection synchronously
@@ -276,15 +306,26 @@ and focus deliberately moved to another control; no app-level reopen callback is
 
 ## CollapsiblePanel / sidebar
 
-`CollapsiblePanel` is a labeled `aside` region that is `aria-hidden` while
-collapsed; its content slides via transform (disabled under reduced motion).
+`CollapsiblePanel` is a labeled `aside` region that renders `inert` and
+`aria-hidden` while collapsed, straight from the app's `collapsed` flag, so its
+controls leave the Tab order and the accessibility tree even while the content
+is still sliding out, and focusing one can never scroll clipped content back into
+view (`aria-hidden` alone left them focusable inside a hidden subtree). Its
+content slides via transform (disabled under reduced motion); `inert` does not
+affect rendering, so the slide still plays. A `restoreControl` renders outside
+the panel and stays reachable. A collapsed `ResizableRegion` renders `inert` and
+`aria-hidden` on the region itself the same way (its content wrapper is `inert`
+too, and its separator is already hidden and not displayed), so no empty
+labeled region landmark stays behind; its `restoreControl` stays outside the
+region.
 `CollapsiblePanelToggle` is a named button carrying `aria-expanded` and the
 standard per-side collapse/expand glyph (`PanelLeft*` / `PanelRight*` /
 `PanelBottom*`); place a collapse toggle inside the panel and an expand toggle in
 an always-visible location so it is reachable while collapsed. `wireSidebar()`
 moves focus into the panel when it opens and restores it to the trigger when it
-closes; a trigger inside the now-hidden panel hands focus to the panel's toggle
-outside it instead, so an app may render the expand toggle only while the panel
+closes; a trigger inside the now-inert panel hands focus to the panel's toggle
+outside it instead (and focus stranded there by a wide → compact crossing is
+rescued the same way), so an app may render the expand toggle only while the panel
 is collapsed. When a `deviceClass()` reports `compact`, an open panel becomes an overlay
 with a dismissable backdrop, Escape and backdrop-click collapse it, and Tab is
 trapped within it (the ARIA dialog pattern). That modal state only ever begins
@@ -293,6 +334,21 @@ crossing, every panel starts collapsed, so no page load or resize traps focus. T
 signal, the panels, their sizes, and content; the wire may persist the collapsed
 state per panel.
 
+## Workbench
+
+Each `Workbench` rail and drawer is a labeled region (`aside` for a rail, `section`
+for the drawer). While a panel is collapsed the region itself renders `inert` and
+`aria-hidden="true"`, and so does not linger as an empty landmark, and its content
+wrapper is `inert`, all rendered from the app's `collapsed` flag, so its controls
+leave the Tab order and the accessibility tree even while the content is still
+sliding out, and focusing one can never scroll clipped content back into view. The panel's `restoreControl` renders
+outside that content and stays reachable; a resizable panel's separator also leaves
+the Tab order while collapsed or not inline. `wireWorkbench`, given a panel's
+`collapsed` signal, returns focus stranded in a closing panel to the control that
+opened it, else the restore control, else a control whose `aria-controls` names the
+panel; an open overlay panel takes focus and keeps Tab inside it (the ARIA dialog
+pattern). See [`workbench.md`](workbench.md).
+
 ## Verification matrix
 
 For each changed component, inspect default, hover, focus, disabled, selected/pressed, busy/error, long-content, wide, narrow, light, dark, increased-contrast, reduced-motion, keyboard-only, and 200%-zoom states where applicable. DOM order must match reading and focus order, with no clipping or unreachable action.

package/docs/app-layouts.md

@@ -113,7 +113,18 @@ device in tests.
   selection).
 - **IDE (complex tool):** `Workbench` with a left navigator rail, a right
   inspector rail, and a bottom console drawer, each `collapsed` bound to a
-  signal. Only offer this `atLeast('desktop')`.
+  signal. Only offer this `atLeast('desktop')`. To let people size the
+  navigator or console, opt those panels in with `resizable` and call
+  `wireWorkbench` with their size signals and `deviceClass`; resizing is
+  suspended on `compact`, where the rails become overlay drawers — or give each
+  rail `responsiveOverlayAt: "narrow"` and let the Workbench's own width decide
+  when it overlays, with no device check; pass each rail's `collapsed` signal
+  to `wireWorkbench` so the overlay starts collapsed, takes focus and keeps Tab
+  inside it while open, and closes on Escape or an outside press. Inline
+  rails, fixed or resizable, leave the editor its `mainMinSize` (320px by
+  default) and shrink in proportion when the window narrows; the bottom drawer
+  leaves it `mainMinHeight` (120px by default) and shrinks when the window gets
+  shorter.
 - **Social app (tabbed):** `TabScaffold` with Home / Search / Profile tabs, each
   `content` a `NavStack`. On a tablet/desktop, render the same sections as a
   `Workbench` left rail instead of a bottom bar.

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,12 @@ 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 the
+  status + resource footer stay pinned (`fixed`, default) or scroll with the preview
+  (`scroll`) — useful where large text would leave pinned chrome little room.
 - **`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 +412,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`.