@duro-app/ui 5.25.0 → 5.27.0

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

@@ -2,7 +2,7 @@ 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. 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). The scroll region is a tab stop with a focus ring, so the keyboard can scroll rows that hold no control.',
+    '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). The scroll region is a tab stop with a focus ring, so the keyboard can scroll rows that hold no control. onEndReached mirrors onStartReached at the end (load newer items in a window opened on an older point); scrollToKey centres one item each time it changes to a key in the list (a link to one message), and anchor="end" stops following the end while it applies.',
   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")',

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

@@ -1,4 +1,4 @@
-import {useCallback, useRef} from 'react'
+import {useCallback, useEffect, 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'
@@ -31,6 +31,8 @@ export function VirtualList<T>({
   getKey,
   anchor = 'start',
   onStartReached,
+  onEndReached,
+  scrollToKey,
   maxHeight,
   'aria-label': ariaLabel,
 }: VirtualListProps<T>) {
@@ -43,6 +45,18 @@ export function VirtualList<T>({
       contentSize.height - contentOffset.y - layoutMeasurement.height <= BOTTOM_SLOP
   }, [])
 
+  // `scrollToKey`: centre that item once per key, as soon as the items hold it.
+  const scrolledTo = useRef<string | number | null | undefined>(undefined)
+  useEffect(() => {
+    if (scrollToKey === null || scrollToKey === undefined || scrolledTo.current === scrollToKey)
+      return
+    const at = items.findIndex((item, i) => getKey(item, i) === scrollToKey)
+    if (at < 0) return
+    scrolledTo.current = scrollToKey
+    atBottom.current = false
+    listRef.current?.scrollToIndex({index: at, viewPosition: 0.5, animated: false})
+  }, [getKey, items, scrollToKey])
+
   const followEnd = useCallback(() => {
     if (anchor === 'end' && atBottom.current) listRef.current?.scrollToEnd({animated: false})
   }, [anchor])
@@ -65,6 +79,15 @@ export function VirtualList<T>({
         maintainVisibleContentPosition={MAINTAIN_POSITION}
         onStartReached={onStartReached ? () => onStartReached() : undefined}
         onStartReachedThreshold={0.1}
+        onEndReached={onEndReached ? () => onEndReached() : undefined}
+        onEndReachedThreshold={0.1}
+        // A row not measured yet: jump near it by estimate, then centre it once laid out.
+        onScrollToIndexFailed={({index, averageItemLength}) => {
+          listRef.current?.scrollToOffset({offset: index * averageItemLength, animated: false})
+          requestAnimationFrame(() =>
+            listRef.current?.scrollToIndex({index, viewPosition: 0.5, animated: false}),
+          )
+        }}
         onScroll={onScroll}
         scrollEventThrottle={16}
         onContentSizeChange={followEnd}

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

@@ -263,3 +263,65 @@ export const ShortListDoesNotLoopOnFreshArrays: StoryObj<{onStartReached: () =>
     await expect(args.onStartReached).toHaveBeenCalledTimes(1)
   },
 }
+
+/** A link to one message: the list opens anchored to the end, then centres that message. */
+function JumpTo({target}: {target: number | null}) {
+  return (
+    <VirtualList
+      aria-label="Transcript"
+      items={ITEMS}
+      getKey={(m) => m.id}
+      estimateSize="controlLg"
+      anchor="end"
+      scrollToKey={target}
+      maxHeight="previewMaxH"
+      renderItem={(m) => <Text>{m.text}</Text>}
+    />
+  )
+}
+
+export const ScrollToKeyCentresTheItem: Story = {
+  render: () => <JumpTo target={4_200} />,
+  play: async ({canvas}) => {
+    const list = canvas.getByRole('list', {name: 'Transcript'})
+    const row = await waitFor(() => canvas.getByText('Message 4201'))
+    const listBox = list.getBoundingClientRect()
+    const rowBox = row.getBoundingClientRect()
+    await expect(rowBox.top).toBeGreaterThanOrEqual(listBox.top)
+    await expect(rowBox.bottom).toBeLessThanOrEqual(listBox.bottom)
+    // It stays there: anchor="end" does not pull it back to the last message.
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)))
+    await expect(canvas.queryByText('Message 10000')).toBeNull()
+  },
+}
+
+export const EndReachedFiresOncePerApproach: StoryObj<{onEndReached: () => void}> = {
+  args: {onEndReached: fn()},
+  render: (args) => (
+    <VirtualList
+      aria-label="Transcript"
+      items={ITEMS.slice(0, 200)}
+      getKey={(m) => m.id}
+      estimateSize="controlLg"
+      onEndReached={args.onEndReached}
+      maxHeight="previewMaxH"
+      renderItem={(m) => <Text>{m.text}</Text>}
+    />
+  ),
+  play: async ({canvas, args}) => {
+    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 new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)))
+    }
+    await expect(args.onEndReached).not.toHaveBeenCalled()
+    await scrollTo(list.scrollHeight)
+    await waitFor(() => expect(args.onEndReached).toHaveBeenCalledTimes(1))
+    await scrollTo(list.scrollHeight)
+    await expect(args.onEndReached).toHaveBeenCalledTimes(1)
+    await scrollTo(0)
+    await scrollTo(list.scrollHeight)
+    await waitFor(() => expect(args.onEndReached).toHaveBeenCalledTimes(2))
+  },
+}

package/src/components/VirtualList/VirtualList.tsx

@@ -33,6 +33,8 @@ export function VirtualList<T>({
   overscan = 5,
   anchor = 'start',
   onStartReached,
+  onEndReached,
+  scrollToKey,
   maxHeight,
   'aria-label': ariaLabel,
 }: VirtualListProps<T>) {
@@ -52,6 +54,9 @@ export function VirtualList<T>({
   const startArmed = useRef(true)
   const startCallback = useRef(onStartReached)
   startCallback.current = onStartReached
+  const endArmed = useRef(true)
+  const endCallback = useRef(onEndReached)
+  endCallback.current = onEndReached
   // 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)
@@ -60,6 +65,12 @@ export function VirtualList<T>({
     if (!el) return
     const onScroll = () => {
       atBottom.current = el.scrollHeight - el.scrollTop - el.clientHeight <= BOTTOM_SLOP
+      if (!atBottom.current) {
+        endArmed.current = true
+      } else if (endArmed.current && el.scrollHeight > el.clientHeight) {
+        endArmed.current = false
+        endCallback.current?.()
+      }
       if (el.scrollTop > START_SLOP) {
         startArmed.current = true
       } else if (startArmed.current) {
@@ -156,6 +167,18 @@ export function VirtualList<T>({
     // Runs when `items` changes; scrolling is read by the frame-coalesced listener.
   }, [items, readSeenRow, virtualizer])
 
+  // `scrollToKey`: centre that item once per key, as soon as the items hold it.
+  const scrolledTo = useRef<string | number | null | undefined>(undefined)
+  useLayoutEffect(() => {
+    if (scrollToKey === null || scrollToKey === undefined || scrolledTo.current === scrollToKey)
+      return
+    const at = items.findIndex((item, i) => getKeyRef.current(item, i) === scrollToKey)
+    if (at < 0) return
+    scrolledTo.current = scrollToKey
+    atBottom.current = false
+    virtualizer.scrollToIndex(at, {align: 'center'})
+  }, [items, scrollToKey, virtualizer])
+
   useLayoutEffect(() => {
     if (anchor !== 'end' || items.length === 0 || !atBottom.current) return
     virtualizer.scrollToIndex(items.length - 1, {align: 'end'})

package/src/components/VirtualList/props.ts

@@ -24,6 +24,19 @@ export interface VirtualListProps<T> {
    * Prepending items keeps the first visible row where it was on screen.
    */
   onStartReached?: () => void
+  /**
+   * Called once each time the reader scrolls to within 44px (touchTarget) of the
+   * end (load newer items, as in a window opened on an older point). It fires
+   * again only after they move away.
+   */
+  onEndReached?: () => void
+  /**
+   * Bring this item into view, centred, each time the key changes to an item in
+   * the list (a link to one message). A key not in the list yet waits for the
+   * items that hold it; `null` or `undefined` does nothing. While it applies,
+   * `anchor="end"` stops following the end.
+   */
+  scrollToKey?: string | number | null
   /** Cap the list's height; without it, it fills its parent. */
   maxHeight?: Length
   /** The list's accessible name. */

package/src/index.native.ts

@@ -29,6 +29,7 @@ export {Textarea, type TextareaVariant} from './components/Textarea/Textarea'
 
 // Text and layout
 export {CodeBlock, type CodeBlockProps} from './components/CodeBlock/CodeBlock'
+export type {CodeBlockLineAction, DiffLineInfo} from './components/CodeBlock/types'
 export {Prose} from './components/Prose/Prose'
 export {Toolbar, type ToolbarProps} from './components/Toolbar/Toolbar'
 

package/src/index.ts

@@ -32,6 +32,7 @@ export {Callout, type CalloutVariant} from './components/Callout/Callout'
 export {Card, type CardVariant, type CardSize} from './components/Card/Card'
 export {Checkbox} from './components/Checkbox/Checkbox'
 export {CodeBlock} from './components/CodeBlock/CodeBlock'
+export type {CodeBlockLineAction, DiffLineInfo} from './components/CodeBlock/types'
 export {CheckboxGroup} from './components/CheckboxGroup/CheckboxGroup'
 export {ColorInput} from './components/ColorInput/ColorInput'
 export {ConfirmDialog} from './components/ConfirmDialog/ConfirmDialog'