@duro-app/ui 0.41.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.41.0",
+  "version": "0.43.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.43.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/Callout/Callout.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Block-level informational message with icon and colored background. More prominent than Alert. Use for important notices, onboarding tips, or contextual guidance that should stand out.',
+    'Block-level informational message with icon and colored background. More prominent than Alert. Use for important notices, onboarding tips, or contextual guidance that should stand out. `align` controls icon↔message vertical alignment: `center` (default) for short messages, `start` for long multi-paragraph content.',
   whenToUse: [
     'Important notices that need visual prominence',
     'Onboarding tips or contextual guidance',

package/src/components/Callout/Callout.stories.tsx

@@ -11,15 +11,21 @@ const meta: Meta<typeof Callout> = {
       control: 'select',
       options: ['error', 'success', 'warning', 'info'],
     },
+    align: {
+      control: 'inline-radio',
+      options: ['center', 'start'],
+    },
   },
 }
 
 export default meta
 type Story = StoryObj<typeof Callout>
 
+// Long, multi-paragraph messages align the icon to the first line.
 export const Info: Story = {
   args: {
     variant: 'info',
+    align: 'start',
     children:
       'A new version of the application is available. Please save your work and refresh the page to get the latest features and security updates.',
   },
@@ -28,6 +34,7 @@ export const Info: Story = {
 export const Warning: Story = {
   args: {
     variant: 'warning',
+    align: 'start',
     children:
       "It looks like your certificate isn't installed yet. Install the .p12 file from your email, then click the button below. After installing the certificate, you may need to close and reopen your browser for it to be recognized.",
   },
@@ -36,6 +43,7 @@ export const Warning: Story = {
 export const Success: Story = {
   args: {
     variant: 'success',
+    align: 'start',
     children:
       'Your account has been created and your certificate is installed. You can now access all resources assigned to your groups. Check your email for a welcome guide with next steps.',
   },
@@ -44,16 +52,24 @@ export const Success: Story = {
 export const Error: Story = {
   args: {
     variant: 'error',
+    align: 'start',
     children:
       'We could not verify your identity. This may happen if your invite link has expired or was already used. Please contact your administrator to request a new invitation.',
   },
 }
 
-export const ShortText: Story = {
-  name: 'Short text (still wraps)',
+// Short single-line message — the default `align="center"` vertically centres
+// the icon against the text.
+export const ShortCentered: Story = {
   args: {
-    variant: 'info',
-    children: 'System update available.',
+    variant: 'success',
+    children: "You're all caught up — no requests awaiting review.",
+  },
+  play: async ({canvas}) => {
+    await expect(canvas.getByRole('note')).toBeInTheDocument()
+    await expect(canvas.getByText(/all caught up/)).toBeInTheDocument()
+    // Exactly one icon (svg) — the component's own, no duplicate.
+    await expect(canvas.getByRole('note').querySelectorAll('svg')).toHaveLength(1)
   },
 }
 
@@ -72,22 +88,19 @@ const stackStyles = css.create({
 export const AllVariants: Story = {
   render: () => (
     <html.div style={stackStyles.stack}>
-      <Callout variant="error">
+      <Callout variant="error" align="start">
         We could not verify your identity. This may happen if your invite link has expired or was
         already used. Please contact your administrator.
       </Callout>
-      <Callout variant="success">
+      <Callout variant="success" align="start">
         Your account has been created and your certificate is installed. You can now access all
         resources assigned to your groups.
       </Callout>
-      <Callout variant="warning">
+      <Callout variant="warning" align="start">
         It looks like your certificate is not installed yet. Install the .p12 file from your email,
         then click the button below.
       </Callout>
-      <Callout variant="info">
-        A new version of the application is available. Please save your work and refresh the page to
-        get the latest features.
-      </Callout>
+      <Callout variant="info">A new version is available.</Callout>
     </html.div>
   ),
   play: async ({canvas}) => {

package/src/components/Callout/Callout.tsx

@@ -17,6 +17,12 @@ interface CalloutProps {
   variant?: CalloutVariant
   /** Built-in icon name, custom ReactNode, or false to hide. Defaults to variant icon. */
   icon?: IconName | ReactNode | false
+  /**
+   * Vertical alignment of the icon against the message. `center` (default)
+   * suits short single/two-line messages; `start` aligns the icon to the first
+   * line for long multi-paragraph content.
+   */
+  align?: 'center' | 'start'
   children: ReactNode
 }
 
@@ -27,13 +33,20 @@ function resolveIcon(icon: CalloutProps['icon'], variant: CalloutVariant): React
   return icon
 }
 
-export function Callout({variant = 'info', icon, children}: CalloutProps) {
+export function Callout({variant = 'info', icon, align = 'center', children}: CalloutProps) {
   const resolvedIcon = resolveIcon(icon, variant)
 
   return (
-    <html.div role="note" style={[styles.base, styles[variant]]}>
+    <html.div
+      role="note"
+      style={[
+        styles.base,
+        styles[variant],
+        align === 'center' ? styles.alignCenter : styles.alignStart,
+      ]}
+    >
       {resolvedIcon && <html.span style={styles.icon}>{resolvedIcon}</html.span>}
-      {children}
+      <html.div style={styles.content}>{children}</html.div>
     </html.div>
   )
 }

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

@@ -5,23 +5,35 @@ import {typography} from '@duro-app/tokens/tokens/typography.css'
 
 export const styles = css.create({
   base: {
+    display: 'flex',
+    flexDirection: 'row',
+    gap: spacing.sm,
     padding: spacing.md,
     borderRadius: radii.sm,
     borderWidth: 1,
     borderStyle: 'solid',
     fontSize: typography.fontSizeSm,
     lineHeight: typography.lineHeight,
-    overflow: 'hidden', // contain the float
+  },
+  // Vertically centres the icon with the message — the right default for the
+  // short, single/two-line messages callouts usually carry.
+  alignCenter: {
+    alignItems: 'center',
+  },
+  // Aligns the icon to the first line — for long, multi-paragraph messages.
+  alignStart: {
+    alignItems: 'flex-start',
   },
   icon: {
-    float: 'left',
-    marginRight: spacing.sm,
-    marginBottom: spacing.xs,
-    marginTop: 2,
+    flexShrink: 0,
     display: 'inline-flex',
     alignItems: 'center',
     justifyContent: 'center',
   },
+  content: {
+    flexGrow: 1,
+    minWidth: 0,
+  },
   error: {
     backgroundColor: colors.errorBg,
     borderColor: colors.errorBorder,

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>
+  )
+}