@intentface/ui 0.0.0 → 0.7.0

package/dist/shell/shell.js

@@ -0,0 +1,390 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useCallback, useEffect, useId, useMemo, useRef, useState, } from "react";
+import { useIsomorphicLayoutEffect } from "../internal/iso-layout-effect.js";
+import { useRenderElement } from "../internal/render/useRenderElement.js";
+import { createShellStore, ShellStoreContext, useShellContextStore, useShellStore } from "./store.js";
+/**
+ * The shell: a sidebar that collapses, floats out on hover, and can be dragged
+ * wider, next to the viewport it shares the screen with.
+ *
+ * The package ships no CSS. Parts publish their state as `data-*` attributes
+ * and the sidebar's measured width as a custom property; sizing, collapsing
+ * geometry and transitions are all yours. In particular **the sidebar's width
+ * and the range it may be dragged through are CSS**:
+ *
+ *   [data-shell-sidebar] {
+ *     width: var(--shell-sidebar-width, 240px);
+ *     min-width: 200px;
+ *     max-width: 400px;
+ *   }
+ *
+ * The drag writes that custom property, the browser clamps it against your
+ * `min-width` / `max-width`, and the sidebar reports back whatever the browser
+ * settled on. Nothing here second-guesses your stylesheet.
+ *
+ * No global key binding either. `Shell.Trigger` is the click affordance; a
+ * Cmd/Ctrl+B — or whatever your app's shortcut registry says — is four lines
+ * around `useShell((shell) => shell.toggle)`, and a package has no business
+ * claiming a window-level `keydown` for a key it cannot know is free.
+ */
+/** Written by the grip; read by your `width`. */
+export const SHELL_SIDEBAR_WIDTH_VAR = "--shell-sidebar-width";
+// Both delays are intent filters: the open delay stops a pointer merely
+// crossing the strip from floating the panel out, and the close grace lets you
+// clip a corner on the way from the strip to the panel without losing it.
+const PEEK_OPEN_DELAY_MS = 200;
+const PEEK_CLOSE_DELAY_MS = 250;
+const selectOpen = (shell) => shell.open;
+const selectHotspot = (shell) => shell.hotspot;
+const selectResizing = (shell) => shell.resizing;
+const selectWidth = (shell) => shell.width;
+// Three primitive subscriptions rather than one selector returning an object:
+// useSyncExternalStore compares snapshots by identity, so a selector that built
+// a fresh object every call would never settle.
+const usePartState = (store) => ({
+    state: useShellStore(store, selectOpen) ? "expanded" : "collapsed",
+    hotspot: useShellStore(store, selectHotspot),
+    resizing: useShellStore(store, selectResizing),
+});
+const ShellHotspotContext = createContext(null);
+const useHotspotControls = (store) => {
+    const openTimer = useRef(undefined);
+    const closeTimer = useRef(undefined);
+    const controls = useMemo(() => ({
+        request: () => {
+            // Armed by the collapse that just happened under this pointer.
+            if (store.hotspotSuppressionRef.current)
+                return;
+            window.clearTimeout(closeTimer.current);
+            if (store.getSnapshot().hotspot)
+                return;
+            openTimer.current = window.setTimeout(() => {
+                // Re-checked on firing, not just on arming. A timer started while the
+                // sidebar was still expanded outlives a collapse that happens during
+                // the delay, and would then float the panel straight back out from
+                // under the pointer that just closed it.
+                if (store.hotspotSuppressionRef.current)
+                    return;
+                store.getSnapshot().setHotspot(true);
+            }, PEEK_OPEN_DELAY_MS);
+        },
+        hold: () => window.clearTimeout(closeTimer.current),
+        release: () => {
+            // The pointer has moved on, so the bounce-back guard has done its job.
+            store.hotspotSuppressionRef.current = false;
+            // Darting through the strip never opens it.
+            window.clearTimeout(openTimer.current);
+            if (!store.getSnapshot().hotspot)
+                return;
+            closeTimer.current = window.setTimeout(() => store.getSnapshot().setHotspot(false), PEEK_CLOSE_DELAY_MS);
+        },
+    }), [store]);
+    // Cmd-Tab away mid-hotspot fires no pointerleave: without this the panel stays
+    // floated and a pending open timer fires into a backgrounded window.
+    useEffect(() => {
+        const dismiss = () => {
+            window.clearTimeout(openTimer.current);
+            window.clearTimeout(closeTimer.current);
+            store.getSnapshot().setHotspot(false);
+        };
+        window.addEventListener("blur", dismiss);
+        return () => {
+            window.removeEventListener("blur", dismiss);
+            window.clearTimeout(openTimer.current);
+            window.clearTimeout(closeTimer.current);
+        };
+    }, [store]);
+    return controls;
+};
+const useHotspotContext = () => {
+    const controls = use(ShellHotspotContext);
+    if (!controls)
+        throw new Error("Shell parts must be used within <Shell.Root>");
+    return controls;
+};
+/**
+ * The provider and container. Holds the store every other part reads, so
+ * `defaultOpen` and the width must arrive here rather than on a child.
+ * Renders a `<div>` element.
+ */
+export const ShellRoot = ({ defaultOpen, open, onOpenChange, store: storeProp, className, render, style, ...elementProps }) => {
+    const sidebarId = useId();
+    const [store] = useState(() => {
+        const created = storeProp ?? createShellStore();
+        // Before anything has subscribed, so no notify and no write-back. The
+        // controlled value wins over the default: the layout effect below would
+        // otherwise correct it only after the server had already shipped the wrong
+        // markup, which is the pre-hydration flash `defaultOpen` exists to prevent.
+        created.hydrate({ open: open ?? defaultOpen });
+        created.sidebarId = sidebarId;
+        return created;
+    });
+    // Latest-ref bridges, written during render: idempotent, and they have to be
+    // current before any event handler can read them.
+    store.controlledRef.current = open !== undefined;
+    store.onOpenChangeRef.current = onOpenChange ?? null;
+    // Before paint, so a controlled change never shows the old state first.
+    useIsomorphicLayoutEffect(() => {
+        if (open !== undefined)
+            store.commitOpen(open);
+    }, [open, store]);
+    const hotspot = useHotspotControls(store);
+    const state = usePartState(store);
+    /*
+     * The bounce-back guard is armed by every collapse, but it is only *meant* to
+     * survive one where the pointer was sitting where the strip is about to
+     * appear. Any movement outside the strip proves it wasn't, so it is cleared
+     * here — without this, collapsing by keyboard or by a trigger anywhere else
+     * arms a guard that then swallows the next genuine hover.
+     *
+     * Ref write only, no re-render, and it returns immediately when nothing is
+     * armed — which is almost always.
+     */
+    const handlePointerMove = (event) => {
+        if (!store.hotspotSuppressionRef.current)
+            return;
+        const target = event.target;
+        if (target?.closest("[data-shell-hotspot]"))
+            return;
+        store.hotspotSuppressionRef.current = false;
+    };
+    const element = useRenderElement("div", { className, render, style }, {
+        state,
+        ref: store.rootRef,
+        props: [{ "data-shell": "", onPointerMove: handlePointerMove }, elementProps],
+    });
+    return (_jsx(ShellStoreContext, { value: store, children: _jsx(ShellHotspotContext, { value: hotspot, children: element }) }));
+};
+/**
+ * The panel, and the element whose width is measured and reported back.
+ * Carries the `id` the trigger's `aria-controls` points at.
+ * Renders a `<div>` element.
+ */
+export const ShellSidebar = ({ side = "left", onResize, className, render, style, ...elementProps }) => {
+    const store = useShellContextStore();
+    // Latest-ref bridge, written during render: idempotent, and current before
+    // the measurement below can report anything.
+    store.onResizeRef.current = onResize ?? null;
+    const hotspot = useHotspotContext();
+    const partState = usePartState(store);
+    // Report the width the browser settled on, so persistence and the resize
+    // handle's aria-valuenow describe what is actually on screen.
+    useIsomorphicLayoutEffect(() => {
+        const element = store.sidebarRef.current;
+        if (!element)
+            return;
+        const measure = () => {
+            const measured = element.offsetWidth;
+            // Zero means the element is not laid out — display:none, a breakpoint
+            // that hides it, a test environment without layout. That carries no
+            // information, and persisting it would throw away the width the user
+            // actually chose.
+            if (measured > 0)
+                store.getSnapshot().setWidth(measured);
+        };
+        measure();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [store]);
+    return useRenderElement("div", { className, render, style }, {
+        state: { ...partState, side },
+        ref: store.sidebarRef,
+        props: [
+            {
+                "data-shell-sidebar": "",
+                id: store.sidebarId,
+                onPointerEnter: hotspot.hold,
+                onPointerLeave: hotspot.release,
+            },
+            elementProps,
+        ],
+    });
+};
+/**
+ * The content area beside the sidebar. Carries the same state attributes as
+ * the root, so it can react to the sidebar without a group selector.
+ * Renders a `<div>` element.
+ */
+export const ShellViewport = ({ className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, {
+    state: usePartState(useShellContextStore()),
+    props: [{ "data-shell-viewport": "" }, elementProps],
+});
+/**
+ * The strip along the screen edge that floats a collapsed sidebar out on
+ * hover. Give it a width and a position in CSS. Omitting it is how you opt out
+ * of hotspot entirely — there is no prop to turn it off, because not rendering it
+ * already says that.
+ */
+export const ShellHotspot = ({ className, render, style, ...elementProps }) => {
+    const hotspot = useHotspotContext();
+    return useRenderElement("div", { className, render, style }, {
+        state: usePartState(useShellContextStore()),
+        props: [
+            {
+                "data-shell-hotspot": "",
+                "aria-hidden": true,
+                onPointerEnter: hotspot.request,
+                onPointerLeave: hotspot.release,
+            },
+            elementProps,
+        ],
+    });
+};
+/**
+ * Toggles the sidebar, and pins a floated-out one open rather than closing it.
+ * Ships no copy — supply the label as children.
+ * Renders a `<button>` element.
+ */
+export const ShellTrigger = ({ className, render, style, ...elementProps }) => {
+    const store = useShellContextStore();
+    const state = usePartState(store);
+    const handleClick = useCallback(() => {
+        const shell = store.getSnapshot();
+        // Clicking the trigger inside a floated sidebar pins it open.
+        shell.setOpen(shell.hotspot ? true : !shell.open);
+    }, [store]);
+    return useRenderElement("button", { className, render, style }, {
+        state,
+        props: [
+            {
+                type: "button",
+                "data-shell-trigger": "",
+                "aria-expanded": state.state === "expanded",
+                "aria-controls": store.sidebarId,
+                onClick: handleClick,
+            },
+            elementProps,
+        ],
+    });
+};
+/** The drag range, straight from the stylesheet. `max-width: none` means unbounded. */
+const readBounds = (element) => {
+    const computed = getComputedStyle(element);
+    const min = Number.parseFloat(computed.minWidth);
+    const max = Number.parseFloat(computed.maxWidth);
+    return {
+        min: Number.isFinite(min) ? min : 0,
+        max: Number.isFinite(max) ? max : Number.POSITIVE_INFINITY,
+    };
+};
+const clamp = (value, { min, max }) => Math.min(Math.max(value, min), max);
+/**
+ * Publish the width on the root, not the sidebar, so anything else in the
+ * shell can size itself to match. Clamped here rather than left to the
+ * browser: `min-width` would constrain only the sidebar, and a spacer reading
+ * the raw value would then disagree with it past either end of the range.
+ */
+const publishWidth = (store, width, bounds) => {
+    store.rootRef.current?.style.setProperty(SHELL_SIDEBAR_WIDTH_VAR, `${clamp(width, bounds)}px`);
+};
+/** Dragging right widens a left sidebar and narrows a right one. */
+const widenDirection = (sidebar) => (sidebar.dataset.side === "right" ? -1 : 1);
+/**
+ * The drag affordance. Give it a width and a cursor in CSS; the drag range
+ * comes from the sidebar's own `min-width` and `max-width`.
+ * Renders a `<div>` element with `role="separator"`.
+ */
+export const ShellGrip = ({ step = 16, className, render, style, ...elementProps }) => {
+    const store = useShellContextStore();
+    const state = usePartState(store);
+    const width = useShellStore(store, selectWidth);
+    const [bounds, setBounds] = useState({ min: 0, max: Number.POSITIVE_INFINITY });
+    const drag = useRef(null);
+    // Re-read after every commit rather than on a dependency, so a stylesheet
+    // that swaps the range at a breakpoint reaches aria-valuemin/max too. Cheap:
+    // the identity guard stops it looping, and it is skipped mid-drag, where the
+    // range cannot change and the drag holds its own copy anyway.
+    useIsomorphicLayoutEffect(() => {
+        const sidebar = store.sidebarRef.current;
+        if (!sidebar || state.resizing)
+            return;
+        const next = readBounds(sidebar);
+        setBounds((current) => (current.min === next.min && current.max === next.max ? current : next));
+    });
+    const endDrag = useCallback(() => {
+        if (!drag.current)
+            return;
+        drag.current = null;
+        store.getSnapshot().setResizing(false);
+    }, [store]);
+    // A drag can end without a pointerup: cmd-tab away, or the tab going to the
+    // background. Left unhandled the flag sticks and everything downstream of
+    // `data-resizing` stays wrong until a reload.
+    useEffect(() => {
+        if (!state.resizing)
+            return;
+        window.addEventListener("blur", endDrag);
+        document.addEventListener("visibilitychange", endDrag);
+        return () => {
+            window.removeEventListener("blur", endDrag);
+            document.removeEventListener("visibilitychange", endDrag);
+        };
+    }, [state.resizing, endDrag]);
+    const handlePointerDown = (event) => {
+        const sidebar = store.sidebarRef.current;
+        if (!sidebar || event.button !== 0)
+            return;
+        event.preventDefault();
+        // Not every environment implements pointer capture; without it the drag
+        // still works, it just stops tracking once the pointer leaves the handle.
+        if ("setPointerCapture" in event.currentTarget) {
+            event.currentTarget.setPointerCapture(event.pointerId);
+        }
+        drag.current = {
+            pointerId: event.pointerId,
+            startX: event.clientX,
+            startWidth: sidebar.offsetWidth,
+            // Read once, at the start: the range cannot change mid-drag, and
+            // re-reading computed style on every pointermove would be a needless
+            // style recalculation per frame.
+            bounds: readBounds(sidebar),
+        };
+        store.getSnapshot().setResizing(true);
+    };
+    const handlePointerMove = (event) => {
+        const sidebar = store.sidebarRef.current;
+        if (!drag.current || !sidebar || event.pointerId !== drag.current.pointerId)
+            return;
+        const travelled = (event.clientX - drag.current.startX) * widenDirection(sidebar);
+        publishWidth(store, drag.current.startWidth + travelled, drag.current.bounds);
+    };
+    const handleKeyDown = (event) => {
+        const sidebar = store.sidebarRef.current;
+        if (!sidebar)
+            return;
+        const towards = event.key === "ArrowLeft" ? -1 : event.key === "ArrowRight" ? 1 : 0;
+        if (towards === 0)
+            return;
+        event.preventDefault();
+        const next = sidebar.offsetWidth + towards * widenDirection(sidebar) * step;
+        publishWidth(store, next, readBounds(sidebar));
+    };
+    return useRenderElement("div", { className, render, style }, {
+        state,
+        props: [
+            {
+                "data-shell-grip": "",
+                role: "separator",
+                "aria-orientation": "vertical",
+                // A focusable separator must always carry a value; omitting it until
+                // the first measurement lands would leave the widget invalid for that
+                // window. The minimum is the least misleading stand-in, and it is
+                // corrected on the next frame.
+                "aria-valuenow": width ?? bounds.min,
+                "aria-valuemin": bounds.min,
+                "aria-valuemax": Number.isFinite(bounds.max) ? bounds.max : undefined,
+                tabIndex: 0,
+                onPointerDown: handlePointerDown,
+                onPointerMove: handlePointerMove,
+                onPointerUp: endDrag,
+                onPointerCancel: endDrag,
+                onKeyDown: handleKeyDown,
+            },
+            elementProps,
+        ],
+    });
+};

package/dist/shell/store.d.ts

@@ -0,0 +1,112 @@
+import type { RefObject } from "react";
+/**
+ * Shell store — all reactive shell state in one closure, so `useShell` can
+ * offer selectors and a component re-renders only for the value it reads.
+ * Not React state and not Zustand: a plain object with `subscribe` and
+ * `getSnapshot`, read through `useSyncExternalStore`.
+ *
+ * The factory takes no arguments. Everything configurable is either a
+ * `Shell.Root` prop (`defaultOpen`) seeded through `hydrate()` before the first
+ * paint, or — for anything dimensional — CSS.
+ *
+ * Nothing is persisted here. `open` goes out through `onOpenChange` and comes
+ * back as `defaultOpen`; the measured width goes out through `Shell.Sidebar`'s
+ * `onResize` and comes back as **CSS** — the custom property, which is
+ * where the width lives anyway. Where any of it is kept is the app's business,
+ * and the package needs no opinion about serialisation, keys or cookie flags.
+ *
+ * **Width is not owned here.** The sidebar's size, and the range it may be
+ * dragged through, are `width` / `min-width` / `max-width` in the consumer's
+ * stylesheet. The browser clamps; this store only records what the element
+ * actually measured, because persistence and `aria-valuenow` need a number.
+ * Measure in JS, size in CSS.
+ *
+ * Instance model: every `Shell.Root` owns a store — an explicit
+ * `Shell.createStore()` handle, or one created per mount — and provides it on
+ * `ShellStoreContext`. Inside the tree `useShell` resolves it implicitly;
+ * outside, `useShellStore(handle, selector)` takes the handle explicitly.
+ * There is deliberately **no global fallback**, so shell state is never read
+ * or driven by accident from somewhere that just happened to import this.
+ *
+ * SSR-safe by invariant: every write happens in an effect, an event handler,
+ * or `hydrate()` before anything has subscribed — so a server render only ever
+ * sees the pristine snapshot and one getter serves both sides of hydration.
+ */
+export type ShellState = {
+    open: boolean;
+    /** The collapsed sidebar floating over the content on hover. Never persisted. */
+    hotspot: boolean;
+    /** True for the duration of a resize drag, so parts can suppress transitions. */
+    resizing: boolean;
+    /** Measured from the sidebar element. Null until it has mounted. */
+    width: number | null;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+    setHotspot: (hotspot: boolean) => void;
+    setResizing: (resizing: boolean) => void;
+    /** Reports a measurement. Not a request to resize — CSS decides the size. */
+    setWidth: (width: number) => void;
+};
+export type ShellStore = {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => ShellState;
+    /**
+     * Seed state before the first render commits: no notify and no report back,
+     * because nothing has subscribed yet and re-announcing what we just restored
+     * is pointless. This is how `defaultOpen` reaches the store without a flash.
+     */
+    hydrate: (state: {
+        open?: boolean;
+    }) => void;
+    /** Set while `open` is a controlled prop, which makes `setOpen` report-only. */
+    controlledRef: RefObject<boolean>;
+    onOpenChangeRef: RefObject<((open: boolean) => void) | null>;
+    /** Reports a settled size — never the per-frame values a drag produces. */
+    onResizeRef: RefObject<((width: number) => void) | null>;
+    /** Commits `open` past the controlled guard — how the Root syncs its prop in. */
+    commitOpen: (open: boolean) => void;
+    /**
+     * The mounted `Shell.Root`'s element. The width custom property is written
+     * here rather than on the sidebar, so siblings — an in-flow spacer holding
+     * the sidebar's place while it floats, say — can read the same value.
+     */
+    rootRef: RefObject<HTMLElement | null>;
+    /**
+     * The mounted `Shell.Sidebar`'s element, registered by its ref. The resize
+     * handle sizes and measures it; the trigger points `aria-controls` at its id.
+     */
+    sidebarRef: RefObject<HTMLElement | null>;
+    /**
+     * Stable per-instance id for the sidebar, assigned by the mounting
+     * `Shell.Root` from React's `useId` (SSR-stable). The factory can't mint it,
+     * because explicit handles are created outside React.
+     */
+    sidebarId: string;
+    /**
+     * Set while collapsing, so a panel sliding out from under a parked pointer
+     * doesn't bounce straight back as a hotspot. Cleared once the pointer leaves
+     * the edge strip. Imperative, not reactive.
+     */
+    hotspotSuppressionRef: RefObject<boolean>;
+};
+export declare const createShellStore: () => ShellStore;
+export declare const ShellStoreContext: import("react").Context<ShellStore | null>;
+/** Internal: parts resolve the store their Shell.Root provided. */
+export declare const useShellContextStore: () => ShellStore;
+/**
+ * Subscribe to an explicit `Shell.createStore()` handle — the
+ * outside-the-tree twin of `useShell`, for command palettes, global shortcut
+ * handlers and anything else that isn't a descendant. Wrap it once per
+ * instance to drop the argument at call sites:
+ *
+ *   const useAppShell = <T,>(selector: (shell: ShellState) => T) =>
+ *     useShellStore(appShellStore, selector);
+ */
+export declare const useShellStore: <Selected = ShellState>(store: ShellStore, selector?: (shell: ShellState) => Selected) => Selected;
+/**
+ * Subscribe to shell state from inside the tree. With a selector the component
+ * re-renders only when that value changes; without one it re-renders on any
+ * change. The actions are part of the snapshot and their identities never
+ * change, so selecting one never causes a render.
+ */
+export declare const useShell: <Selected = ShellState>(selector?: (shell: ShellState) => Selected) => Selected;

package/dist/shell/store.js

@@ -0,0 +1,134 @@
+"use client";
+import { createContext, use, useSyncExternalStore } from "react";
+export const createShellStore = () => {
+    const listeners = new Set();
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const controlledRef = { current: false };
+    const onOpenChangeRef = { current: null };
+    const onResizeRef = { current: null };
+    const hotspotSuppressionRef = { current: false };
+    const rootRef = { current: null };
+    const sidebarRef = { current: null };
+    let snapshot;
+    // A drag emits a measurement per frame, and reporting each one would hand the
+    // app a hundred sizes the user is still in the middle of choosing.
+    // `setResizing(false)` reports whatever it landed on.
+    const reportResize = () => {
+        if (snapshot.resizing || snapshot.width === null)
+            return;
+        onResizeRef.current?.(snapshot.width);
+    };
+    const commitOpen = (open) => {
+        if (snapshot.open === open)
+            return;
+        // Collapsing arms the bounce-back guard: a panel sliding out from under a
+        // parked pointer must not immediately float back as a hotspot.
+        if (!open)
+            hotspotSuppressionRef.current = true;
+        // Hotspot only means anything while collapsed, so opening ends it.
+        snapshot = { ...snapshot, open, hotspot: open ? false : snapshot.hotspot };
+        notify();
+    };
+    const setOpen = (open) => {
+        // Reported before the commit, and the only effect while controlled: whoever
+        // owns the prop decides, then pushes the result back through commitOpen.
+        onOpenChangeRef.current?.(open);
+        if (!controlledRef.current)
+            commitOpen(open);
+    };
+    const toggle = () => setOpen(!snapshot.open);
+    const setHotspot = (hotspot) => {
+        // There is nothing to hotspot at while the sidebar is already open.
+        const next = hotspot && !snapshot.open;
+        if (snapshot.hotspot === next)
+            return;
+        snapshot = { ...snapshot, hotspot: next };
+        notify();
+    };
+    const setWidth = (width) => {
+        if (snapshot.width === width)
+            return;
+        snapshot = { ...snapshot, width };
+        notify();
+        reportResize();
+    };
+    const setResizing = (resizing) => {
+        if (snapshot.resizing === resizing)
+            return;
+        snapshot = { ...snapshot, resizing };
+        notify();
+        if (!resizing)
+            reportResize();
+    };
+    snapshot = {
+        open: true,
+        hotspot: false,
+        resizing: false,
+        width: null,
+        setOpen,
+        toggle,
+        setHotspot,
+        setResizing,
+        setWidth,
+    };
+    return {
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot: () => snapshot,
+        hydrate: ({ open }) => {
+            // Width is deliberately not seedable: it is a *measurement*, and CSS has
+            // already decided the number before anything here runs.
+            snapshot = { ...snapshot, open: open ?? snapshot.open };
+        },
+        rootRef,
+        sidebarRef,
+        sidebarId: "",
+        controlledRef,
+        onOpenChangeRef,
+        onResizeRef,
+        commitOpen,
+        hotspotSuppressionRef,
+    };
+};
+// ---------------------------------------------------------------------------
+// Instance resolution — the nearest Shell.Root, explicitly.
+// ---------------------------------------------------------------------------
+export const ShellStoreContext = createContext(null);
+/** Internal: parts resolve the store their Shell.Root provided. */
+export const useShellContextStore = () => {
+    const store = use(ShellStoreContext);
+    if (!store)
+        throw new Error("Shell parts must be used within <Shell.Root>");
+    return store;
+};
+/**
+ * Subscribe to an explicit `Shell.createStore()` handle — the
+ * outside-the-tree twin of `useShell`, for command palettes, global shortcut
+ * handlers and anything else that isn't a descendant. Wrap it once per
+ * instance to drop the argument at call sites:
+ *
+ *   const useAppShell = <T,>(selector: (shell: ShellState) => T) =>
+ *     useShellStore(appShellStore, selector);
+ */
+export const useShellStore = (store, selector) => {
+    const getValue = () => {
+        const state = store.getSnapshot();
+        // Safe: without a selector, Selected defaults to ShellState.
+        return selector ? selector(state) : state;
+    };
+    return useSyncExternalStore(store.subscribe, getValue, getValue);
+};
+/**
+ * Subscribe to shell state from inside the tree. With a selector the component
+ * re-renders only when that value changes; without one it re-renders on any
+ * change. The actions are part of the snapshot and their identities never
+ * change, so selecting one never causes a render.
+ */
+export const useShell = (selector) => useShellStore(useShellContextStore(), selector);

package/dist/steps/index.d.ts

@@ -0,0 +1,2 @@
+export * as Steps from "./index.parts.js";
+export type { StepStatus, StepsIconProps, StepsItemProps, StepsLabelProps, StepsPanelProps, StepsRootProps, StepsStatusProps, StepsTriggerProps, } from "./steps.js";

package/dist/steps/index.js

@@ -0,0 +1,2 @@
+// Public surface of @intentface/ui/steps. No directive — see index.parts.ts.
+export * as Steps from "./index.parts.js";

package/dist/steps/index.parts.d.ts

@@ -0,0 +1 @@
+export { StepsIcon as Icon, StepsItem as Item, StepsLabel as Label, StepsPanel as Panel, StepsRoot as Root, StepsStatus as Status, StepsTrigger as Trigger, } from "./steps.js";

package/dist/steps/index.parts.js

@@ -0,0 +1,5 @@
+// Part names for the `Steps` namespace. Deliberately carries no
+// "use client" directive: this module and index.ts must stay server-resolvable
+// so a React Server Component can reach Steps.Root and its siblings
+// through them. The directive lives one level down, on steps.tsx.
+export { StepsIcon as Icon, StepsItem as Item, StepsLabel as Label, StepsPanel as Panel, StepsRoot as Root, StepsStatus as Status, StepsTrigger as Trigger, } from "./steps.js";