@kerfjs/ui 5.0.0-beta.8 → 5.0.0-beta.80

package/dist/workbench.d.ts

@@ -1,33 +1,270 @@
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { b as NavPane, N as NavStackProps } from './nav-stack-B1Qc2e5q.js';
+import { ListConfig } from './list.js';
+import { PaneConfig } from './pane.js';
+import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
+import { a as PanelToolbar, c as PanelBottomToolbar, b as PanelChromePlacement, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
+import { ToolbarConfig } from './toolbar.js';
+import './toolbar-text.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './sides-BPSWde0A.js';
+import './lucide-icon.js';
+import 'lucide';
 
-/** A collapsible Workbench panel — a side rail or the bottom drawer. */
-interface WorkbenchPanel {
-    content: SafeHtml;
+/** 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 marked 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;
+type WorkbenchPanelBottomToolbar = PanelBottomToolbar;
+/**
+ * The work area's top toolbar; collapsed rails add their groups to it. Its
+ * configuration forwards to its `Toolbar`. It draws no divider of its own by
+ * default: the work area's `Pane` draws one under its header chrome, wherever
+ * that chrome ends, while `main` is scrolled (`mainPane.chromeDividers`).
+ */
+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`. It draws no divider of its own
+ * by default: the work area's `Pane` draws one over its footer chrome while
+ * more of `main` lies below (`mainPane.chromeDividers`).
+ */
+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 = PanelChromePlacement;
+
+/**
+ * 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' | number;
+/**
+ * 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;
+}
+/** Region sizing, collapse, and presentation shared by either panel body. */
+interface WorkbenchPanelBase {
     /** 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;
+    /** Opt into keyboard (`0`) or programmatic (`-1`) focus on the panel region. */
+    tabIndex?: 0 | -1;
+    /** Keep the standard focus outline visible while this panel is expanded. */
+    outlined?: boolean;
+    separator?: ResizableRegionSeparator;
+    collapseMotion?: ResizableRegionCollapseMotion;
+    contentOverflow?: ResizableRegionContentOverflow;
+    presentation?: ResizableRegionPresentation;
+    /**
+     * Present the panel as an overlay, without a separator, below a Workbench
+     * container breakpoint, and inline above it. `compact` and `narrow` use
+     * CSS container queries; a positive number is a pixel threshold measured
+     * by `wireWorkbench` and requires a `collapsed` signal. 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;
+}
+/** The original static panel body: one toolbar, optional fixed chrome, and one Pane. */
+interface WorkbenchStaticPanel extends WorkbenchPanelBase, NavPane<WorkbenchPanelToolbar, WorkbenchPanelBottomToolbar> {
+    /** The composed toolbar; marked groups and its toggle relocate on collapse. */
+    toolbar?: WorkbenchPanelToolbar;
+    headerPlacement?: WorkbenchChromePlacement;
+    footerPlacement?: WorkbenchChromePlacement;
+    navStack?: never;
+}
+/** A panel whose active NavStack view supplies the toolbar, fixed header, and scroll body. */
+interface WorkbenchNavigationPanel extends WorkbenchPanelBase {
+    navStack: Omit<NavStackProps, 'panelToggle' | 'hideToolbar' | 'className' | 'slot'>;
+    /** Supplies the standard toggle; active view groups precede it and may relocate on collapse. */
+    toolbar: Omit<WorkbenchPanelToolbar, 'title' | 'leading' | 'center' | 'trailing'> & {
+        toggle: NonNullable<WorkbenchPanelToolbar['toggle']>;
+    };
+    content?: never;
+    header?: never;
+    headerList?: never;
+    headerPlacement?: never;
+    footer?: never;
+    footerList?: never;
+    bottomToolbar?: never;
+    footerPlacement?: never;
+    pane?: never;
 }
+/** A collapsible Workbench side rail or bottom drawer. */
+type WorkbenchPanel = WorkbenchStaticPanel | WorkbenchNavigationPanel;
 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: SafeHtml;
+    main: KerfUiContent;
+    /**
+     * The work area's top toolbar. A collapsed left rail's marked 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 marked 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`, `chromeDividers`), 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;
+    /** Accessible name for the central region when it needs its own landmark. */
+    mainLabel?: string;
+    /** Opt into keyboard (`0`) or programmatic (`-1`) focus on the central region. */
+    mainTabIndex?: 0 | -1;
+    /** Keep the standard focus outline visible on the central region. */
+    mainOutlined?: boolean;
+    /**
+     * Configuration for the `List` that holds `mainHeader` (`gap`, `hAlign`,
+     * `vAlign`, `dividerSides`, `textInsets`, `controlInsets`). Omitted or
+     * `undefined` fields keep the defaults (no divider: the work area's
+     * `Pane` draws the line under its header chrome).
+     */
+    mainHeaderList?: ListConfig;
+    /**
+     * The same for the `List` that holds `mainFooter` (no divider by default:
+     * the work area's `Pane` draws the line over its footer chrome).
+     */
+    mainFooterList?: ListConfig;
     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;
+    /** Dim the work area below any open overlay and absorb outside presses; off by default. */
+    overlayBackdrop?: boolean;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and
  * bottom drawer around a central work area (any absent). Collapsing snaps the
  * panel's track to zero in one reflow while its fixed-size content slides out via
  * a composited transform — the instant-width / sliding-content technique, so the
- * work area relayouts once, not per frame. The app owns each `collapsed` flag;
- * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.
+ * 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. 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 }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainPane, mainLabel, mainTabIndex, mainOutlined, mainHeaderList, mainFooterList, mainMinSize, mainMinHeight, overlayBackdrop, className, slot, }: WorkbenchProps): SafeHtml;
 
-export { Workbench, type WorkbenchPanel, type WorkbenchProps };
+export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchNavigationPanel, type WorkbenchPanel, type WorkbenchPanelBottomToolbar, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt, type WorkbenchStaticPanel };

package/dist/workbench.js

@@ -1,17 +1,19 @@
-import { jsxs, jsx } from 'kerfjs/jsx-runtime';
-
-// src/workbench.tsx
-function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className = "" }) {
-  return /* @__PURE__ */ jsxs("section", { class: `kui-workbench ${className}`.trim(), id, "data-component": "workbench", "aria-label": label, children: [
-    leftRail && /* @__PURE__ */ jsx("aside", { class: "kui-workbench__rail kui-workbench__rail--left", "data-workbench-rail": "left", "data-collapsed": String(leftRail.collapsed ?? false), "aria-label": leftRail.label || 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 }) }),
-    /* @__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), "aria-label": bottomDrawer.label || 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 }) })
-    ] }),
-    rightRail && /* @__PURE__ */ jsx("aside", { class: "kui-workbench__rail kui-workbench__rail--right", "data-workbench-rail": "right", "data-collapsed": String(rightRail.collapsed ?? false), "aria-label": rightRail.label || 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 }) })
-  ] });
-}
-
-export { Workbench };
+export { Workbench } from './chunk-LQKY5S4F.js';
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 //# sourceMappingURL=workbench.js.map

package/dist/workbench.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/workbench.tsx"],"names":[],"mappings":";;;AAgCO,SAAS,SAAA,CAAU,EAAE,EAAA,EAAI,KAAA,EAAO,IAAA,EAAM,UAAU,SAAA,EAAW,YAAA,EAAc,SAAA,GAAY,EAAA,EAAG,EAAmB;AAChH,EAAA,uBAAO,IAAA,CAAC,SAAA,EAAA,EAAQ,KAAA,EAAO,CAAA,cAAA,EAAiB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK,EAAG,EAAA,EAAQ,gBAAA,EAAe,WAAA,EAAY,YAAA,EAAY,KAAA,EACxG,QAAA,EAAA;AAAA,IAAA,QAAA,oBAAY,GAAA,CAAC,OAAA,EAAA,EAAM,KAAA,EAAM,+CAAA,EAAgD,qBAAA,EAAoB,MAAA,EAAO,gBAAA,EAAgB,MAAA,CAAO,QAAA,CAAS,SAAA,IAAa,KAAK,CAAA,EAAG,cAAY,QAAA,CAAS,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,QAAA,CAAS,IAAA,GAAO,CAAA,4BAAA,EAA+B,QAAA,CAAS,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EAC3Q,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,QAAA,CAAS,SAAQ,CAAA,EAC9D,CAAA;AAAA,oBACA,IAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EACT,QAAA,EAAA;AAAA,sBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,qBAAA,EAAsB,qBAAA,EAAmB,MAAE,QAAA,EAAA,IAAA,EAAK,CAAA;AAAA,MAC1D,YAAA,oBAAgB,GAAA,CAAC,SAAA,EAAA,EAAQ,KAAA,EAAM,uBAAA,EAAwB,uBAAA,EAAqB,IAAA,EAAC,gBAAA,EAAgB,MAAA,CAAO,YAAA,CAAa,SAAA,IAAa,KAAK,GAAG,YAAA,EAAY,YAAA,CAAa,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,YAAA,CAAa,IAAA,GAAO,CAAA,+BAAA,EAAkC,aAAa,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EACvQ,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,YAAA,CAAa,SAAQ,CAAA,EAClE;AAAA,KAAA,EACF,CAAA;AAAA,IACC,SAAA,oBAAa,GAAA,CAAC,OAAA,EAAA,EAAM,KAAA,EAAM,gDAAA,EAAiD,qBAAA,EAAoB,OAAA,EAAQ,gBAAA,EAAgB,MAAA,CAAO,SAAA,CAAU,SAAA,IAAa,KAAK,GAAG,YAAA,EAAY,SAAA,CAAU,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,SAAA,CAAU,IAAA,GAAO,CAAA,4BAAA,EAA+B,UAAU,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EAClR,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,SAAA,CAAU,SAAQ,CAAA,EAC/D;AAAA,GAAA,EACF,CAAA;AACF","file":"workbench.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\n/** A collapsible Workbench panel — a side rail or the bottom drawer. */\nexport interface WorkbenchPanel {\n  content: SafeHtml;\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}\n\nexport interface WorkbenchProps {\n  id: string;\n  label: string;\n  /** The central work area. */\n  main: SafeHtml;\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  bottomDrawer?: WorkbenchPanel;\n  className?: 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. The app owns each `collapsed` flag;\n * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.\n */\nexport function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className = '' }: WorkbenchProps) {\n  return <section class={`kui-workbench ${className}`.trim()} id={id} data-component=\"workbench\" aria-label={label}>\n    {leftRail && <aside class=\"kui-workbench__rail kui-workbench__rail--left\" data-workbench-rail=\"left\" data-collapsed={String(leftRail.collapsed ?? false)} aria-label={leftRail.label || undefined} style={leftRail.size ? `--kui-workbench-rail-width: ${leftRail.size}px` : undefined}>\n      <div class=\"kui-workbench__panel-content\">{leftRail.content}</div>\n    </aside>}\n    <div class=\"kui-workbench__center\">\n      <div class=\"kui-workbench__main\" data-workbench-main>{main}</div>\n      {bottomDrawer && <section class=\"kui-workbench__drawer\" data-workbench-drawer data-collapsed={String(bottomDrawer.collapsed ?? false)} aria-label={bottomDrawer.label || undefined} style={bottomDrawer.size ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px` : undefined}>\n        <div class=\"kui-workbench__panel-content\">{bottomDrawer.content}</div>\n      </section>}\n    </div>\n    {rightRail && <aside class=\"kui-workbench__rail kui-workbench__rail--right\" data-workbench-rail=\"right\" data-collapsed={String(rightRail.collapsed ?? false)} aria-label={rightRail.label || undefined} style={rightRail.size ? `--kui-workbench-rail-width: ${rightRail.size}px` : undefined}>\n      <div class=\"kui-workbench__panel-content\">{rightRail.content}</div>\n    </aside>}\n  </section>;\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"workbench.js"}