@intentface/ui 0.0.0 → 0.7.0

package/dist/nav/store.d.ts

@@ -0,0 +1,50 @@
+import { type RefObject } from "react";
+export type NavState = {
+    /** Which groups are open, by value. */
+    expanded: ReadonlySet<string>;
+    toggle: (value: string) => void;
+    setOpen: (value: string, open: boolean) => void;
+    setExpanded: (expanded: Iterable<string>) => void;
+};
+export type NavStore = {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => NavState;
+    /**
+     * Adopt state the Root owns rather than the store.
+     *
+     * Silent by default, because the seeding call happens *during render* and a
+     * handle you created yourself may already have subscribers — notifying there
+     * would update a mounted component mid-render. Pass `notify` from a layout
+     * effect, where it is safe and necessary: without it a memoised subtree never
+     * re-renders and so never learns a controlled value changed.
+     */
+    hydrate: (state: {
+        expanded?: string[];
+    }, options?: {
+        notify?: boolean;
+    }) => void;
+    controlledRef: RefObject<boolean>;
+    onExpandedChangeRef: RefObject<((expanded: string[]) => void) | null>;
+    /** Route a change through the controlled/uncontrolled decision and persistence. */
+    commitExpanded: (expanded: ReadonlySet<string>) => void;
+    /** The Root's element. Keyboard navigation reads row order off the DOM. */
+    rootRef: RefObject<HTMLElement | null>;
+};
+/**
+ * A plain closure store read through `useSyncExternalStore` — not React state
+ * and not Zustand. Takes no arguments: everything configurable arrives from
+ * `Nav.Root` as props, so a handle created at module scope cannot disagree
+ * with the tree that later adopts it.
+ */
+export declare const createNavStore: () => NavStore;
+export declare const NavStoreContext: import("react").Context<NavStore | null>;
+/** Internal: parts resolve the store their Nav.Root provided. */
+export declare const useNavContextStore: () => NavStore;
+/** Subscribe to an explicit `Nav.createStore()` handle, from outside the tree. */
+export declare const useNavStore: <Selected = NavState>(store: NavStore, selector?: (nav: NavState) => Selected) => Selected;
+/**
+ * Subscribe from inside the tree. Select a primitive — a boolean, an id — so
+ * the subscription can settle; a selector building a fresh Set on every call
+ * never will.
+ */
+export declare const useNav: <Selected = NavState>(selector?: (nav: NavState) => Selected) => Selected;

package/dist/nav/store.js

@@ -0,0 +1,95 @@
+"use client";
+import { createContext, use, useSyncExternalStore } from "react";
+const sameSet = (a, b) => a.size === b.size && [...a].every((value) => b.has(value));
+/**
+ * A plain closure store read through `useSyncExternalStore` — not React state
+ * and not Zustand. Takes no arguments: everything configurable arrives from
+ * `Nav.Root` as props, so a handle created at module scope cannot disagree
+ * with the tree that later adopts it.
+ */
+export const createNavStore = () => {
+    const listeners = new Set();
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const controlledRef = { current: false };
+    const onExpandedChangeRef = { current: null };
+    const rootRef = { current: null };
+    let snapshot;
+    const commitExpanded = (expanded) => {
+        if (sameSet(snapshot.expanded, expanded))
+            return;
+        const list = [...expanded];
+        onExpandedChangeRef.current?.(list);
+        // A controlled Root owns the value: it comes back as a prop or it does not
+        // change at all. Writing it here too would let the two disagree.
+        if (!controlledRef.current) {
+            snapshot = { ...snapshot, expanded };
+            notify();
+        }
+    };
+    const setOpen = (value, open) => {
+        const next = new Set(snapshot.expanded);
+        if (open)
+            next.add(value);
+        else
+            next.delete(value);
+        commitExpanded(next);
+    };
+    snapshot = {
+        expanded: new Set(),
+        toggle: (value) => setOpen(value, !snapshot.expanded.has(value)),
+        setOpen,
+        setExpanded: (expanded) => commitExpanded(new Set(expanded)),
+    };
+    return {
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot: () => snapshot,
+        hydrate: ({ expanded }, { notify: shouldNotify = false } = {}) => {
+            if (!expanded)
+                return;
+            const next = new Set(expanded);
+            if (shouldNotify && sameSet(snapshot.expanded, next))
+                return;
+            snapshot = { ...snapshot, expanded: next };
+            if (shouldNotify)
+                notify();
+        },
+        controlledRef,
+        onExpandedChangeRef,
+        commitExpanded,
+        rootRef,
+    };
+};
+// ---------------------------------------------------------------------------
+// Instance resolution — the nearest Nav.Root, explicitly.
+// ---------------------------------------------------------------------------
+export const NavStoreContext = createContext(null);
+/** Internal: parts resolve the store their Nav.Root provided. */
+export const useNavContextStore = () => {
+    const store = use(NavStoreContext);
+    if (!store)
+        throw new Error("Nav parts must be used within <Nav.Root>");
+    return store;
+};
+/** Subscribe to an explicit `Nav.createStore()` handle, from outside the tree. */
+export const useNavStore = (store, selector) => {
+    const getValue = () => {
+        const state = store.getSnapshot();
+        // Safe: without a selector, Selected defaults to NavState.
+        return selector ? selector(state) : state;
+    };
+    return useSyncExternalStore(store.subscribe, getValue, getValue);
+};
+/**
+ * Subscribe from inside the tree. Select a primitive — a boolean, an id — so
+ * the subscription can settle; a selector building a fresh Set on every call
+ * never will.
+ */
+export const useNav = (selector) => useNavStore(useNavContextStore(), selector);

package/dist/reasoning/index.d.ts

@@ -0,0 +1,3 @@
+export * as Reasoning from "./index.parts.js";
+export type { ReasoningContentProps, ReasoningRootProps, ReasoningTriggerProps, } from "./reasoning.js";
+export { useReasoning } from "./reasoning.js";

package/dist/reasoning/index.js

@@ -0,0 +1,3 @@
+// Public surface of @intentface/ui/reasoning. No directive — see index.parts.ts.
+export * as Reasoning from "./index.parts.js";
+export { useReasoning } from "./reasoning.js";

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

@@ -0,0 +1 @@
+export { ReasoningContent as Content, ReasoningRoot as Root, ReasoningTrigger as Trigger, } from "./reasoning.js";

package/dist/reasoning/index.parts.js

@@ -0,0 +1,5 @@
+// Part names for the `Reasoning` namespace. Deliberately carries no
+// "use client" directive: this module and index.ts must stay server-resolvable
+// so a React Server Component can reach Reasoning.Root and its siblings
+// through them. The directive lives one level down, on reasoning.tsx.
+export { ReasoningContent as Content, ReasoningRoot as Root, ReasoningTrigger as Trigger, } from "./reasoning.js";

package/dist/reasoning/reasoning.d.ts

@@ -0,0 +1,38 @@
+import { type ComponentProps } from "react";
+import { Collapsible } from "../internal/collapsible.js";
+type ReasoningContextValue = {
+    isStreaming: boolean;
+    isOpen: boolean;
+    setIsOpen: (open: boolean) => void;
+    duration: number | undefined;
+};
+export declare const useReasoning: () => ReasoningContextValue;
+export type ReasoningRootProps = Omit<ComponentProps<typeof Collapsible>, "onOpenChange"> & {
+    isStreaming?: boolean;
+    duration?: number;
+    onOpenChange?: (open: boolean) => void;
+};
+/**
+ * The disclosure root. Tracks how long `isStreaming` stayed true and hands the
+ * elapsed seconds back through `useReasoning`, so a label can change without
+ * the consumer timing anything.
+ * Renders a `<div>` element.
+ */
+export declare const ReasoningRoot: import("react").MemoExoticComponent<({ isStreaming, open: controlledOpen, defaultOpen, onOpenChange, duration: durationProp, children, ...props }: ReasoningRootProps) => import("react").JSX.Element>;
+export type ReasoningTriggerProps = ComponentProps<typeof Collapsible.Trigger>;
+/**
+ * The toggle. Ships no copy: supply the label as children, and read
+ * `isStreaming` and `duration` from `useReasoning` if it should change while
+ * the model is thinking.
+ * Renders a `<button>` element.
+ */
+export declare const ReasoningTrigger: (props: ReasoningTriggerProps) => import("react").JSX.Element;
+export type ReasoningContentProps = ComponentProps<typeof Collapsible.Panel>;
+/**
+ * The collapsible panel. Publishes its measured height while a transition runs
+ * and releases it once settled open, so a panel that is open keeps growing as
+ * text streams in.
+ * Renders a `<div>` element.
+ */
+export declare const ReasoningContent: (props: ReasoningContentProps) => import("react").JSX.Element;
+export {};

package/dist/reasoning/reasoning.js

@@ -0,0 +1,67 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// Headless reasoning disclosure. Owns the open state and the streaming
+// duration tracking; exposes them via useReasoning() so the styled layer can
+// render its own trigger label (shimmer, crossfade) and markdown content.
+import { createContext, memo, use, useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { Collapsible } from "../internal/collapsible.js";
+const MS_IN_S = 1000;
+const ReasoningContext = createContext(null);
+export const useReasoning = () => {
+    const context = use(ReasoningContext);
+    if (!context) {
+        throw new Error("Reasoning components must be used within Reasoning");
+    }
+    return context;
+};
+/**
+ * The disclosure root. Tracks how long `isStreaming` stayed true and hands the
+ * elapsed seconds back through `useReasoning`, so a label can change without
+ * the consumer timing anything.
+ * Renders a `<div>` element.
+ */
+export const ReasoningRoot = memo(({ isStreaming = false, open: controlledOpen, defaultOpen, onOpenChange, duration: durationProp, children, ...props }) => {
+    const resolvedDefaultOpen = defaultOpen ?? false;
+    const [internalOpen, setInternalOpen] = useState(resolvedDefaultOpen);
+    const isControlled = controlledOpen !== undefined;
+    const isOpen = isControlled ? controlledOpen : internalOpen;
+    const [duration, setDuration] = useState(durationProp);
+    const hasEverStreamedRef = useRef(isStreaming);
+    const startTimeRef = useRef(null);
+    const setIsOpen = useCallback((value) => {
+        if (!isControlled) {
+            setInternalOpen(value);
+        }
+        onOpenChange?.(value);
+    }, [isControlled, onOpenChange]);
+    // Track when streaming starts and compute duration
+    useEffect(() => {
+        if (isStreaming) {
+            hasEverStreamedRef.current = true;
+            if (startTimeRef.current === null) {
+                startTimeRef.current = Date.now();
+            }
+        }
+        else if (startTimeRef.current !== null) {
+            setDuration(Math.ceil((Date.now() - startTimeRef.current) / MS_IN_S));
+            startTimeRef.current = null;
+        }
+    }, [isStreaming]);
+    const contextValue = useMemo(() => ({ duration, isOpen, isStreaming, setIsOpen }), [duration, isOpen, isStreaming, setIsOpen]);
+    return (_jsx(ReasoningContext, { value: contextValue, children: _jsx(Collapsible, { open: isOpen, onOpenChange: (open) => setIsOpen(open), "aria-busy": isStreaming || undefined, "data-reasoning": "", "data-streaming": isStreaming ? "" : undefined, ...props, children: children }) }));
+});
+ReasoningRoot.displayName = "Reasoning";
+/**
+ * The toggle. Ships no copy: supply the label as children, and read
+ * `isStreaming` and `duration` from `useReasoning` if it should change while
+ * the model is thinking.
+ * Renders a `<button>` element.
+ */
+export const ReasoningTrigger = (props) => (_jsx(Collapsible.Trigger, { "data-reasoning-trigger": "", ...props }));
+/**
+ * The collapsible panel. Publishes its measured height while a transition runs
+ * and releases it once settled open, so a panel that is open keeps growing as
+ * text streams in.
+ * Renders a `<div>` element.
+ */
+export const ReasoningContent = (props) => (_jsx(Collapsible.Panel, { "data-reasoning-content": "", ...props }));

package/dist/shell/index.d.ts

@@ -0,0 +1,5 @@
+export * as Shell from "./index.parts.js";
+export type { ShellGripProps, ShellHotspotProps, ShellPartState, ShellRootProps, ShellSidebarProps, ShellSidebarState, ShellTriggerProps, ShellViewportProps, } from "./shell.js";
+export { SHELL_SIDEBAR_WIDTH_VAR } from "./shell.js";
+export type { ShellState, ShellStore } from "./store.js";
+export { useShell, useShellStore } from "./store.js";

package/dist/shell/index.js

@@ -0,0 +1,5 @@
+// Public surface of @intentface/ui/shell: the `Shell` namespace plus the store. No "use client" directive here — see
+// index.parts.ts.
+export * as Shell from "./index.parts.js";
+export { SHELL_SIDEBAR_WIDTH_VAR } from "./shell.js";
+export { useShell, useShellStore } from "./store.js";

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

@@ -0,0 +1,3 @@
+export { ShellGrip as Grip, ShellHotspot as Hotspot, ShellRoot as Root, ShellSidebar as Sidebar, ShellTrigger as Trigger, ShellViewport as Viewport, } from "./shell.js";
+/** Create a standalone store handle: `<Shell.Root store={…}>` plus `useShellStore(store, selector)` for reading it from outside the tree. */
+export { createShellStore as createStore } from "./store.js";

package/dist/shell/index.parts.js

@@ -0,0 +1,7 @@
+// Part names for the `Shell` namespace. Deliberately carries no "use client"
+// directive: this module and index.ts must stay server-resolvable so a React
+// Server Component can reach Shell.Root and its siblings through them. Each
+// part module carries the directive itself.
+export { ShellGrip as Grip, ShellHotspot as Hotspot, ShellRoot as Root, ShellSidebar as Sidebar, ShellTrigger as Trigger, ShellViewport as Viewport, } from "./shell.js";
+/** Create a standalone store handle: `<Shell.Root store={…}>` plus `useShellStore(store, selector)` for reading it from outside the tree. */
+export { createShellStore as createStore } from "./store.js";

package/dist/shell/shell.d.ts

@@ -0,0 +1,108 @@
+import type { ReactNode } from "react";
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+import type { ShellStore } 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 declare const SHELL_SIDEBAR_WIDTH_VAR = "--shell-sidebar-width";
+export type ShellPartState = {
+    state: "expanded" | "collapsed";
+    hotspot: boolean;
+    resizing: boolean;
+};
+export type ShellSidebarState = ShellPartState & {
+    side: "left" | "right";
+};
+export type ShellRootProps = PrimitiveProps<"div", ShellPartState> & {
+    /**
+     * Where the sidebar starts when nothing controls it. Read it from the
+     * request on the server, if you persist it, so the first paint is already
+     * right rather than snapping a frame later. Nothing here reads storage —
+     * see `onOpenChange` for the other half.
+     */
+    defaultOpen?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * An explicit `Shell.createStore()` handle, for when the state has to be
+     * reachable from outside this tree. Must be stable for the Root's lifetime.
+     */
+    store?: ShellStore;
+    children?: ReactNode;
+};
+/**
+ * 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 declare const ShellRoot: ({ defaultOpen, open, onOpenChange, store: storeProp, className, render, style, ...elementProps }: ShellRootProps) => import("react").JSX.Element;
+export type ShellSidebarProps = PrimitiveProps<"div", ShellSidebarState> & {
+    side?: "left" | "right";
+    /**
+     * The panel's settled width, in pixels — fired once a drag ends, never per
+     * frame, and whenever anything else resizes it. Persist it if you want it
+     * remembered, and restore it as the custom property rather than as a prop:
+     * the width is CSS's, and this is only the measurement coming back.
+     */
+    onResize?: (width: number) => void;
+};
+/**
+ * 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 declare const ShellSidebar: ({ side, onResize, className, render, style, ...elementProps }: ShellSidebarProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ShellViewportProps = PrimitiveProps<"div", ShellPartState>;
+/**
+ * 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 declare const ShellViewport: ({ className, render, style, ...elementProps }: ShellViewportProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ShellHotspotProps = PrimitiveProps<"div", ShellPartState>;
+/**
+ * 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 declare const ShellHotspot: ({ className, render, style, ...elementProps }: ShellHotspotProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ShellTriggerProps = PrimitiveProps<"button", ShellPartState>;
+/**
+ * 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 declare const ShellTrigger: ({ className, render, style, ...elementProps }: ShellTriggerProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ShellGripProps = PrimitiveProps<"div", ShellPartState> & {
+    /** Pixels moved per arrow-key press. */
+    step?: number;
+};
+/**
+ * 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 declare const ShellGrip: ({ step, className, render, style, ...elementProps }: ShellGripProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;