@atscript/ui-table 0.1.132 → 0.1.134

package/dist/index.cjs

@@ -149,13 +149,22 @@ function unescapeRegex(input) {
 //#region src/filters/filter-input-format.ts
 /**
 * Coerce a raw string value to the appropriate JS type for the column.
-* Number columns get numeric values; everything else stays as string.
+* Number columns get numeric values, boolean columns understand the
+* `true` / `false` vocabulary (case-insensitive) so the condition carries a
+* real boolean and round-trips through the URL as one. Anything else stays
+* a string. Since 0.1.133 for booleans.
 */
 function coerceValue(raw, columnType) {
 	if (columnType === "number") {
 		const n = Number(raw);
 		return Number.isNaN(n) ? raw : n;
 	}
+	if (columnType === "boolean") {
+		const lower = raw.toLowerCase();
+		if (lower === "true") return true;
+		if (lower === "false") return false;
+		return raw;
+	}
 	return raw;
 }
 /** Default condition type when no symbol matches the input. */
@@ -580,6 +589,10 @@ function derivePresetAspects(content) {
 * Convert in-memory dict-form snapshot to the wire form persisted on the
 * server. Entries-arrays are sorted by `field` so consumers (server-side
 * aspect derivation, dirty detection, equality checks) see a stable order.
+*
+* Empty aspects round-trip as empty (since 0.1.133): a saved view with no
+* filters owns `filterOps` and clears them on apply, which is not the same
+* thing as a view that never claimed the aspect.
 */
 function toWireSnapshot(snapshot) {
 	const wire = {};
@@ -592,7 +605,7 @@ function toWireSnapshot(snapshot) {
 				field,
 				width: columnWidths[field]
 			});
-			if (entries.length > 0) columns.columnWidths = entries;
+			columns.columnWidths = entries;
 		}
 		wire.columns = columns;
 	}
@@ -603,7 +616,7 @@ function toWireSnapshot(snapshot) {
 			field,
 			conditions: snapshot.filterOps[field]
 		});
-		if (entries.length > 0) wire.filterOps = entries;
+		wire.filterOps = entries;
 	}
 	if (snapshot.sorters) wire.sorters = snapshot.sorters;
 	if (snapshot.itemsPerPage !== void 0) wire.itemsPerPage = snapshot.itemsPerPage;
@@ -614,7 +627,7 @@ function fromWireSnapshot(wire) {
 	if (wire.columns) {
 		const { columnNames, columnWidths } = wire.columns;
 		const columns = { columnNames };
-		if (columnWidths && columnWidths.length > 0) {
+		if (columnWidths) {
 			const dict = {};
 			for (const entry of columnWidths) dict[entry.field] = entry.width;
 			columns.columnWidths = dict;
@@ -622,7 +635,7 @@ function fromWireSnapshot(wire) {
 		snapshot.columns = columns;
 	}
 	if (wire.filters) snapshot.filters = wire.filters;
-	if (wire.filterOps && wire.filterOps.length > 0) {
+	if (wire.filterOps) {
 		const dict = {};
 		for (const entry of wire.filterOps) dict[entry.field] = entry.conditions;
 		snapshot.filterOps = dict;
@@ -819,7 +832,7 @@ function draftMatchesPreset(draft, presetSnapshot, availableAspects) {
 /**
 * Framework-agnostic wrapper over `@atscript/db-client`'s `Client` for the
 * `AsPresetEntry` table. Handles wire serialisation, list-splitting by
-* `type`, capabilities side-channel, and 401/403 → `denied` semantics.
+* `type`, capabilities side-channel, and 401/403/404 → `denied` semantics.
 *
 * Stateless: every method is a fresh request. The Vue composable layer
 * holds reactive state; this class only translates intent → HTTP.
@@ -845,8 +858,8 @@ var PresetsClient = class {
 	* `(app, tableKey)`. By default also fetches `capabilities` in parallel —
 	* pass `{ capabilities: false }` for refresh-after-mutation calls (fav
 	* toggle, default change, save/save-as, public toggle, rename, delete)
-	* where role-derived capabilities can't have changed. Auth errors
-	* (401/403) collapse to `denied: true` with empty data so the UI hides
+	* where role-derived capabilities can't have changed. Unavailable
+	* responses (401/403/404) collapse to `denied: true` with empty data so the UI hides
 	* itself silently.
 	*/
 	async list(opts = {}) {
@@ -858,7 +871,7 @@ var PresetsClient = class {
 		};
 		try {
 			const [rows, capabilities] = await Promise.all([this.client.query({ filter }), fetchCapabilities ? this.loadCapabilities().catch((err) => {
-				if (isAuthError(err)) throw err;
+				if (isUnavailableError(err)) throw err;
 				return null;
 			}) : Promise.resolve(void 0)]);
 			const presets = [];
@@ -872,7 +885,7 @@ var PresetsClient = class {
 				denied: false
 			};
 		} catch (err) {
-			if (isAuthError(err)) return {
+			if (isUnavailableError(err)) return {
 				presets: [],
 				userConf: null,
 				capabilities: null,
@@ -988,12 +1001,22 @@ var PresetsHttpError = class extends Error {
 		this.name = "PresetsHttpError";
 	}
 };
-/** True for HTTP 401/403 across both `ClientError` and `PresetsHttpError`. */
-function isAuthError(err) {
-	if (err instanceof _atscript_db_client.ClientError && (err.status === 401 || err.status === 403)) return true;
-	if (err instanceof PresetsHttpError && (err.status === 401 || err.status === 403)) return true;
-	return false;
+/**
+* True when the presets/app-prefs surface is simply not available to this
+* client: HTTP 401/403 (not signed in / not permitted) or 404 (the
+* controller is not mounted on this server). All three collapse to
+* `denied: true` — the UI hides itself silently instead of surfacing an
+* error. Covers both `ClientError` and `PresetsHttpError`.
+*/
+function isUnavailableError(err) {
+	const status = err instanceof _atscript_db_client.ClientError || err instanceof PresetsHttpError ? err.status : void 0;
+	return status === 401 || status === 403 || status === 404;
 }
+/**
+* @deprecated Renamed to `isUnavailableError` in 0.1.133 — it also covers
+* 404 (feature not mounted), not just auth failures.
+*/
+const isAuthError = isUnavailableError;
 //#endregion
 //#region src/presets/app-prefs-client.ts
 /**
@@ -1026,7 +1049,7 @@ var AppPrefsClient = class {
 				denied: false
 			};
 		} catch (err) {
-			if (isAuthError(err)) return {
+			if (isUnavailableError(err)) return {
 				row: null,
 				prefs: null,
 				denied: true
@@ -1232,6 +1255,36 @@ function stateToUrlQueryString(state, defaults) {
 	return (0, _uniqu_url_builder.buildUrl)(query);
 }
 /**
+* The `$`-controls {@link urlQueryStringToState} actually reads. Any other
+* `$key` is ignored by the parser, so it is NOT the table's to remove.
+*/
+const CONSUMED_CONTROLS = new Set([
+	"$sort",
+	"$search",
+	"$relevance",
+	"$skip"
+]);
+/** Characters that can only appear in a uniqu filter key, never in a page flag. */
+const FILTER_OPERATOR_CHAR = /[<>!~]/;
+/**
+* Whether {@link urlQueryStringToState} would consume the query key `key` —
+* i.e. whether the key belongs to the table rather than to the page hosting
+* it. This is the ownership rule the `useTableUrlQuery` router bridge reads
+* and writes by, so both directions agree: a key the parser ignores is never
+* removed, and a key it reads is the table's to remove.
+*
+* Shape-only, and deliberately conservative for bare `field=value` keys: a
+* filter on a column and a host flag are indistinguishable without the table
+* definition, so those are owned only once the bridge has written them
+* itself (or once a `prefix` namespaces them).
+*
+* @since 0.1.133
+*/
+function urlQueryConsumesKey(key) {
+	if (key.startsWith("$")) return CONSUMED_CONTROLS.has(key);
+	return FILTER_OPERATOR_CHAR.test(key);
+}
+/**
 * Parse a URL query string back into the table state subset.
 *
 * Robust by design — schema drift and copy-paste errors must not break the
@@ -1628,10 +1681,230 @@ function reorderColumnNames(names, fromPath, toPath, position) {
 	return without.slice(0, insertAt).concat(fromPath, without.slice(insertAt));
 }
 //#endregion
+//#region src/export/csv.ts
+const FORMULA_LEADERS = new Set([
+	"=",
+	"+",
+	"-",
+	"@",
+	"	",
+	"\r"
+]);
+/** RFC 4180 row separator. */
+const CRLF = "\r\n";
+/**
+* Render one value as an RFC 4180 field: formula-escaped (unless opted out),
+* then quoted when it contains the delimiter, a quote, CR or LF — with inner
+* quotes doubled.
+*/
+function csvCell(value, opts = {}) {
+	const delimiter = opts.delimiter ?? ",";
+	let text = value === null || value === void 0 ? "" : String(value);
+	if (typeof value === "string" && opts.escapeFormulas !== false && text.length > 0 && FORMULA_LEADERS.has(text[0])) text = `'${text}`;
+	return text.includes(delimiter) || text.includes("\"") || text.includes("\n") || text.includes("\r") ? `"${text.replaceAll("\"", "\"\"")}"` : text;
+}
+/**
+* Serialise a header row + data rows to an RFC 4180 CSV string (`\r\n` row
+* separators, quoted fields where required, optional UTF-8 BOM).
+*
+* Pure — no DOM, no framework. See {@link csvCell} for the per-field rules.
+*/
+function toCsv(header, rows, opts = {}) {
+	const delimiter = opts.delimiter ?? ",";
+	const lines = [header.map((h) => csvCell(h, opts)).join(delimiter)];
+	for (const row of rows) lines.push(row.map((v) => csvCell(v, opts)).join(delimiter));
+	const body = lines.join(CRLF) + CRLF;
+	return opts.bom ? `${body}` : body;
+}
+//#endregion
+//#region src/export/export-paging.ts
+/** Default page size used by the export pager when the caller gives none. */
+const DEFAULT_EXPORT_PAGE_SIZE = 500;
+/** Rejection raised when an export is cancelled through its `AbortSignal`. */
+var ExportAbortError = class extends Error {
+	/** Matches the DOM convention so `err.name === "AbortError"` checks work. */
+	name = "AbortError";
+	constructor(message = "Export aborted") {
+		super(message);
+	}
+};
+/**
+* Append the primary key(s) to a query's `$sort` as a tiebreaker so paging is
+* stable: two rows equal on every user sorter keep a deterministic relative
+* order, and no row is skipped or duplicated across page boundaries.
+*
+* Existing sort fields are preserved in order and never replaced — a pk the
+* user already sorts by is left where it is. Returns the input query when
+* there is nothing to add.
+*/
+function withStableOrder(query, primaryKeys) {
+	if (primaryKeys.length === 0) return query;
+	const current = query.controls?.$sort ?? {};
+	const missing = primaryKeys.filter((pk) => !(pk in current));
+	if (missing.length === 0) return query;
+	const $sort = { ...current };
+	for (const pk of missing) $sort[pk] = 1;
+	return {
+		...query,
+		controls: {
+			...query.controls,
+			$sort
+		}
+	};
+}
+/**
+* Page through `query` until the endpoint runs out of rows, collecting every
+* row into one array.
+*
+* Stops when a page comes back short (fewer rows than `pageSize`), when the
+* reported `count` is reached, or when `maxRows` is hit. Checks `signal`
+* before and after every request so a cancel lands between pages rather than
+* mid-flight.
+*/
+async function collectExportRows(opts) {
+	const pageSize = opts.pageSize && opts.pageSize > 0 ? opts.pageSize : 500;
+	const mapRow = opts.mapRow ?? ((row) => row);
+	const rows = [];
+	let total;
+	let page = 1;
+	for (;;) {
+		throwIfAborted(opts.signal);
+		const result = await opts.fetchPage(opts.query, page, pageSize);
+		throwIfAborted(opts.signal);
+		if (page === 1 && typeof result.count === "number") total = result.count;
+		const data = result.data ?? [];
+		const take = opts.maxRows === void 0 ? data.length : Math.min(data.length, opts.maxRows - rows.length);
+		for (let i = 0; i < take; i++) rows.push(mapRow(data[i]));
+		opts.onProgress?.(rows.length, total);
+		if (data.length < pageSize || opts.maxRows !== void 0 && rows.length >= opts.maxRows || total !== void 0 && rows.length >= total) break;
+		page++;
+	}
+	return {
+		rows,
+		total
+	};
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw new ExportAbortError();
+}
+//#endregion
+//#region src/export/export-value.ts
+/**
+* Turn a raw cell value into the scalar an export carries, using the same
+* column metadata the cell renderers read:
+*
+* - `null` / `undefined` → `null` (an empty CSV field).
+* - union / enum columns (`column.options`) → the option's **label**, so the
+*   file reads like the screen; an unknown key falls back to the raw value.
+* - `Date` → ISO 8601 (spreadsheet- and re-import-friendly, unlike a
+*   locale-formatted date).
+* - arrays → comma-joined scalars; other objects → JSON.
+* - numbers / booleans pass through untouched so a spreadsheet keeps them
+*   numeric.
+*
+* Callers override per column (`formatters`) or globally (`formatCell`) when
+* they want different text.
+*/
+function resolveExportValue(value, column) {
+	if (value === null || value === void 0) return null;
+	const options = column?.options;
+	if (options?.length) {
+		const key = typeof value === "string" || typeof value === "number" ? String(value) : void 0;
+		if (key !== void 0) {
+			const hit = options.find((o) => o.key === key);
+			if (hit) return hit.label;
+		}
+	}
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	if (typeof value === "string") return value;
+	if (value instanceof Date) return value.toISOString();
+	if (Array.isArray(value)) return value.map((v) => scalarText(v)).join(", ");
+	return scalarText(value);
+}
+function scalarText(value) {
+	if (value === null || value === void 0 || typeof value === "function") return "";
+	try {
+		return (0, _atscript_ui.str)(value);
+	} catch {
+		return "";
+	}
+}
+//#endregion
+//#region src/columns/display-columns.ts
+/** Columns with no explicit `order` land after every server column. */
+const TRAILING_ORDER = Number.MAX_SAFE_INTEGER;
+/** Turn a {@link DisplayColumnDef} into the `ColumnDef` the table renders. */
+function displayColumnToDef(def) {
+	return {
+		path: def.key,
+		label: def.label,
+		type: def.type ?? "text",
+		component: def.component,
+		sortable: def.sortable === "local",
+		filterable: false,
+		nullable: true,
+		order: def.order ?? TRAILING_ORDER,
+		width: def.width,
+		local: true
+	};
+}
+/**
+* Merge client-owned columns into the server's column list, ordered by each
+* column's `order`. `Array#sort` is stable, so server columns that share an
+* `order` keep their `/meta` sequence. Returns `base` untouched when there is
+* nothing to merge.
+*/
+function mergeDisplayColumns(base, display) {
+	if (display.length === 0) return base;
+	return [...base, ...display.map(displayColumnToDef)].toSorted((a, b) => a.order - b.order);
+}
+//#endregion
+//#region src/utils/sort-rows.ts
+/**
+* Coerce a primitive cell value to the text used for comparing and matching
+* cells — the string compare in {@link sortRowsLocally} and the substring
+* search of an in-memory table. Objects and functions collapse to `""` so
+* `'[object Object]'` never drives an ordering or matches a search.
+*/
+function cellAsString(v) {
+	if (v == null) return "";
+	if (typeof v === "string") return v;
+	if (typeof v === "number" || typeof v === "boolean") return v.toString();
+	return "";
+}
+/**
+* Sort rows in memory by `sorters`, numerically when both sides are numbers
+* and locale-aware otherwise. Returns a NEW array; the input is untouched. A
+* no-op (returns the input reference) when there is nothing to sort.
+*
+* `getValue` reads a sorter's field off a row — pass a dot-path reader for
+* nested fields; the default is a flat property read.
+*/
+function sortRowsLocally(rows, sorters, getValue = (row, field) => row[field]) {
+	if (sorters.length === 0 || rows.length < 2) return rows;
+	return rows.toSorted((a, b) => {
+		for (const s of sorters) {
+			const dir = s.direction === "desc" ? -1 : 1;
+			const av = getValue(a, s.field);
+			const bv = getValue(b, s.field);
+			if (typeof av === "number" && typeof bv === "number") {
+				if (av < bv) return -dir;
+				if (av > bv) return dir;
+			} else {
+				const cmp = cellAsString(av).localeCompare(cellAsString(bv));
+				if (cmp !== 0) return cmp * dir;
+			}
+		}
+		return 0;
+	});
+}
+//#endregion
 exports.APP_CONF_PREFIX = APP_CONF_PREFIX;
 exports.AppPrefsClient = AppPrefsClient;
+exports.DEFAULT_EXPORT_PAGE_SIZE = DEFAULT_EXPORT_PAGE_SIZE;
 exports.DEFAULT_ROW_HEIGHT_PX = DEFAULT_ROW_HEIGHT_PX;
 exports.DRAFT_PERSISTED_ASPECTS = DRAFT_PERSISTED_ASPECTS;
+exports.ExportAbortError = ExportAbortError;
 exports.MAX_DEFAULT_COLUMN_WIDTH_PX = MAX_DEFAULT_COLUMN_WIDTH_PX;
 exports.NULL_OPS = NULL_OPS;
 exports.PRESET_ASPECTS = PRESET_ASPECTS;
@@ -1645,11 +1918,14 @@ exports.appConfId = appConfId;
 exports.arraysEqual = arraysEqual;
 exports.blockStartFor = blockStartFor;
 exports.buildTableQuery = buildTableQuery;
+exports.cellAsString = cellAsString;
 exports.clampTopIndex = clampTopIndex;
+exports.collectExportRows = collectExportRows;
 exports.columnFilterType = columnFilterType;
 exports.computeDefaultColumnWidth = computeDefaultColumnWidth;
 exports.conditionLabel = conditionLabel;
 exports.conditionsForType = conditionsForType;
+exports.csvCell = csvCell;
 exports.dateShortcuts = dateShortcuts;
 exports.debounce = debounce;
 exports.defaultCondition = defaultCondition;
@@ -1669,6 +1945,8 @@ exports.isEmptyDraft = isEmptyDraft;
 exports.isFilled = isFilled;
 exports.isSimpleEq = isSimpleEq;
 exports.isSystemPresetId = isSystemPresetId;
+exports.isUnavailableError = isUnavailableError;
+exports.mergeDisplayColumns = mergeDisplayColumns;
 exports.mergeFilters = mergeFilters;
 exports.mergeSorters = mergeSorters;
 exports.normaliseSystemPresetId = normaliseSystemPresetId;
@@ -1678,20 +1956,25 @@ exports.planFetch = planFetch;
 exports.reconcileColumnWidthDefaults = reconcileColumnWidthDefaults;
 exports.reorderColumnNames = reorderColumnNames;
 exports.resolveAspectGate = resolveAspectGate;
+exports.resolveExportValue = resolveExportValue;
 exports.resolveSystemPresets = resolveSystemPresets;
 exports.rowsToPks = rowsToPks;
 exports.sameColumnSet = sameColumnSet;
 exports.serializeDraft = serializeDraft;
 exports.setsEqual = setsEqual;
+exports.sortRowsLocally = sortRowsLocally;
 exports.sortersEqual = sortersEqual;
 exports.stableStringify = stableStringify;
 exports.stateToUrlQueryString = stateToUrlQueryString;
+exports.toCsv = toCsv;
 exports.toWireSnapshot = toWireSnapshot;
 exports.togglePk = togglePk;
 exports.trimSelection = trimSelection;
 exports.unescapeRegex = unescapeRegex;
 exports.uniqueryFilterToFieldFilters = uniqueryFilterToFieldFilters;
+exports.urlQueryConsumesKey = urlQueryConsumesKey;
 exports.urlQueryStringToState = urlQueryStringToState;
 exports.userConfId = userConfId;
 exports.walkBackwardAbsorb = walkBackwardAbsorb;
 exports.walkForwardAbsorb = walkForwardAbsorb;
+exports.withStableOrder = withStableOrder;