@stigmer/react 0.3.4 → 0.4.0

package/src/internal/__tests__/thread-animation.test.tsx

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import React from "react";
+import { ThreadItemWrapper } from "../ThreadItemWrapper";
+import { JumpToLatestButton } from "../JumpToLatestButton";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// ThreadItemWrapper
+// ---------------------------------------------------------------------------
+
+describe("ThreadItemWrapper", () => {
+  it("applies stgm-thread-item-enter class on mount when animate=true", () => {
+    const { container } = render(
+      <ThreadItemWrapper animate>
+        <span>content</span>
+      </ThreadItemWrapper>,
+    );
+
+    const wrapper = container.firstElementChild as HTMLElement;
+    expect(wrapper.classList.contains("stgm-thread-item-enter")).toBe(true);
+    expect(screen.getByText("content")).toBeTruthy();
+  });
+
+  it("removes animation class after animationend", () => {
+    const { container } = render(
+      <ThreadItemWrapper animate>
+        <span>content</span>
+      </ThreadItemWrapper>,
+    );
+
+    const wrapper = container.firstElementChild as HTMLElement;
+    expect(wrapper.classList.contains("stgm-thread-item-enter")).toBe(true);
+
+    fireEvent.animationEnd(wrapper);
+
+    expect(container.querySelector(".stgm-thread-item-enter")).toBeNull();
+    expect(screen.getByText("content")).toBeTruthy();
+  });
+
+  it("renders children directly when animate=false (no wrapper div)", () => {
+    const { container } = render(
+      <ThreadItemWrapper animate={false}>
+        <span data-testid="child">no-animation</span>
+      </ThreadItemWrapper>,
+    );
+
+    expect(container.querySelector(".stgm-thread-item-enter")).toBeNull();
+    expect(screen.getByTestId("child")).toBeTruthy();
+  });
+
+  it("renders children directly after animation completes (no residual wrapper)", () => {
+    const { container, rerender } = render(
+      <ThreadItemWrapper animate>
+        <span>content</span>
+      </ThreadItemWrapper>,
+    );
+
+    const wrapper = container.firstElementChild as HTMLElement;
+    fireEvent.animationEnd(wrapper);
+
+    rerender(
+      <ThreadItemWrapper animate>
+        <span>content</span>
+      </ThreadItemWrapper>,
+    );
+
+    const span = screen.getByText("content");
+    expect(span.tagName).toBe("SPAN");
+    expect(container.querySelector(".stgm-thread-item-enter")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// JumpToLatestButton
+// ---------------------------------------------------------------------------
+
+describe("JumpToLatestButton", () => {
+  it("renders visible state with correct attributes", () => {
+    const onClick = vi.fn();
+    render(<JumpToLatestButton onClick={onClick} visible />);
+
+    const button = screen.getByRole("button", { name: "Jump to latest" });
+    expect(button.getAttribute("aria-hidden")).toBe("false");
+    expect(button.getAttribute("tabindex")).toBe("0");
+    expect(button.className).toContain("opacity-100");
+    expect(button.className).toContain("pointer-events-auto");
+  });
+
+  it("renders hidden state with correct attributes", () => {
+    const onClick = vi.fn();
+    render(<JumpToLatestButton onClick={onClick} visible={false} />);
+
+    const button = screen.getByLabelText("Jump to latest");
+    expect(button.getAttribute("aria-hidden")).toBe("true");
+    expect(button.getAttribute("tabindex")).toBe("-1");
+    expect(button.className).toContain("opacity-0");
+    expect(button.className).toContain("pointer-events-none");
+    expect(button.className).toContain("translate-y-2");
+  });
+
+  it("calls onClick when clicked in visible state", () => {
+    const onClick = vi.fn();
+    render(<JumpToLatestButton onClick={onClick} visible />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Jump to latest" }));
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it("has transition classes for smooth enter/exit", () => {
+    const onClick = vi.fn();
+    render(<JumpToLatestButton onClick={onClick} visible />);
+
+    const button = screen.getByRole("button", { name: "Jump to latest" });
+    expect(button.className).toContain("transition-[opacity,transform]");
+  });
+});

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

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, act, screen, cleanup } from "@testing-library/react";
+import React from "react";
+import { useAutoScroll, type UseAutoScrollReturn } from "../useAutoScroll";
+
+// ---------------------------------------------------------------------------
+// Test harness — renders actual DOM elements so refs get populated
+// ---------------------------------------------------------------------------
+
+let latestResult: UseAutoScrollReturn;
+
+function Harness() {
+  const result = useAutoScroll();
+  latestResult = result;
+  return (
+    <div ref={result.scrollRef} data-testid="scroller">
+      <div ref={result.contentRef} data-testid="content">
+        <p>Hello</p>
+      </div>
+      <div ref={result.sentinelRef} data-testid="sentinel" />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Observer mocks
+// ---------------------------------------------------------------------------
+
+type IOCallback = IntersectionObserverCallback;
+type ROCallback = ResizeObserverCallback;
+
+let ioCallback: IOCallback;
+let ioDisconnect: ReturnType<typeof vi.fn>;
+let ioObserve: ReturnType<typeof vi.fn>;
+
+let roCallback: ROCallback;
+let roDisconnect: ReturnType<typeof vi.fn>;
+let roObserve: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  ioDisconnect = vi.fn();
+  ioObserve = vi.fn();
+  roDisconnect = vi.fn();
+  roObserve = vi.fn();
+
+  vi.stubGlobal(
+    "IntersectionObserver",
+    vi.fn((cb: IOCallback) => {
+      ioCallback = cb;
+      return {
+        observe: ioObserve,
+        unobserve: vi.fn(),
+        disconnect: ioDisconnect,
+        takeRecords: vi.fn(() => []),
+        root: null,
+        rootMargin: "",
+        thresholds: [0],
+      };
+    }),
+  );
+
+  vi.stubGlobal(
+    "ResizeObserver",
+    vi.fn((cb: ROCallback) => {
+      roCallback = cb;
+      return {
+        observe: roObserve,
+        unobserve: vi.fn(),
+        disconnect: roDisconnect,
+      };
+    }),
+  );
+
+  vi.stubGlobal(
+    "requestAnimationFrame",
+    vi.fn((cb: FrameRequestCallback) => {
+      cb(performance.now());
+      return 1;
+    }),
+  );
+
+  vi.stubGlobal("cancelAnimationFrame", vi.fn());
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function fireIO(isIntersecting: boolean) {
+  act(() => {
+    ioCallback(
+      [{ isIntersecting } as IntersectionObserverEntry],
+      {} as IntersectionObserver,
+    );
+  });
+}
+
+function fireRO() {
+  act(() => {
+    roCallback([], {} as ResizeObserver);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("useAutoScroll", () => {
+  it("starts in following state", () => {
+    render(<Harness />);
+    expect(latestResult.isFollowing).toBe(true);
+  });
+
+  it("observes sentinel with IntersectionObserver on mount", () => {
+    render(<Harness />);
+    expect(ioObserve).toHaveBeenCalledWith(screen.getByTestId("sentinel"));
+  });
+
+  it("observes content with ResizeObserver on mount", () => {
+    render(<Harness />);
+    expect(roObserve).toHaveBeenCalledWith(screen.getByTestId("content"));
+  });
+
+  it("configures IO with 80px bottom root margin", () => {
+    render(<Harness />);
+    const IOConstructor = vi.mocked(IntersectionObserver);
+    const options = IOConstructor.mock.calls[0]?.[1];
+    expect(options?.rootMargin).toBe("0px 0px 80px 0px");
+  });
+
+  it("configures IO with scroll container as root", () => {
+    render(<Harness />);
+    const IOConstructor = vi.mocked(IntersectionObserver);
+    const options = IOConstructor.mock.calls[0]?.[1];
+    expect(options?.root).toBe(screen.getByTestId("scroller"));
+  });
+
+  it("disengages when sentinel exits viewport", () => {
+    render(<Harness />);
+    fireIO(false);
+    expect(latestResult.isFollowing).toBe(false);
+  });
+
+  it("re-engages when sentinel enters viewport", () => {
+    render(<Harness />);
+    fireIO(false);
+    expect(latestResult.isFollowing).toBe(false);
+
+    fireIO(true);
+    expect(latestResult.isFollowing).toBe(true);
+  });
+
+  it("jumpToLatest re-engages follow mode", () => {
+    render(<Harness />);
+    fireIO(false);
+    expect(latestResult.isFollowing).toBe(false);
+
+    act(() => {
+      latestResult.jumpToLatest();
+    });
+
+    expect(latestResult.isFollowing).toBe(true);
+  });
+
+  it("jumpToLatest sets scrollTop to scrollHeight", () => {
+    render(<Harness />);
+    fireIO(false);
+
+    const scroller = screen.getByTestId("scroller");
+    Object.defineProperty(scroller, "scrollHeight", {
+      value: 1000,
+      configurable: true,
+    });
+
+    act(() => {
+      latestResult.jumpToLatest();
+    });
+
+    expect(scroller.scrollTop).toBe(1000);
+  });
+
+  it("scrolls via rAF on content resize while following", () => {
+    render(<Harness />);
+    fireIO(true);
+
+    const scroller = screen.getByTestId("scroller");
+    Object.defineProperty(scroller, "scrollHeight", {
+      value: 500,
+      configurable: true,
+    });
+
+    fireRO();
+
+    expect(requestAnimationFrame).toHaveBeenCalled();
+    expect(scroller.scrollTop).toBe(500);
+  });
+
+  it("does not scroll on content resize while disengaged", () => {
+    render(<Harness />);
+    fireIO(false);
+
+    const scroller = screen.getByTestId("scroller");
+    Object.defineProperty(scroller, "scrollHeight", {
+      value: 500,
+      configurable: true,
+    });
+
+    vi.mocked(requestAnimationFrame).mockClear();
+
+    fireRO();
+
+    expect(requestAnimationFrame).not.toHaveBeenCalled();
+  });
+
+  it("cancels pending rAF before scheduling a new one", () => {
+    render(<Harness />);
+    fireIO(true);
+
+    fireRO();
+    fireRO();
+
+    expect(cancelAnimationFrame).toHaveBeenCalled();
+  });
+
+  it("disconnects IO on unmount", () => {
+    const { unmount } = render(<Harness />);
+    unmount();
+    expect(ioDisconnect).toHaveBeenCalled();
+  });
+
+  it("disconnects RO on unmount", () => {
+    const { unmount } = render(<Harness />);
+    unmount();
+    expect(roDisconnect).toHaveBeenCalled();
+  });
+
+  it("cancels pending rAF on unmount", () => {
+    const { unmount } = render(<Harness />);
+    fireIO(true);
+    fireRO();
+
+    vi.mocked(cancelAnimationFrame).mockClear();
+    unmount();
+
+    expect(cancelAnimationFrame).toHaveBeenCalled();
+  });
+
+  it("scrolls to bottom on mount without error", () => {
+    // The hook sets scrollTop = scrollHeight in the IO setup effect.
+    // In jsdom both values are 0, so scrollTop stays 0. The important
+    // thing is that the code path executes without error; real scroll
+    // behavior is validated by integration tests.
+    render(<Harness />);
+    expect(screen.getByTestId("scroller").scrollTop).toBe(0);
+  });
+});

package/src/internal/__tests__/useFetch-cache.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { createElement } from "react";
+import { FetchCacheContext, useFetchCache } from "../FetchCacheProvider";
+import { FetchCache } from "../fetch-cache";
+import { useFetch } from "../useFetch";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function flush(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+/**
+ * Build a wrapper that provides a specific FetchCache instance via
+ * context. Tests that need cross-mount caching share the same cache
+ * object, mirroring the production layout where FetchCacheProvider
+ * sits above the key-based remount boundary.
+ */
+function createCacheWrapper(cache: FetchCache) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return createElement(FetchCacheContext.Provider, { value: cache }, children);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests: useFetch + FetchCacheProvider
+// ---------------------------------------------------------------------------
+
+describe("useFetch — cache integration", () => {
+  it("serves cached data on mount and skips isLoading", async () => {
+    const cache = new FetchCache();
+    const wrapper = createCacheWrapper(cache);
+
+    // First mount: populate the cache via a normal fetch.
+    const fetchFn = vi.fn(async () => "fetched-value");
+
+    const { result, unmount } = renderHook(
+      () => useFetch(fetchFn, [], "init", { cacheKey: "test:1" }),
+      { wrapper },
+    );
+
+    expect(result.current.isLoading).toBe(true);
+    await flush();
+    expect(result.current.data).toBe("fetched-value");
+    expect(result.current.isLoading).toBe(false);
+
+    unmount();
+
+    // Second mount (simulating remount after key change): should
+    // seed state from cache and never show isLoading.
+    const fetchFn2 = vi.fn(async () => "fresh-value");
+    const { result: result2 } = renderHook(
+      () => useFetch(fetchFn2, [], "init", { cacheKey: "test:1" }),
+      { wrapper },
+    );
+
+    // On mount, cached data is available immediately.
+    expect(result2.current.data).toBe("fetched-value");
+    expect(result2.current.isLoading).toBe(false);
+    expect(result2.current.isRefetching).toBe(true);
+
+    // Background fetch completes and updates data.
+    await flush();
+    expect(result2.current.data).toBe("fresh-value");
+    expect(result2.current.isRefetching).toBe(false);
+  });
+
+  it("falls back to initialData on cache miss", async () => {
+    const cache = new FetchCache();
+    const wrapper = createCacheWrapper(cache);
+    const fetchFn = vi.fn(async () => "fetched");
+
+    const { result } = renderHook(
+      () => useFetch(fetchFn, [], "init", { cacheKey: "miss:1" }),
+      { wrapper },
+    );
+
+    expect(result.current.data).toBe("init");
+    expect(result.current.isLoading).toBe(true);
+
+    await flush();
+    expect(result.current.data).toBe("fetched");
+  });
+
+  it("writes to cache on fetch success", async () => {
+    const cache = new FetchCache();
+    const wrapper = createCacheWrapper(cache);
+    const fetchFn = vi.fn(async () => "data-1");
+
+    const { result } = renderHook(
+      () => useFetch(fetchFn, [], "init", { cacheKey: "write:1" }),
+      { wrapper },
+    );
+
+    expect(cache.has("write:1")).toBe(false);
+
+    await flush();
+    expect(result.current.data).toBe("data-1");
+    expect(cache.get("write:1")).toBe("data-1");
+  });
+
+  it("does not interact with cache when cacheKey is undefined", async () => {
+    const cache = new FetchCache();
+    const wrapper = createCacheWrapper(cache);
+    const fetchFn = vi.fn(async () => "val");
+
+    const { result } = renderHook(
+      () => useFetch(fetchFn, [], "init"),
+      { wrapper },
+    );
+
+    await flush();
+    expect(result.current.data).toBe("val");
+    expect(cache.size).toBe(0);
+  });
+
+  it("works without FetchCacheProvider (graceful degradation)", async () => {
+    const fetchFn = vi.fn(async () => "value");
+
+    // No wrapper — no provider.
+    const { result } = renderHook(() =>
+      useFetch(fetchFn, [], "init", { cacheKey: "no-provider:1" }),
+    );
+
+    expect(result.current.data).toBe("init");
+    expect(result.current.isLoading).toBe(true);
+
+    await flush();
+    expect(result.current.data).toBe("value");
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it("does not read cache when fetchFn is null", async () => {
+    const cache = new FetchCache();
+    const wrapper = createCacheWrapper(cache);
+
+    const fetchFn1 = vi.fn(async () => "cached-val");
+
+    // First: populate cache.
+    const { unmount } = renderHook(
+      () => useFetch(fetchFn1, [], "init", { cacheKey: "null-fn:1" }),
+      { wrapper },
+    );
+    await flush();
+    unmount();
+
+    // Second: mount with fetchFn=null — should reset to initialData
+    // even though cache has data for this key.
+    const { result } = renderHook(
+      () =>
+        useFetch(null, [], "fallback" as string | null, {
+          cacheKey: "null-fn:1",
+        }),
+      { wrapper },
+    );
+
+    expect(result.current.data).toBe("fallback");
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it("does not write to cache on fetch error", async () => {
+    const cache = new FetchCache();
+    const wrapper = createCacheWrapper(cache);
+    const fetchFn = vi.fn(async () => {
+      throw new Error("fail");
+    });
+
+    const { result } = renderHook(
+      () => useFetch(fetchFn, [], "init", { cacheKey: "err:1" }),
+      { wrapper },
+    );
+
+    await flush();
+    expect(result.current.error?.message).toBe("fail");
+    expect(cache.has("err:1")).toBe(false);
+  });
+
+  it("independent cache keys do not interfere", async () => {
+    const cache = new FetchCache();
+    const wrapper = createCacheWrapper(cache);
+
+    const fetchA = vi.fn(async () => "session-A");
+    const fetchB = vi.fn(async () => "session-B");
+
+    const { unmount: unmountA } = renderHook(
+      () => useFetch(fetchA, [], null, { cacheKey: "session:A" }),
+      { wrapper },
+    );
+    await flush();
+    unmountA();
+
+    const { unmount: unmountB } = renderHook(
+      () => useFetch(fetchB, [], null, { cacheKey: "session:B" }),
+      { wrapper },
+    );
+    await flush();
+    unmountB();
+
+    // Remount A — should get A's cached data, not B's.
+    const { result } = renderHook(
+      () => useFetch(vi.fn(async () => "fresh-A"), [], null, { cacheKey: "session:A" }),
+      { wrapper },
+    );
+
+    expect(result.current.data).toBe("session-A");
+    expect(result.current.isLoading).toBe(false);
+  });
+});