@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/state/search-state.service.ts

@@ -0,0 +1,735 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import {
+	computed,
+	DestroyRef,
+	effect,
+	inject,
+	Injectable,
+	signal,
+	type Signal,
+	untracked,
+	type WritableSignal,
+} from "@angular/core";
+import { takeUntilDestroyed } from "@angular/core/rxjs-interop";
+import { ActivatedRoute, Router } from "@angular/router";
+import { Subject } from "rxjs";
+import { debounceTime } from "rxjs/operators";
+import { SearchService } from "../api/search.service";
+import { MIN_QUERY_LENGTH, URL_SYNC_DEBOUNCE_MS } from "../constants";
+import type { FilterValue } from "../filters/filter-types";
+import type { ActiveFilterValue, FilterFieldConfig, PicklistOption } from "../types/filter.types";
+import { ALL_SCOPE, type SearchScope } from "../types/scope.types";
+import type { SearchConfig } from "../types/search-config.types";
+import type {
+	GlobalPaginationState,
+	MergedResultItem,
+	RunSearchOutcome,
+	SourceRequest,
+} from "../types/search-result.types";
+import type { SortState } from "../types/sort.types";
+import { createAsyncData } from "../../../utils/async-data";
+import { GLOBAL_QUERY_KEY, readSourceParams, writeSourceParams } from "../utils/filter-utils";
+import {
+	computeMergedPagination,
+	computePerSourcePagination,
+	filterToGlobalPage,
+	mergedFetchSize,
+	mergeNodes,
+	resolvePagination,
+	validatePageSize,
+	windowMergedPage,
+	type ResolvedPagination,
+} from "../utils/merge-utils";
+import { validateSearchConfig } from "../utils/validate-config";
+import { isSourceInScope, validateScope } from "../utils/scope-utils";
+import { activeTypeFor, toActiveFilter, toFilterValue } from "./filter-mapping";
+import type { SearchInitOptions, SourceLocalState, SourceView } from "./search-state.types";
+
+const EMPTY_OUTCOME: RunSearchOutcome = { results: {}, errors: {} };
+
+/** Whether a query-string key belongs to the search state (vs. the host app). */
+function isOwnParam(key: string): boolean {
+	return (
+		key === GLOBAL_QUERY_KEY ||
+		key === GLOBAL_PAGE_KEY ||
+		key === GLOBAL_SIZE_KEY ||
+		key.startsWith("s.")
+	);
+}
+
+function freshSourceState(pageSize: number, sort: SortState | null): SourceLocalState {
+	return {
+		filters: [],
+		sort,
+		pageSize,
+		pageIndex: 0,
+		afterCursor: undefined,
+		cursorStack: [],
+	};
+}
+
+/** Back to page one: every cursor is invalidated. */
+function withFirstPage(state: SourceLocalState): SourceLocalState {
+	return { ...state, pageIndex: 0, afterCursor: undefined, cursorStack: [] };
+}
+
+/** URL param holding the 1-based merged-mode page. */
+const GLOBAL_PAGE_KEY = "page";
+/** URL param holding the merged-mode page size (omitted when it is the default). */
+const GLOBAL_SIZE_KEY = "size";
+/**
+ * Upper bound on a restored per-source page number; a crafted URL cannot push
+ * the index to an absurd value.
+ */
+const MAX_RESTORED_PAGE = 1000;
+/**
+ * Merged mode fetches a front-anchored window of `(page + 1) * pageSize` rows
+ * per source. The window is capped here (the uiapi `first` limit), so pages
+ * beyond `MAX_MERGED_WINDOW / pageSize` are not reachable in merged mode.
+ */
+export const MAX_MERGED_WINDOW = 200;
+
+/**
+ * State, URL sync and fetching for one multi-source search — the Angular
+ * analogue of React's `useSearch` + `FilterProvider`.
+ *
+ * ## State model
+ * Signals drive instant UI updates; the URL query string (`q`, plus
+ * `s.<key>.*` per source) is the durable seed so a refresh or shared link
+ * restores the same view. URL writes are debounced and use `replaceUrl`.
+ * The current page index and its cursor are persisted per source, so a reload
+ * restores the page (earlier cursors are padded with the current one).
+ * The scope is likewise never persisted: a fresh load starts in "All".
+ *
+ * ## Fetching
+ * One batched request per change of the fetch-relevant inputs, run through
+ * `createAsyncData` (latest-wins). The keyword gate ({@link MIN_QUERY_LENGTH})
+ * and the in-scope source set are applied client-side, so out-of-scope edits
+ * and sub-minimum keystrokes never hit the network.
+ *
+ * ## Pagination
+ * `pagination.mode` decides the model. `"per-source"` keeps one cursor stack
+ * per source; the "global" page is the furthest-advanced in-scope source.
+ * `"merged"` windows the cumulative result set into fixed pages: every
+ * in-scope source fetches its first `(page + 1) * pageSize` rows and the page
+ * slice is taken after ordering.
+ *
+ * ## Scope
+ * Provide per search host (`providers: [SearchStateService]`), NOT in root, and
+ * call {@link init} once with the config.
+ */
+@Injectable()
+export class SearchStateService {
+	private readonly router = inject(Router);
+	private readonly route = inject(ActivatedRoute);
+	private readonly destroyRef = inject(DestroyRef);
+	private readonly searchService = inject(SearchService);
+
+	// -- Writable state ---------------------------------------------------------
+	private readonly _config = signal<SearchConfig | null>(null);
+	private readonly _pagination = signal<ResolvedPagination>(resolvePagination({ sources: [] }));
+	private readonly _lockedScope = signal<SearchScope | undefined>(undefined);
+	private readonly _configError = signal<string | null>(null);
+	private readonly _q = signal("");
+	private readonly _scope = signal<SearchScope>(ALL_SCOPE);
+	private readonly _sourceStates = signal<Record<string, SourceLocalState>>({});
+	private readonly _globalPageIndex = signal(0);
+	private readonly _globalPageSize = signal(resolvePagination({ sources: [] }).pageSize);
+
+	/** Coalesces rapid state changes into a single debounced URL write. */
+	private readonly urlSync$ = new Subject<void>();
+	/** The `q` last seeded from, or written to, the URL by this service. */
+	private lastSyncedQ = "";
+	private readonly distinctCache = new Map<string, WritableSignal<readonly PicklistOption[]>>();
+
+	// -- Public read signals ----------------------------------------------------
+	readonly config: Signal<SearchConfig | null> = this._config.asReadonly();
+	/** Set when {@link init} rejected the config; nothing is fetched in that case. */
+	readonly configError: Signal<string | null> = this._configError.asReadonly();
+	/** Raw search term (the search bar debounces before calling {@link setQ}). */
+	readonly q: Signal<string> = this._q.asReadonly();
+	readonly scope: Signal<SearchScope> = this._scope.asReadonly();
+	readonly scopeLocked = computed(() => this._lockedScope() !== undefined);
+	readonly pagination: Signal<ResolvedPagination> = this._pagination.asReadonly();
+	readonly mergedMode = computed(() => this._pagination().mode === "merged");
+	/** True while the search term is below {@link MIN_QUERY_LENGTH} (no request fires). */
+	readonly isShortQuery = computed(() => this._q().trim().length < MIN_QUERY_LENGTH);
+
+	// -- Fetch ------------------------------------------------------------------
+	/** Requests for the current state; empty when gated (short query / no source). */
+	private readonly requests = computed<SourceRequest[]>(() => {
+		const config = this._config();
+		if (!config || this.isShortQuery()) return [];
+		const q = this._q();
+		const scope = this._scope();
+		const states = this._sourceStates();
+		const merged = this.mergedMode();
+		// Merged mode fetches the whole front-anchored window with no cursor.
+		const pageSize = this._globalPageSize();
+		const windowSize = Math.min(
+			mergedFetchSize(this._globalPageIndex(), pageSize),
+			Math.max(MAX_MERGED_WINDOW, pageSize),
+		);
+		return config.sources
+			.filter((source) => isSourceInScope(scope, source.key))
+			.flatMap((source) => {
+				const st = states[source.key];
+				if (!st) return [];
+				return [
+					{
+						source,
+						q,
+						filters: st.filters,
+						sort: st.sort,
+						pageSize: merged ? windowSize : st.pageSize,
+						afterCursor: merged ? undefined : st.afterCursor,
+					},
+				];
+			});
+	});
+
+	/**
+	 * Fetch-relevant fingerprint. A string so that edits which do not change any
+	 * request (e.g. to an out-of-scope source) do not refetch.
+	 */
+	private readonly requestKey = computed(() =>
+		JSON.stringify(
+			this.requests().map((r) => ({
+				k: r.source.key,
+				q: r.q,
+				f: r.filters,
+				o: r.sort,
+				p: r.pageSize,
+				a: r.afterCursor ?? null,
+			})),
+		),
+	);
+
+	private readonly fetched = createAsyncData<string, RunSearchOutcome>(this.requestKey, () =>
+		this.fetch(this.requests()),
+	);
+
+	/** True while a request for the current state is in flight. */
+	readonly loading = computed(() => this.requests().length > 0 && this.fetched.loading());
+
+	private readonly outcome = computed(() => this.fetched.data() ?? EMPTY_OUTCOME);
+
+	/**
+	 * Page-level error: a whole-request failure, or every requested source
+	 * failed. A partial failure surfaces per source instead (see {@link SourceView.error}).
+	 */
+	readonly error = computed<string | null>(() => {
+		const invalid = this._configError();
+		if (invalid) return invalid;
+		if (this.loading()) return null;
+		const whole = this.fetched.error();
+		if (whole) return whole;
+		const requested = this.requests();
+		if (requested.length === 0) return null;
+		const errors = this.outcome().errors;
+		if (!requested.every((r) => errors[r.source.key] != null)) return null;
+		const combined = [...new Set(requested.map((r) => errors[r.source.key]).filter(Boolean))];
+		return combined.join("; ") || "Unified search failed";
+	});
+
+	// -- Derived views ----------------------------------------------------------
+	/** Every configured source, keyed by `source.key`. */
+	readonly sources = computed<Record<string, SourceView>>(() => {
+		const config = this._config();
+		if (!config) return {};
+		const states = this._sourceStates();
+		const { results, errors } = this.outcome();
+		const loading = this.loading();
+		const out: Record<string, SourceView> = {};
+		for (const source of config.sources) {
+			const st = states[source.key];
+			if (!st) continue;
+			const result = results[source.key] ?? null;
+			out[source.key] = {
+				config: source,
+				result,
+				error: loading ? null : (errors[source.key] ?? null),
+				filters: st.filters,
+				sort: st.sort,
+				pageSize: st.pageSize,
+				pageIndex: st.pageIndex,
+				hasNextPage: result?.pageInfo?.hasNextPage ?? false,
+				hasPreviousPage: st.pageIndex > 0,
+			};
+		}
+		return out;
+	});
+
+	/** Views of the sources in the current scope, in config order. */
+	readonly inScopeSources = computed<SourceView[]>(() => {
+		const scope = this._scope();
+		const sources = this.sources();
+		return (this._config()?.sources ?? [])
+			.filter((s) => isSourceInScope(scope, s.key))
+			.map((s) => sources[s.key])
+			.filter((v): v is SourceView => !!v);
+	});
+
+	/** Cumulative in-scope result count (`totalCount`, else rows fetched). */
+	readonly totalCount = computed(() =>
+		this.inScopeSources().reduce(
+			(sum, v) => sum + (v.result?.totalCount ?? v.result?.nodes.length ?? 0),
+			0,
+		),
+	);
+
+	private readonly concatenatedNodes = computed<MergedResultItem[]>(() =>
+		mergeNodes(
+			this.inScopeSources().map((v) => ({
+				key: v.config.key,
+				nodes: v.result?.nodes ?? [],
+				weight: v.result?.totalCount ?? v.result?.nodes.length ?? 0,
+			})),
+			this._pagination().mergeOrder,
+		),
+	);
+
+	/** Aggregate pagination across the in-scope sources (model per `pagination.mode`). */
+	readonly globalPagination = computed<GlobalPaginationState>(() => {
+		const pagination = this._pagination();
+		if (this.mergedMode()) {
+			const total = this.totalCount();
+			const size = this._globalPageSize();
+			// Only the capped window is reachable, so page math uses the capped total.
+			const reachable = Math.min(total, Math.max(MAX_MERGED_WINDOW, size));
+			return {
+				...computeMergedPagination(
+					reachable,
+					size,
+					this._globalPageIndex(),
+					pagination.pageSizeOptions,
+				),
+				totalCount: total,
+			};
+		}
+		const inScope = this.inScopeSources();
+		return computePerSourcePagination(
+			inScope.map((v) => ({
+				key: v.config.key,
+				pageIndex: v.pageIndex,
+				hasNextPage: v.hasNextPage,
+				totalCount: v.result?.totalCount ?? null,
+				nodeCount: v.result?.nodes.length ?? 0,
+			})),
+			inScope[0]?.pageSize ?? pagination.pageSize,
+			pagination.pageSizeOptions,
+		);
+	});
+
+	/** The nodes of the current page, tagged by source, for a combined list. */
+	readonly mergedResults = computed<MergedResultItem[]>(() => {
+		const page = this.globalPagination();
+		if (this.mergedMode()) {
+			return windowMergedPage(this.concatenatedNodes(), page.pageIndex, page.pageSize);
+		}
+		const indexBySource: Record<string, number> = {};
+		for (const v of this.inScopeSources()) indexBySource[v.config.key] = v.pageIndex;
+		return filterToGlobalPage(this.concatenatedNodes(), indexBySource, page.pageIndex);
+	});
+
+	constructor() {
+		this.urlSync$
+			.pipe(debounceTime(URL_SYNC_DEBOUNCE_MS), takeUntilDestroyed(this.destroyRef))
+			.subscribe(() => this.flushToUrl());
+
+		// An external change of `q` (e.g. GlobalSearchBox navigating while this page
+		// is already open) re-seeds the term. Our own URL writes are ignored by
+		// comparing against the last `q` we wrote or seeded.
+		this.route.queryParamMap.pipe(takeUntilDestroyed(this.destroyRef)).subscribe((map) => {
+			if (!this._config()) return;
+			const q = map.get(GLOBAL_QUERY_KEY) ?? "";
+			if (q === this.lastSyncedQ) return;
+			this.lastSyncedQ = q;
+			this._q.set(q);
+			this._globalPageIndex.set(0);
+			this.resetAllCursors();
+		});
+
+		// A restored (or stale) merged page past the last page is pulled back once
+		// the totals are known, which also shrinks the fetch window.
+		effect(() => {
+			if (!this.mergedMode() || this.loading() || this.requests().length === 0) return;
+			if (this.fetched.data() === undefined) return;
+			const clamped = this.globalPagination().pageIndex;
+			if (untracked(this._globalPageIndex) > clamped) {
+				this._globalPageIndex.set(clamped);
+				this.scheduleUrlSync();
+			}
+		});
+	}
+
+	/**
+	 * Seeds state from the config and the current URL. Safe to call once; later
+	 * calls are ignored (the config is stable for the service's lifetime).
+	 */
+	init(config: SearchConfig, options?: SearchInitOptions): void {
+		if (this._config()) return;
+		try {
+			validateSearchConfig(config);
+		} catch (err) {
+			this._configError.set(err instanceof Error ? err.message : String(err));
+			return;
+		}
+		const pagination = resolvePagination(config);
+
+		const locked = options?.lockedScope;
+		const lockedScope: SearchScope | undefined =
+			locked === undefined
+				? undefined
+				: locked !== ALL_SCOPE && config.sources.some((s) => s.key === locked)
+					? locked
+					: ALL_SCOPE;
+
+		const params = new URLSearchParams();
+		for (const [key, raw] of Object.entries(this.route.snapshot.queryParams)) {
+			const value = Array.isArray(raw) ? raw[0] : raw;
+			if (typeof value === "string") params.set(key, value);
+		}
+
+		const states: Record<string, SourceLocalState> = {};
+		for (const source of config.sources) {
+			const read = readSourceParams(params, source.key, source.filterBy ?? [], {
+				sortBy: source.sortBy,
+			});
+			const fresh = freshSourceState(
+				validatePageSize(pagination, read.pageSize ?? pagination.pageSize),
+				read.sort ?? source.defaultSort ?? null,
+			);
+			// Only the current page's cursor is known after a reload; the stack holds
+			// just that one entry, so Previous falls back to page one (see
+			// goToPreviousSourcePage).
+			states[source.key] = {
+				...fresh,
+				pageIndex: read.afterCursor ? Math.min(read.pageIndex, MAX_RESTORED_PAGE) : 0,
+				afterCursor: read.afterCursor,
+				cursorStack: read.afterCursor ? [read.afterCursor] : [],
+				filters: read.filters.map((f) => ({ ...f, type: activeTypeFor(f.type) })),
+			};
+		}
+
+		this._pagination.set(pagination);
+		let globalSize = pagination.pageSize;
+		if (pagination.mode === "merged") {
+			const size = parseInt(params.get(GLOBAL_SIZE_KEY) ?? "", 10);
+			if (!isNaN(size)) globalSize = validatePageSize(pagination, size);
+		}
+		this._globalPageSize.set(globalSize);
+		this._lockedScope.set(lockedScope);
+		this._scope.set(lockedScope ?? ALL_SCOPE);
+		this._q.set(params.get(GLOBAL_QUERY_KEY) ?? "");
+		if (pagination.mode === "merged") {
+			const page = parseInt(params.get(GLOBAL_PAGE_KEY) ?? "", 10);
+			const maxIndex = Math.max(
+				0,
+				Math.floor(Math.max(MAX_MERGED_WINDOW, globalSize) / globalSize) - 1,
+			);
+			this._globalPageIndex.set(!isNaN(page) && page > 1 ? Math.min(page - 1, maxIndex) : 0);
+		}
+		this.lastSyncedQ = params.get(GLOBAL_QUERY_KEY) ?? "";
+		this._sourceStates.set(states);
+		this._config.set(config);
+	}
+
+	// -- Global term / scope ----------------------------------------------------
+
+	setQ(q: string): void {
+		this._q.set(q);
+		this._globalPageIndex.set(0);
+		this.resetAllCursors();
+		this.scheduleUrlSync();
+	}
+
+	/** No-op when the scope is locked; unknown values fall back to "all". */
+	setScope(scope: SearchScope): void {
+		const config = this._config();
+		if (!config || this._lockedScope() !== undefined) return;
+		this._scope.set(validateScope(config, scope));
+		this._globalPageIndex.set(0);
+		this.resetAllCursors();
+		this.scheduleUrlSync();
+	}
+
+	/** Clears the term and every source's filters / sort / paging (scope stays locked if locked). */
+	resetAll(): void {
+		const config = this._config();
+		if (!config) return;
+		const pagination = this._pagination();
+		this._q.set("");
+		this._scope.set(this._lockedScope() ?? ALL_SCOPE);
+		this._globalPageIndex.set(0);
+		this._globalPageSize.set(pagination.pageSize);
+		const states: Record<string, SourceLocalState> = {};
+		for (const source of config.sources) {
+			states[source.key] = freshSourceState(pagination.pageSize, source.defaultSort ?? null);
+		}
+		this._sourceStates.set(states);
+		this.flushToUrl();
+	}
+
+	// -- Per-source filters / sort ----------------------------------------------
+
+	/** The input-shaped value of a source's active filter (for filter components). */
+	filterValue(sourceKey: string, field: string): FilterValue | undefined {
+		return toFilterValue(this._sourceStates()[sourceKey]?.filters.find((f) => f.field === field));
+	}
+
+	/** Sets the filter from an input value; an empty value removes it. */
+	setFilterValue(
+		sourceKey: string,
+		config: FilterFieldConfig,
+		value: FilterValue | undefined,
+	): void {
+		this.setFilter(sourceKey, config.field, toActiveFilter(config, value));
+	}
+
+	/** Adds or replaces the filter for `field`; `undefined` removes it. */
+	setFilter(sourceKey: string, field: string, value: ActiveFilterValue | undefined): void {
+		this.updateSource(
+			sourceKey,
+			(prev) => {
+				const filters = prev.filters.filter((f) => f.field !== field);
+				if (value) filters.push(value);
+				return { ...prev, filters };
+			},
+			true,
+		);
+	}
+
+	removeFilter(sourceKey: string, field: string): void {
+		this.setFilter(sourceKey, field, undefined);
+	}
+
+	/** Removes every active filter of one source. */
+	clearFilters(sourceKey: string): void {
+		this.updateSource(sourceKey, (prev) => ({ ...prev, filters: [] }), true);
+	}
+
+	setSort(sourceKey: string, sort: SortState | null): void {
+		this.updateSource(sourceKey, (prev) => ({ ...prev, sort }), true);
+	}
+
+	// -- Per-source pagination --------------------------------------------------
+
+	setSourcePageSize(sourceKey: string, size: number): void {
+		const valid = validatePageSize(this._pagination(), size);
+		this.updateSource(sourceKey, (prev) => ({ ...prev, pageSize: valid }), true);
+	}
+
+	goToNextSourcePage(sourceKey: string): void {
+		const cursor = this.sources()[sourceKey]?.result?.pageInfo?.endCursor;
+		if (!cursor) return;
+		this.updateSource(
+			sourceKey,
+			(prev) => ({
+				...prev,
+				cursorStack: [...prev.cursorStack, cursor],
+				afterCursor: cursor,
+				pageIndex: prev.pageIndex + 1,
+			}),
+			false,
+		);
+	}
+
+	goToPreviousSourcePage(sourceKey: string): void {
+		this.updateSource(
+			sourceKey,
+			(prev) => {
+				if (prev.pageIndex === 0) return prev;
+				// The cursor of the previous page is the second-from-last stack entry.
+				// After a reload only the current cursor is known, so go to page one.
+				if (prev.pageIndex === 1 || prev.cursorStack.length < 2) return withFirstPage(prev);
+				const cursorStack = prev.cursorStack.slice(0, -1);
+				return {
+					...prev,
+					cursorStack,
+					afterCursor: cursorStack[cursorStack.length - 1],
+					pageIndex: Math.max(0, prev.pageIndex - 1),
+				};
+			},
+			false,
+		);
+	}
+
+	// -- Global pagination ------------------------------------------------------
+
+	goToNextPage(): void {
+		if (this.mergedMode()) {
+			if (this.globalPagination().hasNextPage) {
+				this._globalPageIndex.update((p) => p + 1);
+				this.scheduleUrlSync();
+			}
+			return;
+		}
+		for (const v of this.inScopeSources()) {
+			if (v.hasNextPage) this.goToNextSourcePage(v.config.key);
+		}
+	}
+
+	goToPreviousPage(): void {
+		if (this.mergedMode()) {
+			this._globalPageIndex.update((p) => Math.max(0, p - 1));
+			this.scheduleUrlSync();
+			return;
+		}
+		const current = this.globalPagination().pageIndex;
+		for (const v of this.inScopeSources()) {
+			if (v.pageIndex === current) this.goToPreviousSourcePage(v.config.key);
+		}
+	}
+
+	/** Jumps to a 0-based page. Merged: any page. Per-source: only the adjacent pages. */
+	goToPage(pageIndex: number): void {
+		if (!Number.isFinite(pageIndex)) return;
+		const target = Math.max(0, Math.floor(pageIndex));
+		if (this.mergedMode()) {
+			const last = Math.max(0, this.globalPagination().pageCount - 1);
+			this._globalPageIndex.set(Math.min(target, last));
+			this.scheduleUrlSync();
+			return;
+		}
+		const page = this.globalPagination();
+		if (target === page.pageIndex + 1 && page.hasNextPage) this.goToNextPage();
+		else if (target === page.pageIndex - 1 && page.hasPreviousPage) this.goToPreviousPage();
+	}
+
+	/** Sets the page size for the whole search (every source in per-source mode). */
+	setPageSize(size: number): void {
+		const valid = validatePageSize(this._pagination(), size);
+		if (this.mergedMode()) {
+			this._globalPageSize.set(valid);
+			this._globalPageIndex.set(0);
+			this.scheduleUrlSync();
+			return;
+		}
+		// Every source, not only the in-scope ones, so sizes cannot diverge after a
+		// later scope change.
+		this._globalPageIndex.set(0);
+		this._sourceStates.update((prev) => {
+			const next: Record<string, SourceLocalState> = {};
+			for (const [key, st] of Object.entries(prev)) {
+				next[key] = withFirstPage({ ...st, pageSize: valid });
+			}
+			return next;
+		});
+		this.scheduleUrlSync();
+	}
+
+	// -- Distinct picklist values -----------------------------------------------
+
+	/**
+	 * Distinct values of a picklist field, fetched once (per object + field) on
+	 * first read. Empty until loaded, and on failure.
+	 */
+	distinctOptions(objectName: string, fieldName: string): Signal<readonly PicklistOption[]> {
+		const cacheKey = `${objectName}.${fieldName}`;
+		let options = this.distinctCache.get(cacheKey);
+		if (!options) {
+			const created = signal<readonly PicklistOption[]>([]);
+			options = created;
+			this.distinctCache.set(cacheKey, created);
+			this.searchService
+				.fetchDistinctValues(objectName, fieldName)
+				.then((values) => created.set(values))
+				.catch((err: unknown) => {
+					console.error(err);
+					// Drop the entry so a later read retries instead of caching "empty" forever.
+					this.distinctCache.delete(cacheKey);
+				});
+		}
+		return options.asReadonly();
+	}
+
+	// -- Internals --------------------------------------------------------------
+
+	private async fetch(requests: SourceRequest[]): Promise<RunSearchOutcome> {
+		if (requests.length === 0) return EMPTY_OUTCOME;
+		return this.searchService.runSearch(requests);
+	}
+
+	private updateSource(
+		sourceKey: string,
+		updater: (prev: SourceLocalState) => SourceLocalState,
+		resetPagination: boolean,
+	): void {
+		if (!this._sourceStates()[sourceKey]) return;
+		// A filter / sort / page-size change reshapes the result set, so the
+		// global merged page returns to the first page too.
+		if (resetPagination) this._globalPageIndex.set(0);
+		this._sourceStates.update((prev) => {
+			const prior = prev[sourceKey];
+			if (!prior) return prev;
+			const next = updater(prior);
+			return { ...prev, [sourceKey]: resetPagination ? withFirstPage(next) : next };
+		});
+		this.scheduleUrlSync();
+	}
+
+	private resetAllCursors(): void {
+		this._sourceStates.update((prev) => {
+			const next: Record<string, SourceLocalState> = {};
+			for (const [key, st] of Object.entries(prev)) next[key] = withFirstPage(st);
+			return next;
+		});
+	}
+
+	private scheduleUrlSync(): void {
+		this.urlSync$.next();
+	}
+
+	private flushToUrl(): void {
+		const config = this._config();
+		if (!config) return;
+		const params = new URLSearchParams();
+		const q = this._q();
+		if (q) params.set(GLOBAL_QUERY_KEY, q);
+		const globalPage = this._globalPageIndex();
+		if (this.mergedMode()) {
+			if (globalPage > 0) params.set(GLOBAL_PAGE_KEY, String(globalPage + 1));
+			const size = this._globalPageSize();
+			if (size !== this._pagination().pageSize) params.set(GLOBAL_SIZE_KEY, String(size));
+		}
+		const states = this._sourceStates();
+		const defaultPageSize = this._pagination().pageSize;
+		for (const source of config.sources) {
+			const st = states[source.key];
+			if (!st) continue;
+			// Sort / page size equal to the defaults are omitted so a reset leaves a
+			// clean query string.
+			writeSourceParams(
+				params,
+				source.key,
+				st.filters,
+				st.sort,
+				st.pageSize,
+				st.pageIndex,
+				st.afterCursor,
+				{
+					sort: source.defaultSort ?? null,
+					pageSize: defaultPageSize,
+				},
+			);
+		}
+		const queryParams: Record<string, string | null> = Object.fromEntries(params.entries());
+		// Merge so host-app params survive; our own now-unused keys are nulled out.
+		for (const key of Object.keys(this.route.snapshot.queryParams)) {
+			if (!(key in queryParams) && isOwnParam(key)) queryParams[key] = null;
+		}
+		this.lastSyncedQ = q;
+		void this.router.navigate([], {
+			relativeTo: this.route,
+			queryParams,
+			queryParamsHandling: "merge",
+			// Replace so typing does not flood browser history.
+			replaceUrl: true,
+		});
+	}
+}