@classytic/fluid 0.4.0 → 0.4.1

package/dist/client/spreadsheet.d.mts

@@ -0,0 +1,207 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react from "react";
+import { ComponentType, ReactNode } from "react";
+
+//#region src/components/spreadsheet/types.d.ts
+interface SpreadsheetColumn<TData = unknown> {
+  /** Unique column identifier — also used as the field key unless `field` is set */
+  id: string;
+  /** Optional field key on the data object (defaults to `id`) */
+  field?: string;
+  /** Column header label */
+  header: string | ReactNode;
+  /** CSS width: '20%', '120px', 'minmax(100px, 1fr)', etc. */
+  width: string;
+  /** Text alignment */
+  align?: "left" | "right" | "center";
+  /** Component that renders the cell content */
+  cell: ComponentType<CellRenderProps<TData>>;
+  /** Label shown above the field in mobile card layout */
+  mobileLabel?: string;
+  /** grid-cols-12 span for mobile card layout (default 12 = full width) */
+  mobileSpan?: number;
+  /** Hide column conditionally (e.g., hide actions when read-only) */
+  hiddenWhen?: (ctx: {
+    isReadOnly: boolean;
+  }) => boolean;
+  /** Data type hint for clipboard paste coercion. "number" coerces pasted strings to numbers. */
+  dataType?: "string" | "number";
+}
+interface CellRenderProps<TData = unknown> {
+  /** Current field value */
+  value: unknown;
+  /** Full row data object */
+  row: TData;
+  /** Stable row ID (UUID) */
+  rowId: string;
+  /** Visual row index (0-based, accounts for filtering) */
+  rowIndex: number;
+  /** Column definition */
+  column: SpreadsheetColumn<TData>;
+  /**
+   * Commit a value change.
+   * - Single field: `onChange("debit", 100)`
+   * - Multi-field batch: `onChange({ debit: 100, credit: 0 })`
+   */
+  onChange: (fieldOrPatch: string | Record<string, unknown>, value?: unknown) => void;
+  /** Whether the spreadsheet is in read-only mode */
+  isReadOnly: boolean;
+  /** Data attributes for keyboard navigation */
+  cellRef?: string;
+}
+interface SpreadsheetTableProps<TData = unknown> {
+  /** Column definitions */
+  columns: SpreadsheetColumn<TData>[];
+  /** Items state from useSpreadsheetStore */
+  items: Map<string, TData>;
+  /** Ordered row IDs (can be pre-filtered for search) */
+  orderedIds: string[];
+  /** Dispatch function from useSpreadsheetStore */
+  dispatch: (action: SpreadsheetAction<TData>) => void;
+  /** Read-only mode (e.g., posted journal entries) */
+  isReadOnly?: boolean;
+  /** Enable row virtualization (recommended when > 30 rows) */
+  virtualize?: boolean;
+  /** Estimated row height for virtualization (default: 48) */
+  estimateRowHeight?: number;
+  /** Render a footer row (e.g., totals) — used inside <tfoot> on desktop */
+  footer?: ReactNode;
+  /** Separate footer for mobile card layout (avoids <tr> inside <div>) */
+  mobileFooter?: ReactNode;
+  /** Render row action buttons (add/remove) */
+  rowActions?: (props: {
+    rowId: string;
+    rowIndex: number;
+    isReadOnly: boolean;
+  }) => ReactNode;
+  /** CSS class for the table container */
+  className?: string;
+  /** Accessible label for the table */
+  ariaLabel?: string;
+  /** Called when a row is added (receives the ID of the row to insert after) */
+  onAddRow?: (afterRowId: string) => void;
+  /** Called when a row is removed */
+  onRemoveRow?: (rowId: string) => void;
+}
+interface SpreadsheetState<TData> {
+  items: Map<string, TData>;
+  orderedIds: string[];
+}
+type SpreadsheetAction<TData = unknown> = {
+  type: "SET_ALL";
+  items: TData[];
+  getId?: (item: TData) => string;
+} | {
+  type: "UPDATE_CELL";
+  rowId: string;
+  field: string;
+  value: unknown;
+} | {
+  type: "UPDATE_ROW";
+  rowId: string;
+  patch: Partial<TData>;
+} | {
+  type: "ADD_ROW";
+  afterRowId: string;
+  item: TData;
+  newId?: string;
+} | {
+  type: "REMOVE_ROW";
+  rowId: string;
+} | {
+  type: "BATCH";
+  actions: SpreadsheetAction<TData>[];
+};
+//#endregion
+//#region src/components/spreadsheet/spreadsheet-table.d.ts
+declare function SpreadsheetTable<TData = unknown>({
+  columns,
+  items,
+  orderedIds,
+  dispatch,
+  isReadOnly,
+  footer,
+  mobileFooter,
+  rowActions,
+  className,
+  ariaLabel,
+  onAddRow,
+  virtualize,
+  estimateRowHeight
+}: SpreadsheetTableProps<TData>): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/components/spreadsheet/spreadsheet-row.d.ts
+interface SpreadsheetRowProps<TData = unknown> {
+  rowId: string;
+  rowIndex: number;
+  item: TData;
+  visibleColumns: SpreadsheetColumn<TData>[];
+  dispatch: (action: SpreadsheetAction<TData>) => void;
+  isReadOnly: boolean;
+  rowActions?: (props: {
+    rowId: string;
+    rowIndex: number;
+    isReadOnly: boolean;
+  }) => ReactNode;
+  onCellKeyDown?: (e: React.KeyboardEvent, rowId: string, colId: string) => void;
+  cellAttr?: string;
+  isMobile?: boolean;
+  style?: React.CSSProperties;
+  /** Ref callback from virtualizer for dynamic row measurement */
+  measureRef?: (node: HTMLElement | null) => void;
+}
+declare function SpreadsheetRowInner<TData>({
+  rowId,
+  rowIndex,
+  item,
+  visibleColumns,
+  dispatch,
+  isReadOnly,
+  rowActions,
+  onCellKeyDown,
+  cellAttr,
+  isMobile,
+  style,
+  measureRef
+}: SpreadsheetRowProps<TData>): react_jsx_runtime0.JSX.Element;
+declare const SpreadsheetRow: typeof SpreadsheetRowInner;
+//#endregion
+//#region src/components/spreadsheet/use-spreadsheet-store.d.ts
+declare function useSpreadsheetStore<TData>(initialItems?: TData[], getId?: (item: TData) => string): {
+  items: Map<string, TData>;
+  orderedIds: string[];
+  dispatch: react.ActionDispatch<[action: SpreadsheetAction<TData>]>;
+  getOrderedItems: () => TData[];
+  rowCount: number;
+};
+type SpreadsheetStore<TData> = ReturnType<typeof useSpreadsheetStore<TData>>;
+//#endregion
+//#region src/components/spreadsheet/use-spreadsheet-keyboard.d.ts
+interface UseSpreadsheetKeyboardOptions {
+  /** Ordered row IDs (visible/filtered) */
+  orderedIds: string[];
+  /** Column IDs in display order */
+  columnIds: string[];
+  /** Ref to the table container element */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Add a row when navigating past the end */
+  onAddRow?: (afterRowId: string) => void;
+}
+/**
+ * Keyboard navigation for spreadsheet cells.
+ *
+ * Tab → next cell → wrap to next row
+ * Shift+Tab → previous cell → wrap to previous row
+ * Enter → commit + move down (same column, next row)
+ */
+declare function useSpreadsheetKeyboard({
+  orderedIds,
+  columnIds,
+  containerRef,
+  onAddRow
+}: UseSpreadsheetKeyboardOptions): {
+  handleCellKeyDown: (e: React.KeyboardEvent, rowId: string, colId: string) => void;
+  CELL_ATTR: string;
+};
+//#endregion
+export { type CellRenderProps, type SpreadsheetAction, type SpreadsheetColumn, SpreadsheetRow, type SpreadsheetState, type SpreadsheetStore, SpreadsheetTable, type SpreadsheetTableProps, useSpreadsheetKeyboard, useSpreadsheetStore };

package/dist/client/spreadsheet.mjs

@@ -0,0 +1,611 @@
+"use client";
+
+import { jsx, jsxs } from "react/jsx-runtime";
+import { memo, useCallback, useEffect, useMemo, useReducer, useRef } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+
+//#region src/components/spreadsheet/spreadsheet-row.tsx
+function SpreadsheetRowInner({ rowId, rowIndex, item, visibleColumns, dispatch, isReadOnly, rowActions, onCellKeyDown, cellAttr = "data-cell", isMobile = false, style, measureRef }) {
+	const handleChange = useCallback((fieldOrPatch, value) => {
+		if (typeof fieldOrPatch === "string") dispatch({
+			type: "UPDATE_CELL",
+			rowId,
+			field: fieldOrPatch,
+			value
+		});
+		else dispatch({
+			type: "UPDATE_ROW",
+			rowId,
+			patch: fieldOrPatch
+		});
+	}, [dispatch, rowId]);
+	if (isMobile) return /* @__PURE__ */ jsxs("div", {
+		className: "rounded-lg border bg-card p-3 space-y-2",
+		children: [/* @__PURE__ */ jsx("div", {
+			className: "grid grid-cols-12 gap-2",
+			children: visibleColumns.map((col) => {
+				const CellComponent = col.cell;
+				const field = col.field ?? col.id;
+				const value = item?.[field];
+				return /* @__PURE__ */ jsxs("div", {
+					style: { gridColumn: `span ${col.mobileSpan ?? 12}` },
+					[cellAttr]: `${rowId}:${col.id}`,
+					children: [col.mobileLabel && /* @__PURE__ */ jsx("label", {
+						className: "text-xs text-muted-foreground mb-1 block",
+						children: col.mobileLabel
+					}), /* @__PURE__ */ jsx(CellComponent, {
+						value,
+						row: item,
+						rowId,
+						rowIndex,
+						column: col,
+						onChange: handleChange,
+						isReadOnly
+					})]
+				}, col.id);
+			})
+		}), rowActions && /* @__PURE__ */ jsx("div", {
+			className: "flex justify-end pt-1",
+			children: rowActions({
+				rowId,
+				rowIndex,
+				isReadOnly
+			})
+		})]
+	});
+	const isVirtual = !!style;
+	return /* @__PURE__ */ jsxs("tr", {
+		ref: measureRef,
+		"data-index": measureRef ? rowIndex : void 0,
+		className: "border-b transition-colors hover:bg-muted/30",
+		style,
+		children: [visibleColumns.map((col) => {
+			const CellComponent = col.cell;
+			const field = col.field ?? col.id;
+			const value = item?.[field];
+			return /* @__PURE__ */ jsx("td", {
+				className: `px-2 py-1 overflow-hidden ${col.align === "right" ? "text-right" : col.align === "center" ? "text-center" : "text-left"}`,
+				style: isVirtual ? {
+					flex: `0 0 ${col.width}`,
+					minWidth: 0
+				} : void 0,
+				[cellAttr]: `${rowId}:${col.id}`,
+				onKeyDown: onCellKeyDown ? (e) => onCellKeyDown(e, rowId, col.id) : void 0,
+				children: /* @__PURE__ */ jsx(CellComponent, {
+					value,
+					row: item,
+					rowId,
+					rowIndex,
+					column: col,
+					onChange: handleChange,
+					isReadOnly
+				})
+			}, col.id);
+		}), rowActions && /* @__PURE__ */ jsx("td", {
+			className: "px-2 py-1",
+			style: isVirtual ? {
+				flex: "0 0 8%",
+				minWidth: 0
+			} : { width: "8%" },
+			children: rowActions({
+				rowId,
+				rowIndex,
+				isReadOnly
+			})
+		})]
+	});
+}
+function rowPropsAreEqual(prev, next) {
+	return prev.rowId === next.rowId && prev.rowIndex === next.rowIndex && prev.item === next.item && prev.isReadOnly === next.isReadOnly && prev.isMobile === next.isMobile && prev.visibleColumns === next.visibleColumns && prev.measureRef === next.measureRef && prev.style?.transform === next.style?.transform;
+}
+const SpreadsheetRow = memo(SpreadsheetRowInner, rowPropsAreEqual);
+
+//#endregion
+//#region src/components/spreadsheet/use-spreadsheet-keyboard.ts
+/**
+* Data attribute used to mark focusable cells for keyboard navigation.
+* Each cell should have: data-cell="rowId:colId"
+*/
+const CELL_ATTR = "data-cell";
+function findCell(container, rowId, colId) {
+	return container.querySelector(`[${CELL_ATTR}="${rowId}:${colId}"]`);
+}
+function focusCell(cell) {
+	const focusable = cell.querySelector("input, select, textarea, button, [tabindex]:not([tabindex=\"-1\"])");
+	if (focusable) focusable.focus();
+	else cell.focus();
+}
+/**
+* Keyboard navigation for spreadsheet cells.
+*
+* Tab → next cell → wrap to next row
+* Shift+Tab → previous cell → wrap to previous row
+* Enter → commit + move down (same column, next row)
+*/
+function useSpreadsheetKeyboard({ orderedIds, columnIds, containerRef, onAddRow }) {
+	const orderedIdsRef = useRef(orderedIds);
+	const columnIdsRef = useRef(columnIds);
+	const onAddRowRef = useRef(onAddRow);
+	useEffect(() => {
+		orderedIdsRef.current = orderedIds;
+		columnIdsRef.current = columnIds;
+		onAddRowRef.current = onAddRow;
+	}, [
+		orderedIds,
+		columnIds,
+		onAddRow
+	]);
+	return {
+		handleCellKeyDown: useCallback((e, rowId, colId) => {
+			const container = containerRef.current;
+			if (!container) return;
+			const currentOrderedIds = orderedIdsRef.current;
+			const currentColumnIds = columnIdsRef.current;
+			const rowIdx = currentOrderedIds.indexOf(rowId);
+			const colIdx = currentColumnIds.indexOf(colId);
+			if (rowIdx === -1 || colIdx === -1) return;
+			let targetRowIdx = rowIdx;
+			let targetColIdx = colIdx;
+			if (e.key === "Tab") {
+				e.preventDefault();
+				if (e.shiftKey) {
+					targetColIdx--;
+					if (targetColIdx < 0) {
+						targetRowIdx--;
+						targetColIdx = currentColumnIds.length - 1;
+					}
+				} else {
+					targetColIdx++;
+					if (targetColIdx >= currentColumnIds.length) {
+						targetRowIdx++;
+						targetColIdx = 0;
+					}
+				}
+			} else if (e.key === "Enter" && !e.shiftKey) {
+				if (document.activeElement instanceof HTMLElement) document.activeElement.blur();
+				e.preventDefault();
+				targetRowIdx++;
+			} else if (e.key === "ArrowDown") {
+				e.preventDefault();
+				targetRowIdx++;
+			} else if (e.key === "ArrowUp") {
+				e.preventDefault();
+				targetRowIdx--;
+			} else if (e.key === "ArrowRight") {
+				const active = document.activeElement;
+				if (!active || active.tagName !== "INPUT" || active.selectionStart === active.value?.length) {
+					e.preventDefault();
+					targetColIdx++;
+				} else return;
+			} else if (e.key === "ArrowLeft") {
+				const active = document.activeElement;
+				if (!active || active.tagName !== "INPUT" || active.selectionEnd === 0) {
+					e.preventDefault();
+					targetColIdx--;
+				} else return;
+			} else return;
+			if (targetRowIdx >= currentOrderedIds.length) {
+				if (onAddRowRef.current) {
+					const lastRowId = currentOrderedIds[currentOrderedIds.length - 1];
+					onAddRowRef.current(lastRowId);
+				}
+				return;
+			}
+			if (targetRowIdx < 0) return;
+			if (targetColIdx < 0 || targetColIdx >= currentColumnIds.length) return;
+			const targetRowId = currentOrderedIds[targetRowIdx];
+			const targetColId = currentColumnIds[targetColIdx];
+			const targetCell = findCell(container, targetRowId, targetColId);
+			if (targetCell) requestAnimationFrame(() => focusCell(targetCell));
+		}, [containerRef]),
+		CELL_ATTR
+	};
+}
+
+//#endregion
+//#region src/components/spreadsheet/use-spreadsheet-clipboard.ts
+/**
+* Handles copy/pasting from Excel or other spreadsheets natively.
+* Supports matrix pasting (multiple rows and columns at once) via BATCH updates.
+*/
+function useSpreadsheetClipboard({ containerRef, orderedIds, columns, dispatch, isReadOnly = false }) {
+	const orderedIdsRef = useRef(orderedIds);
+	const columnsRef = useRef(columns);
+	const isReadOnlyRef = useRef(isReadOnly);
+	useEffect(() => {
+		orderedIdsRef.current = orderedIds;
+		columnsRef.current = columns;
+		isReadOnlyRef.current = isReadOnly;
+	}, [
+		orderedIds,
+		columns,
+		isReadOnly
+	]);
+	useEffect(() => {
+		const container = containerRef.current;
+		if (!container) return;
+		function handlePaste(e) {
+			if (isReadOnlyRef.current) return;
+			const activeElement = document.activeElement;
+			if (!activeElement || !container?.contains(activeElement)) return;
+			const cellElement = activeElement.closest("[data-cell]");
+			if (!cellElement) return;
+			const cellCoord = cellElement.getAttribute("data-cell");
+			if (!cellCoord) return;
+			const [startRowId, startColId] = cellCoord.split(":");
+			const clipboardData = e.clipboardData;
+			if (!clipboardData) return;
+			const pastedText = clipboardData.getData("text/plain");
+			if (!pastedText) return;
+			if (!(pastedText.includes("	") || pastedText.includes("\n"))) return;
+			e.preventDefault();
+			const currentOrderedIds = orderedIdsRef.current;
+			const visibleCols = columnsRef.current.filter((c) => !c.hiddenWhen?.({ isReadOnly: isReadOnlyRef.current }));
+			const startRowIdx = currentOrderedIds.indexOf(startRowId);
+			const startColIdx = visibleCols.findIndex((c) => c.id === startColId);
+			if (startRowIdx === -1 || startColIdx === -1) return;
+			const rows = pastedText.replace(/\r?\n$/, "").split(/\r?\n/);
+			const batchActions = [];
+			rows.forEach((row, rIdx) => {
+				const targetRowIdx = startRowIdx + rIdx;
+				if (targetRowIdx >= currentOrderedIds.length) return;
+				const targetRowId = currentOrderedIds[targetRowIdx];
+				row.split("	").forEach((cellValue, cIdx) => {
+					const targetColIdx = startColIdx + cIdx;
+					if (targetColIdx >= visibleCols.length) return;
+					const col = visibleCols[targetColIdx];
+					const field = col.field ?? col.id;
+					let value = cellValue;
+					if (col.dataType === "number") {
+						const num = Number(cellValue);
+						value = isNaN(num) ? 0 : num;
+					}
+					batchActions.push({
+						type: "UPDATE_CELL",
+						rowId: targetRowId,
+						field,
+						value
+					});
+				});
+			});
+			if (batchActions.length > 0) dispatch({
+				type: "BATCH",
+				actions: batchActions
+			});
+		}
+		container.addEventListener("paste", handlePaste);
+		return () => container.removeEventListener("paste", handlePaste);
+	}, [containerRef, dispatch]);
+}
+
+//#endregion
+//#region src/components/spreadsheet/spreadsheet-table.tsx
+const VIRTUAL_ROW_BASE = {
+	display: "flex",
+	alignItems: "stretch",
+	position: "absolute",
+	top: 0,
+	left: 0,
+	width: "100%",
+	willChange: "transform"
+};
+function SpreadsheetTable({ columns, items, orderedIds, dispatch, isReadOnly = false, footer, mobileFooter, rowActions, className = "", ariaLabel = "Spreadsheet", onAddRow, virtualize = false, estimateRowHeight = 48 }) {
+	const containerRef = useRef(null);
+	const tableContainerRef = useRef(null);
+	const mobileContainerRef = useRef(null);
+	const visibleColumns = useMemo(() => columns.filter((col) => !col.hiddenWhen?.({ isReadOnly })), [columns, isReadOnly]);
+	const { handleCellKeyDown, CELL_ATTR } = useSpreadsheetKeyboard({
+		orderedIds,
+		columnIds: useMemo(() => visibleColumns.map((col) => col.id), [visibleColumns]),
+		containerRef,
+		onAddRow
+	});
+	useSpreadsheetClipboard({
+		containerRef,
+		orderedIds,
+		columns,
+		dispatch,
+		isReadOnly
+	});
+	const getItemKey = useCallback((index) => orderedIds[index] ?? index, [orderedIds]);
+	const estimateSize = useCallback(() => estimateRowHeight, [estimateRowHeight]);
+	const desktopVirtualizer = useVirtualizer({
+		count: orderedIds.length,
+		getScrollElement: () => tableContainerRef.current,
+		estimateSize,
+		measureElement: virtualize ? (el) => el.getBoundingClientRect().height : void 0,
+		overscan: 5,
+		getItemKey,
+		enabled: virtualize
+	});
+	const mobileVirtualizer = useVirtualizer({
+		count: orderedIds.length,
+		getScrollElement: () => mobileContainerRef.current,
+		estimateSize,
+		measureElement: virtualize ? (el) => el.getBoundingClientRect().height : void 0,
+		overscan: 3,
+		getItemKey,
+		enabled: virtualize
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		ref: containerRef,
+		className,
+		children: [/* @__PURE__ */ jsx("div", {
+			ref: tableContainerRef,
+			className: "hidden md:block overflow-x-auto",
+			style: virtualize ? {
+				maxHeight: "600px",
+				overflowY: "auto"
+			} : void 0,
+			children: /* @__PURE__ */ jsxs("table", {
+				className: "w-full border-collapse table-fixed",
+				style: { minWidth: "800px" },
+				"aria-label": ariaLabel,
+				children: [
+					/* @__PURE__ */ jsx("thead", {
+						className: "sticky top-0 z-10 bg-background",
+						children: /* @__PURE__ */ jsxs("tr", {
+							className: "border-b bg-muted/50",
+							style: virtualize ? {
+								display: "flex",
+								width: "100%"
+							} : void 0,
+							children: [visibleColumns.map((col) => /* @__PURE__ */ jsx("th", {
+								className: `px-2 py-2 text-xs font-medium text-muted-foreground ${col.align === "right" ? "text-right" : col.align === "center" ? "text-center" : "text-left"}`,
+								style: virtualize ? {
+									width: col.width,
+									flex: `0 0 ${col.width}`,
+									minWidth: 0
+								} : { width: col.width },
+								children: col.header
+							}, col.id)), rowActions && /* @__PURE__ */ jsx("th", {
+								className: "px-2 py-2",
+								style: virtualize ? {
+									width: "8%",
+									flex: "0 0 8%",
+									minWidth: 0
+								} : { width: "8%" }
+							})]
+						})
+					}),
+					/* @__PURE__ */ jsx("tbody", {
+						style: virtualize ? {
+							height: `${desktopVirtualizer.getTotalSize()}px`,
+							position: "relative"
+						} : void 0,
+						children: virtualize ? desktopVirtualizer.getVirtualItems().map((virtualRow) => {
+							const rowId = orderedIds[virtualRow.index];
+							const item = items.get(rowId);
+							if (!item) return null;
+							return /* @__PURE__ */ jsx(SpreadsheetRow, {
+								rowId,
+								rowIndex: virtualRow.index,
+								item,
+								visibleColumns,
+								dispatch,
+								isReadOnly,
+								rowActions,
+								onCellKeyDown: handleCellKeyDown,
+								cellAttr: CELL_ATTR,
+								isMobile: false,
+								measureRef: desktopVirtualizer.measureElement,
+								style: {
+									...VIRTUAL_ROW_BASE,
+									transform: `translateY(${virtualRow.start}px)`
+								}
+							}, virtualRow.key);
+						}) : orderedIds.map((rowId, index) => {
+							const item = items.get(rowId);
+							if (!item) return null;
+							return /* @__PURE__ */ jsx(SpreadsheetRow, {
+								rowId,
+								rowIndex: index,
+								item,
+								visibleColumns,
+								dispatch,
+								isReadOnly,
+								rowActions,
+								onCellKeyDown: handleCellKeyDown,
+								cellAttr: CELL_ATTR,
+								isMobile: false
+							}, rowId);
+						})
+					}),
+					footer && /* @__PURE__ */ jsx("tfoot", { children: footer })
+				]
+			})
+		}), /* @__PURE__ */ jsxs("div", {
+			ref: mobileContainerRef,
+			className: "md:hidden space-y-3",
+			style: virtualize ? {
+				maxHeight: "600px",
+				overflowY: "auto"
+			} : void 0,
+			children: [/* @__PURE__ */ jsx("div", {
+				style: virtualize ? {
+					height: `${mobileVirtualizer.getTotalSize()}px`,
+					position: "relative"
+				} : void 0,
+				children: virtualize ? mobileVirtualizer.getVirtualItems().map((virtualRow) => {
+					const rowId = orderedIds[virtualRow.index];
+					const item = items.get(rowId);
+					if (!item) return null;
+					return /* @__PURE__ */ jsx(SpreadsheetRow, {
+						rowId,
+						rowIndex: virtualRow.index,
+						item,
+						visibleColumns,
+						dispatch,
+						isReadOnly,
+						rowActions,
+						cellAttr: CELL_ATTR,
+						isMobile: true,
+						measureRef: mobileVirtualizer.measureElement,
+						style: {
+							...VIRTUAL_ROW_BASE,
+							transform: `translateY(${virtualRow.start}px)`
+						}
+					}, virtualRow.key);
+				}) : orderedIds.map((rowId, index) => {
+					const item = items.get(rowId);
+					if (!item) return null;
+					return /* @__PURE__ */ jsx(SpreadsheetRow, {
+						rowId,
+						rowIndex: index,
+						item,
+						visibleColumns,
+						dispatch,
+						isReadOnly,
+						rowActions,
+						cellAttr: CELL_ATTR,
+						isMobile: true
+					}, rowId);
+				})
+			}), mobileFooter && /* @__PURE__ */ jsx("div", {
+				className: "rounded-lg border bg-card p-3",
+				children: mobileFooter
+			})]
+		})]
+	});
+}
+
+//#endregion
+//#region src/components/spreadsheet/use-spreadsheet-store.ts
+function defaultGetId(item) {
+	if (item && typeof item === "object") {
+		const obj = item;
+		const id = obj._id ?? obj.id;
+		if (typeof id === "string" && id) return id;
+	}
+	return crypto.randomUUID();
+}
+function spreadsheetReducer(state, action) {
+	switch (action.type) {
+		case "SET_ALL": {
+			const getId = action.getId ?? defaultGetId;
+			const items = /* @__PURE__ */ new Map();
+			const orderedIds = [];
+			for (const item of action.items) {
+				let id = getId(item);
+				while (items.has(id)) id = `${id}_${crypto.randomUUID().slice(0, 8)}`;
+				items.set(id, item);
+				orderedIds.push(id);
+			}
+			return {
+				items,
+				orderedIds
+			};
+		}
+		case "UPDATE_CELL": {
+			const existing = state.items.get(action.rowId);
+			if (!existing) return state;
+			const updated = {
+				...existing,
+				[action.field]: action.value
+			};
+			const newItems = new Map(state.items);
+			newItems.set(action.rowId, updated);
+			return {
+				...state,
+				items: newItems
+			};
+		}
+		case "UPDATE_ROW": {
+			const existing = state.items.get(action.rowId);
+			if (!existing) return state;
+			const updated = {
+				...existing,
+				...action.patch
+			};
+			const newItems = new Map(state.items);
+			newItems.set(action.rowId, updated);
+			return {
+				...state,
+				items: newItems
+			};
+		}
+		case "ADD_ROW": {
+			const newId = action.newId ?? crypto.randomUUID();
+			const newItems = new Map(state.items);
+			newItems.set(newId, action.item);
+			const idx = state.orderedIds.indexOf(action.afterRowId);
+			const insertAt = idx === -1 ? state.orderedIds.length : idx + 1;
+			const newIds = [...state.orderedIds];
+			newIds.splice(insertAt, 0, newId);
+			return {
+				items: newItems,
+				orderedIds: newIds
+			};
+		}
+		case "REMOVE_ROW": {
+			if (state.orderedIds.length <= 1) return state;
+			const newItems = new Map(state.items);
+			newItems.delete(action.rowId);
+			return {
+				items: newItems,
+				orderedIds: state.orderedIds.filter((id) => id !== action.rowId)
+			};
+		}
+		case "BATCH": {
+			if (action.actions.every((a) => a.type === "UPDATE_CELL")) {
+				const newItems = new Map(state.items);
+				for (const sub of action.actions) {
+					if (sub.type !== "UPDATE_CELL") continue;
+					const existing = newItems.get(sub.rowId);
+					if (!existing) continue;
+					newItems.set(sub.rowId, {
+						...existing,
+						[sub.field]: sub.value
+					});
+				}
+				return {
+					...state,
+					items: newItems
+				};
+			}
+			let current = state;
+			for (const sub of action.actions) current = spreadsheetReducer(current, sub);
+			return current;
+		}
+		default: return state;
+	}
+}
+const EMPTY_STATE = {
+	items: /* @__PURE__ */ new Map(),
+	orderedIds: []
+};
+function useSpreadsheetStore(initialItems, getId) {
+	const [state, dispatch] = useReducer(spreadsheetReducer, initialItems, (items) => {
+		if (!items || items.length === 0) return EMPTY_STATE;
+		return spreadsheetReducer(EMPTY_STATE, {
+			type: "SET_ALL",
+			items,
+			getId
+		});
+	});
+	const stateRef = useRef(state);
+	stateRef.current = state;
+	/** Get items as an ordered array (for API submission) — stable reference */
+	const getOrderedItems = useCallback(() => {
+		const { orderedIds, items } = stateRef.current;
+		return orderedIds.map((id) => items.get(id)).filter(Boolean);
+	}, []);
+	/** Convenience: total row count */
+	const rowCount = state.orderedIds.length;
+	return useMemo(() => ({
+		items: state.items,
+		orderedIds: state.orderedIds,
+		dispatch,
+		getOrderedItems,
+		rowCount
+	}), [
+		state.items,
+		state.orderedIds,
+		dispatch,
+		getOrderedItems,
+		rowCount
+	]);
+}
+
+//#endregion
+export { SpreadsheetRow, SpreadsheetTable, useSpreadsheetKeyboard, useSpreadsheetStore };

package/dist/forms.mjs

@@ -1325,7 +1325,7 @@ function TagChoiceInputInternal({ name, label, description, placeholder = "Selec
 					}),
 					children: [/* @__PURE__ */ jsx("div", {
 						className: "flex flex-1 flex-wrap items-center gap-1 px-3 py-1.5 min-h-[2.25rem]",
-						children: selectedValues.length > 0 ? selectedValues.map((val) => {
+						children: selectedValues.length > 0 ? selectedValues.map((val, idx) => {
 							const item = items.find((i) => i.value === val);
 							return /* @__PURE__ */ jsxs(Badge, {
 								variant: "secondary",
@@ -1338,7 +1338,7 @@ function TagChoiceInputInternal({ name, label, description, placeholder = "Selec
 									"aria-label": `Remove ${item?.label || val}`,
 									children: /* @__PURE__ */ jsx(X, { className: "h-3 w-3" })
 								})]
-							}, val);
+							}, val || `tag-${idx}`);
 						}) : /* @__PURE__ */ jsx("span", {
 							className: "text-sm text-muted-foreground",
 							children: placeholder
@@ -1485,7 +1485,7 @@ function ComboboxInput({ control, name, label, placeholder = "Select...", emptyT
 	onValueChangeRef.current = onValueChange;
 	const propOnChangeRef = useRef(propOnChange);
 	propOnChangeRef.current = propOnChange;
-	const fieldRef = useRef();
+	const fieldRef = useRef(void 0);
 	const handleValueChange = useCallback((newItem) => {
 		const safeValue = newItem?.value || "";
 		if (safeValue === currentValueRef.current) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/fluid",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Fluid UI - Custom components built on shadcn/ui and base ui by Classytic",
   "main": "./dist/index.mjs",
@@ -35,6 +35,10 @@
       "types": "./dist/client/calendar.d.mts",
       "default": "./dist/client/calendar.mjs"
     },
+    "./client/spreadsheet": {
+      "types": "./dist/client/spreadsheet.d.mts",
+      "default": "./dist/client/spreadsheet.mjs"
+    },
     "./forms": {
       "types": "./dist/forms.d.mts",
       "default": "./dist/forms.mjs"
@@ -71,30 +75,36 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit",
     "clean": "rimraf dist",
-    "prepublishOnly": "npm run clean && npm run build"
+    "prepublishOnly": "npm run typecheck && npm test && npm run clean && npm run build"
   },
   "peerDependencies": {
-    "@tanstack/react-table": "^8.21.0",
-    "class-variance-authority": "^0.7.0",
-    "clsx": "^2.1.0",
-    "date-fns": "^4.1.0",
+    "@tanstack/react-table": ">=8.21.0",
+    "@tanstack/react-virtual": ">=3.11.2",
+    "class-variance-authority": ">=0.7.0",
+    "clsx": ">=2.1.0",
+    "date-fns": ">=4.1.0",
     "lucide-react": ">=0.460.0",
-    "next": "^15.0.0 || ^16.0.0",
-    "next-themes": "^0.4.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-error-boundary": "^4.0.0 || ^5.0.0 || ^6.0.0",
-    "react-hook-form": "^7.54.0",
-    "tailwind-merge": "^2.2.0 || ^3.0.0",
-    "vaul": "^1.0.0"
+    "next": ">=16.0.0",
+    "next-themes": ">=0.4.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "react-error-boundary": ">=6.0.0",
+    "react-hook-form": ">=7.54.0",
+    "tailwind-merge": ">=2.2.0",
+    "vaul": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-table": {
       "optional": true
     },
+    "@tanstack/react-virtual": {
+      "optional": true
+    },
     "next-themes": {
       "optional": true
     },
@@ -113,12 +123,18 @@
   },
   "devDependencies": {
     "@tanstack/react-table": "^8.21.0",
+    "@tanstack/react-virtual": "^3.13.23",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.0",
     "date-fns": "^4.1.0",
+    "jsdom": "^29.0.0",
     "lucide-react": "^0.460.0",
     "next-themes": "^0.4.0",
     "react": "^19.0.0",
@@ -128,7 +144,8 @@
     "rimraf": "^5.0.0",
     "tailwind-merge": "^3.5.0",
     "tsdown": "^0.21.0-beta.2",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
   },
   "publishConfig": {
     "access": "public"