@dxos/react-ui-mosaic 0.9.1-staging.ee54ba693a → 0.11.0

package/src/components/Mosaic/VirtualStackPagination.stories.tsx

@@ -0,0 +1,423 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import React, { type FC, useCallback, useMemo, useRef, useState } from 'react';
+
+import { Database, DXN, Feed, Filter, Obj, Order, Query, Type } from '@dxos/echo';
+import { usePagination, useQuery } from '@dxos/echo-react';
+import { random } from '@dxos/random';
+import { type Client, useClient } from '@dxos/react-client';
+import { useSpaces } from '@dxos/react-client/echo';
+import { persistentClientServices, withClientProvider } from '@dxos/react-client/testing';
+import { Button, Card, Input, Panel, ScrollArea, Select, Toolbar } from '@dxos/react-ui';
+import { Dnd } from '@dxos/react-ui-dnd';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { Focus } from '../Focus';
+import { Mosaic } from './Mosaic';
+import { type MosaicTileProps } from './Tile';
+
+const PAGE_SIZE = 50;
+const MAX_WINDOW_SIZE = PAGE_SIZE * 10;
+
+//
+// In-memory story (no ECHO): windows a plain array to show `Mosaic.VirtualStack`'s `pagination`
+// prop needs only a `{ getNext, getPrevious }` shape.
+//
+
+/** Total size of the synthetic, in-memory data source. */
+const TOTAL_ITEMS = 5_000;
+
+type ListItem = { id: string; index: number };
+
+type Range = { skip: number; limit: number };
+
+/**
+ * Windows a plain in-memory array the same way `usePagination` windows a live query: a page
+ * size, a bounded max window, and getNext/getPrevious that grow the window until it hits
+ * `MAX_WINDOW_SIZE`, then slide it instead.
+ */
+const usePaginatedItems = (total: number) => {
+  const [range, setRange] = useState<Range>({ skip: 0, limit: PAGE_SIZE });
+  const pendingRef = useRef(false);
+
+  const items = useMemo<ListItem[]>(() => {
+    const count = Math.max(0, Math.min(range.limit, total - range.skip));
+    return Array.from({ length: count }, (_, i) => {
+      const index = range.skip + i;
+      return { id: String(index), index };
+    });
+  }, [range, total]);
+
+  const getNext = useCallback(() => {
+    if (pendingRef.current) {
+      return;
+    }
+    pendingRef.current = true;
+    queueMicrotask(() => {
+      pendingRef.current = false;
+    });
+    setRange((prev) => {
+      if (prev.skip + prev.limit >= total) {
+        return prev;
+      }
+      const nextLimit = prev.limit + PAGE_SIZE;
+      return nextLimit <= MAX_WINDOW_SIZE
+        ? { ...prev, limit: nextLimit }
+        : { limit: MAX_WINDOW_SIZE, skip: prev.skip + PAGE_SIZE };
+    });
+  }, [total]);
+
+  const getPrevious = useCallback(() => {
+    if (pendingRef.current) {
+      return;
+    }
+    pendingRef.current = true;
+    queueMicrotask(() => {
+      pendingRef.current = false;
+    });
+    setRange((prev) => (prev.skip === 0 ? prev : { ...prev, skip: Math.max(0, prev.skip - PAGE_SIZE) }));
+  }, []);
+
+  return { items, getNext, getPrevious, atHead: range.skip === 0 };
+};
+
+const ListItemTile: FC<MosaicTileProps<ListItem>> = ({ data, location, current }) => (
+  <Mosaic.Tile id={data.id} data={data} location={location} current={current} asChild>
+    <Focus.Item asChild>
+      <Card.Root>
+        <Card.Header>
+          <Card.Title>Item #{data.index}</Card.Title>
+        </Card.Header>
+      </Card.Root>
+    </Focus.Item>
+  </Mosaic.Tile>
+);
+
+const VirtualStackPaginationStory = () => {
+  const { items, getNext, getPrevious, atHead } = usePaginatedItems(TOTAL_ITEMS);
+  const pagination = useMemo(() => ({ getNext, getPrevious, atHead }), [getNext, getPrevious, atHead]);
+  const [viewport, setViewport] = useState<HTMLElement | null>(null);
+
+  const range = items.length > 0 ? `${items[0].index}–${items[items.length - 1].index}` : '–';
+
+  return (
+    <Dnd.Root>
+      <Panel.Root>
+        <Panel.Toolbar asChild>
+          <Toolbar.Root>
+            <div className='flex grow justify-center'>
+              Range {range} of {TOTAL_ITEMS} ({items.length} loaded) {atHead && '(at head)'}
+            </div>
+          </Toolbar.Root>
+        </Panel.Toolbar>
+        <Panel.Content asChild>
+          <Mosaic.Container asChild eventHandler={{ id: 'virtual-stack-pagination', canDrop: () => false }}>
+            <ScrollArea.Root orientation='vertical'>
+              <ScrollArea.Viewport ref={setViewport}>
+                <Mosaic.VirtualStack
+                  Tile={ListItemTile}
+                  items={items}
+                  draggable={false}
+                  getId={(item) => item.id}
+                  getScrollElement={() => viewport}
+                  estimateSize={() => 56}
+                  gap={4}
+                  pagination={pagination}
+                />
+              </ScrollArea.Viewport>
+            </ScrollArea.Root>
+          </Mosaic.Container>
+        </Panel.Content>
+      </Panel.Root>
+    </Dnd.Root>
+  );
+};
+
+//
+// Feed-backed story (live ECHO): end-to-end pagination over a feed, with runtime append and sort.
+//
+
+/** Items seeded into the feed on space creation. */
+const INITIAL_ITEMS = 100;
+/** Default value of the toolbar's "add" count input. */
+const DEFAULT_ADD_COUNT = 50;
+
+class CounterItem extends Type.makeObject<CounterItem>(DXN.make('com.example.type.counterItem', '0.1.0'))(
+  Schema.Struct({
+    index: Schema.Number,
+    word: Schema.String,
+  }),
+) {}
+
+/**
+ * Persistent, monotonically-advancing index used to number new items. Lives in the space db (not
+ * the feed) so item numbering continues correctly across reloads rather than restarting.
+ */
+class Counter extends Type.makeObject<Counter>(DXN.make('com.example.type.paginationCounter', '0.1.0'))(
+  Schema.Struct({
+    next: Schema.Number,
+  }),
+) {}
+
+type SortField = 'natural' | 'number' | 'word';
+type SortDirection = 'asc' | 'desc';
+
+const makeItems = (start: number, count: number): CounterItem[] =>
+  Array.from({ length: count }, (_, i) => Obj.make(CounterItem, { index: start + i, word: random.lorem.word() }));
+
+const appendItems = (db: Database.Database, feed: Feed.Feed, start: number, count: number): Promise<void> =>
+  Feed.append(feed, makeItems(start, count)).pipe(Effect.provide(Database.layer(db)), Effect.runPromise);
+
+const seedFeed = async (db: Database.Database): Promise<void> => {
+  db.add(Obj.make(Counter, { next: INITIAL_ITEMS }));
+  const feed = db.add(Feed.make({ name: 'counter-feed' }));
+  await appendItems(db, feed, 0, INITIAL_ITEMS);
+};
+
+/**
+ * Reuses the persisted identity/space/feed, creating and seeding them only on the first ever load.
+ * Runs after `client.initialize()`, by which point `client.spaces.get()` already reflects any
+ * persisted spaces (the space list awaits its initial update on open), so an existing space is
+ * reused rather than duplicated on reload.
+ */
+const initializeStory = async (client: Client): Promise<void> => {
+  if (!client.halo.identity.get()) {
+    await client.halo.createIdentity();
+  }
+  const space = client.spaces.get()[0] ?? (await client.spaces.create());
+  await space.waitUntilReady();
+  const feeds = await space.db.query(Filter.type(Feed.Feed)).run();
+  if (feeds.length === 0) {
+    await seedFeed(space.db);
+  } else {
+    // Feed exists but its `Counter` is missing (partial seed / older data): restore it from the
+    // feed's current length so numbering continues and the story isn't stuck without a counter.
+    const counters = await space.db.query(Filter.type(Counter)).run();
+    if (counters.length === 0) {
+      const existing = await space.db.query(Query.select(Filter.type(CounterItem)).from(feeds[0])).run();
+      space.db.add(Obj.make(Counter, { next: existing.length }));
+    }
+  }
+  // Flush so the `Counter` (a space-db object) is indexed and persisted; otherwise it survives in
+  // Automerge but the index-backed `useQuery(Filter.type(Counter))` can't find it after reload.
+  await space.db.flush({ indexes: true });
+};
+
+const orderFor = (field: SortField, direction: SortDirection) => {
+  switch (field) {
+    case 'number':
+      return Order.property<CounterItem>('index', direction);
+    case 'word':
+      return Order.property<CounterItem>('word', direction);
+    case 'natural':
+    default:
+      return Order.natural(direction);
+  }
+};
+
+const CounterItemTile: FC<MosaicTileProps<CounterItem>> = ({ data, location, current }) => (
+  <Mosaic.Tile id={data.id} data={data} location={location} current={current} asChild>
+    <Focus.Item asChild>
+      <Card.Root>
+        <Card.Header>
+          <Card.Title>
+            #{data.index} · {data.word}
+          </Card.Title>
+        </Card.Header>
+      </Card.Root>
+    </Focus.Item>
+  </Mosaic.Tile>
+);
+
+const FeedPaginationStory = () => {
+  const client = useClient();
+  const [space] = useSpaces();
+  const db = space?.db;
+  const [feed] = useQuery(db, Filter.type(Feed.Feed));
+  // Persisted item count / next index (the story is the feed's only writer), so the header shows a
+  // "loaded of total" figure and item numbering continues across reloads without a full-feed count.
+  const [counter] = useQuery(db, Filter.type(Counter));
+
+  const [addCount, setAddCount] = useState(DEFAULT_ADD_COUNT);
+  const [sortField, setSortField] = useState<SortField>('natural');
+  const [direction, setDirection] = useState<SortDirection>('desc');
+  const [viewport, setViewport] = useState<HTMLElement | null>(null);
+
+  // Both branches select `CounterItem` so `items` infers as `CounterItem[]`; the fallback (no feed
+  // yet) matches nothing until the query re-points once the feed loads. Re-pointing on a sort
+  // change resets to the first page.
+  const query = useMemo(
+    () =>
+      feed
+        ? Query.select(Filter.type(CounterItem)).from(feed).orderBy(orderFor(sortField, direction)).limit(PAGE_SIZE)
+        : Query.select(Filter.type(CounterItem)).limit(PAGE_SIZE),
+    [feed, sortField, direction],
+  );
+  const { items, getNext, getPrevious, hasMore, isLoading, atHead } = usePagination(db, query, {
+    maxWindowSize: MAX_WINDOW_SIZE,
+  });
+
+  const pagination = useMemo(() => ({ getNext, getPrevious, atHead }), [getNext, getPrevious, atHead]);
+
+  const handleAdd = useCallback(() => {
+    if (!db || !feed || !counter || addCount <= 0) {
+      return;
+    }
+    void appendItems(db, feed, counter.next, addCount);
+    Obj.update(counter, (counter) => {
+      counter.next += addCount;
+    });
+  }, [db, feed, counter, addCount]);
+
+  // Wipes the persisted identity/storage and reloads so the story boots a fresh seeded space.
+  const handleReset = useCallback(() => {
+    void client.reset().then(() => window.location.reload());
+  }, [client]);
+
+  if (!db || !feed || !counter) {
+    return <Loading data={{ db: !!db, feed: !!feed, counter: !!counter }} />;
+  }
+
+  const total = counter.next;
+
+  return (
+    <Dnd.Root>
+      <Panel.Root>
+        <Panel.Toolbar asChild>
+          <Toolbar.Root>
+            <div className='shrink-0' style={{ inlineSize: '6rem' }}>
+              <Input.Root>
+                <Input.TextInput
+                  type='number'
+                  min={1}
+                  value={addCount}
+                  onChange={(event) => setAddCount(event.target.valueAsNumber || 0)}
+                  classNames='w-full'
+                />
+              </Input.Root>
+            </div>
+            <Button onClick={handleAdd} classNames='shrink-0'>
+              Add
+            </Button>
+            <Button onClick={handleReset} classNames='shrink-0'>
+              Reset
+            </Button>
+            <Select.Root
+              value={sortField}
+              onValueChange={(value) => setSortField(value === 'number' || value === 'word' ? value : 'natural')}
+            >
+              <Toolbar.Button asChild>
+                <Select.TriggerButton classNames='shrink-0' />
+              </Toolbar.Button>
+              <Select.Portal>
+                <Select.Content>
+                  <Select.Viewport>
+                    <Select.Option value='natural'>Natural</Select.Option>
+                    <Select.Option value='number'>Number</Select.Option>
+                    <Select.Option value='word'>Word</Select.Option>
+                  </Select.Viewport>
+                  <Select.Arrow />
+                </Select.Content>
+              </Select.Portal>
+            </Select.Root>
+            <Select.Root value={direction} onValueChange={(value) => setDirection(value === 'asc' ? 'asc' : 'desc')}>
+              <Toolbar.Button asChild>
+                <Select.TriggerButton classNames='shrink-0' />
+              </Toolbar.Button>
+              <Select.Portal>
+                <Select.Content>
+                  <Select.Viewport>
+                    <Select.Option value='asc'>Ascending</Select.Option>
+                    <Select.Option value='desc'>Descending</Select.Option>
+                  </Select.Viewport>
+                  <Select.Arrow />
+                </Select.Content>
+              </Select.Portal>
+            </Select.Root>
+            <div className='grow text-end truncate whitespace-nowrap'>
+              {items.length} loaded of {total}
+              {!atHead && ' · detached'}
+              {isLoading && ' · loading…'}
+              {!hasMore && ' · end'}
+            </div>
+          </Toolbar.Root>
+        </Panel.Toolbar>
+        <Panel.Content asChild>
+          <Mosaic.Container asChild eventHandler={{ id: 'virtual-stack-feed-pagination', canDrop: () => false }}>
+            <ScrollArea.Root orientation='vertical'>
+              <ScrollArea.Viewport ref={setViewport}>
+                <Mosaic.VirtualStack
+                  Tile={CounterItemTile}
+                  items={items}
+                  draggable={false}
+                  getId={(item) => item.id}
+                  getScrollElement={() => viewport}
+                  estimateSize={() => 56}
+                  gap={4}
+                  pagination={pagination}
+                />
+              </ScrollArea.Viewport>
+            </ScrollArea.Root>
+          </Mosaic.Container>
+        </Panel.Content>
+      </Panel.Root>
+    </Dnd.Root>
+  );
+};
+
+const meta: Meta = {
+  title: 'ui/react-ui-mosaic/Stack/Pagination',
+  decorators: [withLayout({ layout: 'column' }), withTheme()],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+/**
+ * `Mosaic.VirtualStack`'s `pagination` prop over a plain in-memory array -- no ECHO query or
+ * `usePagination` involved. Scroll down to grow the window, then keep scrolling past
+ * `MAX_WINDOW_SIZE` to see it slide (evicting the newest items); scroll back up to slide it back
+ * toward the head without a visible jump.
+ */
+export const Default: Story = {
+  render: VirtualStackPaginationStory,
+};
+
+/**
+ * End-to-end pagination over a live ECHO feed: `usePagination` windows a feed seeded with 100
+ * items (each a number + a random word), rendered through `Mosaic.VirtualStack`'s `pagination`
+ * prop. Scroll to page toward older items (past `MAX_WINDOW_SIZE` to see the window slide). Use
+ * the toolbar to append more items (they appear live at the head), and to sort by
+ * natural/number/word in either direction.
+ */
+// Hoisted so `config` and `services` below share the same call — calling `persistentClientServices`
+// twice would spawn two independent dedicated workers/coordinators for the one story.
+const FEED_BACKED_CLIENT_SERVICES = persistentClientServices();
+
+export const FeedBacked: Story = {
+  render: FeedPaginationStory,
+  decorators: [
+    withClientProvider({
+      // Persist identity/storage across reloads, mirroring stories-assistant. DEDICATED_WORKER mode
+      // (not a bare createOpfsWorker) elects a single leader across tabs via navigator.locks so a
+      // second tab proxies through the first instead of racing it for the same OPFS file handle —
+      // see the failure-mode comment on OpfsWorker.run in @dxos/sql-sqlite. `onInitialized` reuses
+      // the persisted space/feed rather than creating fresh ones each load (hence no
+      // `createIdentity`/`createSpace` flags).
+      config: FEED_BACKED_CLIENT_SERVICES.config,
+      // `ClientProviderProps.services` wants a resolved value or a factory, not a bare promise.
+      services: () => FEED_BACKED_CLIENT_SERVICES.services,
+      types: [Feed.Feed, CounterItem, Counter],
+      onInitialized: initializeStory,
+    }),
+  ],
+};

package/src/components/Mosaic/index.ts

@@ -5,6 +5,5 @@
 export { styles as mosaicStyles } from './styles';
 
 export * from './extension';
-export * from './types';
 
 export * from './Mosaic';

package/src/hooks/index.ts

@@ -5,4 +5,5 @@
 export * from './useContainerDebug';
 export * from './useDefaultColumnEventHandler';
 export * from './useEventHandlerAdapter';
+export * from './useVirtualizerPagination';
 export * from './useVisibleItems';

package/src/hooks/useDefaultColumnEventHandler.ts

@@ -3,8 +3,8 @@
 //
 
 import { type Obj } from '@dxos/echo';
+import { type DndContainerHandler, type GetId } from '@dxos/react-ui-dnd';
 
-import { type GetId, type MosaicEventHandler } from '../components';
 import { useEventHandlerAdapter } from './useEventHandlerAdapter';
 
 /**
@@ -23,7 +23,7 @@ export const useDefaultColumnEventHandler = <TColumn extends Obj.Unknown = Obj.U
   id: string,
   model: DefaultColumnEventHandlerModel<TColumn>,
   items: TColumn[],
-): MosaicEventHandler<TColumn> =>
+): DndContainerHandler<TColumn> =>
   useEventHandlerAdapter<TColumn, TColumn>({
     id,
     items,

package/src/hooks/useEventHandlerAdapter.ts

@@ -6,12 +6,11 @@ import { useMemo } from 'react';
 
 import { type Obj } from '@dxos/echo';
 import { log } from '@dxos/log';
+import { type DndContainerHandler, type GetId } from '@dxos/react-ui-dnd';
 import { arrayMove } from '@dxos/util';
 
-import { type GetId, type MosaicEventHandler } from '../components';
-
 export type UseEventHandlerProps<TItem = any, TObject extends Obj.Unknown = Obj.Unknown> = Pick<
-  MosaicEventHandler<TItem>,
+  DndContainerHandler<TItem>,
   'id' | 'canDrop'
 > & {
   /**
@@ -53,8 +52,8 @@ export const useEventHandlerAdapter = <TItem = any, TObject extends Obj.Unknown
   make,
   onChange,
   ...props
-}: UseEventHandlerProps<TItem, TObject>): MosaicEventHandler<TItem> => {
-  return useMemo<MosaicEventHandler<TItem>>(
+}: UseEventHandlerProps<TItem, TObject>): DndContainerHandler<TItem> => {
+  return useMemo<DndContainerHandler<TItem>>(
     () => ({
       ...props,
       onTake: ({ source }, cb) => {

package/src/hooks/useVirtualizerPagination.test.tsx

@@ -0,0 +1,105 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Virtualizer } from '@tanstack/react-virtual';
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+
+import { type VirtualizerPaginationController, useVirtualizerPagination } from './useVirtualizerPagination';
+
+type Item = { id: string };
+
+const getId = (item: Item) => item.id;
+const makeItems = (ids: number[]): Item[] => ids.map((id) => ({ id: String(id) }));
+
+const ROW_HEIGHT = 60;
+const VIEWPORT_HEIGHT = 340;
+
+/**
+ * Minimal fake covering only the fields the hook actually reads off a real `Virtualizer` -- a
+ * genuine type-boundary mock; there's no typed alternative short of driving real DOM layout.
+ */
+const makeVirtualizer = (itemCount: number, lastVisibleIndex: number): Virtualizer<any, any> =>
+  ({
+    getVirtualItems: () => [{ index: lastVisibleIndex }],
+    measurementsCache: Array.from({ length: itemCount }, (_, i) => ({
+      start: i * ROW_HEIGHT,
+      end: i * ROW_HEIGHT + (ROW_HEIGHT - 4),
+    })),
+    scrollOffset: lastVisibleIndex * ROW_HEIGHT,
+    scrollElement: { clientHeight: VIEWPORT_HEIGHT },
+    getTotalSize: () => itemCount * ROW_HEIGHT,
+    scrollToOffset: vi.fn(),
+  }) as unknown as Virtualizer<any, any>;
+
+describe('useVirtualizerPagination', () => {
+  test('chains getNext across a page landing with no further onChange', async () => {
+    // Regression test: once the loaded window's tail is fully rendered and the scrollbar sits at
+    // its physical max, `@tanstack/react-virtual` stops calling `onChange` -- its `maybeNotify` only
+    // fires on `[isScrolling, startIndex, endIndex]` changes, and neither moves just because `items`
+    // did. A `getNext` chain (e.g. a mailbox window sliding once it hits its max size, appending a
+    // page while evicting an equal-sized one from the front) must keep going purely off the `items`
+    // prop changing -- with no further onChange -- or it stalls forever right where it landed.
+    let items = makeItems([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+    const getNext = vi.fn(() => {
+      items = makeItems([10, 11, 12, 13, 14, 15, 16, 17, 18, 19]);
+    });
+    const pagination: VirtualizerPaginationController = { getNext, atHead: true };
+
+    const { result, rerender } = renderHook(
+      (props: { items: Item[] }) => useVirtualizerPagination({ items: props.items, getId, pagination }),
+      { initialProps: { items } },
+    );
+
+    // The one onChange tanstack fires as the user scrolls to the loaded window's tail: near the
+    // bottom edge, last row visible, and tall enough (10 rows) to exceed the viewport so the
+    // hook's own `isScrollable` check passes.
+    act(() => {
+      result.current.onChange(makeVirtualizer(10, 9));
+    });
+    // `requestNext`'s own `getNext()` call is deferred to a microtask.
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(getNext).toHaveBeenCalledTimes(1);
+
+    // The data layer resolved and slid the window -- re-render with the new page, but WITHOUT any
+    // further onChange call (tanstack wouldn't fire one: the rendered range hasn't moved).
+    rerender({ items });
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    // The chain must continue on its own: the window is still the same size, so the same geometry
+    // is still "near the bottom" -- the layout effect's re-arm should have requested another page.
+    expect(getNext).toHaveBeenCalledTimes(2);
+  });
+
+  test('does not misclassify a mid-list item reordered to the head as an eviction', () => {
+    // Regression test: a conversation-grouped mailbox bumps an existing (already-loaded) thread to
+    // the head when a new reply lands during sync. A bare `findIndex` match on the new head's id
+    // used to be enough to classify this as an 'evicted' prefix -- reading the bumped item's old
+    // mid-list offset as "evicted" height and growing the leading spacer by a bogus amount that's
+    // never reversed, which is what produced the flashing/jumping during sync.
+    const items = makeItems([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+    const pagination: VirtualizerPaginationController = {};
+
+    const { result, rerender } = renderHook(
+      (props: { items: Item[] }) => useVirtualizerPagination({ items: props.items, getId, pagination }),
+      { initialProps: { items } },
+    );
+
+    act(() => {
+      result.current.onChange(makeVirtualizer(10, 4));
+    });
+    expect(result.current.leadingSpace).toBe(0);
+
+    // Item '5' (previously mid-list, at index 5) is bumped to the head; everything else keeps its
+    // prior relative order -- exactly the shape a conversation re-sort produces.
+    const reordered = [items[5], ...items.slice(0, 5), ...items.slice(6)];
+    rerender({ items: reordered });
+
+    expect(result.current.leadingSpace).toBe(0);
+  });
+});