@atscript/ui-table 0.1.139 → 0.1.141

package/dist/index.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _uniqu_core = require("@uniqu/core");
+let _uniqu_url_builder = require("@uniqu/url/builder");
 let _atscript_db_client = require("@atscript/db-client");
 let _atscript_ui = require("@atscript/ui");
-let _uniqu_url_builder = require("@uniqu/url/builder");
 let _uniqu_url = require("@uniqu/url");
 //#region src/filters/filter-conditions.ts
 /** Conditions that operate purely on nullability — value is ignored. */
@@ -509,8 +509,16 @@ const RANGE_OPS = {
 	$lt: "lt",
 	$lte: "lte"
 };
-/** Field paths an expression references, deduped, in order of appearance. */
-function fieldsOf(expr, out = []) {
+/**
+* Field paths a Uniquery filter expression references, deduped, in order of
+* appearance (logical operators are walked, operator keys skipped).
+*
+* @internal Exported for `@atscript/vue-table`.
+*/
+function filterExprFields(expr) {
+	return fieldsOf(expr, []);
+}
+function fieldsOf(expr, out) {
 	if (Array.isArray(expr)) {
 		for (const child of expr) fieldsOf(child, out);
 		return out;
@@ -520,8 +528,9 @@ 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);
+	const fields = fieldsOf(expr, []);
 	return {
 		reason: fields.length > 1 ? "cross-field" : reason,
 		expr,
@@ -699,6 +708,7 @@ function invert(cond) {
 * anything else would invert into an OR of ANDs, which the model cannot hold.
 */
 function collectNot(child, out) {
+	if (isPlainObject(child) && Object.keys(child).length === 1 && "$not" in child) return collect(child.$not, out);
 	const expr = { $not: child };
 	const b = classifyBranch(child);
 	if (b && !("reason" in b) && (b.terms.length === 1 || b.terms.every(isNegative))) {
@@ -742,30 +752,27 @@ function warnUnsupported(issue) {
 	console.warn(`[ui-table] Filter left out (${issue.reason}): ${JSON.stringify(issue.expr)}. Field filters cannot express it, so the result is broader than the source filter.`);
 }
 /**
-* Convert a Uniquery `FilterExpr` back into the UI's `FieldFilters` shape.
-*
-* Inverse of `filtersToUniqueryFilter`, and exact for everything that encoder
-* produces. For any other input, each AND-ed piece is either converted exactly
-* or left out whole and reported — never approximated:
-*
-* - `$in` becomes equality conditions on the field, `$nin` inequality ones.
-* - A same-field `$or` becomes that field's OR'd conditions.
-* - A `$not` that inverts equality / emptiness becomes the inverse conditions.
-* - Fields next to `$and` / `$or` / `$not` in one object are all kept.
-* - Anything else (see {@link UnsupportedFilterReason}) is left out. Leaving
-*   an AND-ed piece out only ever widens the match, so the result selects a
-*   superset of `expr`. Each left-out piece goes to `onUnsupportedFilter`, or
-*   to a dev-mode `console.warn` when no handler is given.
+* 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`), 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.
 *
-* 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.
+* Never throws, never warns — the caller decides how to report.
 *
-* Returns `{}` for an empty/missing expression. Never throws.
+* @since 0.1.140
 */
-function uniqueryFilterToFieldFilters(expr, knownFields, onUnsupportedFilter = warnUnsupported) {
-	const acc = {};
-	if (!expr) return acc;
+function decomposeUniqueryFilter(expr, opts = {}) {
+	const filters = {};
+	const result = {
+		filters,
+		residual: [],
+		unsupported: [],
+		unknown: []
+	};
+	if (!expr) return result;
+	const knownFields = opts.knownFields;
 	const known = knownFields == null ? null : knownFields instanceof Set ? knownFields : new Set(knownFields);
 	const isKnown = (field) => known === null || known.has(field);
 	const out = {
@@ -783,21 +790,170 @@ function uniqueryFilterToFieldFilters(expr, knownFields, onUnsupportedFilter = w
 		}];
 	}
 	const positives = /* @__PURE__ */ new Map();
+	const unknown = /* @__PURE__ */ new Map();
 	for (const term of out.terms) {
-		if (!isKnown(term.field)) continue;
-		const list = acc[term.field] ??= [];
-		const kept = positives.get(term.field);
-		if (isNegative(term) || !kept) {
-			if (!isNegative(term)) positives.set(term.field, term.conds);
+		if (!isKnown(term.field)) {
+			unknown.set(term.expr, [term.field]);
+			continue;
+		}
+		const list = filters[term.field] ??= [];
+		if (isNegative(term)) {
 			list.push(...term.conds);
-		} else if (!sameConds(kept, term.conds)) out.issues.push({
+			continue;
+		}
+		const groups = positives.get(term.field);
+		if (!groups) {
+			positives.set(term.field, [term]);
+			list.push(...term.conds);
+		} else if (!groups.some((g) => sameConds(g.conds, term.conds))) groups.push(term);
+	}
+	const carried = [];
+	for (const [field, groups] of positives) {
+		if (groups.length < 2) continue;
+		const leftOut = opts.carry ? groups : groups.slice(1);
+		if (opts.carry) {
+			const kept = new Set(groups[0].conds);
+			const rest = filters[field].filter((c) => !kept.has(c));
+			if (rest.length > 0) filters[field] = rest;
+			else delete filters[field];
+		}
+		for (const term of leftOut) out.issues.push({
 			reason: "conjunction",
 			expr: term.expr,
-			fields: [term.field]
+			fields: [field]
 		});
 	}
-	for (const issue of out.issues) if (issue.fields.length === 0 || issue.fields.some(isKnown)) onUnsupportedFilter(issue);
-	return acc;
+	for (const issue of out.issues) {
+		const fields = issue.fields;
+		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;
+}
+/**
+* Canonical identity of a filter expression — its `@uniqu/url` spelling.
+* Two expressions with the same key select the same rows.
+*
+* @since 0.1.140
+*/
+function filterExprKey(expr) {
+	try {
+		return (0, _uniqu_url_builder.buildUrl)({ filter: expr });
+	} catch {
+		return JSON.stringify(expr) ?? "";
+	}
+}
+/**
+* A residual-condition list with empty expressions and duplicates (by
+* {@link filterExprKey}) dropped, sorted by key. Sorted, not first-appearance:
+* the URL parser moves \`$not\`-wrapped clauses (how \`mergeFilters\` spells
+* a repeated same-field clause) ahead of plain ones, so appearance order would
+* flip on every round trip.
+*
+* @internal Exported for `@atscript/vue-table`.
+*/
+function normalizeResidualFilters(exprs) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const expr of exprs) {
+		if (!isPlainObject(expr)) continue;
+		const key = filterExprKey(expr);
+		if (key && !byKey.has(key)) byKey.set(key, expr);
+	}
+	return [...byKey.keys()].toSorted().map((key) => byKey.get(key));
+}
+/**
+* Convert a Uniquery `FilterExpr` back into the UI's `FieldFilters` shape.
+*
+* Inverse of `filtersToUniqueryFilter`, and exact for everything that encoder
+* produces. For any other input, each AND-ed piece is either converted exactly
+* or left out whole and reported — never approximated:
+*
+* - `$in` becomes equality conditions on the field, `$nin` inequality ones.
+* - A same-field `$or` becomes that field's OR'd conditions.
+* - A `$not` that inverts equality / emptiness becomes the inverse conditions.
+* - Fields next to `$and` / `$or` / `$not` in one object are all kept.
+* - Anything else (see {@link UnsupportedFilterReason}) is left out. Leaving
+*   an AND-ed piece out only ever widens the match, so the result selects a
+*   superset of `expr`. Each left-out piece goes to `onUnsupportedFilter`, or
+*   to a dev-mode `console.warn` when no handler is given. To keep those
+*   pieces instead, use {@link decomposeUniqueryFilter} with `carry`.
+*
+* 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.
+*/
+function uniqueryFilterToFieldFilters(expr, knownFields, onUnsupportedFilter = warnUnsupported) {
+	const { filters, unsupported } = decomposeUniqueryFilter(expr, { knownFields });
+	for (const issue of unsupported) onUnsupportedFilter(issue);
+	return filters;
+}
+//#endregion
+//#region src/filters/format-filter-expr.ts
+function show(v) {
+	if (v instanceof Date) return v.toISOString();
+	if (typeof v === "object" && v !== null) return JSON.stringify(v) ?? "";
+	return String(v);
+}
+/** One comparison, worded like the filter chips (the decoder's operator table). */
+function leaf(label, op, value) {
+	if (op === "$eq" && value instanceof RegExp) op = "$regex";
+	if ((op === "$in" || op === "$nin") && Array.isArray(value)) return `${label} ${op === "$in" ? "is one of" : "is none of"} ${value.map(show).join(", ")}`;
+	const conds = decodeOperator(op, value);
+	if (conds?.length === 1) return filterTokenLabel(label, conds, label);
+	return (0, _uniqu_url_builder.buildUrl)({ filter: { [label]: { [op]: value } } }) || `${label}${op}`;
+}
+function join(children, kind) {
+	const parts = children.filter((c) => c.s);
+	if (parts.length === 0) return {
+		s: "",
+		kind: "leaf"
+	};
+	if (parts.length === 1) return parts[0];
+	const wrap = kind === "and" ? "or" : "and";
+	return {
+		s: parts.map((c) => c.kind === wrap ? `(${c.s})` : c.s).join(` ${kind} `),
+		kind
+	};
+}
+/**
+* Human-readable rendering of a Uniquery filter expression, worded like the
+* filter-field chips: `(Status equals shipped and Total greater than 500) or
+* (Status equals pending and Total less or equal 50)`. `and` binds tighter
+* than `or`; groups are parenthesized only where needed. Operators without a
+* wording fall back to their `@uniqu/url` spelling.
+*
+* @param labelOf — display label for a field path (e.g. the column label);
+*   the path itself when omitted or when it returns `undefined`.
+* @since 0.1.140
+*/
+function formatFilterExpr(expr, labelOf) {
+	const visitor = {
+		comparison: (field, op, value) => ({
+			s: leaf(labelOf?.(field) ?? field, op, value),
+			kind: "leaf"
+		}),
+		and: (children) => join(children, "and"),
+		or: (children) => join(children, "or"),
+		not: (child) => ({
+			s: child.s ? `not (${child.s})` : "",
+			kind: "leaf"
+		})
+	};
+	try {
+		return (0, _uniqu_core.walkFilter)(expr, visitor)?.s ?? "";
+	} catch {
+		return JSON.stringify(expr) ?? "";
+	}
 }
 //#endregion
 //#region src/filters/date-shortcuts.ts
@@ -1002,6 +1158,137 @@ 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
+	};
+}
+/**
+* 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
@@ -1394,8 +1681,9 @@ function mergeSorters(forceSorters, userSorters) {
 //#endregion
 //#region src/query/merge-filters.ts
 /**
-* AND-merge two filter expressions, producing a wire shape that survives
-* `@uniqu/url`'s `mergeConjunction` parser collapse.
+* AND-merge filter expressions (`undefined` ones skipped), producing a wire
+* shape that survives `@uniqu/url`'s `mergeConjunction` parser collapse.
+* Variadic since 0.1.140.
 *
 * The collapse problem: when two `$and` siblings target the same field
 * with the same op (e.g. `{status: 'cancelled'}` AND `{status: 'shipped'}`),
@@ -1408,10 +1696,10 @@ function mergeSorters(forceSorters, userSorters) {
 * and `!!p ≡ p` is a semantic identity, so the server evaluator sees the
 * same AND. Non-colliding merges produce the canonical `$and` shape.
 */
-function mergeFilters(a, b) {
-	if (!a) return b;
-	if (!b) return a;
-	return makeParserSafeAnd([a, b]);
+function mergeFilters(...exprs) {
+	const list = exprs.filter((e) => !!e);
+	if (list.length <= 1) return list[0];
+	return makeParserSafeAnd(list);
 }
 /** Op-set for a field value: primitives are `$eq`, op-bags expose their keys. */
 function getOpsForFieldValue(value) {
@@ -1479,12 +1767,12 @@ function makeParserSafeAnd(children) {
 * Build a Uniquery object from table UI state.
 *
 * Pure function — no framework dependencies.
-* Combines user filters with force filters, merges sorters,
+* Combines user filters (field filters, then residual conditions) with force
+* filters, merges sorters,
 * projects visible columns, and applies pagination.
 */
 function buildTableQuery(opts) {
-	const userFilter = filtersToUniqueryFilter(opts.filters);
-	const filter = mergeFilters(opts.forceFilters, userFilter);
+	const filter = mergeFilters(opts.forceFilters, filtersToUniqueryFilter(opts.filters), ...opts.residualFilters ?? []);
 	const userSorters = opts.ignoreSorters ? [] : opts.sorters;
 	const sorters = opts.forceSorters?.length ? mergeSorters(opts.forceSorters, userSorters) : userSorters;
 	const $sort = {};
@@ -1544,6 +1832,17 @@ function gateOwns(gate, path) {
 	if (gate === "none") return false;
 	return gate.has(path);
 }
+/**
+* Does a URL under `gate` own the residual condition `expr`? Only when it
+* owns every field the condition references — a condition that touches a
+* private field stays private as a whole.
+*
+* @internal Exported for `@atscript/vue-table`.
+*/
+function residualGateOwns(gate, expr) {
+	const fields = filterExprFields(expr);
+	return fields.length > 0 && fields.every((path) => gateOwns(gate, path));
+}
 function pickFilterPaths(filters, gate) {
 	const out = {};
 	for (const path in filters) if (gateOwns(gate, path)) out[path] = filters[path];
@@ -1570,6 +1869,7 @@ function stateToUrlQueryString(state, defaults) {
 		visibleColumnPaths: [],
 		sorters: sortersGate === "all" ? state.sorters : state.sorters.filter((s) => gateOwns(sortersGate, s.field)),
 		filters,
+		residualFilters: defaults.sync?.residual === false || !state.residualFilters?.length ? void 0 : state.residualFilters.filter((expr) => residualGateOwns(filtersGate, expr)),
 		search: searchOff ? void 0 : state.searchTerm || void 0
 	});
 	if (!searchOff && state.searchTerm && state.ignoreSorters !== void 0 && state.ignoreSorters !== (defaults.defaultIgnoreSorters ?? false)) query.controls.$relevance = state.ignoreSorters ? 1 : 0;
@@ -1592,8 +1892,25 @@ const CONSUMED_CONTROLS = new Set([
 	"$skip",
 	URL_SNAPSHOT_KEY
 ]);
-/** Characters that can only appear in a uniqu filter key, never in a page flag. */
-const FILTER_OPERATOR_CHAR = /[<>!~]/;
+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).
+*/
+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
@@ -1615,12 +1932,15 @@ 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)
+*   approximated (the parser does not warn — the caller decides). Unless
+*   `sync.residual` is `false`, those whose fields are all known come back
+*   in `residual` instead
 * - unknown controls (e.g. `$weird=42`) → silently ignored
 * - malformed query → `{ filters: {}, sorters: [], searchTerm: "" }`
 *
@@ -1648,30 +1968,35 @@ 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 unsupported = [];
-	const filters = filtersGate === "none" ? {} : uniqueryFilterToFieldFilters(parsed.filter, filterKnown, (issue) => unsupported.push(issue));
+	const decomposed = filtersGate === "none" ? null : decomposeUniqueryFilter(parsed.filter, {
+		knownFields: filterKnown,
+		carry: opts.sync?.residual !== false
+	});
+	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;
@@ -1680,7 +2005,24 @@ function urlQueryStringToState(urlString, opts = {}) {
 		sorters,
 		searchTerm: !searchOff && typeof $search === "string" ? $search : ""
 	};
-	if (unsupported.length > 0) out.unsupported = 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;
@@ -2265,15 +2607,19 @@ exports.conditionsForType = conditionsForType;
 exports.csvCell = csvCell;
 exports.dateShortcuts = dateShortcuts;
 exports.debounce = debounce;
+exports.decomposeUniqueryFilter = decomposeUniqueryFilter;
 exports.defaultCondition = defaultCondition;
 exports.derivePresetAspects = derivePresetAspects;
 exports.deserializeDraft = deserializeDraft;
 exports.draftMatchesPreset = draftMatchesPreset;
 exports.escapeRegex = escapeRegex;
 exports.filledFilterCount = filledFilterCount;
+exports.filterExprFields = filterExprFields;
+exports.filterExprKey = filterExprKey;
 exports.filterTokenLabel = filterTokenLabel;
 exports.filtersToUniqueryFilter = filtersToUniqueryFilter;
 exports.formatFilterCondition = formatFilterCondition;
+exports.formatFilterExpr = formatFilterExpr;
 exports.fromWireSnapshot = fromWireSnapshot;
 exports.gateOwns = gateOwns;
 exports.hasSecondValue = hasSecondValue;
@@ -2289,15 +2635,20 @@ exports.mergeDisplayColumns = mergeDisplayColumns;
 exports.mergeFilters = mergeFilters;
 exports.mergeSorters = mergeSorters;
 exports.normaliseSystemPresetId = normaliseSystemPresetId;
+exports.normalizeResidualFilters = normalizeResidualFilters;
 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;