@proteos/ui 0.46.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/ui",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "license": "FSL-1.1-Apache-2.0",
   "description": "Proteos React component library (React Aria Components + Tailwind v4).",
   "repository": {
@@ -55,7 +55,7 @@
     "tailwind-merge": "^3.5.0",
     "tailwind-variants": "^3.2.2",
     "tailwindcss": "^4.2.4",
-    "@proteos/sdk": "0.46.0"
+    "@proteos/sdk": "0.47.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",

package/src/components/checkbox/checkbox.tsx

@@ -16,7 +16,14 @@ export function Checkbox({ children, className, ...props }: CheckboxProps) {
       {...props}
       className={(renderProps) =>
         cn(
-          'group inline-flex items-center gap-2.5 cursor-pointer',
+          // `relative` so RAC's visually-hidden <input> — which is absolutely
+          // positioned and is the element that actually receives focus — is
+          // laid out against THIS checkbox. Without a positioned ancestor here
+          // it resolves against a far-away container, ends up outside any
+          // scroll clipping, and focusing it makes the browser scroll a
+          // container the user cannot scroll back (the roles permission
+          // matrix, where toggling a row threw the page off-screen).
+          'group relative inline-flex items-center gap-2.5 cursor-pointer',
           'font-sans text-[14px] text-ink-2 select-none',
           'data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed',
           typeof className === 'function' ? className(renderProps) : className,

package/src/components/data-table/data-table.test.tsx

@@ -0,0 +1,112 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useState } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { DataTable, type InfiniteQueryLike } from './data-table'
+
+type Row = { id: string; name: string }
+
+const ROWS: Row[] = [
+  { id: 'r-1', name: 'Alpha' },
+  { id: 'r-2', name: 'Beta' },
+  { id: 'r-3', name: 'Gamma' },
+]
+
+function query(rows: Row[]): InfiniteQueryLike<Row> {
+  return {
+    data: { pages: [{ data: rows, meta: { items_total: rows.length } }] },
+    isLoading: false,
+    isFetchingNextPage: false,
+    hasNextPage: false,
+    error: null,
+    fetchNextPage: vi.fn(),
+  }
+}
+
+const columns = [{ id: 'name', accessorKey: 'name', header: 'Name', size: 160 }]
+
+function Harness({ onChange }: { onChange?: (ids: Set<string>) => void }) {
+  const [selected, setSelected] = useState<Set<string>>(new Set())
+  return (
+    <DataTable<Row>
+      query={query(ROWS)}
+      columns={columns}
+      ariaLabel="Records"
+      selectionMode="multiple"
+      selectedIds={selected}
+      onSelectionChange={(ids) => {
+        setSelected(ids)
+        onChange?.(ids)
+      }}
+    />
+  )
+}
+
+// The body is virtualized against a real scroll box, which jsdom cannot
+// measure (every rect is 0×0, so the virtualizer yields no items and no row
+// ever renders). Swap the virtualizer for a pass-through that emits every
+// row — the windowing itself is TanStack's to test, not ours.
+vi.mock('@tanstack/react-virtual', () => ({
+  useVirtualizer: ({ count, estimateSize }: { count: number; estimateSize: () => number }) => {
+    const size = estimateSize()
+    return {
+      getTotalSize: () => count * size,
+      getVirtualItems: () =>
+        Array.from({ length: count }, (_unused, index) => ({
+          index,
+          key: index,
+          start: index * size,
+          size,
+        })),
+    }
+  },
+}))
+
+describe('DataTable selection', () => {
+  it('renders no checkboxes when selection is off', () => {
+    render(<DataTable<Row> query={query(ROWS)} columns={columns} ariaLabel="Records" />)
+    expect(screen.queryByRole('checkbox')).toBeNull()
+  })
+
+  it('select-all toggles every loaded row, then clears', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Harness onChange={onChange} />)
+
+    await user.click(screen.getByRole('checkbox', { name: 'Select all rows' }))
+    expect(onChange).toHaveBeenLastCalledWith(new Set(['r-1', 'r-2', 'r-3']))
+
+    await user.click(screen.getByRole('checkbox', { name: 'Deselect all rows' }))
+    expect(onChange).toHaveBeenLastCalledWith(new Set())
+  })
+
+  it('selecting one row leaves select-all indeterminate', async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+
+    await user.click(screen.getByRole('checkbox', { name: 'Select row 1' }))
+
+    const selectAll = screen.getByRole('checkbox', { name: 'Select all rows' })
+    expect(selectAll).toBePartiallyChecked()
+  })
+
+  it('does not open a row when its checkbox is clicked', async () => {
+    const user = userEvent.setup()
+    const onRowClick = vi.fn()
+    render(
+      <DataTable<Row>
+        query={query(ROWS)}
+        columns={columns}
+        ariaLabel="Records"
+        selectionMode="multiple"
+        selectedIds={new Set()}
+        onSelectionChange={vi.fn()}
+        onRowClick={onRowClick}
+      />,
+    )
+
+    await user.click(screen.getByRole('checkbox', { name: 'Select row 1' }))
+    expect(onRowClick).not.toHaveBeenCalled()
+  })
+})

package/src/components/data-table/data-table.tsx

@@ -24,6 +24,7 @@ import {
 } from 'react'
 
 import { cn } from '../../lib/cn'
+import { Checkbox } from '../checkbox'
 import {
   isColumnDragData,
   type SortDirection,
@@ -138,6 +139,20 @@ export type DataTableProps<TRow> = {
    * at slot='end'. Sits inside the scrollable area below the rows.
    */
   bodyAfter?: ReactNode
+  /**
+   * Row selection. `none` (default) renders no checkbox column; `multiple`
+   * prepends a sticky leading checkbox column and turns the header checkbox
+   * into a tri-state select-all.
+   *
+   * Selection is CONTROLLED — the owner holds the ids because it is the one
+   * that acts on them (running a batch action, clearing after a save). The
+   * header checkbox covers the rows currently LOADED: an infinite list can't
+   * honestly claim to select rows it has never fetched, so "select everything
+   * matching the filter" belongs to the owner's toolbar, not here.
+   */
+  selectionMode?: 'none' | 'multiple'
+  selectedIds?: Set<string>
+  onSelectionChange?: (ids: Set<string>) => void
   /**
    * Draw vertical gridlines between body cells. The header always has them;
    * the body opts in (e.g. inline-edit mode wants the full Excel-style grid).
@@ -148,6 +163,9 @@ export type DataTableProps<TRow> = {
 
 const DEFAULT_ROW_HEIGHT = 32
 
+/** Column id of the leading checkbox column added by `selectionMode`. */
+export const SELECTION_COLUMN_ID = '__select__' 
+
 export function DataTable<TRow>({
   query,
   columns,
@@ -172,6 +190,9 @@ export function DataTable<TRow>({
   extraRows,
   bodyBefore,
   bodyAfter,
+  selectionMode = 'none',
+  selectedIds,
+  onSelectionChange,
   columnBorders = false,
 }: DataTableProps<TRow>) {
   const rows = useMemo<TRow[]>(() => {
@@ -183,21 +204,124 @@ export function DataTable<TRow>({
     return [...startExtras, ...dataRows, ...endExtras]
   }, [query.data, extraRows])
 
+  const resolveRowId = useMemo(
+    () =>
+      getRowId ??
+      ((row: TRow, index: number) => {
+        const r = row as Record<string, unknown>
+        if (typeof r.id === 'string' || typeof r.id === 'number') return String(r.id)
+        if (typeof r.slug === 'string') return r.slug
+        return String(index)
+      }),
+    [getRowId],
+  )
+
+  const selectionEnabled = selectionMode === 'multiple'
+  const selected = useMemo(() => selectedIds ?? new Set<string>(), [selectedIds])
+  // Ids of the rows currently LOADED — what the header checkbox operates on.
+  const loadedIds = useMemo(
+    () => (selectionEnabled ? rows.map((row, index) => resolveRowId(row, index)) : []),
+    [selectionEnabled, rows, resolveRowId],
+  )
+  // Anchor for shift-click range selection, in loaded-row index space.
+  const lastToggledIndexRef = useRef<number | null>(null)
+
+  const toggleRow = (id: string, index: number, isRange: boolean) => {
+    if (!onSelectionChange) return
+    const next = new Set(selected)
+    const anchor = lastToggledIndexRef.current
+    if (isRange && anchor !== null) {
+      const [from, to] = anchor <= index ? [anchor, index] : [index, anchor]
+      // A range drag always ADDS — matching how file managers and mail
+      // clients behave; use individual clicks to take rows back out.
+      for (let i = from; i <= to; i += 1) {
+        const rangeId = loadedIds[i]
+        if (rangeId !== undefined) next.add(rangeId)
+      }
+    } else if (next.has(id)) {
+      next.delete(id)
+    } else {
+      next.add(id)
+    }
+    lastToggledIndexRef.current = index
+    onSelectionChange(next)
+  }
+
+  const loadedSelectedCount = loadedIds.reduce((count, id) => count + (selected.has(id) ? 1 : 0), 0)
+  const allLoadedSelected = loadedIds.length > 0 && loadedSelectedCount === loadedIds.length
+
+  const toggleAllLoaded = () => {
+    if (!onSelectionChange) return
+    const next = new Set(selected)
+    if (allLoadedSelected) {
+      for (const id of loadedIds) next.delete(id)
+    } else {
+      for (const id of loadedIds) next.add(id)
+    }
+    lastToggledIndexRef.current = null
+    onSelectionChange(next)
+  }
+
+  // RAC's Checkbox onChange carries no modifier keys, so the shift state is
+  // captured on the preceding pointer event.
+  const rangeModifierRef = useRef(false)
+
+  const selectionColumn = useMemo<ColumnDef<TRow>>(
+    () => ({
+      id: SELECTION_COLUMN_ID,
+      size: 36,
+      enableSorting: false,
+      meta: { align: 'center', sticky: 'left', cellClassName: 'px-0 justify-center' },
+      header: () => (
+        <span className="inline-flex items-center justify-center w-full">
+          <Checkbox
+            aria-label={allLoadedSelected ? 'Deselect all rows' : 'Select all rows'}
+            isSelected={allLoadedSelected}
+            isIndeterminate={loadedSelectedCount > 0 && !allLoadedSelected}
+            isDisabled={loadedIds.length === 0}
+            onChange={toggleAllLoaded}
+          />
+        </span>
+      ),
+      cell: ({ row }) => (
+        // Stop the click here: selecting a row must never also open it.
+        <span
+          className="inline-flex items-center justify-center w-full"
+          onClick={(event) => event.stopPropagation()}
+          onKeyDown={(event) => {
+            event.stopPropagation()
+            rangeModifierRef.current = event.shiftKey
+          }}
+          onPointerDownCapture={(event) => {
+            rangeModifierRef.current = event.shiftKey
+          }}
+          role="presentation"
+        >
+          <Checkbox
+            aria-label={`Select row ${row.index + 1}`}
+            isSelected={selected.has(row.id)}
+            onChange={() => toggleRow(row.id, row.index, rangeModifierRef.current)}
+          />
+        </span>
+      ),
+    }),
+    // biome-ignore lint/correctness/useExhaustiveDependencies: handlers read the latest selection via closure recreated on these inputs
+    [selected, loadedIds, allLoadedSelected, loadedSelectedCount],
+  )
+
+  const tableColumns = useMemo(
+    () => (selectionEnabled ? [selectionColumn, ...columns] : columns),
+    [selectionEnabled, selectionColumn, columns],
+  )
+
   const table = useReactTable({
     data: rows,
-    columns,
+    columns: tableColumns,
     state: { sorting: sorting ?? [] },
     ...(onSortingChange ? { onSortingChange } : {}),
     manualSorting: true,
     getCoreRowModel: getCoreRowModel(),
-    getRowId: getRowId
-      ? (row, index) => getRowId(row, index)
-      : (row, index) => {
-          const r = row as Record<string, unknown>
-          if (typeof r.id === 'string' || typeof r.id === 'number') return String(r.id)
-          if (typeof r.slug === 'string') return r.slug
-          return String(index)
-        },
+    getRowId: (row, index) => resolveRowId(row, index),
   })
 
   const tableRows = table.getRowModel().rows
@@ -243,8 +367,8 @@ export function DataTable<TRow>({
   })
 
   const totalColumnWidth = useMemo(
-    () => columns.reduce((sum, c) => sum + (c.size ?? 140), 0),
-    [columns],
+    () => tableColumns.reduce((sum, c) => sum + (c.size ?? 140), 0),
+    [tableColumns],
   )
 
   // Single global pragmatic-dnd monitor for column reorder. We mirror the

package/src/components/data-table/index.ts

@@ -7,7 +7,7 @@ export type {
 } from './cells'
 export { BooleanCell, DateCell, DateTimeCell, LinkCell, TruncateCell } from './cells'
 export type { DataTableProps, InfiniteQueryLike } from './data-table'
-export { DataTable } from './data-table'
+export { DataTable, SELECTION_COLUMN_ID } from './data-table'
 
 export type { ActionsColumnOptions } from './make-actions-column'
 export { makeActionsColumn } from './make-actions-column'

package/src/test/setup.ts

@@ -4,6 +4,36 @@ import { afterEach, expect } from 'vitest'
 
 expect.extend(matchers)
 
+// jsdom implements neither Element.scrollTo nor IntersectionObserver, both of
+// which the virtualized DataTable calls on mount. Stub them so scrolling
+// components can be rendered in tests at all.
+if (!Element.prototype.scrollTo) {
+  Element.prototype.scrollTo = () => {}
+}
+if (!('ResizeObserver' in globalThis)) {
+  class NoopResizeObserver implements ResizeObserver {
+    disconnect() {}
+    observe() {}
+    unobserve() {}
+  }
+  globalThis.ResizeObserver = NoopResizeObserver as unknown as typeof ResizeObserver
+}
+if (!('IntersectionObserver' in globalThis)) {
+  class NoopIntersectionObserver implements IntersectionObserver {
+    readonly root = null
+    readonly rootMargin = ''
+    readonly thresholds: ReadonlyArray<number> = []
+    disconnect() {}
+    observe() {}
+    unobserve() {}
+    takeRecords(): IntersectionObserverEntry[] {
+      return []
+    }
+  }
+  globalThis.IntersectionObserver =
+    NoopIntersectionObserver as unknown as typeof IntersectionObserver
+}
+
 afterEach(() => {
   cleanup()
 })