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

package/dist/workbench.d.ts

@@ -1,13 +1,77 @@
 import { SafeHtml } from 'kerfjs';
+import { ListConfig } from './list.js';
+import { PaneConfig } from './pane.js';
 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-C8sF-YZC.js';
+import { ToolbarConfig } from './toolbar.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './sides-BPSWde0A.js';
+import './lucide-icon.js';
+import 'lucide';
+
+/** 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. Its
+ * configuration forwards to its `Toolbar`. By default it draws the divider
+ * under the work area's header chrome: its own bottom edge, or none when a
+ * `mainHeader` follows (which then carries the divider).
+ */
+interface WorkbenchMainToolbar extends ToolbarConfig {
+    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 work area's bottom toolbar; a collapsed drawer adds its groups to it.
+ * Its configuration forwards to its `Toolbar`. By default it draws the divider
+ * over the work area's footer chrome: its own top edge, or none when a
+ * `mainFooter` precedes it.
+ */
+interface WorkbenchMainBottomToolbar extends ToolbarConfig {
+    label: string;
+    leading?: KerfUiContent;
+    center?: KerfUiContent;
+    trailing?: KerfUiContent;
+}
+/**
+ * Whether the work area's header or footer chrome stays pinned (`fixed`),
+ * scrolls away with the content (`scroll`), or stays pinned while the work
+ * area is tall enough and scrolls with the content when it is short (`auto`,
+ * the Pane's `chromePlacement="auto"`; it applies to the pinned header and
+ * footer together).
+ */
+type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
 
 /**
  * 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`.
+ * 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 WorkbenchResponsiveOverlayAt = 'compact' | 'narrow';
+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). */
@@ -18,6 +82,22 @@ interface WorkbenchPanelResizable {
 /** 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;
+    /**
+     * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`) — for example
+     * `{ contentElement: 'nav', contentLabel: 'Sections' }` for a navigation
+     * rail. Omitted or `undefined` fields keep the `Pane` defaults. Ignored
+     * without a `toolbar`, where `content` renders as given.
+     */
+    pane?: PaneConfig;
     /** Whether the panel is currently collapsed (the app owns this). */
     collapsed?: boolean;
     /**
@@ -43,13 +123,22 @@ interface WorkbenchPanel {
      * 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; the bottom drawer overlays the bottom of the work-area column.
+     * 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.
+     * 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;
@@ -64,6 +153,55 @@ interface WorkbenchProps {
     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),
+     * scroll away with `main` (`scroll`) — useful where large text would leave
+     * pinned chrome little room — or stay pinned while the work area is tall
+     * enough and scroll with `main` when it is short (`auto`).
+     */
+    mainHeaderPlacement?: WorkbenchChromePlacement;
+    /** The same for `mainFooter` and `mainBottomToolbar` (default `fixed`). */
+    mainFooterPlacement?: WorkbenchChromePlacement;
+    /**
+     * Configuration for the work area's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`), which it has whenever it
+     * has a toolbar, `mainHeader`, or `mainFooter`; without that chrome, `main`
+     * renders as given and this is ignored. Omitted or `undefined` fields keep
+     * the `Pane` defaults.
+     */
+    mainPane?: PaneConfig;
+    /**
+     * Configuration for the `List` that holds `mainHeader` (`gap`, `hAlign`,
+     * `vAlign`, `dividerSides`, `textInsets`, `controlInsets`). Omitted or
+     * `undefined` fields keep the defaults, including its bottom divider.
+     */
+    mainHeaderList?: ListConfig;
+    /**
+     * The same for the `List` that holds `mainFooter`; by default it draws a
+     * top divider, or none when a `mainBottomToolbar` follows it.
+     */
+    mainFooterList?: ListConfig;
     leftRail?: WorkbenchPanel;
     rightRail?: WorkbenchPanel;
     bottomDrawer?: WorkbenchPanel;
@@ -100,6 +238,6 @@ interface WorkbenchProps {
  * 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, mainMinSize, mainMinHeight, className, slot, }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainPane, mainHeaderList, mainFooterList, mainMinSize, mainMinHeight, className, slot, }: WorkbenchProps): SafeHtml;
 
-export { Workbench, type WorkbenchPanel, type WorkbenchPanelResizable, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
+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,212 +1,15 @@
-import { WORKBENCH_MAIN_MIN_SIZE, WORKBENCH_MAIN_MIN_HEIGHT, workbenchRegionId, WORKBENCH_RESIZE_DEFAULTS } from './chunk-PSHUSWQH.js';
-import { clampRegionSize, ResizeGrip } from './chunk-VHADGP3B.js';
-import { jsxs, jsx } from 'kerfjs/jsx-runtime';
+export { Workbench } from './chunk-QQOTQTDD.js';
+
+
+
+
+
+
+
+
+
+
 
-var EDGES = {
-  leftRail: "end",
-  rightRail: "start",
-  bottomDrawer: "start"
-};
-var DEFAULT_LABELS = {
-  leftRail: "left rail",
-  rightRail: "right rail",
-  bottomDrawer: "bottom drawer"
-};
-function resolveResize(id, key, panel) {
-  if (!panel.resizable) return void 0;
-  const defaults = WORKBENCH_RESIZE_DEFAULTS[key];
-  const limits = panel.resizable === true ? {} : panel.resizable;
-  const min = limits.min ?? defaults.min;
-  const max = Math.max(min, limits.max ?? defaults.max);
-  return {
-    regionId: workbenchRegionId(id, key),
-    axis: key === "bottomDrawer" ? "vertical" : "horizontal",
-    edge: EDGES[key],
-    size: clampRegionSize(panel.size ?? defaults.size, min, max),
-    min,
-    max
-  };
-}
-var resizeAttributes = (resize) => resize ? {
-  "data-resizable": "true",
-  "data-region-id": resize.regionId,
-  "data-axis": resize.axis,
-  "data-edge": resize.edge
-} : {};
-function panelStyle(panel, resize, sizeProperty) {
-  if (resize) return `--kui-resizable-region-size:${resize.size}px`;
-  return panel.size ? `${sizeProperty}: ${panel.size}px` : void 0;
-}
-function PanelHandle({
-  panel,
-  resize,
-  label
-}) {
-  const inert = Boolean(panel.collapsed) || (panel.presentation ?? "inline") !== "inline";
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      class: "kui-workbench__handle",
-      role: "separator",
-      tabindex: inert ? "-1" : "0",
-      "aria-label": `Resize ${label}`,
-      "aria-orientation": resize.axis === "horizontal" ? "vertical" : "horizontal",
-      "aria-valuemin": resize.min,
-      "aria-valuemax": resize.max,
-      "aria-valuenow": resize.size,
-      "aria-hidden": inert ? "true" : void 0,
-      "data-kui-resize-handle": true,
-      "data-region-id": resize.regionId,
-      children: /* @__PURE__ */ jsx("span", { class: "kui-workbench__handle-icon", "aria-hidden": "true", children: /* @__PURE__ */ jsx(ResizeGrip, { axis: resize.axis }) })
-    }
-  );
-}
-function hiddenFromAccessibility(panel) {
-  return panel.collapsed || panel.presentation === "hidden" ? "true" : void 0;
-}
-function Rail({
-  id,
-  side,
-  panel
-}) {
-  const key = side === "left" ? "leftRail" : "rightRail";
-  const resize = resolveResize(id, key, panel);
-  return /* @__PURE__ */ jsxs(
-    "aside",
-    {
-      id: workbenchRegionId(id, key),
-      class: `kui-workbench__rail kui-workbench__rail--${side}`,
-      "data-workbench-rail": side,
-      "data-collapsed": String(panel.collapsed ?? false),
-      "data-separator": panel.separator ?? "auto",
-      "data-collapse-motion": panel.collapseMotion ?? "slide",
-      "data-content-overflow": panel.contentOverflow ?? "clip",
-      "data-presentation": panel.presentation ?? "inline",
-      "data-responsive-overlay-at": panel.responsiveOverlayAt,
-      ...resizeAttributes(resize),
-      "aria-label": panel.label || void 0,
-      "aria-hidden": hiddenFromAccessibility(panel),
-      inert: Boolean(panel.collapsed),
-      style: panelStyle(panel, resize, "--kui-workbench-rail-width"),
-      children: [
-        /* @__PURE__ */ jsx(
-          "div",
-          {
-            class: "kui-workbench__panel-content",
-            inert: Boolean(panel.collapsed),
-            children: panel.content
-          }
-        ),
-        resize && /* @__PURE__ */ jsx(
-          PanelHandle,
-          {
-            panel,
-            resize,
-            label: panel.label || DEFAULT_LABELS[key]
-          }
-        )
-      ]
-    }
-  );
-}
-function Drawer({ id, panel }) {
-  const resize = resolveResize(id, "bottomDrawer", panel);
-  return /* @__PURE__ */ jsxs(
-    "section",
-    {
-      id: workbenchRegionId(id, "bottomDrawer"),
-      class: "kui-workbench__drawer",
-      "data-workbench-drawer": true,
-      "data-collapsed": String(panel.collapsed ?? false),
-      "data-separator": panel.separator ?? "auto",
-      "data-collapse-motion": panel.collapseMotion ?? "slide",
-      "data-content-overflow": panel.contentOverflow ?? "clip",
-      "data-presentation": panel.presentation ?? "inline",
-      "data-responsive-overlay-at": panel.responsiveOverlayAt,
-      ...resizeAttributes(resize),
-      "aria-label": panel.label || void 0,
-      "aria-hidden": hiddenFromAccessibility(panel),
-      inert: Boolean(panel.collapsed),
-      style: panelStyle(panel, resize, "--kui-workbench-drawer-height"),
-      children: [
-        /* @__PURE__ */ jsx(
-          "div",
-          {
-            class: "kui-workbench__panel-content",
-            inert: Boolean(panel.collapsed),
-            children: panel.content
-          }
-        ),
-        resize && /* @__PURE__ */ jsx(
-          PanelHandle,
-          {
-            panel,
-            resize,
-            label: panel.label || DEFAULT_LABELS.bottomDrawer
-          }
-        )
-      ]
-    }
-  );
-}
-function restore(panel, side, position) {
-  if (!panel?.collapsed || !panel.restoreControl || panel.presentation === "hidden")
-    return "";
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      class: "kui-workbench__restore",
-      "data-panel": side,
-      "data-position": panel.restorePosition ?? position,
-      children: panel.restoreControl
-    }
-  );
-}
-function Workbench({
-  id,
-  label,
-  main,
-  leftRail,
-  rightRail,
-  bottomDrawer,
-  mainMinSize = WORKBENCH_MAIN_MIN_SIZE,
-  mainMinHeight = WORKBENCH_MAIN_MIN_HEIGHT,
-  className = "",
-  slot
-}) {
-  const px = (value) => Math.max(0, Math.round(value));
-  const mainMin = leftRail || rightRail ? px(mainMinSize) : void 0;
-  const mainMinBlock = bottomDrawer ? px(mainMinHeight) : void 0;
-  const style = [
-    mainMin === void 0 ? "" : `--_kui-workbench-main-min-width:${mainMin}px`,
-    mainMinBlock === void 0 ? "" : `--_kui-workbench-main-min-height:${mainMinBlock}px`
-  ].filter(Boolean).join(";");
-  return /* @__PURE__ */ jsxs(
-    "section",
-    {
-      class: `kui-workbench ${className}`.trim(),
-      id,
-      "data-component": "workbench",
-      "data-main-min-size": mainMin === void 0 ? void 0 : String(mainMin),
-      "data-main-min-height": mainMinBlock === void 0 ? void 0 : String(mainMinBlock),
-      style: style || void 0,
-      "aria-label": label,
-      slot,
-      children: [
-        leftRail && /* @__PURE__ */ jsx(Rail, { id, side: "left", panel: leftRail }),
-        restore(leftRail, "left", "bottom-start"),
-        /* @__PURE__ */ jsxs("div", { class: "kui-workbench__center", children: [
-          /* @__PURE__ */ jsx("div", { class: "kui-workbench__main", "data-workbench-main": true, children: main }),
-          bottomDrawer && /* @__PURE__ */ jsx(Drawer, { id, panel: bottomDrawer }),
-          restore(bottomDrawer, "bottom", "bottom-end")
-        ] }),
-        rightRail && /* @__PURE__ */ jsx(Rail, { id, side: "right", panel: rightRail }),
-        restore(rightRail, "right", "bottom-end")
-      ]
-    }
-  );
-}
 
-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 {\n  clampRegionSize,\n  type ResizableRegionAxis,\n  type ResizableRegionCollapseMotion,\n  type ResizableRegionContentOverflow,\n  type ResizableRegionEdge,\n  type ResizableRegionPresentation,\n  type ResizableRegionRestorePosition,\n  type ResizableRegionSeparator,\n} from './resizable-region.js';\nimport { ResizeGrip } from './resize-grip.js';\nimport type { KerfUiContent } from './semantic-content.js';\nimport {\n  WORKBENCH_MAIN_MIN_HEIGHT,\n  WORKBENCH_MAIN_MIN_SIZE,\n  WORKBENCH_RESIZE_DEFAULTS,\n  type WorkbenchPanelKey,\n  workbenchRegionId,\n} from './workbench-resize.js';\n\n/**\n * The Workbench container breakpoint below which a panel presents as an\n * overlay: `narrow` (704px or less) or `compact` (448px or less) — the same\n * breakpoints as `ResizableRegion`'s `responsiveFillAt`.\n */\nexport type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow';\n\n/** Drag-resize limits for a resizable Workbench panel, in px. */\nexport interface WorkbenchPanelResizable {\n  /** Smallest size (default 180 for a rail, 120 for the drawer). */\n  min?: number;\n  /** Largest size (default 480). */\n  max?: number;\n}\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  /**\n   * Rail width, or drawer height, in px. Overrides the CSS default. For a\n   * resizable panel it is the current size (default 280 for a rail, 220 for\n   * the drawer), clamped to the limits; the app owns it and `wireWorkbench`\n   * reports each resize.\n   */\n  size?: number;\n  /**\n   * Opt in to drag and keyboard resizing on the panel's inner separator:\n   * `true` for the default limits, or `{ min, max }`. Off by default. Pair it\n   * with `wireWorkbench` from `@kerfjs/ui/wire-workbench`.\n   */\n  resizable?: boolean | WorkbenchPanelResizable;\n  /** Accessible name for the panel region. */\n  label?: string;\n  separator?: ResizableRegionSeparator;\n  collapseMotion?: ResizableRegionCollapseMotion;\n  contentOverflow?: ResizableRegionContentOverflow;\n  presentation?: ResizableRegionPresentation;\n  /**\n   * Present the panel as an overlay, without a separator, below a Workbench\n   * container breakpoint, and inline above it — the CSS decides, so the app\n   * needs no device-class check. A rail overlays from its side at full\n   * height; the bottom drawer overlays the bottom of the work-area column.\n   */\n  responsiveOverlayAt?: WorkbenchResponsiveOverlayAt;\n  /**\n   * Control shown while collapsed, in a safe-area-aware corner of the\n   * Workbench (not the viewport); the bottom drawer's sits in the work-area\n   * column.\n   */\n  restoreControl?: SafeHtml;\n  restorePosition?: ResizableRegionRestorePosition;\n}\n\nexport interface WorkbenchProps {\n  /**\n   * The Workbench's `id`. Each panel's `id` derives from it —\n   * `<id>-left-rail`, `<id>-right-rail`, `<id>-bottom-drawer` — so a toggle\n   * can name the panel it shows and hides with `aria-controls`.\n   */\n  id: string;\n  label: string;\n  /** The central work area. */\n  main: KerfUiContent;\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  bottomDrawer?: WorkbenchPanel;\n  /**\n   * Minimum width, in px, the work area keeps beside the inline rails, fixed\n   * or `resizable` (default 320; `0` turns it off). Resizing a rail stops\n   * where the work area would drop below it, and inline rails shrink\n   * proportionally when the Workbench gets narrower. Workbenches without a\n   * rail ignore it.\n   */\n  mainMinSize?: number;\n  /**\n   * Minimum height, in px, the work area keeps above an inline bottom drawer,\n   * fixed or `resizable` (default 120; `0` turns it off) — the drawer's\n   * counterpart of `mainMinSize`. Resizing the drawer stops where the work\n   * area would drop below it, and the drawer shrinks when the Workbench gets\n   * shorter. Workbenches without a drawer ignore it.\n   */\n  mainMinHeight?: number;\n  className?: string;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\ninterface ResolvedResize {\n  regionId: string;\n  axis: ResizableRegionAxis;\n  edge: ResizableRegionEdge;\n  size: number;\n  min: number;\n  max: number;\n}\n\n/**\n * Each panel's separator is its inner edge. Growing the left rail moves that\n * edge toward the inline end; growing the right rail or the drawer moves it\n * toward the start — the same edge vocabulary `ResizableRegion` uses.\n */\nconst EDGES: Record<WorkbenchPanelKey, ResizableRegionEdge> = {\n  leftRail: 'end',\n  rightRail: 'start',\n  bottomDrawer: 'start',\n};\n\nconst DEFAULT_LABELS: Record<WorkbenchPanelKey, string> = {\n  leftRail: 'left rail',\n  rightRail: 'right rail',\n  bottomDrawer: 'bottom drawer',\n};\n\nfunction resolveResize(\n  id: string,\n  key: WorkbenchPanelKey,\n  panel: WorkbenchPanel,\n): ResolvedResize | undefined {\n  if (!panel.resizable) return undefined;\n  const defaults = WORKBENCH_RESIZE_DEFAULTS[key];\n  const limits = panel.resizable === true ? {} : panel.resizable;\n  const min = limits.min ?? defaults.min;\n  const max = Math.max(min, limits.max ?? defaults.max);\n  return {\n    regionId: workbenchRegionId(id, key),\n    axis: key === 'bottomDrawer' ? 'vertical' : 'horizontal',\n    edge: EDGES[key],\n    size: clampRegionSize(panel.size ?? defaults.size, min, max),\n    min,\n    max,\n  };\n}\n\n/** The attributes a resizable panel adds for the resize wiring to read. */\nconst resizeAttributes = (resize: ResolvedResize | undefined) =>\n  resize\n    ? {\n        'data-resizable': 'true',\n        'data-region-id': resize.regionId,\n        'data-axis': resize.axis,\n        'data-edge': resize.edge,\n      }\n    : {};\n\n/**\n * A resizable panel's size lives in the resize wiring's track property, so a\n * drag or key press resizes the panel before the app re-renders; the CSS maps\n * it onto the rail width or drawer height.\n */\nfunction panelStyle(\n  panel: WorkbenchPanel,\n  resize: ResolvedResize | undefined,\n  sizeProperty: string,\n) {\n  if (resize) return `--kui-resizable-region-size:${resize.size}px`;\n  return panel.size ? `${sizeProperty}: ${panel.size}px` : undefined;\n}\n\n/**\n * The separator a resizable panel owns: the same focusable `role=\"separator\"`\n * contract a `ResizableRegion` handle carries, so one resize wiring drives\n * both. It leaves the tab order while the panel is collapsed or not inline.\n */\nfunction PanelHandle({\n  panel,\n  resize,\n  label,\n}: {\n  panel: WorkbenchPanel;\n  resize: ResolvedResize;\n  label: string;\n}) {\n  const inert =\n    Boolean(panel.collapsed) || (panel.presentation ?? 'inline') !== 'inline';\n  return (\n    <div\n      class=\"kui-workbench__handle\"\n      role=\"separator\"\n      tabindex={inert ? '-1' : '0'}\n      aria-label={`Resize ${label}`}\n      aria-orientation={\n        resize.axis === 'horizontal' ? 'vertical' : 'horizontal'\n      }\n      aria-valuemin={resize.min}\n      aria-valuemax={resize.max}\n      aria-valuenow={resize.size}\n      aria-hidden={inert ? 'true' : undefined}\n      data-kui-resize-handle\n      data-region-id={resize.regionId}\n    >\n      <span class=\"kui-workbench__handle-icon\" aria-hidden=\"true\">\n        <ResizeGrip axis={resize.axis} />\n      </span>\n    </div>\n  );\n}\n\n/**\n * A collapsed panel leaves the accessibility tree as a whole, like a collapsed\n * `CollapsiblePanel`: its content and separator are already inert or hidden,\n * so the labeled landmark would otherwise stay behind, empty, for a screen\n * reader to land on. Its restore control renders outside it and stays\n * reachable.\n */\nfunction hiddenFromAccessibility(panel: WorkbenchPanel) {\n  return panel.collapsed || panel.presentation === 'hidden'\n    ? ('true' as const)\n    : undefined;\n}\n\nfunction Rail({\n  id,\n  side,\n  panel,\n}: {\n  id: string;\n  side: 'left' | 'right';\n  panel: WorkbenchPanel;\n}) {\n  const key: WorkbenchPanelKey = side === 'left' ? 'leftRail' : 'rightRail';\n  const resize = resolveResize(id, key, panel);\n  return (\n    <aside\n      id={workbenchRegionId(id, key)}\n      class={`kui-workbench__rail kui-workbench__rail--${side}`}\n      data-workbench-rail={side}\n      data-collapsed={String(panel.collapsed ?? false)}\n      data-separator={panel.separator ?? 'auto'}\n      data-collapse-motion={panel.collapseMotion ?? 'slide'}\n      data-content-overflow={panel.contentOverflow ?? 'clip'}\n      data-presentation={panel.presentation ?? 'inline'}\n      data-responsive-overlay-at={panel.responsiveOverlayAt}\n      {...resizeAttributes(resize)}\n      aria-label={panel.label || undefined}\n      aria-hidden={hiddenFromAccessibility(panel)}\n      inert={Boolean(panel.collapsed)}\n      style={panelStyle(panel, resize, '--kui-workbench-rail-width')}\n    >\n      <div\n        class=\"kui-workbench__panel-content\"\n        inert={Boolean(panel.collapsed)}\n      >\n        {panel.content}\n      </div>\n      {resize && (\n        <PanelHandle\n          panel={panel}\n          resize={resize}\n          label={panel.label || DEFAULT_LABELS[key]}\n        />\n      )}\n    </aside>\n  );\n}\n\nfunction Drawer({ id, panel }: { id: string; panel: WorkbenchPanel }) {\n  const resize = resolveResize(id, 'bottomDrawer', panel);\n  return (\n    <section\n      id={workbenchRegionId(id, 'bottomDrawer')}\n      class=\"kui-workbench__drawer\"\n      data-workbench-drawer\n      data-collapsed={String(panel.collapsed ?? false)}\n      data-separator={panel.separator ?? 'auto'}\n      data-collapse-motion={panel.collapseMotion ?? 'slide'}\n      data-content-overflow={panel.contentOverflow ?? 'clip'}\n      data-presentation={panel.presentation ?? 'inline'}\n      data-responsive-overlay-at={panel.responsiveOverlayAt}\n      {...resizeAttributes(resize)}\n      aria-label={panel.label || undefined}\n      aria-hidden={hiddenFromAccessibility(panel)}\n      inert={Boolean(panel.collapsed)}\n      style={panelStyle(panel, resize, '--kui-workbench-drawer-height')}\n    >\n      <div\n        class=\"kui-workbench__panel-content\"\n        inert={Boolean(panel.collapsed)}\n      >\n        {panel.content}\n      </div>\n      {resize && (\n        <PanelHandle\n          panel={panel}\n          resize={resize}\n          label={panel.label || DEFAULT_LABELS.bottomDrawer}\n        />\n      )}\n    </section>\n  );\n}\n\n/** A collapsed panel's restore control, outside the clipped panel. */\nfunction restore(\n  panel: WorkbenchPanel | undefined,\n  side: 'left' | 'right' | 'bottom',\n  position: ResizableRegionRestorePosition,\n) {\n  if (\n    !panel?.collapsed ||\n    !panel.restoreControl ||\n    panel.presentation === 'hidden'\n  )\n    return '';\n  return (\n    <div\n      class=\"kui-workbench__restore\"\n      data-panel={side}\n      data-position={panel.restorePosition ?? position}\n    >\n      {panel.restoreControl}\n    </div>\n  );\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. A collapsed panel renders\n * `inert` and `aria-hidden`, so neither Tab nor assistive technology reaches\n * controls that have slid out of view or an empty landmark (its restore control\n * lives outside it and stays reachable). A panel may opt in to drag and keyboard resizing with\n * `resizable`, which `wireWorkbench` drives. See `docs/23-app-layouts.md` §3.3.\n */\nexport function Workbench({\n  id,\n  label,\n  main,\n  leftRail,\n  rightRail,\n  bottomDrawer,\n  mainMinSize = WORKBENCH_MAIN_MIN_SIZE,\n  mainMinHeight = WORKBENCH_MAIN_MIN_HEIGHT,\n  className = '',\n  slot,\n}: WorkbenchProps) {\n  // Each work-area minimum applies only on an axis a panel shares with it:\n  // the width beside a rail, the height above the drawer.\n  const px = (value: number) => Math.max(0, Math.round(value));\n  const mainMin = leftRail || rightRail ? px(mainMinSize) : undefined;\n  const mainMinBlock = bottomDrawer ? px(mainMinHeight) : undefined;\n  const style = [\n    mainMin === undefined ? '' : `--_kui-workbench-main-min-width:${mainMin}px`,\n    mainMinBlock === undefined\n      ? ''\n      : `--_kui-workbench-main-min-height:${mainMinBlock}px`,\n  ]\n    .filter(Boolean)\n    .join(';');\n  return (\n    <section\n      class={`kui-workbench ${className}`.trim()}\n      id={id}\n      data-component=\"workbench\"\n      data-main-min-size={mainMin === undefined ? undefined : String(mainMin)}\n      data-main-min-height={\n        mainMinBlock === undefined ? undefined : String(mainMinBlock)\n      }\n      style={style || undefined}\n      aria-label={label}\n      slot={slot}\n    >\n      {leftRail && <Rail id={id} side=\"left\" panel={leftRail} />}\n      {restore(leftRail, 'left', 'bottom-start')}\n      <div class=\"kui-workbench__center\">\n        <div class=\"kui-workbench__main\" data-workbench-main>\n          {main}\n        </div>\n        {bottomDrawer && <Drawer id={id} panel={bottomDrawer} />}\n        {restore(bottomDrawer, 'bottom', 'bottom-end')}\n      </div>\n      {rightRail && <Rail id={id} side=\"right\" panel={rightRail} />}\n      {restore(rightRail, 'right', 'bottom-end')}\n    </section>\n  );\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"workbench.js"}

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,18 +30,44 @@ 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
 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
 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,95 @@ 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
+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. 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
 
 `ListActionRow` renders a noninteractive visual root containing primary and
@@ -172,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