@protobase/ui 0.0.0-stage → 0.1.0

package/dist/data-grid/data-grid.js

@@ -0,0 +1,238 @@
+import { cn } from "../lib/cn.js";
+import { useIsDesktop } from "../lib/use-media-query.js";
+import { buildColumns, features } from "./columns.js";
+import { GridFooter } from "./grid-footer.js";
+import { RowMenu, availableActions } from "./row-menu.js";
+import { desktopMinScale, gridMinWidth, gutterWidthFor } from "./grid-template.js";
+import { useHorizontalScroll } from "./use-horizontal-scroll.js";
+import { usePinnedColumns } from "./use-pinned-columns.js";
+import { GridHeader } from "./grid-header.js";
+import { DataRow, SkeletonRow } from "./grid-row.js";
+import { windowFor } from "./geometry.js";
+import { useGridScroll } from "./use-grid-scroll.js";
+import { usePagedRows } from "./use-paged-rows.js";
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useTable } from "@tanstack/react-table";
+//#region src/data-grid/data-grid.tsx
+const headerHeight = 32;
+const DataGrid = ({ columns: given, source, naturalSort, initialScrollIndex = 0, latencyMs = 150, sort: controlledSort, onSortChange, onOpenRow, rowActions, bulkActions, pinKey, defaultPinned, rowNumbers = true, compact = false, selectable = true, className }) => {
+	const rowHeight = compact ? 28 : 36;
+	const [pinned, setPinned] = usePinnedColumns(pinKey, defaultPinned);
+	const columns = useMemo(() => {
+		return [...pinned.flatMap((id) => given.find((spec) => spec.id === id) ?? []), ...given.filter((spec) => !pinned.includes(spec.id))];
+	}, [given, pinned]);
+	const pinnedIds = columns.slice(0, columns.filter((spec) => pinned.includes(spec.id)).length).map((spec) => spec.id);
+	const { total } = source;
+	const [localSorting, setLocalSorting] = useState(naturalSort ? [{
+		id: naturalSort.columnId,
+		desc: naturalSort.direction === "desc"
+	}] : []);
+	const sorting = controlledSort ? [{
+		id: controlledSort.columnId,
+		desc: controlledSort.direction === "desc"
+	}] : localSorting;
+	const setSorting = (updater) => {
+		const next = typeof updater === "function" ? updater(sorting) : updater;
+		const first = next[0];
+		if (onSortChange && first) onSortChange({
+			columnId: first.id,
+			direction: first.desc ? "desc" : "asc"
+		});
+		if (!controlledSort) setLocalSorting(next);
+	};
+	const [rowSelection, setRowSelection] = useState({});
+	const tableColumns = useMemo(() => buildColumns(columns), [columns]);
+	const sort = sorting[0];
+	const reverse = Boolean(!controlledSort && naturalSort && sort && sort.id === naturalSort.columnId && (sort.desc ? "desc" : "asc") !== naturalSort.direction);
+	const sourceRowAt = source.rowAt;
+	const rowAt = useCallback((index) => sourceRowAt(reverse ? total - 1 - index : index), [
+		sourceRowAt,
+		reverse,
+		total
+	]);
+	const { ref, onScroll, viewport, top, geometry } = useGridScroll(total, rowHeight, initialScrollIndex);
+	const narrow = !useIsDesktop();
+	const gutter = narrow || !rowNumbers ? 40 : gutterWidthFor(total);
+	const bodyHeight = Math.max(0, viewport - headerHeight);
+	const bodyRef = useRef(null);
+	const offsetListener = useRef(null);
+	const { base, count } = windowFor(total, top, rowHeight);
+	const localOffset = top - base * rowHeight;
+	const virtualizer = useVirtualizer({
+		count,
+		getScrollElement: () => bodyRef.current,
+		estimateSize: () => rowHeight,
+		overscan: 6,
+		initialRect: {
+			width: 0,
+			height: bodyHeight
+		},
+		observeElementOffset: (_, callback) => {
+			offsetListener.current = callback;
+			callback(localOffset, false);
+			return () => {
+				offsetListener.current = null;
+			};
+		}
+	});
+	useLayoutEffect(() => offsetListener.current?.(localOffset, false), [localOffset, base]);
+	const items = virtualizer.getVirtualItems();
+	const firstIndex = base + (items[0]?.index ?? 0);
+	const lastIndex = base + (items[items.length - 1]?.index ?? 0);
+	const getRow = usePagedRows({
+		total,
+		rowAt: sourceRowAt ? rowAt : void 0,
+		loadRows: source.loadRows,
+		latencyMs
+	}, firstIndex, lastIndex);
+	const loaded = items.map((item) => ({
+		item,
+		index: base + item.index,
+		row: getRow(base + item.index)
+	}));
+	const data = useMemo(() => loaded.flatMap(({ row }) => row ? [row] : []), [
+		getRow,
+		firstIndex,
+		lastIndex
+	]);
+	const table = useTable({
+		features,
+		columns: tableColumns,
+		data,
+		state: {
+			sorting,
+			rowSelection
+		},
+		onSortingChange: setSorting,
+		onRowSelectionChange: setRowSelection,
+		manualSorting: true,
+		enableMultiSort: false,
+		enableSortingRemoval: false,
+		getRowId: (row) => row.id
+	});
+	const tableRows = new Map(table.getRowModel().rows.map((row) => [row.id, row]));
+	const selectedCount = Object.keys(rowSelection).length;
+	const selectedRows = useRef(/* @__PURE__ */ new Map());
+	for (const row of table.getRowModel().rows) if (row.getIsSelected()) selectedRows.current.set(row.id, row.original);
+	const trailing = rowActions && rowActions.length > 0 ? 40 : 0;
+	const minScale = narrow ? 1 : desktopMinScale;
+	const horizontal = useHorizontalScroll();
+	const [pins, setPins] = useState({});
+	useLayoutEffect(() => {
+		const header = horizontal.ref.current?.querySelector("[role=row]");
+		if (!header) return;
+		let left = gutter;
+		const next = {};
+		for (const id of pinnedIds) {
+			next[id] = left;
+			left += header.querySelector(`[data-col-id="${id}"]`)?.offsetWidth ?? 0;
+		}
+		if (JSON.stringify(pins) !== JSON.stringify(next)) setPins(next);
+	});
+	const lastPinned = pinnedIds.at(-1);
+	const togglePin = (id) => setPinned(pinned.includes(id) ? pinned.filter((entry) => entry !== id) : [...pinned, id]);
+	const headerCells = table.getHeaderGroups().flatMap((group) => group.headers.map((header) => ({
+		spec: columns.find((spec) => spec.id === header.column.id),
+		sorted: header.column.getIsSorted(),
+		onSort: (event) => header.column.getToggleSortingHandler()?.(event)
+	})));
+	const visibleRows = Math.max(1, Math.floor(bodyHeight / rowHeight));
+	const first = Math.min(total, Math.floor(top / rowHeight) + 1);
+	const last = Math.min(total, first + visibleRows - 1);
+	return /* @__PURE__ */ jsxs("div", {
+		className: cn("flex min-h-0 flex-col overflow-hidden rounded-lg border bg-background", className),
+		children: [/* @__PURE__ */ jsx("div", {
+			ref,
+			onScroll,
+			className: "relative min-h-0 flex-1 overflow-y-auto overflow-x-hidden",
+			role: "grid",
+			"aria-rowcount": total,
+			children: /* @__PURE__ */ jsx("div", {
+				style: { height: geometry.contentHeight || void 0 },
+				children: /* @__PURE__ */ jsx("div", {
+					className: "sticky top-0",
+					style: { height: viewport },
+					children: viewport > 0 && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("div", {
+						ref: horizontal.attach,
+						onScroll: horizontal.onScroll,
+						className: "h-full overflow-x-auto overflow-y-hidden overscroll-x-contain [-webkit-overflow-scrolling:touch]",
+						children: /* @__PURE__ */ jsxs("div", {
+							className: "flex h-full flex-col",
+							style: { minWidth: gridMinWidth(columns, gutter, trailing, minScale) },
+							children: [/* @__PURE__ */ jsx(GridHeader, {
+								cells: headerCells,
+								specs: columns,
+								gutter,
+								trailing,
+								minScale,
+								pins,
+								lastPinned,
+								scrolled: horizontal.scrolled,
+								onTogglePin: togglePin,
+								selectable,
+								selectedCount,
+								onClearSelection: () => setRowSelection({})
+							}), /* @__PURE__ */ jsx("div", {
+								ref: bodyRef,
+								className: "relative min-h-0 flex-1 overflow-clip",
+								children: loaded.map(({ item, index, row }) => {
+									const frame = {
+										specs: columns,
+										gutter,
+										index,
+										offset: item.start - localOffset,
+										height: rowHeight,
+										selectable,
+										trailing,
+										minScale,
+										scrolled: horizontal.scrolled,
+										pins,
+										lastPinned
+									};
+									const tableRow = row ? tableRows.get(row.id) : void 0;
+									if (!tableRow) return /* @__PURE__ */ jsx(SkeletonRow, { ...frame }, `skeleton-${index}`);
+									const actions = trailing && row ? availableActions(rowActions, row) : [];
+									return /* @__PURE__ */ jsx(DataRow, {
+										...frame,
+										selected: tableRow.getIsSelected(),
+										onToggle: () => tableRow.toggleSelected(),
+										onOpen: onOpenRow && row ? () => onOpenRow(row) : void 0,
+										menu: row && actions.length > 0 ? /* @__PURE__ */ jsx(RowMenu, {
+											row,
+											actions
+										}) : void 0,
+										cells: tableRow.getAllCells().map((cell) => ({
+											spec: columns.find((spec) => spec.id === cell.column.id),
+											content: /* @__PURE__ */ jsx(table.FlexRender, { cell })
+										}))
+									}, row?.id);
+								})
+							})]
+						})
+					}), horizontal.more && /* @__PURE__ */ jsx("div", {
+						"aria-hidden": true,
+						className: "pointer-events-none absolute inset-y-0 right-0 w-8 bg-gradient-to-l from-foreground/15 to-transparent"
+					})] })
+				})
+			})
+		}), /* @__PURE__ */ jsx(GridFooter, {
+			total,
+			first,
+			last,
+			selectedCount,
+			bulkActions: bulkActions?.map((action) => ({
+				label: action.label(selectedCount),
+				destructive: action.destructive,
+				onRun: () => {
+					action.onRun(Object.keys(rowSelection).flatMap((id) => selectedRows.current.get(id) ?? []));
+					setRowSelection({});
+					selectedRows.current.clear();
+				}
+			}))
+		})]
+	});
+};
+//#endregion
+export { DataGrid };

package/dist/data-grid/geometry.js

@@ -0,0 +1,32 @@
+//#region src/data-grid/geometry.ts
+/** Browsers cap element height (about 17M px in the strictest); stay well below it. */
+const maxContentHeight = 1e7;
+const chunk = 2e3;
+const windowSize = 5e3;
+const gridGeometry = (total, rowHeight, viewportHeight) => {
+	const trueHeight = total * rowHeight;
+	const contentHeight = Math.min(trueHeight, maxContentHeight);
+	return {
+		rowHeight,
+		trueHeight,
+		contentHeight,
+		scaled: trueHeight > contentHeight,
+		maxTop: Math.max(0, trueHeight - viewportHeight),
+		maxScroll: Math.max(0, contentHeight - viewportHeight)
+	};
+};
+/** Maps the native scroll position onto the virtual (true) pixel offset. */
+const topFromScroll = (geometry, scrollTop) => geometry.maxScroll === 0 ? 0 : scrollTop / geometry.maxScroll * geometry.maxTop;
+const scrollFromTop = (geometry, top) => geometry.maxTop === 0 ? 0 : top / geometry.maxTop * geometry.maxScroll;
+const clampTop = (geometry, top) => Math.min(Math.max(0, top), geometry.maxTop);
+/** The slice of rows handed to the virtualizer; it moves in whole chunks so row measurements stay small. */
+const windowFor = (total, top, rowHeight) => {
+	const topRow = Math.floor(top / rowHeight);
+	const base = Math.min(Math.max(0, Math.floor(topRow / chunk) * chunk - chunk), Math.max(0, total - windowSize));
+	return {
+		base,
+		count: Math.min(windowSize, total - base)
+	};
+};
+//#endregion
+export { clampTop, gridGeometry, maxContentHeight, scrollFromTop, topFromScroll, windowFor };

package/dist/data-grid/grid-footer.js

@@ -0,0 +1,33 @@
+import { cn } from "../lib/cn.js";
+import { formatApproxRows, formatInt } from "../format/number.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/data-grid/grid-footer.tsx
+const GridFooter = ({ total, first, last, selectedCount, bulkActions = [] }) => /* @__PURE__ */ jsxs("div", {
+	className: "flex h-9 shrink-0 items-center justify-between border-t bg-surface px-3 text-xs text-muted-foreground",
+	children: [/* @__PURE__ */ jsxs("span", {
+		className: "flex items-center tabular-nums",
+		children: [
+			formatApproxRows(total),
+			selectedCount > 0 && /* @__PURE__ */ jsxs("span", {
+				className: "ml-3 font-medium text-primary-text",
+				children: [formatInt(selectedCount), " selected"]
+			}),
+			selectedCount > 0 && bulkActions.map((action) => /* @__PURE__ */ jsx("button", {
+				type: "button",
+				onClick: action.onRun,
+				className: cn("ml-3 rounded border bg-background px-2 py-0.5 font-medium hover:bg-muted", action.destructive ? "border-danger/40 text-danger-text" : "text-foreground"),
+				children: action.label
+			}, action.label))
+		]
+	}), /* @__PURE__ */ jsxs("span", {
+		className: "tabular-nums",
+		children: [
+			"Rows ",
+			formatInt(first),
+			" – ",
+			formatInt(last)
+		]
+	})]
+});
+//#endregion
+export { GridFooter };

package/dist/data-grid/grid-header.js

@@ -0,0 +1,69 @@
+import { cn } from "../lib/cn.js";
+import { gridTemplate } from "./grid-template.js";
+import { Checkbox } from "../primitives/checkbox.js";
+import { isRightAligned } from "./column-spec.js";
+import { HeaderMenu } from "./header-menu.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { ArrowDown, ArrowUp, ChevronsUpDown } from "lucide-react";
+//#region src/data-grid/grid-header.tsx
+const SortIcon = ({ sorted }) => {
+	if (sorted === "asc") return /* @__PURE__ */ jsx(ArrowUp, { className: "size-3 text-foreground" });
+	if (sorted === "desc") return /* @__PURE__ */ jsx(ArrowDown, { className: "size-3 text-foreground" });
+	return /* @__PURE__ */ jsx(ChevronsUpDown, { className: "size-3 opacity-0 group-hover/head:opacity-100" });
+};
+const GridHeader = ({ cells, specs, gutter, selectedCount, selectable, trailing, minScale, pins = {}, lastPinned, scrolled, onTogglePin, onClearSelection }) => /* @__PURE__ */ jsxs("div", {
+	className: "grid h-8 shrink-0 items-center border-b bg-surface text-xs font-medium text-muted-foreground",
+	style: { gridTemplateColumns: gridTemplate(specs, gutter, trailing, minScale) },
+	role: "row",
+	children: [
+		/* @__PURE__ */ jsxs("div", {
+			className: cn("sticky left-0 z-10 flex h-full items-center gap-2 bg-inherit pl-3", scrolled && !lastPinned && "shadow-[1px_0_0_var(--border),4px_0_6px_-2px_rgb(0_0_0/0.12)]"),
+			style: { width: gutter },
+			children: [selectable && /* @__PURE__ */ jsx(Checkbox, {
+				checked: false,
+				indeterminate: selectedCount > 0,
+				label: "Clear selection",
+				onChange: onClearSelection,
+				className: cn(selectedCount === 0 && "opacity-60")
+			}), gutter > 40 && /* @__PURE__ */ jsx("span", {
+				className: "w-6 text-right text-faint-foreground",
+				children: "#"
+			})]
+		}),
+		cells.map(({ spec, sorted, onSort }) => {
+			const pinned = spec.id in pins;
+			return /* @__PURE__ */ jsxs("div", {
+				"data-col-id": spec.id,
+				style: pinned ? { left: pins[spec.id] } : void 0,
+				className: cn("group/cell flex h-full min-w-0 items-center", pinned && "sticky z-10 bg-inherit", pinned && scrolled && spec.id === lastPinned && "shadow-[1px_0_0_var(--border),4px_0_6px_-2px_rgb(0_0_0/0.12)]", spec.highlight && "bg-primary-soft text-primary-text"),
+				children: [/* @__PURE__ */ jsxs("button", {
+					type: "button",
+					onClick: onSort,
+					disabled: !spec.sortable,
+					className: cn("group/head flex h-full min-w-0 flex-1 items-center gap-1 pl-3 pr-1 text-left", isRightAligned(spec.kind) && "justify-end", spec.sortable && "hover:text-foreground", sorted && "text-foreground"),
+					children: [
+						/* @__PURE__ */ jsx("span", {
+							className: "truncate",
+							children: spec.header
+						}),
+						spec.highlight && /* @__PURE__ */ jsx("span", {
+							className: "rounded bg-primary px-1 text-[10px] font-semibold uppercase leading-4 text-primary-foreground",
+							children: "New"
+						}),
+						spec.sortable && /* @__PURE__ */ jsx(SortIcon, { sorted })
+					]
+				}), /* @__PURE__ */ jsx("div", {
+					className: "pr-1.5",
+					children: /* @__PURE__ */ jsx(HeaderMenu, {
+						header: spec.header,
+						pinned,
+						onTogglePin: () => onTogglePin(spec.id)
+					})
+				})]
+			}, spec.id);
+		}),
+		trailing ? /* @__PURE__ */ jsx("div", {}) : null
+	]
+});
+//#endregion
+export { GridHeader };

package/dist/data-grid/grid-row.js

@@ -0,0 +1,83 @@
+import { cn } from "../lib/cn.js";
+import { formatInt } from "../format/number.js";
+import { gridTemplate } from "./grid-template.js";
+import { Checkbox } from "../primitives/checkbox.js";
+import { isRightAligned } from "./column-spec.js";
+import { Skeleton } from "../primitives/skeleton.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/data-grid/grid-row.tsx
+const frameStyle = (frame) => ({
+	gridTemplateColumns: gridTemplate(frame.specs, frame.gutter, frame.trailing, frame.minScale),
+	height: frame.height,
+	transform: `translateY(${frame.offset}px)`
+});
+/** Pinned cells need a solid background; `bg-inherit` takes the row's, so hover and selection still show. */
+const cellClass = (spec, frame) => cn("flex h-full min-w-0 items-center overflow-hidden whitespace-nowrap px-3", isRightAligned(spec.kind) && "justify-end", spec.highlight && "bg-primary-soft/60", frame.pins && spec.id in frame.pins && "sticky z-10 bg-inherit", frame.scrolled && spec.id === frame.lastPinned && "shadow-[1px_0_0_var(--border),4px_0_6px_-2px_rgb(0_0_0/0.12)]");
+const pinStyle = (spec, pins) => pins && spec.id in pins ? { left: pins[spec.id] } : void 0;
+/** The selection column never scrolls away, so rows can be selected from anywhere in a wide grid. */
+const Gutter = ({ width, index, selectable, selected, onToggle, edge }) => /* @__PURE__ */ jsxs("div", {
+	className: cn("sticky left-0 z-10 flex h-full items-center gap-2 bg-inherit pl-3", edge && "shadow-[1px_0_0_var(--border),4px_0_6px_-2px_rgb(0_0_0/0.12)]"),
+	style: { width },
+	children: [selectable && /* @__PURE__ */ jsx("span", {
+		onClick: (event) => event.stopPropagation(),
+		children: /* @__PURE__ */ jsx(Checkbox, {
+			checked: Boolean(selected),
+			onChange: onToggle,
+			label: `Select row ${index + 1}`
+		})
+	}), width > 40 && /* @__PURE__ */ jsx("span", {
+		className: "min-w-6 text-right text-[11px] tabular-nums text-faint-foreground",
+		children: formatInt(index + 1)
+	})]
+});
+const DataRow = ({ cells, selected, onToggle, onOpen, menu, ...frame }) => /* @__PURE__ */ jsxs("div", {
+	role: "row",
+	onClick: onOpen,
+	className: cn("absolute inset-x-0 top-0 grid items-center border-b text-[13px]", selected ? "bg-primary-soft" : "bg-background hover:bg-surface", onOpen && "cursor-pointer"),
+	style: frameStyle(frame),
+	children: [
+		/* @__PURE__ */ jsx(Gutter, {
+			width: frame.gutter,
+			index: frame.index,
+			selectable: frame.selectable,
+			selected,
+			onToggle,
+			edge: frame.scrolled && !frame.lastPinned
+		}),
+		cells.map(({ spec, content }) => /* @__PURE__ */ jsx("div", {
+			role: "cell",
+			className: cellClass(spec, frame),
+			style: pinStyle(spec, frame.pins),
+			children: content
+		}, spec.id)),
+		menu && /* @__PURE__ */ jsx("div", {
+			className: "flex h-full items-center justify-center",
+			children: menu
+		})
+	]
+});
+const skeletonWidths = [
+	"w-3/4",
+	"w-1/2",
+	"w-2/3",
+	"w-5/6",
+	"w-2/5"
+];
+const SkeletonRow = (frame) => /* @__PURE__ */ jsxs("div", {
+	role: "row",
+	"aria-busy": true,
+	className: "absolute inset-x-0 top-0 grid items-center border-b bg-background",
+	style: frameStyle(frame),
+	children: [/* @__PURE__ */ jsx(Gutter, {
+		width: frame.gutter,
+		index: frame.index,
+		selectable: false,
+		edge: frame.scrolled && !frame.lastPinned
+	}), frame.specs.map((spec, column) => /* @__PURE__ */ jsx("div", {
+		className: cellClass(spec, frame),
+		style: pinStyle(spec, frame.pins),
+		children: /* @__PURE__ */ jsx(Skeleton, { className: cn("h-2.5", skeletonWidths[(frame.index + column) % skeletonWidths.length], isRightAligned(spec.kind) && "ml-auto") })
+	}, spec.id))]
+});
+//#endregion
+export { DataRow, SkeletonRow };

package/dist/data-grid/grid-template.js

@@ -0,0 +1,12 @@
+//#region src/data-grid/grid-template.ts
+/** Wide enough for the checkbox plus the largest row number, with thousands separators. */
+const gutterWidthFor = (total) => 52 + Math.ceil(String(total).length * 1.33) * 7;
+/** Columns may shrink to this share of their width on desktop; on narrow screens they keep it whole and the grid scrolls. */
+const desktopMinScale = .6;
+const minWidthOf = (spec, minScale) => Math.max(spec.minWidth ?? 0, spec.width * minScale);
+const columnTemplate = (spec, minScale) => spec.fixed ? `${Math.max(spec.minWidth ?? 0, spec.width)}px` : `minmax(${minWidthOf(spec, minScale)}px, ${spec.width}fr)`;
+const gridTemplate = (specs, gutter, trailing = 0, minScale = desktopMinScale) => `${gutter}px ${specs.map((spec) => columnTemplate(spec, minScale)).join(" ")}${trailing > 0 ? ` ${trailing}px` : ""}`;
+/** The narrowest the grid can be before it has to scroll sideways. */
+const gridMinWidth = (specs, gutter, trailing = 0, minScale = desktopMinScale) => gutter + trailing + specs.reduce((sum, spec) => sum + (spec.fixed ? Math.max(spec.minWidth ?? 0, spec.width) : minWidthOf(spec, minScale)), 0);
+//#endregion
+export { desktopMinScale, gridMinWidth, gridTemplate, gutterWidthFor };

package/dist/data-grid/header-menu.js

@@ -0,0 +1,52 @@
+import { useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { MoreHorizontal } from "lucide-react";
+//#region src/data-grid/header-menu.tsx
+/** The "..." in a column header: for now, pinning the column to the left edge. */
+const HeaderMenu = ({ header, pinned, onTogglePin }) => {
+	const [open, setOpen] = useState(false);
+	const root = useRef(null);
+	useEffect(() => {
+		if (!open) return;
+		const close = (event) => {
+			if (event instanceof KeyboardEvent ? event.key === "Escape" : !root.current?.contains(event.target)) setOpen(false);
+		};
+		document.addEventListener("mousedown", close);
+		document.addEventListener("keydown", close);
+		return () => {
+			document.removeEventListener("mousedown", close);
+			document.removeEventListener("keydown", close);
+		};
+	}, [open]);
+	return /* @__PURE__ */ jsxs("div", {
+		ref: root,
+		className: "relative ml-auto shrink-0",
+		children: [/* @__PURE__ */ jsx("button", {
+			type: "button",
+			"aria-label": `${header} column menu`,
+			"aria-haspopup": "menu",
+			"aria-expanded": open,
+			onClick: () => setOpen(!open),
+			className: "relative inline-flex size-5 items-center justify-center rounded text-faint-foreground hover:bg-muted hover:text-foreground focus-visible:opacity-100 after:absolute after:-inset-2 after:content-[''] md:opacity-0 md:group-hover/cell:opacity-100 aria-expanded:opacity-100",
+			children: /* @__PURE__ */ jsx(MoreHorizontal, { className: "size-3.5" })
+		}), open && /* @__PURE__ */ jsx("ul", {
+			role: "menu",
+			className: "absolute right-0 top-full z-30 mt-1 min-w-32 rounded-md border bg-background py-1 text-[13px] font-normal text-foreground shadow-pop",
+			children: /* @__PURE__ */ jsx("li", {
+				role: "none",
+				children: /* @__PURE__ */ jsx("button", {
+					type: "button",
+					role: "menuitem",
+					className: "block min-h-9 w-full whitespace-nowrap px-3 py-1.5 text-left hover:bg-muted",
+					onClick: () => {
+						setOpen(false);
+						onTogglePin();
+					},
+					children: pinned ? "Unpin" : "Pin to left"
+				})
+			})
+		})]
+	});
+};
+//#endregion
+export { HeaderMenu };

package/dist/data-grid/page-cache.js

@@ -0,0 +1,27 @@
+//#region src/data-grid/page-cache.ts
+/** Holds fixed-size pages of rows; evicts the oldest pages beyond `maxPages`. */
+const createPageCache = (pageSize, maxPages) => {
+	const pages = /* @__PURE__ */ new Map();
+	return {
+		get: (index) => pages.get(Math.floor(index / pageSize))?.[index % pageSize],
+		hasPage: (page) => pages.has(page),
+		setPage: (page, rows) => {
+			pages.delete(page);
+			pages.set(page, rows);
+			if (pages.size <= maxPages) return;
+			const oldest = pages.keys().next();
+			if (oldest.done) return;
+			pages.delete(oldest.value);
+		},
+		get size() {
+			return pages.size;
+		}
+	};
+};
+const pagesForRange = (start, end, pageSize) => {
+	const first = Math.floor(start / pageSize);
+	const last = Math.floor(end / pageSize);
+	return Array.from({ length: last - first + 1 }, (_, offset) => first + offset);
+};
+//#endregion
+export { createPageCache, pagesForRange };

package/dist/data-grid/pinned-storage.js

@@ -0,0 +1,13 @@
+import { guarded } from "../lib/guarded.js";
+//#region src/data-grid/pinned-storage.ts
+const prefix = "protobase:pinned:";
+const pinnedStorageKey = (userId, resource) => `${prefix}${userId}:${resource}`;
+const readPinned = (storage, key) => guarded(() => {
+	const raw = storage.getItem(key);
+	if (raw === null) return void 0;
+	const parsed = JSON.parse(raw);
+	return Array.isArray(parsed) && parsed.every((entry) => typeof entry === "string") ? parsed : void 0;
+}, void 0);
+const writePinned = (storage, key, pinned) => guarded(() => pinned.length === 0 ? storage.removeItem(key) : storage.setItem(key, JSON.stringify(pinned)), void 0);
+//#endregion
+export { pinnedStorageKey, readPinned, writePinned };

package/dist/data-grid/row-menu.js

@@ -0,0 +1,88 @@
+import { cn } from "../lib/cn.js";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { MoreHorizontal } from "lucide-react";
+import { createPortal } from "react-dom";
+//#region src/data-grid/row-menu.tsx
+/** The actions that apply to a row; a row with none gets no menu at all. */
+const availableActions = (actions, row) => actions.filter((action) => action.available?.(row) ?? true);
+const gap = 4;
+/** Below the button, or above it when the viewport has no room underneath. */
+const placeMenu = (button, menuHeight) => {
+	const below = button.bottom + gap;
+	return {
+		top: below + menuHeight > window.innerHeight - gap ? Math.max(gap, button.top - gap - menuHeight) : below,
+		right: window.innerWidth - button.right
+	};
+};
+/**
+* The "..." button at the end of a row, with a small menu of the row's actions. The menu is portalled to the body:
+* every grid row is its own stacking context and the grid body clips, so a menu inside the row would sit under the
+* rows below it.
+*/
+const RowMenu = ({ row, actions }) => {
+	const [open, setOpen] = useState(false);
+	const [place, setPlace] = useState();
+	const button = useRef(null);
+	const menu = useRef(null);
+	useLayoutEffect(() => {
+		if (!open || !button.current || !menu.current) {
+			setPlace(void 0);
+			return;
+		}
+		setPlace(placeMenu(button.current.getBoundingClientRect(), menu.current.offsetHeight));
+	}, [open]);
+	useEffect(() => {
+		if (!open) return;
+		const inside = (target) => button.current?.contains(target) || menu.current?.contains(target);
+		const close = (event) => {
+			if (event instanceof KeyboardEvent ? event.key === "Escape" : !inside(event.target)) setOpen(false);
+		};
+		const dismiss = () => setOpen(false);
+		document.addEventListener("mousedown", close);
+		document.addEventListener("keydown", close);
+		document.addEventListener("scroll", dismiss, true);
+		window.addEventListener("resize", dismiss);
+		return () => {
+			document.removeEventListener("mousedown", close);
+			document.removeEventListener("keydown", close);
+			document.removeEventListener("scroll", dismiss, true);
+			window.removeEventListener("resize", dismiss);
+		};
+	}, [open]);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "relative flex justify-center bg-inherit",
+		onClick: (event) => event.stopPropagation(),
+		children: [/* @__PURE__ */ jsx("button", {
+			ref: button,
+			type: "button",
+			"aria-label": "Row actions",
+			"aria-haspopup": "menu",
+			"aria-expanded": open,
+			onClick: () => setOpen(!open),
+			className: "inline-flex items-center justify-center rounded p-1 text-faint-foreground hover:bg-muted hover:text-foreground pointer-coarse:size-11",
+			children: /* @__PURE__ */ jsx(MoreHorizontal, { className: "size-4" })
+		}), open && createPortal(/* @__PURE__ */ jsx("ul", {
+			ref: menu,
+			role: "menu",
+			onClick: (event) => event.stopPropagation(),
+			style: place ?? { visibility: "hidden" },
+			className: "fixed z-50 min-w-36 rounded-md border bg-background py-1 text-[13px] shadow-pop",
+			children: actions.map((action) => /* @__PURE__ */ jsx("li", {
+				role: "none",
+				children: /* @__PURE__ */ jsx("button", {
+					type: "button",
+					role: "menuitem",
+					className: cn("block w-full px-3 py-1.5 text-left hover:bg-muted", action.destructive && "text-danger-text"),
+					onClick: () => {
+						setOpen(false);
+						action.onSelect(row);
+					},
+					children: action.label
+				})
+			}, action.label))
+		}), document.body)]
+	});
+};
+//#endregion
+export { RowMenu, availableActions };