@salesforce/ui-bundle-template-feature-angular-search 0.0.0-stage → 12.14.0

package/dist/force-app/main/default/uiBundles/feature-angular-search/src/app/features/search/utils/filter-utils.spec.ts

@@ -0,0 +1,335 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+// W-23860670: negative min must clamp to the configured bound.
+import { describe, it, expect } from "vitest";
+import {
+	buildFilter,
+	buildGlobalQueryClause,
+	readSourceParams,
+	writeSourceParams,
+} from "./filter-utils";
+import type { ActiveFilterValue, FilterFieldConfig } from "../types/filter.types";
+
+describe("buildFilter numeric bounds", () => {
+	it("clamps a negative min to the configured bound, and leaves unbounded fields unchanged", () => {
+		const configs: FilterFieldConfig[] = [
+			{ field: "Price", label: "Price", type: "numeric", min: 0 },
+			{ field: "Quantity", label: "Quantity", type: "numeric" },
+		];
+		const filters: ActiveFilterValue[] = [
+			{ field: "Price", label: "Price", type: "numeric", min: "-500" },
+			{ field: "Quantity", label: "Quantity", type: "numeric", min: "-500" },
+		];
+
+		expect(buildFilter(filters, configs)).toEqual({
+			and: [{ Price: { gte: 0 } }, { Quantity: { gte: -500 } }],
+		});
+	});
+
+	it("clamps the max endpoint into the declared bounds too", () => {
+		const configs: FilterFieldConfig[] = [
+			{ field: "Price", label: "Price", type: "numeric", min: 0 },
+		];
+		const filters: ActiveFilterValue[] = [
+			{ field: "Price", label: "Price", type: "numeric", max: "-500" },
+		];
+
+		expect(buildFilter(filters, configs)).toEqual({ Price: { lte: 0 } });
+	});
+});
+
+// W-23935484: LIKE metacharacters in user input must be escaped, not treated as wildcards.
+describe("LIKE pattern escaping", () => {
+	const configs: FilterFieldConfig[] = [{ field: "Name", label: "Name", type: "text" }];
+
+	it("escapes %, _, and \\ in a text filter value", () => {
+		const filters: ActiveFilterValue[] = [
+			{ field: "Name", label: "Name", type: "text", value: "50%_off\\deal" },
+		];
+
+		expect(buildFilter(filters, configs)).toEqual({
+			Name: { like: "%50\\%\\_off\\\\deal%" },
+		});
+	});
+
+	it("leaves ordinary characters in a text filter value untouched", () => {
+		const filters: ActiveFilterValue[] = [
+			{ field: "Name", label: "Name", type: "text", value: "widget" },
+		];
+
+		expect(buildFilter(filters, configs)).toEqual({ Name: { like: "%widget%" } });
+	});
+
+	it("escapes %, _, and \\ in the global query across a single searchable field", () => {
+		expect(buildGlobalQueryClause("50%_off\\deal", ["Name"])).toEqual({
+			Name: { like: "%50\\%\\_off\\\\deal%" },
+		});
+	});
+
+	it("escapes %, _, and \\ in the global query across multiple/nested searchable fields", () => {
+		expect(buildGlobalQueryClause("a_b", ["Name", "Owner.Name"])).toEqual({
+			or: [{ Name: { like: "%a\\_b%" } }, { Owner: { Name: { like: "%a\\_b%" } } }],
+		});
+	});
+});
+
+// A non-numeric or non-finite URL bound must be dropped, never emitted as NaN/Infinity.
+describe("buildFilter numeric guard against invalid bounds", () => {
+	const configs: FilterFieldConfig[] = [{ field: "Amount", label: "Amount", type: "numeric" }];
+
+	it("drops a non-numeric min when there is no valid max, emitting no clause", () => {
+		const filters: ActiveFilterValue[] = [
+			{ field: "Amount", label: "Amount", type: "numeric", min: "abc" },
+		];
+		expect(buildFilter(filters, configs)).toBeUndefined();
+	});
+
+	it("drops a non-numeric min but keeps a valid max", () => {
+		const filters: ActiveFilterValue[] = [
+			{ field: "Amount", label: "Amount", type: "numeric", min: "abc", max: "200" },
+		];
+		expect(buildFilter(filters, configs)).toEqual({ Amount: { lte: 200 } });
+	});
+
+	it("keeps both bounds when min and max are valid numbers", () => {
+		const filters: ActiveFilterValue[] = [
+			{ field: "Amount", label: "Amount", type: "numeric", min: "100", max: "200" },
+		];
+		expect(buildFilter(filters, configs)).toEqual({ Amount: { gte: 100, lte: 200 } });
+	});
+
+	it("keeps a numeric zero bound (a non-empty string is truthy)", () => {
+		const filters: ActiveFilterValue[] = [
+			{ field: "Amount", label: "Amount", type: "numeric", min: "0" },
+		];
+		expect(buildFilter(filters, configs)).toEqual({ Amount: { gte: 0 } });
+	});
+
+	it('drops a non-finite bound like Infinity (Number("1e999"))', () => {
+		const filters: ActiveFilterValue[] = [
+			{ field: "Amount", label: "Amount", type: "numeric", min: "1e999" },
+		];
+		expect(buildFilter(filters, configs)).toBeUndefined();
+	});
+});
+
+describe("buildFilter by type", () => {
+	it("builds eq for picklist, boolean and a single multipicklist value, in for several", () => {
+		const configs: FilterFieldConfig[] = [];
+		const f = (type: ActiveFilterValue["type"], value: string): ActiveFilterValue => ({
+			field: "F",
+			label: "F",
+			type,
+			value,
+		});
+		expect(buildFilter([f("picklist", "A")], configs)).toEqual({ F: { eq: "A" } });
+		expect(buildFilter([f("boolean", "true")], configs)).toEqual({ F: { eq: true } });
+		expect(buildFilter([f("boolean", "false")], configs)).toEqual({ F: { eq: false } });
+		expect(buildFilter([f("multipicklist", "A")], configs)).toEqual({ F: { eq: "A" } });
+		expect(buildFilter([f("multipicklist", "A,B")], configs)).toEqual({ F: { in: ["A", "B"] } });
+	});
+
+	it("builds date and datetime ranges", () => {
+		const configs: FilterFieldConfig[] = [];
+		const range = (type: ActiveFilterValue["type"]): ActiveFilterValue => ({
+			field: "D",
+			label: "D",
+			type,
+			min: "2026-01-01",
+			max: "2026-01-31",
+		});
+		expect(buildFilter([range("daterange")], configs)).toEqual({
+			and: [{ D: { gte: { value: "2026-01-01" } } }, { D: { lte: { value: "2026-01-31" } } }],
+		});
+		expect(buildFilter([range("datetimerange")], configs)).toEqual({
+			and: [
+				{ D: { gte: { value: "2026-01-01T00:00:00.000Z" } } },
+				{ D: { lte: { value: "2026-01-31T23:59:59.999Z" } } },
+			],
+		});
+	});
+});
+
+describe("URL param round-trip", () => {
+	const configs: FilterFieldConfig[] = [{ field: "Name", label: "Name", type: "text" }];
+
+	it("omits sort and page size equal to the defaults", () => {
+		const params = new URLSearchParams();
+		writeSourceParams(params, "acc", [], { field: "Name", direction: "ASC" }, 10, 0, undefined, {
+			sort: { field: "Name", direction: "ASC" },
+			pageSize: 10,
+		});
+		expect(params.toString()).toBe("");
+	});
+
+	it("writes and reads filters, sort and page", () => {
+		const params = new URLSearchParams();
+		writeSourceParams(
+			params,
+			"acc",
+			[{ field: "Name", label: "Name", type: "text", value: "acme" }],
+			{ field: "Name", direction: "DESC" },
+			25,
+			2,
+			"cursor-abc",
+		);
+		const read = readSourceParams(params, "acc", configs);
+		expect(read.filters).toEqual([
+			{ field: "Name", label: "Name", type: "text", value: "acme", min: undefined, max: undefined },
+		]);
+		expect(read.sort).toEqual({ field: "Name", direction: "DESC" });
+		expect(read.pageSize).toBe(25);
+		expect(read.pageIndex).toBe(2);
+		expect(read.afterCursor).toBe("cursor-abc");
+	});
+
+	it("omits the cursor on page 1 and ignores a stray cursor on read", () => {
+		const params = new URLSearchParams();
+		writeSourceParams(params, "acc", [], null, undefined, 0, "cursor-abc");
+		expect(params.has("s.acc.after")).toBe(false);
+
+		params.set("s.acc.after", "stray");
+		expect(readSourceParams(params, "acc", configs).afterCursor).toBeUndefined();
+	});
+
+	it("keeps cursors independent per source", () => {
+		const params = new URLSearchParams();
+		writeSourceParams(params, "a", [], null, undefined, 1, "ca");
+		writeSourceParams(params, "b", [], null, undefined, 2, "cb");
+		expect(readSourceParams(params, "a", configs).afterCursor).toBe("ca");
+		expect(readSourceParams(params, "b", configs).afterCursor).toBe("cb");
+	});
+});
+
+describe("date / datetime comparison operators", () => {
+	const filter = (
+		type: ActiveFilterValue["type"],
+		extra: Partial<ActiveFilterValue>,
+	): ActiveFilterValue => ({ field: "D", label: "D", type, ...extra });
+
+	it("honours an explicit gt / lt operator carried in value", () => {
+		expect(buildFilter([filter("date", { value: "gt", min: "2026-01-05" })], [])).toEqual({
+			D: { gt: { value: "2026-01-05" } },
+		});
+		expect(buildFilter([filter("date", { value: "lt", max: "2026-01-05" })], [])).toEqual({
+			D: { lt: { value: "2026-01-05" } },
+		});
+	});
+
+	it("applies start/end of day for datetime gt / lt", () => {
+		expect(buildFilter([filter("datetime", { value: "gt", min: "2026-01-05" })], [])).toEqual({
+			D: { gt: { value: "2026-01-05T00:00:00.000Z" } },
+		});
+		expect(buildFilter([filter("datetime", { value: "lt", max: "2026-01-05" })], [])).toEqual({
+			D: { lt: { value: "2026-01-05T23:59:59.999Z" } },
+		});
+	});
+
+	it("falls back to gte when min is set and lte otherwise", () => {
+		expect(buildFilter([filter("date", { min: "2026-01-05" })], [])).toEqual({
+			D: { gte: { value: "2026-01-05" } },
+		});
+		expect(buildFilter([filter("datetime", { max: "2026-01-05" })], [])).toEqual({
+			D: { lte: { value: "2026-01-05T23:59:59.999Z" } },
+		});
+	});
+
+	it("ignores an unrecognised operator in value", () => {
+		expect(buildFilter([filter("date", { value: "or", min: "2026-01-05" })], [])).toEqual({
+			D: { gte: { value: "2026-01-05" } },
+		});
+	});
+
+	it("returns no clause without a bound", () => {
+		expect(buildFilter([filter("date", { value: "gt" })], [])).toBeUndefined();
+	});
+
+	it("builds a one-sided daterange from min or max alone", () => {
+		expect(buildFilter([filter("daterange", { min: "2026-01-01" })], [])).toEqual({
+			D: { gte: { value: "2026-01-01" } },
+		});
+		expect(buildFilter([filter("daterange", { max: "2026-01-31" })], [])).toEqual({
+			D: { lte: { value: "2026-01-31" } },
+		});
+	});
+});
+
+describe("readSourceParams untrusted URL values", () => {
+	const cfgs: FilterFieldConfig[] = [
+		{ field: "Created", label: "Created", type: "date" },
+		{ field: "Closed", label: "Closed", type: "datetime" },
+		{
+			field: "Stage",
+			label: "Stage",
+			type: "picklist",
+			options: [{ value: "Open", label: "Open" }],
+		},
+		{
+			field: "Tags",
+			label: "Tags",
+			type: "multipicklist",
+			options: [
+				{ value: "a", label: "a" },
+				{ value: "b", label: "b" },
+			],
+		},
+		{ field: "Free", label: "Free", type: "picklist" },
+	];
+	const read = (entries: Record<string, string>, options?: { sortBy?: { field: string }[] }) =>
+		readSourceParams(new URLSearchParams(entries), "s", cfgs, options as never);
+
+	it("drops a sort field that is not in sortBy", () => {
+		const params = { "s.s.sort": "Secret__c", "s.s.dir": "DESC" };
+		expect(read(params, { sortBy: [{ field: "Name" }] }).sort).toBeNull();
+		expect(read({ "s.s.sort": "Name" }, { sortBy: [{ field: "Name" }] }).sort).toEqual({
+			field: "Name",
+			direction: "ASC",
+		});
+		expect(read(params).sort).toEqual({ field: "Secret__c", direction: "DESC" });
+	});
+
+	it("drops malformed date and datetime strings", () => {
+		const r = read({
+			"s.s.f.Created.min": "2024-01-02",
+			"s.s.f.Created.max": "2024-01-02T00:00:00Z",
+			"s.s.f.Closed.min": "not-a-date",
+		});
+		expect(r.filters).toHaveLength(1);
+		expect(r.filters[0]).toMatchObject({ field: "Created", min: "2024-01-02", max: undefined });
+	});
+
+	it("keeps only comparison operators as a date value", () => {
+		expect(
+			read({ "s.s.f.Created.min": "2024-01-02", "s.s.f.Created": "gt" }).filters[0].value,
+		).toBe("gt");
+		expect(
+			read({ "s.s.f.Created.min": "2024-01-02", "s.s.f.Created": "evil" }).filters[0].value,
+		).toBeUndefined();
+	});
+
+	it("filters picklist values against configured options", () => {
+		expect(read({ "s.s.f.Stage": "Hacked" }).filters).toEqual([]);
+		expect(read({ "s.s.f.Stage": "Open" }).filters[0].value).toBe("Open");
+		expect(read({ "s.s.f.Tags": "a,zzz,b" }).filters[0].value).toBe("a,b");
+		expect(read({ "s.s.f.Tags": "zzz" }).filters).toEqual([]);
+	});
+
+	it("leaves picklist values alone when no options are configured", () => {
+		expect(read({ "s.s.f.Free": "anything" }).filters[0].value).toBe("anything");
+	});
+
+	it("bounds the page index", () => {
+		expect(read({ "s.s.page": "999999999" }).pageIndex).toBe(1000);
+		expect(read({ "s.s.page": "abc" }).pageIndex).toBe(0);
+	});
+
+	it("ignores oversize or control-character cursors", () => {
+		expect(read({ "s.s.page": "2", "s.s.after": "x".repeat(513) }).afterCursor).toBeUndefined();
+		expect(read({ "s.s.page": "2", "s.s.after": "a\u0000b" }).afterCursor).toBeUndefined();
+		expect(read({ "s.s.page": "2", "s.s.after": "ok" }).afterCursor).toBe("ok");
+	});
+});

package/dist/force-app/main/default/uiBundles/feature-angular-search/src/app/features/search/utils/filter-utils.ts

@@ -0,0 +1,354 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Filter primitives for search.
+ *
+ * Two responsibilities:
+ *   1. Build a GraphQL `where` clause from a list of active filter values.
+ *   2. Serialize/deserialize active filters to/from URLSearchParams under a
+ *      per-source namespace prefix (so multiple sources can coexist on one URL).
+ *
+ * The URL helpers are namespaced: each source declares its key, and filter
+ * params are written as `s.<key>.f.<field>=...`. Sort uses
+ * `s.<key>.sort=<field>&s.<key>.dir=ASC|DESC`. Page size and page index use
+ * `s.<key>.ps=<size>` and `s.<key>.page=<n>`.
+ *
+ * The global search term `q=...` is **not** scoped to a source — it's broadcast
+ * to every source's `searchableFields` by the query builder.
+ */
+
+import type { ActiveFilterValue, FilterFieldConfig } from "../types/filter.types";
+import type { SortFieldConfig, SortState } from "../types/sort.types";
+
+// ---------------------------------------------------------------------------
+// URL serialization (per-source namespace)
+// ---------------------------------------------------------------------------
+
+const SOURCE_PREFIX = "s.";
+const FILTER_INFIX = ".f.";
+const SORT_SUFFIX = ".sort";
+const DIR_SUFFIX = ".dir";
+const PAGE_SIZE_SUFFIX = ".ps";
+const PAGE_SUFFIX = ".page";
+const CURSOR_SUFFIX = ".after";
+
+/** Global search term key (not source-scoped). */
+export const GLOBAL_QUERY_KEY = "q";
+
+function filterKey(sourceKey: string, field: string, suffix?: string) {
+	return `${SOURCE_PREFIX}${sourceKey}${FILTER_INFIX}${field}${suffix ? `.${suffix}` : ""}`;
+}
+
+/**
+ * The source's own default sort / page size. When a source's current state
+ * matches these, the corresponding URL params are omitted so the query string
+ * only ever reflects an *explicit* user choice — resetting filters or returning
+ * a source to its defaults yields a clean URL instead of one littered with the
+ * defaults. The read path falls back to these same defaults when the params are
+ * absent, so the round-trip is lossless.
+ */
+export interface SourceParamDefaults {
+	sort?: SortState | null;
+	pageSize?: number;
+}
+
+function sortMatchesDefault(sort: SortState, defaultSort: SortState | null | undefined): boolean {
+	return (
+		!!defaultSort && sort.field === defaultSort.field && sort.direction === defaultSort.direction
+	);
+}
+
+export function writeSourceParams(
+	params: URLSearchParams,
+	sourceKey: string,
+	filters: ActiveFilterValue[],
+	sort: SortState | null,
+	pageSize?: number,
+	pageIndex?: number,
+	afterCursor?: string,
+	defaults?: SourceParamDefaults,
+): void {
+	for (const filter of filters) {
+		if (filter.value !== undefined && filter.value !== "") {
+			params.set(filterKey(sourceKey, filter.field), filter.value);
+		}
+		if (filter.min !== undefined && filter.min !== "") {
+			params.set(filterKey(sourceKey, filter.field, "min"), filter.min);
+		}
+		if (filter.max !== undefined && filter.max !== "") {
+			params.set(filterKey(sourceKey, filter.field, "max"), filter.max);
+		}
+	}
+	// Only serialize sort when it differs from the source default — otherwise
+	// the URL would carry the default the user never chose.
+	if (sort && !sortMatchesDefault(sort, defaults?.sort)) {
+		params.set(`${SOURCE_PREFIX}${sourceKey}${SORT_SUFFIX}`, sort.field);
+		params.set(`${SOURCE_PREFIX}${sourceKey}${DIR_SUFFIX}`, sort.direction);
+	}
+	if (pageSize !== undefined && pageSize !== defaults?.pageSize) {
+		params.set(`${SOURCE_PREFIX}${sourceKey}${PAGE_SIZE_SUFFIX}`, String(pageSize));
+	}
+	if (pageIndex !== undefined && pageIndex > 0) {
+		params.set(`${SOURCE_PREFIX}${sourceKey}${PAGE_SUFFIX}`, String(pageIndex + 1));
+		// The cursor is only meaningful past page 1; persisting it lets a deep link
+		// or refresh fetch the right page.
+		if (afterCursor) params.set(`${SOURCE_PREFIX}${sourceKey}${CURSOR_SUFFIX}`, afterCursor);
+	}
+}
+
+export interface ReadSourceParamsResult {
+	filters: ActiveFilterValue[];
+	sort: SortState | null;
+	pageSize: number | undefined;
+	pageIndex: number;
+	/** Cursor for the current page; undefined on page 1. */
+	afterCursor: string | undefined;
+}
+
+/** Upper bound on a page index read from the URL. */
+export const MAX_PAGE_INDEX = 1000;
+/** Upper bound on the length of an `after` cursor read from the URL. */
+export const MAX_CURSOR_LENGTH = 512;
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/** True when the string has an ASCII control character (C0 range or DEL). */
+function hasControlChars(value: string): boolean {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code <= 0x1f || code === 0x7f) return true;
+	}
+	return false;
+}
+const DATE_FAMILY = ["date", "daterange", "datetime", "datetimerange"];
+const COMPARISON_OPERATORS = ["gt", "gte", "lt", "lte"];
+
+function validDate(v: string | undefined): string | undefined {
+	return v !== undefined && DATE_PATTERN.test(v) && !isNaN(Date.parse(v)) ? v : undefined;
+}
+
+/** Drops URL-supplied values that the config or type does not allow. */
+function sanitizeFilterValues(
+	config: FilterFieldConfig,
+	value: string | undefined,
+	min: string | undefined,
+	max: string | undefined,
+): { value?: string; min?: string; max?: string } {
+	if (DATE_FAMILY.includes(config.type)) {
+		return {
+			value: value !== undefined && COMPARISON_OPERATORS.includes(value) ? value : undefined,
+			min: validDate(min),
+			max: validDate(max),
+		};
+	}
+	const known = config.options?.map((o) => o.value);
+	if (value && known && known.length > 0) {
+		if (config.type === "picklist") {
+			return { value: known.includes(value) ? value : undefined, min, max };
+		}
+		if (config.type === "multipicklist") {
+			const kept = value.split(",").filter((v) => known.includes(v));
+			return { value: kept.length > 0 ? kept.join(",") : undefined, min, max };
+		}
+	}
+	return { value, min, max };
+}
+
+export interface ReadSourceParamsOptions {
+	/** Allowed sort fields. A URL sort outside this list is dropped. */
+	sortBy?: SortFieldConfig[];
+}
+
+/**
+ * Reads one source's state from the URL. URL values are untrusted: invalid
+ * values are dropped, so a dropped `sort` is `null` and the caller falls back
+ * to the source's default sort.
+ */
+export function readSourceParams(
+	params: URLSearchParams,
+	sourceKey: string,
+	configs: FilterFieldConfig[],
+	options?: ReadSourceParamsOptions,
+): ReadSourceParamsResult {
+	const filters: ActiveFilterValue[] = [];
+	for (const config of configs) {
+		const { field, label, type } = config;
+		const { value, min, max } = sanitizeFilterValues(
+			config,
+			params.get(filterKey(sourceKey, field)) ?? undefined,
+			params.get(filterKey(sourceKey, field, "min")) ?? undefined,
+			params.get(filterKey(sourceKey, field, "max")) ?? undefined,
+		);
+
+		const hasValue = value !== undefined && value !== "";
+		const hasRange = (min !== undefined && min !== "") || (max !== undefined && max !== "");
+		if (hasValue || hasRange) {
+			filters.push({ field, label, type, value, min, max });
+		}
+	}
+
+	let sort: SortState | null = null;
+	const sortField = params.get(`${SOURCE_PREFIX}${sourceKey}${SORT_SUFFIX}`);
+	const sortDir = params.get(`${SOURCE_PREFIX}${sourceKey}${DIR_SUFFIX}`);
+	if (sortField && (!options?.sortBy || options.sortBy.some((s) => s.field === sortField))) {
+		sort = { field: sortField, direction: sortDir === "DESC" ? "DESC" : "ASC" };
+	}
+
+	const pageSizeRaw = params.get(`${SOURCE_PREFIX}${sourceKey}${PAGE_SIZE_SUFFIX}`);
+	const pageSize = pageSizeRaw ? parseInt(pageSizeRaw, 10) : undefined;
+	const pageRaw = params.get(`${SOURCE_PREFIX}${sourceKey}${PAGE_SUFFIX}`);
+	const page = pageRaw ? parseInt(pageRaw, 10) : 1;
+	const pageIndex = !isNaN(page) && page > 1 ? Math.min(page - 1, MAX_PAGE_INDEX) : 0;
+	const rawCursor = params.get(`${SOURCE_PREFIX}${sourceKey}${CURSOR_SUFFIX}`);
+	const afterCursor =
+		pageIndex > 0 &&
+		rawCursor &&
+		rawCursor.length <= MAX_CURSOR_LENGTH &&
+		!hasControlChars(rawCursor)
+			? rawCursor
+			: undefined;
+
+	return {
+		filters,
+		sort,
+		pageSize: pageSize && !isNaN(pageSize) ? pageSize : undefined,
+		pageIndex,
+		afterCursor,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL filter building
+// ---------------------------------------------------------------------------
+
+/**
+ * Combines active filter values into a GraphQL `where` clause for one source.
+ * Returns `undefined` when no constraints are active.
+ */
+export function buildFilter(filters: ActiveFilterValue[], configs: FilterFieldConfig[]): unknown {
+	const configMap = new Map(configs.map((c) => [c.field, c]));
+	const clauses: unknown[] = [];
+	for (const filter of filters) {
+		const clause = buildSingleFilter(filter, configMap.get(filter.field));
+		if (clause) clauses.push(clause);
+	}
+	if (clauses.length === 0) return undefined;
+	if (clauses.length === 1) return clauses[0];
+	return { and: clauses };
+}
+
+function toStartOfDay(d: string) {
+	return `${d}T00:00:00.000Z`;
+}
+function toEndOfDay(d: string) {
+	return `${d}T23:59:59.999Z`;
+}
+
+/** Escapes LIKE metacharacters (`\`, `%`, `_`) so user input is matched literally. */
+function escapeLikePattern(value: string): string {
+	return value.replace(/[\\%_]/g, "\\$&");
+}
+
+/**
+ * Operator for a single-bound date/datetime filter: an explicit comparison
+ * carried in `value` (e.g. "gt" for After, "lt" for Before), else `gte` when a
+ * lower bound is set and `lte` otherwise.
+ */
+function comparisonOperator(value: string | undefined, min: string | undefined): string {
+	if (value && COMPARISON_OPERATORS.includes(value)) return value;
+	return min ? "gte" : "lte";
+}
+
+function buildSingleFilter(filter: ActiveFilterValue, config?: FilterFieldConfig): unknown {
+	const { field, type, value, min, max } = filter;
+	switch (type) {
+		case "text": {
+			if (!value) return null;
+			return { [field]: { like: `%${escapeLikePattern(value)}%` } };
+		}
+		case "picklist": {
+			if (!value) return null;
+			return { [field]: { eq: value } };
+		}
+		case "numeric": {
+			if (!min && !max) return null;
+			const ops: Record<string, number> = {};
+			// clamp both endpoints into the declared [min,max] bounds
+			const clamp = (n: number) => {
+				if (config?.min != null) n = Math.max(n, config.min);
+				if (config?.max != null) n = Math.min(n, config.max);
+				return n;
+			};
+			// Drop any endpoint that isn't finite — NaN/Infinity serialize to null on the wire.
+			const lo = Number(min);
+			if (min && Number.isFinite(lo)) ops["gte"] = clamp(lo);
+			const hi = Number(max);
+			if (max && Number.isFinite(hi)) ops["lte"] = clamp(hi);
+			// If both endpoints were dropped as invalid, emit no clause at all.
+			if (Object.keys(ops).length === 0) return null;
+			return { [field]: ops };
+		}
+		case "boolean": {
+			if (value === undefined || value === "") return null;
+			return { [field]: { eq: value === "true" } };
+		}
+		case "multipicklist": {
+			if (!value) return null;
+			const values = value.split(",").filter(Boolean);
+			if (values.length === 0) return null;
+			if (values.length === 1) return { [field]: { eq: values[0] } };
+			return { [field]: { in: values } };
+		}
+		case "date": {
+			if (!min && !max) return null;
+			const op = comparisonOperator(value, min);
+			const dateStr = min ?? max;
+			return { [field]: { [op]: { value: dateStr } } };
+		}
+		case "daterange": {
+			if (!min && !max) return null;
+			const clauses: unknown[] = [];
+			if (min) clauses.push({ [field]: { gte: { value: min } } });
+			if (max) clauses.push({ [field]: { lte: { value: max } } });
+			return clauses.length === 1 ? clauses[0] : { and: clauses };
+		}
+		case "datetime": {
+			if (!min && !max) return null;
+			const op = comparisonOperator(value, min);
+			const dateStr = min ?? max;
+			const isoStr = op === "gte" || op === "gt" ? toStartOfDay(dateStr!) : toEndOfDay(dateStr!);
+			return { [field]: { [op]: { value: isoStr } } };
+		}
+		case "datetimerange": {
+			if (!min && !max) return null;
+			const clauses: unknown[] = [];
+			if (min) clauses.push({ [field]: { gte: { value: toStartOfDay(min) } } });
+			if (max) clauses.push({ [field]: { lte: { value: toEndOfDay(max) } } });
+			return clauses.length === 1 ? clauses[0] : { and: clauses };
+		}
+		default:
+			return null;
+	}
+}
+
+/**
+ * Builds a global-q `or` clause across the source's searchable fields.
+ * Returns `undefined` when q is empty or the source has no searchable fields.
+ */
+export function buildGlobalQueryClause(q: string, searchableFields: string[]): unknown {
+	const trimmed = q.trim();
+	if (!trimmed || searchableFields.length === 0) return undefined;
+	const clauses = searchableFields.map((path) => {
+		const parts = path.split(".");
+		let clause: Record<string, unknown> = { like: `%${escapeLikePattern(trimmed)}%` };
+		for (let i = parts.length - 1; i >= 0; i--) {
+			clause = { [parts[i]]: clause };
+		}
+		return clause;
+	});
+	return clauses.length === 1 ? clauses[0] : { or: clauses };
+}