@spree/dashboard-ui 0.1.0

package/src/spree/data-grid/data-grid.tsx

@@ -0,0 +1,214 @@
+import {
+  flexRender,
+  getCoreRowModel,
+  type Row,
+  type Table,
+  type TableOptions,
+  useReactTable,
+} from '@tanstack/react-table'
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { cn } from '../../lib/utils'
+import { coordsInRect, DataGridContext, type DataGridContextValue } from './context'
+import { FillHandle } from './fill-handle'
+import type { CellCoords, CellKey, CellRegistration, RenderSectionHeader } from './types'
+import { cellKey } from './types'
+import { useDataGridKeyboard } from './use-data-grid-keyboard'
+
+interface DataGridProps<T> {
+  rows: T[]
+  columns: TableOptions<T>['columns']
+  getRowId: (row: T) => string
+  /** Optional grouping. Return a node spanning all columns to render this row
+   *  as a (non-editable) section header. Return null to render the row as
+   *  normal editable cells. */
+  renderSectionHeader?: RenderSectionHeader<T>
+  /** Optional className on the outer table. */
+  className?: string
+  /** Optional caption-row aria-label etc. */
+  'aria-label'?: string
+}
+
+export function DataGrid<T>({
+  rows,
+  columns,
+  getRowId,
+  renderSectionHeader,
+  className,
+  'aria-label': ariaLabel,
+}: DataGridProps<T>) {
+  const table = useReactTable<T>({
+    data: rows,
+    columns,
+    getRowId,
+    getCoreRowModel: getCoreRowModel(),
+  })
+
+  return (
+    <DataGridShell
+      table={table}
+      renderSectionHeader={renderSectionHeader}
+      className={className}
+      ariaLabel={ariaLabel}
+    />
+  )
+}
+
+function DataGridShell<T>({
+  table,
+  renderSectionHeader,
+  className,
+  ariaLabel,
+}: {
+  table: Table<T>
+  renderSectionHeader?: RenderSectionHeader<T>
+  className?: string
+  ariaLabel?: string
+}) {
+  const gridRef = useRef<HTMLTableElement | null>(null)
+  const cellsRef = useRef<Map<CellKey, CellRegistration>>(new Map())
+  const [bounds, setBounds] = useState<{ maxRow: number; maxCol: number }>({ maxRow: 0, maxCol: 0 })
+  const [anchor, setAnchor] = useState<CellCoords | null>(null)
+  const [extent, setExtent] = useState<CellCoords | null>(null)
+  const [editing, setEditing] = useState<CellCoords | null>(null)
+
+  const recomputeBounds = useCallback(() => {
+    let maxRow = 0
+    let maxCol = 0
+    for (const reg of cellsRef.current.values()) {
+      if (reg.coords.row > maxRow) maxRow = reg.coords.row
+      if (reg.coords.col > maxCol) maxCol = reg.coords.col
+    }
+    setBounds((prev) =>
+      prev.maxRow === maxRow && prev.maxCol === maxCol ? prev : { maxRow, maxCol },
+    )
+  }, [])
+
+  const registerCell = useCallback(
+    (reg: CellRegistration) => {
+      const key = cellKey(reg.coords)
+      cellsRef.current.set(key, reg)
+      recomputeBounds()
+      return () => {
+        cellsRef.current.delete(key)
+        recomputeBounds()
+      }
+    },
+    [recomputeBounds],
+  )
+
+  const isSelected = useCallback(
+    (coords: CellCoords) => coordsInRect(coords, anchor, extent),
+    [anchor, extent],
+  )
+
+  const selectedCells = useCallback((): CellRegistration[] => {
+    if (!anchor || !extent) return []
+    const out: CellRegistration[] = []
+    for (const reg of cellsRef.current.values()) {
+      if (coordsInRect(reg.coords, anchor, extent)) out.push(reg)
+    }
+    return out
+  }, [anchor, extent])
+
+  const ctx: DataGridContextValue = useMemo(
+    () => ({
+      cells: cellsRef.current,
+      bounds,
+      anchor,
+      extent,
+      editing,
+      setAnchor,
+      setExtent,
+      setEditing,
+      registerCell,
+      isSelected,
+      selectedCells,
+    }),
+    [bounds, anchor, extent, editing, registerCell, isSelected, selectedCells],
+  )
+
+  return (
+    <DataGridContext.Provider value={ctx}>
+      <DataGridKeyboardMount gridRef={gridRef} />
+      <div className="relative overflow-hidden rounded-md">
+        <table
+          ref={gridRef}
+          className={cn(
+            'w-full border-collapse text-sm [&_td]:border [&_th]:border [&_td]:border-border [&_th]:border-border',
+            className,
+          )}
+          aria-label={ariaLabel}
+          onBlurCapture={(e) => {
+            // If focus leaves the grid entirely, drop the selection so a
+            // fresh focus-in starts clean.
+            const next = e.relatedTarget as Node | null
+            if (next && gridRef.current?.contains(next)) return
+            setAnchor(null)
+            setExtent(null)
+            setEditing(null)
+          }}
+        >
+          <thead className="sticky top-0 z-10 bg-muted/60 text-xs text-muted-foreground">
+            {table.getHeaderGroups().map((group) => (
+              <tr key={group.id}>
+                {group.headers.map((header) => (
+                  <th key={header.id} className="h-8 px-3 text-left font-medium">
+                    {header.isPlaceholder
+                      ? null
+                      : flexRender(header.column.columnDef.header, header.getContext())}
+                  </th>
+                ))}
+              </tr>
+            ))}
+          </thead>
+          <tbody>
+            {table.getRowModel().rows.map((row) => (
+              <DataGridRow
+                key={row.id}
+                row={row}
+                renderSectionHeader={renderSectionHeader}
+                columnCount={table.getAllColumns().length}
+              />
+            ))}
+          </tbody>
+        </table>
+        <FillHandle gridRef={gridRef} />
+      </div>
+    </DataGridContext.Provider>
+  )
+}
+
+function DataGridRow<T>({
+  row,
+  renderSectionHeader,
+  columnCount,
+}: {
+  row: Row<T>
+  renderSectionHeader?: RenderSectionHeader<T>
+  columnCount: number
+}) {
+  const headerContent = renderSectionHeader?.(row.original)
+  if (headerContent) {
+    return (
+      <tr>
+        <td colSpan={columnCount} className="bg-muted/60 px-3 py-2 text-sm">
+          {headerContent}
+        </td>
+      </tr>
+    )
+  }
+  return (
+    <tr>
+      {row.getVisibleCells().map((cell) => (
+        <td key={cell.id} className="h-9 p-0 align-middle">
+          {flexRender(cell.column.columnDef.cell, cell.getContext())}
+        </td>
+      ))}
+    </tr>
+  )
+}
+
+function DataGridKeyboardMount({ gridRef }: { gridRef: React.RefObject<HTMLElement | null> }) {
+  useDataGridKeyboard(gridRef)
+  return null
+}

package/src/spree/data-grid/fill-handle.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useState } from 'react'
+import { useDataGridContext } from './context'
+import type { CellCoords, CellKey } from './types'
+import { cellKey } from './types'
+
+/**
+ * Excel-style fill handle. Renders a 9×9 square anchored to the
+ * bottom-right of the cell that's the current selection's far corner.
+ * Pointer-drag from the handle expands the selection rectangle; on
+ * release we copy the anchor cell's value into every other cell in
+ * the rectangle (skipping cells whose `canWrite` rejects the value).
+ *
+ * Positioning is absolute over the grid's `<table>`. The handle reads
+ * the far-corner cell's bounding rect via `getElement()` (provided by
+ * each cell's registration) and the table's own rect, then offsets so
+ * the handle sits inside the cell's corner.
+ */
+export function FillHandle({ gridRef }: { gridRef: React.RefObject<HTMLElement | null> }) {
+  const ctx = useDataGridContext()
+  const { anchor, extent, cells, editing } = ctx
+
+  // Local drag state — null when idle.
+  const [drag, setDrag] = useState<{
+    sourceKey: CellKey
+    sourceValue: string
+    /** The current rect we're previewing as the fill target. */
+    preview: { row: number; col: number } | null
+  } | null>(null)
+  const [tick, setTick] = useState(0)
+  // Re-measure on scroll/resize so the handle follows the cell.
+  useEffect(() => {
+    function bump() {
+      setTick((t) => t + 1)
+    }
+    window.addEventListener('resize', bump)
+    window.addEventListener('scroll', bump, true)
+    return () => {
+      window.removeEventListener('resize', bump)
+      window.removeEventListener('scroll', bump, true)
+    }
+  }, [])
+
+  // Hide the handle while editing or when there's no selection.
+  if (!anchor || !extent || editing) return null
+
+  // Far corner of the current selection (the cell whose bottom-right
+  // gets the handle). Drag previews use the same anchor as the source.
+  const farRow = Math.max(anchor.row, extent.row)
+  const farCol = Math.max(anchor.col, extent.col)
+  const farReg = cells.get(cellKey({ row: farRow, col: farCol }))
+  const farEl = farReg?.getElement?.()
+  const gridEl = gridRef.current
+  if (!farEl || !gridEl) return null
+
+  // Position relative to the gridEl's positioning context. Use offsetParent
+  // math through getBoundingClientRect for portability.
+  const farRect = farEl.getBoundingClientRect()
+  const gridRect = gridEl.getBoundingClientRect()
+  // Sit the handle so its center is exactly on the cell's bottom-right corner.
+  const left = farRect.right - gridRect.left - 4
+  const top = farRect.bottom - gridRect.top - 4
+
+  function onPointerDown(e: React.PointerEvent<HTMLDivElement>) {
+    e.preventDefault()
+    e.stopPropagation()
+    // Source is always the *anchor* — that's what users instinctively
+    // expect to be copied. If they had a multi-cell selection going,
+    // we still copy from the anchor (top-left), matching Excel.
+    const sourceReg = cells.get(cellKey(anchor!))
+    if (!sourceReg) return
+    const sourceValue = sourceReg.read()
+    setDrag({
+      sourceKey: cellKey(anchor!),
+      sourceValue,
+      preview: { row: farRow, col: farCol },
+    })
+    // Capture pointer so we keep getting move events even outside the
+    // handle div.
+    e.currentTarget.setPointerCapture(e.pointerId)
+  }
+
+  function onPointerMove(e: React.PointerEvent<HTMLDivElement>) {
+    if (!drag) return
+    // Hit-test the cell under the pointer.
+    const target = document.elementFromPoint(e.clientX, e.clientY)
+    if (!target) return
+    // Walk up from the hit target looking for a cell with a known
+    // coords attribute. We don't tag DOM nodes, so do it by linear scan
+    // through the registry — small (<a few hundred cells per grid).
+    let hit: CellCoords | null = null
+    for (const reg of cells.values()) {
+      const el = reg.getElement?.()
+      if (el?.contains(target as Node)) {
+        hit = reg.coords
+        break
+      }
+    }
+    if (!hit) return
+    // Constrain to the same column as the source (Excel: fill flows
+    // down a column by default). Allow row movement only.
+    setDrag({
+      ...drag,
+      preview: { row: hit.row, col: anchor!.col },
+    })
+    // Drive the grid's extent so the standard selection highlight
+    // matches the preview region.
+    ctx.setExtent({ row: hit.row, col: anchor!.col })
+  }
+
+  function onPointerUp() {
+    if (!drag) return
+    const preview = drag.preview
+    if (preview) {
+      const minRow = Math.min(anchor!.row, preview.row)
+      const maxRow = Math.max(anchor!.row, preview.row)
+      // Copy into every cell in the column range, skipping the source.
+      for (let r = minRow; r <= maxRow; r += 1) {
+        if (r === anchor!.row) continue
+        const reg = cells.get(cellKey({ row: r, col: anchor!.col }))
+        if (!reg) continue
+        if (reg.canWrite(drag.sourceValue)) reg.write(drag.sourceValue)
+      }
+    }
+    setDrag(null)
+  }
+
+  // The `tick` value forces position re-measurement when the table
+  // reflows. Read it once so React doesn't optimize the var away.
+  void tick
+
+  return (
+    <div
+      // biome-ignore lint/a11y/useSemanticElements: this is a drag handle, not actionable on its own
+      role="presentation"
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={onPointerUp}
+      style={{
+        position: 'absolute',
+        left,
+        top,
+        width: 9,
+        height: 9,
+        zIndex: 20,
+        background: 'rgb(59 130 246)',
+        border: '1px solid white',
+        cursor: 'crosshair',
+        boxShadow: '0 0 0 1px rgba(0,0,0,0.1)',
+      }}
+      aria-hidden
+    />
+  )
+}

package/src/spree/data-grid/helpers.ts

@@ -0,0 +1,18 @@
+/**
+ * Counts editable (non-header) rows up to and including the given row id so
+ * the cell at that position has stable grid coords that exclude section
+ * headers. Used by every spreadsheet that mixes a `renderSectionHeader`
+ * with `<NumberCell>` / `<MoneyCell>` etc.
+ */
+export function editableRowIndex<T extends { kind: 'header' | 'item'; id: string }>(
+  rows: ReadonlyArray<{ id: string; original: T }>,
+  rowId: string,
+): number {
+  let i = 0
+  for (const row of rows) {
+    if (row.original.kind !== 'item') continue
+    if (row.id === rowId) return i
+    i++
+  }
+  return i
+}

package/src/spree/data-grid/index.ts

@@ -0,0 +1,5 @@
+export { MoneyCell, NumberCell, ReadOnlyCell, SelectCell, SwitchCell } from './cells'
+export { useDataGridContext } from './context'
+export { DataGrid } from './data-grid'
+export { editableRowIndex } from './helpers'
+export type { CellCoords, RenderSectionHeader } from './types'

package/src/spree/data-grid/types.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react'
+
+/** Cell coords used for keyboard navigation and selection.
+ *  `row` is a flat row index across the rendered table (after section
+ *  headers are inserted); `col` is the column index in the editable order. */
+export interface CellCoords {
+  row: number
+  col: number
+}
+
+export type CellKey = `${number}.${number}`
+
+export function cellKey(coords: CellCoords): CellKey {
+  return `${coords.row}.${coords.col}`
+}
+
+export type GridMode = 'select' | 'edit'
+
+export interface CellRegistration {
+  coords: CellCoords
+  /** Imperatively focus the cell's interactive element. */
+  focus: () => void
+  /** Read the current display value (for copy / fill-down). */
+  read: () => string
+  /** Write a new value (for paste / fill-down / clear). */
+  write: (value: string) => void
+  /** Whether this cell accepts a write — Switch cells, for example, only
+   *  accept "true" / "false" / "" so we can no-op on non-boolean pastes. */
+  canWrite: (value: string) => boolean
+  /** Resolve the cell's interactive root element. Used by the fill
+   *  handle to measure positions and hit-test drag targets. */
+  getElement?: () => HTMLElement | null
+}
+
+/** Public render-prop API for grouped rows (e.g. "Variant: Small / Navy"). */
+export type RenderSectionHeader<T> = (row: T) => ReactNode | null

package/src/spree/data-grid/use-data-grid-keyboard.ts

@@ -0,0 +1,254 @@
+import { useHotkey } from '@tanstack/react-hotkeys'
+import type { RefObject } from 'react'
+import { useDataGridContext } from './context'
+import type { CellCoords } from './types'
+
+/** Mounts grid-wide keyboard bindings scoped to a container ref. */
+export function useDataGridKeyboard(gridRef: RefObject<HTMLElement | null>) {
+  const ctx = useDataGridContext()
+  const target = gridRef
+
+  function focusCoords(coords: CellCoords) {
+    const cell = ctx.cells.get(`${coords.row}.${coords.col}`)
+    cell?.focus()
+  }
+
+  function navigate(dx: number, dy: number) {
+    const from = ctx.anchor
+    if (!from) return
+    // Clamp inside the grid, no wrap-around.
+    let row = from.row + dy
+    let col = from.col + dx
+    row = Math.max(0, Math.min(ctx.bounds.maxRow, row))
+    col = Math.max(0, Math.min(ctx.bounds.maxCol, col))
+    // If the target slot has no registered cell (e.g. a sparse row where the
+    // column index doesn't render), find the nearest existing cell in the
+    // direction of travel. Falls back to the original if nothing is reachable.
+    const next = findExistingCoords({ row, col }, dx, dy)
+    if (!next) return
+    ctx.setAnchor(next)
+    ctx.setExtent(next)
+    ctx.setEditing(null)
+    focusCoords(next)
+  }
+
+  function extendSelection(dx: number, dy: number) {
+    const from = ctx.extent ?? ctx.anchor
+    if (!from) return
+    let row = from.row + dy
+    let col = from.col + dx
+    row = Math.max(0, Math.min(ctx.bounds.maxRow, row))
+    col = Math.max(0, Math.min(ctx.bounds.maxCol, col))
+    const next = findExistingCoords({ row, col }, dx, dy)
+    if (!next) return
+    ctx.setExtent(next)
+    focusCoords(next)
+  }
+
+  function findExistingCoords(start: CellCoords, dx: number, dy: number): CellCoords | null {
+    if (ctx.cells.has(`${start.row}.${start.col}`)) return start
+    // Step in the direction of travel until we find a registered cell or
+    // run out of grid. Bounded by maxRow*maxCol steps.
+    let row = start.row
+    let col = start.col
+    for (let i = 0; i < (ctx.bounds.maxRow + 1) * (ctx.bounds.maxCol + 1); i++) {
+      row += dy === 0 ? 0 : dy
+      col += dx === 0 ? 0 : dx
+      // If we're walking pure-row, also step columns to find sparse hits.
+      if (dx === 0 && dy === 0) return null
+      if (row < 0 || col < 0 || row > ctx.bounds.maxRow || col > ctx.bounds.maxCol) return null
+      if (ctx.cells.has(`${row}.${col}`)) return { row, col }
+    }
+    return null
+  }
+
+  // Selection-mode navigation. Edit-mode is handled inside the cell itself
+  // (Enter / Esc / Tab there route to the grid via callbacks).
+  useHotkey('ArrowUp', () => navigate(0, -1), {
+    target,
+    ignoreInputs: false,
+    enabled: !ctx.editing,
+  })
+  useHotkey('ArrowDown', () => navigate(0, 1), {
+    target,
+    ignoreInputs: false,
+    enabled: !ctx.editing,
+  })
+  useHotkey('ArrowLeft', () => navigate(-1, 0), {
+    target,
+    ignoreInputs: false,
+    enabled: !ctx.editing,
+  })
+  useHotkey('ArrowRight', () => navigate(1, 0), {
+    target,
+    ignoreInputs: false,
+    enabled: !ctx.editing,
+  })
+
+  useHotkey('Shift+ArrowUp', () => extendSelection(0, -1), {
+    target,
+    ignoreInputs: false,
+    enabled: !ctx.editing,
+  })
+  useHotkey('Shift+ArrowDown', () => extendSelection(0, 1), {
+    target,
+    ignoreInputs: false,
+    enabled: !ctx.editing,
+  })
+  useHotkey('Shift+ArrowLeft', () => extendSelection(-1, 0), {
+    target,
+    ignoreInputs: false,
+    enabled: !ctx.editing,
+  })
+  useHotkey('Shift+ArrowRight', () => extendSelection(1, 0), {
+    target,
+    ignoreInputs: false,
+    enabled: !ctx.editing,
+  })
+
+  // Tab: navigate within the grid; let the browser handle when at the edge
+  // so the user can Tab past the grid into the next form field.
+  useHotkey(
+    'Tab',
+    (event) => {
+      const from = ctx.anchor
+      if (!from) return
+      const atLastCell = from.row === ctx.bounds.maxRow && from.col === ctx.bounds.maxCol
+      if (atLastCell) return // let browser focus the next form field
+      event.preventDefault()
+      navigate(1, 0)
+      // If we just walked off the right edge, wrap to the next row.
+      const next = ctx.anchor
+      if (next && next.row === from.row && next.col === from.col) {
+        navigate(-ctx.bounds.maxCol, 1)
+      }
+    },
+    { target, ignoreInputs: false, preventDefault: false, enabled: !ctx.editing },
+  )
+  useHotkey(
+    'Shift+Tab',
+    (event) => {
+      const from = ctx.anchor
+      if (!from) return
+      const atFirst = from.row === 0 && from.col === 0
+      if (atFirst) return // let browser walk focus backward out of the grid
+      event.preventDefault()
+      navigate(-1, 0)
+    },
+    { target, ignoreInputs: false, preventDefault: false, enabled: !ctx.editing },
+  )
+
+  // Enter — toggle into edit mode for the focused cell.
+  useHotkey(
+    'Enter',
+    () => {
+      if (ctx.anchor) ctx.setEditing(ctx.anchor)
+    },
+    { target, ignoreInputs: false, enabled: !ctx.editing },
+  )
+
+  // Escape — clear selection. (Edit-mode Escape is handled inside the cell
+  // since it needs to revert the in-flight value before exiting.)
+  useHotkey(
+    'Escape',
+    () => {
+      ctx.setExtent(ctx.anchor)
+    },
+    { target, ignoreInputs: false, enabled: !ctx.editing },
+  )
+
+  // Delete / Backspace — clear all selected cells. Skipped while editing
+  // so the user can use these keys to edit text.
+  function clearSelected() {
+    for (const cell of ctx.selectedCells()) {
+      if (cell.canWrite('')) cell.write('')
+    }
+  }
+  useHotkey('Delete', clearSelected, { target, ignoreInputs: false, enabled: !ctx.editing })
+  useHotkey('Backspace', clearSelected, { target, ignoreInputs: false, enabled: !ctx.editing })
+
+  // Cmd/Ctrl+D — fill down: take the top-most cell of each selected column
+  // and broadcast its value to the rest of that column's selection.
+  useHotkey(
+    'Mod+D',
+    () => {
+      const cells = ctx.selectedCells()
+      if (cells.length < 2) return
+      const byCol = new Map<number, typeof cells>()
+      for (const c of cells) {
+        const arr = byCol.get(c.coords.col) ?? []
+        arr.push(c)
+        byCol.set(c.coords.col, arr)
+      }
+      for (const colCells of byCol.values()) {
+        colCells.sort((a, b) => a.coords.row - b.coords.row)
+        const source = colCells[0].read()
+        for (let i = 1; i < colCells.length; i++) {
+          if (colCells[i].canWrite(source)) colCells[i].write(source)
+        }
+      }
+    },
+    { target, ignoreInputs: false, enabled: !ctx.editing },
+  )
+
+  // Cmd/Ctrl+C — write the selection to the OS clipboard as TSV.
+  useHotkey(
+    'Mod+C',
+    async () => {
+      const cells = ctx.selectedCells()
+      if (cells.length === 0) return
+      const rows = new Map<number, Map<number, string>>()
+      let minCol = Infinity
+      let maxCol = -Infinity
+      for (const c of cells) {
+        const row = rows.get(c.coords.row) ?? new Map()
+        row.set(c.coords.col, c.read())
+        rows.set(c.coords.row, row)
+        if (c.coords.col < minCol) minCol = c.coords.col
+        if (c.coords.col > maxCol) maxCol = c.coords.col
+      }
+      const rowKeys = Array.from(rows.keys()).sort((a, b) => a - b)
+      const tsv = rowKeys
+        .map((r) => {
+          const row = rows.get(r)
+          const out: string[] = []
+          for (let col = minCol; col <= maxCol; col++) {
+            out.push(row?.get(col) ?? '')
+          }
+          return out.join('\t')
+        })
+        .join('\n')
+      try {
+        await navigator.clipboard.writeText(tsv)
+      } catch {
+        // Clipboard write may fail in non-secure contexts or when the page
+        // doesn't have focus. Silent — the alternative is a noisy toast on
+        // a routine Cmd+C and there's no recovery path here.
+      }
+    },
+    { target, ignoreInputs: false, enabled: !ctx.editing },
+  )
+
+  // Cmd/Ctrl+V — broadcast a single clipboard value to all selected cells.
+  // Multi-cell TSV paste with row/col pattern matching is deferred.
+  useHotkey(
+    'Mod+V',
+    async () => {
+      const cells = ctx.selectedCells()
+      if (cells.length === 0) return
+      let text = ''
+      try {
+        text = await navigator.clipboard.readText()
+      } catch {
+        return
+      }
+      // First-pass: only use the first line, first column of whatever was on
+      // the clipboard. Excel TSV will collapse cleanly to its first cell.
+      const value = text.split('\n')[0]?.split('\t')[0] ?? ''
+      for (const c of cells) {
+        if (c.canWrite(value)) c.write(value)
+      }
+    },
+    { target, ignoreInputs: false, enabled: !ctx.editing },
+  )
+}