@vueye-table/core 3.0.0-alpha.1 → 3.0.0-alpha.2

package/dist/index.js

@@ -8,13 +8,34 @@ function humanize(id) {
 	return sentence.charAt(0).toUpperCase() + sentence.slice(1);
 }
 
+//#endregion
+//#region src/issues.ts
+function issue(code, message, details = {}) {
+	return Object.freeze({
+		code,
+		message,
+		...details
+	});
+}
+
 //#endregion
 //#region src/path.ts
+/**
+* Dotted property paths.
+*
+* A column addresses nested data with a path such as `"address.city"`. The types below give every
+* such path its value type, and the functions read and write through a path without mutating.
+*/
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
+/** Whether every path segment can be read or written without addressing a prototype. */
+function isSafePath(path) {
+	return path.split(".").every((segment) => segment !== "__proto__" && segment !== "constructor" && segment !== "prototype");
+}
 /** Read the value at a dotted path, or `undefined` when a step is missing. */
 function getPath(source, path) {
+	if (!isSafePath(path)) return;
 	let current = source;
 	for (const segment of path.split(".")) {
 		if (!isRecord$1(current)) return;
@@ -24,13 +45,18 @@ function getPath(source, path) {
 }
 /**
 * Return a copy of `source` with `value` at `path`. Only the objects along the path are copied;
-* everything else is shared. Missing steps are created as plain objects.
+* everything else is shared. Missing steps are created as plain objects. Unsafe paths return
+* `source` unchanged and report an `unsafe_path` issue through `onIssue`, when supplied.
 */
-function setPath(source, path, value) {
+function setPath(source, path, value, onIssue) {
+	if (!isSafePath(path)) {
+		onIssue?.(issue("unsafe_path", `The path "${path}" addresses a prototype and cannot be written.`, { column: path }));
+		return source;
+	}
 	const [head, ...rest] = path.split(".");
 	const base = isRecord$1(source) ? { ...source } : {};
 	if (head === void 0) return source;
-	base[head] = rest.length === 0 ? value : setPath(base[head], rest.join("."), value);
+	base[head] = rest.length === 0 ? value : setPath(Object.hasOwn(base, head) ? base[head] : void 0, rest.join("."), value);
 	return base;
 }
 
@@ -197,14 +223,15 @@ function parseAs(input, type) {
 function resolveColumn(definition) {
 	const def = definition;
 	const { accessor } = def;
-	const getValue = accessor ?? ((row) => getPath(row, def.id));
+	const safe = isSafePath(def.id);
+	const getValue = safe ? accessor ?? ((row) => getPath(row, def.id)) : () => void 0;
 	const format = def.format ?? ((value) => formatValue(value));
 	const compare = def.compare ?? compareValues;
 	const customFilter = def.filter;
 	const customParse = def.parse;
 	const editable = def.editable ?? false;
 	const customSetValue = def.setValue;
-	const canWrite = accessor === void 0 || customSetValue !== void 0;
+	const canWrite = safe && (accessor === void 0 || customSetValue !== void 0);
 	return Object.freeze({
 		id: def.id,
 		header: def.header ?? humanize(def.id),
@@ -241,6 +268,7 @@ function resolveColumn(definition) {
 			return parseAs(input, def.type ?? typeOf(getValue(row)) ?? typeOf(sample) ?? "text");
 		},
 		setValue(row, value) {
+			if (!safe) return;
 			if (customSetValue) return customSetValue(row, value);
 			return accessor === void 0 ? setPath(row, def.id, value) : void 0;
 		}
@@ -258,6 +286,10 @@ function resolveColumn(definition) {
 function quote(field, delimiter) {
 	return field.includes(delimiter) || field.includes("\"") || field.includes("\n") || field.includes("\r") ? `"${field.replaceAll("\"", "\"\"")}"` : field;
 }
+/** Escape formula-like display text; a finite number formatted as a number stays numeric. */
+function escapeFormula(text, value) {
+	return !(typeof value === "number" && Number.isFinite(value) && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/u.test(text)) && /^[=+\-@\t\r\n＝＋－＠]/u.test(text) ? "'" + text : text;
+}
 /** Write a matrix of text as delimited lines joined with `\n`. */
 function toDelimited(matrix, delimiter = "	") {
 	return matrix.map((line) => line.map((field) => quote(field, delimiter)).join(delimiter)).join("\n");
@@ -267,39 +299,92 @@ function toDelimited(matrix, delimiter = "	") {
 * and embedded line breaks, and ignores one trailing line break.
 */
 function parseDelimited(text, delimiter = "	") {
+	return readDelimited(text, {
+		maxRows: Infinity,
+		maxColumns: Infinity,
+		maxCells: Infinity,
+		maxLength: Infinity
+	}, delimiter).rows;
+}
+/** Read complete fields within a grid and work budget, without materializing discarded fields. */
+function readDelimited(text, limits, delimiter = "	") {
 	const rows = [];
+	if (limits.maxRows === 0 || limits.maxColumns === 0) return {
+		rows,
+		truncated: text.length > 0
+	};
 	let row = [];
 	let field = "";
 	let quoted = false;
+	let started = false;
 	let index = 0;
+	let column = 0;
+	let cells = 0;
+	let truncated = false;
+	const end = Math.min(text.length, limits.maxLength);
 	const endField = () => {
-		row.push(field);
+		if (column < limits.maxColumns) row.push(field);
+		else truncated = true;
+		column += 1;
+		cells += 1;
 		field = "";
+		started = false;
 	};
-	const endRow = () => {
-		endField();
-		rows.push(row);
-		row = [];
+	const append = (char) => {
+		if (column < limits.maxColumns) field += char;
 	};
-	while (index < text.length) {
+	while (index < end) {
 		const char = text.charAt(index);
 		if (quoted) {
 			if (char === "\"") {
-				if (text.charAt(index + 1) === "\"") {
-					field += "\"";
+				if (index + 1 < end && text.charAt(index + 1) === "\"") {
+					append("\"");
 					index += 1;
 				} else quoted = false;
-			} else field += char;
-		} else if (char === "\"" && field === "") quoted = true;
-		else if (char === delimiter) endField();
-		else if (char === "\n" || char === "\r") {
-			if (char === "\r" && text.charAt(index + 1) === "\n") index += 1;
-			endRow();
-		} else field += char;
+			} else append(char);
+		} else if (char === "\"" && !started) quoted = true;
+		else if (char === delimiter) {
+			endField();
+			index += 1;
+			if (cells >= limits.maxCells || rows.length + 1 >= limits.maxRows && column >= limits.maxColumns) {
+				rows.push(row);
+				return {
+					rows,
+					truncated: true
+				};
+			}
+			continue;
+		} else if (char === "\n" || char === "\r") {
+			if (char === "\r" && index + 1 < end && text.charAt(index + 1) === "\n") index += 1;
+			endField();
+			rows.push(row);
+			row = [];
+			column = 0;
+			index += 1;
+			if (cells >= limits.maxCells || rows.length >= limits.maxRows) return {
+				rows,
+				truncated: truncated || index < text.length
+			};
+			continue;
+		} else append(char);
+		started = true;
 		index += 1;
 	}
-	if (field !== "" || row.length > 0) endRow();
-	return rows;
+	if (end < text.length) {
+		if (row.length > 0) rows.push(row);
+		return {
+			rows,
+			truncated: true
+		};
+	}
+	if (started || column > 0) {
+		endField();
+		rows.push(row);
+	}
+	return {
+		rows,
+		truncated
+	};
 }
 
 //#endregion
@@ -466,6 +551,196 @@ function createUndoStack(limit = 100) {
 	};
 }
 
+//#endregion
+//#region src/virtualizer.ts
+const FALLBACK_SIZE = 40;
+/** Layout arithmetic for either axis. All viewport values and measurements come from the caller. */
+function createVirtualizer(initialOptions) {
+	let options = initialOptions;
+	let count = 0;
+	let overscan = 5;
+	let fixedSize;
+	let keys = [];
+	let byKey = /* @__PURE__ */ new Map();
+	let sizes = [];
+	let prefix = [0];
+	let offset = 0;
+	let viewportSize = 0;
+	let cached;
+	const measured = /* @__PURE__ */ new Map();
+	const problems = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	function recover(code, message) {
+		if (!problems.has(code)) {
+			const problem = issue(code, message);
+			problems.set(code, problem);
+			options.onIssue?.(problem);
+			cached = void 0;
+		}
+	}
+	function validSize(value) {
+		if (Number.isFinite(value) && value > 0) return value;
+		recover("invalid_virtual_size", `Item size ${String(value)} is not positive and finite; 40 is used.`);
+		return FALLBACK_SIZE;
+	}
+	function configure(next) {
+		options = next;
+		problems.clear();
+		count = Number.isSafeInteger(next.count) && next.count >= 0 ? next.count : 0;
+		if (count !== next.count) recover("invalid_virtual_option", "Virtual item count must be a non-negative safe integer; 0 is used.");
+		const requestedOverscan = next.overscan ?? 5;
+		overscan = Number.isSafeInteger(requestedOverscan) && requestedOverscan >= 0 ? requestedOverscan : 5;
+		if (overscan !== requestedOverscan) recover("invalid_virtual_option", "Overscan must be a non-negative safe integer; 5 is used.");
+		const estimate = typeof next.estimateSize === "number" ? validSize(next.estimateSize) : void 0;
+		const nextKeys = [];
+		const nextSizes = [];
+		const nextByKey = /* @__PURE__ */ new Map();
+		let firstChanged = count;
+		let uniform = estimate !== void 0;
+		for (let index = 0; index < count; index += 1) {
+			let key = next.getKey ? next.getKey(index) : index;
+			if (!(typeof key === "string" || typeof key === "number" && Number.isFinite(key))) {
+				recover("invalid_virtual_option", `Item ${index} has an invalid key; its index is used.`);
+				key = index;
+			}
+			if (nextByKey.has(key)) {
+				recover("duplicate_virtual_key", `Item ${index} repeats a key; a distinct fallback key is used.`);
+				key = JSON.stringify(["virtual", index]);
+				while (nextByKey.has(key)) key += ":";
+			}
+			const size = measured.get(key) ?? estimate ?? validSize(next.estimateSize(index));
+			uniform &&= size === estimate;
+			if (keys[index] !== key || sizes[index] !== size) firstChanged = Math.min(firstChanged, index);
+			nextKeys.push(key);
+			nextSizes.push(size);
+			nextByKey.set(key, index);
+		}
+		if (fixedSize !== void 0 || uniform) prefix = [0];
+		else prefix.length = Math.min(prefix.length, firstChanged + 1);
+		keys = nextKeys;
+		sizes = nextSizes;
+		byKey = nextByKey;
+		fixedSize = uniform ? estimate : void 0;
+		cached = void 0;
+	}
+	function startOf(index) {
+		if (fixedSize !== void 0) return index * fixedSize;
+		while (prefix.length <= index) {
+			const at = prefix.length - 1;
+			prefix.push(prefix[at] + sizes[at]);
+		}
+		return prefix[index];
+	}
+	function totalSize() {
+		return startOf(count);
+	}
+	function indexAt(position) {
+		if (fixedSize !== void 0) return Math.min(count - 1, Math.floor(position / fixedSize));
+		let low = 0;
+		let high = count - 1;
+		while (low < high) {
+			const middle = Math.floor((low + high) / 2);
+			if (startOf(middle + 1) <= position) low = middle + 1;
+			else high = middle;
+		}
+		return low;
+	}
+	function getWindow() {
+		if (cached) return cached;
+		const total = totalSize();
+		const clampedOffset = Math.min(offset, Math.max(0, total - viewportSize));
+		let first = 0;
+		let last = -1;
+		if (count > 0 && viewportSize > 0) {
+			first = Math.max(0, indexAt(clampedOffset) - overscan);
+			const edge = Math.min(total, clampedOffset + viewportSize);
+			let visibleEnd = indexAt(edge);
+			if (startOf(visibleEnd) >= edge) visibleEnd -= 1;
+			last = Math.min(count - 1, visibleEnd + overscan);
+		}
+		const items = [];
+		for (let index = first; index <= last; index += 1) items.push(Object.freeze({
+			index,
+			key: keys[index],
+			start: startOf(index),
+			size: sizes[index]
+		}));
+		const paddingStart = items.length > 0 ? startOf(first) : 0;
+		const paddingEnd = items.length > 0 ? Math.max(0, total - startOf(last + 1)) : total;
+		cached = Object.freeze({
+			items: Object.freeze(items),
+			totalSize: total,
+			paddingStart,
+			paddingEnd,
+			startIndex: first,
+			endIndex: last,
+			offset: clampedOffset,
+			viewportSize,
+			issues: Object.freeze([...problems.values()])
+		});
+		return cached;
+	}
+	function notify() {
+		cached = void 0;
+		if (listeners.size > 0) {
+			const view = getWindow();
+			for (const listener of listeners) listener(view);
+		}
+	}
+	configure(initialOptions);
+	return {
+		setOptions(next) {
+			configure(next);
+			notify();
+		},
+		setViewport(nextOffset, nextSize) {
+			const issueCount = problems.size;
+			const safeOffset = Number.isFinite(nextOffset) && nextOffset >= 0 ? nextOffset : 0;
+			const safeSize = Number.isFinite(nextSize) && nextSize >= 0 ? nextSize : 0;
+			if (safeOffset !== nextOffset || safeSize !== nextSize) recover("invalid_virtual_viewport", "Viewport offset and size must be non-negative and finite; invalid values use 0.");
+			if (offset === safeOffset && viewportSize === safeSize && problems.size === issueCount) return;
+			offset = safeOffset;
+			viewportSize = safeSize;
+			notify();
+		},
+		measure(key, size) {
+			const index = byKey.get(key);
+			if (index === void 0) return;
+			if (!Number.isFinite(size) || size <= 0) {
+				recover("invalid_virtual_size", "Measured size must be positive and finite; the previous size is retained.");
+				notify();
+				return;
+			}
+			measured.set(key, size);
+			if (sizes[index] === size) return;
+			if (fixedSize !== void 0) {
+				fixedSize = void 0;
+				prefix = [0];
+			} else prefix.length = Math.min(prefix.length, index + 1);
+			sizes[index] = size;
+			notify();
+		},
+		getWindow,
+		getOffsetForIndex(index, align = "auto") {
+			if (count === 0) return 0;
+			if (!Number.isFinite(index) || !Number.isInteger(index)) recover("invalid_virtual_option", "Scroll index must be a finite integer; it is clamped to a valid item.");
+			const target = Math.min(count - 1, Math.max(0, Number.isFinite(index) ? Math.trunc(index) : 0));
+			const start = startOf(target);
+			const end = start + sizes[target];
+			const current = getWindow().offset;
+			let result = start;
+			if (align === "center") result = start - (viewportSize - sizes[target]) / 2;
+			else if (align === "end") result = end - viewportSize;
+			else if (align === "auto") result = start < current ? start : end > current + viewportSize ? end - viewportSize : current;
+			return Math.min(Math.max(0, totalSize() - viewportSize), Math.max(0, result));
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+
 //#endregion
 //#region src/infer.ts
 function isPlainObject(value) {
@@ -593,10 +868,47 @@ function paginationItems(page, pageCount, siblings = 1) {
 	return items;
 }
 
+//#endregion
+//#region src/row.ts
+/** Disjoint namespaces and typed keys avoid collisions between 1, "1", and detail-like ids. */
+function getRowItemKey(key, kind = "row") {
+	return JSON.stringify([
+		kind,
+		typeof key,
+		key
+	]);
+}
+function createRow(original, key, index, columns, canExpand = false) {
+	const values = /* @__PURE__ */ new Map();
+	const displays = /* @__PURE__ */ new Map();
+	const getValue = (columnId) => {
+		if (values.has(columnId)) return values.get(columnId);
+		const value = columns.get(columnId)?.getValue(original);
+		values.set(columnId, value);
+		return value;
+	};
+	return Object.freeze({
+		key,
+		index,
+		original,
+		canExpand,
+		isExpanded: false,
+		getValue,
+		getDisplay(columnId) {
+			const cached = displays.get(columnId);
+			if (cached !== void 0) return cached;
+			const column = columns.get(columnId);
+			const display = column ? column.format(getValue(columnId), original) : "";
+			displays.set(columnId, display);
+			return display;
+		}
+	});
+}
+
 //#endregion
 //#region src/state.ts
 const DEFAULT_PAGE_SIZE = 10;
-function createInitialState(patch = {}) {
+function createInitialState(patch = {}, onIssue) {
 	return freezeState({
 		sorting: patch.sorting ?? [],
 		search: patch.search ?? "",
@@ -606,70 +918,46 @@ function createInitialState(patch = {}) {
 			pageSize: 10
 		},
 		selection: patch.selection ?? [],
+		expanded: normalizeExpanded(patch.expanded === void 0 ? [] : patch.expanded, onIssue),
 		hiddenColumns: patch.hiddenColumns ?? [],
 		columnOrder: patch.columnOrder ?? []
 	});
 }
-function mergeState(state, patch) {
+function mergeState(state, patch, onIssue) {
 	let changed = false;
 	const next = { ...state };
-	for (const [key, value] of Object.entries(patch)) {
+	for (const [key, input] of Object.entries(patch)) {
+		const value = key === "expanded" && input !== void 0 ? normalizeExpanded(input, onIssue) : input;
 		if (value === void 0 || Object.is(next[key], value)) continue;
 		if (key === "pagination" && samePagination(next[key], value)) continue;
+		if (key === "expanded" && sameExpanded(state.expanded, value)) continue;
 		next[key] = value;
 		changed = true;
 	}
-	return changed ? freezeState(next) : state;
+	return changed ? freezeState(next, state) : state;
+}
+function normalizeExpanded(value, onIssue) {
+	if (value === true) return true;
+	if (Array.isArray(value) && value.every((key) => typeof key === "string" || typeof key === "number" && Number.isFinite(key))) return [...new Set(value)];
+	onIssue?.(issue("invalid_expanded", "Expanded state must be true or an array of string/finite number keys; an empty array is used."));
+	return [];
+}
+function sameExpanded(left, right) {
+	return left === right || left !== true && right !== true && left.length === right.length && left.every((key, index) => key === right[index]);
 }
 function samePagination(left, right) {
 	return left.page === right.page && left.pageSize === right.pageSize;
 }
-function freezeState(state) {
+function freezeState(state, previous) {
 	return Object.freeze({
-		sorting: Object.freeze(state.sorting.map((rule) => Object.freeze({ ...rule }))),
+		sorting: state.sorting === previous?.sorting ? previous.sorting : Object.freeze(state.sorting.map((rule) => Object.freeze({ ...rule }))),
 		search: state.search,
-		filters: Object.freeze({ ...state.filters }),
-		pagination: Object.freeze({ ...state.pagination }),
-		selection: Object.freeze([...state.selection]),
-		hiddenColumns: Object.freeze([...state.hiddenColumns]),
-		columnOrder: Object.freeze([...state.columnOrder])
-	});
-}
-
-//#endregion
-//#region src/issues.ts
-function issue(code, message, details = {}) {
-	return Object.freeze({
-		code,
-		message,
-		...details
-	});
-}
-
-//#endregion
-//#region src/row.ts
-function createRow(original, key, index, columns) {
-	const values = /* @__PURE__ */ new Map();
-	const displays = /* @__PURE__ */ new Map();
-	const getValue = (columnId) => {
-		if (values.has(columnId)) return values.get(columnId);
-		const value = columns.get(columnId)?.getValue(original);
-		values.set(columnId, value);
-		return value;
-	};
-	return Object.freeze({
-		key,
-		index,
-		original,
-		getValue,
-		getDisplay(columnId) {
-			const cached = displays.get(columnId);
-			if (cached !== void 0) return cached;
-			const column = columns.get(columnId);
-			const display = column ? column.format(getValue(columnId), original) : "";
-			displays.set(columnId, display);
-			return display;
-		}
+		filters: state.filters === previous?.filters ? previous.filters : Object.freeze({ ...state.filters }),
+		pagination: state.pagination === previous?.pagination ? previous.pagination : Object.freeze({ ...state.pagination }),
+		selection: state.selection === previous?.selection ? previous.selection : Object.freeze([...state.selection]),
+		expanded: state.expanded === previous?.expanded ? previous.expanded : state.expanded === true ? true : Object.freeze([...state.expanded]),
+		hiddenColumns: state.hiddenColumns === previous?.hiddenColumns ? previous.hiddenColumns : Object.freeze([...state.hiddenColumns]),
+		columnOrder: state.columnOrder === previous?.columnOrder ? previous.columnOrder : Object.freeze([...state.columnOrder])
 	});
 }
 
@@ -697,19 +985,33 @@ function coverage(selected, total) {
 	if (selected === 0 || total === 0) return "none";
 	return selected === total ? "all" : "some";
 }
+function pasteLimit(value, fallback, name, issues) {
+	if (value === void 0) return fallback;
+	if (Number.isSafeInteger(value) && value > 0) return value;
+	issues.push(issue("invalid_paste_limit", `Paste ${name} ${String(value)} is not a positive safe integer; ${fallback} is used.`));
+	return fallback;
+}
 /** Create a data table. */
 function createTable(options) {
+	const paginate = options.paginate ?? true;
+	const expandMode = options.expandMode ?? "multiple";
 	const selectionMode = options.selectionMode ?? "multiple";
 	const selectScope = options.selectScope ?? "all";
 	const manual = options.manual ?? false;
 	const undoStack = createUndoStack(options.historyLimit);
 	const listeners = /* @__PURE__ */ new Set();
+	const optionIssues = [];
+	const maxPasteCells = pasteLimit(options.pasteLimit?.maxCells, 1e5, "maxCells", optionIssues);
+	const maxPasteLength = pasteLimit(options.pasteLimit?.maxLength, 5e6, "maxLength", optionIssues);
 	let data = options.data;
 	let definitions = options.columns;
 	let rowCount = options.rowCount;
-	const initialState = createInitialState({
+	let expandedIssue;
+	let initialState = createInitialState({
 		...options.initialState,
 		hiddenColumns: options.initialState?.hiddenColumns ?? options.columns.filter((column) => column.hidden === true).map((column) => column.id)
+	}, (problem) => {
+		expandedIssue = problem;
 	});
 	let state = initialState;
 	let snapshot;
@@ -721,10 +1023,18 @@ function createTable(options) {
 		return rowKey === void 0 || !isRecord(row) ? index : String(value);
 	};
 	const resolveColumns = memo((defs) => {
-		const columns = defs.map((definition) => resolveColumn(definition));
+		const issues = [];
+		const columns = defs.flatMap((definition) => {
+			if (!isSafePath(definition.id)) {
+				issues.push(issue("unsafe_path", `The column "${definition.id}" addresses a prototype and is ignored.`, { column: definition.id }));
+				return [];
+			}
+			return [resolveColumn(definition)];
+		});
 		return {
 			columns,
-			byId: new Map(columns.map((column) => [column.id, column]))
+			byId: new Map(columns.map((column) => [column.id, column])),
+			issues
 		};
 	});
 	const indexRows = memo((rows, byId) => {
@@ -737,7 +1047,7 @@ function createTable(options) {
 					issues.push(issue("duplicate_row_key", `Row ${index} repeats the key "${String(key)}"; it is keyed "${String(key)}#${index}" instead.`, { rowKey: key }));
 					key = `${String(key)}#${index}`;
 				}
-				const row = createRow(original, key, index, byId);
+				const row = createRow(original, key, index, byId, options.getRowCanExpand?.(original) ?? false);
 				byKey.set(key, row);
 				return row;
 			}),
@@ -762,8 +1072,21 @@ function createTable(options) {
 	const filterStage = memo(filterRows);
 	const sortStage = memo(sortRows);
 	const selectedSet = memo((selection) => new Set(selection));
+	const expansionStage = memo((indexed, expanded) => {
+		const keys = expanded === true ? void 0 : new Set(expanded);
+		const rows = indexed.rows.map((row) => row.canExpand && (expanded === true || keys?.has(row.key)) ? Object.freeze({
+			...row,
+			isExpanded: true
+		}) : row);
+		return {
+			rows,
+			byKey: new Map(rows.map((row) => [row.key, row]))
+		};
+	});
+	const expandedOrder = memo((rows, byKey) => rows.map((row) => byKey.get(row.key)));
 	function stateIssues(byId) {
 		const issues = [];
+		if (expandedIssue) issues.push(expandedIssue);
 		const referenced = /* @__PURE__ */ new Set([
 			...state.sorting.map((rule) => rule.column),
 			...Object.keys(state.filters),
@@ -772,30 +1095,36 @@ function createTable(options) {
 		]);
 		for (const id of referenced) if (!byId.has(id)) issues.push(issue("unknown_column", `The state refers to a column "${id}" that is not defined.`, { column: id }));
 		const { pageSize } = state.pagination;
-		if (!Number.isInteger(pageSize) || pageSize < 1) issues.push(issue("invalid_page_size", `Page size ${String(pageSize)} is not a positive whole number; ${10} is used.`));
+		if (paginate && (!Number.isInteger(pageSize) || pageSize < 1)) issues.push(issue("invalid_page_size", `Page size ${String(pageSize)} is not a positive whole number; ${10} is used.`));
 		return issues;
 	}
 	function computeSnapshot() {
-		const { columns, byId } = resolveColumns(definitions);
+		const { columns, byId, issues: columnIssues } = resolveColumns(definitions);
 		const indexed = indexRows(data, byId);
+		const expanded = expansionStage(indexed, state.expanded);
 		const ordered = orderColumns(columns, state.columnOrder, state.hiddenColumns);
-		const issues = [...indexed.issues, ...stateIssues(byId)];
+		const issues = [
+			...optionIssues,
+			...columnIssues,
+			...indexed.issues,
+			...stateIssues(byId)
+		];
 		const requestedSize = state.pagination.pageSize;
-		const pageSize = Number.isInteger(requestedSize) && requestedSize >= 1 ? requestedSize : 10;
+		let pageSize = Number.isInteger(requestedSize) && requestedSize >= 1 ? requestedSize : 10;
 		let processedRows;
 		let rows;
 		let filteredCount;
 		let page;
 		let pageCount;
 		if (manual) {
-			processedRows = indexed.rows;
-			rows = indexed.rows;
+			processedRows = expanded.rows;
+			rows = expanded.rows;
 			filteredCount = rowCount ?? indexed.rows.length;
 			pageCount = countPages(filteredCount, pageSize);
 			page = clampPage(state.pagination.page, pageCount);
 		} else {
 			const filtered = filterStage(indexed.rows, columns, state.search, state.filters);
-			processedRows = sortStage(filtered, columns, state.sorting);
+			processedRows = expandedOrder(sortStage(filtered, columns, state.sorting), expanded.byKey);
 			filteredCount = processedRows.length;
 			pageCount = countPages(filteredCount, pageSize);
 			page = clampPage(state.pagination.page, pageCount);
@@ -804,6 +1133,12 @@ function createTable(options) {
 				pageSize
 			});
 		}
+		if (!paginate) {
+			rows = processedRows;
+			page = 1;
+			pageCount = 1;
+			pageSize = Math.max(1, rows.length);
+		}
 		const selected = selectedSet(state.selection);
 		const pageSelected = rows.filter((row) => selected.has(row.key)).length;
 		const scopeRows = selectScope === "page" || manual ? rows : processedRows;
@@ -818,6 +1153,21 @@ function createTable(options) {
 			columns: ordered.visible,
 			allColumns: ordered.all,
 			rows,
+			renderItems: Object.freeze(rows.flatMap((row, rowIndex) => {
+				const item = Object.freeze({
+					kind: "row",
+					key: getRowItemKey(row.key),
+					row,
+					rowIndex
+				});
+				return row.isExpanded ? [item, Object.freeze({
+					kind: "detail",
+					key: getRowItemKey(row.key, "detail"),
+					row,
+					rowIndex
+				})] : [item];
+			})),
+			paginate,
 			processedRows,
 			page,
 			pageSize,
@@ -839,7 +1189,7 @@ function createTable(options) {
 			isSelected: (key) => selected.has(key),
 			getSort: (columnId) => sortIndex.get(columnId),
 			getColumn: (columnId) => byId.get(columnId),
-			getRow: (key) => indexed.byKey.get(key)
+			getRow: (key) => expanded.byKey.get(key)
 		});
 	}
 	function getSnapshot() {
@@ -855,12 +1205,31 @@ function createTable(options) {
 	/** Apply a change made by a table operation. */
 	function commit(patch) {
 		const previous = state;
-		const next = mergeState(state, patch);
-		if (next === previous) return;
+		const previousIssue = expandedIssue;
+		const next = mergePatch(patch);
+		if (next === previous && previousIssue === expandedIssue) return;
 		state = next;
-		options.onStateChange?.(state, previous);
+		if (next !== previous) options.onStateChange?.(state, previous);
 		notify();
 	}
+	function canonicalExpanded(expanded, candidate = state) {
+		if (expandMode === "multiple") return expanded;
+		if (expanded !== true) return expanded.slice(-1);
+		const { columns, byId } = resolveColumns(definitions);
+		const indexed = indexRows(data, byId);
+		const first = (manual ? indexed.rows : sortStage(filterStage(indexed.rows, columns, candidate.search, candidate.filters), columns, candidate.sorting)).find((row) => row.canExpand);
+		return first ? [first.key] : [];
+	}
+	function mergePatch(patch) {
+		if (patch.expanded !== void 0) expandedIssue = void 0;
+		const next = mergeState(state, patch, (problem) => {
+			expandedIssue = problem;
+		});
+		return expandMode === "single" && patch.expanded !== void 0 ? mergeState(state, {
+			...patch,
+			expanded: canonicalExpanded(next.expanded, next)
+		}) : next;
+	}
 	const firstPage = () => ({
 		page: 1,
 		pageSize: state.pagination.pageSize
@@ -890,10 +1259,10 @@ function createTable(options) {
 		if (selection.length === current.length && selection.every((key, i) => key === current[i])) return;
 		commit({ selection });
 	}
-	function applyChanges(edits, record) {
+	function applyChanges(edits, record, recoveredIssues = []) {
 		const current = getSnapshot();
 		const working = [...data];
-		const issues = [];
+		const issues = [...recoveredIssues];
 		const changes = [];
 		const samples = /* @__PURE__ */ new Map();
 		const sampleOf = (columnId) => {
@@ -916,6 +1285,13 @@ function createTable(options) {
 				}));
 				continue;
 			}
+			if (!isSafePath(edit.column)) {
+				issues.push(issue("unsafe_path", `The path "${edit.column}" addresses a prototype and cannot be written.`, {
+					rowKey: edit.rowKey,
+					column: edit.column
+				}));
+				continue;
+			}
 			if (!column) {
 				issues.push(issue("unknown_column", `No column has the id "${edit.column}".`, {
 					rowKey: edit.rowKey,
@@ -1002,6 +1378,11 @@ function createTable(options) {
 			value: direction === "undo" ? change.previous : change.value
 		})), false);
 	}
+	if (expandMode === "single") {
+		initialState = mergeState(initialState, { expanded: canonicalExpanded(initialState.expanded) });
+		state = initialState;
+		snapshot = void 0;
+	}
 	const table = {
 		getSnapshot,
 		getState: () => state,
@@ -1012,8 +1393,9 @@ function createTable(options) {
 			};
 		},
 		setState(patch) {
-			const next = mergeState(state, patch);
-			if (next !== state) {
+			const previousIssue = expandedIssue;
+			const next = mergePatch(patch);
+			if (next !== state || previousIssue !== expandedIssue) {
 				state = next;
 				notify();
 			}
@@ -1069,6 +1451,7 @@ function createTable(options) {
 			});
 		},
 		goToPage(page) {
+			if (!paginate) return;
 			const { pageCount, page: currentPage } = getSnapshot();
 			const next = clampPage(page, pageCount);
 			if (next !== currentPage || next !== state.pagination.page) commit({ pagination: {
@@ -1083,6 +1466,7 @@ function createTable(options) {
 			table.goToPage(getSnapshot().page - 1);
 		},
 		setPageSize(pageSize) {
+			if (!paginate) return;
 			if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize === state.pagination.pageSize) return;
 			const { pageStart } = getSnapshot();
 			commit({ pagination: {
@@ -1121,6 +1505,23 @@ function createTable(options) {
 				return row ? [row] : [];
 			});
 		},
+		toggleExpanded(key, expanded) {
+			const row = getSnapshot().getRow(key);
+			if (!row?.canExpand) return;
+			const open = expanded ?? !row.isExpanded;
+			if (open === row.isExpanded) return;
+			if (expandMode === "single") commit({ expanded: open ? [key] : [] });
+			else if (state.expanded === true) {
+				const { byId } = resolveColumns(definitions);
+				commit({ expanded: indexRows(data, byId).rows.filter((candidate) => candidate.canExpand && candidate.key !== key).map((candidate) => candidate.key) });
+			} else commit({ expanded: open ? [...state.expanded, key] : state.expanded.filter((candidate) => candidate !== key) });
+		},
+		expandAll() {
+			commit({ expanded: true });
+		},
+		collapseAll() {
+			commit({ expanded: [] });
+		},
 		toggleColumn(columnId, visible) {
 			if (!getSnapshot().getColumn(columnId)) return;
 			const hidden = state.hiddenColumns.includes(columnId);
@@ -1153,7 +1554,7 @@ function createTable(options) {
 			replay(changes, "redo");
 			return true;
 		},
-		copy(range) {
+		copy(range, { escapeFormulas = false } = {}) {
 			const { rows, columns } = getSnapshot();
 			const matrix = [];
 			rows.forEach((row, rowIndex) => {
@@ -1162,14 +1563,26 @@ function createTable(options) {
 					if (rangeContains(range, {
 						row: rowIndex,
 						column: columnIndex
-					})) line.push(row.getDisplay(column.id));
+					})) {
+						const display = row.getDisplay(column.id);
+						line.push(escapeFormulas ? escapeFormula(display, row.getValue(column.id)) : display);
+					}
 				});
 				if (line.length > 0) matrix.push(line);
 			});
 			return toDelimited(matrix);
 		},
 		paste(origin, text) {
-			return applyChanges(rangeEdits(origin, parseDelimited(text)), true);
+			if (!Number.isInteger(origin.row) || !Number.isInteger(origin.column) || origin.row < 0 || origin.column < 0) return applyChanges([], true, [issue("invalid_value", "The paste origin must use non-negative whole row and column indices.")]);
+			const { rows, columns } = getSnapshot();
+			const parsed = readDelimited(text, {
+				maxRows: Math.max(0, rows.length - origin.row),
+				maxColumns: Math.max(0, columns.length - origin.column),
+				maxCells: maxPasteCells,
+				maxLength: maxPasteLength
+			});
+			const issues = parsed.truncated ? [issue("paste_truncated", "The paste exceeds the visible grid or parsing limits; only complete cells within those limits are applied.")] : [];
+			return applyChanges(rangeEdits(origin, parsed.rows), true, issues);
 		},
 		clear(range) {
 			const matrix = Array.from({ length: range.bottom - range.top + 1 }, () => Array.from({ length: range.right - range.left + 1 }, () => ""));
@@ -1182,14 +1595,17 @@ function createTable(options) {
 				return row !== void 0 && current.getColumn(edit.column)?.isEditable(row.original) === true;
 			}), true);
 		},
-		exportRows({ format = "csv", columns: ids, pageOnly = false, headers = true } = {}) {
+		exportRows({ format = "csv", columns: ids, pageOnly = false, headers = true, escapeFormulas = true } = {}) {
 			const current = getSnapshot();
 			const columns = ids ? ids.flatMap((id) => {
 				const column = current.getColumn(id);
 				return column ? [column] : [];
 			}) : current.columns;
-			const matrix = (pageOnly ? current.rows : current.processedRows).map((row) => columns.map((column) => row.getDisplay(column.id)));
-			if (headers) matrix.unshift(columns.map((column) => column.header));
+			const matrix = (pageOnly ? current.rows : current.processedRows).map((row) => columns.map((column) => {
+				const display = row.getDisplay(column.id);
+				return escapeFormulas ? escapeFormula(display, row.getValue(column.id)) : display;
+			}));
+			if (headers) matrix.unshift(columns.map((column) => escapeFormulas ? escapeFormula(column.header) : column.header));
 			return toDelimited(matrix, format === "csv" ? "," : "	");
 		},
 		reset() {
@@ -1203,5 +1619,5 @@ function createTable(options) {
 }
 
 //#endregion
-export { DEFAULT_PAGE_SIZE, clampPage, clampPosition, columnLabel, compareValues, countPages, createTable, createUndoStack, defineColumns, filterRows, formatValue, fromA1, getPath, gridCommand, humanize, inferColumns, matchesFilter, moveSelection, paginateRows, paginationItems, parseAs, parseDelimited, rangeContains, resolveColumn, selectCell, selectionRange, setPath, sortRows, toA1, toDelimited, typeOf };
+export { DEFAULT_PAGE_SIZE, clampPage, clampPosition, columnLabel, compareValues, countPages, createTable, createUndoStack, createVirtualizer, defineColumns, filterRows, formatValue, fromA1, getPath, getRowItemKey, gridCommand, humanize, inferColumns, matchesFilter, moveSelection, paginateRows, paginationItems, parseAs, parseDelimited, rangeContains, resolveColumn, selectCell, selectionRange, setPath, sortRows, toA1, toDelimited, typeOf };
 //# sourceMappingURL=index.js.map