@atscript/ui-table 0.1.133 → 0.1.135

package/dist/index.cjs

@@ -1681,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;
@@ -1698,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;
@@ -1723,6 +1946,7 @@ exports.isFilled = isFilled;
 exports.isSimpleEq = isSimpleEq;
 exports.isSystemPresetId = isSystemPresetId;
 exports.isUnavailableError = isUnavailableError;
+exports.mergeDisplayColumns = mergeDisplayColumns;
 exports.mergeFilters = mergeFilters;
 exports.mergeSorters = mergeSorters;
 exports.normaliseSystemPresetId = normaliseSystemPresetId;
@@ -1732,14 +1956,17 @@ 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;
@@ -1750,3 +1977,4 @@ exports.urlQueryStringToState = urlQueryStringToState;
 exports.userConfId = userConfId;
 exports.walkBackwardAbsorb = walkBackwardAbsorb;
 exports.walkForwardAbsorb = walkForwardAbsorb;
+exports.withStableOrder = withStableOrder;

package/dist/index.d.cts

@@ -1106,4 +1106,188 @@ type ColumnReorderPosition = "before" | "after";
  */
 declare function reorderColumnNames(names: string[], fromPath: string, toPath: string, position: ColumnReorderPosition): string[];
 //#endregion
-export { APP_CONF_PREFIX, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, DEFAULT_ROW_HEIGHT_PX, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DraftPersistedAspect, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, USER_CONF_PREFIX, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, clampTopIndex, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortersEqual, stableStringify, stateToUrlQueryString, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb };
+//#region src/export/csv.d.ts
+/** A cell value after export-time resolution — always a spreadsheet scalar. */
+type ExportScalar = string | number | boolean | null;
+/** Options shared by {@link csvCell} and {@link toCsv}. */
+interface CsvOptions {
+  /**
+   * Prepend a UTF-8 byte-order mark. Excel needs it to detect UTF-8 in a
+   * `.csv` opened by double-click; most other tools don't care. Default `false`.
+   */
+  bom?: boolean;
+  /**
+   * Prefix a STRING cell starting with `=`, `+`, `-`, `@`, TAB or CR with a
+   * single quote so a spreadsheet treats it as text instead of a formula
+   * (CSV-injection defence). Numbers and booleans are never touched — a
+   * negative number stays numeric. Default `true`; set `false` when the file
+   * is consumed by a parser rather than a spreadsheet.
+   */
+  escapeFormulas?: boolean;
+  /** Field delimiter. Default `","`. */
+  delimiter?: string;
+}
+/**
+ * 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.
+ */
+declare function csvCell(value: ExportScalar | undefined, opts?: CsvOptions): string;
+/**
+ * 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.
+ */
+declare function toCsv(header: readonly string[], rows: readonly (readonly ExportScalar[])[], opts?: CsvOptions): string;
+//#endregion
+//#region src/export/export-paging.d.ts
+/** Default page size used by the export pager when the caller gives none. */
+declare const DEFAULT_EXPORT_PAGE_SIZE = 500;
+/** One page of an export run — the subset of `PageResult` the pager needs. */
+interface ExportPage {
+  data: Record<string, unknown>[];
+  /** Total row count, when the endpoint reports one. */
+  count?: number;
+}
+/** Fetches one page of the export query. Mirrors `client.pages(query, page, size)`. */
+type ExportPageFetcher = (query: Uniquery, page: number, size: number) => Promise<ExportPage>;
+/** Rejection raised when an export is cancelled through its `AbortSignal`. */
+declare class ExportAbortError extends Error {
+  /** Matches the DOM convention so `err.name === "AbortError"` checks work. */
+  readonly name = "AbortError";
+  constructor(message?: string);
+}
+interface CollectExportRowsOptions<T = Record<string, unknown>> {
+  /** The query to page through. Pass it through {@link withStableOrder} first. */
+  query: Uniquery;
+  /** Rows per request. Default {@link DEFAULT_EXPORT_PAGE_SIZE}. */
+  pageSize?: number;
+  fetchPage: ExportPageFetcher;
+  /** Aborts between pages; the returned promise rejects with {@link ExportAbortError}. */
+  signal?: AbortSignal;
+  /** Called after every settled page. `total` comes from the first page's `count`. */
+  onProgress?: (done: number, total?: number) => void;
+  /** Hard ceiling on collected rows — the pager stops once it is reached. */
+  maxRows?: number;
+  /**
+   * Project each row as it arrives — the collected array holds the projection,
+   * not the raw row, so a formatted export never keeps both in memory.
+   * Identity by default.
+   */
+  mapRow?: (row: Record<string, unknown>) => T;
+}
+/**
+ * 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.
+ */
+declare function withStableOrder(query: Uniquery, primaryKeys: readonly string[]): Uniquery;
+/**
+ * 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.
+ */
+declare function collectExportRows<T = Record<string, unknown>>(opts: CollectExportRowsOptions<T>): Promise<{
+  rows: T[];
+  total?: number;
+}>;
+//#endregion
+//#region src/export/export-value.d.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.
+ */
+declare function resolveExportValue(value: unknown, column?: ColumnDef): ExportScalar;
+//#endregion
+//#region src/columns/display-columns.d.ts
+/**
+ * A client-owned column the app adds on top of the server's `/meta` columns —
+ * a derived value, a count, a link, a widget. It has a label, a width and a
+ * renderer, takes part in column visibility / reordering / presets like any
+ * other column, but never reaches the backend: no `$select`, no server sort,
+ * no filters.
+ *
+ * Since 0.1.134.
+ */
+interface DisplayColumnDef {
+  /**
+   * Stable key. Becomes the column's `path`, so it is what `cell-<key>` /
+   * `header-<key>` slots, the `columnNames` model and presets refer to. Must
+   * not collide with a real field path.
+   */
+  key: string;
+  /** Header label. Unlike `fixed` chrome columns, a display column is labelled. */
+  label: string;
+  /** Default width (any CSS length), e.g. `"8em"`. */
+  width?: string;
+  /** Initial position among the server columns (lower = earlier). Appended when omitted. */
+  order?: number;
+  /**
+   * `'local'` makes the header offer sorting, applied client-side over the
+   * rows currently loaded (page-local). Anything else — including the default
+   * — leaves the column unsortable, since the server cannot sort it.
+   *
+   * Paged tables only: `<AsWindowTable>` caches rows by absolute index, so
+   * there is no page to re-order and the affordance is not offered there.
+   */
+  sortable?: false | "local";
+  /**
+   * The value `sortable: 'local'` orders by. A display column has no server
+   * field behind it, so without this the sorter reads `row[key]` — which is
+   * `undefined` unless the app happens to carry that key on the row. Ignored
+   * when the column is not sorted locally.
+   */
+  sortValue?: (row: Record<string, unknown>) => unknown;
+  /** Named cell component (`components[name]` on the table context). */
+  component?: string;
+  /** Cell type for the `types[type]` dispatch. Default `"text"`. */
+  type?: string;
+}
+/**
+ * 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.
+ */
+declare function mergeDisplayColumns(base: ColumnDef[], display: readonly DisplayColumnDef[]): ColumnDef[];
+//#endregion
+//#region src/utils/sort-rows.d.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.
+ */
+declare function cellAsString(v: unknown): string;
+/**
+ * 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.
+ */
+declare function sortRowsLocally<T extends Record<string, unknown>>(rows: T[], sorters: readonly SortControl[], getValue?: (row: T, field: string) => unknown): T[];
+//#endregion
+export { APP_CONF_PREFIX, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, type CsvOptions, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DisplayColumnDef, type DraftPersistedAspect, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, USER_CONF_PREFIX, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };

package/dist/index.d.mts

@@ -1106,4 +1106,188 @@ type ColumnReorderPosition = "before" | "after";
  */
 declare function reorderColumnNames(names: string[], fromPath: string, toPath: string, position: ColumnReorderPosition): string[];
 //#endregion
-export { APP_CONF_PREFIX, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, DEFAULT_ROW_HEIGHT_PX, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DraftPersistedAspect, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, USER_CONF_PREFIX, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, clampTopIndex, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortersEqual, stableStringify, stateToUrlQueryString, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb };
+//#region src/export/csv.d.ts
+/** A cell value after export-time resolution — always a spreadsheet scalar. */
+type ExportScalar = string | number | boolean | null;
+/** Options shared by {@link csvCell} and {@link toCsv}. */
+interface CsvOptions {
+  /**
+   * Prepend a UTF-8 byte-order mark. Excel needs it to detect UTF-8 in a
+   * `.csv` opened by double-click; most other tools don't care. Default `false`.
+   */
+  bom?: boolean;
+  /**
+   * Prefix a STRING cell starting with `=`, `+`, `-`, `@`, TAB or CR with a
+   * single quote so a spreadsheet treats it as text instead of a formula
+   * (CSV-injection defence). Numbers and booleans are never touched — a
+   * negative number stays numeric. Default `true`; set `false` when the file
+   * is consumed by a parser rather than a spreadsheet.
+   */
+  escapeFormulas?: boolean;
+  /** Field delimiter. Default `","`. */
+  delimiter?: string;
+}
+/**
+ * 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.
+ */
+declare function csvCell(value: ExportScalar | undefined, opts?: CsvOptions): string;
+/**
+ * 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.
+ */
+declare function toCsv(header: readonly string[], rows: readonly (readonly ExportScalar[])[], opts?: CsvOptions): string;
+//#endregion
+//#region src/export/export-paging.d.ts
+/** Default page size used by the export pager when the caller gives none. */
+declare const DEFAULT_EXPORT_PAGE_SIZE = 500;
+/** One page of an export run — the subset of `PageResult` the pager needs. */
+interface ExportPage {
+  data: Record<string, unknown>[];
+  /** Total row count, when the endpoint reports one. */
+  count?: number;
+}
+/** Fetches one page of the export query. Mirrors `client.pages(query, page, size)`. */
+type ExportPageFetcher = (query: Uniquery, page: number, size: number) => Promise<ExportPage>;
+/** Rejection raised when an export is cancelled through its `AbortSignal`. */
+declare class ExportAbortError extends Error {
+  /** Matches the DOM convention so `err.name === "AbortError"` checks work. */
+  readonly name = "AbortError";
+  constructor(message?: string);
+}
+interface CollectExportRowsOptions<T = Record<string, unknown>> {
+  /** The query to page through. Pass it through {@link withStableOrder} first. */
+  query: Uniquery;
+  /** Rows per request. Default {@link DEFAULT_EXPORT_PAGE_SIZE}. */
+  pageSize?: number;
+  fetchPage: ExportPageFetcher;
+  /** Aborts between pages; the returned promise rejects with {@link ExportAbortError}. */
+  signal?: AbortSignal;
+  /** Called after every settled page. `total` comes from the first page's `count`. */
+  onProgress?: (done: number, total?: number) => void;
+  /** Hard ceiling on collected rows — the pager stops once it is reached. */
+  maxRows?: number;
+  /**
+   * Project each row as it arrives — the collected array holds the projection,
+   * not the raw row, so a formatted export never keeps both in memory.
+   * Identity by default.
+   */
+  mapRow?: (row: Record<string, unknown>) => T;
+}
+/**
+ * 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.
+ */
+declare function withStableOrder(query: Uniquery, primaryKeys: readonly string[]): Uniquery;
+/**
+ * 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.
+ */
+declare function collectExportRows<T = Record<string, unknown>>(opts: CollectExportRowsOptions<T>): Promise<{
+  rows: T[];
+  total?: number;
+}>;
+//#endregion
+//#region src/export/export-value.d.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.
+ */
+declare function resolveExportValue(value: unknown, column?: ColumnDef): ExportScalar;
+//#endregion
+//#region src/columns/display-columns.d.ts
+/**
+ * A client-owned column the app adds on top of the server's `/meta` columns —
+ * a derived value, a count, a link, a widget. It has a label, a width and a
+ * renderer, takes part in column visibility / reordering / presets like any
+ * other column, but never reaches the backend: no `$select`, no server sort,
+ * no filters.
+ *
+ * Since 0.1.134.
+ */
+interface DisplayColumnDef {
+  /**
+   * Stable key. Becomes the column's `path`, so it is what `cell-<key>` /
+   * `header-<key>` slots, the `columnNames` model and presets refer to. Must
+   * not collide with a real field path.
+   */
+  key: string;
+  /** Header label. Unlike `fixed` chrome columns, a display column is labelled. */
+  label: string;
+  /** Default width (any CSS length), e.g. `"8em"`. */
+  width?: string;
+  /** Initial position among the server columns (lower = earlier). Appended when omitted. */
+  order?: number;
+  /**
+   * `'local'` makes the header offer sorting, applied client-side over the
+   * rows currently loaded (page-local). Anything else — including the default
+   * — leaves the column unsortable, since the server cannot sort it.
+   *
+   * Paged tables only: `<AsWindowTable>` caches rows by absolute index, so
+   * there is no page to re-order and the affordance is not offered there.
+   */
+  sortable?: false | "local";
+  /**
+   * The value `sortable: 'local'` orders by. A display column has no server
+   * field behind it, so without this the sorter reads `row[key]` — which is
+   * `undefined` unless the app happens to carry that key on the row. Ignored
+   * when the column is not sorted locally.
+   */
+  sortValue?: (row: Record<string, unknown>) => unknown;
+  /** Named cell component (`components[name]` on the table context). */
+  component?: string;
+  /** Cell type for the `types[type]` dispatch. Default `"text"`. */
+  type?: string;
+}
+/**
+ * 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.
+ */
+declare function mergeDisplayColumns(base: ColumnDef[], display: readonly DisplayColumnDef[]): ColumnDef[];
+//#endregion
+//#region src/utils/sort-rows.d.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.
+ */
+declare function cellAsString(v: unknown): string;
+/**
+ * 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.
+ */
+declare function sortRowsLocally<T extends Record<string, unknown>>(rows: T[], sorters: readonly SortControl[], getValue?: (row: T, field: string) => unknown): T[];
+//#endregion
+export { APP_CONF_PREFIX, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, type CsvOptions, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DisplayColumnDef, type DraftPersistedAspect, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, USER_CONF_PREFIX, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { ClientError } from "@atscript/db-client";
-import { getDefaultClientFactory } from "@atscript/ui";
+import { getDefaultClientFactory, str } from "@atscript/ui";
 import { buildUrl } from "@uniqu/url/builder";
 import { parseUrl } from "@uniqu/url";
 //#region src/filters/filter-conditions.ts
@@ -1680,4 +1680,222 @@ function reorderColumnNames(names, fromPath, toPath, position) {
 	return without.slice(0, insertAt).concat(fromPath, without.slice(insertAt));
 }
 //#endregion
-export { APP_CONF_PREFIX, AppPrefsClient, DEFAULT_ROW_HEIGHT_PX, DRAFT_PERSISTED_ASPECTS, MAX_DEFAULT_COLUMN_WIDTH_PX, NULL_OPS, PRESET_ASPECTS, PresetsClient, PresetsHttpError, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, USER_CONF_PREFIX, appConfId, arraysEqual, blockStartFor, buildTableQuery, clampTopIndex, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortersEqual, stableStringify, stateToUrlQueryString, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb };
+//#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 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
+export { APP_CONF_PREFIX, AppPrefsClient, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DRAFT_PERSISTED_ASPECTS, ExportAbortError, MAX_DEFAULT_COLUMN_WIDTH_PX, NULL_OPS, PRESET_ASPECTS, PresetsClient, PresetsHttpError, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, USER_CONF_PREFIX, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/ui-table",
-  "version": "0.1.133",
+  "version": "0.1.135",
   "description": "Framework-agnostic filter model, filter-to-Uniquery conversion, and preset serialization for atscript tables",
   "keywords": [
     "atscript",
@@ -42,7 +42,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@atscript/ui": "0.1.133"
+    "@atscript/ui": "0.1.135"
   },
   "devDependencies": {
     "@atscript/db-client": "^0.1.129",