@dxos/react-ui-feed 0.11.1

package/src/components/Block/widget-state.tsx

@@ -0,0 +1,75 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type PropsWithChildren, createContext, useCallback, useContext, useMemo, useState } from 'react';
+
+/**
+ * State a widget keeps that must outlive the row it is drawn in.
+ *
+ * A virtualized feed destroys a row when it leaves the window, and React state inside a widget dies
+ * with it — so a reader who expands a tool panel, scrolls away and comes back finds it shut. In a
+ * thread that is one long document the question never arises, because nothing ever unmounts; it is
+ * the cost of virtualization, and it has to be paid somewhere above the row.
+ *
+ * Here, in a map owned by `MessageList.Root`. Not in the message, because whether a panel is open is
+ * the reader's business and not part of what was said.
+ */
+export type WidgetStateStore = {
+  read: (key: string) => unknown;
+  write: (key: string, value: unknown) => void;
+};
+
+const WidgetStateContext = createContext<WidgetStateStore | undefined>(undefined);
+
+/** Scopes a widget's key to its message, so two messages' widgets cannot collide. */
+const WidgetScopeContext = createContext<string>('');
+
+export const WidgetStateProvider = ({ store, children }: PropsWithChildren<{ store: WidgetStateStore }>) => (
+  <WidgetStateContext.Provider value={store}>{children}</WidgetStateContext.Provider>
+);
+
+export const WidgetScopeProvider = ({ scope, children }: PropsWithChildren<{ scope: string }>) => (
+  <WidgetScopeContext.Provider value={scope}>{children}</WidgetScopeContext.Provider>
+);
+
+/** Creates the store a feed's widgets share. One per `MessageList.Root`. */
+export const createWidgetStateStore = (): WidgetStateStore => {
+  const values = new Map<string, unknown>();
+  return {
+    read: (key) => values.get(key),
+    write: (key, value) => {
+      values.set(key, value);
+    },
+  };
+};
+
+/**
+ * `useState` for a widget, keyed so it survives the row being destroyed and rebuilt.
+ *
+ * The key must identify the widget within its message — its tag and position in the document, say —
+ * and is scoped to the message automatically. Outside a feed this degrades to plain `useState`, so a
+ * widget can still be rendered on its own.
+ */
+export const useWidgetState = <T,>(key: string, initial: T): [T, (value: T) => void] => {
+  const store = useContext(WidgetStateContext);
+  const scope = useContext(WidgetScopeContext);
+  const scoped = useMemo(() => `${scope}:${key}`, [scope, key]);
+
+  // Seeded from the store on mount, which is the whole point: a remounted widget starts from what
+  // the reader last left it at rather than from the default.
+  const [value, setValue] = useState<T>(() => {
+    const stored = store?.read(scoped);
+    return (stored === undefined ? initial : stored) as T;
+  });
+
+  const set = useCallback(
+    (next: T) => {
+      store?.write(scoped, next);
+      setValue(next);
+    },
+    [store, scoped],
+  );
+
+  return [value, set];
+};

package/src/components/MessageList/MessageList.stories.tsx

@@ -0,0 +1,111 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { FeedStory, type FeedStoryProps } from '../../testing';
+
+const meta: Meta<FeedStoryProps> = {
+  title: 'ui/react-ui-feed/components/MessageList',
+  render: FeedStory,
+  decorators: [withLayout({ layout: 'column', classNames: 'w-[50rem]' }), withTheme()],
+  parameters: { layout: 'fullscreen' },
+  args: {
+    count: 100,
+    scrollPastEnd: true,
+  },
+  argTypes: {
+    debug: { control: 'boolean' },
+    scrollPastEnd: { control: 'boolean' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<FeedStoryProps>;
+
+//
+// Size and stress variants of the one realistic feed. Everything here renders the assistant
+// scenario — real chat turns, per-message chrome, block widgets — because a size story over
+// synthetic filler answers questions about the filler. The call-site sims (email, thread,
+// comments, transcript) were dropped by decision; the flagship (`assistant/*`) is the use case.
+//
+
+/** Passive: the assistant-shaped feed under the shared harness. */
+export const Default: Story = {
+  args: { scenario: 'assistant', count: 200 },
+};
+
+export const Small: Story = {
+  args: {
+    scenario: 'assistant',
+    count: 20,
+  },
+};
+
+export const Medium: Story = {
+  args: {
+    scenario: 'assistant',
+    count: 100,
+  },
+};
+
+/**
+ * Scroll-quality case: the deciding criterion is smoothness here, not at 200.
+ *
+ * The statusbar's right-hand readout is `fps · worst frame · hitches`, sampled from animation
+ * frames and reset by clicking it. It has to be read at a real keyboard — an agent's browser
+ * throttles `requestAnimationFrame`, so any number collected there describes the harness.
+ *
+ * Test:
+ * 1. Click the frame readout to reset it, then fling-scroll the list from top to bottom twice.
+ * 2. Read `fps` while the scroll is running: it should hold near the display's rate.
+ * 3. Read `worst` and `hitches` after it settles — one 200ms stall reads as smooth in an average
+ *    and as broken to a reader, which is why they are reported separately.
+ * 4. Watch the scrollbar thumb during the fling: it should not jump backwards as rows measure.
+ */
+export const Large: Story = {
+  args: {
+    scenario: 'assistant',
+    count: 2_000,
+  },
+};
+
+/**
+ * A bad height estimate is what scrollbar drift looks like; compare against `Large`.
+ *
+ * Test:
+ * 1. Reset the frame readout and fling-scroll to the middle of the list.
+ * 2. Compare `worst` and `hitches` against `Large` — the cost of measurement correction is the
+ *    difference between the two stories, since nothing else changes.
+ * 3. Hold at one position for a second: the rows must not creep once measurement catches up.
+ */
+export const BadEstimate: Story = {
+  args: {
+    scenario: 'assistant',
+    count: 2_000,
+    estimateSize: 24,
+  },
+};
+
+/**
+ * A model answering into the tail, from nothing, until stopped. The answer arrives in word chunks
+ * and re-parses as markdown (heading, list, code fence) while the row it lives in grows.
+ *
+ * Test:
+ * 1. Reset the frame readout and let three or four turns arrive.
+ * 2. Read `fps` while the tail grows — the follow runs on animation frames, so it competes with
+ *    the item re-parsing its markdown, and this is where they collide.
+ * 3. Scroll away mid-answer: the follow must stop and stay stopped.
+ * 4. Scroll back to the tail: it must resume following without a jump.
+ */
+export const Streaming: Story = {
+  args: {
+    scenario: 'assistant',
+    count: 0,
+    streaming: true,
+  },
+};