@salesforce/ui-bundle-template-feature-react-search 11.3.0

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/hooks/useSearch.ts

@@ -0,0 +1,442 @@
+/**
+ * useSearch — orchestrates configuration-driven multi-source search.
+ *
+ * Owns:
+ *  - global `q` (one search box drives all sources)
+ *  - per-source filters / sort / pagination (independent state per source)
+ *  - URL sync (debounced; namespace `s.<key>.f.<field>=...`)
+ *  - one batched GraphQL fetch on every state change
+ *
+ * Returns a per-source `controller` map plus aggregate loading/error flags.
+ * Rendering and routing are the caller's responsibility.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useSearchParams } from "react-router";
+import { runSearch } from "../api/searchService";
+import {
+	GLOBAL_QUERY_KEY,
+	readSourceParams,
+	writeSourceParams,
+	type ActiveFilterValue,
+} from "../utils/filterUtils";
+import type { SortState } from "../utils/sortUtils";
+import { debounce } from "../utils/debounce";
+import type {
+	SObjectSourceConfig,
+	SourceController,
+	SourceResult,
+	SearchConfig,
+	SearchHandle,
+	SearchScope,
+} from "../types";
+import { ALL_SCOPE } from "../types";
+
+const URL_SYNC_DEBOUNCE_MS = 300;
+const SCOPE_KEY = "scope";
+
+/**
+ * Returns true when `source` should participate in the current scope —
+ * either the scope is "all" or the scope matches this source's key.
+ */
+function isSourceInScope(scope: SearchScope, sourceKey: string): boolean {
+	return scope === ALL_SCOPE || scope === sourceKey;
+}
+
+interface SourceLocalState {
+	filters: ActiveFilterValue[];
+	sort: SortState | null;
+	pageSize: number;
+	pageIndex: number;
+	afterCursor: string | undefined;
+	cursorStack: string[];
+}
+
+function defaultPageSize(source: SObjectSourceConfig): number {
+	return source.pageSize ?? source.validPageSizes?.[0] ?? 10;
+}
+
+function validatePageSize(source: SObjectSourceConfig, size: number): number {
+	const valid = source.validPageSizes;
+	if (!valid || valid.length === 0) return size;
+	return valid.includes(size) ? size : defaultPageSize(source);
+}
+
+function initSourceState(source: SObjectSourceConfig, params: URLSearchParams): SourceLocalState {
+	const read = readSourceParams(params, source.key, source.filterFields ?? []);
+	const sort = read.sort ?? source.defaultSort ?? null;
+	const pageSize = validatePageSize(source, read.pageSize ?? defaultPageSize(source));
+	return {
+		filters: read.filters,
+		sort,
+		pageSize,
+		pageIndex: read.pageIndex,
+		afterCursor: undefined,
+		cursorStack: [],
+	};
+}
+
+export interface UseSearchOptions {
+	/**
+	 * Lock the search to a single source key (or "all"). When set:
+	 *   - `scope` is forced to this value and `setScope` becomes a no-op.
+	 *   - The URL never writes `?scope=` (it's implicit in the page route).
+	 *   - The dropdown should be hidden by the caller.
+	 *
+	 * Use when you embed the search inside a page that already represents
+	 * the source (e.g. `/accounts/search` rendering only Accounts).
+	 */
+	lockedScope?: SearchScope;
+}
+
+export function useSearch(config: SearchConfig, options?: UseSearchOptions): SearchHandle {
+	const [searchParams, setSearchParams] = useSearchParams();
+	const lockedScope = options?.lockedScope;
+
+	// One-time seed from URL.
+	const initialSourceStates = useMemo(() => {
+		const map: Record<string, SourceLocalState> = {};
+		for (const source of config.sources) {
+			map[source.key] = initSourceState(source, searchParams);
+		}
+		return map;
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, []);
+	const initialQ = useMemo(() => searchParams.get(GLOBAL_QUERY_KEY) ?? "", []);
+	const initialScope = useMemo<SearchScope>(() => {
+		// When the caller locks the scope, that always wins over the URL.
+		if (lockedScope !== undefined) {
+			if (lockedScope === ALL_SCOPE) return ALL_SCOPE;
+			return config.sources.some((s) => s.key === lockedScope) ? lockedScope : ALL_SCOPE;
+		}
+		const raw = searchParams.get(SCOPE_KEY);
+		if (!raw || raw === ALL_SCOPE) return ALL_SCOPE;
+		return config.sources.some((s) => s.key === raw) ? raw : ALL_SCOPE;
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, []);
+
+	const [q, setQState] = useState(initialQ);
+	const [scope, setScopeState] = useState<SearchScope>(initialScope);
+	const [sourceStates, setSourceStates] =
+		useState<Record<string, SourceLocalState>>(initialSourceStates);
+
+	// Snapshot ref so debounced URL sync sees the latest state without
+	// recreating callbacks on every render.
+	const stateRef = useRef({ q, scope, sourceStates });
+	useEffect(() => {
+		stateRef.current = { q, scope, sourceStates };
+	});
+
+	// -- URL sync --------------------------------------------------------------
+
+	const syncToUrl = useCallback(
+		(nextQ: string, nextScope: SearchScope, nextStates: Record<string, SourceLocalState>) => {
+			const params = new URLSearchParams();
+			if (nextQ) params.set(GLOBAL_QUERY_KEY, nextQ);
+			// Skip writing ?scope when caller has locked the scope — it's
+			// already implicit in the page route.
+			if (lockedScope === undefined && nextScope !== ALL_SCOPE) {
+				params.set(SCOPE_KEY, nextScope);
+			}
+			for (const source of config.sources) {
+				const state = nextStates[source.key];
+				if (!state) continue;
+				writeSourceParams(
+					params,
+					source.key,
+					state.filters,
+					state.sort,
+					state.pageSize,
+					state.pageIndex,
+					// Omit sort / page size from the URL when they equal this
+					// source's defaults, so a reset (or untouched source) leaves
+					// a clean query string instead of echoing the defaults.
+					{ sort: source.defaultSort ?? null, pageSize: defaultPageSize(source) },
+				);
+			}
+			setSearchParams(params, { replace: true });
+		},
+		[config.sources, setSearchParams, lockedScope],
+	);
+
+	const debouncedSyncRef = useRef(debounce(syncToUrl, URL_SYNC_DEBOUNCE_MS));
+	useEffect(() => {
+		debouncedSyncRef.current = debounce(syncToUrl, URL_SYNC_DEBOUNCE_MS);
+	}, [syncToUrl]);
+
+	// Update one source's state and (optionally) reset its pagination.
+	const updateSource = useCallback(
+		(
+			sourceKey: string,
+			updater: (prev: SourceLocalState) => SourceLocalState,
+			resetPagination: boolean,
+		) => {
+			setSourceStates((prev) => {
+				const prior = prev[sourceKey];
+				if (!prior) return prev;
+				let next = updater(prior);
+				if (resetPagination) {
+					next = { ...next, pageIndex: 0, afterCursor: undefined, cursorStack: [] };
+				}
+				const merged = { ...prev, [sourceKey]: next };
+				debouncedSyncRef.current(stateRef.current.q, stateRef.current.scope, merged);
+				return merged;
+			});
+		},
+		[],
+	);
+
+	// -- Global q --------------------------------------------------------------
+
+	const setQ = useCallback((nextQ: string) => {
+		setQState(nextQ);
+		// Changing the global term invalidates every cursor.
+		setSourceStates((prev) => {
+			const next: Record<string, SourceLocalState> = {};
+			for (const [key, state] of Object.entries(prev)) {
+				next[key] = { ...state, pageIndex: 0, afterCursor: undefined, cursorStack: [] };
+			}
+			debouncedSyncRef.current(nextQ, stateRef.current.scope, next);
+			return next;
+		});
+	}, []);
+
+	// -- Scope -----------------------------------------------------------------
+
+	const setScope = useCallback(
+		(nextScope: SearchScope) => {
+			// Locked scope wins over user input — silently no-op.
+			if (lockedScope !== undefined) return;
+			// Reject unknown scope values; fall back to "all".
+			const validated: SearchScope =
+				nextScope === ALL_SCOPE || config.sources.some((s) => s.key === nextScope)
+					? nextScope
+					: ALL_SCOPE;
+			setScopeState(validated);
+			// Narrowing or widening invalidates every cursor — the visible result
+			// set is changing.
+			setSourceStates((prev) => {
+				const next: Record<string, SourceLocalState> = {};
+				for (const [key, state] of Object.entries(prev)) {
+					next[key] = { ...state, pageIndex: 0, afterCursor: undefined, cursorStack: [] };
+				}
+				debouncedSyncRef.current(stateRef.current.q, validated, next);
+				return next;
+			});
+		},
+		[config.sources, lockedScope],
+	);
+
+	// -- Reset all -------------------------------------------------------------
+
+	const resetAll = useCallback(() => {
+		setQState("");
+		// Preserve locked scope; otherwise widen back to "all".
+		const nextScope: SearchScope = lockedScope ?? ALL_SCOPE;
+		setScopeState(nextScope);
+		const empty: Record<string, SourceLocalState> = {};
+		for (const source of config.sources) {
+			empty[source.key] = {
+				filters: [],
+				sort: source.defaultSort ?? null,
+				pageSize: defaultPageSize(source),
+				pageIndex: 0,
+				afterCursor: undefined,
+				cursorStack: [],
+			};
+		}
+		setSourceStates(empty);
+		syncToUrl("", nextScope, empty);
+	}, [config.sources, syncToUrl, lockedScope]);
+
+	// -- Fetch -----------------------------------------------------------------
+
+	const requestKey = useMemo(() => {
+		// Stable string key that changes only when something fetch-relevant changes.
+		// Sources outside the current scope are listed (with `skip: true`) so
+		// the key still changes when scope toggles, but they don't contribute
+		// per-source state to the diff.
+		return JSON.stringify({
+			q,
+			scope,
+			s: config.sources.map((source) => {
+				if (!isSourceInScope(scope, source.key)) {
+					return { k: source.key, skip: true };
+				}
+				const st = sourceStates[source.key];
+				return {
+					k: source.key,
+					f: st?.filters,
+					o: st?.sort,
+					p: st?.pageSize,
+					a: st?.afterCursor ?? null,
+				};
+			}),
+		});
+	}, [q, scope, sourceStates, config.sources]);
+
+	const [results, setResults] = useState<Record<string, SourceResult>>({});
+	const [loading, setLoading] = useState(true);
+	const [error, setError] = useState<string | null>(null);
+	const fetchGenRef = useRef(0);
+
+	useEffect(() => {
+		const generation = ++fetchGenRef.current;
+		setLoading(true);
+		setError(null);
+
+		const activeSources = config.sources.filter((source) => isSourceInScope(scope, source.key));
+
+		// All sources gated out — clear results and exit without firing a request.
+		if (activeSources.length === 0) {
+			setResults({});
+			setLoading(false);
+			return;
+		}
+
+		const requests = activeSources.map((source) => {
+			const st = sourceStates[source.key]!;
+			return {
+				source,
+				q,
+				filters: st.filters,
+				sort: st.sort,
+				pageSize: st.pageSize,
+				afterCursor: st.afterCursor,
+			};
+		});
+
+		runSearch(requests)
+			.then((resp) => {
+				if (generation !== fetchGenRef.current) return;
+				setResults(resp);
+			})
+			.catch((err: unknown) => {
+				if (generation !== fetchGenRef.current) return;
+				console.error(err);
+				setError(err instanceof Error ? err.message : "Unified search failed");
+			})
+			.finally(() => {
+				if (generation !== fetchGenRef.current) return;
+				setLoading(false);
+			});
+		// requestKey is the dependency-of-record; sourceStates and q are
+		// captured via the ref-like closure above each render.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [requestKey]);
+
+	// -- Per-source controllers ------------------------------------------------
+
+	const controllers = useMemo(() => {
+		const out: Record<string, SourceController> = {};
+		for (const source of config.sources) {
+			const state = sourceStates[source.key];
+			const result = results[source.key] ?? null;
+
+			const setFilter = (field: string, value: ActiveFilterValue | undefined) => {
+				updateSource(
+					source.key,
+					(prev) => {
+						const filtered = prev.filters.filter((f) => f.field !== field);
+						if (value) filtered.push(value);
+						return { ...prev, filters: filtered };
+					},
+					true,
+				);
+			};
+			const removeFilter = (field: string) => {
+				updateSource(
+					source.key,
+					(prev) => ({
+						...prev,
+						filters: prev.filters.filter((f) => f.field !== field),
+					}),
+					true,
+				);
+			};
+			const setSort = (sort: SortState | null) => {
+				updateSource(source.key, (prev) => ({ ...prev, sort }), true);
+			};
+			const setPageSize = (size: number) => {
+				updateSource(
+					source.key,
+					(prev) => ({ ...prev, pageSize: validatePageSize(source, size) }),
+					true,
+				);
+			};
+			const goToNextPage = () => {
+				const cursor = result?.pageInfo?.endCursor;
+				if (!cursor) return;
+				updateSource(
+					source.key,
+					(prev) => ({
+						...prev,
+						cursorStack: [...prev.cursorStack, cursor],
+						afterCursor: cursor,
+						pageIndex: prev.pageIndex + 1,
+					}),
+					false,
+				);
+			};
+			const goToPreviousPage = () => {
+				updateSource(
+					source.key,
+					(prev) => {
+						if (prev.pageIndex === 0) return prev;
+						const nextStack = prev.cursorStack.slice(0, -1);
+						return {
+							...prev,
+							cursorStack: nextStack,
+							afterCursor: nextStack[nextStack.length - 1],
+							pageIndex: Math.max(0, prev.pageIndex - 1),
+						};
+					},
+					false,
+				);
+			};
+
+			out[source.key] = {
+				config: source,
+				result,
+				loading,
+				error,
+				filters: {
+					active: state?.filters ?? [],
+					set: setFilter,
+					remove: removeFilter,
+				},
+				sort: {
+					current: state?.sort ?? null,
+					set: setSort,
+				},
+				pagination: {
+					pageSize: state?.pageSize ?? defaultPageSize(source),
+					pageIndex: state?.pageIndex ?? 0,
+					hasNextPage: result?.pageInfo?.hasNextPage ?? false,
+					hasPreviousPage: (state?.pageIndex ?? 0) > 0,
+					setPageSize,
+					goToNextPage,
+					goToPreviousPage,
+				},
+			};
+		}
+		return out;
+	}, [config.sources, sourceStates, results, loading, error, updateSource]);
+
+	const scopeLocked = lockedScope !== undefined;
+
+	return useMemo(
+		() => ({
+			q,
+			setQ,
+			scope,
+			setScope,
+			scopeLocked,
+			sources: controllers,
+			loading,
+			error,
+			resetAll,
+		}),
+		[q, setQ, scope, setScope, scopeLocked, controllers, loading, error, resetAll],
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Public API for the search feature.
+ *
+ * Most apps only need:
+ *   ```tsx
+ *   import { Search, config } from ".../features/search";
+ *   <Search config={config} />
+ *   ```
+ *
+ * For more control, drop down to primitives:
+ *   - {@link useSearch} hook + {@link SearchBar} + {@link SearchResults}
+ *   - {@link DefaultResultRow} / {@link DefaultFilterPanel} for opt-in defaults
+ *   - filter components (TextFilter, SelectFilter, ...) for custom sidebars
+ */
+
+// Drop-in wrapper (most common entry point)
+export { Search } from "./components/Search";
+
+// Primitives
+export { useSearch } from "./hooks/useSearch";
+export { useAsyncData } from "./hooks/useAsyncData";
+export { useDistinctValues } from "./hooks/useDistinctValues";
+
+export { SearchBar } from "./components/controls/SearchBar";
+export { SearchResults } from "./components/SearchResults";
+export { SourceSection } from "./components/SourceSection";
+export { SortControl } from "./components/controls/SortControl";
+export { PaginationControls } from "./components/controls/PaginationControls";
+export { ScopeSelector } from "./components/controls/ScopeSelector";
+export { ActiveFilters } from "./components/filters/ActiveFilters";
+export { DefaultResultRow } from "./components/results/DefaultResultRow";
+export { DefaultFilterPanel } from "./components/filters/DefaultFilterPanel";
+export {
+	FilterProvider,
+	FilterResetButton,
+	useFilterField,
+	useFilterPanel,
+} from "./components/filters/FilterContext";
+
+export { TextFilter } from "./components/filters/inputs/TextFilter";
+export { SelectFilter } from "./components/filters/inputs/SelectFilter";
+export { MultiSelectFilter } from "./components/filters/inputs/MultiSelectFilter";
+export { NumericRangeFilter } from "./components/filters/inputs/NumericRangeFilter";
+export { BooleanFilter } from "./components/filters/inputs/BooleanFilter";
+export { DateRangeFilter } from "./components/filters/inputs/DateRangeFilter";
+export { FilterFieldWrapper } from "./components/filters/inputs/FilterFieldWrapper";
+
+export { fieldValue } from "./utils/fieldUtils";
+export {
+	buildFilter,
+	buildGlobalQueryClause,
+	readSourceParams,
+	writeSourceParams,
+	GLOBAL_QUERY_KEY,
+} from "./utils/filterUtils";
+export type { ActiveFilterValue, FilterFieldConfig, FilterFieldType } from "./utils/filterUtils";
+export { buildOrderBy } from "./utils/sortUtils";
+export type { SortFieldConfig, SortState } from "./utils/sortUtils";
+
+export { buildSearchQuery } from "./queryBuilder";
+export type { SourceRequest, SearchQueryPayload } from "./queryBuilder";
+
+export { runSearch } from "./api/searchService";
+export { fetchDistinctValues } from "./api/distinctValuesService";
+export type { PicklistOption } from "./api/distinctValuesService";
+
+export { config } from "./loadConfig";
+
+export { ALL_SCOPE } from "./types";
+export type {
+	DisplayField,
+	SObjectSourceConfig,
+	SearchConfig,
+	SourceController,
+	SourceResult,
+	SourcePageInfo,
+	SearchHandle,
+	SearchScope,
+	RenderResultFn,
+} from "./types";

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/loadConfig.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed re-export of the static config.json that ships with the feature.
+ *
+ * Application code:
+ *   import { config } from ".../features/search/loadConfig";
+ *   const handle = useSearch(config);
+ *
+ * To customize, edit `config.json` directly (no code changes required).
+ */
+
+import rawConfig from "./config.json";
+import type { SearchConfig } from "./types";
+
+export const config: SearchConfig = rawConfig as SearchConfig;

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/queryBuilder.ts

@@ -0,0 +1,156 @@
+/**
+ * Builds a single multi-aliased GraphQL document for search.
+ *
+ * Each SObject source becomes one aliased child of `uiapi.query`, with its own
+ * `first / after / where / orderBy` variables. Variable names are
+ * `${sourceKey}_first` etc. so two sources with similar names never collide.
+ *
+ * Selection sets are generated from `displayFields`:
+ *   - string `"Name"` → `Name @optional { value displayValue }`
+ *   - `{ name, raw: true }` → `Name`
+ *   - `{ name, subfields }` → nested `Name @optional { ... }`
+ *
+ * The `idField` (default "Id") is always emitted; it is **not** wrapped
+ * because uiapi's Id is a scalar.
+ */
+
+import { buildFilter, buildGlobalQueryClause, type ActiveFilterValue } from "./utils/filterUtils";
+import { buildOrderBy, type SortState } from "./utils/sortUtils";
+import type { DisplayField, SObjectSourceConfig } from "./types";
+
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function assertValidKey(key: string): void {
+	if (!KEY_PATTERN.test(key)) {
+		throw new Error(
+			`Invalid source key "${key}". Must match /^[A-Za-z_][A-Za-z0-9_]*$/ to be a valid GraphQL alias and variable prefix.`,
+		);
+	}
+}
+
+export interface SearchQueryPayload {
+	document: string;
+	variables: Record<string, unknown>;
+}
+
+export interface SourceRequest {
+	source: SObjectSourceConfig;
+	q: string;
+	filters: ActiveFilterValue[];
+	sort: SortState | null;
+	pageSize: number;
+	afterCursor: string | undefined;
+}
+
+/**
+ * Combines a per-source structured-filter clause with the global-q `or` clause.
+ * Returns `undefined` when neither side has any constraints.
+ */
+function buildSourceWhere(
+	source: SObjectSourceConfig,
+	q: string,
+	filters: ActiveFilterValue[],
+): unknown {
+	const clauses: unknown[] = [];
+	const globalClause = buildGlobalQueryClause(q, source.searchableFields);
+	if (globalClause) clauses.push(globalClause);
+	const structured = buildFilter(filters, source.filterFields ?? []);
+	if (structured) clauses.push(structured);
+	if (clauses.length === 0) return undefined;
+	if (clauses.length === 1) return clauses[0];
+	return { and: clauses };
+}
+
+/** Builds the multi-aliased query document and a flat variables map. */
+export function buildSearchQuery(requests: SourceRequest[]): SearchQueryPayload {
+	if (requests.length === 0) {
+		throw new Error("buildSearchQuery requires at least one source request");
+	}
+
+	const variableDeclarations: string[] = [];
+	const querySelections: string[] = [];
+	const variables: Record<string, unknown> = {};
+
+	for (const request of requests) {
+		const { source } = request;
+		assertValidKey(source.key);
+
+		const firstVar = `${source.key}_first`;
+		const afterVar = `${source.key}_after`;
+		const whereVar = `${source.key}_where`;
+		const orderByVar = `${source.key}_orderBy`;
+		const whereType = source.whereTypeName ?? `${source.objectName}_Filter`;
+		const orderByType = source.orderByTypeName ?? `${source.objectName}_OrderBy`;
+
+		variableDeclarations.push(
+			`$${firstVar}: Int`,
+			`$${afterVar}: String`,
+			`$${whereVar}: ${whereType}`,
+			`$${orderByVar}: ${orderByType}`,
+		);
+
+		querySelections.push(
+			`${source.key}: ${source.objectName}(` +
+				`first: $${firstVar}, ` +
+				`after: $${afterVar}, ` +
+				`where: $${whereVar}, ` +
+				`orderBy: $${orderByVar}` +
+				`) {\n` +
+				buildSelectionBody(source) +
+				`\n}`,
+		);
+
+		variables[firstVar] = request.pageSize;
+		variables[afterVar] = request.afterCursor ?? null;
+		variables[whereVar] = buildSourceWhere(source, request.q, request.filters) ?? null;
+		variables[orderByVar] = buildOrderBy(request.sort) ?? null;
+	}
+
+	const document =
+		`query Search(${variableDeclarations.join(", ")}) {\n` +
+		`  uiapi {\n` +
+		`    query {\n` +
+		querySelections.map((s) => indent(s, "      ")).join("\n") +
+		`\n    }\n` +
+		`  }\n` +
+		`}\n`;
+
+	return { document, variables };
+}
+
+function buildSelectionBody(source: SObjectSourceConfig): string {
+	const idField = source.idField ?? "Id";
+	const fieldLines = [`    ${idField}`];
+	for (const field of source.displayFields) {
+		fieldLines.push(...renderField(field, "    "));
+	}
+	return [
+		`  edges { node {`,
+		...fieldLines,
+		`  } }`,
+		`  pageInfo { hasNextPage hasPreviousPage startCursor endCursor }`,
+		`  totalCount`,
+	].join("\n");
+}
+
+function renderField(field: DisplayField, indentStr: string): string[] {
+	if (typeof field === "string") {
+		return [`${indentStr}${field} @optional { value displayValue }`];
+	}
+	if ("raw" in field) {
+		return [`${indentStr}${field.name}`];
+	}
+	const lines = [`${indentStr}${field.name} @optional {`];
+	for (const sub of field.subfields) {
+		lines.push(...renderField(sub, indentStr + "  "));
+	}
+	lines.push(`${indentStr}}`);
+	return lines;
+}
+
+function indent(s: string, prefix: string): string {
+	return s
+		.split("\n")
+		.map((line) => prefix + line)
+		.join("\n");
+}