@stackframe/dashboard-ui-components 2.8.84 → 2.8.86

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

@@ -0,0 +1,868 @@
+"use client";
+
+import { ArrowDown, ArrowUp, CaretDown, CaretUp, CheckSquare, MinusSquare, Square } from "@phosphor-icons/react";
+import { cn } from "@stackframe/stack-ui";
+import { jsx, jsxs } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import { clearSelection, exportToCsv, formatGridDate, getSortDirection, getSortIndex, isColumnVisible, resolveColumnValue, resolveColumnWidth, selectAll, toggleRowSelection, toggleSort } from "./state.js";
+import { resolveDataGridStrings } from "./strings.js";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { DesignSkeleton } from "../skeleton.js";
+import { DataGridToolbar } from "./data-grid-toolbar.js";
+import { applyDraggedColumnWidth, clampColumnWidth, createGridSizingStyle, getColumnSizingStyle } from "./data-grid-sizing.js";
+
+//#region src/components/data-grid/data-grid.tsx
+function ResizeHandle({ onResize, onResizeEnd }) {
+	const startXRef = useRef(0);
+	const rafRef = useRef(0);
+	const latestDeltaRef = useRef(0);
+	const callbacksRef = useRef({
+		onResize,
+		onResizeEnd
+	});
+	callbacksRef.current = {
+		onResize,
+		onResizeEnd
+	};
+	const onPointerDown = useCallback((e) => {
+		e.preventDefault();
+		e.stopPropagation();
+		startXRef.current = e.clientX;
+		latestDeltaRef.current = 0;
+		const el = e.currentTarget;
+		el.setPointerCapture(e.pointerId);
+		let finished = false;
+		const onMove = (ev) => {
+			latestDeltaRef.current = ev.clientX - startXRef.current;
+			if (rafRef.current !== 0) return;
+			rafRef.current = requestAnimationFrame(() => {
+				rafRef.current = 0;
+				callbacksRef.current.onResize(latestDeltaRef.current);
+			});
+		};
+		const finish = () => {
+			if (finished) return;
+			finished = true;
+			if (rafRef.current !== 0) {
+				cancelAnimationFrame(rafRef.current);
+				rafRef.current = 0;
+				callbacksRef.current.onResize(latestDeltaRef.current);
+			}
+			el.removeEventListener("pointermove", onMove);
+			el.removeEventListener("pointerup", finish);
+			el.removeEventListener("pointercancel", finish);
+			el.removeEventListener("lostpointercapture", finish);
+			if (el.hasPointerCapture(e.pointerId)) el.releasePointerCapture(e.pointerId);
+			callbacksRef.current.onResizeEnd();
+		};
+		el.addEventListener("pointermove", onMove);
+		el.addEventListener("pointerup", finish);
+		el.addEventListener("pointercancel", finish);
+		el.addEventListener("lostpointercapture", finish);
+	}, []);
+	return /* @__PURE__ */ jsx("div", {
+		className: cn("absolute right-0 top-0 bottom-0 z-10 w-[5px] cursor-col-resize touch-none", "group-hover/header:bg-foreground/[0.06] hover:!bg-blue-500/30", "transition-colors duration-100"),
+		onClick: (e) => {
+			e.preventDefault();
+			e.stopPropagation();
+		},
+		onPointerDown
+	});
+}
+function HeaderCell({ col, isSorted, sortIndex, resizable, onSort, onResize, onResizeEnd }) {
+	const ctx = {
+		columnId: col.id,
+		columnDef: col,
+		isSorted,
+		sortIndex
+	};
+	const label = typeof col.header === "function" ? col.header(ctx) : col.header;
+	const sortable = col.sortable !== false;
+	return /* @__PURE__ */ jsxs("div", {
+		className: cn("group/header relative flex items-center gap-1.5 px-3 select-none bg-transparent", "border-r border-black/[0.04] dark:border-white/[0.04] last:border-r-0", sortable && "cursor-pointer"),
+		style: getColumnSizingStyle(col),
+		"data-col-id": col.id,
+		onClick: (e) => sortable && onSort(col.id, e.metaKey || e.ctrlKey),
+		role: "columnheader",
+		"aria-sort": isSorted === "asc" ? "ascending" : isSorted === "desc" ? "descending" : "none",
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: cn("flex-1 truncate text-xs font-semibold uppercase tracking-wider text-muted-foreground", col.align === "center" && "text-center", col.align === "right" && "text-right"),
+				children: label
+			}),
+			isSorted && /* @__PURE__ */ jsxs("span", {
+				className: "flex items-center gap-0.5 text-foreground/60",
+				children: [isSorted === "asc" ? /* @__PURE__ */ jsx(ArrowUp, {
+					className: "h-3 w-3",
+					weight: "bold"
+				}) : /* @__PURE__ */ jsx(ArrowDown, {
+					className: "h-3 w-3",
+					weight: "bold"
+				}), sortIndex != null && /* @__PURE__ */ jsx("span", {
+					className: "text-[10px] font-medium tabular-nums",
+					children: sortIndex
+				})]
+			}),
+			!isSorted && sortable && /* @__PURE__ */ jsxs("span", {
+				className: "hidden group-hover/header:flex items-center text-foreground/20",
+				children: [/* @__PURE__ */ jsx(CaretUp, {
+					className: "h-2.5 w-2.5 -mb-[1px]",
+					weight: "bold"
+				}), /* @__PURE__ */ jsx(CaretDown, {
+					className: "h-2.5 w-2.5 -mt-[1px]",
+					weight: "bold"
+				})]
+			}),
+			resizable && col.resizable !== false && /* @__PURE__ */ jsx(ResizeHandle, {
+				onResize: (delta) => onResize(col.id, delta),
+				onResizeEnd
+			})
+		]
+	});
+}
+function DataCell({ col, row, rowId, rowIndex, isSelected, dateDisplay }) {
+	const value = resolveColumnValue(col, row);
+	const ctx = {
+		row,
+		rowId,
+		rowIndex,
+		value,
+		columnId: col.id,
+		isSelected,
+		dateDisplay
+	};
+	const isDateCol = col.type === "date" || col.type === "dateTime";
+	let content;
+	if (col.renderCell) content = col.renderCell(ctx);
+	else if (isDateCol) content = renderDateCell(value, dateDisplay, col);
+	else content = formatCellValue(value);
+	const hasCellClick = col.onCellClick || col.onCellDoubleClick;
+	return /* @__PURE__ */ jsx("div", {
+		className: cn("flex items-center px-3 truncate bg-transparent", "border-r border-black/[0.04] dark:border-white/[0.04] last:border-r-0", "text-sm text-foreground", col.align === "center" && "justify-center", col.align === "right" && "justify-end", hasCellClick && "cursor-pointer"),
+		style: getColumnSizingStyle(col),
+		"data-col-id": col.id,
+		role: "gridcell",
+		onClick: col.onCellClick ? (e) => {
+			e.stopPropagation();
+			col.onCellClick(ctx, e);
+		} : void 0,
+		onDoubleClick: col.onCellDoubleClick ? (e) => {
+			e.stopPropagation();
+			col.onCellDoubleClick(ctx, e);
+		} : void 0,
+		children: content
+	});
+}
+function formatCellValue(value) {
+	if (value == null) return /* @__PURE__ */ jsx("span", {
+		className: "text-muted-foreground/40",
+		children: "-"
+	});
+	if (typeof value === "boolean") return /* @__PURE__ */ jsx("span", {
+		className: cn("inline-flex items-center px-1.5 py-0.5 rounded-md text-xs font-medium", value ? "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400" : "bg-foreground/[0.04] text-muted-foreground"),
+		children: value ? "Yes" : "No"
+	});
+	if (value instanceof Date) return /* @__PURE__ */ jsx("span", {
+		className: "tabular-nums text-muted-foreground",
+		children: value.toLocaleDateString()
+	});
+	return /* @__PURE__ */ jsx("span", {
+		className: "truncate",
+		children: String(value)
+	});
+}
+/** Built-in date cell — mirrors what `formatGridDate` returns but wraps
+* the display in a `<span>` with a `title` tooltip showing the absolute
+* datetime. Only used when the column has `type: "date" | "dateTime"`
+* and no custom `renderCell`. */
+function renderDateCell(value, dateDisplay, col) {
+	const { display, tooltip } = formatGridDate(value, dateDisplay, {
+		parseValue: col.parseValue,
+		dateFormat: col.dateFormat
+	});
+	if (display == null) return /* @__PURE__ */ jsx("span", {
+		className: "text-muted-foreground/40",
+		children: "-"
+	});
+	return /* @__PURE__ */ jsx("span", {
+		className: "tabular-nums text-muted-foreground truncate cursor-help",
+		title: tooltip ?? void 0,
+		children: display
+	});
+}
+function SkeletonRow({ columns, height, showCheckbox }) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "flex",
+		style: { height },
+		role: "row",
+		children: [showCheckbox && /* @__PURE__ */ jsx("div", {
+			className: "flex items-center justify-center border-r border-black/[0.04] dark:border-white/[0.04]",
+			style: { width: 44 },
+			children: /* @__PURE__ */ jsx(DesignSkeleton, { className: "h-4 w-4 rounded" })
+		}), columns.map((col) => /* @__PURE__ */ jsx("div", {
+			className: "flex items-center px-3 border-r border-black/[0.04] dark:border-white/[0.04] last:border-r-0",
+			style: getColumnSizingStyle(col),
+			children: /* @__PURE__ */ jsx(DesignSkeleton, {
+				className: "h-3.5 rounded-md",
+				style: { width: `${40 + Math.random() * 40}%` }
+			})
+		}, col.id))]
+	});
+}
+function SelectionCheckbox({ checked, indeterminate, onChange, ariaLabel }) {
+	const Icon = indeterminate ? MinusSquare : checked ? CheckSquare : Square;
+	return /* @__PURE__ */ jsx("button", {
+		className: cn("flex items-center justify-center w-full h-full", "hover:bg-foreground/[0.04] transition-colors duration-75", checked || indeterminate ? "text-blue-600 dark:text-blue-400" : "text-muted-foreground/40 hover:text-muted-foreground/60"),
+		onClick: (e) => {
+			e.stopPropagation();
+			onChange(e);
+		},
+		"aria-label": ariaLabel,
+		role: "checkbox",
+		"aria-checked": indeterminate ? "mixed" : checked,
+		children: /* @__PURE__ */ jsx(Icon, {
+			className: "h-4 w-4",
+			weight: checked || indeterminate ? "fill" : "regular"
+		})
+	});
+}
+function InfiniteScrollSentinel({ onIntersect, isLoading, strings }) {
+	const ref = useRef(null);
+	useEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		const observer = new IntersectionObserver((entries) => {
+			if (entries[0]?.isIntersecting) onIntersect();
+		}, { rootMargin: "200px" });
+		observer.observe(el);
+		return () => observer.disconnect();
+	}, [onIntersect]);
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		className: "flex items-center justify-center py-4",
+		children: isLoading && /* @__PURE__ */ jsxs("div", {
+			className: "flex items-center gap-2 text-xs text-muted-foreground",
+			children: [/* @__PURE__ */ jsx("div", { className: "h-3 w-3 rounded-full border-2 border-current border-t-transparent animate-spin" }), strings.loadingMore]
+		})
+	});
+}
+function DefaultFooter({ ctx, pagination, onChange }) {
+	const { state, totalRowCount, visibleRowCount, selectedRowCount, strings } = ctx;
+	const totalPages = totalRowCount != null ? Math.max(1, Math.ceil(totalRowCount / state.pagination.pageSize)) : void 0;
+	const setPage = (pageIndex) => onChange((s) => ({
+		...s,
+		pagination: {
+			...s.pagination,
+			pageIndex
+		}
+	}));
+	const setPageSize = (pageSize) => onChange((s) => ({
+		...s,
+		pagination: {
+			...s.pagination,
+			pageSize,
+			pageIndex: 0
+		}
+	}));
+	return /* @__PURE__ */ jsxs("div", {
+		className: "flex items-center justify-between px-4 py-2.5 border-t border-foreground/[0.06] text-xs text-muted-foreground",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex items-center gap-3",
+			children: [selectedRowCount > 0 && /* @__PURE__ */ jsx("span", {
+				className: "font-medium text-foreground",
+				children: strings.rowsSelected(selectedRowCount)
+			}), totalRowCount != null && /* @__PURE__ */ jsxs("span", { children: [
+				visibleRowCount,
+				" of ",
+				totalRowCount,
+				" rows"
+			] })]
+		}), pagination !== "infinite" && totalPages != null && /* @__PURE__ */ jsxs("div", {
+			className: "flex items-center gap-3",
+			children: [/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-1.5",
+				children: [/* @__PURE__ */ jsx("span", { children: strings.rowsPerPage }), /* @__PURE__ */ jsx("select", {
+					className: cn("h-7 rounded-lg border border-black/[0.08] dark:border-white/[0.08] bg-background px-1.5", "text-xs text-foreground focus:outline-none focus:ring-1 focus:ring-foreground/[0.1]", "cursor-pointer"),
+					value: state.pagination.pageSize,
+					onChange: (e) => setPageSize(Number(e.target.value)),
+					children: [
+						10,
+						25,
+						50,
+						100
+					].map((size) => /* @__PURE__ */ jsx("option", {
+						value: size,
+						children: size
+					}, size))
+				})]
+			}), /* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-1",
+				children: [
+					/* @__PURE__ */ jsx("button", {
+						className: cn("h-7 w-7 flex items-center justify-center rounded-lg", "hover:bg-foreground/[0.04] disabled:opacity-30 disabled:cursor-not-allowed", "transition-colors duration-75"),
+						onClick: () => setPage(state.pagination.pageIndex - 1),
+						disabled: state.pagination.pageIndex === 0,
+						"aria-label": "Previous page",
+						children: /* @__PURE__ */ jsx(CaretUp, {
+							className: "h-3.5 w-3.5 -rotate-90",
+							weight: "bold"
+						})
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: "px-2 tabular-nums font-medium",
+						children: strings.pageOf(state.pagination.pageIndex + 1, totalPages)
+					}),
+					/* @__PURE__ */ jsx("button", {
+						className: cn("h-7 w-7 flex items-center justify-center rounded-lg", "hover:bg-foreground/[0.04] disabled:opacity-30 disabled:cursor-not-allowed", "transition-colors duration-75"),
+						onClick: () => setPage(state.pagination.pageIndex + 1),
+						disabled: state.pagination.pageIndex >= totalPages - 1,
+						"aria-label": "Next page",
+						children: /* @__PURE__ */ jsx(CaretDown, {
+							className: "h-3.5 w-3.5 -rotate-90",
+							weight: "bold"
+						})
+					})
+				]
+			})]
+		})]
+	});
+}
+/**
+* Interactive table with sorting, quick search, pagination, selection,
+* and virtualization. Handles 10k+ rows smoothly. Pair with
+* `useDataSource` for client-side data; use an async `dataSource`
+* generator for server or infinite-scroll modes.
+*
+* ## Mental model (read this first — everything else depends on it)
+*
+* DataGrid is a **display** component. It does NOT sort, search, or
+* paginate your data directly — you own that, but `useDataSource` does
+* it for you. The `rows` prop is always the already-processed slice to
+* show. The grid tracks user intent in `state` (sort model, quick
+* search text, page index). You feed that state into `useDataSource`,
+* and its output goes back in as `rows`.
+*
+* `useDataSource` IS the processor. Given your full dataset and the
+* grid's state, it returns the searched + sorted + paginated rows
+* ready to pass to DataGrid. This is the ONLY correct pattern for
+* client-side data — do NOT pass a raw array to `rows`.
+*
+* ## Search (client vs async)
+*
+* - **Client mode** (`useDataSource` with `data`): a case-insensitive
+*   substring match across every column is applied automatically.
+*   Override the matcher with `matchRow` for fuzzy / weighted search,
+*   or disable by passing `matchRow: () => true`.
+* - **Async mode** (`useDataSource` with `dataSource`): `state.quickSearch`
+*   is forwarded to the generator as `params.quickSearch`. Same
+*   mechanism as `params.sorting` — a change triggers a refetch, and
+*   the generator is the "matching logic" (typically a WHERE / ILIKE
+*   clause in the backend query). The grid does NO client-side
+*   filtering in async mode.
+*
+* ## The canonical pattern
+*
+* ```tsx
+* // 1. Columns — define OUTSIDE the component or inside a useMemo. Must be stable.
+* const columns = React.useMemo(() => [
+*   { id: "name", header: "Name", accessor: "name", width: 180, type: "string" },
+*   { id: "email", header: "Email", accessor: "email", width: 240, type: "string" },
+*   { id: "role", header: "Role", accessor: "role", width: 120, type: "singleSelect",
+*     valueOptions: [{ value: "admin", label: "Admin" }, { value: "member", label: "Member" }] },
+*   { id: "signUps", header: "Sign-ups", accessor: "signUps", width: 120, type: "number", align: "right",
+*     renderCell: ({ value }) => <span className="tabular-nums">{Number(value).toLocaleString()}</span> },
+* ], []);
+*
+* // 2. Grid state — one hook, initialized from the columns. NEVER build the state object by hand.
+* const [gridState, setGridState] = React.useState(() => createDefaultDataGridState(columns));
+*
+* // 3. Data source — wires your raw array through the grid state. ALWAYS call this
+* //    hook unconditionally at the top level (no if/return before it).
+* const gridData = useDataSource({
+*   data: users,                   // your raw array (can be [] while loading)
+*   columns,
+*   getRowId: (row) => row.id,
+*   sorting: gridState.sorting,
+*   quickSearch: gridState.quickSearch,
+*   pagination: gridState.pagination,
+*   paginationMode: "client",       // "client" | "server" | "infinite"
+* });
+*
+* // 4. Render — `rows` comes from gridData.rows, NOT from your raw array.
+* <DataGrid
+*   columns={columns}
+*   rows={gridData.rows}
+*   getRowId={(row) => row.id}
+*   totalRowCount={gridData.totalRowCount}
+*   isLoading={gridData.isLoading}
+*   state={gridState}
+*   onChange={setGridState}
+*   selectionMode="none"            // "none" | "single" | "multiple"
+*   maxHeight={480}
+* />
+* ```
+*
+* ## Iron rules (violating any of these breaks the grid)
+*
+* 1. The prop is `rows`, NOT `data`. There is no `data` prop on DataGrid.
+*    `data` belongs on `useDataSource`.
+* 2. `rows` is ALWAYS `gridData.rows`. Never pass your raw array to
+*    `rows` — the grid won't search, sort, or paginate it.
+* 3. Columns must be stable across renders. Define them outside the
+*    component or wrap in `React.useMemo`. A fresh columns array every
+*    render will reset sorting state.
+* 4. Initialize grid state with `createDefaultDataGridState(columns)`.
+*    Do NOT spell out the state object manually — you will miss fields
+*    and crash.
+* 5. `onChange` takes a `SetStateAction` (the setter you got from
+*    `useState`). Pass `setGridState` directly. Do NOT wrap it unless
+*    you know exactly what you're doing.
+* 6. Call `useDataSource` ONCE per grid, at the top level, before any
+*    early return. It contains hooks.
+* 7. `renderCell` is a PURE function of its context. NEVER call React
+*    hooks inside it (no `useState`, `useMemo`, `useEffect`, nothing).
+*    If you need derived data per row, compute it BEFORE the render —
+*    e.g. build a `Map<rowId, sparklineData>` in a `useMemo` and look
+*    it up in `renderCell`.
+* 8. `toolbar` accepts `false` (hide it) or a render function
+*    `(ctx) => ReactNode`. Anything else — `true`, `undefined`, a state
+*    variable — will either show the default toolbar or crash. If you
+*    just want the default toolbar, omit the prop entirely.
+* 9. The toolbar's search input writes to `state.quickSearch`. That
+*    value is consumed by `useDataSource` — client mode filters
+*    client-side, async mode forwards to the generator. Do NOT wire
+*    a separate "controlled" search prop, everything flows through
+*    grid state.
+*
+* ## renderCell — what you can and cannot do inside it
+*
+* ```tsx
+* // OK — pure rendering from ctx:
+* renderCell: ({ value }) => <span className="tabular-nums">{Number(value).toLocaleString()}</span>
+* renderCell: ({ row }) => <Badge variant={row.active ? "default" : "outline"}>{row.status}</Badge>
+*
+* // OK — looking up pre-computed data by row id:
+* // BEFORE the return, in the component body:
+* const sparklinesById = React.useMemo(() => {
+*   const m = new Map();
+*   for (const u of users) {
+*     m.set(u.id, u.recentActivity.map((n, i) => ({ ts: i, values: { primary: n } })));
+*   }
+*   return m;
+* }, [users]);
+* // Then inside the column def:
+* renderCell: ({ rowId }) => <MiniSparkline data={sparklinesById.get(rowId) ?? []} />
+*
+* // NOT OK — hooks inside renderCell:
+* renderCell: ({ row }) => {
+*   const [hovered, setHovered] = React.useState(false);  // ← crashes the grid
+*   const data = React.useMemo(() => ..., []);             // ← crashes the grid
+*   return ...;
+* }
+*
+* // NOT OK — embedding AnalyticsChart (or any other controlled, stateful chart) per row:
+* // AnalyticsChart owns its own state, tooltips, zoom, and virtualized data
+* // pipeline. Instantiating one per row is expensive and fights the grid's
+* // virtualizer. Don't do it.
+* ```
+*
+* ## Sparklines and mini-charts in cells — use raw Recharts
+*
+* If you want a tiny chart (sparkline, micro bar chart, trend line) inside
+* a cell, drop down to raw `Recharts.*` components — they are lightweight
+* and stateless, so they render cleanly per row without owning any state.
+* Read pre-computed points off the row (or off a `Map<rowId, points>` you
+* built in a `useMemo` above) and pass them directly to the Recharts
+* primitive. Do NOT wrap them in `DesignChartContainer` or
+* `DesignChartCard` inside a cell — those add chrome meant for full-size
+* charts.
+*
+* ```tsx
+* // OK — raw Recharts sparkline per row:
+* renderCell: ({ rowId }) => {
+*   const points = sparklinesById.get(rowId) ?? [];
+*   return (
+*     <Recharts.ResponsiveContainer width="100%" height={28}>
+*       <Recharts.LineChart data={points} margin={{ top: 2, right: 2, bottom: 2, left: 2 }}>
+*         <Recharts.Line type="monotone" dataKey="v" stroke="currentColor" strokeWidth={1.5} dot={false} isAnimationActive={false} />
+*       </Recharts.LineChart>
+*     </Recharts.ResponsiveContainer>
+*   );
+* }
+* ```
+*
+* Keep in-cell Recharts configs minimal: no axes, no tooltips, no animation
+* (`isAnimationActive={false}`), tight margins, fixed height. The goal is a
+* visual summary, not an interactive chart.
+*
+* ## State shape (from `createDefaultDataGridState`)
+*
+* ```ts
+* {
+*   sorting: [],                                        // { columnId, direction: "asc" | "desc" }[]
+*   quickSearch: "",                                    // search input text
+*   dateDisplay: "relative",                            // "relative" | "absolute"
+*   columnVisibility: {}, columnWidths: {...},
+*   columnPinning: { left: [], right: [] }, columnOrder: [...],
+*   pagination: { pageIndex: 0, pageSize: 50 },
+*   selection: { selectedIds: new Set(), anchorId: null },
+* }
+* ```
+*
+* Everything is updated through `setGridState` — the toolbar, header,
+* and footer all call it for you. You do not need to wire any of this
+* manually.
+*
+* ## Height and scrolling
+*
+* DataGrid is NOT a card. It has no border, rounded corners, or shadow of
+* its own. Wrap it in whatever chrome you want — a `DesignCard`, a section,
+* or just raw layout. The grid itself fills its parent's height via
+* `h-full`.
+*
+* How the grid gets its height (pick ONE):
+* 1. Bounded parent — put the grid inside a flex/grid container with a
+*    definite height (e.g. `flex-1 min-h-0` inside a page-filling flex
+*    column). The grid stretches to that height and scrolls its body.
+* 2. `maxHeight` prop — pass a number (pixels) or CSS string
+*    (`"480px"`, `"60vh"`, `"100%"`). The grid caps at that size and
+*    scrolls its body.
+* 3. Unbounded — omit `maxHeight` and let the parent grow freely. The
+*    grid renders at its full content height and the page scrolls. Fine
+*    for small lists; bad UX for thousands of rows.
+*
+* The toolbar, header, and footer are always `shrink-0`; only the body
+* scrolls. You do NOT need to subtract toolbar/footer heights from
+* `maxHeight` — the grid's internal flex layout handles that.
+*
+* ## When to use what
+*
+* - Simple static list, < 20 rows, no interaction → use a plain table component instead.
+* - Interactive table, sortable + searchable, any size → `DataGrid` +
+*   `useDataSource` with `paginationMode: "client"`.
+* - Infinite scroll over a huge dataset you fetch in pages → `dataSource` async
+*   generator + `paginationMode: "infinite"`. Only reach for this if you actually
+*   need pagination over a remote source. For anything that fits in memory,
+*   `"client"` is simpler and faster.
+*
+* ## Features you get for free
+*
+* Quick search, sortable columns (shift-click for multi-sort), column
+* visibility toggle, column resize, CSV export, virtualized rendering
+* for 10k+ rows, keyboard navigation, and a relative/absolute date
+* toggle for `date` / `dateTime` columns.
+*/
+function DataGrid(props) {
+	const { columns: allColumns, rows, getRowId, totalRowCount, isLoading = false, isRefetching = false, hasMore = false, isLoadingMore = false, onLoadMore, state, onChange, paginationMode = "paginated", selectionMode = "none", resizable = true, rowHeight = 44, headerHeight = 44, overscan = 5, maxHeight, toolbar, toolbarExtra, emptyState, loadingState, footer, footerExtra, exportFilename = "export", strings: stringsOverride, className, onRowClick, onRowDoubleClick, onSelectionChange, onSortChange } = props;
+	const strings = useMemo(() => resolveDataGridStrings(stringsOverride), [stringsOverride]);
+	const visibleColumns = useMemo(() => (state.columnOrder.length > 0 ? state.columnOrder.map((id) => allColumns.find((c) => c.id === id)).filter(Boolean) : allColumns).filter((col) => isColumnVisible(col.id, state.columnVisibility)), [
+		allColumns,
+		state.columnOrder,
+		state.columnVisibility
+	]);
+	const rowIds = useMemo(() => rows.map(getRowId), [rows, getRowId]);
+	const visibleColumnMetrics = useMemo(() => {
+		const widths = /* @__PURE__ */ new Map();
+		let totalWidth = selectionMode !== "none" ? 44 : 0;
+		for (const col of visibleColumns) {
+			const width = resolveColumnWidth(col, state.columnWidths[col.id]);
+			widths.set(col.id, width);
+			totalWidth += width;
+		}
+		return {
+			widths,
+			totalWidth
+		};
+	}, [
+		selectionMode,
+		state.columnWidths,
+		visibleColumns
+	]);
+	const gridSizingStyle = useMemo(() => createGridSizingStyle(visibleColumnMetrics.widths, visibleColumnMetrics.totalWidth), [visibleColumnMetrics]);
+	const resizeRef = useRef(null);
+	const gridRef = useRef(null);
+	const handleSort = useCallback((columnId, multi) => {
+		onChange((s) => {
+			const next = toggleSort(s.sorting, columnId, multi);
+			onSortChange?.(next);
+			return {
+				...s,
+				sorting: next
+			};
+		});
+	}, [onChange, onSortChange]);
+	const handleResize = useCallback((columnId, delta) => {
+		const col = allColumns.find((c) => c.id === columnId);
+		if (!col) return;
+		if (!resizeRef.current || resizeRef.current.columnId !== columnId) {
+			const baseWidth = visibleColumnMetrics.widths.get(columnId) ?? resolveColumnWidth(col, state.columnWidths[columnId]);
+			resizeRef.current = {
+				columnId,
+				baseWidth,
+				baseTotalWidth: visibleColumnMetrics.totalWidth,
+				latestWidth: baseWidth
+			};
+		}
+		const newWidth = clampColumnWidth(col, resizeRef.current.baseWidth + delta);
+		resizeRef.current.latestWidth = newWidth;
+		if (gridRef.current) applyDraggedColumnWidth(gridRef.current, columnId, newWidth, resizeRef.current.baseTotalWidth + (newWidth - resizeRef.current.baseWidth));
+	}, [
+		allColumns,
+		state.columnWidths,
+		visibleColumnMetrics
+	]);
+	useLayoutEffect(() => {
+		const r = resizeRef.current;
+		if (r && gridRef.current) applyDraggedColumnWidth(gridRef.current, r.columnId, r.latestWidth, r.baseTotalWidth + (r.latestWidth - r.baseWidth));
+	}, [gridSizingStyle]);
+	const handleResizeEnd = useCallback(() => {
+		const r = resizeRef.current;
+		resizeRef.current = null;
+		if (!r || r.latestWidth === r.baseWidth) return;
+		onChange((s) => ({
+			...s,
+			columnWidths: {
+				...s.columnWidths,
+				[r.columnId]: r.latestWidth
+			}
+		}));
+	}, [onChange]);
+	const handleRowClick = useCallback((row, rowId, event) => {
+		if (selectionMode !== "none") onChange((s) => {
+			const next = toggleRowSelection(s.selection, rowId, selectionMode, event.shiftKey, event.metaKey || event.ctrlKey, rowIds);
+			if (onSelectionChange) {
+				const selectedRows = rows.filter((r) => next.selectedIds.has(getRowId(r)));
+				setTimeout(() => onSelectionChange(next.selectedIds, selectedRows), 0);
+			}
+			return {
+				...s,
+				selection: next
+			};
+		});
+		onRowClick?.(row, rowId, event);
+	}, [
+		selectionMode,
+		onChange,
+		onRowClick,
+		onSelectionChange,
+		rowIds,
+		rows,
+		getRowId
+	]);
+	const handleRowSelectionCheckboxClick = useCallback((row, rowId, event) => {
+		handleRowClick(row, rowId, event);
+	}, [handleRowClick]);
+	const handleSelectAll = useCallback(() => {
+		onChange((s) => {
+			const allSelected = rowIds.every((id) => s.selection.selectedIds.has(id));
+			const next = allSelected ? clearSelection() : selectAll(rowIds);
+			if (onSelectionChange) {
+				const selectedRows = allSelected ? [] : rows;
+				setTimeout(() => onSelectionChange(next.selectedIds, [...selectedRows]), 0);
+			}
+			return {
+				...s,
+				selection: next
+			};
+		});
+	}, [
+		onChange,
+		rowIds,
+		rows,
+		onSelectionChange
+	]);
+	const handleExportCsv = useCallback(() => {
+		exportToCsv(rows, visibleColumns, exportFilename);
+	}, [
+		rows,
+		visibleColumns,
+		exportFilename
+	]);
+	const scrollContainerRef = useRef(null);
+	const headerScrollRef = useRef(null);
+	const rowVirtualizer = useVirtualizer({
+		count: rows.length,
+		getScrollElement: () => scrollContainerRef.current,
+		estimateSize: () => rowHeight,
+		overscan
+	});
+	const handleBodyScroll = useCallback(() => {
+		const body = scrollContainerRef.current;
+		const header = headerScrollRef.current;
+		if (body && header) header.scrollLeft = body.scrollLeft;
+	}, []);
+	const toolbarCtx = useMemo(() => ({
+		state,
+		onChange,
+		columns: allColumns,
+		visibleColumns,
+		totalRowCount,
+		selectedRowCount: state.selection.selectedIds.size,
+		strings,
+		exportCsv: handleExportCsv
+	}), [
+		state,
+		onChange,
+		allColumns,
+		visibleColumns,
+		totalRowCount,
+		strings,
+		handleExportCsv
+	]);
+	const footerCtx = useMemo(() => ({
+		state,
+		totalRowCount,
+		visibleRowCount: rows.length,
+		selectedRowCount: state.selection.selectedIds.size,
+		paginationMode,
+		strings
+	}), [
+		state,
+		totalRowCount,
+		rows.length,
+		paginationMode,
+		strings
+	]);
+	const allSelected = rowIds.length > 0 && rowIds.every((id) => state.selection.selectedIds.has(id));
+	const someSelected = !allSelected && rowIds.some((id) => state.selection.selectedIds.has(id));
+	return /* @__PURE__ */ jsxs("div", {
+		ref: gridRef,
+		className: cn("flex flex-col h-full min-h-0 bg-transparent", className),
+		style: maxHeight != null ? {
+			...gridSizingStyle,
+			maxHeight
+		} : gridSizingStyle,
+		role: "grid",
+		"aria-rowcount": totalRowCount ?? rows.length,
+		"aria-colcount": visibleColumns.length,
+		children: [
+			toolbar !== false && /* @__PURE__ */ jsx("div", {
+				className: "relative shrink-0 bg-transparent",
+				children: toolbar ? toolbar(toolbarCtx) : /* @__PURE__ */ jsx(DataGridToolbar, {
+					ctx: toolbarCtx,
+					extra: typeof toolbarExtra === "function" ? toolbarExtra(toolbarCtx) : toolbarExtra
+				})
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "relative flex min-h-0 flex-1 flex-col",
+				children: [
+					isRefetching && /* @__PURE__ */ jsx("div", {
+						className: "absolute top-0 left-0 right-0 h-0.5 z-30 bg-foreground/[0.04] overflow-hidden",
+						children: /* @__PURE__ */ jsx("div", { className: "h-full w-1/3 bg-blue-500/60 rounded-full animate-pulse" })
+					}),
+					/* @__PURE__ */ jsx("div", {
+						ref: headerScrollRef,
+						className: "overflow-hidden shrink-0 border-b border-foreground/[0.06]",
+						children: /* @__PURE__ */ jsxs("div", {
+							className: "flex",
+							style: {
+								height: headerHeight,
+								minWidth: visibleColumnMetrics.totalWidth
+							},
+							role: "row",
+							children: [selectionMode !== "none" && /* @__PURE__ */ jsx("div", {
+								className: "flex items-center justify-center border-r border-foreground/[0.04]",
+								style: { width: 44 },
+								children: selectionMode === "multiple" && /* @__PURE__ */ jsx(SelectionCheckbox, {
+									checked: allSelected,
+									indeterminate: someSelected,
+									onChange: handleSelectAll,
+									ariaLabel: "Select all rows"
+								})
+							}), visibleColumns.map((col) => /* @__PURE__ */ jsx(HeaderCell, {
+								col,
+								isSorted: getSortDirection(state.sorting, col.id),
+								sortIndex: getSortIndex(state.sorting, col.id),
+								resizable,
+								onSort: handleSort,
+								onResize: handleResize,
+								onResizeEnd: handleResizeEnd
+							}, col.id))]
+						})
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						ref: scrollContainerRef,
+						className: cn("min-h-0 overflow-auto flex-1 bg-transparent", "[&::-webkit-scrollbar]:w-1.5 [&::-webkit-scrollbar]:h-1.5", "[&::-webkit-scrollbar-track]:bg-transparent", "[&::-webkit-scrollbar-thumb]:bg-foreground/[0.08] [&::-webkit-scrollbar-thumb]:rounded-full", "[&::-webkit-scrollbar-thumb]:hover:bg-foreground/[0.15]"),
+						onScroll: handleBodyScroll,
+						children: [
+							isLoading && /* @__PURE__ */ jsx("div", {
+								style: { minWidth: visibleColumnMetrics.totalWidth },
+								children: loadingState ?? Array.from({ length: 8 }).map((_, i) => /* @__PURE__ */ jsx(SkeletonRow, {
+									columns: visibleColumns,
+									height: rowHeight,
+									showCheckbox: selectionMode !== "none"
+								}, i))
+							}),
+							!isLoading && rows.length === 0 && /* @__PURE__ */ jsx("div", {
+								className: "flex items-center justify-center py-16 text-sm text-muted-foreground",
+								style: { minWidth: visibleColumnMetrics.totalWidth },
+								children: emptyState ?? strings.noData
+							}),
+							!isLoading && rows.length > 0 && /* @__PURE__ */ jsx("div", {
+								style: {
+									height: rowVirtualizer.getTotalSize(),
+									width: "100%",
+									minWidth: visibleColumnMetrics.totalWidth,
+									position: "relative"
+								},
+								children: rowVirtualizer.getVirtualItems().map((virtualRow) => {
+									const row = rows[virtualRow.index];
+									const rowId = getRowId(row);
+									const isSelected = state.selection.selectedIds.has(rowId);
+									const isOddRow = virtualRow.index % 2 === 1;
+									return /* @__PURE__ */ jsxs("div", {
+										className: cn("absolute left-0 w-full flex", "border-b border-black/[0.03] dark:border-white/[0.03]", "transition-colors duration-75", isSelected ? "bg-blue-500/[0.06] dark:bg-blue-400/[0.08] hover:bg-blue-500/[0.08] dark:hover:bg-blue-400/[0.1]" : isOddRow ? "bg-foreground/[0.02] dark:bg-foreground/[0.03] hover:bg-foreground/[0.04] dark:hover:bg-foreground/[0.06]" : "hover:bg-foreground/[0.025] dark:hover:bg-foreground/[0.04]", selectionMode !== "none" && "cursor-pointer"),
+										style: {
+											height: rowHeight,
+											transform: `translateY(${virtualRow.start}px)`
+										},
+										onClick: (e) => handleRowClick(row, rowId, e),
+										onDoubleClick: (e) => onRowDoubleClick?.(row, rowId, e),
+										role: "row",
+										"aria-rowindex": virtualRow.index + 2,
+										"aria-selected": isSelected,
+										"data-row-id": rowId,
+										"data-state": isSelected ? "selected" : void 0,
+										children: [selectionMode !== "none" && /* @__PURE__ */ jsx("div", {
+											className: "flex items-center justify-center border-r border-black/[0.04] dark:border-white/[0.04]",
+											style: { width: 44 },
+											children: /* @__PURE__ */ jsx(SelectionCheckbox, {
+												checked: isSelected,
+												onChange: (event) => handleRowSelectionCheckboxClick(row, rowId, event),
+												ariaLabel: `Select row ${rowId}`
+											})
+										}), visibleColumns.map((col) => /* @__PURE__ */ jsx(DataCell, {
+											col,
+											row,
+											rowId,
+											rowIndex: virtualRow.index,
+											isSelected,
+											dateDisplay: state.dateDisplay
+										}, col.id))]
+									}, rowId);
+								})
+							}),
+							paginationMode === "infinite" && hasMore && !isLoading && /* @__PURE__ */ jsx(InfiniteScrollSentinel, {
+								onIntersect: onLoadMore ?? (() => {}),
+								isLoading: isLoadingMore,
+								strings
+							})
+						]
+					})
+				]
+			}),
+			footer !== false && /* @__PURE__ */ jsxs("div", {
+				className: "relative z-10 shrink-0 bg-transparent",
+				children: [footer ? footer(footerCtx) : /* @__PURE__ */ jsx(DefaultFooter, {
+					ctx: footerCtx,
+					pagination: paginationMode,
+					onChange
+				}), footerExtra && (typeof footerExtra === "function" ? footerExtra(footerCtx) : footerExtra)]
+			})
+		]
+	});
+}
+
+//#endregion
+export { DataGrid };
+//# sourceMappingURL=data-grid.js.map