@duro-app/ui 5.20.0 → 5.22.0

package/src/components/Textarea/grow.css.ts

@@ -0,0 +1,18 @@
+import {css} from 'react-strict-dom'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
+
+// Web only: native has no field-sizing or lh unit (see native.css.ts).
+export const growCss = css.create({
+  // The height follows the content (CSS field-sizing, or autoGrow.ts where
+  // it is missing); the rows attribute is the floor.
+  autoGrow: {
+    fieldSizing: 'content',
+    resize: 'none' as const,
+    overflowY: 'auto',
+  },
+  // `maxRows` lines of text plus the vertical padding and border (border-box).
+  maxRows: (rows: number) => ({
+    maxHeight: `calc(${rows}lh + ${spacing.sm} + ${spacing.sm} + ${borders.hairline} + ${borders.hairline})`,
+  }),
+})

package/src/components/Textarea/grow.native.ts

@@ -0,0 +1 @@
+export {nativeStyles as grow} from './native.css'

package/src/components/Textarea/grow.ts

@@ -0,0 +1 @@
+export {growCss as grow} from './grow.css'

package/src/components/Textarea/native.css.ts

@@ -0,0 +1,16 @@
+import {css} from 'react-strict-dom'
+import {FONT_SIZE_REM, LINE_HEIGHT, ROOT_FONT_PX, SPACING_PX} from '@duro-app/tokens/keys'
+
+// One row of text, in px: the Textarea's font size (fontSizeSm, rem) at the
+// root size, times the typography line height. Native has no `lh` unit.
+const ROW_PX = FONT_SIZE_REM.fontSizeSm * ROOT_FONT_PX * LINE_HEIGHT
+
+export const nativeStyles = css.create({
+  // A multiline field on native grows with its content on its own.
+  autoGrow: {},
+  // `maxRows` lines plus the vertical padding; a multiline field on native
+  // already grows with its content, so only the cap is needed.
+  maxRows: (rows: number) => ({
+    maxHeight: rows * ROW_PX + 2 * SPACING_PX.sm,
+  }),
+})

package/src/components/Textarea/useAutoGrowFallback.native.ts

@@ -0,0 +1,5 @@
+import type {GrowMode} from './autoGrow'
+import type {RefObject} from 'react'
+
+/** A multiline field on native already grows with its content. */
+export function useAutoGrowFallback(_ref: RefObject<unknown>, _mode: GrowMode) {}

package/src/components/Textarea/useAutoGrowFallback.ts

@@ -0,0 +1,35 @@
+import {useEffect, useLayoutEffect, type RefObject} from 'react'
+import {fitToContent, supportsFieldSizing} from './autoGrow'
+
+import type {GrowMode} from './autoGrow'
+
+/** Fields this hook gave an inline height, so turning autoGrow off can take it back. */
+const sized = new WeakSet<HTMLElement>()
+
+/**
+ * Where CSS field-sizing is missing, size the field to its content: after each
+ * render (first paint, controlled value changes) and on every `input` event, so
+ * an uncontrolled field grows as it is typed into.
+ */
+export function useAutoGrowFallback(ref: RefObject<HTMLTextAreaElement | null>, mode: GrowMode) {
+  useLayoutEffect(() => {
+    const el = ref.current
+    if (!el || supportsFieldSizing()) return
+    if (mode === 'content') {
+      fitToContent(el)
+      sized.add(el)
+    } else if (sized.delete(el)) {
+      el.style.height = ''
+    }
+  })
+  useEffect(() => {
+    const el = ref.current
+    if (mode !== 'content' || !el || supportsFieldSizing()) return
+    const onInput = () => {
+      fitToContent(el)
+      sized.add(el)
+    }
+    el.addEventListener('input', onInput)
+    return () => el.removeEventListener('input', onInput)
+  }, [ref, mode])
+}

package/src/components/Toolbar/Toolbar.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'A row of controls with one tab stop (the WAI-ARIA toolbar pattern): Tab enters at the last focused control, Left/Right move across every control inside — through attached ButtonGroups too — and Home/End jump to the ends. A Select or Menu trigger keeps its own keys, and a control whose popup is open keeps Left/Right.',
+    'A row of controls with one tab stop (the WAI-ARIA toolbar pattern): Tab enters at the last focused control, Left/Right move across every control inside — through attached ButtonGroups too — and Home/End jump to the ends. A Select or Menu trigger keeps its own keys, and a control whose popup is open keeps Left/Right. On native it is the same row of controls without the roving tab stop and arrow keys.',
   whenToUse: [
     'An editor toolbar: text style, format toggles, insert menus',
     'A dense set of related actions that should cost one Tab, not one per control',

package/src/components/Toolbar/Toolbar.native.tsx

@@ -0,0 +1,27 @@
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+import type {ToolbarProps} from './types'
+
+export type {ToolbarProps} from './types'
+
+/**
+ * Native Toolbar: a row (or column) of controls with the web's props. The
+ * roving tab stop and arrow keys are web only: a touch screen reaches every
+ * control directly, so each control keeps its own press target.
+ */
+export function Toolbar({
+  'aria-label': ariaLabel,
+  orientation = 'horizontal',
+  children,
+}: ToolbarProps) {
+  return (
+    <html.div
+      role="toolbar"
+      aria-label={ariaLabel}
+      aria-orientation={orientation}
+      style={[styles.root, orientation === 'vertical' && styles.vertical]}
+    >
+      {children}
+    </html.div>
+  )
+}

package/src/components/Toolbar/Toolbar.tsx

@@ -1,22 +1,11 @@
-import {type ReactNode, useCallback, useEffect, useMemo, useRef, useState} from 'react'
+import {useCallback, useEffect, useMemo, useRef, useState} from 'react'
 import {html} from 'react-strict-dom'
-import type {Orientation} from '../../shared/types'
 import {useOrderedRegistry} from '../../shared/useOrderedRegistry'
 import {ToolbarContext, type ToolbarContextValue} from './ToolbarContext'
 import {styles} from './styles.css'
+import type {ToolbarProps} from './types'
 
-export interface ToolbarProps {
-  /** Names the toolbar ("Formatting"). Required: a toolbar is a landmark-like widget. */
-  'aria-label': string
-  /**
-   * Arrow keys follow the orientation: Left/Right (default) or Up/Down. A
-   * vertical toolbar cannot hold a Select, whose closed trigger opens on
-   * ArrowDown/ArrowUp. A Menu can: its closed trigger handles no arrow key,
-   * so Up/Down move past it and Enter or Space opens it.
-   */
-  orientation?: Orientation
-  children: ReactNode
-}
+export type {ToolbarProps} from './types'
 
 /**
  * A row of controls with one tab stop (the WAI-ARIA toolbar pattern). Every

package/src/components/Toolbar/types.ts

@@ -0,0 +1,15 @@
+import type {ReactNode} from 'react'
+import type {Orientation} from '../../shared/types'
+
+export interface ToolbarProps {
+  /** Names the toolbar ("Formatting"). Required: a toolbar is a landmark-like widget. */
+  'aria-label': string
+  /**
+   * Arrow keys follow the orientation: Left/Right (default) or Up/Down. A
+   * vertical toolbar cannot hold a Select, whose closed trigger opens on
+   * ArrowDown/ArrowUp. A Menu can: its closed trigger handles no arrow key,
+   * so Up/Down move past it and Enter or Space opens it.
+   */
+  orientation?: Orientation
+  children: ReactNode
+}

package/src/components/VirtualList/VirtualList.meta.ts

@@ -2,10 +2,11 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'A windowed list on @tanstack/react-virtual: only the rows in view (plus overscan) are mounted, and rows are measured so they may differ in height. role="list" with listitem rows carrying aria-setsize and aria-posinset. anchor="end" opens at the last item and stays pinned to the bottom while new items arrive and the reader is at the bottom (a transcript, a log). It fills its parent, or stops at maxHeight. Web only: on native, host FlashList or Legend List behind your own .native.tsx leaf.',
+    'A windowed list on @tanstack/react-virtual: only the rows in view (plus overscan) are mounted, and rows are measured so they may differ in height. role="list" with listitem rows carrying aria-setsize and aria-posinset. anchor="end" opens at the last item and stays pinned to the bottom while new items arrive and the reader is at the bottom (a transcript, a log). It fills its parent, or stops at maxHeight. onStartReached fires once each time the reader scrolls to the start (load older history), and prepending items keeps the first visible row in place. On native it is a FlatList with the same props (role list; rows carry no listitem role, which React Native lacks) (maintainVisibleContentPosition for prepend).',
   whenToUse: [
     'Hundreds to tens of thousands of rows: sessions, a chat transcript, log lines',
     'A list that grows at the bottom while the reader follows it (anchor="end")',
+    'A transcript that pages older history in at the top (onStartReached, then prepend items)',
   ],
   whenNotToUse: [
     'Tabular data with columns and sorting — use VirtualTable',

package/src/components/VirtualList/VirtualList.native.tsx

@@ -0,0 +1,80 @@
+import {useCallback, useRef} from 'react'
+import {FlatList, type NativeScrollEvent, type NativeSyntheticEvent, StyleSheet} from 'react-native'
+import {html} from 'react-strict-dom'
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import {resolveLength} from '../../shared/length'
+import type {VirtualListProps} from './props'
+import {nativeStyles} from './native.css'
+
+/**
+ * Native VirtualList: a FlatList with the web component's props. Prepending
+ * keeps the first visible row in place (`maintainVisibleContentPosition`),
+ * `onStartReached` is FlatList's own, and `anchor="end"` follows new items
+ * while the reader is at the bottom. FlatList measures rows itself, so
+ * `estimateSize` and `overscan` are accepted for one API and not needed.
+ */
+
+export type {VirtualListProps}
+
+// React Native has no listitem accessibility role, so rows are not announced as
+// list items (the list itself is role list).
+// holds-until: the device checkpoint. Native prepend (maintainVisibleContentPosition)
+// and onStartReached are verified only on a device, not in CI; FlatList may fire
+// onStartReached on mount for a list shorter than the view.
+
+const BOTTOM_SLOP = SIZES_PX.touchTarget
+const MAINTAIN_POSITION = {minIndexForVisible: 0}
+
+export function VirtualList<T>({
+  items,
+  renderItem,
+  getKey,
+  anchor = 'start',
+  onStartReached,
+  maxHeight,
+  'aria-label': ariaLabel,
+}: VirtualListProps<T>) {
+  const listRef = useRef<FlatList<T>>(null)
+  const atBottom = useRef(true)
+
+  const onScroll = useCallback((e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const {contentOffset, contentSize, layoutMeasurement} = e.nativeEvent
+    atBottom.current =
+      contentSize.height - contentOffset.y - layoutMeasurement.height <= BOTTOM_SLOP
+  }, [])
+
+  const followEnd = useCallback(() => {
+    if (anchor === 'end' && atBottom.current) listRef.current?.scrollToEnd({animated: false})
+  }, [anchor])
+
+  return (
+    <html.div
+      style={[
+        nativeStyles.root,
+        maxHeight !== undefined && nativeStyles.rootMax(resolveLength(maxHeight)),
+      ]}
+    >
+      <FlatList
+        ref={listRef}
+        style={maxHeight === undefined ? layout.fill : layout.capped}
+        accessibilityLabel={ariaLabel}
+        accessibilityRole="list"
+        data={items as T[]}
+        keyExtractor={(item, index) => String(getKey(item, index))}
+        renderItem={({item, index}) => <>{renderItem(item, index)}</>}
+        maintainVisibleContentPosition={MAINTAIN_POSITION}
+        onStartReached={onStartReached ? () => onStartReached() : undefined}
+        onStartReachedThreshold={0.1}
+        onScroll={onScroll}
+        scrollEventThrottle={16}
+        onContentSizeChange={followEnd}
+      />
+    </html.div>
+  )
+}
+
+// Fill the parent unless capped; with a cap the list shrinks to its content.
+const layout = StyleSheet.create({
+  fill: {flexGrow: 1, flexShrink: 1},
+  capped: {flexGrow: 0, flexShrink: 1},
+})

package/src/components/VirtualList/VirtualList.stories.tsx

@@ -1,5 +1,7 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, waitFor} from 'storybook/test'
+import {useState} from 'react'
+import {html} from 'react-strict-dom'
+import {expect, fn, waitFor} from 'storybook/test'
 import type {SizeToken} from '@duro-app/tokens/keys'
 import {VirtualList} from './VirtualList'
 import {Text} from '../Text/Text'
@@ -93,3 +95,171 @@ export const AnchoredToTheEnd: Story = {
     await expect(last).toBeDefined()
   },
 }
+
+function firstVisible(list: HTMLElement) {
+  const top = list.getBoundingClientRect().top
+  const row = Array.from(list.querySelectorAll<HTMLElement>('[role="listitem"]')).find(
+    (r) => r.getBoundingClientRect().bottom > top,
+  )
+  if (!row) throw new Error('no visible row')
+  return {text: row.textContent, offset: row.getBoundingClientRect().top - top}
+}
+
+const HISTORY = Array.from({length: 200}, (_, i) => ({id: i, text: `Message ${i + 1}`}))
+
+function Pager({onStart}: {onStart?: () => void}) {
+  const [items, setItems] = useState(HISTORY.slice(100))
+  return (
+    <>
+      <html.button
+        type="button"
+        onClick={() => setItems((prev) => [...HISTORY.slice(prev[0].id - 20, prev[0].id), ...prev])}
+      >
+        Load older
+      </html.button>
+      <VirtualList
+        aria-label="Transcript"
+        items={items}
+        getKey={(m) => m.id}
+        estimateSize="controlLg"
+        maxHeight="previewMaxH"
+        onStartReached={onStart}
+        renderItem={(m) => <Text>{m.text}</Text>}
+      />
+    </>
+  )
+}
+
+export const PrependKeepsPosition: Story = {
+  render: () => <Pager />,
+  play: async ({canvas, userEvent}) => {
+    const list = canvas.getByRole('list', {name: 'Transcript'})
+    await waitFor(() => expect(canvas.getAllByRole('listitem').length).toBeGreaterThan(0))
+    list.scrollTop = 600
+    // scrolled and re-rendered: the first visible row is no longer the first item
+    await waitFor(() => {
+      expect(list.scrollTop).toBe(600)
+      expect(firstVisible(list).text).not.toBe('Message 101')
+    })
+    const before = firstVisible(list)
+    await userEvent.click(canvas.getByRole('button', {name: 'Load older'}))
+    await waitFor(() =>
+      expect(canvas.getAllByRole('listitem')[0]).toHaveAttribute('aria-setsize', '120'),
+    )
+    await waitFor(() => {
+      const after = firstVisible(list)
+      expect(after.text).toBe(before.text)
+      expect(Math.abs(after.offset - before.offset)).toBeLessThan(2)
+    })
+  },
+}
+
+export const StartReachedFiresOncePerApproach: StoryObj<{onStartReached: () => void}> = {
+  args: {onStartReached: fn()},
+  render: (args) => <Pager onStart={args.onStartReached} />,
+  play: async ({canvas, args}) => {
+    const onStart = args.onStartReached
+    const list = canvas.getByRole('list', {name: 'Transcript'})
+    await waitFor(() => expect(canvas.getAllByRole('listitem').length).toBeGreaterThan(0))
+    const scrollTo = async (top: number) => {
+      list.scrollTop = top
+      await waitFor(() => expect(list.scrollTop).toBe(top))
+      // The scroll listener reads rows once per animation frame, so two scrollTop
+      // writes in one frame would lose the first offset: wait two frames.
+      await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)))
+    }
+    await scrollTo(600)
+    await expect(onStart).not.toHaveBeenCalled()
+    await scrollTo(0)
+    await waitFor(() => expect(onStart).toHaveBeenCalledTimes(1))
+    await scrollTo(1)
+    await expect(onStart).toHaveBeenCalledTimes(1)
+    await scrollTo(600)
+    await scrollTo(0)
+    await waitFor(() => expect(onStart).toHaveBeenCalledTimes(2))
+  },
+}
+
+/** A list too short to scroll asks for older history at once, since no scroll can reach its start. */
+export const ShortListAsksForMore: StoryObj<{onStartReached: () => void}> = {
+  tags: ['!dev', '!autodocs'],
+  args: {onStartReached: fn()},
+  render: (args) => (
+    <VirtualList
+      aria-label="Transcript"
+      items={HISTORY.slice(0, 2)}
+      getKey={(m) => m.id}
+      estimateSize="controlLg"
+      maxHeight="previewMaxH"
+      onStartReached={args.onStartReached}
+      renderItem={(m) => <Text>{m.text}</Text>}
+    />
+  ),
+  play: async ({canvas, args}) => {
+    await waitFor(() => expect(canvas.getAllByRole('listitem').length).toBe(2))
+    await waitFor(() => expect(args.onStartReached).toHaveBeenCalledTimes(1))
+  },
+}
+
+function ShortPager({onStart}: {onStart: () => void}) {
+  const [from, setFrom] = useState(198)
+  return (
+    <VirtualList
+      aria-label="Transcript"
+      items={HISTORY.slice(from)}
+      getKey={(m) => m.id}
+      estimateSize="controlLg"
+      maxHeight="previewMaxH"
+      onStartReached={() => {
+        onStart()
+        setFrom((f) => Math.max(f - 1, 196))
+      }}
+      renderItem={(m) => <Text>{m.text}</Text>}
+    />
+  )
+}
+
+/** A prepend that leaves the list short asks again; when no more comes, it stops. */
+export const ShortListKeepsAskingUntilNoMore: StoryObj<{onStartReached: () => void}> = {
+  tags: ['!dev', '!autodocs'],
+  args: {onStartReached: fn()},
+  render: (args) => <ShortPager onStart={args.onStartReached} />,
+  play: async ({canvas, args}) => {
+    // 2 items, then 3, then 4 (the last prepend): one call for each, then no more
+    await waitFor(() => expect(canvas.getAllByRole('listitem').length).toBe(4))
+    await waitFor(() => expect(args.onStartReached).toHaveBeenCalledTimes(3))
+    await new Promise((resolve) => setTimeout(resolve, 200))
+    await expect(args.onStartReached).toHaveBeenCalledTimes(3)
+  },
+}
+
+function FreshArray({onStart}: {onStart: () => void}) {
+  const [calls, setCalls] = useState(0)
+  return (
+    <VirtualList
+      aria-label={`Transcript ${calls}`}
+      // a new array on every render, with the same content
+      items={HISTORY.slice(0, 2)}
+      getKey={(m) => m.id}
+      estimateSize="controlLg"
+      maxHeight="previewMaxH"
+      onStartReached={() => {
+        onStart()
+        setCalls((c) => c + 1)
+      }}
+      renderItem={(m) => <Text>{m.text}</Text>}
+    />
+  )
+}
+
+/** A new array with the same content does not ask again, even when the call re-renders. */
+export const ShortListDoesNotLoopOnFreshArrays: StoryObj<{onStartReached: () => void}> = {
+  tags: ['!dev', '!autodocs'],
+  args: {onStartReached: fn()},
+  render: (args) => <FreshArray onStart={args.onStartReached} />,
+  play: async ({canvas, args}) => {
+    await waitFor(() => expect(canvas.getByRole('list', {name: 'Transcript 1'})).toBeVisible())
+    await new Promise((resolve) => setTimeout(resolve, 200))
+    await expect(args.onStartReached).toHaveBeenCalledTimes(1)
+  },
+}

package/src/components/VirtualList/VirtualList.tsx

@@ -1,41 +1,29 @@
-import {type ReactNode, useEffect, useLayoutEffect, useRef} from 'react'
+import {useCallback, useEffect, useLayoutEffect, useRef} from 'react'
 import {html} from 'react-strict-dom'
 import {useVirtualizer} from '@tanstack/react-virtual'
-import {SIZES_PX, type SizeToken} from '@duro-app/tokens/keys'
-import {resolveLength, type Length} from '../../shared/length'
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import {resolveLength} from '../../shared/length'
 import {styles} from './styles.css'
+import type {VirtualListProps} from './props'
 
-export interface VirtualListProps<T> {
-  items: readonly T[]
-  /** Each row's starting height estimate, a size token; rows are then measured. */
-  estimateSize: SizeToken
-  renderItem: (item: T, index: number) => ReactNode
-  /** A stable key per item (an id), so rows keep their measurement as items change. */
-  getKey: (item: T, index: number) => string | number
-  /** Rows rendered beyond each edge of the view. Default 5 */
-  overscan?: number
-  /**
-   * `end` starts at the last item and stays pinned to the bottom while new
-   * items arrive, as long as the reader is at the bottom (a transcript, a log).
-   * Default `start`.
-   */
-  anchor?: 'start' | 'end'
-  /** Cap the list's height; without it, it fills its parent. */
-  maxHeight?: Length
-  /** The list's accessible name. */
-  'aria-label': string
-}
+export type {VirtualListProps}
 
 /** Within this many px of the end counts as "at the bottom" for `anchor="end"`. */
 const BOTTOM_SLOP = SIZES_PX.touchTarget
+/** Frames a prepend keeps re-pinning its anchor row while new rows are measured. */
+// holds-until: a prepend whose rows take more than 6 frames to measure (images,
+// late fonts, mermaid) and visibly jumps; then settle on a ResizeObserver instead.
+const PIN_FRAMES = 6
+/** Within this many px of the start counts as "reached" for `onStartReached`. */
+const START_SLOP = SIZES_PX.touchTarget
 
 /**
  * A windowed list: only the rows in view (plus `overscan`) are mounted, so a
  * list of tens of thousands stays fast. Rows are measured as they render, so
  * they may differ in height. It is a `role="list"`; each row is a listitem
  * with `aria-setsize` and `aria-posinset`, so assistive tech knows the full
- * length while most rows are not in the DOM. Web only: on native, host
- * FlashList or Legend List behind your own `.native.tsx` leaf.
+ * length while most rows are not in the DOM. On native it is
+ * a FlatList with the same props.
  */
 export function VirtualList<T>({
   items,
@@ -44,6 +32,7 @@ export function VirtualList<T>({
   getKey,
   overscan = 5,
   anchor = 'start',
+  onStartReached,
   maxHeight,
   'aria-label': ariaLabel,
 }: VirtualListProps<T>) {
@@ -57,16 +46,116 @@ export function VirtualList<T>({
   })
 
   // `end`: open at the last item, and follow new items while at the bottom.
+  // `onStartReached`: fire once per approach to the start, re-arming when the
+  // reader moves away (a prepend that moves the start away re-arms it too).
   const atBottom = useRef(true)
+  const startArmed = useRef(true)
+  const startCallback = useRef(onStartReached)
+  startCallback.current = onStartReached
+  // The items a short list last asked more for: a new array with the same
+  // first key and length is the same content, so it does not ask again.
+  const askedFor = useRef<string | undefined>(undefined)
   useEffect(() => {
     const el = scrollRef.current
-    if (!el || anchor !== 'end') return
+    if (!el) return
     const onScroll = () => {
       atBottom.current = el.scrollHeight - el.scrollTop - el.clientHeight <= BOTTOM_SLOP
+      if (el.scrollTop > START_SLOP) {
+        startArmed.current = true
+      } else if (startArmed.current) {
+        startArmed.current = false
+        startCallback.current?.()
+      }
     }
     el.addEventListener('scroll', onScroll, {passive: true})
     return () => el.removeEventListener('scroll', onScroll)
-  }, [anchor])
+  }, [])
+
+  // Prepend: the rows above are new and only estimated until measured, so
+  // pin the first visible row (by key, read from the DOM while the list is
+  // still as the reader last saw it) at its on-screen offset, and repeat for a
+  // few frames while the new rows settle to their real heights.
+  const firstKey = useRef<string | number | undefined>(undefined)
+  const seenRow = useRef<{key: string | number; offset: number} | null>(null)
+  const itemsRef = useRef(items)
+  // Latest getKey, so the effects below need not re-run when its identity changes.
+  const getKeyRef = useRef(getKey)
+  getKeyRef.current = getKey
+  const readSeenRow = useCallback(() => {
+    const el = scrollRef.current
+    if (!el) return
+    const top = el.getBoundingClientRect().top
+    for (const row of el.querySelectorAll<HTMLElement>('[role="listitem"]')) {
+      const rect = row.getBoundingClientRect()
+      const index = Number(row.dataset.index)
+      const item = itemsRef.current[index]
+      if (rect.bottom > top && item !== undefined) {
+        seenRow.current = {key: getKeyRef.current(item, index), offset: rect.top - top}
+        return
+      }
+    }
+  }, [])
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+    // Coalesce: at most one read per frame, however many scroll events fire.
+    let frame = 0
+    const onScroll = () => {
+      if (frame) return
+      frame = requestAnimationFrame(() => {
+        frame = 0
+        readSeenRow()
+      })
+    }
+    el.addEventListener('scroll', onScroll, {passive: true})
+    return () => {
+      el.removeEventListener('scroll', onScroll)
+      if (frame) cancelAnimationFrame(frame)
+    }
+  }, [readSeenRow])
+  useLayoutEffect(() => {
+    const el = scrollRef.current
+    const previous = firstKey.current
+    firstKey.current = items.length > 0 ? getKeyRef.current(items[0], 0) : undefined
+    itemsRef.current = items
+    // A list too short to scroll cannot be scrolled to its start: ask for more
+    // now, once per distinct content, until it fills.
+    const content = `${String(firstKey.current)}:${items.length}`
+    if (
+      el &&
+      items.length > 0 &&
+      el.scrollHeight <= el.clientHeight &&
+      askedFor.current !== content
+    ) {
+      askedFor.current = content
+      startCallback.current?.()
+    }
+    const kept = seenRow.current
+    let settleFrame = 0
+    if (el && kept && previous !== undefined && previous !== firstKey.current) {
+      const at = items.findIndex((item, i) => getKeyRef.current(item, i) === kept.key)
+      if (at >= 0) {
+        const pin = () => {
+          const start = virtualizer.measurementsCache[at]?.start
+          if (start !== undefined) el.scrollTop = start - kept.offset
+        }
+        pin()
+        if (el.scrollTop > START_SLOP) startArmed.current = true
+        let frames = 0
+        const settle = () => {
+          pin()
+          if (frames++ < PIN_FRAMES) settleFrame = requestAnimationFrame(settle)
+          else readSeenRow()
+        }
+        settleFrame = requestAnimationFrame(settle)
+        // A later prepend (or unmount) stops this loop, so it cannot re-pin a stale row.
+        return () => cancelAnimationFrame(settleFrame)
+      }
+    }
+    readSeenRow()
+    // Runs when `items` changes; scrolling is read by the frame-coalesced listener.
+  }, [items, readSeenRow, virtualizer])
+
   useLayoutEffect(() => {
     if (anchor !== 'end' || items.length === 0 || !atBottom.current) return
     virtualizer.scrollToIndex(items.length - 1, {align: 'end'})

package/src/components/VirtualList/native.css.ts

@@ -0,0 +1,14 @@
+import {css} from 'react-strict-dom'
+
+/** The native list sits in a view that fills its parent or stops at a cap. */
+export const nativeStyles = css.create({
+  root: {
+    width: '100%',
+    height: '100%',
+    minHeight: 0,
+  },
+  rootMax: (maxHeight: number | string) => ({
+    height: 'auto',
+    maxHeight,
+  }),
+})

package/src/components/VirtualList/props.ts

@@ -0,0 +1,31 @@
+import type {ReactNode} from 'react'
+import type {SizeToken} from '@duro-app/tokens/keys'
+import type {Length} from '../../shared/length'
+
+export interface VirtualListProps<T> {
+  items: readonly T[]
+  /** Each row's starting height estimate, a size token; rows are then measured. */
+  estimateSize: SizeToken
+  renderItem: (item: T, index: number) => ReactNode
+  /** A stable key per item (an id), so rows keep their measurement as items change. */
+  getKey: (item: T, index: number) => string | number
+  /** Rows rendered beyond each edge of the view. Default 5 */
+  overscan?: number
+  /**
+   * `end` starts at the last item and stays pinned to the bottom while new
+   * items arrive, as long as the reader is at the bottom (a transcript, a log).
+   * Default `start`.
+   */
+  anchor?: 'start' | 'end'
+  /**
+   * Called once each time the reader scrolls to within 44px (touchTarget) of the
+   * start (load older history). It fires again only after they move away.
+   * A list too short to scroll calls it once for each new first item or length, until it fills.
+   * Prepending items keeps the first visible row where it was on screen.
+   */
+  onStartReached?: () => void
+  /** Cap the list's height; without it, it fills its parent. */
+  maxHeight?: Length
+  /** The list's accessible name. */
+  'aria-label': string
+}