@hanzo/ui 8.27.91 → 8.28.0

package/dist/product/CommandMenu.d.ts

@@ -0,0 +1,77 @@
+/**
+ * CommandMenu — the palette as a side-panel page (twenty-ui's command menu
+ * frame, MIT, NOTICE): the search field IS the top bar, and the commands are
+ * grouped rows under it.
+ *
+ *   const pane = useDetailPane()
+ *   useCommandK(() => pane.open({ title: 'Command menu', bare: true, content: <CommandMenu groups={groups} /> }))
+ *
+ * Layout: the 48px pane bar holds a borderless 24px field ("Type anything…");
+ * each group opens on a 32px header row (a 24px icon slot, the label in medium
+ * ink, a hairline under it); rows are the record menu row — 32 high, a 16px
+ * icon in its well, contextual text, keycaps for the command's shortcut ("G
+ * then P"), a chevron when it opens a page — 2 apart, groups 12 apart. A query
+ * that matches nothing says so in a 64px status line.
+ *
+ * The decisions are the palette's own (`command.logic`): `score` keeps and
+ * ranks a row against the query, `step` moves the cursor. The view is drawn
+ * here as the ARIA combobox it is — the field owns focus and names the active
+ * option, the rows are options in grouped listboxes — so a screen reader hears
+ * the row the arrows land on while the caret stays in the field.
+ *
+ * Keys, from the field: ArrowDown/ArrowUp move (wrapping), Enter runs the
+ * active row, Escape clears a query (and on an empty one lets the pane close),
+ * Backspace on an empty query goes back a page.
+ */
+import { type ReactNode } from 'react';
+import { type ShortcutKeys } from '../backends/gui/shortcut.js';
+export type CommandMenuItem = {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    /** Dimmed text after the label: an object's name, a count. */
+    contextual?: string;
+    /** More words the query matches it by. */
+    keywords?: string[];
+    /** The keys that run it outside the menu, drawn as keycaps: `['Mod', 'K']`, or `[['G'], ['P']]` for G then P. */
+    shortcut?: ShortcutKeys;
+    /** It opens a page rather than acting: a chevron at its end. */
+    submenu?: boolean;
+    disabled?: boolean;
+    onSelect: () => void;
+};
+export type CommandMenuGroup = {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    items: CommandMenuItem[];
+};
+export type CommandMenuProps = {
+    groups: CommandMenuGroup[];
+    placeholder?: string;
+    /** What a query that matches nothing says. */
+    empty?: ReactNode;
+    /** The listbox's accessible name. */
+    label?: string;
+    /** The query, controlled; uncontrolled when absent. */
+    query?: string;
+    onQueryChange?: (query: string) => void;
+    /** Backspace on an empty query. Default: the pane's `back`, when there is a page under this one. */
+    onBack?: () => void;
+    /** Escape on an empty query, outside a pane (inside one, the pane closes itself). */
+    onClose?: () => void;
+    autoFocus?: boolean;
+};
+/** The frame's measures (twenty-ui's command menu, MIT). */
+export declare const COMMAND: {
+    readonly field: 24;
+    readonly header: 32;
+    readonly icon: 24;
+    readonly row: 32;
+    readonly rows: 2;
+    readonly groups: 12;
+    readonly empty: 64;
+    readonly margin: 48;
+};
+export declare function CommandMenu({ groups, placeholder, empty, label, query: controlled, onQueryChange, onBack, onClose, autoFocus, }: CommandMenuProps): import("react").JSX.Element;
+//# sourceMappingURL=CommandMenu.d.ts.map

package/dist/product/CommandMenu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandMenu.d.ts","sourceRoot":"","sources":["../../src/product/CommandMenu.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAA+C,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAInF,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAMtE,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,iHAAiH;IACjH,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,EAAE,MAAM,IAAI,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,gBAAgB,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,oGAAoG;IACpG,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,OAAO;aAAK,KAAK,EAAE,EAAE;aAAE,MAAM,EAAE,EAAE;aAAE,IAAI,EAAE,EAAE;aAAE,GAAG,EAAE,EAAE;aAAE,IAAI,EAAE,CAAC;aAAE,MAAM,EAAE,EAAE;aAAE,KAAK,EAAE,EAAE;aAAE,MAAM,EAAE,EAAE;CAAW,CAAA;AAIxH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,WAA8B,EAC9B,KAA0B,EAC1B,KAAkB,EAClB,KAAK,EAAE,UAAU,EACjB,aAAa,EACb,MAAM,EACN,OAAO,EACP,SAAgB,GACjB,EAAE,gBAAgB,+BAgMlB"}

package/dist/product/CommandMenu.js

@@ -0,0 +1,134 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * CommandMenu — the palette as a side-panel page (twenty-ui's command menu
+ * frame, MIT, NOTICE): the search field IS the top bar, and the commands are
+ * grouped rows under it.
+ *
+ *   const pane = useDetailPane()
+ *   useCommandK(() => pane.open({ title: 'Command menu', bare: true, content: <CommandMenu groups={groups} /> }))
+ *
+ * Layout: the 48px pane bar holds a borderless 24px field ("Type anything…");
+ * each group opens on a 32px header row (a 24px icon slot, the label in medium
+ * ink, a hairline under it); rows are the record menu row — 32 high, a 16px
+ * icon in its well, contextual text, keycaps for the command's shortcut ("G
+ * then P"), a chevron when it opens a page — 2 apart, groups 12 apart. A query
+ * that matches nothing says so in a 64px status line.
+ *
+ * The decisions are the palette's own (`command.logic`): `score` keeps and
+ * ranks a row against the query, `step` moves the cursor. The view is drawn
+ * here as the ARIA combobox it is — the field owns focus and names the active
+ * option, the rows are options in grouped listboxes — so a screen reader hears
+ * the row the arrows land on while the caret stays in the field.
+ *
+ * Keys, from the field: ArrowDown/ArrowUp move (wrapping), Enter runs the
+ * active row, Escape clears a query (and on an empty one lets the pane close),
+ * Backspace on an empty query goes back a page.
+ */
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import { Input, Text, XStack, YStack } from '@hanzo/gui';
+import { score, step } from '../backends/gui/command.logic.js';
+import { Shortcut } from '../backends/gui/shortcut.js';
+import { slot } from '../backends/gui/slot.js';
+import { touch } from '../backends/gui/gesture.js';
+import { MenuRowContent } from './MenuRow.js';
+import { PaneBar, PaneBody, usePane } from './DetailPane.js';
+/** The frame's measures (twenty-ui's command menu, MIT). */
+export const COMMAND = { field: 24, header: 32, icon: 24, row: 32, rows: 2, groups: 12, empty: 64, margin: 48 };
+export function CommandMenu({ groups, placeholder = 'Type anything…', empty = 'No results found', label = 'Commands', query: controlled, onQueryChange, onBack, onClose, autoFocus = true, }) {
+    const pane = usePane();
+    const base = useId();
+    const [own, setOwn] = useState('');
+    const query = controlled ?? own;
+    const setQuery = (q) => {
+        if (controlled === undefined)
+            setOwn(q);
+        onQueryChange?.(q);
+    };
+    // The rows that survive the query, grouped, in source order.
+    const shown = useMemo(() => groups
+        .map((g) => ({
+        ...g,
+        items: g.items.filter((it) => score(it.label, query, [...(it.keywords ?? []), ...(it.contextual ? [it.contextual] : [])]) > 0),
+    }))
+        .filter((g) => g.items.length > 0), [groups, query]);
+    const reachable = useMemo(() => shown.flatMap((g) => g.items.filter((it) => !it.disabled)), [shown]);
+    const [active, setActive] = useState(undefined);
+    const current = reachable.find((it) => it.id === active) ?? reachable[0];
+    const optionId = (id) => `${base}-option-${id}`;
+    const listId = `${base}-list`;
+    // A cursor the arrows moved is brought into view; the first row of a group
+    // carries a scroll margin, so its header comes with it.
+    const moved = useRef(false);
+    useEffect(() => {
+        if (!moved.current || !current || typeof document === 'undefined')
+            return;
+        moved.current = false;
+        const el = document.getElementById(optionId(current.id));
+        el?.scrollIntoView?.({ block: 'nearest' });
+    });
+    const field = useRef(null);
+    useEffect(() => {
+        if (!autoFocus)
+            return;
+        const t = setTimeout(() => field.current?.focus?.(), 0);
+        return () => clearTimeout(t);
+    }, [autoFocus]);
+    const onKey = (e) => {
+        if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+            e.preventDefault();
+            const at = current ? reachable.indexOf(current) : -1;
+            const next = reachable[step(reachable.length, at, e.key === 'ArrowDown' ? 1 : -1, true)];
+            if (next) {
+                moved.current = true;
+                setActive(next.id);
+            }
+        }
+        else if (e.key === 'Enter') {
+            if (!current)
+                return;
+            e.preventDefault();
+            current.onSelect();
+        }
+        else if (e.key === 'Escape') {
+            if (query) {
+                // Clearing the query is this key's whole job: it must not reach the pane.
+                e.preventDefault();
+                e.stopPropagation();
+                setQuery('');
+            }
+            else if (!pane && onClose) {
+                e.preventDefault();
+                onClose();
+            }
+        }
+        else if (e.key === 'Backspace' && !query) {
+            const back = onBack ?? (pane && pane.depth > 1 ? pane.back : undefined);
+            if (back) {
+                e.preventDefault();
+                back();
+            }
+        }
+    };
+    return (_jsxs(YStack, { ...slot('command-menu'), flex: 1, minH: 0, children: [_jsx(PaneBar, { children: _jsx(Input, { ref: field, ...slot('command-menu-input'), ...{
+                        role: 'combobox',
+                        'aria-expanded': true,
+                        'aria-controls': listId,
+                        'aria-autocomplete': 'list',
+                        'aria-activedescendant': current ? optionId(current.id) : undefined,
+                        'aria-label': label,
+                    }, flex: 1, minW: 0, height: COMMAND.field, px: 0, borderWidth: 0, rounded: 0, bg: "transparent", color: "$ink", fontSize: "$2", placeholder: placeholder, placeholderTextColor: "$hush", value: query, onChangeText: (t) => {
+                        setQuery(t);
+                        setActive(undefined);
+                    }, onKeyDown: onKey, 
+                    // The bar is the field; its caret is the focus, so the field draws no
+                    // ring of its own (inline, to outrank design's :focus-visible rule).
+                    style: { outlineStyle: 'none' } }) }), _jsx(PaneBody, { padded: false, children: _jsxs(YStack, { id: listId, ...slot('command-menu-list'), px: "$2", pt: "$2", pb: "$2", gap: COMMAND.groups, children: [shown.map((g) => {
+                            const head = `${base}-group-${g.id}`;
+                            return (_jsxs(YStack, { ...slot('command-menu-group'), gap: COMMAND.rows, children: [_jsxs(XStack, { id: head, ...slot('command-menu-heading'), height: COMMAND.header, items: "center", gap: "$1", pl: "$1", borderBottomWidth: 1, borderColor: "$borderColor", children: [_jsx(XStack, { width: COMMAND.icon, height: COMMAND.icon, items: "center", justify: "center", shrink: 0, children: g.icon }), _jsx(Text, { fontSize: "$2", fontWeight: "500", color: "$ink", numberOfLines: 1, children: g.label })] }), _jsx(YStack, { role: "listbox", "aria-labelledby": head, gap: COMMAND.rows, children: g.items.map((it, i) => {
+                                            const on = current?.id === it.id;
+                                            return (_jsx(XStack, { id: optionId(it.id), ...slot('command-menu-item'), ...{ role: 'option', 'aria-selected': on, 'aria-disabled': it.disabled || undefined }, "data-active": on ? '' : undefined, items: "center", gap: "$2", px: "$1", minH: COMMAND.row, rounded: "$xs", cursor: it.disabled ? 'default' : 'pointer', opacity: it.disabled ? 0.5 : 1, bg: on ? '$hover' : 'transparent', hoverStyle: it.disabled ? undefined : { bg: '$hover' }, ...touch(COMMAND.row, 44, 'y'), onHoverIn: it.disabled ? undefined : () => setActive(it.id), onPress: it.disabled ? undefined : it.onSelect, style: i === 0 ? { scrollMarginTop: COMMAND.margin } : undefined, children: _jsx(MenuRowContent, { label: it.label, icon: it.icon, iconContainer: it.icon != null, contextual: it.contextual, shortcut: it.shortcut ? _jsx(Shortcut, { keys: it.shortcut }) : undefined, submenu: it.submenu, quiet: true }) }, it.id));
+                                        }) })] }, g.id));
+                        }), shown.length === 0 ? (_jsx(YStack, { ...slot('command-menu-empty'), role: "status", "aria-live": "polite", height: COMMAND.empty, items: "center", justify: "center", children: typeof empty === 'string' ? (_jsx(Text, { fontSize: "$2", color: "$hush", children: empty })) : (empty) })) : null] }) })] }));
+}
+//# sourceMappingURL=CommandMenu.js.map

package/dist/product/CommandMenu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandMenu.js","sourceRoot":"","sources":["../../src/product/CommandMenu.tsx"],"names":[],"mappings":"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"}

package/dist/product/DetailPane.cjs

@@ -1,8 +1,12 @@
 'use client';"use strict";
 'use client';
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PANE = exports.usePane = void 0;
 exports.useDetailPane = useDetailPane;
 exports.DetailPane = DetailPane;
+exports.PaneBar = PaneBar;
+exports.PaneBody = PaneBody;
+exports.PaneFoot = PaneFoot;
 const jsx_runtime_1 = require("react/jsx-runtime");
 /**
  * DetailPane — the ONE reusable right-side pane for viewing or editing the
@@ -19,28 +23,166 @@ const jsx_runtime_1 = require("react/jsx-runtime");
  * The last descriptor stays mounted through the close transition, so the exit
  * animates with its content (no flash of empty pane). Opening a new
  * descriptor replaces it.
+ *
+ * A pane is a STACK of pages. `open` starts a new stack, `push` lays a page on
+ * top (a relation opened from a record, a step of a flow), `back` takes it off;
+ * the top bar shows a back button while there is a page under the current one.
+ *
+ * Two modes, chosen by the shell:
+ *
+ *   overlay  (default) the SlideOver above the page, with its scrim — the
+ *            console's contract, unchanged.
+ *   docked   a column in the layout row beside the page content: no scrim, the
+ *            content narrows. 400 wide, resizable 320–600 from its leading edge
+ *            by the kit's one resizer (Grip), the width kept per person
+ *            (useSpan). The width animates 0 ↔ W while the page inside keeps the
+ *            target width, so it never reflows mid-slide. Below lg it is the
+ *            overlay again, full screen.
+ *
+ * A docked pane — or any pane under `<Density value="compact">` — draws the
+ * record frame (twenty-ui's side panel, MIT, NOTICE): a 48px top bar on the
+ * panel ground (back · icon + title · page actions · expand · close), a body
+ * that scrolls without chaining, and a footer on the panel ground with its
+ * actions at the end. An overlay pane at regular density keeps the header it
+ * always had. A page that draws itself (`bare`, a command menu, a search)
+ * composes the same frame from `PaneBar`, `PaneBody` and `PaneFoot`.
+ *
+ * Escape closes a docked pane while focus is inside it (the overlay's
+ * SlideOver already does); ⌘/Ctrl+Enter runs the page's `onExpand`.
  */
 const react_1 = require("react");
 const gui_1 = require("@hanzo/gui");
 const lucide_icons_2_1 = require("@hanzogui/lucide-icons-2");
 const SlideOver_1 = require("./SlideOver.cjs");
 const color_1 = require("./color.cjs");
-const Ctx = (0, react_1.createContext)(null);
+const button_1 = require("../backends/gui/button.cjs");
+const tooltip_1 = require("../backends/gui/tooltip.cjs");
+const grip_1 = require("../backends/gui/grip.cjs");
+const span_1 = require("../backends/gui/span.cjs");
+const density_1 = require("../backends/gui/density.cjs");
+const slot_1 = require("../backends/gui/slot.cjs");
+const Ctx = /* @__PURE__ */ (0, react_1.createContext)(null);
+/** The page being drawn, for the bar a bare page composes. */
+const PageCtx = /* @__PURE__ */ (0, react_1.createContext)(null);
+/** The pane this sits in, or null outside one — for a page that adapts to being in a pane. */
+const usePane = () => (0, react_1.useContext)(Ctx);
+exports.usePane = usePane;
 function useDetailPane() {
     const ctx = (0, react_1.useContext)(Ctx);
     if (!ctx)
         throw new Error('useDetailPane must be used within <DetailPane>');
     return ctx;
 }
-function DetailPane({ children, zIndex }) {
-    const [isOpen, setIsOpen] = (0, react_1.useState)(false);
-    const [desc, setDesc] = (0, react_1.useState)(null);
-    const open = (0, react_1.useCallback)((descriptor) => {
-        setDesc(descriptor);
-        setIsOpen(true);
-    }, []);
-    const close = (0, react_1.useCallback)(() => setIsOpen(false), []);
-    const api = (0, react_1.useMemo)(() => ({ open, close, isOpen }), [open, close, isOpen]);
-    const Icon = desc?.icon;
-    return ((0, jsx_runtime_1.jsxs)(Ctx.Provider, { value: api, children: [children, (0, jsx_runtime_1.jsxs)(SlideOver_1.SlideOver, { open: isOpen, onClose: close, side: "right", size: desc?.size ?? 460, ariaLabel: typeof desc?.title === 'string' ? desc?.title : 'Details', zIndex: zIndex, children: [(0, jsx_runtime_1.jsxs)(gui_1.XStack, { items: "center", gap: "$2.5", px: "$4", height: 56, borderBottomWidth: 1, borderColor: "$borderColor", children: [Icon ? (0, jsx_runtime_1.jsx)(Icon, { size: 18, color: desc?.iconColor ? (0, color_1.asColor)(desc.iconColor) : undefined }) : null, (0, jsx_runtime_1.jsxs)(gui_1.YStack, { flex: 1, minW: 0, children: [(0, jsx_runtime_1.jsx)(gui_1.Text, { fontSize: "$5", fontWeight: "700", color: "$color12", numberOfLines: 1, children: desc?.title }), desc?.subtitle !== undefined ? ((0, jsx_runtime_1.jsx)(gui_1.Text, { fontSize: "$2", color: "$color10", numberOfLines: 1, children: desc?.subtitle })) : null] }), (0, jsx_runtime_1.jsx)(gui_1.Button, { size: "$2", chromeless: true, icon: (0, jsx_runtime_1.jsx)(lucide_icons_2_1.X, { size: 18 }), onPress: close, "aria-label": "Close" })] }), (0, jsx_runtime_1.jsx)(gui_1.ScrollView, { flex: 1, minH: 0, children: (0, jsx_runtime_1.jsx)(gui_1.YStack, { p: "$4", gap: "$3", children: desc?.content }) }), desc?.footer !== undefined ? ((0, jsx_runtime_1.jsx)(gui_1.XStack, { px: "$4", py: "$3", gap: "$2", borderTopWidth: 1, borderColor: "$borderColor", bg: "$color1", children: desc?.footer })) : null] })] }));
+/** The record frame's measures (twenty-ui's side panel, MIT). */
+exports.PANE = { w: 400, min: 320, max: 600, bar: 48, icon: 16 };
+function DetailPane({ children, zIndex, mode = 'overlay', store = 'hanzo.pane' }) {
+    // One state, so every transition is one pure update: whether it is open, and
+    // the pages it holds (kept through a close, so the exit animates with them).
+    const [state, setState] = (0, react_1.useState)({ open: false, stack: [] });
+    const { open: isOpen, stack } = state;
+    const density = (0, density_1.useDensity)();
+    const media = (0, gui_1.useMedia)();
+    const docked = mode === 'docked' && !!media.lg;
+    const record = mode === 'docked' || density === 'compact';
+    const open = (0, react_1.useCallback)((descriptor) => setState({ open: true, stack: [descriptor] }), []);
+    const push = (0, react_1.useCallback)((descriptor) => setState((s) => ({ open: true, stack: s.open ? [...s.stack, descriptor] : [descriptor] })), []);
+    const close = (0, react_1.useCallback)(() => setState((s) => ({ ...s, open: false })), []);
+    const back = (0, react_1.useCallback)(() => setState((s) => (s.stack.length > 1 ? { ...s, stack: s.stack.slice(0, -1) } : { ...s, open: false })), []);
+    const depth = isOpen ? stack.length : 0;
+    const api = (0, react_1.useMemo)(() => ({ open, push, back, close, isOpen, depth }), [open, push, back, close, isOpen, depth]);
+    const desc = stack[stack.length - 1] ?? null;
+    const title = typeof desc?.title === 'string' ? desc.title : 'Details';
+    const page = desc ? ((0, jsx_runtime_1.jsx)(PageCtx.Provider, { value: desc, children: record || desc.bare ? (0, jsx_runtime_1.jsx)(RecordPage, { desc: desc }) : (0, jsx_runtime_1.jsx)(SheetPage, { desc: desc, close: close }) })) : null;
+    if (docked)
+        return ((0, jsx_runtime_1.jsx)(Ctx.Provider, { value: api, children: (0, jsx_runtime_1.jsxs)(gui_1.XStack, { ...(0, slot_1.slot)('detail-pane-row'), flex: 1, minW: 0, minH: 0, self: "stretch", children: [(0, jsx_runtime_1.jsx)(gui_1.YStack, { flex: 1, minW: 0, minH: 0, children: children }), (0, jsx_runtime_1.jsx)(Dock, { open: isOpen, title: title, store: store, onClose: close, onExpand: desc?.onExpand, children: page })] }) }));
+    return ((0, jsx_runtime_1.jsxs)(Ctx.Provider, { value: api, children: [children, (0, jsx_runtime_1.jsx)(SlideOver_1.SlideOver, { open: isOpen, onClose: close, side: "right", size: desc?.size ?? (record ? exports.PANE.w : 460), ariaLabel: title, zIndex: zIndex, children: record && desc ? ((0, jsx_runtime_1.jsx)(gui_1.YStack, { flex: 1, minH: 0, bg: "$background", onKeyDown: expandKey(desc.onExpand), children: page })) : (page) })] }));
+}
+/** ⌘/Ctrl+Enter runs `onExpand`, from anywhere inside the pane. */
+const expandKey = (onExpand) => (e) => {
+    if (!onExpand || e.key !== 'Enter' || !(e.metaKey || e.ctrlKey))
+        return;
+    e.preventDefault?.();
+    onExpand();
+};
+/**
+ * The docked column. The OUTER box is what animates and what the Grip measures
+ * (its width is the pane's); the INNER box holds the target width throughout, so
+ * the page slides in already laid out.
+ */
+function Dock({ open, title, store, onClose, onExpand, children, }) {
+    const span = (0, span_1.useSpan)(store, exports.PANE.w, exports.PANE.min, exports.PANE.max);
+    const node = (0, react_1.useRef)(null);
+    const opener = (0, react_1.useRef)(null);
+    // Focus moves in when the pane opens and back to what opened it when it shuts:
+    // a docked pane is not modal, but a keyboard has to be able to reach it.
+    (0, react_1.useEffect)(() => {
+        if (!open || typeof document === 'undefined')
+            return;
+        opener.current = document.activeElement;
+        const t = window.setTimeout(() => node.current?.focus?.(), 0);
+        return () => {
+            window.clearTimeout(t);
+            const back = opener.current;
+            if (back instanceof HTMLElement && node.current?.contains(document.activeElement))
+                back.focus();
+        };
+    }, [open]);
+    return ((0, jsx_runtime_1.jsxs)(gui_1.YStack, { ref: ((el) => {
+            span.ref(el);
+            node.current = el instanceof HTMLElement ? el : null;
+        }), ...(0, slot_1.slot)('detail-pane'), "data-mode": "docked", "data-open": open ? '' : undefined, role: "complementary", "aria-label": title, "aria-hidden": !open, ...(!open ? { inert: true } : null), tabIndex: -1, position: "relative", shrink: 0, self: "stretch", overflow: "hidden", outlineWidth: 0, onKeyDown: ((e) => {
+            if (e.key === 'Escape' && !e.defaultPrevented) {
+                e.preventDefault?.();
+                onClose();
+                return;
+            }
+            expandKey(onExpand)(e);
+        }), style: {
+            ...span.style,
+            width: open ? 'var(--span)' : 0,
+            transition: 'width var(--duration-base, 300ms) var(--ease-out, ease)',
+        }, children: [(0, jsx_runtime_1.jsx)(gui_1.YStack, { width: "var(--span)", flex: 1, minH: 0, bg: "$background", borderLeftWidth: 1, borderColor: "$borderColor", children: children }), open ? ((0, jsx_runtime_1.jsx)(grip_1.Grip, { side: "right", span: span.span, floor: exports.PANE.min, ceil: exports.PANE.max, reset: exports.PANE.w, bar: "edge", label: "Resize side panel", onSpan: span.move, onKeep: span.keep, onShut: onClose })) : null] }));
+}
+/** The record frame of one page: the bar, the scrolling body, the footer. */
+function RecordPage({ desc }) {
+    if (desc.bare)
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: desc.content });
+    const Icon = desc.icon;
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsxs)(PaneBar, { actions: desc.actions, children: [Icon ? (0, jsx_runtime_1.jsx)(Icon, { size: exports.PANE.icon, color: desc.iconColor ? (0, color_1.asColor)(desc.iconColor) : '$aside' }) : null, (0, jsx_runtime_1.jsx)(gui_1.Text, { fontSize: "$2", fontWeight: "500", color: "$ink", numberOfLines: 1, shrink: 1, minW: 0, children: desc.title }), desc.subtitle !== undefined ? ((0, jsx_runtime_1.jsx)(gui_1.Text, { fontSize: "$2", color: "$hint", numberOfLines: 1, shrink: 1, minW: 0, children: desc.subtitle })) : null] }), (0, jsx_runtime_1.jsx)(PaneBody, { children: desc.content }), desc.footer !== undefined ? (0, jsx_runtime_1.jsx)(PaneFoot, { children: desc.footer }) : null] }));
+}
+/** The overlay sheet's own page, as it always was: the 56px header and the body. */
+function SheetPage({ desc, close }) {
+    const Icon = desc.icon;
+    const pane = (0, react_1.useContext)(Ctx);
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsxs)(gui_1.XStack, { items: "center", gap: "$2.5", px: "$4", height: 56, borderBottomWidth: 1, borderColor: "$borderColor", children: [pane && pane.depth > 1 ? ((0, jsx_runtime_1.jsx)(gui_1.Button, { size: "$2", chromeless: true, icon: (0, jsx_runtime_1.jsx)(lucide_icons_2_1.ChevronLeft, { size: 18 }), onPress: pane.back, "aria-label": "Back" })) : null, Icon ? (0, jsx_runtime_1.jsx)(Icon, { size: 18, color: desc.iconColor ? (0, color_1.asColor)(desc.iconColor) : undefined }) : null, (0, jsx_runtime_1.jsxs)(gui_1.YStack, { flex: 1, minW: 0, children: [(0, jsx_runtime_1.jsx)(gui_1.Text, { fontSize: "$5", fontWeight: "700", color: "$color12", numberOfLines: 1, children: desc.title }), desc.subtitle !== undefined ? ((0, jsx_runtime_1.jsx)(gui_1.Text, { fontSize: "$2", color: "$color10", numberOfLines: 1, children: desc.subtitle })) : null] }), (0, jsx_runtime_1.jsx)(gui_1.Button, { size: "$2", chromeless: true, icon: (0, jsx_runtime_1.jsx)(lucide_icons_2_1.X, { size: 18 }), onPress: close, "aria-label": "Close" })] }), (0, jsx_runtime_1.jsx)(gui_1.ScrollView, { flex: 1, minH: 0, children: (0, jsx_runtime_1.jsx)(gui_1.YStack, { p: "$4", gap: "$3", children: desc.content }) }), desc.footer !== undefined ? ((0, jsx_runtime_1.jsx)(gui_1.XStack, { px: "$4", py: "$3", gap: "$2", borderTopWidth: 1, borderColor: "$borderColor", bg: "$color1", children: desc.footer })) : null] }));
+}
+/**
+ * The record frame's top bar: 48 high on the panel ground, a hairline under
+ * it, 8 in from each side, its two clusters 16 apart and their parts 4 apart.
+ * Inside a pane it adds back (while there is a page under this one), expand
+ * (when the page can open on the main surface) and close; outside one it is the
+ * bar alone.
+ */
+function PaneBar({ children, actions }) {
+    const pane = (0, react_1.useContext)(Ctx);
+    const page = (0, react_1.useContext)(PageCtx);
+    const expand = page?.onExpand;
+    return ((0, jsx_runtime_1.jsxs)(gui_1.XStack, { ...(0, slot_1.slot)('pane-bar'), height: exports.PANE.bar, shrink: 0, items: "center", justify: "space-between", gap: "$4", px: "$2", bg: "$panel", borderBottomWidth: 1, borderColor: "$borderColor", children: [(0, jsx_runtime_1.jsxs)(gui_1.XStack, { flex: 1, minW: 0, items: "center", gap: "$1", children: [pane && pane.depth > 1 ? ((0, jsx_runtime_1.jsx)(Tool, { tip: "Back", onPress: pane.back, children: (0, jsx_runtime_1.jsx)(lucide_icons_2_1.ChevronLeft, {}) })) : null, children] }), (0, jsx_runtime_1.jsxs)(gui_1.XStack, { shrink: 0, items: "center", gap: "$1", children: [actions, expand ? ((0, jsx_runtime_1.jsx)(Tool, { tip: page?.expandLabel ?? 'Open', onPress: expand, children: (0, jsx_runtime_1.jsx)(lucide_icons_2_1.Maximize2, {}) })) : null, pane ? ((0, jsx_runtime_1.jsx)(Tool, { tip: "Close side panel", onPress: pane.close, children: (0, jsx_runtime_1.jsx)(lucide_icons_2_1.X, {}) })) : null] })] }));
+}
+/**
+ * The bar's quiet 24px icon button, named by its tooltip. The tooltip's trigger
+ * IS the button (`asChild`): wrapped in a box, the trigger's `aria-expanded`
+ * lands on a div, which axe refuses (`aria-allowed-attr`), and a button may
+ * carry it.
+ */
+function Tool({ tip, children, ...props }) {
+    return ((0, jsx_runtime_1.jsxs)(tooltip_1.Tooltip, { delay: 1000, placement: "bottom", children: [(0, jsx_runtime_1.jsx)(tooltip_1.TooltipTrigger, { asChild: true, children: (0, jsx_runtime_1.jsx)(button_1.Button, { size: "icon-xs", variant: "ghost", emphasis: "subtle", "aria-label": tip, ...props, children: children }) }), (0, jsx_runtime_1.jsx)(tooltip_1.TooltipContent, { children: tip })] }));
+}
+/** The record frame's body: it takes what the bar and footer leave, and scrolls without chaining to the page. */
+function PaneBody({ children, padded = true }) {
+    return ((0, jsx_runtime_1.jsx)(gui_1.ScrollView, { ...(0, slot_1.slot)('pane-body'), flex: 1, minH: 0, style: { overscrollBehavior: 'contain' }, children: (0, jsx_runtime_1.jsx)(gui_1.YStack, { ...(padded ? { p: '$2' } : null), gap: "$2", children: children }) }));
+}
+/** The record frame's footer: the panel ground, a hairline above, its actions at the end, 8 apart. */
+function PaneFoot({ children }) {
+    return ((0, jsx_runtime_1.jsx)(gui_1.XStack, { ...(0, slot_1.slot)('pane-foot'), shrink: 0, items: "center", justify: "flex-end", gap: "$2", px: "$3", py: "$2", bg: "$panel", borderTopWidth: 1, borderColor: "$borderColor", children: children }));
 }

package/dist/product/DetailPane.d.ts

@@ -13,6 +13,32 @@
  * The last descriptor stays mounted through the close transition, so the exit
  * animates with its content (no flash of empty pane). Opening a new
  * descriptor replaces it.
+ *
+ * A pane is a STACK of pages. `open` starts a new stack, `push` lays a page on
+ * top (a relation opened from a record, a step of a flow), `back` takes it off;
+ * the top bar shows a back button while there is a page under the current one.
+ *
+ * Two modes, chosen by the shell:
+ *
+ *   overlay  (default) the SlideOver above the page, with its scrim — the
+ *            console's contract, unchanged.
+ *   docked   a column in the layout row beside the page content: no scrim, the
+ *            content narrows. 400 wide, resizable 320–600 from its leading edge
+ *            by the kit's one resizer (Grip), the width kept per person
+ *            (useSpan). The width animates 0 ↔ W while the page inside keeps the
+ *            target width, so it never reflows mid-slide. Below lg it is the
+ *            overlay again, full screen.
+ *
+ * A docked pane — or any pane under `<Density value="compact">` — draws the
+ * record frame (twenty-ui's side panel, MIT, NOTICE): a 48px top bar on the
+ * panel ground (back · icon + title · page actions · expand · close), a body
+ * that scrolls without chaining, and a footer on the panel ground with its
+ * actions at the end. An overlay pane at regular density keeps the header it
+ * always had. A page that draws itself (`bare`, a command menu, a search)
+ * composes the same frame from `PaneBar`, `PaneBody` and `PaneFoot`.
+ *
+ * Escape closes a docked pane while focus is inside it (the overlay's
+ * SlideOver already does); ⌘/Ctrl+Enter runs the page's `onExpand`.
  */
 import { type ReactNode } from 'react';
 import { type IconLike } from './color.js';
@@ -24,24 +50,76 @@ export type DetailDescriptor = {
     /** Optional title icon, tinted with `iconColor`. */
     icon?: IconLike;
     iconColor?: string;
-    /** Desktop pane width (px). Mobile is always full-screen. Default 460. */
+    /** Desktop pane width (px), overlay mode. Mobile is always full-screen. Default 460 (400 in the record frame). */
     size?: number;
     /** The body — the detail view or edit form for the item. */
     content: ReactNode;
     /** Optional sticky footer (primary actions), pinned below the scroll body. */
     footer?: ReactNode;
+    /** The page's own actions, in the top bar before expand and close (record frame). */
+    actions?: ReactNode;
+    /** Opens the page on the main surface: shows the expand button and binds ⌘/Ctrl+Enter. */
+    onExpand?: () => void;
+    /** The expand button's tooltip. Default "Open". */
+    expandLabel?: string;
+    /** The page draws its own frame from `PaneBar` / `PaneBody` / `PaneFoot` (a command menu, a search). */
+    bare?: boolean;
 };
 export type DetailPaneApi = {
+    /** A new stack, holding this page. */
     open: (descriptor: DetailDescriptor) => void;
+    /** This page over the current one. Opens the pane when it is shut. */
+    push: (descriptor: DetailDescriptor) => void;
+    /** Off the top: the page under it shows. On the last page, the pane closes. */
+    back: () => void;
     close: () => void;
     isOpen: boolean;
+    /** How many pages the stack holds; a back button shows while it is more than one. */
+    depth: number;
 };
+/** The pane this sits in, or null outside one — for a page that adapts to being in a pane. */
+export declare const usePane: () => DetailPaneApi | null;
 export declare function useDetailPane(): DetailPaneApi;
 export type DetailPaneProps = {
     children: ReactNode;
     /** z-index for stacking — a pane opened over another overlay passes a
      *  higher value. Left to `SlideOver`'s own default otherwise. */
     zIndex?: number;
+    /** `overlay` (default) floats above the page; `docked` is a column in the layout beside it. */
+    mode?: 'overlay' | 'docked';
+    /** Where a docked pane keeps the width a person chose (localStorage key). */
+    store?: string;
 };
-export declare function DetailPane({ children, zIndex }: DetailPaneProps): import("react").JSX.Element;
+/** The record frame's measures (twenty-ui's side panel, MIT). */
+export declare const PANE: {
+    readonly w: 400;
+    readonly min: 320;
+    readonly max: 600;
+    readonly bar: 48;
+    readonly icon: 16;
+};
+export declare function DetailPane({ children, zIndex, mode, store }: DetailPaneProps): import("react").JSX.Element;
+export type PaneBarProps = {
+    /** The leading cluster after the back button: an icon and a title, or a search field. */
+    children?: ReactNode;
+    /** The page's own actions, before expand and close. */
+    actions?: ReactNode;
+};
+/**
+ * The record frame's top bar: 48 high on the panel ground, a hairline under
+ * it, 8 in from each side, its two clusters 16 apart and their parts 4 apart.
+ * Inside a pane it adds back (while there is a page under this one), expand
+ * (when the page can open on the main surface) and close; outside one it is the
+ * bar alone.
+ */
+export declare function PaneBar({ children, actions }: PaneBarProps): import("react").JSX.Element;
+/** The record frame's body: it takes what the bar and footer leave, and scrolls without chaining to the page. */
+export declare function PaneBody({ children, padded }: {
+    children?: ReactNode;
+    padded?: boolean;
+}): import("react").JSX.Element;
+/** The record frame's footer: the panel ground, a hairline above, its actions at the end, 8 apart. */
+export declare function PaneFoot({ children }: {
+    children?: ReactNode;
+}): import("react").JSX.Element;
 //# sourceMappingURL=DetailPane.d.ts.map

package/dist/product/DetailPane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DetailPane.d.ts","sourceRoot":"","sources":["../../src/product/DetailPane.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAKd,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEhD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oCAAoC;IACpC,KAAK,EAAE,SAAS,CAAA;IAChB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,oDAAoD;IACpD,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,OAAO,EAAE,SAAS,CAAA;IAClB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAID,wBAAgB,aAAa,IAAI,aAAa,CAI7C;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,SAAS,CAAA;IACnB;qEACiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,eAAe,+BAsD/D"}
+{"version":3,"file":"DetailPane.d.ts","sourceRoot":"","sources":["../../src/product/DetailPane.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAKd,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAA;AAQhD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oCAAoC;IACpC,KAAK,EAAE,SAAS,CAAA;IAChB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,oDAAoD;IACpD,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kHAAkH;IAClH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,OAAO,EAAE,SAAS,CAAA;IAClB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,qFAAqF;IACrF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wGAAwG;IACxG,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,sCAAsC;IACtC,IAAI,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAC5C,sEAAsE;IACtE,IAAI,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAC5C,+EAA+E;IAC/E,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;IACf,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAMD,8FAA8F;AAC9F,eAAO,MAAM,OAAO,QAAO,aAAa,GAAG,IAAuB,CAAA;AAElE,wBAAgB,aAAa,IAAI,aAAa,CAI7C;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,SAAS,CAAA;IACnB;qEACiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+FAA+F;IAC/F,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC3B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,IAAI;aAAK,CAAC,EAAE,GAAG;aAAE,GAAG,EAAE,GAAG;aAAE,GAAG,EAAE,GAAG;aAAE,GAAG,EAAE,EAAE;aAAE,IAAI,EAAE,EAAE;CAAW,CAAA;AAE9E,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAgB,EAAE,KAAoB,EAAE,EAAE,eAAe,+BAuEvG;AA0KD,MAAM,MAAM,YAAY,GAAG;IACzB,yFAAyF;IACzF,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,uDAAuD;IACvD,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,YAAY,+BAwC1D;AAqBD,iHAAiH;AACjH,wBAAgB,QAAQ,CAAC,EAAE,QAAQ,EAAE,MAAa,EAAE,EAAE;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,+BAQ/F;AAED,sGAAsG;AACtG,wBAAgB,QAAQ,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,+BAiB9D"}