ui/data-grid.tsx
GitHub'use client';
import * as React from 'react';
import {Icon, Checkmark} from '../icon';
import {cn} from '../lib/utils';
import {Checkbox} from './checkbox';
import {Input} from './input';
import {Kbd} from './kbd';
import {Popover, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger} from './popover';
import {Select, SelectContent, SelectItem, SelectTrigger, SelectValue} from './select';
import {Status, StatusArc} from './status';
import {Table, TableBody, TableCell, TableHead, TableHeader, TableRow} from './table';
import {Textarea} from './textarea';
type CellValue = string | number | boolean | null;
type CellOption = {value: string; label: string};
type CellEditor = 'text' | 'long-text' | 'number' | 'select' | 'boolean';
type CellSaveState = {state: 'idle' | 'saving' | 'saved' | 'error'; message?: string};
type CellPosition = {row: number; col: number};
type MoveAfterEdit = 'down' | 'right' | 'left';
type CellEntry = {
id: string;
label: string;
value: CellValue;
editor?: CellEditor;
options?: CellOption[];
text: string;
editable: boolean;
onCommit?: (value: CellValue) => unknown;
};
type Editing = CellPosition & {draft: string; via: 'inline' | 'popover' | 'select'};
const SAVED_FOR = 1600;
const posKey = (p: CellPosition) => `${p.row}:${p.col}`;
function formatCellValue(value: CellValue | undefined, editor?: CellEditor, options?: CellOption[]): string {
if (value == null) return '';
if (editor === 'boolean' || typeof value === 'boolean') return value ? 'Yes' : 'No';
if (editor === 'select') return options?.find(o => o.value === value)?.label ?? String(value);
return String(value);
}
function parseCellValue(text: string, editor?: CellEditor, options?: CellOption[]): CellValue {
const t = text.trim();
if (t === '') return null;
if (editor === 'number') return Number.isFinite(Number(t)) ? Number(t) : t;
if (editor === 'boolean') return /^(true|yes|y|1|x)$/i.test(t);
if (editor === 'select') return options?.find(o => o.value === t || o.label.toLowerCase() === t.toLowerCase())?.value ?? t;
return text;
}
type DataGridContextValue = {
active: CellPosition;
editing: Editing | null;
focused: boolean;
readOnly: boolean;
rowCount: number;
colCount: number;
focusableHeader: boolean;
setActive: (p: CellPosition) => void;
move: (p: CellPosition) => void;
startEdit: (p: CellPosition, seed?: string) => void;
endEdit: (commit: boolean, then?: MoveAfterEdit, value?: string) => void;
setDraft: (draft: string) => void;
register: (p: CellPosition, entry: React.RefObject<CellEntry>) => () => void;
entryAt: (p: CellPosition) => CellEntry | undefined;
commit: (entry: CellEntry, value: CellValue) => void;
statusOf: (id: string) => CellSaveState | undefined;
saving: boolean;
copy: () => void;
announce: (text: string) => void;
itemProps: (p: CellPosition) => {'data-cell': string; tabIndex: number; onFocus: (event: React.FocusEvent<HTMLElement>) => void};
cellElement: (p: CellPosition) => HTMLElement | null;
setFocused: (focused: boolean) => void;
helpId: string;
};
const DataGridContext = React.createContext<DataGridContextValue | null>(null);
function useDataGrid() {
const ctx = React.useContext(DataGridContext);
if (!ctx) throw new Error('useDataGrid must be used inside <DataGrid>.');
return ctx;
}
type DataGridProps = Omit<React.ComponentProps<'div'>, 'onChange'> & {
rowCount: number;
colCount: number;
focusableHeader?: boolean;
readOnly?: boolean;
activeCell?: CellPosition;
defaultActiveCell?: CellPosition;
onActiveCellChange?: (cell: CellPosition) => void;
};
function DataGrid({
rowCount, colCount, focusableHeader = false, readOnly = false, activeCell, defaultActiveCell, onActiveCellChange,
className, children, ...props
}: DataGridProps) {
const helpId = React.useId();
const rootRef = React.useRef<HTMLDivElement>(null);
const [ownActive, setOwnActive] = React.useState<CellPosition>(defaultActiveCell ?? {row: 0, col: 0});
const [editing, setEditingState] = React.useState<Editing | null>(null);
const editingRef = React.useRef<Editing | null>(null);
const [focused, setFocused] = React.useState(false);
const [status, setStatus] = React.useState<Record<string, CellSaveState>>({});
const [announcement, setAnnouncement] = React.useState('');
const focusNext = React.useRef(false);
const cells = React.useRef(new Map<string, React.RefObject<CellEntry>>());
const timers = React.useRef(new Map<string, number>());
const minRow = focusableHeader ? -1 : 0;
const clamp = (p: CellPosition): CellPosition => ({
row: Math.max(minRow, Math.min(rowCount - 1, p.row)),
col: Math.max(0, Math.min(colCount - 1, p.col)),
});
const active = clamp(activeCell ?? ownActive);
const setEditing = (next: Editing | null) => {
editingRef.current = next;
setEditingState(next);
};
const setActive = (p: CellPosition) => {
const next = clamp(p);
if (activeCell === undefined) setOwnActive(next);
if (next.row !== active.row || next.col !== active.col) onActiveCellChange?.(next);
};
const cellElement = (p: CellPosition) => rootRef.current?.querySelector<HTMLElement>(`[data-cell="${posKey(p)}"]`) ?? null;
React.useEffect(() => {
if (!focusNext.current) return;
focusNext.current = false;
const el = cellElement(active);
if (!el) return;
el.focus();
el.scrollIntoView?.({block: 'nearest', inline: 'nearest'});
requestAnimationFrame(() => { if (document.activeElement !== el && el.isConnected && !editingRef.current) el.focus(); });
});
React.useEffect(() => () => { timers.current.forEach(t => window.clearTimeout(t)); }, []);
const announce = (text: string) => {
setAnnouncement('');
requestAnimationFrame(() => setAnnouncement(text));
};
const move = (p: CellPosition) => {
focusNext.current = true;
setActive(p);
};
const entryAt = (p: CellPosition) => cells.current.get(posKey(p))?.current;
const commit = (entry: CellEntry, value: CellValue) => {
if (!entry.onCommit) return;
const id = entry.id;
const result = entry.onCommit(value);
if (!result || typeof (result as Promise<unknown>).then !== 'function') return;
window.clearTimeout(timers.current.get(id));
setStatus(s => ({...s, [id]: {state: 'saving'}}));
announce(`Saving ${entry.label}`);
(result as Promise<unknown>).then(
() => {
setStatus(s => ({...s, [id]: {state: 'saved'}}));
announce(`Saved ${entry.label}`);
timers.current.set(id, window.setTimeout(() => setStatus(s => {
if (s[id]?.state !== 'saved') return s;
const next = {...s};
delete next[id];
return next;
}), SAVED_FOR));
},
(error: unknown) => {
const message = error instanceof Error ? error.message : 'Could not save';
setStatus(s => ({...s, [id]: {state: 'error', message}}));
announce(`${entry.label} not saved. ${message}`);
},
);
};
const startEdit = (p: CellPosition, seed?: string) => {
if (readOnly || p.row < 0) return;
const entry = entryAt(p);
if (!entry?.editable || !entry.editor) return;
if (entry.editor === 'boolean') { commit(entry, !entry.value); return; }
const via = entry.editor === 'select' ? 'select' : entry.editor === 'long-text' ? 'popover' : 'inline';
setEditing({...p, via, draft: seed ?? (entry.value == null ? '' : String(entry.value))});
};
const endEdit = (save: boolean, then?: MoveAfterEdit, value?: string) => {
const current = editingRef.current;
if (!current) return;
const entry = entryAt(current);
if (save && entry) {
const next = parseCellValue(value ?? current.draft, entry.editor, entry.options);
if (next !== (entry.value ?? null)) commit(entry, next);
}
setEditing(null);
focusNext.current = true;
const p = {row: current.row, col: current.col};
setActive(then === 'down' ? {...p, row: p.row + 1} : then === 'right' ? {...p, col: p.col + 1} : then === 'left' ? {...p, col: p.col - 1} : p);
};
const setDraft = (draft: string) => {
if (editingRef.current) setEditing({...editingRef.current, draft});
};
const copy = () => {
const entry = active.row >= 0 ? entryAt(active) : undefined;
if (!entry) return;
navigator.clipboard?.writeText(entry.text).catch(() => {});
announce(entry.text ? `Copied ${entry.text.length > 40 ? `${entry.text.slice(0, 40)}…` : entry.text}` : 'Copied an empty cell');
};
const register = React.useCallback((p: CellPosition, entry: React.RefObject<CellEntry>) => {
const key = posKey(p);
cells.current.set(key, entry);
return () => { if (cells.current.get(key) === entry) cells.current.delete(key); };
}, []);
const itemProps = (p: CellPosition) => ({
'data-cell': posKey(p),
tabIndex: active.row === p.row && active.col === p.col && !(editing && editing.row === p.row && editing.col === p.col) ? 0 : -1,
onFocus: (event: React.FocusEvent<HTMLElement>) => { if (event.target === event.currentTarget) setActive(p); },
});
const ctx: DataGridContextValue = {
active, editing, focused, readOnly, rowCount, colCount, focusableHeader,
setActive, move, startEdit, endEdit, setDraft, register, entryAt, commit,
statusOf: id => status[id], saving: Object.values(status).some(s => s.state === 'saving'), copy, announce, itemProps, cellElement, setFocused, helpId,
};
return <DataGridContext.Provider value={ctx}>
<div ref={rootRef} data-slot="data-grid" className={cn('flex min-w-0 flex-col gap-3', className)} {...props}>
{children}
<p role="status" aria-live="polite" className="sr-only">{announcement}</p>
</div>
</DataGridContext.Provider>;
}
type DataGridTableProps = React.ComponentProps<typeof Table> & {
'aria-label': string;
};
function DataGridTable({className, size = 'sm', onKeyDownCapture, onPaste, onFocus, onBlur, ...props}: DataGridTableProps) {
const grid = useDataGrid();
const {active, editing, readOnly, rowCount, colCount, focusableHeader} = grid;
const onKeyDown = (event: React.KeyboardEvent<HTMLTableElement>) => {
onKeyDownCapture?.(event);
if (event.defaultPrevented || editing) return;
const target = event.target as HTMLElement;
if (!target.closest('[data-cell]')) return;
const mod = event.metaKey || event.ctrlKey;
const {row, col} = active;
if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown'].includes(event.key)) {
event.preventDefault();
event.stopPropagation();
}
switch (event.key) {
case 'ArrowUp': grid.move({row: row - 1, col}); return;
case 'ArrowDown': grid.move({row: row + 1, col}); return;
case 'ArrowLeft': grid.move({row, col: col - 1}); return;
case 'ArrowRight': grid.move({row, col: col + 1}); return;
case 'Home': grid.move(mod ? {row: 0, col: 0} : {row, col: 0}); return;
case 'End': grid.move(mod ? {row: rowCount - 1, col: colCount - 1} : {row, col: colCount - 1}); return;
case 'PageDown': grid.move({row: row + 10, col}); return;
case 'PageUp': grid.move({row: Math.max(0, row - 10), col}); return;
}
if (row < 0) return;
if (mod && event.key.toLowerCase() === 'c') { event.preventDefault(); grid.copy(); return; }
if (mod) return;
const entry = grid.entryAt(active);
if (event.key === 'Enter' || event.key === 'F2') { event.preventDefault(); grid.startEdit(active); return; }
if (!entry?.editable || readOnly) return;
if (event.key === ' ' && entry.editor === 'boolean') { event.preventDefault(); grid.startEdit(active); return; }
if (event.key === 'Delete' || event.key === 'Backspace') {
if (entry.editor !== 'boolean') { event.preventDefault(); if (entry.value != null && entry.value !== '') grid.commit(entry, null); }
return;
}
if (event.key.length === 1 && !event.altKey) {
if (entry.editor === 'text' || entry.editor === 'long-text' || entry.editor === 'number') { event.preventDefault(); grid.startEdit(active, event.key); }
else if (entry.editor === 'select') { event.preventDefault(); grid.startEdit(active); }
}
};
const paste = (event: React.ClipboardEvent<HTMLTableElement>) => {
onPaste?.(event);
if (event.defaultPrevented || editing || readOnly || active.row < 0) return;
const text = event.clipboardData.getData('text/plain');
if (!text) return;
event.preventDefault();
const lines = text.replace(/\r/g, '').replace(/\n$/, '').split('\n').map(line => line.split('\t'));
let count = 0, same = 0;
lines.forEach((cells, dr) => cells.forEach((value, dc) => {
const entry = grid.entryAt({row: active.row + dr, col: active.col + dc});
if (!entry?.editable || !entry.editor) return;
const next = parseCellValue(value, entry.editor, entry.options);
if (next !== (entry.value ?? null) || grid.statusOf(entry.id)?.state === 'error') { grid.commit(entry, next); count++; }
else same++;
}));
const cellsWord = (n: number) => `${n} ${n === 1 ? 'cell' : 'cells'}`;
grid.announce(count
? `Pasted into ${cellsWord(count)}${same ? `, ${same} already held that value` : ''}`
: same ? `${cellsWord(same)} already held that value` : 'Nothing to paste into here');
};
return <Table
data-slot="data-grid-table"
scrollFocus={false}
size={size}
role="grid"
aria-rowcount={rowCount + 1}
aria-colcount={colCount}
aria-readonly={readOnly || undefined}
aria-describedby={grid.helpId}
onKeyDownCapture={onKeyDown}
onPaste={paste}
onFocus={event => { grid.setFocused(true); onFocus?.(event); }}
onBlur={event => { if (!event.currentTarget.contains(event.relatedTarget as Node | null)) grid.setFocused(false); onBlur?.(event); }}
className={cn('w-max min-w-full', className)}
{...props}
/>;
}
function DataGridHeader({className, ...props}: React.ComponentProps<typeof TableHeader>) {
return <TableHeader data-slot="data-grid-header" className={cn('sticky top-0 z-(--z-raised) bg-page', className)} {...props}/>;
}
const DataGridBody = TableBody;
function DataGridRow({index, ...props}: React.ComponentProps<typeof TableRow> & {index: number}) {
return <TableRow data-slot="data-grid-row" role="row" aria-rowindex={index + 2} {...props}/>;
}
function DataGridHead({col, focusable, className, ...props}: React.ComponentProps<typeof TableHead> & {col: number; focusable?: boolean}) {
const grid = useDataGrid();
const own = (focusable ?? grid.focusableHeader) ? grid.itemProps({row: -1, col}) : undefined;
const active = grid.active.row === -1 && grid.active.col === col;
return <TableHead
data-slot="data-grid-head"
role="columnheader"
aria-colindex={col + 1}
{...own}
className={cn(own && 'outline-none', own && active && grid.focused && 'focus-ring-inset!', className)}
{...props}
/>;
}
type DataGridCellProps = Omit<React.ComponentProps<'td'>, 'children' | 'onChange'> & {
row: number;
col: number;
cellId?: string;
label: string;
value?: CellValue;
editor?: CellEditor;
options?: CellOption[];
onCommit?: (value: CellValue) => void | Promise<unknown>;
validate?: (value: CellValue) => string | null;
status?: CellSaveState;
readOnly?: boolean;
text?: string;
placeholder?: string;
mono?: boolean;
children?: React.ReactNode;
};
function DataGridCell({
row, col, cellId, label, value = null, editor, options, onCommit, validate, status, readOnly, text, placeholder, mono,
className, children, onMouseDown, onDoubleClick, onContextMenu, ...props
}: DataGridCellProps) {
const grid = useDataGrid();
const p = {row, col};
const id = cellId ?? posKey(p);
const editable = !!editor && !readOnly && !grid.readOnly;
const entry = React.useRef<CellEntry>(null!);
entry.current = {
id, label, value, editor, options, onCommit, editable: editable && !!onCommit,
text: text ?? formatCellValue(value, editor, options),
};
const {register} = grid;
React.useEffect(() => register({row, col}, entry), [register, row, col]);
const isActive = grid.active.row === row && grid.active.col === col;
const editing = grid.editing && grid.editing.row === row && grid.editing.col === col ? grid.editing : null;
const st = status ?? grid.statusOf(id);
const invalid = validate ? validate(value) : null;
const failed = st?.state === 'error' ? st.message ?? 'Could not save' : null;
const error = failed ?? invalid;
const numeric = editor === 'number';
return <TableCell
data-slot="data-grid-cell"
role="gridcell"
aria-colindex={col + 1}
aria-readonly={!entry.current.editable || undefined}
aria-invalid={invalid ? true : undefined}
aria-busy={st?.state === 'saving' || undefined}
data-active={isActive || undefined}
data-editing={editing ? editing.via : undefined}
data-save={st && st.state !== 'idle' ? st.state : undefined}
data-status={error ? 'fail' : undefined}
{...grid.itemProps(p)}
onMouseDown={event => { onMouseDown?.(event); if (!editing) grid.move(p); }}
onDoubleClick={event => { onDoubleClick?.(event); grid.startEdit(p); }}
onContextMenu={event => { onContextMenu?.(event); grid.setActive(p); }}
className={cn(
'relative max-w-80 outline-none',
numeric && 'text-end data',
error && 'wash-row',
isActive && (grid.focused || editing) && editing?.via !== 'inline' && 'focus-ring-inset!',
editing?.via === 'inline' && 'py-0',
className,
)}
{...props}
>
{editing?.via === 'inline'
? <Input
size="sm"
autoFocus
aria-label={label}
inputMode={numeric ? 'decimal' : undefined}
value={editing.draft}
onChange={event => grid.setDraft(event.target.value)}
onBlur={() => grid.endEdit(true)}
onKeyDown={event => {
event.stopPropagation();
if (event.key === 'Escape') { event.preventDefault(); grid.endEdit(false); }
else if (event.key === 'Enter') { event.preventDefault(); grid.endEdit(true, 'down'); }
else if (event.key === 'Tab') { event.preventDefault(); grid.endEdit(true, event.shiftKey ? 'left' : 'right'); }
}}
className={cn('min-w-24', numeric && 'text-end', mono && 'type-tag')}
/>
: editing?.via === 'select'
? <Select
open
value={(value as string | null) ?? null}
onOpenChange={open => { if (!open) grid.endEdit(false); }}
onValueChange={next => grid.endEdit(true, undefined, (next as string | null) ?? '')}
>
<SelectTrigger size="sm" aria-label={label} className="min-w-full">
<SelectValue placeholder={placeholder ?? 'Choose'}>{(v: string | null) => options?.find(o => o.value === v)?.label ?? placeholder ?? 'Choose'}</SelectValue>
</SelectTrigger>
<SelectContent>
{options?.map(o => <SelectItem key={o.value} value={o.value}>{o.label}</SelectItem>)}
</SelectContent>
</Select>
: <CellDisplay
p={p}
label={label}
value={value}
editor={editor}
options={options}
placeholder={placeholder}
mono={mono}
editable={entry.current.editable}
error={failed ? {kind: 'failed', message: failed} : invalid ? {kind: 'invalid', message: invalid} : null}
save={st?.state}
popover={editing?.via === 'popover' ? editing : null}
>{children}</CellDisplay>}
</TableCell>;
}
function CellDisplay({p, label, value, editor, options, placeholder, mono, editable, error, save, popover, children}: {
p: CellPosition; label: string; value: CellValue; editor?: CellEditor; options?: CellOption[]; placeholder?: string; mono?: boolean;
editable: boolean; error: {kind: 'failed' | 'invalid'; message: string} | null; save?: CellSaveState['state']; popover: Editing | null; children?: React.ReactNode;
}) {
const grid = useDataGrid();
let body: React.ReactNode = children;
if (body === undefined) {
if (editor === 'boolean') body = <Checkbox
checked={!!value}
tabIndex={-1}
readOnly={!editable}
onCheckedChange={() => { if (editable) { grid.setActive(p); grid.startEdit(p); } }}
aria-label={`${label}: ${value ? 'yes' : 'no'}`}
/>;
else if (value == null || value === '') body = <span className="text-text-3">{placeholder ?? (editor === 'select' ? 'Choose' : '')}</span>;
else body = <span className="block truncate">{formatCellValue(value, editor, options)}</span>;
}
const marks = <>
{error && <Status status="fail">{`${error.kind === 'failed' ? 'Not saved' : 'Invalid'}: ${error.message}`}</Status>}
{save === 'saving' && <StatusArc name="Saving"/>}
{save === 'saved' && <Icon icon={Checkmark} size={12} label="Saved" className="text-text-2"/>}
</>;
const content = <span className={cn('flex min-w-0 items-center gap-2', editor === 'number' && 'justify-end', mono && 'type-tag')}>
{editor === 'number' && marks}
<span className={cn('min-w-0', editor === 'boolean' ? 'inline-flex' : 'flex-1')}>{body}</span>
{editor !== 'number' && marks}
</span>;
if (editor !== 'long-text') return content;
return <Popover
open={!!popover}
onOpenChange={(open, details) => { if (!open && popover) grid.endEdit(details.reason !== 'escape-key'); }}
>
<PopoverTrigger nativeButton={false} render={<span className="block min-w-0"/>} tabIndex={-1}>
{content}
</PopoverTrigger>
{popover && <PopoverContent align="start" side="bottom" sideOffset={4} className="w-80" finalFocus={() => grid.cellElement(p)}>
<div className="flex flex-col gap-1">
<PopoverTitle className="type-label">{label}</PopoverTitle>
<PopoverDescription className="type-body-sm text-text-3">Enter saves. Shift+Enter adds a line. Esc cancels.</PopoverDescription>
</div>
<Textarea
autoFocus
aria-label={label}
maxRows={8}
value={popover.draft}
onChange={event => grid.setDraft(event.target.value)}
onFocus={event => { const end = event.currentTarget.value.length; event.currentTarget.setSelectionRange(end, end); }}
onKeyDown={event => {
event.stopPropagation();
if (event.key === 'Enter' && !event.shiftKey) { event.preventDefault(); grid.endEdit(true, 'down'); }
}}
/>
</PopoverContent>}
</Popover>;
}
function DataGridHelp({className, children, ...props}: React.ComponentProps<'p'>) {
const grid = useDataGrid();
return <p id={grid.helpId} data-slot="data-grid-help" className={cn('flex flex-wrap items-center gap-x-3 gap-y-1 type-body-sm text-text-3', className)} {...props}>
{children ?? <>
<span className="flex items-center gap-1"><Kbd keys="enter"/>edits</span>
<span className="flex items-center gap-1"><Kbd keys="esc"/>cancels</span>
<span className="flex items-center gap-1"><Kbd keys="mod+c"/>copies</span>
<span>Paste fills from here</span>
</>}
</p>;
}
export {
DataGrid, DataGridTable, DataGridHeader, DataGridBody, DataGridRow, DataGridHead, DataGridCell, DataGridHelp, useDataGrid,
formatCellValue, parseCellValue,
type CellValue, type CellOption, type CellEditor, type CellSaveState, type CellPosition, type DataGridProps, type DataGridCellProps,
};