@atscript/ui-table 0.1.140 → 0.1.142

package/dist/index.cjs

@@ -46,6 +46,19 @@ function filledFilterCount(filters) {
 	for (const path in filters) if (filters[path].some(isFilled)) count++;
 	return count;
 }
+/**
+* `filters` without the fields that have no filled condition — the shape
+* table state holds (a field with nothing filled has no entry). Returns
+* `filters` itself when every field has one; never mutates it.
+*
+* @since 0.1.142
+*/
+function compactFieldFilters(filters) {
+	if (filledFilterCount(filters) === Object.keys(filters).length) return filters;
+	const out = {};
+	for (const path in filters) if (filters[path].some(isFilled)) out[path] = filters[path];
+	return out;
+}
 /** Summarize a field's conditions into a human-readable token label. */
 function filterTokenLabel(path, conditions, columnLabel) {
 	const filled = conditions.filter(isFilled);
@@ -528,6 +541,7 @@ function fieldsOf(expr, out) {
 	else if (!out.includes(key)) out.push(key);
 	return out;
 }
+/** @internal Module-shared with the URL parser; not a package export. */
 function unsupported(reason, expr) {
 	const fields = fieldsOf(expr, []);
 	return {
@@ -753,10 +767,10 @@ function warnUnsupported(issue) {
 /**
 * Split a Uniquery `FilterExpr` into what the table's field-filter model
 * holds exactly (`filters`), what it cannot hold but carries as residual
-* conditions (`residual`, with `carry`), and what it leaves out
-* (`unsupported`). Nothing is approximated: `filters AND residual` selects
-* `expr` minus the `unsupported` pieces and pieces on fields outside
-* `knownFields`.
+* conditions (`residual`, with `carry`), what it leaves out (`unsupported`)
+* and what names a field outside `knownFields` (`unknown`). Nothing is
+* approximated: `filters AND residual` selects `expr` minus the
+* `unsupported` and `unknown` pieces.
 *
 * Never throws, never warns — the caller decides how to report.
 *
@@ -767,7 +781,8 @@ function decomposeUniqueryFilter(expr, opts = {}) {
 	const result = {
 		filters,
 		residual: [],
-		unsupported: []
+		unsupported: [],
+		unknown: []
 	};
 	if (!expr) return result;
 	const knownFields = opts.knownFields;
@@ -788,8 +803,12 @@ function decomposeUniqueryFilter(expr, opts = {}) {
 		}];
 	}
 	const positives = /* @__PURE__ */ new Map();
+	const unknown = /* @__PURE__ */ new Map();
 	for (const term of out.terms) {
-		if (!isKnown(term.field)) continue;
+		if (!isKnown(term.field)) {
+			unknown.set(term.expr, [term.field]);
+			continue;
+		}
 		const list = filters[term.field] ??= [];
 		if (isNegative(term)) {
 			list.push(...term.conds);
@@ -819,11 +838,16 @@ function decomposeUniqueryFilter(expr, opts = {}) {
 	}
 	for (const issue of out.issues) {
 		const fields = issue.fields;
-		if (fields.length > 0 && !fields.some(isKnown)) continue;
-		if (opts.carry && fields.length > 0 && fields.every(isKnown)) carried.push(issue.expr);
+		const outside = fields.filter((f) => !isKnown(f));
+		if (outside.length > 0) unknown.set(issue.expr, outside);
+		else if (opts.carry && fields.length > 0) carried.push(issue.expr);
 		else result.unsupported.push(issue);
 	}
 	result.residual = normalizeResidualFilters(carried);
+	result.unknown = [...unknown].map(([expr, fields]) => ({
+		expr,
+		fields
+	}));
 	return result;
 }
 /**
@@ -874,9 +898,10 @@ function normalizeResidualFilters(exprs) {
 *   to a dev-mode `console.warn` when no handler is given. To keep those
 *   pieces instead, use {@link decomposeUniqueryFilter} with `carry`.
 *
-* Conditions on fields outside `knownFields` (when provided) are ignored
-* silently: they are not this table's (a host page flag, a stale column). A
-* piece that mixes known and unknown fields is reported.
+* Pieces that name a field outside `knownFields` (when provided) are ignored
+* silently: they are not this table's (a host page flag, a hidden or stale
+* column). Since 0.1.141 that includes a piece mixing known and unknown
+* fields — {@link decomposeUniqueryFilter} lists them as `unknown`.
 *
 * Returns `{}` for an empty/missing expression. Never throws.
 */
@@ -1146,6 +1171,176 @@ function resolveSystemPresets(input) {
 	}, ...named];
 }
 //#endregion
+//#region src/presets/prune-preset-snapshot.ts
+/** `[kept, dropped]` in one pass. */
+function partition(list, keep) {
+	const kept = [];
+	const dropped = [];
+	for (const x of list) (keep(x) ? kept : dropped).push(x);
+	return [kept, dropped];
+}
+/** The columns aspect, an empty width map spelled by omission — the way capture writes it. */
+function columnsAspect(columnNames, columnWidths) {
+	return columnWidths && Object.keys(columnWidths).length > 0 ? {
+		columnNames,
+		columnWidths
+	} : { columnNames };
+}
+/**
+* Remove every entry of `snapshot` that names a field outside `known`, per
+* aspect:
+*
+* - `columns.columnNames` — unknown names go, the rest keep their order. When
+*   none survives, it falls back to every column, never an empty grid.
+* - `columns.columnWidths` — unknown keys go.
+* - `filters` (displayed inputs) and `filterOps` — entries on a field outside
+*   `known.server` go. A field's conditions are one AND-ed conjunct, so
+*   dropping one only broadens the result.
+* - `sorters` — unknown entries go, the rest keep their priority.
+* - `itemsPerPage` — untouched.
+*
+* `dropped` is `null` when nothing user-visible went (a width-only drop is
+* hygiene). The input is never mutated.
+*
+* @since 0.1.141
+*/
+function prunePresetSnapshot(snapshot, known) {
+	const isColumn = (p) => known.columns.has(p);
+	const isServer = (p) => known.server.has(p);
+	const out = { ...snapshot };
+	const dropped = {
+		fields: [],
+		columns: [],
+		filterFields: [],
+		filters: {},
+		residual: [],
+		sorters: []
+	};
+	if (snapshot.columns) {
+		const [names, gone] = partition(snapshot.columns.columnNames, isColumn);
+		const [widths] = partition(Object.entries(snapshot.columns.columnWidths ?? {}), ([p]) => isColumn(p));
+		dropped.columns = gone;
+		out.columns = columnsAspect(names.length > 0 || gone.length === 0 ? names : [...known.columns], Object.fromEntries(widths));
+	}
+	if (snapshot.filters) [out.filters, dropped.filterFields] = partition(snapshot.filters, isServer);
+	if (snapshot.filterOps) {
+		const [kept, gone] = partition(Object.entries(snapshot.filterOps), ([p]) => isServer(p));
+		out.filterOps = Object.fromEntries(kept);
+		dropped.filters = Object.fromEntries(gone);
+	}
+	if (snapshot.sorters) [out.sorters, dropped.sorters] = partition(snapshot.sorters, (s) => isColumn(s.field));
+	dropped.fields = [...new Set([
+		...dropped.columns,
+		...dropped.filterFields,
+		...Object.keys(dropped.filters),
+		...dropped.sorters.map((s) => s.field)
+	])];
+	return {
+		snapshot: out,
+		dropped: dropped.fields.length > 0 ? dropped : null
+	};
+}
+/**
+* Spell a snapshot the way table state holds it, so it compares equal to a
+* capture of the state it produces:
+*
+* - `columns.columnWidths` — an entry equal to its column's default width, or
+*   on a path with no default (not a column), goes; an emptied map is
+*   omitted. Capture writes overrides only.
+* - `filterOps` — a field with no filled condition goes
+*   (`compactFieldFilters`). Table state never holds one.
+*
+* `defaultWidths` maps each column path to its default width — the `d` of
+* its `ColumnWidthsMap` entry. Other aspects pass through. Returns `snapshot`
+* itself when nothing changes; the input is never mutated.
+*
+* @since 0.1.142
+*/
+function canonicalPresetSnapshot(snapshot, defaultWidths) {
+	let out = snapshot;
+	const columns = snapshot.columns;
+	if (columns?.columnWidths) {
+		const entries = Object.entries(columns.columnWidths);
+		const [kept] = partition(entries, ([p, w]) => {
+			const d = defaultWidths[p];
+			return d !== void 0 && d !== w;
+		});
+		if (kept.length !== entries.length || kept.length === 0) out = {
+			...out,
+			columns: columnsAspect(columns.columnNames, Object.fromEntries(kept))
+		};
+	}
+	if (snapshot.filterOps) {
+		const filterOps = compactFieldFilters(snapshot.filterOps);
+		if (filterOps !== snapshot.filterOps) out = {
+			...out,
+			filterOps
+		};
+	}
+	return out;
+}
+/**
+* Split residual filter conditions, in one pass, into the ones that name
+* only `known` fields and the ones that do not. A condition naming any
+* unknown field is dropped WHOLE — never pruned inside an `$or` (that would
+* narrow the result) or a `$not` (that would invert it). Each condition is an
+* AND-ed conjunct, so dropping one only broadens the result.
+*
+* `dropped` holds the conditions in `residual` and the unknown paths in
+* `fields`; `null` when every condition is kept.
+*
+* @since 0.1.141
+*/
+function pruneResidualFilters(exprs, known) {
+	const kept = [];
+	const residual = [];
+	const fields = /* @__PURE__ */ new Set();
+	for (const expr of exprs) {
+		const unknown = filterExprFields(expr).filter((p) => !known.has(p));
+		if (unknown.length === 0) {
+			kept.push(expr);
+			continue;
+		}
+		residual.push(expr);
+		for (const p of unknown) fields.add(p);
+	}
+	if (residual.length === 0) return {
+		kept,
+		dropped: null
+	};
+	return {
+		kept,
+		dropped: {
+			fields: [...fields],
+			columns: [],
+			filterFields: [],
+			filters: {},
+			residual,
+			sorters: []
+		}
+	};
+}
+/**
+* Append what a prune dropped back onto a snapshot captured from (pruned)
+* table state, so overwriting a preset with a narrower view does not destroy
+* the parts the saver cannot see. Column names, filter inputs and sorters go
+* after the captured ones; field filters are added back. Only aspects
+* `captured` carries are touched; widths of hidden columns are not kept.
+*
+* @since 0.1.141
+*/
+function restoreDroppedEntries(captured, dropped) {
+	const out = { ...captured };
+	if (captured.columns) out.columns = columnsAspect([...captured.columns.columnNames, ...dropped.columns], captured.columns.columnWidths);
+	if (captured.filters) out.filters = [...captured.filters, ...dropped.filterFields];
+	if (captured.filterOps) out.filterOps = {
+		...captured.filterOps,
+		...dropped.filters
+	};
+	if (captured.sorters) out.sorters = [...captured.sorters, ...dropped.sorters];
+	return out;
+}
+//#endregion
 //#region src/presets/preset-dirty.ts
 /**
 * JSON-stringify with object keys sorted alphabetically at every depth so
@@ -1749,6 +1944,20 @@ const CONSUMED_CONTROLS = new Set([
 	"$skip",
 	URL_SNAPSHOT_KEY
 ]);
+function toSet(paths) {
+	if (!paths) return null;
+	return paths instanceof Set ? paths : new Set(paths);
+}
+/**
+* `field=value` (or `field=null`) — the one filter shape a host page flag
+* shares, so a bare one on an unknown field is not reported as dropped.
+*/
+function isBareEquality(expr) {
+	const keys = Object.keys(expr);
+	if (keys.length !== 1 || keys[0].startsWith("$")) return false;
+	const v = expr[keys[0]];
+	return v === null || typeof v !== "object";
+}
 /**
 * Characters that can only appear in a uniqu filter key, never in a page flag:
 * comparison operators, `^` (OR), `( )` (groups) and `{ }` (`$in` lists).
@@ -1775,9 +1984,10 @@ function urlQueryConsumesKey(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
-* recipient's view:
-* - unknown fields (not in `knownFields`) → silently dropped
+* Robust by design — schema drift, fields hidden from the recipient and
+* copy-paste errors must not break the recipient's view:
+* - unknown fields (not in `knownFields`) → dropped, listed in `unknown` /
+*   `unknownSorters` (the parser does not warn — the caller decides)
 * - filter pieces field filters cannot express (cross-field OR, unknown
 *   operator, …) → left out of `filters` and listed in `unsupported`, never
 *   approximated (the parser does not warn — the caller decides). Unless
@@ -1810,12 +2020,15 @@ function urlQueryStringToState(urlString, opts = {}) {
 	const sortersGate = resolveAspectGate(opts.sync?.sorters);
 	const searchOff = opts.sync?.search === false;
 	const paginationOff = opts.sync?.pagination === false;
-	const knownSet = opts.knownFields ? new Set(opts.knownFields) : null;
+	const knownSet = toSet(opts.knownFields);
+	const localSet = toSet(opts.localFields);
+	const isHidden = (f) => !!knownSet && !knownSet.has(f) && !localSet?.has(f);
 	let filterKnown;
 	if (filtersGate === "all") filterKnown = knownSet ?? void 0;
 	else if (filtersGate !== "none") if (knownSet) {
-		filterKnown = /* @__PURE__ */ new Set();
-		for (const path of filtersGate) if (knownSet.has(path)) filterKnown.add(path);
+		const owned = /* @__PURE__ */ new Set();
+		for (const path of filtersGate) if (knownSet.has(path)) owned.add(path);
+		filterKnown = owned;
 	} else filterKnown = filtersGate;
 	const decomposed = filtersGate === "none" ? null : decomposeUniqueryFilter(parsed.filter, {
 		knownFields: filterKnown,
@@ -1823,20 +2036,19 @@ function urlQueryStringToState(urlString, opts = {}) {
 	});
 	const filters = decomposed?.filters ?? {};
 	const sorters = [];
+	const unknownSorters = [];
 	if (sortersGate !== "none") {
 		const $sort = parsed.controls?.$sort;
 		if ($sort && typeof $sort === "object") for (const field in $sort) {
-			if (knownSet && !knownSet.has(field)) continue;
 			if (!gateOwns(sortersGate, field)) continue;
 			const dir = $sort[field];
-			if (dir === 1) sorters.push({
+			if (dir !== 1 && dir !== -1) continue;
+			const sorter = {
 				field,
-				direction: "asc"
-			});
-			else if (dir === -1) sorters.push({
-				field,
-				direction: "desc"
-			});
+				direction: dir === 1 ? "asc" : "desc"
+			};
+			if (!knownSet || knownSet.has(field)) sorters.push(sorter);
+			else if (isHidden(field)) unknownSorters.push(sorter);
 		}
 	}
 	const $search = parsed.controls?.$search;
@@ -1845,8 +2057,24 @@ function urlQueryStringToState(urlString, opts = {}) {
 		sorters,
 		searchTerm: !searchOff && typeof $search === "string" ? $search : ""
 	};
-	if (decomposed?.unsupported.length) out.unsupported = decomposed.unsupported;
+	const unsupported$1 = decomposed?.unsupported ?? [];
+	const unknown = [];
+	for (const piece of decomposed?.unknown ?? []) {
+		const hidden = piece.fields.filter(isHidden);
+		if (hidden.length > 0) {
+			if (!isBareEquality(piece.expr)) unknown.push({
+				expr: piece.expr,
+				fields: hidden
+			});
+			continue;
+		}
+		const issue = unsupported("cross-field", piece.expr);
+		if (issue.fields.some((f) => filterKnown?.has(f))) unsupported$1.push(issue);
+	}
+	if (unsupported$1.length) out.unsupported = unsupported$1;
 	if (decomposed?.residual.length) out.residual = decomposed.residual;
+	if (unknown.length) out.unknown = unknown;
+	if (unknownSorters.length) out.unknownSorters = unknownSorters;
 	if (opts.sync?.snapshot !== false && parsed.controls && "$snapshot" in parsed.controls) out.snapshot = true;
 	if (!searchOff) {
 		const $relevance = parsed.controls?.$relevance;
@@ -2419,12 +2647,14 @@ exports.appConfId = appConfId;
 exports.arraysEqual = arraysEqual;
 exports.blockStartFor = blockStartFor;
 exports.buildTableQuery = buildTableQuery;
+exports.canonicalPresetSnapshot = canonicalPresetSnapshot;
 exports.cellAsString = cellAsString;
 exports.clampTopIndex = clampTopIndex;
 exports.collectExportRows = collectExportRows;
 exports.columnDefaultCondition = columnDefaultCondition;
 exports.columnFilterConditions = columnFilterConditions;
 exports.columnFilterType = columnFilterType;
+exports.compactFieldFilters = compactFieldFilters;
 exports.computeDefaultColumnWidth = computeDefaultColumnWidth;
 exports.conditionLabel = conditionLabel;
 exports.conditionsForType = conditionsForType;
@@ -2464,12 +2694,15 @@ exports.pageAlignedBlocksFor = pageAlignedBlocksFor;
 exports.parseColumnFilterInput = parseColumnFilterInput;
 exports.parseFilterInput = parseFilterInput;
 exports.planFetch = planFetch;
+exports.prunePresetSnapshot = prunePresetSnapshot;
+exports.pruneResidualFilters = pruneResidualFilters;
 exports.reconcileColumnWidthDefaults = reconcileColumnWidthDefaults;
 exports.reorderColumnNames = reorderColumnNames;
 exports.residualGateOwns = residualGateOwns;
 exports.resolveAspectGate = resolveAspectGate;
 exports.resolveExportValue = resolveExportValue;
 exports.resolveSystemPresets = resolveSystemPresets;
+exports.restoreDroppedEntries = restoreDroppedEntries;
 exports.rowsToPks = rowsToPks;
 exports.sameColumnSet = sameColumnSet;
 exports.serializeDraft = serializeDraft;