@duro-app/ui 5.31.0 → 5.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.31.0",
+  "version": "5.32.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -92,7 +92,7 @@
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.13",
     "qrcode": "^1.5.4",
-    "@duro-app/tokens": "^5.31.0"
+    "@duro-app/tokens": "^5.32.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.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. 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.',
+    '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. onAtEndChange(atEnd) is called once each time the reader comes within 44px of the end or leaves it, so a host can record whether the reader follows the live tail; scrollToEndKey scrolls to the end and resumes anchor="end" following each time it changes to a new non-null value (the host\'s own send), even when the reader had scrolled up.',
   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

@@ -33,18 +33,39 @@ export function VirtualList<T>({
   onStartReached,
   onEndReached,
   scrollToKey,
+  onAtEndChange,
+  scrollToEndKey,
   maxHeight,
   'aria-label': ariaLabel,
 }: VirtualListProps<T>) {
   const listRef = useRef<FlatList<T>>(null)
   const atBottom = useRef(true)
 
+  // The last state `onAtEndChange` was told, so it only hears a change.
+  const reportedAtEnd = useRef(true)
+  const atEndCallback = useRef(onAtEndChange)
+  atEndCallback.current = onAtEndChange
+
   const onScroll = useCallback((e: NativeSyntheticEvent<NativeScrollEvent>) => {
     const {contentOffset, contentSize, layoutMeasurement} = e.nativeEvent
     atBottom.current =
       contentSize.height - contentOffset.y - layoutMeasurement.height <= BOTTOM_SLOP
+    if (reportedAtEnd.current !== atBottom.current) {
+      reportedAtEnd.current = atBottom.current
+      atEndCallback.current?.(atBottom.current)
+    }
   }, [])
 
+  // `scrollToEndKey`: a new non-null key scrolls to the end and resumes following.
+  const endKey = useRef(scrollToEndKey)
+  useEffect(() => {
+    if (endKey.current === scrollToEndKey) return
+    endKey.current = scrollToEndKey
+    if (scrollToEndKey === null || scrollToEndKey === undefined) return
+    atBottom.current = true
+    listRef.current?.scrollToEnd({animated: false})
+  }, [scrollToEndKey])
+
   // `scrollToKey`: centre that item once per key, as soon as the items hold it.
   const scrolledTo = useRef<string | number | null | undefined>(undefined)
   useEffect(() => {

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

@@ -325,3 +325,90 @@ export const EndReachedFiresOncePerApproach: StoryObj<{onEndReached: () => void}
     await waitFor(() => expect(args.onEndReached).toHaveBeenCalledTimes(2))
   },
 }
+
+function Tail({
+  onAtEndChange,
+  endKey,
+}: {
+  onAtEndChange?: (atEnd: boolean) => void
+  endKey?: number | null
+}) {
+  return (
+    <VirtualList
+      aria-label="Transcript"
+      items={ITEMS.slice(0, 200)}
+      getKey={(m) => m.id}
+      estimateSize="controlLg"
+      anchor="end"
+      onAtEndChange={onAtEndChange}
+      scrollToEndKey={endKey}
+      maxHeight="previewMaxH"
+      renderItem={(m) => <Text>{m.text}</Text>}
+    />
+  )
+}
+
+const frames = () =>
+  new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)))
+
+export const AtEndChangeFiresOncePerChange: StoryObj<{onAtEndChange: (atEnd: boolean) => void}> = {
+  args: {onAtEndChange: fn()},
+  render: (args) => <Tail onAtEndChange={args.onAtEndChange} />,
+  play: async ({canvas, args}) => {
+    const list = canvas.getByRole('list', {name: 'Transcript'})
+    await waitFor(() => expect(canvas.getByText('Message 200')).toBeInTheDocument())
+    await frames()
+    await expect(args.onAtEndChange).not.toHaveBeenCalled()
+    list.scrollTop = 0
+    await waitFor(() => expect(args.onAtEndChange).toHaveBeenCalledTimes(1))
+    await expect(args.onAtEndChange).toHaveBeenLastCalledWith(false)
+    list.scrollTop = 20
+    await frames()
+    await expect(args.onAtEndChange).toHaveBeenCalledTimes(1)
+    list.scrollTop = list.scrollHeight
+    await waitFor(() => expect(args.onAtEndChange).toHaveBeenCalledTimes(2))
+    await expect(args.onAtEndChange).toHaveBeenLastCalledWith(true)
+  },
+}
+
+function EndKeyHost() {
+  const [key, setKey] = useState(0)
+  const [, setTick] = useState(0)
+  return (
+    <>
+      <html.button type="button" onClick={() => setKey((k) => k + 1)}>
+        Send
+      </html.button>
+      <html.button type="button" onClick={() => setTick((t) => t + 1)}>
+        Rerender
+      </html.button>
+      <Tail endKey={key} />
+    </>
+  )
+}
+
+export const ScrollToEndKeyScrollsToTheEnd: Story = {
+  render: () => <EndKeyHost />,
+  play: async ({canvas, userEvent}) => {
+    const list = canvas.getByRole('list', {name: 'Transcript'})
+    await waitFor(() => expect(canvas.getByText('Message 200')).toBeInTheDocument())
+    list.scrollTop = 0
+    await waitFor(() => expect(canvas.queryByText('Message 200')).toBeNull())
+    await userEvent.click(canvas.getByRole('button', {name: 'Send'}))
+    await waitFor(() => expect(canvas.getByText('Message 200')).toBeInTheDocument())
+  },
+}
+
+export const ScrollToEndKeyUnchangedDoesNotScroll: Story = {
+  render: () => <EndKeyHost />,
+  play: async ({canvas, userEvent}) => {
+    const list = canvas.getByRole('list', {name: 'Transcript'})
+    await waitFor(() => expect(canvas.getByText('Message 200')).toBeInTheDocument())
+    list.scrollTop = 0
+    await waitFor(() => expect(canvas.queryByText('Message 200')).toBeNull())
+    await userEvent.click(canvas.getByRole('button', {name: 'Rerender'}))
+    await frames()
+    await expect(canvas.queryByText('Message 200')).toBeNull()
+    await expect(list.scrollTop).toBeLessThan(list.scrollHeight / 2)
+  },
+}

package/src/components/VirtualList/VirtualList.tsx

@@ -35,6 +35,8 @@ export function VirtualList<T>({
   onStartReached,
   onEndReached,
   scrollToKey,
+  onAtEndChange,
+  scrollToEndKey,
   maxHeight,
   'aria-label': ariaLabel,
 }: VirtualListProps<T>) {
@@ -57,6 +59,10 @@ export function VirtualList<T>({
   const endArmed = useRef(true)
   const endCallback = useRef(onEndReached)
   endCallback.current = onEndReached
+  // The last state `onAtEndChange` was told, so it only hears a change.
+  const reportedAtEnd = useRef(true)
+  const atEndCallback = useRef(onAtEndChange)
+  atEndCallback.current = onAtEndChange
   // 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)
@@ -65,6 +71,10 @@ export function VirtualList<T>({
     if (!el) return
     const onScroll = () => {
       atBottom.current = el.scrollHeight - el.scrollTop - el.clientHeight <= BOTTOM_SLOP
+      if (reportedAtEnd.current !== atBottom.current) {
+        reportedAtEnd.current = atBottom.current
+        atEndCallback.current?.(atBottom.current)
+      }
       if (!atBottom.current) {
         endArmed.current = true
       } else if (endArmed.current && el.scrollHeight > el.clientHeight) {
@@ -179,6 +189,16 @@ export function VirtualList<T>({
     virtualizer.scrollToIndex(at, {align: 'center'})
   }, [items, scrollToKey, virtualizer])
 
+  // `scrollToEndKey`: a new non-null key scrolls to the end and resumes following.
+  const endKey = useRef(scrollToEndKey)
+  useLayoutEffect(() => {
+    if (endKey.current === scrollToEndKey) return
+    endKey.current = scrollToEndKey
+    if (scrollToEndKey === null || scrollToEndKey === undefined || items.length === 0) return
+    atBottom.current = true
+    virtualizer.scrollToIndex(items.length - 1, {align: 'end'})
+  }, [items.length, scrollToEndKey, virtualizer])
+
   useLayoutEffect(() => {
     if (anchor !== 'end' || items.length === 0 || !atBottom.current) return
     virtualizer.scrollToIndex(items.length - 1, {align: 'end'})

package/src/components/VirtualList/props.ts

@@ -30,6 +30,19 @@ export interface VirtualListProps<T> {
    * again only after they move away.
    */
   onEndReached?: () => void
+  /**
+   * Called once each time the reader comes within 44px (touchTarget) of the end
+   * or leaves it, with `true` at the end and `false` away from it, so a host can
+   * record whether the reader follows the live tail. It never repeats a value.
+   */
+  onAtEndChange?: (atEnd: boolean) => void
+  /**
+   * Scroll to the end, and resume `anchor="end"` following, each time the key
+   * changes to a new non-null value (a host's own send), even when the reader
+   * had scrolled up. The key present at the first render does nothing; `null`
+   * does nothing.
+   */
+  scrollToEndKey?: string | number | null
   /**
    * 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