@duro-app/ui 5.21.0 → 5.22.0

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
+}

package/src/index.native.ts

@@ -27,6 +27,11 @@ export {Text, type TextVariant, type TextColor} from './components/Text/Text'
 export {TextLink, type TextLinkVariant} from './components/TextLink/TextLink'
 export {Textarea, type TextareaVariant} from './components/Textarea/Textarea'
 
+// Text and layout
+export {CodeBlock, type CodeBlockProps} from './components/CodeBlock/CodeBlock'
+export {Prose} from './components/Prose/Prose'
+export {Toolbar, type ToolbarProps} from './components/Toolbar/Toolbar'
+
 // Form field wrappers (RN-safe — used by Input/Textarea/Checkbox)
 export {Field} from './components/Field/Field'
 export {InputGroup} from './components/InputGroup/InputGroup'
@@ -57,6 +62,8 @@ export {Tree} from './components/Tree/Tree'
 export {Select} from './components/Select/Select'
 export {Combobox} from './components/Combobox/Combobox'
 export {Listbox} from './components/Listbox/Listbox'
+// A FlatList with the web props; prepend keeps position.
+export {VirtualList, type VirtualListProps} from './components/VirtualList/VirtualList'
 // The platform's own scroll indicator: Scrollbar and Thumb draw nothing.
 export {ScrollArea} from './components/ScrollArea/ScrollArea'
 export type {ListboxAnchorProps, ListboxMaxHeight} from './components/Listbox/Listbox'