feat(conversation): add useHistoryWindow and ConversationEarlier (#122)

* feat(conversation): add useHistoryWindow and ConversationEarlier

useHistoryWindow keeps a window of the latest items, adds earlier ones
as the reader nears the top, freezes while the reader has scrolled away
and trims back once they return to the end. It works with history the
host pages in asynchronously, and the item in view stays put within a
pixel as earlier items load. ConversationEarlier marks the top with a
loading state and a retry when a page brings nothing. The doc comment
records why this windows rather than virtualizes, and its ceiling.

* fix(conversation): hold the history window until the view is read

An item committed synchronously in the frame the reader scrolled up
in, before the conversation's scroll pass, slid or trimmed the window:
atBottom and the freeze were still a frame old, so the oldest item was
removed while the reader was scrolled up.

A new item now commits with nothing removed. A layout effect then trims
or slides the window as before, unless the view has moved towards the
top since the last scroll snapshot; the next pass then freezes it if
the scroll was the reader's. The snapshot subscription moves to a
layout effect so the one sent when the container mounts is not missed.

A loader that throws now stalls like one that rejects, and its error is
reported once instead of escaping the marker's observer callback. The
scroll helpers both conversation specs copied now live in one module.

* fix(conversation): keep the window start when the last id is swapped

The window remembers the last item it was trimmed through. When that
id vanished in the same update as an append (an optimistic id swapped
for the server's, plus the reply), the window slid by one during
render. If the reader had just scrolled up, the next frame froze the
slid start and the window's first item was gone.

A missing trim id now falls back as a missing pin does: to the first
item of the last window that still exists. At the bottom, the next
commit trims back, as it does after a plain append.

* fix(conversation): freeze the history window on any move up

Only a scroll the reader made froze the window's start. A move the page
made, such as a glide to an item, focus or find in page, left the start
following the latest items, so the next appended item slid the window
and unmounted the item the view had just been moved to.

The window now freezes on any scroll snapshot that moved the view
towards the top and ended away from the end. Content growing below a
view that stays put leaves scrollTop unchanged, so the window still
slides then.

* fix(conversation): keep the history window's last slice in state

The window start's fallback, used when the item it is kept by is gone,
read the previous window from a ref during render. The ref was written
by a layout effect, so it went stale while Activity hid the host: a
start grown while hidden whose item was then deleted fell back to the
window from before the host was hidden.

The last slice now lives in the hook's state, recorded during render as
atBottom already is, and the scroll listener reads the window's first
item in the handler rather than in a state updater.

* docs(conversation): say which failed loads the history window reports

The onLoadEarlier doc said the hook never reports a failure. A loader
that throws synchronously is reported through reportError, so that it
does not escape the marker's observer callback; only a rejection is
left to the host.

* fix(conversation): forward ConversationEarlier's ref under React 18

ConversationEarlier read ref from its props, which React 19 passes but
React 18 strips, so a ref never reached the marker on React 18, the
lower end of the peer range. It is now wrapped in forwardRef.

Author: pratikbuilds

e2e/conversation-helpers.ts

@@ -0,0 +1,74 @@
+// Reads and drives the conversation scroll container the e2e scenarios render.
+import { expect, type Page } from "@playwright/test";
+
+export const container = (page: Page) =>
+  page.locator("[data-slot='conversation-content']");
+
+export const view = (page: Page) =>
+  container(page).evaluate((element) => ({
+    scrollTop: element.scrollTop,
+    top: element.getBoundingClientRect().top,
+    distanceFromEnd:
+      element.scrollHeight - element.scrollTop - element.clientHeight,
+  }));
+
+/** How far an item's top sits below the top of the view. */
+export const offsetOf = async (page: Page, id: string) => {
+  const { top } = await view(page);
+  const itemTop = await page
+    .getByTestId(id)
+    .evaluate((element) => element.getBoundingClientRect().top);
+  return itemTop - top;
+};
+
+/** Waits for the view to stop moving (a glide or a wheel scroll to land). */
+export const settled = async (page: Page) => {
+  let previous = Number.NaN;
+  await expect
+    .poll(
+      async () => {
+        const { scrollTop } = await view(page);
+        const still = scrollTop === previous;
+        previous = scrollTop;
+        return still;
+      },
+      { intervals: [100] },
+    )
+    .toBe(true);
+};
+
+/** The reader's own scroll: a wheel over the conversation. */
+export const wheel = async (page: Page, deltaY: number) => {
+  const box = await container(page).boundingBox();
+  if (box === null) throw new Error("expected the conversation on screen");
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+  await page.mouse.wheel(0, deltaY);
+  await settled(page);
+};
+
+export const atEnd = async (page: Page) => {
+  await expect
+    .poll(async () => (await view(page)).distanceFromEnd)
+    .toBeLessThanOrEqual(1);
+};
+
+/** The id of the topmost item in view. */
+export const firstVisible = (page: Page) =>
+  container(page).evaluate((element) => {
+    const top = element.getBoundingClientRect().top;
+    const items = element.querySelectorAll<HTMLElement>("[data-testid]");
+    for (const item of items) {
+      if (item.getBoundingClientRect().bottom > top)
+        return item.dataset.testid ?? "";
+    }
+    return "";
+  });
+
+/** Two frames: one for resize callbacks, one for any correction to land. */
+export const frames = (page: Page) =>
+  page.evaluate(
+    () =>
+      new Promise((resolve) =>
+        requestAnimationFrame(() => requestAnimationFrame(resolve)),
+      ),
+  );

e2e/conversation.spec.ts

@@ -1,67 +1,15 @@
 import { expect, test, type Page } from "@playwright/test";
 
-const container = (page: Page) =>
-  page.locator("[data-slot='conversation-content']");
-
-const view = (page: Page) =>
-  container(page).evaluate((element) => ({
-    scrollTop: element.scrollTop,
-    top: element.getBoundingClientRect().top,
-    distanceFromEnd:
-      element.scrollHeight - element.scrollTop - element.clientHeight,
-  }));
-
-/** How far an item's top sits below the top of the view. */
-const offsetOf = async (page: Page, id: string) => {
-  const { top } = await view(page);
-  const itemTop = await page
-    .getByTestId(id)
-    .evaluate((element) => element.getBoundingClientRect().top);
-  return itemTop - top;
-};
-
-/** Waits for the view to stop moving (a glide or a wheel scroll to land). */
-const settled = async (page: Page) => {
-  let previous = Number.NaN;
-  await expect
-    .poll(
-      async () => {
-        const { scrollTop } = await view(page);
-        const still = scrollTop === previous;
-        previous = scrollTop;
-        return still;
-      },
-      { intervals: [100] },
-    )
-    .toBe(true);
-};
-
-/** The reader's own scroll: a wheel over the conversation. */
-const wheel = async (page: Page, deltaY: number) => {
-  const box = await container(page).boundingBox();
-  if (box === null) throw new Error("expected the conversation on screen");
-  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
-  await page.mouse.wheel(0, deltaY);
-  await settled(page);
-};
-
-const atEnd = async (page: Page) => {
-  await expect
-    .poll(async () => (await view(page)).distanceFromEnd)
-    .toBeLessThanOrEqual(1);
-};
-
-/** The id of the topmost item in view. */
-const firstVisible = (page: Page) =>
-  container(page).evaluate((element) => {
-    const top = element.getBoundingClientRect().top;
-    const items = element.querySelectorAll<HTMLElement>("[data-testid]");
-    for (const item of items) {
-      if (item.getBoundingClientRect().bottom > top)
-        return item.dataset.testid ?? "";
-    }
-    return "";
-  });
+import {
+  atEnd,
+  container,
+  firstVisible,
+  frames,
+  offsetOf,
+  settled,
+  view,
+  wheel,
+} from "./conversation-helpers.js";
 
 /** Opens a scenario once its history (which arrives after mount) is in. */
 const open = async (page: Page, scenario: string) => {
@@ -74,13 +22,7 @@ const write = async (page: Page, times: number) => {
   for (let count = 0; count < times; count += 1) {
     await page.getByRole("button", { name: "Write" }).click();
   }
-  // One frame for the resize callback, one for any correction to land.
-  await page.evaluate(
-    () =>
-      new Promise((resolve) =>
-        requestAnimationFrame(() => requestAnimationFrame(resolve)),
-      ),
-  );
+  await frames(page);
 };
 
 test.describe("settle", () => {

e2e/fixtures.tsx

@@ -62,6 +62,8 @@ import {
   MessageContent,
   MessageFold,
   MessageFooter,
+  ConversationEarlier,
+  useHistoryWindow,
 } from "@corbits/react-ui";
 import {
   CommandPalette,
@@ -1193,6 +1195,116 @@ function MessageActionsScenario() {
   );
 }
 
+type HistoryRow = { readonly id: string; readonly lines: number };
+
+/** Rows of fractional heights, so rounding shows up in the positions. */
+function historyWindowRows(from: number, to: number): HistoryRow[] {
+  return Array.from({ length: to - from }, (_, index) => ({
+    id: `r${from + index}`,
+    lines: 1 + ((from + index) % 3),
+  }));
+}
+
+const HISTORY_PAGE = 10;
+
+/** Renders the window; must sit inside the Conversation it follows. */
+function HistoryRows({
+  rows,
+  hasEarlier,
+  onLoadEarlier,
+  distance,
+}: {
+  rows: readonly HistoryRow[];
+  hasEarlier: boolean;
+  onLoadEarlier: () => Promise<void>;
+  distance: number | undefined;
+}) {
+  const history = useHistoryWindow({
+    items: rows,
+    windowSize: 30,
+    step: HISTORY_PAGE,
+    hasEarlier,
+    onLoadEarlier,
+  });
+  return (
+    <>
+      <ConversationContent>
+        <ConversationEarlier
+          hasEarlier={history.hasEarlier}
+          loading={history.loading}
+          stalled={history.stalled}
+          onReachStart={history.reachStart}
+          distance={distance}
+        />
+        {history.items.map((row) => (
+          <ConversationItem key={row.id} itemId={row.id} data-testid={row.id}>
+            <p style={{ height: row.lines * 23.5, margin: 0 }}>Row {row.id}</p>
+          </ConversationItem>
+        ))}
+      </ConversationContent>
+      <ConversationScrollButton />
+      <div style={{ display: "flex", gap: 8 }}>
+        <Button onClick={history.reachStart}>Load earlier</Button>
+        <output aria-label="Shown">{history.items.length}</output>
+      </div>
+    </>
+  );
+}
+
+/**
+ * `local` rows are loaded; `remote` older ones come from a pretend server a
+ * page at a time, when "Deliver" is pressed. "Deliver nothing" ends a load
+ * with no rows.
+ */
+function HistoryWindowScenario({
+  local,
+  remote,
+  distance,
+}: {
+  local: number;
+  remote: number;
+  distance?: number;
+}) {
+  const [from, setFrom] = useState(remote);
+  const [to, setTo] = useState(remote + local);
+  const [requests, setRequests] = useState(0);
+  const [pending, setPending] = useState<(() => void) | null>(null);
+  const settle = (rows: number) => {
+    if (pending === null) return;
+    setFrom((current) => Math.max(0, current - rows));
+    setPending(null);
+    pending();
+  };
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        height: 400,
+        width: 600,
+      }}
+    >
+      <Conversation>
+        <HistoryRows
+          rows={historyWindowRows(from, to)}
+          hasEarlier={from > 0}
+          onLoadEarlier={() => {
+            setRequests((count) => count + 1);
+            return new Promise((resolve) => setPending(() => resolve));
+          }}
+          distance={distance}
+        />
+      </Conversation>
+      <div style={{ display: "flex", gap: 8 }}>
+        <Button onClick={() => setTo((current) => current + 1)}>Append</Button>
+        <Button onClick={() => settle(HISTORY_PAGE)}>Deliver</Button>
+        <Button onClick={() => settle(0)}>Deliver nothing</Button>
+        <output aria-label="Requests">{requests}</output>
+      </div>
+    </div>
+  );
+}
+
 export const scenarios: Record<string, () => ReactNode> = {
   smoke: () => <Button>Ready</Button>,
   "approval-card": () => <Approval state="idle" />,
@@ -1245,4 +1357,13 @@ export const scenarios: Record<string, () => ReactNode> = {
     <MessageFoldConversationScenario policy="stick" />
   ),
   "message-actions": () => <MessageActionsScenario />,
+  "history-window": () => (
+    <HistoryWindowScenario local={100} remote={0} distance={0} />
+  ),
+  "history-window-paged": () => (
+    <HistoryWindowScenario local={20} remote={30} distance={0} />
+  ),
+  "history-window-reach": () => (
+    <HistoryWindowScenario local={200} remote={0} />
+  ),
 };