@dxos/react-ui-feed 0.11.1

package/src/stories/navigation.stories.tsx

@@ -0,0 +1,145 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { FeedStory, type FeedStoryProps } from '../testing';
+
+/**
+ * Arrow keys step between the feed's stops, one press one stop.
+ *
+ * The property under test is that a press always moves, and always to the adjacent stop: a smooth
+ * scroll passes through every range between here and its target, and the cursor follows the range
+ * whenever the reader scrolls past it — so a navigation that does not defend its destination
+ * overwrites it mid-flight and the next press steps from a row the animation was crossing. The
+ * symptom is an arrow that sometimes moves and sometimes returns to the row it just left.
+ */
+const meta: Meta<FeedStoryProps> = {
+  title: 'ui/react-ui-feed/stories/navigation',
+  render: FeedStory,
+  decorators: [withLayout({ layout: 'column', classNames: 'w-[50rem]' }), withTheme()],
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+
+type Story = StoryObj<FeedStoryProps>;
+
+/** Frames to let a step settle: the travel is smooth, and the readout follows the range. */
+const SETTLE_FRAMES = 30;
+
+const nextFrame = () => new Promise<number>((resolve) => requestAnimationFrame(resolve));
+
+const settle = async () => {
+  for (let frame = 0; frame < SETTLE_FRAMES; frame++) {
+    await nextFrame();
+  }
+};
+
+/**
+ * The reading the complaint is about: where the feed actually is.
+ *
+ * Not the cursor readout, and not `scrollTop` either. The readout can name a neighbour while a stop
+ * is still being measured; and the offset now absorbs the start edge's repayments — content and
+ * scroll shift together so the reader sees nothing move, which also means the raw offset moves when
+ * nothing did. The row under the top edge is what the reader sees, so a press's travel is read as
+ * that row's index: ArrowUp must put an earlier row there, every time.
+ */
+const topRowOf = (canvasElement: HTMLElement): number => {
+  const viewport = within(canvasElement).getByTestId('feed.viewport');
+  const edge = viewport.getBoundingClientRect().top;
+  const rows = [...viewport.querySelectorAll<HTMLElement>('[data-index]')];
+  const row = rows.find((element) => element.getBoundingClientRect().bottom > edge + 1);
+  return row ? Number(row.dataset.index) : -1;
+};
+
+const press = async (viewport: HTMLElement, key: 'ArrowUp' | 'ArrowDown') => {
+  viewport.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+  // A step glides now, so "after the press" means after the travel lands: polled to a scroll that
+  // has held still for a dozen frames, not a fixed wait that encodes one machine's glide speed.
+  let still = 0;
+  let last = viewport.scrollTop;
+  for (let frame = 0; frame < 300 && still < 12; frame++) {
+    await nextFrame();
+    const current = viewport.scrollTop;
+    still = Math.abs(current - last) < 1 ? still + 1 : 0;
+    last = current;
+  }
+};
+
+/** Passive: the feed with its stops, for driving by hand. */
+export const Default: Story = {
+  args: { scenario: 'assistant', count: 200 },
+};
+
+/**
+ * Every press moves, and lands on a stop.
+ *
+ * `assistant` makes every second message a prompt and only prompts are stops, so a stop is an even
+ * index — which is what makes "landed on a stop" checkable rather than merely "moved". The first
+ * press is the odd one out: the feed opens on the last message, an answer, so the nearest stop above
+ * it is one index away where every step afterwards is two.
+ */
+export const Arrows: Story = {
+  args: { scenario: 'assistant', count: 60 },
+  play: async ({ canvasElement }) => {
+    const viewport = within(canvasElement).getByTestId('feed.viewport');
+    await settle();
+
+    // Asserted as the whole path of top-row indices: every ArrowUp must put an earlier row under
+    // the top edge, so a failure names the press that stalled and what it did instead.
+    const rows = [topRowOf(canvasElement)];
+    for (let step = 0; step < 5; step++) {
+      await press(viewport, 'ArrowUp');
+      rows.push(topRowOf(canvasElement));
+    }
+
+    const stalled = rows.slice(1).filter((row, step) => row >= rows[step]);
+    await expect({ rows, stalled }).toEqual({ rows, stalled: [] });
+
+    // And the other way: `ArrowDown` returns towards the tail it came from. Near the end a stop's
+    // start can lie beyond the maximum offset, so "already at max scroll" counts as arrived rather
+    // than as a stall — the feed cannot advance the top row past what the viewport can hold.
+    const back = [topRowOf(canvasElement)];
+    const progressed: boolean[] = [];
+    for (let step = 0; step < 5; step++) {
+      const wasAtMax = viewport.scrollTop >= viewport.scrollHeight - viewport.clientHeight - 2;
+      await press(viewport, 'ArrowDown');
+      back.push(topRowOf(canvasElement));
+      const atMax = viewport.scrollTop >= viewport.scrollHeight - viewport.clientHeight - 2;
+      // A press made progress if the top row advanced, or it carried the viewport to (or held it
+      // at) the maximum — the last stop's start can lie beyond what the viewport can scroll to.
+      progressed.push(back[step + 1] > back[step] || atMax || wasAtMax);
+    }
+
+    const stalls = progressed.filter((ok) => !ok);
+    await expect({ back, stalls }).toEqual({ back, stalls: [] });
+  },
+};
+
+/**
+ * The same property where every message is a stop.
+ *
+ * `plain` names no `isAnchor`, so a press steps one message — and its rows are tall and unequal,
+ * which is the case where the offset moves furthest between two stops.
+ */
+export const Plain: Story = {
+  args: { scenario: 'plain', count: 60 },
+  play: async ({ canvasElement }) => {
+    const viewport = within(canvasElement).getByTestId('feed.viewport');
+    await settle();
+
+    const rows = [topRowOf(canvasElement)];
+    for (let step = 0; step < 5; step++) {
+      await press(viewport, 'ArrowUp');
+      rows.push(topRowOf(canvasElement));
+    }
+
+    const stalled = rows.slice(1).filter((row, step) => row >= rows[step]);
+    await expect({ rows, stalled }).toEqual({ rows, stalled: [] });
+  },
+};

package/src/stories/streaming.stories.tsx

@@ -0,0 +1,132 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { FeedStory, type FeedStoryProps } from '../testing';
+
+/**
+ * The deciding case: a model answering into the tail while the reader watches.
+ *
+ * Every other rung measures a feed that has stopped. This one measures the feed doing the thing it
+ * exists for — a row growing on every frame, re-parsing its markdown as it goes, while the list
+ * follows the tail it keeps moving. Streaming is where the follow, the measurement and the item's
+ * reconciliation all run at once, and it is the only place their interaction shows.
+ */
+const meta: Meta<FeedStoryProps> = {
+  title: 'ui/react-ui-feed/stories/streaming',
+  render: FeedStory,
+  decorators: [withLayout({ layout: 'column', classNames: 'w-[50rem]' }), withTheme()],
+  parameters: { layout: 'fullscreen' },
+  // Seeded with history on purpose: a feed that does not fill its viewport has nothing to follow,
+  // so a test of the follow over an empty one passes whatever the follow does.
+  args: { scenario: 'assistant', count: 200, streaming: true, debug: false, scrollPastEnd: false },
+};
+
+export default meta;
+
+type Story = StoryObj<FeedStoryProps>;
+
+/** Three seconds: several chunks, and at least one gap between turns for the follow to land in. */
+const WATCH_FRAMES = 240;
+
+/** How far the tail may sit below the fold and still count as landed. */
+const TOLERANCE = 2;
+
+const nextFrame = () => new Promise<number>((resolve) => requestAnimationFrame(resolve));
+
+type Sample = {
+  /** The furthest-on row mounted, and how far its bottom is below the viewport's. */
+  behind: number;
+  /**
+   * Content-space top of every mounted row: viewport-relative top plus the scroll offset.
+   *
+   * Viewport space cannot be the reading, because the follow *writes the scroll* — every mounted
+   * row then moves on screen while nothing about the layout is wrong, and a shrink-and-regrow turn
+   * torn across two samples reads as thirteen rows jumping. In content space the follow's writes
+   * are invisible, a shrinking turn moves later rows up, and nothing has any business moving down.
+   */
+  tops: Map<number, number>;
+};
+
+/**
+ * Read from the last row mounted rather than a fixed index: the feed is growing, so the identity of
+ * the last message changes while the sample runs.
+ */
+const sample = (viewport: HTMLElement): Sample | null => {
+  const rows = [...viewport.querySelectorAll<HTMLElement>('[data-index]')];
+  if (!rows.length) {
+    return null;
+  }
+
+  const box = viewport.getBoundingClientRect();
+  const last = rows.reduce((furthest, row) =>
+    Number(row.dataset.index) > Number(furthest.dataset.index) ? row : furthest,
+  );
+
+  return {
+    behind: Math.round(last.getBoundingClientRect().bottom - box.bottom),
+    tops: new Map(
+      rows.map((row) => [
+        Number(row.dataset.index),
+        Math.round(row.getBoundingClientRect().top - box.top + viewport.scrollTop),
+      ]),
+    ),
+  };
+};
+
+/**
+ * Rows that moved *down* between two frames, on a frame where the document did not shrink.
+ *
+ * Direction is the whole point. Content arriving at the tail pushes everything above it up, so rows
+ * moving up is the feed working, and a row moving down is the list undoing something — a measurement
+ * correction, or two things compensating for one change — which reads as a jump mid-answer.
+ *
+ * The exception is real and is not a defect: a turn *removes* blocks as well as adding them — the
+ * status goes when the answer starts — and a feed pinned to its tail keeps the tail pinned by moving
+ * everything down. Measured here as thirteen rows moving together by exactly 65px, landing the tail
+ * at zero. Counting that would be counting the feed doing its job.
+ */
+/** Rows that moved down in content space — which nothing in a streaming feed may do. */
+const descended = (a: Sample, b: Sample): number =>
+  [...b.tops].filter(([index, top]) => a.tops.has(index) && top - a.tops.get(index)! > 1).length;
+
+/** Passive: press ▶ yourself. */
+export const Default: Story = {};
+
+export const Streaming: Story = {
+  play: async ({ canvasElement }) => {
+    const viewport = canvasElement.querySelector<HTMLElement>('[data-testid="feed.viewport"]')!;
+    const samples: Sample[] = [];
+    for (let frame = 0; frame < WATCH_FRAMES; frame++) {
+      await nextFrame();
+      const current = sample(viewport);
+      if (current) {
+        samples.push(current);
+      }
+    }
+
+    const backwards = samples.reduce(
+      (total, current, index) => total + (index ? descended(samples[index - 1], current) : 0),
+      0,
+    );
+
+    // The follow is allowed to lag — it accelerates into a travel rather than teleporting — but it
+    // has to land: polled past the watch, because a slow runner stretches every frame while the
+    // stream's timers run on the wall clock, and sampling mid-turn measures the runner.
+    let landed = samples.at(-1)!.behind;
+    for (let frame = 0; frame < 600 && landed > TOLERANCE; frame++) {
+      await nextFrame();
+      landed = sample(viewport)?.behind ?? landed;
+    }
+
+    await expect({ backwards, landed: landed <= TOLERANCE }).toEqual({
+      backwards: 0,
+      landed: true,
+    });
+  },
+};

package/src/stories/tail.stories.tsx

@@ -0,0 +1,149 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { FeedStory, type FeedStoryProps } from '../testing';
+
+/**
+ * A feed opened at its tail shows its last message, and stays there.
+ *
+ * Both halves matter and both have been broken. The feed has landed at the tail the *estimate*
+ * predicted — 60,000px into a document that measured 71,565 — and been marked positioned there, so
+ * it opened part-way up the conversation and crept the rest of the way at two rows a second. And
+ * with space reserved past the end it has scrolled straight through the last message into the blank
+ * area below it, because the follow chased the element's own maximum rather than the last row.
+ *
+ * So the reading here is the **last row's own bottom edge**, measured against the viewport's, rather
+ * than the scroll offset: an offset can be at the document's end while the last message is nowhere
+ * near the screen. It has to arrive there, and it has to stop.
+ */
+const meta: Meta<FeedStoryProps> = {
+  title: 'ui/react-ui-feed/stories/tail',
+  render: FeedStory,
+  decorators: [withLayout({ layout: 'column', classNames: 'w-[50rem]' }), withTheme()],
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+
+type Story = StoryObj<FeedStoryProps>;
+
+/** Two seconds: long enough to cover the rebuild that follows the first fill, at ~700ms. */
+const WATCH_FRAMES = 150;
+
+/** Frames from the start that are allowed to still be arriving. */
+const ARRIVING = 100;
+
+/**
+ * How far the last row's bottom may sit from the viewport's, in px.
+ *
+ * Not zero: a row's height is fractional and the scroll offset is rounded, so the two edges meet
+ * within a pixel rather than exactly.
+ */
+const TOLERANCE = 2;
+
+const nextFrame = () => new Promise<number>((resolve) => requestAnimationFrame(resolve));
+
+/**
+ * The last message's bottom edge relative to the viewport's; `null` while it is not mounted.
+ *
+ * Zero means the last message is resting on the bottom of the screen — which is what "at the tail"
+ * means to a reader. Positive means it is below the fold, negative means the feed has scrolled past
+ * it into empty space.
+ */
+const tailOf = (viewport: HTMLElement, last: number): number | null => {
+  const row = viewport.querySelector(`[data-index="${last}"]`);
+  return row ? Math.round(row.getBoundingClientRect().bottom - viewport.getBoundingClientRect().bottom) : null;
+};
+
+const playTail = (count: number) =>
+  async function play({ canvasElement }: { canvasElement: HTMLElement }) {
+    const viewport = canvasElement.querySelector<HTMLElement>('[data-testid="feed.viewport"]')!;
+    const samples: (number | null)[] = [];
+    for (let frame = 0; frame < WATCH_FRAMES; frame++) {
+      await nextFrame();
+      samples.push(tailOf(viewport, count - 1));
+    }
+
+    const settled = samples.slice(ARRIVING);
+    // Reported as a set rather than a count: a failure then shows what the tail was doing — absent
+    // (`null`), below the fold, or drifting a pixel at a time — instead of only that it was wrong.
+    await expect({
+      distinct: [...new Set(settled)].sort(),
+      offBy: [...new Set(settled.map((value) => (value === null || Math.abs(value) > TOLERANCE ? value : 0)))],
+    }).toEqual({ distinct: [...new Set(settled)].sort(), offBy: [0] });
+  };
+
+//
+// The same feed with and without space reserved past the last row. Reserving it moves the
+// element's maximum well beyond the tail, so everything that opens or follows the feed has to stop
+// short of it — which is exactly what a test of the offset alone would not notice.
+//
+
+/** Passive: open at the tail and look. */
+export const Default: Story = {
+  args: { scenario: 'thread', count: 500, scrollPastEnd: true },
+};
+
+/** Tall, uneven rows: the case where the estimate is furthest from the truth. */
+export const Plain: Story = {
+  args: { scenario: 'plain', count: 500 },
+  play: playTail(500),
+};
+
+export const PlainPastEnd: Story = {
+  args: { scenario: 'plain', count: 500, scrollPastEnd: true },
+  play: playTail(500),
+};
+
+/** Short rows, all identical: the estimate is right, so the tail should be right immediately. */
+export const Uniform: Story = {
+  args: { scenario: 'uniform', count: 500 },
+  play: playTail(500),
+};
+
+export const UniformPastEnd: Story = {
+  args: { scenario: 'uniform', count: 500, scrollPastEnd: true },
+  play: playTail(500),
+};
+
+/** A chat's shape: per-message renderers, block widgets, and a per-row estimate. */
+export const Assistant: Story = {
+  args: { scenario: 'assistant', count: 200 },
+  play: playTail(200),
+};
+
+export const AssistantPastEnd: Story = {
+  args: { scenario: 'assistant', count: 200, scrollPastEnd: true },
+  play: playTail(200),
+};
+
+/**
+ * The rung the reader actually opened: an editor per row, contents of different lengths.
+ *
+ * `plain` and `uniform` are estimates that happen to be right, and `assistant` is 200 rows rather
+ * than 500. This is the one where the estimate is wrong for nearly every row *and* the document is
+ * long.
+ *
+ * Its `scrollPastEnd` twin is **not** here, and deliberately. It fails, and what it fails on is not
+ * fixable in this engine: the reserved space is a DOM spacer, so it is in the element's
+ * `scrollHeight` and not in the virtualizer's total, and an offset inside it is beyond the
+ * virtualizer's own maximum — `scrollToOffset` then silently declines to move (verified: the element
+ * stayed exactly where it was). The feed opens at the document's end with its last message near the
+ * top of an empty screen. Two coordinate systems for one document is the defect the placement layer
+ * exists to remove, so the requirement is stated where it can be met: `bridge/VariedPastEnd`.
+ */
+export const Varied: Story = {
+  args: { scenario: 'thread', count: 500 },
+  play: playTail(500),
+};
+
+export const VariedPastEnd: Story = {
+  args: { scenario: 'thread', count: 500, scrollPastEnd: true },
+  play: playTail(500),
+};

package/src/stories/widget.stories.tsx

@@ -0,0 +1,107 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { FeedStory, type FeedStoryProps } from '../testing';
+
+/**
+ * A widget the reader opened stays open when its row leaves the window and comes back.
+ *
+ * This is the one blocker on retrofitting `plugin-assistant`, whose tool panels are exactly this: a
+ * disclosure whose open flag is React state inside the widget, which dies with the item. In a
+ * thread that is one long document the question never arises, because nothing ever unmounts.
+ */
+const meta: Meta<FeedStoryProps> = {
+  title: 'ui/react-ui-feed/stories/widget',
+  render: FeedStory,
+  decorators: [withLayout({ layout: 'column', classNames: 'w-[50rem]' }), withTheme()],
+  parameters: { layout: 'fullscreen' },
+  args: { scenario: 'assistant', count: 200, debug: false },
+};
+
+export default meta;
+
+type Story = StoryObj<FeedStoryProps>;
+
+const nextFrame = () => new Promise<number>((resolve) => requestAnimationFrame(resolve));
+
+/** Row re-placements one disclosure costs today: 177 over 19 frames, ~11 rows a frame. */
+// One toggle's animation: the rows after the panel move each frame (the browser reflows them — the
+// engine writes nothing), and with the tail followed, the glide moves the whole mounted window as
+// well while the growth is paid back to the end. The pre-glide pin was 260; with the glide the
+// travel itself moves every mounted row per frame, so the honest ceiling is the animation's length
+// times the window — a regression past this is a second mover, not a longer animation.
+const REPLACEMENT_CEILING = 400;
+
+const settle = async (frames = 30) => {
+  for (let frame = 0; frame < frames; frame++) {
+    await nextFrame();
+  }
+};
+
+/** Passive: toggle the panels by hand. */
+export const Default: Story = {
+  args: { scenario: 'assistant', count: 200, debug: false },
+};
+
+export const Reopened: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const viewport = canvas.getByTestId('feed.viewport');
+    await settle();
+
+    // The row is identified by its message, not its position: the point of the test is that the row
+    // is destroyed in between, so anything positional would be describing a different row.
+    const panel = canvas.getAllByTestId('feed.widget')[0];
+    const row = panel.closest('[data-object-id]') as HTMLElement;
+    const id = row.dataset.objectId!;
+    // The header is the toggle: `TogglePanel.Header` carries the click handler, and it is the first
+    // element inside the panel's content.
+    // Sampled across the toggle's animation: a row that grows re-places every row after it, and with
+    // rows positioned absolutely that re-placement is ours to do, per frame, for every row below.
+    const tops = () =>
+      new Map(
+        [...viewport.querySelectorAll<HTMLElement>('[data-index]')].map((element) => [
+          Number(element.dataset.index),
+          Math.round(element.getBoundingClientRect().top),
+        ]),
+      );
+
+    const trace: number[] = [];
+    let previous = tops();
+    (panel.querySelector('.cursor-pointer') as HTMLElement | null)?.click();
+    for (let frame = 0; frame < 40; frame++) {
+      await nextFrame();
+      const current = tops();
+      trace.push([...current].filter(([index, top]) => previous.has(index) && previous.get(index) !== top).length);
+      previous = current;
+    }
+
+    // Pinned, not aspired to: this is what absolute placement costs today, and it is the number the
+    // move to flow layout is meant to take to nearly zero. Rows are placed by transform, so every row
+    // below the one that grew is re-placed by us, on every frame of the animation. In normal flow the
+    // browser does it in the same frame for nothing. Kept as a ceiling so the cost cannot grow
+    // unnoticed before that change lands, and so the change has something to prove itself against.
+    const moves = trace.reduce((total, count) => total + count, 0);
+    await expect({ moves: moves <= REPLACEMENT_CEILING }).toEqual({ moves: true });
+    await settle();
+    await expect(panel.dataset.open).toEqual('true');
+
+    // Far enough that the row is unmounted, not merely off screen. The wheel event first: the feed
+    // follows its tail, and a scroll it cannot attribute to the reader is one it will undo.
+    viewport.dispatchEvent(new WheelEvent('wheel', { bubbles: true, deltaY: -100 }));
+    viewport.scrollTop = 0;
+    await settle();
+    await expect(viewport.querySelector(`[data-object-id="${id}"]`)).toBeNull();
+
+    viewport.scrollTop = viewport.scrollHeight;
+    await settle();
+    const reopened = viewport.querySelector(`[data-object-id="${id}"]`)?.querySelector('[data-testid="feed.widget"]');
+    await expect((reopened as HTMLElement | null)?.dataset.open).toEqual('true');
+  },
+};