@duro-app/ui 0.41.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -54,7 +54,8 @@
     }
   },
   "dependencies": {
-    "@duro-app/tokens": "^0.41.0"
+    "@tanstack/react-virtual": "^3.14.6",
+    "@duro-app/tokens": "^0.42.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/VirtualTable/VirtualTable.meta.ts

@@ -0,0 +1,43 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Sortable data table that windows its rows above a threshold (default 150) with @tanstack/react-virtual, shows a floating position indicator, and reports the visible page so the caller can mirror it in the URL. Below the threshold it renders every row in one scroll (no pagination). URL-decoupled: pass initialPage + onVisiblePageChange. Web-only.',
+  whenToUse: [
+    'Long lists/tables (hundreds to tens of thousands of rows) held client-side',
+    'When you want a scroll position reflected in the URL + a "rows X–Y of Z" indicator',
+    'Admin tables that may grow — small today renders all rows, large windows automatically',
+  ],
+  whenNotToUse: [
+    'Small static tables where semantic markup matters — use Table / Table.FromTanstack',
+    'Server-paginated data (this windows an already-loaded array, it does not fetch on scroll)',
+  ],
+  anatomy: {
+    required: ['data', 'columns'],
+    optional: [
+      'sorting',
+      'onSortingChange',
+      'initialPage',
+      'onVisiblePageChange',
+      'rangeLabel',
+      'onRowClick',
+    ],
+  },
+  relatedTo: [
+    {
+      component: 'Table',
+      relationship: 'Table is semantic + paginated; VirtualTable windows large lists',
+    },
+  ],
+  example: `<VirtualTable
+  data={rows}
+  columns={columns}
+  sorting={sorting}
+  onSortingChange={setSorting}
+  initialPage={Number(params.get('page')) || 1}
+  onVisiblePageChange={({page}) =>
+    setParams((p) => { const n = new URLSearchParams(p); page > 1 ? n.set('page', String(page)) : n.delete('page'); return n }, {replace: true, preventScrollReset: true})}
+  rangeLabel={({from, to, total}) => t('table.range', {from, to, total})}
+  onRowClick={(row) => navigate(\`/things/\${row.id}\`)}
+/>`,
+}

package/src/components/VirtualTable/VirtualTable.stories.tsx

@@ -0,0 +1,89 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn, waitFor} from 'storybook/test'
+import {createColumnHelper} from '@tanstack/react-table'
+import {VirtualTable} from './VirtualTable'
+
+interface Item {
+  id: string
+  name: string
+  value: number
+}
+
+const col = createColumnHelper<Item>()
+const columns = [
+  col.accessor('name', {header: 'Name', enableSorting: true}),
+  col.accessor('value', {header: 'Value', enableSorting: true}),
+]
+
+const makeData = (n: number): Item[] =>
+  Array.from({length: n}, (_, i) => ({id: `r${i}`, name: `Row ${i}`, value: i}))
+
+const meta: Meta<typeof VirtualTable<Item>> = {
+  title: 'Components/VirtualTable',
+  component: VirtualTable,
+  args: {columns, getRowId: (r: Item) => r.id},
+}
+export default meta
+type Story = StoryObj<typeof VirtualTable<Item>>
+
+// Below the threshold: every row rendered, one scroll, no windowing/indicator.
+export const SmallList: Story = {
+  args: {data: makeData(10)},
+  play: async ({canvas}) => {
+    // 1 header row + 10 body rows.
+    await waitFor(() => expect(canvas.getAllByRole('row')).toHaveLength(11))
+    await expect(canvas.getByText('Row 0')).toBeInTheDocument()
+    await expect(canvas.getByText('Row 9')).toBeInTheDocument()
+    // No floating position indicator at this size.
+    await expect(canvas.queryByText(/\/ 10$/)).toBeNull()
+  },
+}
+
+// Above the threshold: only a window of rows hits the DOM + the indicator shows.
+export const Virtualized: Story = {
+  args: {
+    data: makeData(500),
+    maxHeight: 300,
+    rangeLabel: ({from, to, total}) => `${from}-${to} of ${total}`,
+    onVisiblePageChange: fn(),
+  },
+  play: async ({canvas}) => {
+    // Windowed: far fewer than 500 body rows are in the DOM.
+    await waitFor(() => {
+      const rows = canvas.getAllByRole('row')
+      expect(rows.length).toBeGreaterThan(1) // header + some
+      expect(rows.length).toBeLessThan(80) // NOT 501 — proof of windowing
+    })
+    // The floating position indicator is present, starting at row 1.
+    await expect(canvas.getByText(/^1-\d+ of 500$/)).toBeInTheDocument()
+  },
+}
+
+// Scrolling reports a new page (for URL sync) once past a page boundary.
+export const ScrollReportsPage: Story = {
+  args: {
+    data: makeData(500),
+    maxHeight: 300,
+    pageSize: 50,
+    rangeLabel: ({page, pages}) => `page ${page}/${pages}`,
+    onVisiblePageChange: fn(),
+  },
+  play: async ({canvas, args}) => {
+    const scroller = canvas.getByRole('table')
+    await waitFor(() => expect(canvas.getByText('page 1/10')).toBeInTheDocument())
+    // Wait past the 300ms mount suppress-write window (which stops the restore
+    // scroll from clobbering the URL) before scrolling for real.
+    await new Promise((r) => setTimeout(r, 400))
+    // Scroll well past the first 50-row page (row height ~44 → page ≈ 2200px).
+    scroller.scrollTo({top: 6000})
+    scroller.dispatchEvent(new Event('scroll'))
+    // The indicator reflects the new page (proves curPage recomputed on scroll)…
+    await waitFor(() => expect(canvas.queryByText('page 1/10')).toBeNull(), {timeout: 3000})
+    await expect(canvas.getByText(/^page \d+\/10$/).textContent).not.toBe('page 1/10')
+    // …and the visible-page callback fired so a caller could sync the URL.
+    await waitFor(() => expect(args.onVisiblePageChange).toHaveBeenCalled(), {timeout: 4000})
+    const calls = (args.onVisiblePageChange as ReturnType<typeof fn>).mock.calls
+    const maxPage = Math.max(...calls.map((c) => (c[0] as {page: number}).page))
+    await expect(maxPage).toBeGreaterThan(1)
+  },
+}

package/src/components/VirtualTable/VirtualTable.tsx

@@ -0,0 +1,275 @@
+import {useEffect, useRef, useState, type ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  flexRender,
+  type ColumnDef,
+  type SortingState,
+  type OnChangeFn,
+  type Row,
+} from '@tanstack/react-table'
+import {useVirtualizer} from '@tanstack/react-virtual'
+import {styles} from './styles.css'
+
+export interface VirtualTableRange {
+  /** 1-based index of the first visible row (0 when empty). */
+  from: number
+  /** 1-based index of the last visible row (0 when empty). */
+  to: number
+  total: number
+  /** 1-based page the first visible row falls in. */
+  page: number
+  pages: number
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+interface VirtualTableProps<TData> {
+  data: TData[]
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  columns: ColumnDef<TData, any>[]
+  /** Controlled sorting (pairs with a SortChip in the caller). */
+  sorting?: SortingState
+  onSortingChange?: OnChangeFn<SortingState>
+  getRowId?: (row: TData, index: number) => string
+  onRowClick?: (row: TData) => void
+  rowLabel?: (row: TData) => string
+  /**
+   * 1-based page to restore the scroll position to on mount (read from the URL
+   * by the caller). Only meaningful when the list virtualizes.
+   */
+  initialPage?: number
+  /**
+   * Fired (debounced) when the top-visible page changes — wire it to the URL.
+   * Only fires in the virtualized branch; small lists render in one scroll and
+   * have no page concept.
+   */
+  onVisiblePageChange?: (range: VirtualTableRange) => void
+  /** Build the floating position-indicator label (i18n stays with the caller). */
+  rangeLabel?: (range: VirtualTableRange) => string
+  /** Rows per "page" for the URL/indicator math. Default 50. */
+  pageSize?: number
+  /** Estimated row height for the virtualizer. Default 44. */
+  estimateRowHeight?: number
+  /** Max height of the scroll viewport once virtualized. Default '70vh'. */
+  maxHeight?: number | string
+  /** Render every row (no windowing) at or below this count. Default 150. */
+  virtualizeThreshold?: number
+  emptyLabel?: ReactNode
+}
+
+/**
+ * A sortable data table that windows its rows above a threshold (default 150)
+ * via @tanstack/react-virtual, keeps a floating position indicator, and reports
+ * the visible page so the caller can mirror it in the URL. Below the threshold
+ * it renders every row in one scroll (find-in-page + a11y intact) — no
+ * pagination, no windowing. Web-only (uses DOM scroll measurement).
+ *
+ * URL-decoupled by design: pass `initialPage` (restore) and `onVisiblePageChange`
+ * (persist); the component never touches the router itself.
+ */
+export function VirtualTable<TData>({
+  data,
+  columns,
+  sorting,
+  onSortingChange,
+  getRowId,
+  onRowClick,
+  rowLabel,
+  initialPage,
+  onVisiblePageChange,
+  rangeLabel,
+  pageSize = 50,
+  estimateRowHeight = 44,
+  maxHeight = '70vh',
+  virtualizeThreshold = 150,
+  emptyLabel,
+}: VirtualTableProps<TData>) {
+  // Support both controlled sorting (SortChip in the caller) and standalone use.
+  const [internalSorting, setInternalSorting] = useState<SortingState>([])
+  const sortingState = sorting ?? internalSorting
+  const handleSortingChange = onSortingChange ?? setInternalSorting
+
+  const table = useReactTable({
+    data,
+    columns,
+    state: {sorting: sortingState},
+    onSortingChange: handleSortingChange,
+    getRowId,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+  })
+
+  const rows = table.getRowModel().rows
+  const virtualize = rows.length > virtualizeThreshold
+
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const rv = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => estimateRowHeight,
+    overscan: 12,
+  })
+
+  // Restore the scroll position from `initialPage` on mount, and suppress the
+  // page-change callback briefly so that restore scroll doesn't immediately
+  // report (and overwrite) the URL.
+  const suppressWrite = useRef(true)
+  useEffect(() => {
+    if (!virtualize) {
+      suppressWrite.current = false
+      return
+    }
+    if (initialPage && initialPage > 1) {
+      rv.scrollToIndex((initialPage - 1) * pageSize, {align: 'start'})
+    }
+    const id = setTimeout(() => {
+      suppressWrite.current = false
+    }, 300)
+    return () => clearTimeout(id)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [virtualize])
+
+  const vItems = rv.getVirtualItems()
+  const firstIndex = vItems[0]?.index ?? 0
+  const lastIndex = vItems.length ? vItems[vItems.length - 1].index : 0
+  const pages = Math.max(1, Math.ceil(rows.length / pageSize))
+  // page = which pageSize-sized block the top visible row is in, so it only
+  // changes when you cross a boundary (no per-scroll-tick churn).
+  const curPage = Math.floor(Math.max(0, firstIndex) / pageSize) + 1
+
+  const range: VirtualTableRange = {
+    from: rows.length ? firstIndex + 1 : 0,
+    to: rows.length ? lastIndex + 1 : 0,
+    total: rows.length,
+    page: curPage,
+    pages,
+  }
+
+  // Report the visible page so the caller can sync the URL. Fire once per
+  // distinct page rather than debouncing a timer — `curPage` only changes at a
+  // pageSize boundary (coarse), and react-virtual's frequent re-renders during
+  // scroll/measurement would keep resetting a debounce timer so it never fires.
+  // The `lastReported` guard prevents redundant calls; callers use replace, so
+  // there's no history churn.
+  const lastReported = useRef<number | null>(null)
+  useEffect(() => {
+    if (!virtualize || !onVisiblePageChange) return
+    if (suppressWrite.current) {
+      // Still in the mount-restore window — record the page so we don't emit a
+      // spurious change once it clears, but don't call out.
+      lastReported.current = curPage
+      return
+    }
+    if (lastReported.current === curPage) return
+    lastReported.current = curPage
+    onVisiblePageChange({
+      from: rows.length ? firstIndex + 1 : 0,
+      to: rows.length ? lastIndex + 1 : 0,
+      total: rows.length,
+      page: curPage,
+      pages,
+    })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [curPage, virtualize])
+
+  const renderRow = (
+    row: Row<TData>,
+    index: number,
+    positioned?: ReturnType<typeof styles.rowAbsolute>,
+    measureRef?: (node: Element | null) => void,
+  ) => (
+    <html.div
+      key={row.id}
+      ref={measureRef}
+      data-index={index}
+      role="row"
+      aria-label={rowLabel?.(row.original)}
+      onClick={onRowClick ? () => onRowClick(row.original) : undefined}
+      style={[styles.row, Boolean(onRowClick) && styles.rowClickable, positioned]}
+    >
+      {row.getVisibleCells().map((cell) => (
+        <html.div
+          key={cell.id}
+          role="cell"
+          style={[styles.cell, styles.cellFlex(cell.column.getSize())]}
+        >
+          {flexRender(cell.column.columnDef.cell, cell.getContext())}
+        </html.div>
+      ))}
+    </html.div>
+  )
+
+  const label =
+    rangeLabel?.(range) ?? (rows.length ? `${range.from}–${range.to} / ${range.total}` : '')
+
+  return (
+    <html.div style={styles.wrap}>
+      <html.div
+        ref={scrollRef}
+        role="table"
+        style={[styles.scroll, virtualize && styles.scrollMax(maxHeight)]}
+      >
+        <html.div role="rowgroup" style={styles.head}>
+          {table.getHeaderGroups().map((headerGroup) => (
+            <html.div key={headerGroup.id} role="row" style={styles.headRow}>
+              {headerGroup.headers.map((header) => {
+                const col = header.column
+                const sorted = col.getIsSorted()
+                return (
+                  <html.div
+                    key={header.id}
+                    role="columnheader"
+                    aria-sort={
+                      sorted === 'asc' ? 'ascending' : sorted === 'desc' ? 'descending' : undefined
+                    }
+                    onClick={col.getCanSort() ? col.getToggleSortingHandler() : undefined}
+                    style={[
+                      styles.headCell,
+                      col.getCanSort() && styles.headCellSortable,
+                      styles.cellFlex(header.getSize()),
+                    ]}
+                  >
+                    {header.isPlaceholder
+                      ? null
+                      : flexRender(col.columnDef.header, header.getContext())}
+                    {sorted ? (
+                      <html.span style={styles.sortMark}>{sorted === 'asc' ? '↑' : '↓'}</html.span>
+                    ) : null}
+                  </html.div>
+                )
+              })}
+            </html.div>
+          ))}
+        </html.div>
+
+        {rows.length === 0 ? (
+          <html.div style={styles.empty}>{emptyLabel}</html.div>
+        ) : (
+          <html.div
+            role="rowgroup"
+            style={virtualize ? styles.bodyTotal(rv.getTotalSize()) : undefined}
+          >
+            {virtualize
+              ? vItems.map((vi) =>
+                  renderRow(
+                    rows[vi.index],
+                    vi.index,
+                    styles.rowAbsolute(vi.start),
+                    rv.measureElement,
+                  ),
+                )
+              : rows.map((row, i) => renderRow(row, i))}
+          </html.div>
+        )}
+      </html.div>
+
+      {virtualize && rows.length > 0 ? (
+        <html.div aria-live="polite" style={styles.pos}>
+          {label}
+        </html.div>
+      ) : null}
+    </html.div>
+  )
+}

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

@@ -0,0 +1,135 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
+
+export const styles = css.create({
+  wrap: {
+    position: 'relative',
+    width: '100%',
+  },
+  scroll: {
+    position: 'relative',
+    width: '100%',
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: radii.md,
+    backgroundColor: colors.bgCard,
+  },
+  // Dynamic: only virtualized lists get a capped, scrollable viewport.
+  scrollMax: (maxHeight: number | string) => ({
+    maxHeight,
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
+  }),
+  head: {
+    position: 'sticky',
+    top: 0,
+    zIndex: 1,
+    backgroundColor: colors.bgCard,
+  },
+  headRow: {
+    display: 'flex',
+    flexDirection: 'row',
+    borderBottomWidth: 1,
+    borderBottomStyle: 'solid',
+    borderBottomColor: colors.border,
+  },
+  headCell: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.xs,
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeXs,
+    fontWeight: typography.fontWeightSemibold,
+    textTransform: 'uppercase' as const,
+    letterSpacing: '0.03em',
+    color: colors.textMuted,
+  },
+  headCellSortable: {
+    cursor: 'pointer',
+    userSelect: 'none',
+    color: {default: colors.textMuted, ':hover': colors.text},
+  },
+  sortMark: {
+    fontSize: typography.fontSizeXs,
+    color: colors.accent,
+  },
+  bodyTotal: (height: number) => ({
+    position: 'relative',
+    width: '100%',
+    height,
+  }),
+  row: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center',
+    width: '100%',
+    borderBottomWidth: 1,
+    borderBottomStyle: 'solid',
+    borderBottomColor: colors.border,
+  },
+  rowClickable: {
+    cursor: 'pointer',
+    backgroundColor: {default: 'transparent', ':hover': colors.bgCardHover},
+  },
+  // Dynamic: absolute placement of a windowed row.
+  rowAbsolute: (y: number) => ({
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    transform: `translateY(${y}px)`,
+  }),
+  cell: {
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.text,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  // Dynamic: proportional column width from the TanStack column size (fr-like).
+  cellFlex: (size: number) => ({
+    flexGrow: size,
+    flexShrink: 1,
+    flexBasis: 0,
+    minWidth: 0,
+  }),
+  empty: {
+    paddingTop: spacing.xl,
+    paddingBottom: spacing.xl,
+    textAlign: 'center' as const,
+    color: colors.textMuted,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+  },
+  // Floating position indicator, pinned bottom-right of the viewport.
+  pos: {
+    position: 'absolute',
+    right: spacing.sm,
+    bottom: spacing.sm,
+    paddingTop: 3,
+    paddingBottom: 3,
+    paddingLeft: spacing.sm,
+    paddingRight: spacing.sm,
+    borderRadius: radii.full,
+    backgroundColor: colors.bgCardHover,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    color: colors.textMuted,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeXs,
+    pointerEvents: 'none',
+  },
+})

package/src/index.ts

@@ -56,6 +56,9 @@ export {
 export {Tag, type TagVariant, type TagSize} from './components/Tag/Tag'
 export {TagGroup} from './components/TagGroup/TagGroup'
 export {Table, type TableVariant, type TableSize} from './components/Table/Table'
+// Web-only (DOM scroll measurement + @tanstack/react-virtual); intentionally
+// absent from index.native.ts.
+export {VirtualTable, type VirtualTableRange} from './components/VirtualTable/VirtualTable'
 // Side-effect import registers our augmentation of TanStack's ColumnMeta
 // (stackLabel / isActions). Standalone module so the augmentation lands
 // whenever this package is in a consumer's TS program, even if FromTanstack