@atscript/ui-table 0.1.139 → 0.1.141

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { isLogicalKey } from "@uniqu/core";
+import { isLogicalKey, walkFilter } from "@uniqu/core";
+import { buildUrl } from "@uniqu/url/builder";
 import { ClientError } from "@atscript/db-client";
 import { getDefaultClientFactory, str } from "@atscript/ui";
-import { buildUrl } from "@uniqu/url/builder";
 import { parseUrl } from "@uniqu/url";
 //#region src/filters/filter-conditions.ts
 /** Conditions that operate purely on nullability — value is ignored. */
@@ -508,8 +508,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;
@@ -519,8 +527,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,
@@ -698,6 +707,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))) {
@@ -741,30 +751,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 = {
@@ -782,21 +789,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 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 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 walkFilter(expr, visitor)?.s ?? "";
+	} catch {
+		return JSON.stringify(expr) ?? "";
+	}
 }
 //#endregion
 //#region src/filters/date-shortcuts.ts
@@ -1001,6 +1157,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
@@ -1393,8 +1680,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'}`),
@@ -1407,10 +1695,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) {
@@ -1478,12 +1766,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 = {};
@@ -1543,6 +1831,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];
@@ -1569,6 +1868,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;
@@ -1591,8 +1891,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
@@ -1614,12 +1931,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: "" }`
 *
@@ -1647,30 +1967,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;
@@ -1679,7 +2004,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;
@@ -2231,4 +2573,4 @@ function sortRowsLocally(rows, sorters, getValue = (row, field) => row[field]) {
 	});
 }
 //#endregion
-export { APP_CONF_PREFIX, AppPrefsClient, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DEV, DRAFT_PERSISTED_ASPECTS, ExportAbortError, MAX_DEFAULT_COLUMN_WIDTH_PX, NULL_OPS, PRESET_ASPECTS, PresetsClient, PresetsHttpError, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, URL_SNAPSHOT_KEY, USER_CONF_PREFIX, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnDefaultCondition, columnFilterConditions, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseColumnFilterInput, 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 };
+export { APP_CONF_PREFIX, AppPrefsClient, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DEV, DRAFT_PERSISTED_ASPECTS, ExportAbortError, MAX_DEFAULT_COLUMN_WIDTH_PX, NULL_OPS, PRESET_ASPECTS, PresetsClient, PresetsHttpError, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, URL_SNAPSHOT_KEY, USER_CONF_PREFIX, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnDefaultCondition, columnFilterConditions, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, decomposeUniqueryFilter, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterExprFields, filterExprKey, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, formatFilterExpr, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, normalizeResidualFilters, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, prunePresetSnapshot, pruneResidualFilters, reconcileColumnWidthDefaults, reorderColumnNames, residualGateOwns, resolveAspectGate, resolveExportValue, resolveSystemPresets, restoreDroppedEntries, 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.139",
+  "version": "0.1.141",
   "description": "Framework-agnostic filter model, filter-to-Uniquery conversion, and preset serialization for atscript tables",
   "keywords": [
     "atscript",
@@ -42,18 +42,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@atscript/ui": "0.1.139"
+    "@atscript/ui": "0.1.141"
   },
   "devDependencies": {
-    "@atscript/db-client": "^0.1.132",
-    "@uniqu/core": "^0.1.9",
-    "@uniqu/url": "^0.1.9",
+    "@atscript/db-client": "^0.1.133",
+    "@uniqu/core": "^0.1.10",
+    "@uniqu/url": "^0.1.10",
     "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.14"
   },
   "peerDependencies": {
-    "@atscript/db-client": "^0.1.132",
-    "@uniqu/core": "^0.1.9",
-    "@uniqu/url": "^0.1.9"
+    "@atscript/db-client": "^0.1.133",
+    "@uniqu/core": "^0.1.10",
+    "@uniqu/url": "^0.1.10"
   },
   "scripts": {
     "build": "vp pack",