@atscript/ui-table 0.1.138 → 0.1.140

package/dist/index.cjs

@@ -1,7 +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. */
@@ -135,6 +136,40 @@ function columnFilterType(columnType) {
 		default: return "text";
 	}
 }
+const EXISTENCE_CONDITIONS = ["null", "notNull"];
+const NO_CONDITIONS = [];
+/**
+* Filter conditions a column offers — the one answer every filter UI (column
+* menu, filter dialog, filter bar, config dialog) reads.
+*
+* - Value-filterable (`filterable: true`) → {@link conditionsForType} for its
+*   display type.
+* - Existence-only (`filterable: false`, `filterOps` includes `$exists` — a
+*   JSON-stored column) → `null` / `notNull`: whether a value is present,
+*   never what it is.
+* - Otherwise → `[]`: the column takes no filter.
+*
+* `null` / `notNull` are dropped for non-nullable columns, so an existence-only
+* column that is never empty offers nothing.
+*
+* @since 0.1.139
+*/
+function columnFilterConditions(column) {
+	if (column.filterable) return conditionsForType(columnFilterType(column.type), column.nullable);
+	if (column.nullable && column.filterOps?.includes("$exists")) return EXISTENCE_CONDITIONS;
+	return NO_CONDITIONS;
+}
+/**
+* Whether a column takes any filter at all — value comparisons or the
+* existence-only `null` / `notNull` pair. Use it (not
+* `column.filterable`, which is value comparison only) to decide whether to
+* show a column in a filter UI.
+*
+* @since 0.1.139
+*/
+function isColumnFilterable(column) {
+	return columnFilterConditions(column).length > 0;
+}
 //#endregion
 //#region src/filters/escape-regex.ts
 /** Escape special regex characters in user input for safe embedding in $regex. */
@@ -176,6 +211,18 @@ function defaultCondition(columnType) {
 		default: return "eq";
 	}
 }
+/**
+* The condition a column's filter input starts with: its type's
+* {@link defaultCondition} when the column offers it, otherwise the first
+* condition it does offer (`null` on an existence-only column).
+*
+* @since 0.1.139
+*/
+function columnDefaultCondition(column) {
+	const type = defaultCondition(columnFilterType(column.type));
+	const offered = columnFilterConditions(column);
+	return offered.length === 0 || offered.includes(type) ? type : offered[0];
+}
 /** Prefix operators in match order (longest first). */
 const PREFIX_OPS = [
 	["!=", "ne"],
@@ -208,12 +255,26 @@ const PREFIX_OPS = [
 *   number/date/boolean → eq
 *
 * Returns undefined for empty/invalid input or if the parsed operator
-* is not available for the column type.
+* is not available for the column type. To honour what a specific column
+* offers (an existence-only column takes only `<empty>` / `!<empty>`), use
+* {@link parseColumnFilterInput}.
 */
 function parseFilterInput(text, columnType, nullable = true) {
+	return parseInput(text, columnType, conditionsForType(columnType, nullable));
+}
+/**
+* {@link parseFilterInput} for a column: the type comes from the column and
+* the accepted operators are {@link columnFilterConditions} — the ones the
+* column's filter UI offers.
+*
+* @since 0.1.139
+*/
+function parseColumnFilterInput(text, column) {
+	return parseInput(text, columnFilterType(column.type), columnFilterConditions(column));
+}
+function parseInput(text, columnType, available) {
 	const trimmed = text.trim();
 	if (trimmed === "") return void 0;
-	const available = conditionsForType(columnType, nullable);
 	const isNumber = columnType === "number";
 	const build = (type, value) => {
 		if (!available.includes(type)) return void 0;
@@ -289,6 +350,10 @@ function formatFilterCondition(condition) {
 //#region src/filters/filters-to-uniquery.ts
 /** Exclusion condition types — AND'd together per field. */
 const EXCLUSION_TYPES = new Set(["ne", "notNull"]);
+/** Whether conditions of `type` are exclusions (AND'd per field) rather than inclusions (OR'd). */
+function isExclusionType(type) {
+	return EXCLUSION_TYPES.has(type);
+}
 /**
 * Convert a single condition to a Uniquery filter expression.
 * Returns a ComparisonNode with the field as key.
@@ -337,7 +402,7 @@ function filtersToUniqueryFilter(fieldFilters) {
 		for (const condition of conditions) {
 			if (!isFilled(condition)) continue;
 			const expr = conditionToExpr(field, condition);
-			if (EXCLUSION_TYPES.has(condition.type)) (exclusions ??= []).push(expr);
+			if (isExclusionType(condition.type)) (exclusions ??= []).push(expr);
 			else (inclusions ??= []).push(expr);
 		}
 		if (inclusions) pushGroup(topGroups, inclusions, "$or");
@@ -348,25 +413,33 @@ function filtersToUniqueryFilter(fieldFilters) {
 	return { $and: topGroups };
 }
 //#endregion
+//#region src/utils/dev.ts
+/**
+* `true` outside a production build — the gate for authoring-time warnings, so
+* their strings and checks cost a shipped app nothing.
+*
+* Read from `process.env.NODE_ENV` rather than `import.meta.env`: bundlers
+* replace this expression with a literal in both the ESM and the CJS output,
+* while `import.meta` only exists in the former. Where neither a bundler nor a
+* `process` shim is present the read throws — warnings stay on, which is the
+* safe side of the trade.
+*/
+function detectDev() {
+	try {
+		return process.env.NODE_ENV !== "production";
+	} catch {
+		return true;
+	}
+}
+const DEV = detectDev();
+//#endregion
 //#region src/filters/uniquery-to-filters.ts
-const SUPPORTED_TYPES = new Set([
-	"eq",
-	"ne",
-	"gt",
-	"gte",
-	"lt",
-	"lte",
-	"contains",
-	"starts",
-	"ends",
-	"bw",
-	"null",
-	"notNull",
-	"regex"
-]);
 function isPrimitive(v) {
 	return typeof v === "string" || typeof v === "number" || typeof v === "boolean";
 }
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof RegExp) && !(v instanceof Date);
+}
 const REGEX_LITERAL = /^\/(.*)\/([a-z]*)$/s;
 const STARTS_ANCHOR = /^\^(.+)$/s;
 const ENDS_ANCHOR = /^(.+)\$$/s;
@@ -377,6 +450,7 @@ const ENDS_ANCHOR = /^(.+)\$$/s;
 * `regex` condition.
 */
 function regexToCondition(raw) {
+	if (raw instanceof RegExp) raw = raw.toString();
 	if (typeof raw !== "string") return null;
 	const m = REGEX_LITERAL.exec(raw);
 	if (!m) return {
@@ -405,109 +479,469 @@ function regexToCondition(raw) {
 		value: [raw]
 	};
 }
-function pushIfPrimitive(out, type, v) {
-	if (!isPrimitive(v)) return;
-	out.push({
-		type,
+const nullCond = () => ({
+	type: "null",
+	value: []
+});
+const notNullCond = () => ({
+	type: "notNull",
+	value: []
+});
+/** Positive condition for one `$eq` / `$in` value — `null` means "is empty". */
+function memberCondition(v) {
+	if (v === null) return nullCond();
+	return isPrimitive(v) ? {
+		type: "eq",
 		value: [v]
-	});
+	} : null;
 }
+/** Negative condition for one `$ne` / `$nin` value — `null` means "is not empty". */
+function nonMemberCondition(v) {
+	if (v === null) return notNullCond();
+	return isPrimitive(v) ? {
+		type: "ne",
+		value: [v]
+	} : null;
+}
+const RANGE_OPS = {
+	$gt: "gt",
+	$gte: "gte",
+	$lt: "lt",
+	$lte: "lte"
+};
 /**
-* Decode a per-field operator object (e.g. `{ $gt: 5, $lte: 10 }`) into one or
-* more `FilterCondition`s. Unknown operators are silently dropped.
+* Field paths a Uniquery filter expression references, deduped, in order of
+* appearance (logical operators are walked, operator keys skipped).
 *
-* `$gte` + `$lte` on the same field collapse into a single `bw` condition,
-* matching the encoder's behaviour.
+* @internal Exported for `@atscript/vue-table`.
 */
-function decodeFieldOps(ops) {
-	const out = [];
-	const hasGte = "$gte" in ops && isPrimitive(ops.$gte);
-	const hasLte = "$lte" in ops && isPrimitive(ops.$lte);
-	if (hasGte && hasLte) out.push({
-		type: "bw",
-		value: [ops.$gte, ops.$lte]
+function filterExprFields(expr) {
+	return fieldsOf(expr, []);
+}
+function fieldsOf(expr, out) {
+	if (Array.isArray(expr)) {
+		for (const child of expr) fieldsOf(child, out);
+		return out;
+	}
+	if (!isPlainObject(expr)) return out;
+	for (const key in expr) if (key.startsWith("$")) fieldsOf(expr[key], out);
+	else if (!out.includes(key)) out.push(key);
+	return out;
+}
+function unsupported(reason, expr) {
+	const fields = fieldsOf(expr, []);
+	return {
+		reason: fields.length > 1 ? "cross-field" : reason,
+		expr,
+		fields
+	};
+}
+const isNegative = (term) => isExclusionType(term.conds[0].type);
+/**
+* Add decoded conditions as terms: negatives one term each (they AND), a
+* positive list as one group (it ORs). Conditions share their polarity.
+*/
+function addTerms(out, field, conds, expr) {
+	if (conds.length === 0) return;
+	if (isExclusionType(conds[0].type)) for (const cond of conds) out.terms.push({
+		field,
+		conds: [cond],
+		expr
 	});
-	else {
-		if (hasGte) pushIfPrimitive(out, "gte", ops.$gte);
-		if (hasLte) pushIfPrimitive(out, "lte", ops.$lte);
-	}
-	if ("$eq" in ops) pushIfPrimitive(out, "eq", ops.$eq);
-	if ("$ne" in ops) pushIfPrimitive(out, "ne", ops.$ne);
-	if ("$gt" in ops) pushIfPrimitive(out, "gt", ops.$gt);
-	if ("$lt" in ops) pushIfPrimitive(out, "lt", ops.$lt);
-	if ("$exists" in ops) {
-		if (ops.$exists === false) out.push({
-			type: "null",
-			value: []
-		});
-		else if (ops.$exists === true) out.push({
-			type: "notNull",
-			value: []
-		});
+	else out.terms.push({
+		field,
+		conds,
+		expr
+	});
+}
+/**
+* `a>=x` AND `a<=y` is the model's `bw`, whether both halves sit in one
+* operator object (the encoder's shape) or in two AND-ed pieces. Folds `cond`
+* into an earlier lone opposite half on `field`; `false` when there is none.
+*/
+function pairRange(out, field, cond) {
+	const opposite = cond.type === "gte" ? "lte" : cond.type === "lte" ? "gte" : null;
+	if (!opposite) return false;
+	const i = out.terms.findIndex((t) => t.field === field && t.conds.length === 1 && t.conds[0].type === opposite);
+	if (i < 0) return false;
+	const other = out.terms[i].conds[0];
+	const [lo, hi] = cond.type === "gte" ? [cond.value[0], other.value[0]] : [other.value[0], cond.value[0]];
+	out.terms[i] = {
+		field,
+		conds: [{
+			type: "bw",
+			value: [lo, hi]
+		}],
+		expr: { [field]: {
+			$gte: lo,
+			$lte: hi
+		} }
+	};
+	return true;
+}
+/**
+* Decode one field entry (`field: value`) into terms. An operator object is an
+* implicit AND of its operators — each becomes its own term.
+*/
+function collectField(field, value, out) {
+	const whole = { [field]: value };
+	if (value === null || value === void 0) return addTerms(out, field, [nullCond()], whole);
+	if (isPrimitive(value)) return addTerms(out, field, [{
+		type: "eq",
+		value: [value]
+	}], whole);
+	if (value instanceof RegExp) return addTerms(out, field, [regexToCondition(value)], whole);
+	if (!isPlainObject(value)) {
+		out.issues.push(unsupported("operator", whole));
+		return;
 	}
-	if ("$regex" in ops) {
-		const cond = regexToCondition(ops.$regex);
-		if (cond) out.push(cond);
+	for (const op in value) {
+		const v = value[op];
+		if (v === void 0) continue;
+		const expr = { [field]: { [op]: v } };
+		const conds = decodeOperator(op, v);
+		if (!conds) out.issues.push(unsupported("operator", expr));
+		else if (conds.length !== 1 || !pairRange(out, field, conds[0])) addTerms(out, field, conds, expr);
 	}
-	return out;
 }
+const one = (cond) => cond ? [cond] : null;
 /**
-* Walk a leaf `ComparisonNode` (one or more field=value entries) into the
-* shared `FieldFilters` accumulator. Drops unknown fields and operators.
+* One operator of a field's operator object, as conditions of one polarity
+* (see {@link addTerms}). `null` means no condition type expresses the
+* operator / operand.
 */
-function walkLeaf(node, acc, knownFields) {
-	for (const field in node) {
-		if (field.startsWith("$")) continue;
-		if (knownFields && !knownFields.has(field)) continue;
-		const value = node[field];
-		let conditions;
-		if (value === null || value === void 0) conditions = [{
-			type: "null",
-			value: []
-		}];
-		else if (isPrimitive(value)) conditions = [{
-			type: "eq",
-			value: [value]
-		}];
-		else if (typeof value === "object" && !Array.isArray(value)) conditions = decodeFieldOps(value);
-		else continue;
-		if (conditions.length === 0) continue;
-		const filtered = conditions.filter((c) => SUPPORTED_TYPES.has(c.type));
-		if (filtered.length === 0) continue;
-		if (acc[field]) acc[field] = [...acc[field], ...filtered];
-		else acc[field] = filtered;
-	}
-}
-function walkExpr(expr, acc, knownFields) {
-	if ("$and" in expr && expr.$and) {
-		for (const child of expr.$and) walkExpr(child, acc, knownFields);
+function decodeOperator(op, v) {
+	if (op in RANGE_OPS) return one(isPrimitive(v) ? {
+		type: RANGE_OPS[op],
+		value: [v]
+	} : null);
+	switch (op) {
+		case "$eq": return one(memberCondition(v));
+		case "$ne": return one(nonMemberCondition(v));
+		case "$regex": return one(regexToCondition(v));
+		case "$exists":
+			if (v === false) return one(nullCond());
+			return v === true ? one(notNullCond()) : null;
+		case "$in": {
+			const conds = Array.isArray(v) ? v.map(memberCondition) : [];
+			return conds.length > 0 && conds.every(Boolean) ? conds : null;
+		}
+		case "$nin": {
+			if (!Array.isArray(v)) return null;
+			const conds = v.map(nonMemberCondition);
+			return conds.every(Boolean) ? conds : null;
+		}
+		default: return null;
+	}
+}
+/**
+* Decode an `$or` branch / `$not` operand on its own. Usable only when it
+* converts fully and stays on one field; `null` when it constrains nothing.
+* A branch that spans fields comes back with a placeholder reason —
+* {@link unsupported} names it `"cross-field"` from the fields it sees.
+*/
+function classifyBranch(expr) {
+	const sub = {
+		terms: [],
+		issues: []
+	};
+	collect(expr, sub);
+	if (sub.issues.length > 0) return { reason: sub.issues[0].reason };
+	if (sub.terms.length === 0) return null;
+	const field = sub.terms[0].field;
+	if (sub.terms.some((t) => t.field !== field)) return { reason: "operator" };
+	return {
+		field,
+		terms: sub.terms
+	};
+}
+/**
+* `$or` fits the model only as a same-field OR of positive branches. Each
+* branch must decode to exactly one positive group; the groups merge.
+*/
+function collectOr(branches, out) {
+	const expr = { $or: branches };
+	if (!Array.isArray(branches) || branches.length === 0) {
+		out.issues.push(unsupported("operator", expr));
 		return;
 	}
-	if ("$or" in expr && expr.$or) {
-		for (const child of expr.$or) walkExpr(child, acc, knownFields);
+	if (branches.length === 1) return collect(branches[0], out);
+	const groups = [];
+	let reason;
+	for (const branch of branches) {
+		const b = classifyBranch(branch);
+		if (b === null) return;
+		if ("reason" in b) reason ??= b.reason;
+		else if (b.terms.length > 1) reason ??= "conjunction";
+		else if (isNegative(b.terms[0])) reason ??= "negation";
+		else groups.push(b.terms[0]);
+	}
+	const field = groups[0]?.field;
+	if (reason !== void 0 || groups.some((t) => t.field !== field)) {
+		out.issues.push(unsupported(reason ?? "operator", expr));
+		return;
+	}
+	out.terms.push({
+		field,
+		conds: groups.flatMap((t) => t.conds),
+		expr
+	});
+}
+const INVERSE = {
+	eq: "ne",
+	ne: "eq",
+	null: "notNull",
+	notNull: "null"
+};
+function invert(cond) {
+	const type = INVERSE[cond.type];
+	return type ? {
+		type,
+		value: [...cond.value]
+	} : null;
+}
+/**
+* `$not` fits when it inverts equality / emptiness on one field — De Morgan
+* turns NOT(a=1 OR a=2) into a≠1 AND a≠2 (negatives), and NOT(a≠1 AND a≠2)
+* back into a=1 OR a=2 (one positive group). A positive group AND'd with
+* 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))) {
+		const inverted = b.terms.flatMap((t) => t.conds).map(invert);
+		if (inverted.every(Boolean)) return addTerms(out, b.field, inverted, expr);
+	}
+	out.issues.push(unsupported("negation", expr));
+}
+function collectAnd(children, out) {
+	if (Array.isArray(children)) for (const child of children) collect(child, out);
+	else out.issues.push(unsupported("operator", { $and: children }));
+}
+const LOGICAL = {
+	$and: collectAnd,
+	$or: collectOr,
+	$not: collectNot
+};
+/**
+* Split an expression into AND-ed terms. Every member of a node is an implicit
+* AND, in key order — comparison fields may sit next to `$and` / `$or` /
+* `$not` (Mongo semantics), and none of them is skipped.
+*/
+function collect(expr, out) {
+	if (!isPlainObject(expr)) {
+		out.issues.push(unsupported("operator", expr));
 		return;
 	}
-	if ("$not" in expr && expr.$not) return;
-	walkLeaf(expr, acc, knownFields);
+	for (const key in expr) {
+		const value = expr[key];
+		if (!key.startsWith("$")) collectField(key, value, out);
+		else if (value === void 0) continue;
+		else if ((0, _uniqu_core.isLogicalKey)(key)) LOGICAL[key](value, out);
+		else out.issues.push(unsupported("operator", { [key]: value }));
+	}
+}
+function sameConds(a, b) {
+	return a.length === b.length && a.every((c, i) => c.type === b[i].type && c.value.length === b[i].value.length && c.value.every((v, j) => v === b[i].value[j]));
+}
+function warnUnsupported(issue) {
+	if (!DEV) return;
+	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.`);
+}
+/**
+* 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`.
+*
+* Never throws, never warns — the caller decides how to report.
+*
+* @since 0.1.140
+*/
+function decomposeUniqueryFilter(expr, opts = {}) {
+	const filters = {};
+	const result = {
+		filters,
+		residual: [],
+		unsupported: []
+	};
+	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 = {
+		terms: [],
+		issues: []
+	};
+	try {
+		collect(expr, out);
+	} catch {
+		out.terms = [];
+		out.issues = [{
+			reason: "operator",
+			expr,
+			fields: []
+		}];
+	}
+	const positives = /* @__PURE__ */ new Map();
+	for (const term of out.terms) {
+		if (!isKnown(term.field)) continue;
+		const list = filters[term.field] ??= [];
+		if (isNegative(term)) {
+			list.push(...term.conds);
+			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: [field]
+		});
+	}
+	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);
+		else result.unsupported.push(issue);
+	}
+	result.residual = normalizeResidualFilters(carried);
+	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`. Drops:
-* - conditions on fields not in `knownFields` (when provided)
-* - operators not in the supported `FilterConditionType` union
-* - `$not` branches (no native UI representation; lossy on hand-crafted URLs)
+* 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`.
+*
+* 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.
 *
 * Returns `{}` for an empty/missing expression. Never throws.
 */
-function uniqueryFilterToFieldFilters(expr, knownFields) {
-	const acc = {};
-	if (!expr) return acc;
-	const known = knownFields == null ? null : knownFields instanceof Set ? knownFields : new Set(knownFields);
+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 {
-		walkExpr(expr, acc, known);
-	} catch {}
-	return acc;
+		return (0, _uniqu_core.walkFilter)(expr, visitor)?.s ?? "";
+	} catch {
+		return JSON.stringify(expr) ?? "";
+	}
 }
 //#endregion
 //#region src/filters/date-shortcuts.ts
@@ -1104,8 +1538,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'}`),
@@ -1118,10 +1553,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) {
@@ -1189,12 +1624,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 = {};
@@ -1214,6 +1649,20 @@ function buildTableQuery(opts) {
 }
 //#endregion
 //#region src/query/url-query.ts
+/**
+* The URL control that marks a query string as a complete snapshot of the
+* table's filters and sorters. Restoring a URL that carries it clears every
+* filter and sorter the URL owns before applying its own, so nothing the URL
+* omits survives (empty `$sort` included). A URL without it is an overlay:
+* its filters and sorters are laid over the table's starting ones.
+*
+* The encoder writes it bare (`…&$snapshot`) on every URL; the decoder goes
+* by presence alone, whatever the value. `UrlQuerySync.snapshot: false` turns
+* both off.
+*
+* @since 0.1.139
+*/
+const URL_SNAPSHOT_KEY = "$snapshot";
 function resolveAspectGate(value) {
 	if (value === void 0 || value === true) return "all";
 	if (value === false) return "none";
@@ -1240,6 +1689,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];
@@ -1252,7 +1712,9 @@ function pickFilterPaths(filters, gate) {
 * `$actions`, `forceFilters`, `forceSorters` — those are not user state) and
 * appends `$skip` / `$limit` for pagination.
 *
-* Returns `""` (no leading `?`) for the default view.
+* Stamps {@link URL_SNAPSHOT_KEY} unless `defaults.sync.snapshot` is `false`
+* (or neither filters nor sorters sync), so the default view serializes to
+* `"$snapshot"`; with the marker off it serializes to `""` (no leading `?`).
 */
 function stateToUrlQueryString(state, defaults) {
 	const filtersGate = resolveAspectGate(defaults.sync?.filters);
@@ -1264,6 +1726,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;
@@ -1272,6 +1735,7 @@ function stateToUrlQueryString(state, defaults) {
 		const page = state.page ?? 1;
 		if (page > 1) query.controls.$skip = (page - 1) * itemsPerPage;
 	}
+	if (defaults.sync?.snapshot !== false && (filtersGate !== "none" || sortersGate !== "none")) query.controls[URL_SNAPSHOT_KEY] = "";
 	return (0, _uniqu_url_builder.buildUrl)(query);
 }
 /**
@@ -1282,10 +1746,14 @@ const CONSUMED_CONTROLS = new Set([
 	"$sort",
 	"$search",
 	"$relevance",
-	"$skip"
+	"$skip",
+	URL_SNAPSHOT_KEY
 ]);
-/** Characters that can only appear in a uniqu filter key, never in a page flag. */
-const FILTER_OPERATOR_CHAR = /[<>!~]/;
+/**
+* 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
@@ -1310,7 +1778,11 @@ function urlQueryConsumesKey(key) {
 * Robust by design — schema drift and copy-paste errors must not break the
 * recipient's view:
 * - unknown fields (not in `knownFields`) → silently dropped
-* - unsupported operators → silently dropped
+* - 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
+*   `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: "" }`
 *
@@ -1345,7 +1817,11 @@ function urlQueryStringToState(urlString, opts = {}) {
 		filterKnown = /* @__PURE__ */ new Set();
 		for (const path of filtersGate) if (knownSet.has(path)) filterKnown.add(path);
 	} else filterKnown = filtersGate;
-	const filters = filtersGate === "none" ? {} : uniqueryFilterToFieldFilters(parsed.filter, filterKnown);
+	const decomposed = filtersGate === "none" ? null : decomposeUniqueryFilter(parsed.filter, {
+		knownFields: filterKnown,
+		carry: opts.sync?.residual !== false
+	});
+	const filters = decomposed?.filters ?? {};
 	const sorters = [];
 	if (sortersGate !== "none") {
 		const $sort = parsed.controls?.$sort;
@@ -1369,6 +1845,9 @@ function urlQueryStringToState(urlString, opts = {}) {
 		sorters,
 		searchTerm: !searchOff && typeof $search === "string" ? $search : ""
 	};
+	if (decomposed?.unsupported.length) out.unsupported = decomposed.unsupported;
+	if (decomposed?.residual.length) out.residual = decomposed.residual;
+	if (opts.sync?.snapshot !== false && parsed.controls && "$snapshot" in parsed.controls) out.snapshot = true;
 	if (!searchOff) {
 		const $relevance = parsed.controls?.$relevance;
 		if ($relevance === "1" || $relevance === 1) out.ignoreSorters = true;
@@ -1923,6 +2402,7 @@ 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.DEV = DEV;
 exports.DRAFT_PERSISTED_ASPECTS = DRAFT_PERSISTED_ASPECTS;
 exports.ExportAbortError = ExportAbortError;
 exports.MAX_DEFAULT_COLUMN_WIDTH_PX = MAX_DEFAULT_COLUMN_WIDTH_PX;
@@ -1933,6 +2413,7 @@ exports.PresetsHttpError = PresetsHttpError;
 exports.RESERVED_ID_PREFIXES = RESERVED_ID_PREFIXES;
 exports.STANDARD_PRESET_ID = STANDARD_PRESET_ID;
 exports.SYSTEM_PRESET_PREFIX = SYSTEM_PRESET_PREFIX;
+exports.URL_SNAPSHOT_KEY = URL_SNAPSHOT_KEY;
 exports.USER_CONF_PREFIX = USER_CONF_PREFIX;
 exports.appConfId = appConfId;
 exports.arraysEqual = arraysEqual;
@@ -1941,6 +2422,8 @@ exports.buildTableQuery = buildTableQuery;
 exports.cellAsString = cellAsString;
 exports.clampTopIndex = clampTopIndex;
 exports.collectExportRows = collectExportRows;
+exports.columnDefaultCondition = columnDefaultCondition;
+exports.columnFilterConditions = columnFilterConditions;
 exports.columnFilterType = columnFilterType;
 exports.computeDefaultColumnWidth = computeDefaultColumnWidth;
 exports.conditionLabel = conditionLabel;
@@ -1948,19 +2431,24 @@ 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;
 exports.isAuthError = isAuthError;
+exports.isColumnFilterable = isColumnFilterable;
 exports.isDirtyAgainst = isDirtyAgainst;
 exports.isEmptyDraft = isEmptyDraft;
 exports.isFilled = isFilled;
@@ -1971,11 +2459,14 @@ 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.reconcileColumnWidthDefaults = reconcileColumnWidthDefaults;
 exports.reorderColumnNames = reorderColumnNames;
+exports.residualGateOwns = residualGateOwns;
 exports.resolveAspectGate = resolveAspectGate;
 exports.resolveExportValue = resolveExportValue;
 exports.resolveSystemPresets = resolveSystemPresets;