@duro-app/ui 5.21.0 → 5.22.0

package/src/components/SplitPane/SplitPane.tsx

@@ -22,6 +22,8 @@ interface SplitPaneContextValue {
   max: number
   setSize: (px: number) => void
   stacked: boolean
+  collapsed: boolean
+  collapsedContent: ReactNode
   primaryId: string
   label: string
 }
@@ -57,6 +59,15 @@ interface RootProps {
   maxSize?: SizeToken
   /** Below this breakpoint, measured on the split's own width, the panes stack. Default: `sm` */
   collapseBelow?: Breakpoint
+  /**
+   * Controlled: shrink the primary pane to a strip (the `iconButton` size),
+   * show `collapsedContent` in it and remove the handle. The pane's own
+   * children stay mounted (their state is kept) but are inert and hidden. When
+   * it turns false the pane returns to its prior width. Ignored when stacked.
+   */
+  collapsed?: boolean
+  /** What the strip shows while `collapsed` (an expand button, icons). */
+  collapsedContent?: ReactNode
   /** The handle's accessible name ("Resize list"). */
   'aria-label': string
 }
@@ -75,6 +86,8 @@ function Root({
   minSize = 'sidebarW',
   maxSize = 'panelLg',
   collapseBelow = 'sm',
+  collapsed = false,
+  collapsedContent,
   'aria-label': label,
 }: RootProps) {
   const min = SIZES_PX[minSize]
@@ -103,7 +116,9 @@ function Root({
   })
 
   return (
-    <SplitPaneContext.Provider value={{size, min, max, setSize, stacked, primaryId, label}}>
+    <SplitPaneContext.Provider
+      value={{size, min, max, setSize, stacked, collapsed, collapsedContent, primaryId, label}}
+    >
       <html.div ref={rootRef} style={[styles.root, stacked && styles.rootStacked]}>
         {items}
       </html.div>
@@ -112,23 +127,51 @@ function Root({
 }
 
 function Pane({children}: {children: ReactNode}) {
-  const {size, stacked, primaryId} = useSplitPane('Pane')
+  const {size, stacked, collapsed, collapsedContent, primaryId} = useSplitPane('Pane')
   const primary = useContext(PaneIndexContext) === 0
+  const strip = primary && collapsed && !stacked
+  const bodyRef = useRef<HTMLDivElement>(null)
+
+  // `inert` takes the stowed children out of the tab order and the accessibility
+  // tree; set on the node because the strict-DOM element has no such prop.
+  useEffect(() => {
+    const el = bodyRef.current
+    if (!el) return
+    if (strip) el.setAttribute('inert', '')
+    else el.removeAttribute('inert')
+  }, [strip])
+
   return (
     <html.div
       id={primary ? primaryId : undefined}
       style={[
-        primary ? [styles.primary, !stacked && styles.primarySize(size)] : styles.secondary,
+        primary
+          ? [
+              styles.primary,
+              !stacked && styles.primarySize(collapsed ? SIZES_PX.iconButton : size),
+              !stacked && collapsed && styles.primaryStrip,
+            ]
+          : styles.secondary,
         stacked && styles.stackedPane,
       ]}
     >
-      {children}
+      {strip ? collapsedContent : null}
+      {primary ? (
+        // The wrapper exists for the primary pane only, to stow its children
+        // (inert) while collapsed; unstowed it fills the pane, so a child that
+        // takes the pane's height keeps scrolling on its own.
+        <html.div ref={bodyRef} style={strip ? styles.stowed : styles.fill}>
+          {children}
+        </html.div>
+      ) : (
+        children
+      )}
     </html.div>
   )
 }
 
 function Handle() {
-  const {size, min, max, setSize, stacked, primaryId, label} = useSplitPane('Handle')
+  const {size, min, max, setSize, stacked, collapsed, primaryId, label} = useSplitPane('Handle')
   const [hovered, setHovered] = useState(false)
   const [keyboardFocus, setKeyboardFocus] = useState(false)
   const [dragging, setDragging] = useState(false)
@@ -158,9 +201,9 @@ function Handle() {
     }
     el.addEventListener('keydown', onKeyDown)
     return () => el.removeEventListener('keydown', onKeyDown)
-  }, [size, min, max, setSize, stacked])
+  }, [size, min, max, setSize, stacked, collapsed])
 
-  if (stacked) return null
+  if (stacked || collapsed) return null
   const active = hovered || keyboardFocus || dragging
 
   return (

package/src/components/SplitPane/styles.css.ts

@@ -28,6 +28,34 @@ export const styles = css.create({
     minWidth: 0,
     overflow: 'auto',
   },
+  // Collapsed: only a strip is left, so nothing spills out of it.
+  // Its content is centred under a top inset, and a hairline stands in for the
+  // handle it no longer has.
+  primaryStrip: {
+    position: 'relative',
+    overflow: 'hidden',
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    paddingTop: spacing.sm,
+    borderRightWidth: borders.hairline,
+    borderRightStyle: 'solid',
+    borderRightColor: colors.border,
+  },
+  // The collapsed pane's own children: mounted, so their state is kept, but
+  // out of sight, out of the tab order (with `inert`) and unclickable.
+  stowed: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    visibility: 'hidden',
+    pointerEvents: 'none',
+  },
+  // The primary pane's children wrapper, unstowed: it fills the pane.
+  fill: {
+    height: '100%',
+    minHeight: 0,
+  },
   primarySize: (px: number) => ({width: px}),
   secondary: {
     flexGrow: 1,

package/src/components/Textarea/Textarea.meta.ts

@@ -2,8 +2,12 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Multi-line text input with automatic Field/Form integration. Same Field binding behavior as Input.',
-  whenToUse: ['Multi-line text entry (comments, messages, descriptions)'],
+    'Multi-line text input with automatic Field/Form integration. Same Field binding behavior as Input. autoGrow makes the height follow the content from rows up to maxRows, then it scrolls (CSS field-sizing, with a scrollHeight fallback; native grows with the content and caps at maxRows). The anchor props of Listbox.getAnchorProps() (role combobox, aria-controls, aria-expanded, aria-activedescendant) are forwarded as ARIA attributes on web and as the matching accessibility props on native, so a Listbox can be anchored to it while the editor keeps focus.',
+  whenToUse: [
+    'Multi-line text entry (comments, messages, descriptions)',
+    'A composer that grows with its text (autoGrow, maxRows)',
+    'An editor a Listbox is anchored to for mentions or slash commands (spread Listbox.getAnchorProps())',
+  ],
   whenNotToUse: ['Single-line input — use Input'],
   relatedTo: [
     {

package/src/components/Textarea/Textarea.stories.tsx

@@ -1,7 +1,9 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, fn} from 'storybook/test'
+import {expect, fn, waitFor, within} from 'storybook/test'
+import {useCallback, useId, useRef, useState} from 'react'
 import {css, html} from 'react-strict-dom'
 import {Textarea} from './Textarea'
+import {Listbox} from '../Listbox/Listbox'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
@@ -96,3 +98,136 @@ export const AllVariants: Story = {
     await expect(disabled).toBeDisabled()
   },
 }
+
+export const AutoGrow: Story = {
+  args: {placeholder: 'Grows', autoGrow: true, rows: 2, maxRows: 5},
+  play: async ({canvas, userEvent}) => {
+    const textarea = canvas.getByPlaceholderText('Grows') as HTMLTextAreaElement
+    const empty = textarea.getBoundingClientRect().height
+
+    await userEvent.click(textarea)
+    await userEvent.keyboard(
+      'a{Shift>}{Enter}{/Shift}b{Shift>}{Enter}{/Shift}c{Shift>}{Enter}{/Shift}d',
+    )
+    // four lines: taller than empty, nothing to scroll yet
+    await waitFor(() => expect(textarea.getBoundingClientRect().height).toBeGreaterThan(empty))
+    await expect(textarea.scrollHeight).toBeLessThanOrEqual(textarea.clientHeight)
+
+    // many more lines: the height stops at maxRows, then the field scrolls
+    await userEvent.keyboard('{Shift>}{Enter}{/Shift}e'.repeat(10))
+    await waitFor(() => expect(textarea.scrollHeight).toBeGreaterThan(textarea.clientHeight))
+    const capped = textarea.getBoundingClientRect().height
+    await userEvent.keyboard('{Shift>}{Enter}{/Shift}f')
+    await expect(textarea.getBoundingClientRect().height).toBe(capped)
+    await expect(capped).toBeLessThan(textarea.scrollHeight)
+    // the cap is maxRows (5) lines plus the vertical padding and border
+    const box = getComputedStyle(textarea)
+    const px = (v: string) => parseFloat(v)
+    const fiveLines =
+      5 * px(box.lineHeight) +
+      px(box.paddingTop) +
+      px(box.paddingBottom) +
+      px(box.borderTopWidth) +
+      px(box.borderBottomWidth)
+    await expect(Math.abs(capped - fiveLines)).toBeLessThan(1)
+  },
+}
+
+const FRUITS = ['Apple', 'Apricot', 'Banana', 'Cherry']
+
+// The editor keeps focus while the anchored Listbox filters and selects.
+function AnchoredEditor() {
+  const id = useId()
+  const ref = useRef<HTMLTextAreaElement | null>(null)
+  const [text, setText] = useState('')
+  const [highlighted, setHighlighted] = useState(0)
+  const [dismissed, setDismissed] = useState(false)
+  const query = text.startsWith('/') ? text.slice(1).toLowerCase() : null
+  const matches = query === null ? [] : FRUITS.filter((f) => f.toLowerCase().startsWith(query))
+  const open = query !== null && !dismissed && matches.length > 0
+  const optionId = useCallback((value: string) => `${id}-${value}`, [id])
+  const highlightedId = open ? optionId(matches[Math.min(highlighted, matches.length - 1)]!) : null
+
+  const pick = (value: string) => {
+    setText(`${value} `)
+    setDismissed(false)
+  }
+
+  return (
+    <>
+      <Textarea
+        placeholder="Type / to pick"
+        ref={ref}
+        value={text}
+        onChange={(e) => {
+          setText(e.target.value)
+          setHighlighted(0)
+          setDismissed(false)
+        }}
+        onKeyDown={(e) => {
+          if (!open) return
+          if (e.key === 'ArrowDown') {
+            e.preventDefault()
+            setHighlighted((i) => (i + 1) % matches.length)
+          } else if (e.key === 'Enter') {
+            e.preventDefault()
+            pick(matches[Math.min(highlighted, matches.length - 1)]!)
+          } else if (e.key === 'Escape') {
+            setDismissed(true)
+          }
+        }}
+        role="combobox"
+        {...Listbox.getAnchorProps({id, open, highlightedId})}
+      />
+      <Listbox.Root
+        id={id}
+        open={open}
+        anchor={() => ref.current?.getBoundingClientRect()}
+        highlightedId={highlightedId}
+        onSelect={pick}
+        getOptionId={optionId}
+        aria-label="Fruits"
+      >
+        {matches.map((f) => (
+          <Listbox.Option key={f} value={f}>
+            {f}
+          </Listbox.Option>
+        ))}
+      </Listbox.Root>
+    </>
+  )
+}
+
+export const AnchoredListbox: Story = {
+  render: () => <AnchoredEditor />,
+  play: async ({canvas, userEvent}) => {
+    const editor = canvas.getByRole('combobox')
+    await userEvent.click(editor)
+    await userEvent.keyboard('/a')
+    const list = await within(document.body).findByRole('listbox', {name: 'Fruits'})
+    await expect(editor).toHaveFocus()
+    await expect(editor).toHaveAttribute('aria-expanded', 'true')
+    await expect(editor).toHaveAttribute('aria-controls', list.id)
+    await expect(within(list).getAllByRole('option')).toHaveLength(2)
+
+    // filtering narrows the list; focus stays in the editor
+    await userEvent.keyboard('pr')
+    await waitFor(() => expect(within(list).getAllByRole('option')).toHaveLength(1))
+    await expect(editor).toHaveFocus()
+    await expect(editor).toHaveAttribute('aria-activedescendant', `${list.id}-Apricot`)
+
+    // selecting by key keeps focus and closes the list
+    await userEvent.keyboard('{Enter}')
+    await expect(editor).toHaveValue('Apricot ')
+    await expect(editor).toHaveFocus()
+    await waitFor(() => expect(editor).toHaveAttribute('aria-expanded', 'false'))
+
+    // selecting by pointer keeps focus too
+    await userEvent.clear(editor)
+    await userEvent.keyboard('/b')
+    const banana = await within(document.body).findByRole('option', {name: 'Banana'})
+    await userEvent.click(banana)
+    await expect(editor).toHaveValue('Banana ')
+    await expect(editor).toHaveFocus()
+  },
+}

package/src/components/Textarea/Textarea.tsx

@@ -1,12 +1,28 @@
+import {useCallback, useRef} from 'react'
 import {html} from 'react-strict-dom'
 import {useFieldContext} from '../Field/FieldContext'
+import type {ListboxAnchorProps} from '../Listbox/Listbox'
+import {useAutoGrowFallback} from './useAutoGrowFallback'
+import {grow} from './grow'
 import {styles} from './styles.css'
 
 type StrictTextareaProps = React.ComponentProps<typeof html.textarea>
 
 export type TextareaVariant = 'default' | 'error'
 
-interface TextareaProps {
+/** `maxRows` only means something on a field that grows. */
+type GrowProps =
+  | {
+      /** The height follows the content, from `rows` up to `maxRows`, then it scrolls. */
+      autoGrow: true
+      /** The most rows the field shows before it scrolls. Default: no limit */
+      maxRows?: number
+    }
+  | {autoGrow?: false; maxRows?: never}
+
+type TextareaProps = Partial<ListboxAnchorProps> & GrowProps & TextareaBaseProps
+
+interface TextareaBaseProps {
   variant?: TextareaVariant
   name?: string
   placeholder?: string
@@ -32,6 +48,14 @@ export function Textarea({
   placeholder,
   required,
   rows = 3,
+  autoGrow,
+  maxRows,
+  role,
+  'aria-controls': ariaControls,
+  'aria-expanded': ariaExpanded,
+  'aria-activedescendant': ariaActiveDescendant,
+  'aria-autocomplete': ariaAutocomplete,
+  'aria-haspopup': ariaHasPopup,
   value,
   defaultValue,
   disabled,
@@ -57,6 +81,18 @@ export function Textarea({
   const extraProps: Record<string, unknown> = {}
   if (autoFocus) extraProps.autoFocus = true
 
+  // Without CSS field-sizing, measure the content after each render.
+  const innerRef = useRef<HTMLTextAreaElement | null>(null)
+  const setRef = useCallback(
+    (el: HTMLTextAreaElement | null) => {
+      innerRef.current = el
+      if (typeof effectiveRef === 'function') effectiveRef(el)
+      else if (effectiveRef) (effectiveRef as {current: unknown}).current = el
+    },
+    [effectiveRef],
+  )
+  useAutoGrowFallback(innerRef, autoGrow ? 'content' : 'fixed')
+
   return (
     <html.textarea
       id={ctx?.controlId}
@@ -76,8 +112,19 @@ export function Textarea({
       onFocus={onFocus as StrictTextareaProps['onFocus']}
       onKeyDown={onKeyDown as StrictTextareaProps['onKeyDown']}
       onKeyUp={onKeyUp as StrictTextareaProps['onKeyUp']}
-      ref={effectiveRef as React.Ref<HTMLTextAreaElement>}
-      style={[styles.base, styles[effectiveVariant]]}
+      role={role}
+      aria-controls={ariaControls}
+      aria-expanded={ariaExpanded}
+      aria-activedescendant={ariaActiveDescendant}
+      aria-autocomplete={ariaAutocomplete}
+      aria-haspopup={ariaHasPopup}
+      ref={setRef}
+      style={[
+        styles.base,
+        styles[effectiveVariant],
+        autoGrow && grow.autoGrow,
+        autoGrow && maxRows !== undefined && grow.maxRows(maxRows),
+      ]}
       {...extraProps}
     />
   )

package/src/components/Textarea/autoGrow.ts

@@ -0,0 +1,33 @@
+/** How a Textarea sizes itself: to its content, or to its fixed rows. */
+export type GrowMode = 'content' | 'fixed'
+
+/**
+ * Fallback for browsers without CSS `field-sizing: content`: size the field to
+ * its content. The element's own `rows` give the floor, the style's maxHeight
+ * the ceiling (past it the field scrolls).
+ */
+export interface GrowableField {
+  style: {height: string}
+  scrollHeight: number
+  offsetHeight: number
+  clientHeight: number
+}
+
+/** True when the browser sizes a textarea to its content in CSS. */
+export function supportsFieldSizing(
+  css: {supports?: (property: string, value: string) => boolean} | undefined = (
+    globalThis as {CSS?: {supports?: (property: string, value: string) => boolean}}
+  ).CSS,
+): boolean {
+  return css?.supports?.('field-sizing', 'content') === true
+}
+
+/** Resize `el` to fit its content; returns the height set, in px. */
+export function fitToContent(el: GrowableField): number {
+  el.style.height = 'auto'
+  // scrollHeight excludes the border; add it back for a border-box field.
+  const border = el.offsetHeight - el.clientHeight
+  const height = el.scrollHeight + border
+  el.style.height = `${height}px`
+  return height
+}

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',