@atscript/ui-table 0.1.139 → 0.1.140

package/dist/index.d.mts

@@ -175,6 +175,67 @@ interface UnsupportedFilter {
   /** Field paths the sub-expression references, in order of appearance. */
   fields: string[];
 }
+/**
+ * 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`.
+ */
+declare function filterExprFields(expr: unknown): string[];
+/** Options for {@link decomposeUniqueryFilter}. @since 0.1.140 */
+interface DecomposeUniqueryFilterOptions {
+  /**
+   * Field paths the table knows. Pieces on fields outside it are ignored
+   * silently; a piece mixing known and unknown fields is reported, never
+   * carried. Omit to accept every field.
+   */
+  knownFields?: Iterable<string>;
+  /**
+   * Keep left-out pieces whose fields are all known as `residual` instead of
+   * reporting them. Default `false` — the 0.1.139 split. See
+   * [Custom filter conditions](https://ui.atscript.dev/tables/filtering#custom-filter-conditions).
+   */
+  carry?: boolean;
+}
+/** Result of {@link decomposeUniqueryFilter}. @since 0.1.140 */
+interface DecomposedUniqueryFilter {
+  /** The part field filters express exactly. */
+  filters: FieldFilters;
+  /** Carried pieces — AND-ed conditions, deduped, canonical order. `[]` unless `carry` is on. */
+  residual: FilterExpr[];
+  /** Pieces left out and lost — the result is broader by exactly these. */
+  unsupported: UnsupportedFilter[];
+}
+/**
+ * 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
+ */
+declare function decomposeUniqueryFilter(expr: FilterExpr | undefined, opts?: DecomposeUniqueryFilterOptions): DecomposedUniqueryFilter;
+/**
+ * Canonical identity of a filter expression — its `@uniqu/url` spelling.
+ * Two expressions with the same key select the same rows.
+ *
+ * @since 0.1.140
+ */
+declare function filterExprKey(expr: FilterExpr): string;
+/**
+ * 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`.
+ */
+declare function normalizeResidualFilters(exprs: readonly FilterExpr[]): FilterExpr[];
 /**
  * Convert a Uniquery `FilterExpr` back into the UI's `FieldFilters` shape.
  *
@@ -189,7 +250,8 @@ interface UnsupportedFilter {
  * - 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 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
@@ -199,6 +261,20 @@ interface UnsupportedFilter {
  */
 declare function uniqueryFilterToFieldFilters(expr: FilterExpr | undefined, knownFields?: Iterable<string> | Set<string>, onUnsupportedFilter?: (issue: UnsupportedFilter) => void): FieldFilters;
 //#endregion
+//#region src/filters/format-filter-expr.d.ts
+/**
+ * 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
+ */
+declare function formatFilterExpr(expr: FilterExpr, labelOf?: (path: string) => string | undefined): string;
+//#endregion
 //#region src/filters/date-shortcuts.d.ts
 /** A date shortcut produces a label and a [start, end] ISO date range. */
 interface DateShortcut {
@@ -694,6 +770,12 @@ interface BuildTableQueryOptions {
   ignoreSorters?: boolean;
   /** User-configured field filters. */
   filters: FieldFilters;
+  /**
+   * Residual filter conditions — AND-ed conjuncts the field-filter model
+   * cannot hold (a cross-field `$or`, a second range on one field, …). AND'd
+   * after `filters`. Since 0.1.140.
+   */
+  residualFilters?: FilterExpr[];
   /** Always-applied Uniquery filter (AND'd with user filters). */
   forceFilters?: FilterExpr;
   /** Full-text search term. */
@@ -712,7 +794,8 @@ interface BuildTableQueryOptions {
  * 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.
  */
 declare function buildTableQuery(opts: BuildTableQueryOptions): Uniquery;
@@ -728,8 +811,9 @@ declare function mergeSorters(forceSorters: SortControl[], userSorters: SortCont
 //#endregion
 //#region src/query/merge-filters.d.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'}`),
@@ -742,12 +826,17 @@ declare function mergeSorters(forceSorters: SortControl[], userSorters: SortCont
  * and `!!p ≡ p` is a semantic identity, so the server evaluator sees the
  * same AND. Non-colliding merges produce the canonical `$and` shape.
  */
-declare function mergeFilters(a: FilterExpr | undefined, b: FilterExpr | undefined): FilterExpr | undefined;
+declare function mergeFilters(...exprs: (FilterExpr | undefined)[]): FilterExpr | undefined;
 //#endregion
 //#region src/query/url-query.d.ts
 /** State subset that round-trips through the URL bridge. */
 interface UrlQueryStateLike {
   filters: FieldFilters;
+  /**
+   * Residual filter conditions, AND-ed after `filters`. Only the ones the
+   * filter gate owns are written (see {@link residualGateOwns}). Since 0.1.140.
+   */
+  residualFilters?: FilterExpr[];
   sorters: SortControl[];
   /** 1-based page number. `1` is the default and is omitted from the URL. */
   page?: number;
@@ -788,11 +877,17 @@ interface UrlQueryStateSnapshot {
    */
   snapshot?: true;
   /**
-   * Pieces of the URL's filter that `filters` leaves out because field filters
-   * cannot express them — see `uniqueryFilterToFieldFilters`. Omitted when
-   * the filter converted exactly. Since 0.1.139.
+   * Pieces of the URL's filter that are left out because field filters
+   * cannot express them — see `uniqueryFilterToFieldFilters`. Since 0.1.140
+   * only the pieces NOT carried in `residual`. Omitted when none. Since 0.1.139.
    */
   unsupported?: UnsupportedFilter[];
+  /**
+   * Filter pieces field filters cannot express, carried as residual
+   * conditions (see `decomposeUniqueryFilter`). Omitted when there are none
+   * or `sync.residual` is `false`. Since 0.1.140.
+   */
+  residual?: FilterExpr[];
   /**
    * Raw record offset from `$skip` (omitted when no `$skip` in URL). The
    * decoder does NOT compute a page index — that requires `itemsPerPage`,
@@ -836,6 +931,15 @@ interface UrlQuerySync {
    * Since 0.1.139.
    */
   snapshot?: boolean;
+  /**
+   * Whether filter pieces the field-filter model cannot hold travel as
+   * residual conditions. Default `true`: the encoder writes
+   * `UrlQueryStateLike.residualFilters` and the decoder returns them as
+   * `residual`. `false`: neither — the 0.1.139 behaviour, where such
+   * pieces are left out and reported. Inert when `filters` is off.
+   * Since 0.1.140.
+   */
+  residual?: boolean;
 }
 interface UrlQueryDefaults {
   /** Consumer's `:limit` prop. Used to omit `$limit` from the URL when state matches it. */
@@ -872,6 +976,14 @@ declare function resolveAspectGate(value: boolean | string[] | undefined): Aspec
  * @since 0.1.137
  */
 declare function gateOwns(gate: AspectGate, path: string): boolean;
+/**
+ * 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`.
+ */
+declare function residualGateOwns(gate: AspectGate, expr: FilterExpr): boolean;
 /**
  * Serialize the table state subset into a URL query string.
  *
@@ -917,7 +1029,9 @@ interface UrlQueryParseOptions {
  * - unknown fields (not in `knownFields`) → 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)
+ *   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: "" }`
  *
@@ -1012,6 +1126,13 @@ interface TableStateData {
   filterFields: string[];
   /** Active field filters. */
   filters: FieldFilters;
+  /**
+   * Residual filter conditions — AND-ed Uniquery conjuncts the field-filter
+   * model cannot hold (a cross-field `$or`, a second range on one field, …),
+   * applied after `filters`. Restored from URLs, shown as "custom filter"
+   * chips. Since 0.1.140.
+   */
+  residualFilters: FilterExpr[];
   /** Active sorters. */
   sorters: SortControl[];
   /**
@@ -1132,8 +1253,18 @@ interface TableStateMethods {
   loadingAt(absIdx: number): boolean;
   /** Returns the last error attached to the block covering `absIdx`, or null. */
   errorAt(absIdx: number): Error | null;
-  /** Clear all applied filters. Does not touch `filterFields`. */
+  /**
+   * Clear all applied filters — field filters and residual conditions. Does
+   * not touch `filterFields`.
+   */
   resetFilters(): void;
+  /**
+   * Replace the residual filter conditions (AND-ed Uniquery conjuncts).
+   * Empty expressions and duplicates are dropped. Since 0.1.140.
+   */
+  setResidualFilters(exprs: FilterExpr[]): void;
+  /** Remove the residual condition at `index`. Since 0.1.140. */
+  removeResidualFilter(index: number): void;
   /** Open the config dialog (optionally to a specific tab). */
   showConfigDialog(tab?: ConfigTab): void;
   /** Append a field to the displayed filter fields (deduped). */
@@ -1430,4 +1561,4 @@ declare function sortRowsLocally<T extends Record<string, unknown>>(rows: T[], s
 //#region src/utils/dev.d.ts
 declare const DEV: boolean;
 //#endregion
-export { APP_CONF_PREFIX, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, type CsvOptions, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DEV, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DisplayColumnDef, type DraftPersistedAspect, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, type FilterableColumn, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, URL_SNAPSHOT_KEY, USER_CONF_PREFIX, type UnsupportedFilter, type UnsupportedFilterReason, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, 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, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, type CsvOptions, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DEV, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DecomposeUniqueryFilterOptions, type DecomposedUniqueryFilter, type DisplayColumnDef, type DraftPersistedAspect, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, type FilterableColumn, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, URL_SNAPSHOT_KEY, USER_CONF_PREFIX, type UnsupportedFilter, type UnsupportedFilterReason, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, 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, reconcileColumnWidthDefaults, reorderColumnNames, residualGateOwns, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };

package/dist/index.mjs

@@ -1,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;
@@ -520,7 +528,7 @@ function fieldsOf(expr, out = []) {
 	return out;
 }
 function unsupported(reason, expr) {
-	const fields = fieldsOf(expr);
+	const fields = fieldsOf(expr, []);
 	return {
 		reason: fields.length > 1 ? "cross-field" : reason,
 		expr,
@@ -698,6 +706,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 +750,26 @@ 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:
+* 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`.
 *
-* - `$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.
-*
-* 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: []
+	};
+	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 = {
@@ -784,19 +789,158 @@ function uniqueryFilterToFieldFilters(expr, knownFields, onUnsupportedFilter = w
 	const positives = /* @__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);
+		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;
+		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 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`.
+*
+* 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, 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
@@ -1393,8 +1537,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 +1552,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 +1623,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 +1688,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 +1725,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 +1748,11 @@ 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 = /[<>!~]/;
+/**
+* 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
@@ -1619,7 +1779,9 @@ function urlQueryConsumesKey(key) {
 * - unknown fields (not in `knownFields`) → 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)
+*   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: "" }`
 *
@@ -1654,8 +1816,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 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 = [];
 	if (sortersGate !== "none") {
 		const $sort = parsed.controls?.$sort;
@@ -1679,7 +1844,8 @@ function urlQueryStringToState(urlString, opts = {}) {
 		sorters,
 		searchTerm: !searchOff && typeof $search === "string" ? $search : ""
 	};
-	if (unsupported.length > 0) out.unsupported = unsupported;
+	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;
@@ -2231,4 +2397,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, reconcileColumnWidthDefaults, reorderColumnNames, residualGateOwns, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };