@duro-app/ui 5.22.0 → 5.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.22.0",
+  "version": "5.24.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.22.0"
+    "@duro-app/tokens": "^5.24.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/AppShell/AppShell.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    "An application's frame: a navigation rail (a labelled nav, the brand at its top, an optional footer at its foot) beside the main content (main), with an optional Header. Below collapseBelow (sm default, md or lg), measured on the shell's own width, the rail is hidden and one sticky bar (a banner, appBarH tall) holds a Menu button that opens the same navigation in a left Drawer, the brand, and the Header's content when there is one — a shell without a Header still has its navigation on a phone. Above it the Header is a row that scrolls with the page and the rail stays sticky. CSS makes the switch: the server renders one HTML for every width with the brand in both places, and display: none hides the inactive copy, so nothing moves after hydration. A skip link (the first tab stop) focuses Main; an Aside inside Main sticks below the bar. Labels come from props. Compound component — Root is required. On React Native it is always the narrow shape: the bar below the status bar, Main under it, and the Rail in a left Drawer; there is no skip link.",
+    "An application's frame: a navigation rail (a labelled nav, the brand at its top, an optional footer at its foot) beside the main content (main), with an optional Header. Below collapseBelow (sm default, md or lg), measured on the shell's own width, the rail is hidden and one sticky bar (a banner, appBarH tall) holds a Menu button that opens the same navigation in a left Drawer, the brand, and the Header's content when there is one — a shell without a Header still has its navigation on a phone. Above it the Header is a row that scrolls with the page and the rail stays sticky. CSS makes the switch: the server renders one HTML for every width with the brand in both places, and display: none hides the inactive copy, so nothing moves after hydration. A skip link (the first tab stop) focuses Main; an Aside inside Main sticks below the bar. Labels come from props. Compound component — Root is required. On React Native it is always the narrow shape: the bar below the status bar, Main under it, and the Rail in a left Drawer; there is no skip link. scroll=\"main\" makes it an app frame rather than a page: the shell is the viewport's height and Main scrolls on its own, so a SplitPane or VirtualList inside it fills Main and scrolls its own panes.",
   whenToUse: [
     'The frame of an app with a persistent navigation rail: an admin, a docs site, a dashboard',
     'A layout whose navigation must collapse into a drawer on a phone',

package/src/components/AppShell/AppShell.native.tsx

@@ -18,6 +18,7 @@ import {InLandmarkContext} from '../../shared/InLandmarkContext'
 import {nativeStyles} from './native.css'
 
 export type AppShellCollapse = 'sm' | 'md' | 'lg'
+export type AppShellScroll = 'page' | 'main'
 
 interface AppShellContextValue {
   open: boolean
@@ -47,6 +48,8 @@ interface RootProps {
   brand?: ReactNode
   /** Web only: a phone is below every breakpoint, so native always shows the bar and the drawer. */
   collapseBelow?: AppShellCollapse
+  /** Web only: native Main always fills the screen under the bar and its content scrolls itself. */
+  scroll?: AppShellScroll
   /** `AppShell.Rail`, `AppShell.Main` and an optional `AppShell.Header`, as direct children. */
   children: ReactNode
 }

package/src/components/AppShell/AppShell.stories.tsx

@@ -20,6 +20,8 @@ import {TextLink} from '../TextLink/TextLink'
 import {Aside} from '../Aside/Aside'
 import {Stack} from '../Stack/Stack'
 import {Prose} from '../Prose/Prose'
+import {SplitPane} from '../SplitPane/SplitPane'
+import {VirtualList} from '../VirtualList/VirtualList'
 
 // --- the story's frame -----------------------------------------------------
 
@@ -853,3 +855,69 @@ export const MenuButtonTouchTarget: Story = {
     })
   },
 }
+
+const ROWS = Array.from({length: 500}, (_, i) => ({id: i, text: `Message ${i + 1}`}))
+
+/**
+ * `scroll="main"`: an app, not a document. The shell is the viewport's height and Main scrolls on
+ * its own, so a SplitPane inside it fills Main and each pane scrolls by itself — here a 500-row
+ * VirtualList that mounts only the rows in view.
+ */
+export const ScrollMain: Story = {
+  render: () => (
+    <AppShell.Root
+      menuLabel="Menu"
+      closeLabel="Close navigation"
+      skipLabel="Skip to content"
+      brand={BRAND}
+      scroll="main"
+    >
+      <AppShell.Rail aria-label="Navigation">
+        <SideNav.Root value="/sessions">
+          <SideNav.Item value="/sessions">Sessions</SideNav.Item>
+        </SideNav.Root>
+      </AppShell.Rail>
+      <AppShell.Main>
+        <SplitPane.Root
+          aria-label="Resize the session list"
+          defaultSize="sidebarW"
+          minSize="sidebarW"
+          maxSize="panelLg"
+        >
+          <SplitPane.Pane>
+            <Text>Sessions</Text>
+          </SplitPane.Pane>
+          <SplitPane.Handle />
+          <SplitPane.Pane>
+            <VirtualList
+              aria-label="Transcript"
+              items={ROWS}
+              getKey={(row) => row.id}
+              estimateSize="controlLg"
+              anchor="end"
+              renderItem={(row) => <Text>{row.text}</Text>}
+            />
+          </SplitPane.Pane>
+        </SplitPane.Root>
+      </AppShell.Main>
+    </AppShell.Root>
+  ),
+}
+
+/** ScrollMain's checks: Main stays within the viewport and the list windows its rows. */
+export const ScrollMainBoundsMain: Story = {
+  ...ScrollMain,
+  tags: TEST_ONLY,
+  play: async () => {
+    const main = document.querySelector('main')!
+    const list = await waitFor(() => page().getByRole('list', {name: 'Transcript'}))
+    await waitFor(() =>
+      expect(list.querySelectorAll('[role="listitem"]').length).toBeGreaterThan(0),
+    )
+    await expect(main.getBoundingClientRect().bottom).toBeLessThanOrEqual(window.innerHeight)
+    await expect(list.querySelectorAll('[role="listitem"]').length).toBeLessThan(100)
+    await expect(list.scrollHeight).toBeGreaterThan(list.clientHeight)
+    // The document itself does not scroll: Main does.
+    await expect(document.documentElement.scrollHeight).toBeLessThanOrEqual(window.innerHeight)
+  },
+}

package/src/components/AppShell/AppShell.tsx

@@ -39,6 +39,8 @@ import {styles} from './styles.css'
  * stop) focuses. */
 
 export type AppShellCollapse = 'sm' | 'md' | 'lg'
+/** `page`: the document scrolls (a docs site). `main`: the shell is the viewport, Main scrolls (an app). */
+export type AppShellScroll = 'page' | 'main'
 
 interface AppShellContextValue {
   open: boolean
@@ -46,6 +48,7 @@ interface AppShellContextValue {
   closeLabel: string
   brand: ReactNode
   collapseBelow: AppShellCollapse
+  scroll: AppShellScroll
   mainId: string
   mainRef: RefObject<HTMLElement | null>
 }
@@ -109,6 +112,13 @@ interface RootProps {
    * becomes a Drawer behind the Menu button. Default `sm`.
    */
   collapseBelow?: AppShellCollapse
+  /**
+   * What scrolls. `page` (default): the document, a page that grows with its
+   * content. `main`: the shell is exactly the viewport's height and Main
+   * scrolls on its own, so a SplitPane or VirtualList inside it can fill Main
+   * and scroll its own panes (an app such as a chat or a mail client).
+   */
+  scroll?: AppShellScroll
   /**
    * `AppShell.Rail`, `AppShell.Main` and an optional `AppShell.Header`, as
    * direct children (Root places the Header's content in its bar).
@@ -122,6 +132,7 @@ function Root({
   skipLabel,
   brand,
   collapseBelow = 'sm',
+  scroll = 'page',
   children,
 }: RootProps) {
   const [open, setOpen] = useState(false)
@@ -165,8 +176,8 @@ function Root({
   }, [open])
 
   const value = useMemo(
-    () => ({open, setOpen, closeLabel, brand, collapseBelow, mainId, mainRef}),
-    [open, closeLabel, brand, collapseBelow, mainId],
+    () => ({open, setOpen, closeLabel, brand, collapseBelow, scroll, mainId, mainRef}),
+    [open, closeLabel, brand, collapseBelow, scroll, mainId],
   )
 
   // Focus Main itself (tabIndex -1), not just scroll to it, and leave the
@@ -179,7 +190,7 @@ function Root({
   return (
     <AppShellContext.Provider value={value}>
       <html.div ref={containerRef} style={styles.container}>
-        <html.div style={[styles.grid, variant.grid]}>
+        <html.div style={[styles.grid, variant.grid, scroll === 'main' && styles.gridViewport]}>
           <html.div style={styles.skip}>
             <TextLink href={`#${mainId}`} onNavigate={skip}>
               {skipLabel}
@@ -318,7 +329,7 @@ interface MainProps {
 }
 
 function Main({children, id, ref}: MainProps) {
-  const {mainId, mainRef, collapseBelow} = useAppShell()
+  const {mainId, mainRef, collapseBelow, scroll} = useAppShell()
   const setRef = useCallback(
     (node: HTMLElement | null) => {
       mainRef.current = node
@@ -332,7 +343,7 @@ function Main({children, id, ref}: MainProps) {
       ref={setRef}
       id={id ?? mainId}
       tabIndex={-1}
-      style={[styles.main, variants[collapseBelow].main]}
+      style={[styles.main, variants[collapseBelow].main, scroll === 'main' && styles.mainScrolls]}
     >
       {children}
     </html.main>

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

@@ -47,6 +47,10 @@ export const styles = css.create({
     backgroundColor: colors.bg,
     gridTemplateRows: 'auto 1fr',
   },
+  // scroll="main": the shell is the viewport, so Main's row has a definite height.
+  gridViewport: {
+    height: '100dvh',
+  },
   gridSm: {
     gridTemplateColumns: {default: 'minmax(0, 1fr)', [WIDE_SM]: RAIL_COLUMNS},
     gridTemplateAreas: {default: NARROW_AREAS, [WIDE_SM]: WIDE_AREAS},
@@ -204,6 +208,12 @@ export const styles = css.create({
     // Focused by the skip link: no ring on a region that is not a control.
     outlineStyle: 'none',
   },
+  // scroll="main": Main is a bounded region that scrolls by itself, and a
+  // child that fills it (height 100%) gets that bound.
+  mainScrolls: {
+    minHeight: 0,
+    overflowY: 'auto',
+  },
   mainSm: {
     paddingLeft: {default: spacing.md, [WIDE_SM]: spacing.lg},
     paddingRight: {default: spacing.md, [WIDE_SM]: spacing.lg},

package/src/components/Select/Select.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it). Select.Trigger takes size="small" to match small Toggles and Buttons in a toolbar. Select.Popup takes label (the list\'s accessible name) and empty (shown in place of the list when it has no items). On React Native the trigger opens a bottom sheet (a Drawer at the medium and large detents) titled by label, with a Cancel text button (cancelLabel); the chosen option is filled with a trailing check, and a press picks an option and closes the sheet. Native has no arrow keys: each option is its own screen-reader stop.',
+    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it). Select.Trigger takes size="small" to match small Toggles and Buttons in a toolbar. Select.Popup takes label (the list\'s accessible name) and empty (shown in place of the list when it has no items). On the web the list opens below the trigger, or above it when it would overflow the viewport below and fits above. On React Native the trigger opens a bottom sheet (a Drawer at the medium and large detents) titled by label, with a Cancel text button (cancelLabel); the chosen option is filled with a trailing check, and a press picks an option and closes the sheet. Native has no arrow keys: each option is its own screen-reader stop.',
   whenToUse: [
     'User must pick one option from a predefined list',
     'Form field for country, category, role selection',

package/src/components/Select/Select.stories.tsx

@@ -1,5 +1,6 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, fn, screen} from 'storybook/test'
+import {expect, fn, screen, waitFor} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
 import {Dialog} from '../Dialog/Dialog'
 import {Select} from './Select'
 
@@ -261,3 +262,38 @@ export const LabelledAndEmpty: StoryObj<LabelledArgs> = {
     await expect(screen.queryAllByRole('option')).toHaveLength(0)
   },
 }
+
+// A composer's mode Select sits at the bottom of the window: its list opens above
+// the trigger, as Menu and Popover do, instead of running off the screen.
+const bottom = css.create({
+  frame: {height: '100vh', display: 'flex', flexDirection: 'column', justifyContent: 'flex-end'},
+})
+
+export const OpensAboveNearTheBottomEdge: Story = {
+  parameters: {layout: 'fullscreen'},
+  render: () => (
+    <html.div style={bottom.frame}>
+      <Select.Root defaultValue="default">
+        <Select.Trigger aria-label="Permission mode">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup label="Permission mode">
+          <Select.Item value="default">Default</Select.Item>
+          <Select.Item value="read-only">Read only</Select.Item>
+          <Select.Item value="auto">Auto</Select.Item>
+          <Select.Item value="yolo">YOLO</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const trigger = canvas.getByRole('combobox', {name: 'Permission mode'})
+    await userEvent.click(trigger)
+    const list = await screen.findByRole('listbox', {name: 'Permission mode'})
+    await waitFor(() => expect(list).toBeVisible())
+    const listBox = list.getBoundingClientRect()
+    await expect(listBox.bottom).toBeLessThanOrEqual(trigger.getBoundingClientRect().top)
+    await expect(listBox.top).toBeGreaterThanOrEqual(0)
+  },
+}

package/src/components/Select/Select.tsx

@@ -1,11 +1,13 @@
 import {Children, type ReactNode, useRef, useId, useEffect, useLayoutEffect, useState} from 'react'
 import {createPortal} from 'react-dom'
 import {html} from 'react-strict-dom'
+import {SPACING_PX} from '@duro-app/tokens/keys'
 import {styles} from './styles.css'
 import {SelectContext, useSelect} from './SelectContext'
 import {useSelectRoot} from './useSelectRoot'
 import {useFieldContext} from '../Field/FieldContext'
 import {usePortalMount} from '../ThemeProvider/ThemeProvider'
+import {computePopoverPosition} from '../Popover/position'
 import {usePopoverLayer} from '../Popover/PopoverLayerContext'
 import {useGroupedControl} from '../ButtonGroup/useGroupedControl'
 import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
@@ -140,18 +142,32 @@ function Popup({children, label, empty}: PopupProps) {
   const {open, close, listboxId, triggerRef} = useSelect()
   const mount = usePortalMount()
   const [coords, setCoords] = useState<{top: number; left: number; width: number} | null>(null)
+  const listboxRef = useRef<HTMLDivElement>(null)
 
-  // Measure the trigger when the popup opens, and re-measure on scroll/resize so
-  // the dropdown follows it. Capture-phase scroll catches scroll on any ancestor
-  // (e.g. a Dialog body).
+  // Place the list against the trigger when it opens, below it unless it would
+  // overflow the viewport there and fits above (as Menu and Popover do), and
+  // re-place it on scroll/resize so it follows the trigger. Capture-phase scroll
+  // catches scroll on any ancestor (e.g. a Dialog body). The list is laid out,
+  // invisible, before its first placement so its height can be measured.
   useLayoutEffect(() => {
     if (!open) return
     const update = () => {
-      const el = triggerRef.current
-      if (!el) return
-      const rect = el.getBoundingClientRect()
-      // `xs` token = 4px gap below the trigger.
-      setCoords({top: rect.bottom + 4, left: rect.left, width: rect.width})
+      const rect = triggerRef.current?.getBoundingClientRect()
+      const list = listboxRef.current
+      if (!rect || !list) return
+      const next = computePopoverPosition({
+        anchor: {top: rect.top, left: rect.left, width: rect.width, height: rect.height},
+        popup: {width: Math.max(list.offsetWidth, rect.width), height: list.offsetHeight},
+        viewport: {width: window.innerWidth, height: window.innerHeight},
+        side: 'bottom',
+        align: 'start',
+        offset: SPACING_PX.xs,
+      })
+      setCoords((prev) =>
+        prev && prev.top === next.top && prev.left === next.left && prev.width === rect.width
+          ? prev
+          : {top: next.top, left: next.left, width: rect.width},
+      )
     }
     update()
     window.addEventListener('resize', update)
@@ -162,7 +178,6 @@ function Popup({children, label, empty}: PopupProps) {
     }
   }, [open, triggerRef])
 
-  const listboxRef = useRef<HTMLDivElement>(null)
   const backdropRef = useRef<HTMLDivElement>(null)
   usePopoverLayer(listboxRef, {active: open})
   usePopoverLayer(backdropRef, {active: open})
@@ -178,7 +193,8 @@ function Popup({children, label, empty}: PopupProps) {
         aria-hidden={!open}
         style={[
           styles.popup,
-          (!open || !coords) && styles.hidden,
+          !open && styles.hidden,
+          open && !coords && styles.measuring,
           coords && styles.popupPosition(coords.top, coords.left, coords.width),
         ]}
       >

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

@@ -124,6 +124,10 @@ export const styles = css.create({
   hidden: {
     display: 'none',
   },
+  // Open but not yet placed: laid out (so its height can be measured) and unseen.
+  measuring: {
+    visibility: 'hidden',
+  },
   // Popup's `empty`: no items to choose from.
   empty: {
     paddingTop: spacing.md,

package/src/components/SplitPane/SplitPane.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Two panes side by side with a resizable separator: the first Pane is sized by the Handle (pointer drag, arrow keys, Shift for larger steps, Home and End), the second takes the rest. Min, max and starting widths are size tokens. Below collapseBelow, measured on its own width, the panes stack in one column and the handle goes; on native they always stack. A controlled collapsed prop shrinks the first pane to a strip (the iconButton size) that shows collapsedContent, removes the Handle, and keeps the first pane’s own children mounted but inert and hidden (state kept, no tab stops, out of the accessibility tree); the prior width returns when it turns false. Native ignores both. The Handle is a hairline that thickens to the accent on hover, keyboard focus or drag.',
+    'Two panes side by side with a resizable separator: the first Pane is sized by the Handle (pointer drag, arrow keys, Shift for larger steps, Home and End), the second takes the rest. Min, max and starting widths are size tokens. onSizeChange reports every width while the handle moves; onSizeCommit reports the width once a resize ends (a released drag, each keyboard step), the moment to persist it. Below collapseBelow, measured on its own width, the panes stack in one column and the handle goes; on native they always stack. A controlled collapsed prop shrinks the first pane to a strip (the iconButton size) that shows collapsedContent, removes the Handle, and keeps the first pane’s own children mounted but inert and hidden (state kept, no tab stops, out of the accessibility tree); the prior width returns when it turns false. Native ignores both. The Handle is a hairline that thickens to the accent on hover, keyboard focus or drag.',
   whenToUse: [
     'A list beside its detail where people need more room on either side (a session list and its transcript)',
     'An editor beside its preview',

package/src/components/SplitPane/SplitPane.native.tsx

@@ -12,6 +12,8 @@ interface RootProps {
   size?: number
   /** Web only. */
   onSizeChange?: (px: number) => void
+  /** Web only: called once a resize ends (native always stacks). */
+  onSizeCommit?: (px: number) => void
   /** Web only. */
   minSize?: SizeToken
   /** Web only. */

package/src/components/SplitPane/SplitPane.stories.tsx

@@ -34,6 +34,7 @@ interface SplitArgs {
   maxSize: SizeToken
   collapseBelow: Breakpoint
   onSizeChange?: (px: number) => void
+  onSizeCommit?: (px: number) => void
   collapsed?: boolean
   collapsedContent?: ReactNode
 }
@@ -50,11 +51,19 @@ const PANE_SIZES: SizeToken[] = ['sidebarW', 'panelSm', 'panelMd', 'panelLg']
 
 /** The picked B0 direction (docs/mockups/split-pane/Hairline.dc.html). */
 function Split(props: Partial<SplitArgs>) {
-  const {defaultSize, minSize, maxSize, collapseBelow, onSizeChange, collapsed, collapsedContent} =
-    {
-      ...DEFAULT_ARGS,
-      ...props,
-    }
+  const {
+    defaultSize,
+    minSize,
+    maxSize,
+    collapseBelow,
+    onSizeChange,
+    onSizeCommit,
+    collapsed,
+    collapsedContent,
+  } = {
+    ...DEFAULT_ARGS,
+    ...props,
+  }
   return (
     <html.div style={frame.fill}>
       <SplitPane.Root
@@ -64,6 +73,7 @@ function Split(props: Partial<SplitArgs>) {
         maxSize={maxSize}
         collapseBelow={collapseBelow}
         onSizeChange={onSizeChange}
+        onSizeCommit={onSizeCommit}
         collapsed={collapsed}
         collapsedContent={collapsedContent}
       >
@@ -145,6 +155,38 @@ export const KeyboardMovesTheSeparator: Story = {
   },
 }
 
+// A drag reports every width while it moves and the final one once, on release;
+// a keyboard step is its own commit. An app persists the width on commit.
+export const ResizeCommitsOnceWhenItEnds: StoryObj<SplitArgs> = {
+  args: {onSizeChange: fn(), onSizeCommit: fn()},
+  render: (args) => <Split {...args} />,
+  beforeEach: async () => {
+    await setViewport(1200, 800)
+  },
+  play: async ({args}) => {
+    await waitFor(() => expect(separator()).not.toBeNull())
+    const handle = separator()!
+    const box = handle.getBoundingClientRect()
+    const x = box.left + box.width / 2
+    const y = box.top + box.height / 2
+    await userEvent.pointer([
+      {keys: '[MouseLeft>]', target: handle, coords: {clientX: x, clientY: y}},
+      {target: handle, coords: {clientX: x + 20, clientY: y}},
+      {target: handle, coords: {clientX: x + 40, clientY: y}},
+      {keys: '[/MouseLeft]', target: handle, coords: {clientX: x + 40, clientY: y}},
+    ])
+    // two widths while it moved, one commit when it was released
+    await expect(args.onSizeChange).toHaveBeenCalledTimes(2)
+    await expect(args.onSizeCommit).toHaveBeenCalledTimes(1)
+    await expect(args.onSizeCommit).toHaveBeenLastCalledWith(SIZES_PX.sidebarW + 40)
+
+    handle.focus()
+    await userEvent.keyboard('{ArrowLeft}')
+    await expect(args.onSizeCommit).toHaveBeenCalledTimes(2)
+    await expect(args.onSizeCommit).toHaveBeenLastCalledWith(SIZES_PX.sidebarW + 40 - SPACING_PX.md)
+  },
+}
+
 export const NarrowStacksInOneColumn: Story = {
   render: () => <Split />,
   beforeEach: async () => {

package/src/components/SplitPane/SplitPane.tsx

@@ -21,6 +21,7 @@ interface SplitPaneContextValue {
   min: number
   max: number
   setSize: (px: number) => void
+  commitSize: (px: number) => void
   stacked: boolean
   collapsed: boolean
   collapsedContent: ReactNode
@@ -53,6 +54,12 @@ interface RootProps {
   size?: number
   /** Called with the primary pane's new width while the handle moves */
   onSizeChange?: (px: number) => void
+  /**
+   * Called once a resize ends, with the width it ended at: when a drag is
+   * released (or cancelled) and after each keyboard step. Persist the width
+   * here rather than on every `onSizeChange`.
+   */
+  onSizeCommit?: (px: number) => void
   /** The primary pane's narrowest width, a size token. Default: `sidebarW` */
   minSize?: SizeToken
   /** The primary pane's widest width, a size token. Default: `panelLg` */
@@ -83,6 +90,7 @@ function Root({
   defaultSize = 'sidebarW',
   size: controlledSize,
   onSizeChange,
+  onSizeCommit,
   minSize = 'sidebarW',
   maxSize = 'panelLg',
   collapseBelow = 'sm',
@@ -102,6 +110,10 @@ function Root({
     },
     [controlledSize, onSizeChange, min, max],
   )
+  const commitSize = useCallback(
+    (px: number) => onSizeCommit?.(clamp(Math.round(px), min, max)),
+    [onSizeCommit, min, max],
+  )
   const rootRef = useRef<HTMLDivElement>(null)
   const stacked = useContainerBelow(rootRef, collapseBelow)
   const primaryId = useId()
@@ -117,7 +129,18 @@ function Root({
 
   return (
     <SplitPaneContext.Provider
-      value={{size, min, max, setSize, stacked, collapsed, collapsedContent, primaryId, label}}
+      value={{
+        size,
+        min,
+        max,
+        setSize,
+        commitSize,
+        stacked,
+        collapsed,
+        collapsedContent,
+        primaryId,
+        label,
+      }}
     >
       <html.div ref={rootRef} style={[styles.root, stacked && styles.rootStacked]}>
         {items}
@@ -171,7 +194,8 @@ function Pane({children}: {children: ReactNode}) {
 }
 
 function Handle() {
-  const {size, min, max, setSize, stacked, collapsed, primaryId, label} = useSplitPane('Handle')
+  const {size, min, max, setSize, commitSize, stacked, collapsed, primaryId, label} =
+    useSplitPane('Handle')
   const [hovered, setHovered] = useState(false)
   const [keyboardFocus, setKeyboardFocus] = useState(false)
   const [dragging, setDragging] = useState(false)
@@ -198,10 +222,11 @@ function Handle() {
       if (next === null) return
       e.preventDefault()
       setSize(next)
+      commitSize(next)
     }
     el.addEventListener('keydown', onKeyDown)
     return () => el.removeEventListener('keydown', onKeyDown)
-  }, [size, min, max, setSize, stacked, collapsed])
+  }, [size, min, max, setSize, commitSize, stacked, collapsed])
 
   if (stacked || collapsed) return null
   const active = hovered || keyboardFocus || dragging
@@ -240,12 +265,16 @@ function Handle() {
         setSize(drag.current.startSize + e.clientX - drag.current.startX)
       }}
       onPointerUp={() => {
+        if (!drag.current) return
         drag.current = null
         setDragging(false)
+        commitSize(size)
       }}
       onPointerCancel={() => {
+        if (!drag.current) return
         drag.current = null
         setDragging(false)
+        commitSize(size)
       }}
     >
       <html.span aria-hidden style={[styles.line, active && styles.lineActive]} />

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).',
+    '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.',
   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.tsx

@@ -167,6 +167,8 @@ export function VirtualList<T>({
       ref={scrollRef}
       role="list"
       aria-label={ariaLabel}
+      // A scroll region the keyboard reaches even when no row holds a control.
+      tabIndex={0}
       style={[
         styles.scroller,
         maxHeight !== undefined && styles.scrollMax(resolveLength(maxHeight)),

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

@@ -1,4 +1,6 @@
 import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
 
 export const styles = css.create({
   // The scroll container: it fills its parent (a pane, a flex column) by
@@ -10,6 +12,11 @@ export const styles = css.create({
     minHeight: 0,
     overflowY: 'auto',
     overscrollBehavior: 'contain',
+    // Focusable so the keyboard can scroll rows that hold no control (WCAG 2.1.1).
+    outlineWidth: {default: 0, ':focus-visible': borders.focusRing},
+    outlineStyle: {default: 'none', ':focus-visible': 'solid'},
+    outlineColor: {default: 'transparent', ':focus-visible': colors.accent},
+    outlineOffset: {default: 0, ':focus-visible': `calc(-1 * ${borders.focusRing})`},
   },
   scrollMax: (maxHeight: number | string) => ({
     height: 'auto',

package/src/index.native.ts

@@ -73,6 +73,7 @@ export {SplitPane} from './components/SplitPane/SplitPane'
 export {
   AppShell,
   type AppShellCollapse,
+  type AppShellScroll,
   type AppShellRailState,
 } from './components/AppShell/AppShell'
 

package/src/index.ts

@@ -13,6 +13,7 @@ export {Alert, type AlertVariant} from './components/Alert/Alert'
 export {
   AppShell,
   type AppShellCollapse,
+  type AppShellScroll,
   type AppShellRailState,
 } from './components/AppShell/AppShell'
 export {Aside} from './components/Aside/Aside'