@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/src/internal/__tests__/RevealToggle.test.tsx

@@ -0,0 +1,61 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { RevealToggle } from "../RevealToggle";
+
+afterEach(cleanup);
+
+describe("RevealToggle", () => {
+  it("shows the default 'Show more' label and a collapsed aria-expanded when collapsed", () => {
+    render(<RevealToggle expanded={false} onToggle={() => {}} />);
+    const btn = screen.getByRole("button", { name: /Show more/ });
+    expect(btn.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("shows the default 'Show less' label and an expanded aria-expanded when expanded", () => {
+    render(<RevealToggle expanded onToggle={() => {}} />);
+    const btn = screen.getByRole("button", { name: /Show less/ });
+    expect(btn.getAttribute("aria-expanded")).toBe("true");
+  });
+
+  it("honours custom more/less labels (e.g. the line-count primitives)", () => {
+    const { rerender } = render(
+      <RevealToggle
+        expanded={false}
+        onToggle={() => {}}
+        moreLabel="Show all 42 lines"
+        lessLabel="Show less"
+      />,
+    );
+    expect(screen.getByText("Show all 42 lines")).toBeTruthy();
+
+    rerender(
+      <RevealToggle
+        expanded
+        onToggle={() => {}}
+        moreLabel="Show all 42 lines"
+        lessLabel="Show less"
+      />,
+    );
+    expect(screen.getByText("Show less")).toBeTruthy();
+  });
+
+  it("invokes onToggle on click", () => {
+    const onToggle = vi.fn();
+    render(<RevealToggle expanded={false} onToggle={onToggle} />);
+    fireEvent.click(screen.getByRole("button"));
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards the e2e cursor-target hook onto the control", () => {
+    render(
+      <RevealToggle
+        expanded={false}
+        onToggle={() => {}}
+        cursorTarget="tool-detail-expand"
+      />,
+    );
+    expect(
+      screen.getByRole("button").getAttribute("data-cursor-target"),
+    ).toBe("tool-detail-expand");
+  });
+});

package/src/internal/__tests__/useAutoDisclosure.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useAutoDisclosure } from "../useAutoDisclosure";
+
+describe("useAutoDisclosure", () => {
+  it("starts open when autoOpen is true", () => {
+    const { result } = renderHook(() => useAutoDisclosure(true));
+    expect(result.current[0]).toBe(true);
+  });
+
+  it("starts closed when autoOpen is false", () => {
+    const { result } = renderHook(() => useAutoDisclosure(false));
+    expect(result.current[0]).toBe(false);
+  });
+
+  it("honours initialOpen over autoOpen for the first render", () => {
+    const { result } = renderHook(() =>
+      useAutoDisclosure(false, { initialOpen: true }),
+    );
+    expect(result.current[0]).toBe(true);
+  });
+
+  it("tracks autoOpen while the user has not toggled", () => {
+    const { result, rerender } = renderHook(
+      ({ autoOpen }) => useAutoDisclosure(autoOpen),
+      { initialProps: { autoOpen: true } },
+    );
+    expect(result.current[0]).toBe(true);
+
+    rerender({ autoOpen: false });
+    expect(result.current[0]).toBe(false);
+
+    rerender({ autoOpen: true });
+    expect(result.current[0]).toBe(true);
+  });
+
+  it("freezes on the user's choice once toggled, ignoring autoOpen", () => {
+    const { result, rerender } = renderHook(
+      ({ autoOpen }) => useAutoDisclosure(autoOpen),
+      { initialProps: { autoOpen: true } },
+    );
+
+    // User collapses while the section is auto-open.
+    act(() => result.current[1]());
+    expect(result.current[0]).toBe(false);
+
+    // Auto signal flips both ways — user's collapse must persist.
+    rerender({ autoOpen: false });
+    expect(result.current[0]).toBe(false);
+    rerender({ autoOpen: true });
+    expect(result.current[0]).toBe(false);
+  });
+
+  it("toggle flips from a user-opened state too", () => {
+    const { result } = renderHook(() => useAutoDisclosure(false));
+    expect(result.current[0]).toBe(false);
+
+    act(() => result.current[1]());
+    expect(result.current[0]).toBe(true);
+
+    act(() => result.current[1]());
+    expect(result.current[0]).toBe(false);
+  });
+
+  it("keeps a stable toggle identity across renders", () => {
+    const { result, rerender } = renderHook(
+      ({ autoOpen }) => useAutoDisclosure(autoOpen),
+      { initialProps: { autoOpen: false } },
+    );
+    const first = result.current[1];
+    rerender({ autoOpen: true });
+    expect(result.current[1]).toBe(first);
+  });
+});

package/src/internal/__tests__/useElapsedSince.test.tsx

@@ -0,0 +1,68 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { renderHook, act, cleanup } from "@testing-library/react";
+import { useElapsedSince, formatElapsed } from "../useElapsedSince";
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date("2026-07-02T12:00:30Z"));
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+describe("useElapsedSince", () => {
+  it("returns the elapsed ms since the timestamp", () => {
+    const { result } = renderHook(() =>
+      useElapsedSince("2026-07-02T12:00:00Z"),
+    );
+    expect(result.current).toBe(30_000);
+  });
+
+  it("ticks forward once per second", () => {
+    const { result } = renderHook(() =>
+      useElapsedSince("2026-07-02T12:00:00Z"),
+    );
+    act(() => {
+      vi.advanceTimersByTime(3_000);
+    });
+    expect(result.current).toBe(33_000);
+  });
+
+  it("clamps to zero when the timestamp is ahead of the client clock", () => {
+    const { result } = renderHook(() =>
+      useElapsedSince("2026-07-02T12:00:35Z"),
+    );
+    expect(result.current).toBe(0);
+  });
+
+  it("returns null for an empty timestamp", () => {
+    const { result } = renderHook(() => useElapsedSince(""));
+    expect(result.current).toBeNull();
+  });
+
+  it("returns null for an unparseable timestamp", () => {
+    const { result } = renderHook(() => useElapsedSince("not-a-date"));
+    expect(result.current).toBeNull();
+  });
+
+  it("tears down its interval on unmount", () => {
+    const { unmount } = renderHook(() =>
+      useElapsedSince("2026-07-02T12:00:00Z"),
+    );
+    unmount();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});
+
+describe("formatElapsed", () => {
+  it("formats each magnitude", () => {
+    expect(formatElapsed(500)).toBe("just now");
+    expect(formatElapsed(42_000)).toBe("42s");
+    expect(formatElapsed(3 * 60_000 + 12_000)).toBe("3m 12s");
+    expect(formatElapsed(5 * 60_000)).toBe("5m");
+    expect(formatElapsed(65 * 60_000)).toBe("1h 5m");
+    expect(formatElapsed(120 * 60_000)).toBe("2h");
+  });
+});

package/src/internal/__tests__/useIsOverflowing.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { createElement } from "react";
+import { render, cleanup } from "@testing-library/react";
+import { useIsOverflowing } from "../useIsOverflowing";
+
+afterEach(cleanup);
+
+function Probe({
+  enabled,
+  onState,
+}: {
+  enabled: boolean;
+  onState: (overflowing: boolean) => void;
+}) {
+  const { ref, isOverflowing } = useIsOverflowing<HTMLDivElement>(enabled);
+  onState(isOverflowing);
+  return createElement("div", { ref }, "content");
+}
+
+// happy-dom does not compute layout (scrollHeight === clientHeight === 0), so the
+// deterministic contract here is the `enabled` gate and the not-overflowing
+// baseline; the clipped (overflowing) case is verified against a real browser in
+// the e2e layer, mirroring the SDK's documented unit/e2e split.
+describe("useIsOverflowing", () => {
+  it("reports not-overflowing when disabled (observer never attached)", () => {
+    let state = true;
+    render(createElement(Probe, { enabled: false, onState: (s) => (state = s) }));
+    expect(state).toBe(false);
+  });
+
+  it("reports not-overflowing for content that fits its container", () => {
+    let state = true;
+    render(createElement(Probe, { enabled: true, onState: (s) => (state = s) }));
+    expect(state).toBe(false);
+  });
+});

package/src/internal/__tests__/useKeyedSubmission.test.tsx

@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useKeyedSubmission } from "../useKeyedSubmission";
+
+describe("useKeyedSubmission", () => {
+  it("tracks a key while its operation is in flight, then releases it", async () => {
+    let resolve!: () => void;
+    const { result } = renderHook(() => useKeyedSubmission<void>());
+
+    let pending: Promise<void>;
+    act(() => {
+      pending = result.current.run("k-1", () => new Promise<void>((r) => (resolve = r)));
+    });
+
+    expect(result.current.submittingKeys.has("k-1")).toBe(true);
+
+    await act(async () => {
+      resolve();
+      await pending;
+    });
+
+    expect(result.current.submittingKeys.size).toBe(0);
+  });
+
+  it("records a failure keyed, releases the in-flight key, then rethrows", async () => {
+    const { result } = renderHook(() => useKeyedSubmission<void>());
+
+    await act(async () => {
+      await expect(
+        result.current.run("k-1", () => Promise.reject(new Error("boom"))),
+      ).rejects.toThrow("boom");
+    });
+
+    expect(result.current.errorsByKey.get("k-1")?.message).toBe("boom");
+    expect(result.current.submittingKeys.size).toBe(0);
+  });
+
+  it("coerces a non-Error rejection into an Error", async () => {
+    const { result } = renderHook(() => useKeyedSubmission<void>());
+
+    await act(async () => {
+      await expect(
+        result.current.run("k-1", () => Promise.reject("plain string")),
+      ).rejects.toBe("plain string");
+    });
+
+    const recorded = result.current.errorsByKey.get("k-1");
+    expect(recorded).toBeInstanceOf(Error);
+    expect(recorded?.message).toBe("plain string");
+  });
+
+  it("keys two failures independently — one never clobbers another", async () => {
+    const { result } = renderHook(() => useKeyedSubmission<void>());
+
+    await act(async () => {
+      await expect(
+        result.current.run("k-a", () => Promise.reject(new Error("fail-a"))),
+      ).rejects.toThrow("fail-a");
+    });
+    await act(async () => {
+      await expect(
+        result.current.run("k-b", () => Promise.reject(new Error("fail-b"))),
+      ).rejects.toThrow("fail-b");
+    });
+
+    expect(result.current.errorsByKey.get("k-a")?.message).toBe("fail-a");
+    expect(result.current.errorsByKey.get("k-b")?.message).toBe("fail-b");
+  });
+
+  it("clears a key's prior error at retry-start, leaving siblings untouched", async () => {
+    const { result } = renderHook(() => useKeyedSubmission<void>());
+
+    await act(async () => {
+      await expect(
+        result.current.run("k-a", () => Promise.reject(new Error("fail-a"))),
+      ).rejects.toThrow("fail-a");
+    });
+    await act(async () => {
+      await expect(
+        result.current.run("k-b", () => Promise.reject(new Error("fail-b"))),
+      ).rejects.toThrow("fail-b");
+    });
+
+    // Retrying k-a succeeds: its error clears at run-start; k-b's persists.
+    await act(async () => {
+      await result.current.run("k-a", () => Promise.resolve());
+    });
+
+    expect(result.current.errorsByKey.has("k-a")).toBe(false);
+    expect(result.current.errorsByKey.get("k-b")?.message).toBe("fail-b");
+  });
+
+  it("returns the resolved value on success", async () => {
+    const { result } = renderHook(() => useKeyedSubmission<number>());
+
+    let value: number | undefined;
+    await act(async () => {
+      value = await result.current.run("k-1", () => Promise.resolve(42));
+    });
+
+    expect(value).toBe(42);
+    expect(result.current.errorsByKey.size).toBe(0);
+  });
+
+  it("clearErrors resets every recorded error", async () => {
+    const { result } = renderHook(() => useKeyedSubmission<void>());
+
+    await act(async () => {
+      await expect(
+        result.current.run("k-a", () => Promise.reject(new Error("fail-a"))),
+      ).rejects.toThrow("fail-a");
+    });
+    expect(result.current.errorsByKey.size).toBe(1);
+
+    act(() => result.current.clearErrors());
+    expect(result.current.errorsByKey.size).toBe(0);
+  });
+
+  it("keeps a stable return reference across renders when nothing changes", () => {
+    const { result, rerender } = renderHook(() => useKeyedSubmission<void>());
+
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});

package/src/internal/useAutoDisclosure.ts

@@ -0,0 +1,58 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * Disclosure state machine for progressively-revealed thread sections
+ * (tool-call groups, individual tool rows, sub-agent cards).
+ *
+ * The challenge it solves: a section should open and close *on its own* as
+ * the agent works (open while a tool runs, settle closed when it finishes),
+ * yet a user's explicit click must win and never be stomped by the next
+ * stream frame. Three components hand-rolled this same "auto unless the user
+ * intervened" logic; this hook is the single source of that shape.
+ *
+ * `autoOpen` is the component's live opinion of whether the section *should*
+ * be open right now (e.g. `isRunning || hasPendingApproval`). While the user
+ * has not toggled, `open` tracks `autoOpen`. Once the user toggles, their
+ * choice sticks for the lifetime of the component — the auto signal is
+ * ignored from then on, so the section never reopens or recollapses under
+ * them mid-stream.
+ *
+ * @param autoOpen Whether the section should auto-open given current state.
+ * @param options.initialOpen First-render open state. Defaults to `autoOpen`.
+ *   Use it to honour a caller-provided `defaultExpanded` before the first
+ *   effect runs.
+ * @returns A `[open, toggle]` tuple. `toggle` flips the state and marks it
+ *   user-controlled.
+ *
+ * @example
+ * ```tsx
+ * const [open, toggle] = useAutoDisclosure(isRunning || hasPendingApproval);
+ * <button aria-expanded={open} onClick={toggle}>…</button>
+ * ```
+ */
+export function useAutoDisclosure(
+  autoOpen: boolean,
+  options?: { readonly initialOpen?: boolean },
+): readonly [open: boolean, toggle: () => void] {
+  const [open, setOpen] = useState(options?.initialOpen ?? autoOpen);
+  const userToggledRef = useRef(false);
+  const prevAutoOpenRef = useRef(autoOpen);
+
+  useEffect(() => {
+    // Sync only on a genuine transition of the auto signal — never on mount,
+    // so `initialOpen` is honoured, and never against the user's choice.
+    if (prevAutoOpenRef.current === autoOpen) return;
+    prevAutoOpenRef.current = autoOpen;
+    if (userToggledRef.current) return;
+    setOpen(autoOpen);
+  }, [autoOpen]);
+
+  const toggle = useRef(() => {
+    userToggledRef.current = true;
+    setOpen((v) => !v);
+  }).current;
+
+  return [open, toggle];
+}

package/src/internal/useElapsedSince.ts

@@ -0,0 +1,72 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+
+/**
+ * Live elapsed time since an ISO 8601 timestamp, re-rendering once per second.
+ *
+ * The shape behind every "how long has this been going" affordance in the
+ * thread: an approval gate waiting on a human, a sub-agent card whose nested
+ * activity cannot be streamed (the Cursor SDK returns sub-agent internals only
+ * at completion), a long-running tool. A ticking duration is the honest signal
+ * that work is progressing when there is nothing else to show — as opposed to
+ * fabricating intermediate state.
+ *
+ * Returns elapsed milliseconds (clamped to >= 0 against client/server clock
+ * skew), or `null` when the timestamp is absent or unparseable — callers
+ * render nothing rather than a bogus "0s". The interval is scoped to the
+ * component instance and torn down on unmount, so a thread full of settled
+ * cards costs zero timers.
+ *
+ * @param startedAt ISO 8601 timestamp the clock counts from (e.g.
+ *   `ToolCall.approval_requested_at`, `SubAgentExecution.started_at`).
+ */
+export function useElapsedSince(startedAt: string): number | null {
+  const startMs = useMemo(() => {
+    if (!startedAt) return null;
+    const t = new Date(startedAt).getTime();
+    return Number.isNaN(t) ? null : t;
+  }, [startedAt]);
+
+  const [elapsed, setElapsed] = useState<number | null>(null);
+
+  useEffect(() => {
+    if (startMs === null) {
+      setElapsed(null);
+      return;
+    }
+    setElapsed(Math.max(0, Date.now() - startMs));
+    const id = setInterval(() => {
+      setElapsed(Math.max(0, Date.now() - startMs));
+    }, 1000);
+    return () => clearInterval(id);
+  }, [startMs]);
+
+  return startMs === null ? null : elapsed;
+}
+
+/**
+ * Format an elapsed duration for the live tickers driven by
+ * {@link useElapsedSince}: `just now`, `42s`, `3m 12s`, `1h 5m`.
+ *
+ * Second-granularity (unlike ToolCallDetail's `formatDuration`, which keeps
+ * millisecond precision for completed calls) because a live counter that
+ * flickers sub-second digits reads as noise, not progress.
+ */
+export function formatElapsed(ms: number): string {
+  if (ms < 1000) return "just now";
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) {
+    return remainingSeconds > 0
+      ? `${minutes}m ${remainingSeconds}s`
+      : `${minutes}m`;
+  }
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return remainingMinutes > 0
+    ? `${hours}h ${remainingMinutes}m`
+    : `${hours}h`;
+}

package/src/internal/useIsOverflowing.ts

@@ -0,0 +1,61 @@
+import { useLayoutEffect, useRef, useState } from "react";
+
+export interface UseIsOverflowingReturn<T extends HTMLElement> {
+  /** Attach to the element whose vertical overflow should be tracked. */
+  readonly ref: React.RefObject<T | null>;
+  /** `true` when the element's content is clipped by a vertical clamp (e.g. `overflow-hidden` + `max-h-*`). */
+  readonly isOverflowing: boolean;
+}
+
+/**
+ * Tracks whether a vertically-clamped element (e.g. one styled with
+ * `overflow-hidden max-h-*`) is actually clipping its content at the current
+ * height.
+ *
+ * The vertical analog of {@link useIsTextTruncated}: it measures
+ * `scrollHeight > clientHeight` synchronously via `useLayoutEffect` (so the
+ * first value is correct before paint — no flash) and keeps it in sync with
+ * content-size changes via a `ResizeObserver`. The state setter compares before
+ * writing, so a stable layout never triggers a re-render loop.
+ *
+ * Pass `enabled: false` to opt out entirely — the observer is not attached and
+ * `isOverflowing` stays `false`. Callers gate on this so only the elements that
+ * consume the signal pay for the measurement.
+ *
+ * Note: under a layout-free test environment (`happy-dom`) `scrollHeight` and
+ * `clientHeight` are both `0`, so this reports `false`; overflow-driven UI is
+ * therefore verified in the e2e (real-browser) layer, mirroring the split the
+ * rest of the SDK already documents.
+ *
+ * @internal
+ */
+export function useIsOverflowing<T extends HTMLElement = HTMLElement>(
+  enabled: boolean,
+): UseIsOverflowingReturn<T> {
+  const ref = useRef<T | null>(null);
+  const [isOverflowing, setIsOverflowing] = useState(false);
+
+  useLayoutEffect(() => {
+    if (!enabled) {
+      // Reset so an element that stops consuming the signal doesn't keep a stale true.
+      setIsOverflowing((prev) => (prev ? false : prev));
+      return;
+    }
+
+    const el = ref.current;
+    if (!el) return;
+
+    const measure = () => {
+      const next = el.scrollHeight > el.clientHeight + 1;
+      setIsOverflowing((prev) => (prev === next ? prev : next));
+    };
+
+    measure();
+
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [enabled]);
+
+  return { ref, isOverflowing };
+}

package/src/internal/useIsTextTruncated.ts

@@ -0,0 +1,55 @@
+import { useLayoutEffect, useRef, useState } from "react";
+
+export interface UseIsTextTruncatedReturn<T extends HTMLElement> {
+  /** Attach to the element whose horizontal overflow should be tracked. */
+  readonly ref: React.RefObject<T | null>;
+  /** `true` when the element's content is clipped by `overflow` (e.g. `truncate`). */
+  readonly isTruncated: boolean;
+}
+
+/**
+ * Tracks whether a single-line, overflow-clipped element (e.g. one styled with
+ * Tailwind's `truncate`) is actually truncating its text at the current width.
+ *
+ * The horizontal analog of {@link useScrollShadows}: it measures
+ * `scrollWidth > clientWidth` synchronously via `useLayoutEffect` (so the first
+ * value is correct before paint — no flash) and keeps it in sync with width
+ * changes via a `ResizeObserver`. The state setter compares before writing, so a
+ * stable layout never triggers a re-render loop.
+ *
+ * Pass `enabled: false` to opt a row out entirely — the observer is not attached
+ * and `isTruncated` stays `false`. Callers gate on this so only the rows that
+ * consume the signal pay for the measurement.
+ *
+ * @internal
+ */
+export function useIsTextTruncated<T extends HTMLElement = HTMLElement>(
+  enabled: boolean,
+): UseIsTextTruncatedReturn<T> {
+  const ref = useRef<T | null>(null);
+  const [isTruncated, setIsTruncated] = useState(false);
+
+  useLayoutEffect(() => {
+    if (!enabled) {
+      // Reset so a row that stops consuming the signal doesn't keep a stale true.
+      setIsTruncated((prev) => (prev ? false : prev));
+      return;
+    }
+
+    const el = ref.current;
+    if (!el) return;
+
+    const measure = () => {
+      const next = el.scrollWidth > el.clientWidth + 1;
+      setIsTruncated((prev) => (prev === next ? prev : next));
+    };
+
+    measure();
+
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [enabled]);
+
+  return { ref, isTruncated };
+}