@xenosystem/elements-react 0.0.1

package/dist/overlays/Tabs.js

@@ -0,0 +1,142 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useLayoutEffect, useRef, useState } from 'react';
+import { XenoElement } from '../XenoElement.js';
+import { sizeAttr, iconPx, cx } from '../controls/util.js';
+// useLayoutEffect measures before paint on the client; fall back to useEffect on the server so SSR does
+// not warn. (Same seam as <Reveal>.)
+const useIsoLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+export function Tabs({ value, onValueChange, items, size = 'md', renderPanel, children, className, 'aria-label': ariaLabel, ...rest }) {
+    const baseId = useId();
+    const tabRefs = useRef([]);
+    const listRef = useRef(null);
+    const glyph = iconPx(size);
+    const currentIndex = items.findIndex((it) => it.value === value);
+    /**
+     * The underline is ONE bar that slides from the old tab to the new one, and to slide it has to know
+     * where the new tab starts and how wide it is. A stylesheet cannot know that: a tab is as wide as its
+     * label, which only layout can answer. So the component measures — once, when the selection or the
+     * layout changes — and hands CSS two numbers. Measuring is not animating: CSS still owns every frame
+     * between them, and nothing here runs per-frame.
+     *
+     * The alternative was forcing every tab to the same width, which would make it pure arithmetic (that
+     * is what SegmentedControl does). Tabs are labels, not segments — they should keep their own width.
+     */
+    const [bar, setBar] = useState({ x: 0, w: 0 });
+    useIsoLayoutEffect(() => {
+        const list = listRef.current;
+        const tab = currentIndex >= 0 ? tabRefs.current[currentIndex] : null;
+        if (!list)
+            return;
+        const measure = () => {
+            if (!tab) {
+                setBar((b) => (b.w === 0 ? b : { x: b.x, w: 0 }));
+                return;
+            }
+            const x = tab.offsetLeft;
+            const w = tab.offsetWidth;
+            setBar((b) => (b.x === x && b.w === w ? b : { x, w }));
+        };
+        measure();
+        // Re-measure when the list is resized or a web font finally lands and relays the labels out.
+        const ro = new ResizeObserver(measure);
+        ro.observe(list);
+        for (const t of tabRefs.current)
+            if (t)
+                ro.observe(t);
+        return () => ro.disconnect();
+    }, [currentIndex, items, size]);
+    /* The travel is a transition, and a transition fires the moment the value changes — including the
+       first measurement after mount, which would slide the bar in from the left edge on page load. Arm on
+       the first genuine change of `value`. */
+    const [armed, setArmed] = useState(false);
+    const [seen, setSeen] = useState(value);
+    const [distance, setDistance] = useState(1);
+    if (seen !== value) {
+        const from = items.findIndex((it) => it.value === seen);
+        if (from >= 0 && currentIndex >= 0)
+            setDistance(Math.min(2, Math.abs(currentIndex - from)));
+        setSeen(value);
+        if (!armed)
+            setArmed(true);
+    }
+    // Only the MEASURED values stay inline — they are per-instance and cannot come from a stylesheet.
+    // The size metrics moved to `data-xeno-size` so a surface can reach them.
+    const listVars = {
+        '--xeno-tab-x': `${bar.x}px`,
+        '--xeno-tab-w': `${bar.w}px`,
+        '--xeno-tab-dist': distance,
+    };
+    const activate = (index) => {
+        const item = items[index];
+        if (!item || item.disabled)
+            return;
+        onValueChange?.(item.value);
+        tabRefs.current[index]?.focus();
+    };
+    const step = (from, dir) => {
+        const n = items.length;
+        let idx = from;
+        for (let k = 0; k < n; k++) {
+            idx = (idx + dir + n) % n;
+            const it = items[idx];
+            if (it && !it.disabled)
+                return idx;
+        }
+        return from;
+    };
+    const edge = (dir) => {
+        const n = items.length;
+        if (dir === 1) {
+            for (let i = 0; i < n; i++) {
+                const it = items[i];
+                if (it && !it.disabled)
+                    return i;
+            }
+            return 0;
+        }
+        for (let i = n - 1; i >= 0; i--) {
+            const it = items[i];
+            if (it && !it.disabled)
+                return i;
+        }
+        return n - 1;
+    };
+    const onKeyDown = (e) => {
+        if (items.length === 0)
+            return;
+        const base = currentIndex < 0 ? 0 : currentIndex;
+        switch (e.key) {
+            case 'ArrowRight':
+                e.preventDefault();
+                activate(step(base, 1));
+                break;
+            case 'ArrowLeft':
+                e.preventDefault();
+                activate(step(base, -1));
+                break;
+            case 'Home':
+                e.preventDefault();
+                activate(edge(1));
+                break;
+            case 'End':
+                e.preventDefault();
+                activate(edge(-1));
+                break;
+        }
+    };
+    const hasPanel = renderPanel !== undefined || children !== undefined;
+    const panelId = `${baseId}-panel`;
+    const panelContent = renderPanel !== undefined ? renderPanel(value) : children;
+    return (_jsxs("div", { className: cx('xeno-tabs', className), ...rest, children: [_jsxs("div", { ref: listRef, role: "tablist", "aria-orientation": "horizontal", className: "xeno-tablist", "data-index": currentIndex >= 0 ? Math.min(7, currentIndex) : undefined, ...(armed ? { 'data-motion': 'ready' } : {}), ...sizeAttr(size), style: listVars, onKeyDown: onKeyDown, ...(ariaLabel !== undefined ? { 'aria-label': ariaLabel } : {}), children: [items.map((item, i) => {
+                        const selected = item.value === value;
+                        const disabled = item.disabled ?? false;
+                        const focusable = selected || (currentIndex < 0 && i === 0);
+                        return (_jsxs("button", { type: "button", role: "tab", id: `${baseId}-tab-${item.value}`, ref: (el) => {
+                                tabRefs.current[i] = el;
+                            }, className: "xeno-tab", "data-selection": selected ? 'on' : 'off', "data-availability": disabled ? 'disabled' : 'enabled', "aria-selected": selected, "aria-disabled": disabled || undefined, ...(hasPanel ? { 'aria-controls': panelId } : {}), tabIndex: focusable ? 0 : -1, onClick: () => {
+                                if (disabled)
+                                    return;
+                                onValueChange?.(item.value);
+                            }, children: [item.icon && _jsx(XenoElement, { decl: item.icon, size: glyph }), _jsx("span", { className: "xeno-tab-label", children: item.label })] }, item.value));
+                    }), _jsx("span", { className: "xeno-tab-indicator", "aria-hidden": "true" })] }), hasPanel && (_jsx("div", { role: "tabpanel", id: panelId, "aria-labelledby": `${baseId}-tab-${value}`, tabIndex: 0, className: "xeno-tab-panel", children: panelContent }))] }));
+}

package/dist/overlays/Tooltip.d.ts

@@ -0,0 +1,23 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from 'react';
+/**
+ * `<Tooltip>` — a hover/focus hint. Behaviour is hand-rolled (no portal lib, no Base UI): a
+ * `position: relative` wrapper holds the trigger (children) and an absolutely-positioned
+ * `role="tooltip"` panel that sits on one `side`. The panel is ALWAYS in the DOM (present for SSR
+ * and for the screen reader via `aria-describedby`); JS flips `data-state` to reveal it and the CSS
+ * animates opacity/transform. Reveal is instant on keyboard focus and, on hover, waits `delay` ms;
+ * per the ARIA tooltip pattern, Escape dismisses it while the pointer/focus stay put.
+ *
+ * Monochrome shell: an `--xeno-elevated` panel with a hairline border and muted 12px mono text.
+ */
+export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
+export interface TooltipProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'content' | 'children'> {
+    /** The hint — any node; rendered into the `role="tooltip"` panel. */
+    readonly content: ReactNode;
+    /** The trigger. A single element is wired with `aria-describedby`; other nodes render as-is. */
+    readonly children: ReactNode;
+    /** Which side of the trigger the panel sits on. Default `top`. */
+    readonly side?: TooltipSide;
+    /** Milliseconds to wait before the hover reveal (keyboard focus is always instant). Default 150. */
+    readonly delay?: number;
+}
+export declare function Tooltip({ content, children, side, delay, className, onKeyDown, onMouseEnter, onMouseLeave, onFocus, onBlur, ...rest }: TooltipProps): ReactElement;

package/dist/overlays/Tooltip.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cloneElement, isValidElement, useCallback, useEffect, useId, useRef, useState, } from 'react';
+import { cx } from '../controls/util.js';
+export function Tooltip({ content, children, side = 'top', delay = 150, className, onKeyDown, onMouseEnter, onMouseLeave, onFocus, onBlur, ...rest }) {
+    const panelId = useId();
+    const [hovered, setHovered] = useState(false);
+    const [focused, setFocused] = useState(false);
+    const [dismissed, setDismissed] = useState(false);
+    const timer = useRef(undefined);
+    const clear = useCallback(() => {
+        if (timer.current !== undefined) {
+            clearTimeout(timer.current);
+            timer.current = undefined;
+        }
+    }, []);
+    useEffect(() => clear, [clear]);
+    /* Every one of these CHAINS the caller's handler rather than replacing it. They used to be written
+       after `{...rest}` in the JSX, which meant a caller's `onMouseEnter` / `onMouseLeave` / `onFocus` /
+       `onBlur` was silently overridden — `onKeyDown` was already chained here, which is what shows the
+       other four were an oversight rather than a decision. */
+    const openHover = useCallback((e) => {
+        onMouseEnter?.(e);
+        clear();
+        if (delay > 0) {
+            timer.current = setTimeout(() => setHovered(true), delay);
+        }
+        else {
+            setHovered(true);
+        }
+    }, [clear, delay, onMouseEnter]);
+    const closeHover = useCallback((e) => {
+        onMouseLeave?.(e);
+        clear();
+        setHovered(false);
+        setDismissed(false);
+    }, [clear, onMouseLeave]);
+    const openFocus = useCallback((e) => {
+        onFocus?.(e);
+        setFocused(true);
+    }, [onFocus]);
+    const closeFocus = useCallback((e) => {
+        onBlur?.(e);
+        setFocused(false);
+        setDismissed(false);
+    }, [onBlur]);
+    const handleKeyDown = useCallback((e) => {
+        onKeyDown?.(e);
+        if (e.key === 'Escape')
+            setDismissed(true);
+    }, [onKeyDown]);
+    const open = (hovered || focused) && !dismissed;
+    const state = open ? 'open' : 'closed';
+    // Wire the description onto the interactive trigger when it is a single element (the correct
+    // aria-describedby seam); fall back to rendering plain nodes as-is (the role still describes it).
+    const trigger = isValidElement(children)
+        ? cloneElement(children, {
+            'aria-describedby': panelId,
+        })
+        : children;
+    return (_jsxs("span", { className: cx('xeno-tooltip', className), "data-side": side, "data-state": state, ...rest, onMouseEnter: openHover, onMouseLeave: closeHover, onFocus: openFocus, onBlur: closeFocus, onKeyDown: handleKeyDown, children: [trigger, _jsxs("span", { className: "xeno-tooltip-panel", role: "tooltip", id: panelId, "data-side": side, "data-state": state, children: [content, _jsx("span", { className: "xeno-tooltip-arrow", "aria-hidden": "true" })] })] }));
+}

package/dist/status/ProgressBar.d.ts

@@ -0,0 +1,20 @@
+import type { HTMLAttributes, ReactElement } from 'react';
+/**
+ * `<ProgressBar>` — the determinate progress signal. A flat track (`--xeno-control`, `radius-sm`,
+ * ~4px tall) holds a fill (`--xeno-text`) whose width is the clamped `value` (0..1) as a percentage.
+ * The track carries `role="progressbar"` + `aria-valuenow/min/max` (0..100). An optional `label`
+ * adds a header row (label + a tabular percent readout) that is `aria-hidden` — the progressbar
+ * already announces its name and value, so the visible header would only double-read.
+ */
+export interface ProgressBarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * Progress fraction, 0..1. Values outside the range are clamped; non-finite reads as 0. Pass `null`
+     * for INDETERMINATE — work is happening but its extent is not known. That is a different statement
+     * from `0`, which claims the work has measurably not started, and it is the one this component could
+     * not make until now.
+     */
+    readonly value: number | null;
+    /** Optional caption; also becomes the progressbar's accessible name. */
+    readonly label?: string;
+}
+export declare function ProgressBar({ value, label, className, ...rest }: ProgressBarProps): ReactElement;

package/dist/status/ProgressBar.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../controls/util.js';
+export function ProgressBar({ value, label, className, ...rest }) {
+    const indeterminate = value === null;
+    const safe = value !== null && Number.isFinite(value) ? value : 0;
+    const fraction = Math.min(1, Math.max(0, safe));
+    const pct = Math.round(fraction * 100);
+    // Keep the fill width to 0.1% precision so the inline style stays clean of float noise.
+    const widthPct = Math.round(fraction * 1000) / 10;
+    return (_jsxs("div", { className: cx('xeno-progressbar', className), ...rest, children: [label !== undefined && (_jsxs("div", { className: "xeno-progressbar-header", "aria-hidden": "true", children: [_jsx("span", { className: "xeno-progressbar-label", children: label }), _jsx("span", { className: "xeno-progressbar-value", children: indeterminate ? '—' : `${pct}%` })] })), _jsx("span", { role: "progressbar", ...(indeterminate ? {} : { 'aria-valuenow': pct }), "aria-valuemin": 0, "aria-valuemax": 100, "aria-label": label !== undefined ? label : 'Progress', className: "xeno-progressbar-track", "data-state": indeterminate ? 'indeterminate' : 'determinate', children: _jsx("span", { className: "xeno-progressbar-fill", ...(indeterminate ? {} : { style: { width: `${widthPct}%` } }) }) })] }));
+}

package/dist/status/Spinner.d.ts

@@ -0,0 +1,16 @@
+import type { HTMLAttributes, ReactElement } from 'react';
+/**
+ * `<Spinner>` — the indeterminate loader, the `busy` signal made visible. A small rounded SQUARE
+ * outline (never a circle): all four edges sit in `--xeno-muted` as the track, the top edge burns to
+ * `--xeno-text` as the bright leading edge, and the whole square rotates. `size` drives both the edge
+ * length and the stroke, emitted as inline `--xeno-spinner-size/-stroke` vars so the metrics can never
+ * drift from the data. Motion lives behind `prefers-reduced-motion: no-preference`. Announces itself
+ * with `role="status"` + `aria-label` (default `'Loading'`).
+ */
+export interface SpinnerProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /** Edge length of the square, in px. Stroke scales with it. Defaults to 16. */
+    readonly size?: number;
+    /** The accessible label announced by assistive tech. Defaults to `'Loading'`. */
+    readonly label?: string;
+}
+export declare function Spinner({ size, label, className, style, ...rest }: SpinnerProps): ReactElement;

package/dist/status/Spinner.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from '../controls/util.js';
+export function Spinner({ size = 16, label = 'Loading', className, style, ...rest }) {
+    // Guard against a zero/negative/NaN size, then scale the stroke off the edge (min 2px).
+    const edge = Number.isFinite(size) && size > 0 ? size : 16;
+    const stroke = Math.max(2, Math.round(edge / 8));
+    const vars = {
+        ['--xeno-spinner-size']: `${edge}px`,
+        ['--xeno-spinner-stroke']: `${stroke}px`,
+    };
+    return (_jsx("span", { role: "status", "aria-label": label, "aria-live": "polite", className: cx('xeno-spinner', className), style: { ...vars, ...style }, ...rest }));
+}

package/dist/status/StatusIndicator.d.ts

@@ -0,0 +1,19 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from 'react';
+/**
+ * `<StatusIndicator>` — an inline square status MARK (radius-xs, never a circle) beside a label. The
+ * `tone` colours the mark CSS-first via `data-tone`:
+ *   - `neutral` — a `--xeno-muted` square (dormant);
+ *   - `active`  — a `--xeno-active` square that BREATHES (scale keyframe, silenced under reduced-motion);
+ *   - `success` — the `success` status TOKEN, injected as the inline `--xeno-status-tone` var so the
+ *                 value can never drift from the data;
+ *   - `danger`  — the theme's `--xeno-danger` (the one sanctioned hue that IS a theme var).
+ * `neutral`/`active` stay inside the monochrome shell; `success`/`danger` are the status exceptions.
+ */
+export type StatusIndicatorTone = 'neutral' | 'active' | 'success' | 'danger';
+export interface StatusIndicatorProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'style'> {
+    /** The label sitting after the mark. */
+    readonly children: ReactNode;
+    /** Colours the mark. Defaults to `neutral`. */
+    readonly tone?: StatusIndicatorTone;
+}
+export declare function StatusIndicator({ children, tone, className, ...rest }: StatusIndicatorProps): ReactElement;

package/dist/status/StatusIndicator.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { status } from '@xenosystem/elements/tokens';
+import { cx } from '../controls/util.js';
+export function StatusIndicator({ children, tone = 'neutral', className, ...rest }) {
+    // success is not a theme var — resolve it from the status TOKEN into an inline CSS var.
+    // neutral/active/danger need no inline var (monochrome, or danger = --xeno-danger in CSS).
+    const toneStyle = tone === 'success'
+        ? { ['--xeno-status-tone']: status.success }
+        : undefined;
+    return (_jsxs("span", { className: cx('xeno-statusindicator', className), "data-tone": tone, ...(toneStyle ? { style: toneStyle } : {}), ...rest, children: [_jsx("span", { className: "xeno-statusindicator-mark", "aria-hidden": "true" }), _jsx("span", { className: "xeno-statusindicator-label", children: children })] }));
+}

package/dist/status/StepTimeline.d.ts

@@ -0,0 +1,26 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from 'react';
+/**
+ * `<StepTimeline>` — a vertical run of steps threaded by a single hairline spine (a 1.5px rounded
+ * `--xeno-border` bar). Each step owns a square status MARK (radius-xs, never a circle) whose paint is
+ * driven CSS-first by `data-status` on the step:
+ *   - `pending` — an outline square in `--xeno-muted` (not yet reached);
+ *   - `active`  — a filled square that BREATHES (a scale keyframe, silenced under reduced-motion);
+ *   - `done`    — a filled `--xeno-text` square stamped with the `check` glyph (in `--xeno-on-accent`).
+ * Beside the mark sit a label and an optional `time` (mono, muted). The list is static (no interaction),
+ * so `data-status` is the only state seam; a visually-hidden word carries each step's status to a
+ * screen reader while the decorative rail stays `aria-hidden`.
+ */
+export type StepStatus = 'pending' | 'active' | 'done';
+export interface Step {
+    /** The step's name. */
+    readonly label: ReactNode;
+    /** Where the step sits in the run — drives the mark's paint via `data-status`. */
+    readonly status: StepStatus;
+    /** Optional trailing timestamp/duration, rendered mono + muted. */
+    readonly time?: string;
+}
+export interface StepTimelineProps extends Omit<HTMLAttributes<HTMLOListElement>, 'children'> {
+    /** The steps, top to bottom. The spine threads every mark but the last. */
+    readonly steps: readonly Step[];
+}
+export declare function StepTimeline({ steps, className, ...rest }: StepTimelineProps): ReactElement;

package/dist/status/StepTimeline.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { XenoElement } from '../XenoElement.js';
+import { cx } from '../controls/util.js';
+import Check from '@xenosystem/elements/elements/check';
+/** Glyph px inside the ~16px done mark — small enough to breathe within the square. */
+const GLYPH_PX = 11;
+/** The word a screen reader hears for each status (the mark itself is decorative). */
+const STATUS_WORD = {
+    pending: 'Pending',
+    active: 'In progress',
+    done: 'Done',
+};
+export function StepTimeline({ steps, className, ...rest }) {
+    const lastIndex = steps.length - 1;
+    return (_jsx("ol", { className: cx('xeno-steptimeline', className), ...rest, children: steps.map((step, i) => (_jsxs("li", { className: "xeno-steptimeline-step", "data-status": step.status, children: [_jsxs("span", { className: "xeno-steptimeline-rail", "aria-hidden": "true", children: [_jsx("span", { className: "xeno-steptimeline-mark", children: step.status === 'done' ? _jsx(XenoElement, { decl: Check, size: GLYPH_PX }) : null }), i !== lastIndex && _jsx("span", { className: "xeno-steptimeline-spine" })] }), _jsxs("span", { className: "xeno-steptimeline-body", children: [_jsxs("span", { className: "xeno-steptimeline-label", children: [step.label, _jsxs("span", { className: "xeno-steptimeline-sr", children: [" \u2014 ", STATUS_WORD[step.status]] })] }), step.time !== undefined && (_jsx("span", { className: "xeno-steptimeline-time", children: step.time }))] })] }, i))) }));
+}

package/dist/status/ThinkingCube.d.ts

@@ -0,0 +1,24 @@
+import type { HTMLAttributes, ReactElement } from 'react';
+/**
+ * `<ThinkingCube>` — the LOCKED branded model avatar. A single rounded SQUARE (`radius.xs`, muted 1.5px
+ * outline) that runs ONE continuous animation per state — never a set of discrete frames, never a circle:
+ *
+ * - `state="thinking"` — the cube *breathes*: `xeno-cube-life` rotates it 0→360° while the scale pulses
+ *   1 → .52 → 1, looping forever. The outline stays muted and the fill stays on the canvas (an opaque
+ *   outlined square, not a hollow gap).
+ * - `state="settled"` — the answer landed: `xeno-cube-settle` runs ONCE, growing the scale .8 → 1.14 → 1
+ *   while the SAME square's background fills opaque canvas → muted (both ends opaque, so there is never a
+ *   dead invisible phase), then rests as a solid muted cube.
+ *
+ * The visual body is `aria-hidden`; the root is `role="img"` with a state-aware label so a screen reader
+ * announces the model's status once. Honours `prefers-reduced-motion`: reduce → no spin, and `settled`
+ * shows the filled square statically. `size` (default 24) is the pixel edge, forwarded as a CSS var.
+ */
+export type ThinkingCubeState = 'thinking' | 'settled';
+export interface ThinkingCubeProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /** Which continuous animation the cube runs. */
+    readonly state: ThinkingCubeState;
+    /** Pixel edge length of the square. Default 24. */
+    readonly size?: number;
+}
+export declare function ThinkingCube({ state, size, className, style, ...rest }: ThinkingCubeProps): ReactElement;

package/dist/status/ThinkingCube.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from '../controls/util.js';
+/** Default accessible label per state (a caller may override with an explicit `aria-label`). */
+const CUBE_LABEL = {
+    thinking: 'Model is thinking',
+    settled: 'Answer ready',
+};
+export function ThinkingCube({ state, size = 24, className, style, ...rest }) {
+    const rootStyle = { ['--xeno-cube-size']: `${size}px`, ...style };
+    return (_jsx("span", { className: cx('xeno-cube', className), "data-state": state, role: "img", "aria-label": CUBE_LABEL[state], style: rootStyle, ...rest, children: _jsx("span", { className: "xeno-cube-body", "aria-hidden": "true" }) }));
+}

package/dist/useDialog.d.ts

@@ -0,0 +1,45 @@
+import type { KeyboardEvent as ReactKeyboardEvent, MutableRefObject } from 'react';
+/**
+ * `useDialog()` — everything a dialog has to DO, for a dialog this library did not build.
+ *
+ * Escape closes it, focus moves in when it opens and returns to whatever opened it when it closes, Tab
+ * stays inside, and the page behind stops scrolling. None of that is visual, and all of it is what
+ * separates a dialog from a `<div>` that happens to sit above the page.
+ *
+ * It exists because {@link Modal} had all of this and nothing else could reach it. A product with its
+ * own dialog design — its own scrim, its own card, its own entrance — had the choice of adopting the
+ * component and its looks together or writing the behaviour again, and what actually happens is the
+ * third thing: the behaviour never gets written. Measured on a real one before this existed — focus
+ * stayed on `body` when it opened, Tab walked straight out into the page behind it, and closing it left
+ * focus nowhere. The look was finished; the dialog was not.
+ *
+ * So the look stays with the product and the behaviour comes from here, one line at a time:
+ *
+ * ```tsx
+ * const { panelProps } = useDialog({ open, onClose })
+ * return open ? <div className="my-scrim"><div role="dialog" aria-modal="true" {...panelProps} /></div> : null
+ * ```
+ */
+export interface UseDialogOptions<T extends HTMLElement> {
+    /** Whether the dialog is open. Everything here is inert while false. */
+    readonly open: boolean;
+    /** Called on Escape. Omit and the hook leaves the key alone. */
+    readonly onClose?: () => void;
+    /** An existing ref for the panel, if the caller already has one. */
+    readonly panelRef?: MutableRefObject<T | null>;
+    /** Lock the page scroll behind the dialog. Default `true`. */
+    readonly lockScroll?: boolean;
+}
+export interface UseDialogResult<T extends HTMLElement> {
+    /** The dialog panel. `panelProps` already carries it. */
+    readonly panelRef: MutableRefObject<T | null>;
+    /** Spread on the element that carries `role="dialog"`. */
+    readonly panelProps: {
+        /** A CALLBACK ref — it is what makes focus land the moment the panel exists. */
+        readonly ref: (node: T | null) => void;
+        /** So the panel itself can hold focus before the user has tabbed to anything. */
+        readonly tabIndex: -1;
+        readonly onKeyDown: (e: ReactKeyboardEvent<T>) => void;
+    };
+}
+export declare function useDialog<T extends HTMLElement = HTMLDivElement>({ open, onClose, panelRef: providedRef, lockScroll, }: UseDialogOptions<T>): UseDialogResult<T>;

package/dist/useDialog.js

@@ -0,0 +1,122 @@
+import { useCallback, useEffect, useRef } from 'react';
+const FOCUSABLE = 'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+/**
+ * Page-scroll lock, REFCOUNTED across every open dialog.
+ *
+ * Each dialog saving and restoring `document.body.style.overflow` for itself is only correct while
+ * exactly one exists. Two mounted as siblings both capture a value and both write one back, in tree
+ * order: the first restores `''`, and the second then restores the `'hidden'` it captured — leaving the
+ * page permanently unscrollable with nothing on screen. A count, and one saved value taken when the
+ * count leaves zero, is the whole fix.
+ */
+let scrollLocks = 0;
+let scrollPrevious = '';
+const lockPageScroll = () => {
+    if (scrollLocks === 0) {
+        scrollPrevious = document.body.style.overflow;
+        document.body.style.overflow = 'hidden';
+    }
+    scrollLocks += 1;
+};
+const unlockPageScroll = () => {
+    scrollLocks = Math.max(0, scrollLocks - 1);
+    if (scrollLocks === 0)
+        document.body.style.overflow = scrollPrevious;
+};
+export function useDialog({ open, onClose, panelRef: providedRef, lockScroll = true, }) {
+    const ownRef = useRef(null);
+    const panelRef = providedRef ?? ownRef;
+    const restoreFocus = useRef(null);
+    // Escape, bound on the DOCUMENT so it fires regardless of where focus sits inside the dialog.
+    useEffect(() => {
+        if (!open || !onClose)
+            return;
+        const onKey = (e) => {
+            if (e.key !== 'Escape')
+                return;
+            /* `stopImmediatePropagation`, not `stopPropagation`. This listener is on `document`, the last node
+               in the bubble path, so there is nothing left to propagate TO — and stopping propagation says
+               nothing about other listeners on the same node. Only the immediate form reaches them. The case
+               it is here for: a dialog opened from inside a menu or popover that keeps its own document-level
+               Escape handler, where one press would otherwise close the dialog and the surface behind it. */
+            e.stopImmediatePropagation();
+            onClose();
+        };
+        document.addEventListener('keydown', onKey);
+        return () => document.removeEventListener('keydown', onKey);
+    }, [open, onClose]);
+    useEffect(() => {
+        if (!open || !lockScroll)
+            return;
+        lockPageScroll();
+        return unlockPageScroll;
+    }, [open, lockScroll]);
+    /**
+     * Focus in when the panel APPEARS, not when `open` turns true.
+     *
+     * Those are the same moment only for a dialog that renders in the same commit as its flag. Real ones
+     * often do not: a common shape is open-then-mount, where one state flag says the dialog is open and a
+     * second, set by an effect that reacts to the first, is what actually renders the portal. An effect
+     * that focuses `panelRef.current` finds null, and focusing on the next frame is a guess — sometimes the
+     * panel is there and sometimes it is still two commits away. Measured on the chat's delete
+     * confirmation: trap and Escape worked, and focus never moved at all.
+     *
+     * A callback ref has no timing to get wrong. It runs the instant the node attaches, whenever that is.
+     *
+     * It also captures the element to restore to, right there, because a callback ref fires during commit —
+     * BEFORE effects — so an effect that read `document.activeElement` would already be reading the panel
+     * we are about to focus, and "restore" would mean restoring to the dialog itself.
+     */
+    const focusedOnce = useRef(false);
+    const openRef = useRef(open);
+    openRef.current = open;
+    const setPanel = useCallback((node) => {
+        panelRef.current = node;
+        if (!node || !openRef.current || focusedOnce.current)
+            return;
+        restoreFocus.current = document.activeElement;
+        focusedOnce.current = true;
+        node.focus();
+    }, [panelRef]);
+    // Hand focus back to the opener on close. The cleanup of an effect that only runs while open IS the
+    // close, and nothing else has to know when that happened.
+    useEffect(() => {
+        if (!open)
+            return;
+        return () => {
+            focusedOnce.current = false;
+            restoreFocus.current?.focus?.();
+        };
+    }, [open]);
+    const onKeyDown = useCallback((e) => {
+        if (e.key !== 'Tab')
+            return;
+        const panel = panelRef.current;
+        if (!panel)
+            return;
+        // `offsetParent === null` filters out anything hidden — a collapsed section's controls are in the
+        // DOM and must not be tab stops.
+        const list = Array.from(panel.querySelectorAll(FOCUSABLE)).filter((n) => n.offsetParent !== null);
+        const first = list[0];
+        const last = list[list.length - 1];
+        if (!first || !last) {
+            // Nothing focusable inside: hold focus on the panel rather than letting Tab walk out.
+            e.preventDefault();
+            panel.focus();
+            return;
+        }
+        const active = document.activeElement;
+        if (e.shiftKey && active === first) {
+            e.preventDefault();
+            last.focus();
+        }
+        else if (!e.shiftKey && active === last) {
+            e.preventDefault();
+            first.focus();
+        }
+    }, [panelRef]);
+    return {
+        panelRef,
+        panelProps: { ref: setPanel, tabIndex: -1, onKeyDown },
+    };
+}

package/dist/useGooPill.d.ts

@@ -0,0 +1,57 @@
+import type { FocusEvent as ReactFocusEvent, MouseEvent as ReactMouseEvent, MutableRefObject, ReactElement, RefObject } from 'react';
+/**
+ * `useGooPill()` — the travelling hover pill (`goo.css`) for a list this hook does not own.
+ *
+ * The pill is CSS; the two numbers CSS cannot work out are where the hovered row starts and how tall it
+ * is. This hook reads them off the row and writes them to the host as custom properties. Everything
+ * between those numbers — the travel, the stretch, the fade — stays in the stylesheet.
+ *
+ * MEASURED rather than computed, and that is the whole reason it exists. A component that owns its rows
+ * (the sidebar maps an `items` array) can do this in pure CSS: every row is the same height, so the
+ * offset is `index x stride`. A host that takes arbitrary children cannot — someone will put a
+ * separator, a heading or a two-line row in there, and a stride from a constant lands the pill between
+ * two rows with nothing to say why.
+ *
+ * Usage — spread `hostProps` on the list and render `pill` as its FIRST child:
+ *
+ * ```tsx
+ * const { hostProps, pill } = useGooPill<HTMLDivElement>()
+ * return (
+ *   <div role="menu" {...hostProps} className={`${hostProps.className} my-panel`}>
+ *     {pill}
+ *     <button role="menuitem">…</button>
+ *   </div>
+ * )
+ * ```
+ *
+ * The host must stop painting a hover background on its rows: the pill IS the filled surface, and two
+ * of them read as two highlights.
+ */
+export interface UseGooPillOptions<T extends HTMLElement> {
+    /**
+     * Which descendants count as rows. Default: enabled `role="menuitem*"` buttons.
+     *
+     * Rows outside the host's own layout tree are ignored even when they match — a nested submenu is
+     * somebody else's list, and its rows are not this pill's to land on.
+     */
+    readonly rowSelector?: string;
+    /** An existing ref for the host, if the caller already has one. */
+    readonly hostRef?: MutableRefObject<T | null>;
+}
+export interface UseGooPillResult<T extends HTMLElement> {
+    /** The host element, for callers that need it themselves. `hostProps` already carries it. */
+    readonly hostRef: MutableRefObject<T | null>;
+    /** Spread on the list element. Carries the `xeno-goo-host` class and the pointer/focus handlers. */
+    readonly hostProps: {
+        readonly ref: RefObject<T>;
+        readonly className: string;
+        readonly onMouseOver: (e: ReactMouseEvent<T>) => void;
+        readonly onMouseLeave: () => void;
+        readonly onFocus: (e: ReactFocusEvent<T>) => void;
+    };
+    /** Render as the host's first child. */
+    readonly pill: ReactElement;
+    /** Put the pill on a row, or pass `null` to take it away. Exposed for keyboard-driven hosts. */
+    readonly moveGoo: (row: HTMLElement | null) => void;
+}
+export declare function useGooPill<T extends HTMLElement = HTMLDivElement>(options?: UseGooPillOptions<T>): UseGooPillResult<T>;