@salesforce/templates 66.13.5 → 66.13.7

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/adapters/sobject/queryFragment.ts

@@ -0,0 +1,141 @@
+/**
+ * SObject fragment builder.
+ *
+ * Extracted verbatim from `queryBuilder.ts`: `buildSelectionBody`,
+ * `renderField`, `buildSourceWhere`, `assertValidKey`, `KEY_PATTERN`, and the
+ * per-source variable/selection assembly. Emits one `QueryFragmentContribution`
+ * with `placement: "uiapi.query"` — the `${key}: ${objectName}(...) { … }`
+ * selection, its 4 per-source variable declarations, and their 4 values.
+ *
+ * Behaviour is byte-for-byte equivalent to the original inline logic; this is a
+ * move, not a rewrite.
+ *
+ * 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 } from "../../utils/sortUtils";
+import type { DisplayField, SObjectSourceConfig } from "../../types";
+import type { QueryFragmentContribution, SourceRequest } 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.`,
+		);
+	}
+}
+
+/**
+ * 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.filterBy ?? []);
+	if (structured) clauses.push(structured);
+	if (clauses.length === 0) return undefined;
+	if (clauses.length === 1) return clauses[0];
+	return { and: clauses };
+}
+
+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;
+}
+
+/**
+ * Builds one SObject source's `QueryFragmentContribution`.
+ *
+ * The fragment is the `${key}: ${objectName}(...) { … }` selection that lives
+ * inside `uiapi.query`; the 4 declarations/values are the per-source
+ * `first / after / where / orderBy` variables. Output matches the original
+ * inline builder exactly.
+ */
+export function buildSObjectFragment(
+	request: SourceRequest<SObjectSourceConfig>,
+): QueryFragmentContribution {
+	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`;
+
+	const variableDeclarations = [
+		`$${firstVar}: Int`,
+		`$${afterVar}: String`,
+		`$${whereVar}: ${whereType}`,
+		`$${orderByVar}: ${orderByType}`,
+	];
+
+	const fragment =
+		`${source.key}: ${source.objectName}(` +
+		`first: $${firstVar}, ` +
+		`after: $${afterVar}, ` +
+		`where: $${whereVar}, ` +
+		`orderBy: $${orderByVar}` +
+		`) {\n` +
+		buildSelectionBody(source) +
+		`\n}`;
+
+	const variables: Record<string, unknown> = {
+		[firstVar]: request.pageSize,
+		[afterVar]: request.afterCursor ?? null,
+		[whereVar]: buildSourceWhere(source, request.q, request.filters) ?? null,
+		[orderByVar]: buildOrderBy(request.sort) ?? null,
+	};
+
+	return {
+		variableDeclarations,
+		variables,
+		placement: "uiapi.query",
+		fragment,
+	};
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/adapters/types.ts

@@ -0,0 +1,101 @@
+/**
+ * Kind-agnostic adapter contracts for unified (multi-source) search.
+ *
+ * Every searchable backend ("sobject", "cms", …) is fronted by a
+ * {@link SourceAdapter}. The core query builder and result parser are
+ * completely kind-agnostic: they dispatch to the adapter registered for a
+ * source's `kind`, so a new backend plugs in by adding a `kind` + an adapter,
+ * never by touching the common builder/parser or any consumer.
+ *
+ *  - {@link SourceAdapter.buildRequest} contributes a {@link QueryFragmentContribution}
+ *    (its GraphQL fragment, variable declarations, and variable values) that the
+ *    builder assembles into one combined document.
+ *  - {@link SourceAdapter.parseResponse} receives the full response `data` root
+ *    and extracts this source's `SourceResult`, returning `null` (never
+ *    throwing) when its own subtree is absent or errored — this is what lets
+ *    sources fail independently (partial-failure resilience).
+ */
+
+import type { SourceConfig, SourceResult } from "../types";
+import type { ActiveFilterValue } from "../utils/filterUtils";
+import type { SortState } from "../utils/sortUtils";
+
+/**
+ * One source's contribution to the combined GraphQL document.
+ *
+ * The builder concatenates every source's `variableDeclarations` into the
+ * `query Search(...)` header and merges every source's `variables` into one
+ * flat map. Fragments are placed by `placement`:
+ *   - `"uiapi.query"` → inside the shared `uiapi { query { … } }` block.
+ *   - `"root"`        → a sibling of `uiapi` at the document root (e.g. the CMS
+ *     `managed_content { … }` block).
+ *
+ * A contribution MAY declare zero extra variables (e.g. the CMS bootstrap call
+ * omits `$cmsContentTypeFQNs` entirely). The builder handles declaration lists of
+ * differing lengths, so an unused/undeclared variable is never emitted.
+ */
+export interface QueryFragmentContribution {
+	/** Namespaced GraphQL variable declarations, e.g. `"$cmsKeyword: String!"`. */
+	variableDeclarations: string[];
+	/** Values for the declared variables, keyed by (unprefixed) variable name. */
+	variables: Record<string, unknown>;
+	/** Where the `fragment` is spliced into the combined document. */
+	placement: "uiapi.query" | "root";
+	/** The GraphQL selection fragment (unindented; the builder indents it). */
+	fragment: string;
+}
+
+/**
+ * A per-source search request. Generic over the source config so an adapter can
+ * narrow to its own config kind (e.g. `SourceRequest<CmsSourceConfig>`).
+ *
+ * The base fields (`source`/`q`/`filters`/`sort`/`pageSize`/`afterCursor`) are
+ * kind-agnostic. The trailing fields are optional and only populated for the
+ * kinds that need them; the sync query builder never resolves async values, so
+ * anything async (e.g. the CMS UIBundle id) is resolved by the caller and
+ * threaded in here.
+ */
+export interface SourceRequest<T extends SourceConfig = SourceConfig> {
+	/** The config for the source this request targets. */
+	source: T;
+	/** The global search term, broadcast to every source. */
+	q: string;
+	/** Active structured filters (SObject-relevant; other kinds may ignore). */
+	filters: ActiveFilterValue[];
+	/** Active sort (SObject-relevant; other kinds may ignore). */
+	sort: SortState | null;
+	/** Page size for this fetch (validated against `pageSizeOptions` upstream). */
+	pageSize: number;
+	/** Opaque forward cursor for this fetch (CMS decodes it to an offset). */
+	afterCursor: string | undefined;
+	/**
+	 * CMS-only, optional. Present (non-null, non-empty) only when content types
+	 * are known/selected; absent on the bootstrap call so the CMS adapter omits
+	 * `$cmsContentTypeFQNs` entirely.
+	 */
+	contentTypes?: string[] | null;
+	/**
+	 * CMS-only, optional. The resolved UIBundle id fed into the CMS search
+	 * query. Resolved by the caller (async `getUIBundleId()`) BEFORE the sync
+	 * query builder runs, then threaded in here so `buildRequest` stays
+	 * synchronous. Ignored by non-CMS adapters.
+	 */
+	uiBundleId?: string;
+}
+
+/**
+ * Runtime adapter for one source `kind`. Bridges a kind-agnostic
+ * {@link SourceRequest} to a GraphQL fragment and back to a {@link SourceResult}.
+ */
+export interface SourceAdapter<T extends SourceConfig = SourceConfig> {
+	/** The `kind` discriminator this adapter handles. */
+	readonly kind: T["kind"];
+	/** Build this source's fragment/variables contribution for the combined doc. */
+	buildRequest(request: SourceRequest<T>): QueryFragmentContribution;
+	/**
+	 * Extract this source's result from the full response `data` root. Returns
+	 * `null` when the source's own subtree is absent or errored — never throws
+	 * for a partial failure.
+	 */
+	parseResponse(root: Record<string, unknown>, request: SourceRequest<T>): SourceResult | null;
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/api/distinctValuesService.ts

@@ -0,0 +1,84 @@
+/**
+ * Fetches distinct values for a picklist field via the uiapi aggregate
+ * `groupBy` query.
+ *
+ * Used by the auto-render pathway when a picklist filter does not declare
+ * inline `options`. Each call hits the GraphQL endpoint once and returns the
+ * sorted set of distinct values plus their display labels.
+ */
+
+import { createDataSDK } from "@salesforce/platform-sdk";
+
+export interface PicklistOption {
+	value: string;
+	label: string;
+}
+
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function assertValidIdentifier(name: string, kind: string): void {
+	if (!KEY_PATTERN.test(name)) {
+		throw new Error(
+			`Invalid ${kind} "${name}". Must match /^[A-Za-z_][A-Za-z0-9_]*$/ to be a valid GraphQL identifier.`,
+		);
+	}
+}
+
+/**
+ * Builds and executes a `uiapi.aggregate.<objectName>(groupBy: { <field>: { group: true } })`
+ * query and extracts the distinct values.
+ */
+export async function fetchDistinctValues(
+	objectName: string,
+	fieldName: string,
+): Promise<PicklistOption[]> {
+	assertValidIdentifier(objectName, "objectName");
+	assertValidIdentifier(fieldName, "fieldName");
+
+	const document = `query DistinctValues {
+		uiapi {
+			aggregate {
+				${objectName}(groupBy: { ${fieldName}: { group: true } }) {
+					edges {
+						node {
+							aggregate @optional {
+								${fieldName} @optional {
+									value
+									displayValue
+									label
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}`;
+
+	const data = await createDataSDK();
+	const response = await data.graphql!.query<unknown>({ query: document });
+
+	if (response.errors?.length) {
+		throw new Error(response.errors.map((e) => e.message).join("; "));
+	}
+
+	const root = response.data as Record<string, unknown> | undefined;
+	const aggregate = (root?.uiapi as Record<string, unknown> | undefined)?.aggregate as
+		| Record<string, unknown>
+		| undefined;
+	const objectAgg = aggregate?.[objectName] as
+		| { edges?: Array<{ node?: { aggregate?: Record<string, unknown> } }> }
+		| undefined;
+	const edges = objectAgg?.edges ?? [];
+
+	return edges
+		.map((edge) => {
+			const field = edge?.node?.aggregate?.[fieldName] as
+				| { value?: string | null; displayValue?: string | null; label?: string | null }
+				| undefined;
+			const value = field?.value;
+			if (value == null || value === "") return null;
+			return { value, label: field?.label ?? field?.displayValue ?? value };
+		})
+		.filter((opt): opt is PicklistOption => opt !== null);
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/api/searchService.ts

@@ -0,0 +1,136 @@
+/**
+ * Executes a combined search request and parses each source's subtree via its
+ * adapter, with partial-failure resilience.
+ *
+ * The combined GraphQL response can carry BOTH partial `data` AND `errors`
+ * (`uiapi` and CMS `managed_content` are independent roots). Rather than
+ * throwing on `response.errors`, we parse each source through
+ * `getAdapter(kind).parseResponse(root, req)`:
+ *   - a `SourceResult` → recorded in `results[key]`.
+ *   - `null` (subtree absent/errored) → the source produced no data; if the
+ *     request as a whole reported GraphQL errors, an attributed message is
+ *     recorded in `errors[key]` so the UI can show a per-source error while
+ *     sibling sources still render.
+ *
+ * Only a whole-request failure — the SDK call rejecting, or a response with no
+ * `data` at all — throws, so `useSearch` surfaces it as a page-level error
+ * (preserving the original network-failure behaviour).
+ */
+
+import { createDataSDK } from "@salesforce/platform-sdk";
+import { buildSearchQuery } from "../queryBuilder";
+import { getAdapter } from "../adapters/registry";
+import type { SourceRequest } from "../adapters/types";
+import type { SourceResult } from "../types";
+
+/**
+ * The outcome of a combined `runSearch`: successfully-parsed results plus a
+ * per-source error map. `errors` is keyed by `source.key` and only carries an
+ * entry for a source that failed to produce data (its subtree was absent or
+ * errored). A source appears in at most one of `results` / `errors`.
+ */
+export interface RunSearchOutcome {
+	results: Record<string, SourceResult>;
+	errors: Record<string, string>;
+}
+
+/** Minimal shape of a GraphQL error we can attribute to a source by path. */
+interface GraphQLErrorLike {
+	message?: string | null;
+	path?: Array<string | number> | null;
+}
+
+/**
+ * Attributes GraphQL errors to a source by matching the error `path` against
+ * the source's location in the document:
+ *   - SObject aliases live under `uiapi.query.<key>`.
+ *   - CMS lives under the root `managed_content` block.
+ *
+ * Returns the joined messages whose `path` matches `request`. When NO path
+ * matches (or paths are absent), returns a GENERIC per-source message rather
+ * than echoing unrelated sources' messages — otherwise one source could display
+ * another's error text (over-broad cross-attribution). The whole-request
+ * (`data == null`) path still joins ALL error messages; that lives in
+ * `runSearch` and is unaffected.
+ */
+function attributeError(request: SourceRequest, errors: GraphQLErrorLike[]): string {
+	const kind = request.source.kind;
+	const key = request.source.key;
+
+	const matched = errors.filter((e) => {
+		const path = e.path;
+		if (!path || path.length === 0) return false;
+		if (kind === "cms") {
+			return path[0] === "managed_content";
+		}
+		// SObject: uiapi -> query -> <key>
+		return path[0] === "uiapi" && path[1] === "query" && path[2] === key;
+	});
+
+	// No path matched this source: don't leak sibling sources' messages — fall
+	// back to a generic per-source explanation.
+	if (matched.length === 0) {
+		return "Search failed for this source.";
+	}
+
+	const message = matched
+		.map((e) => e.message)
+		.filter((m): m is string => !!m)
+		.join("; ");
+	return message || "Search failed for this source.";
+}
+
+/**
+ * Runs one combined multi-source GraphQL request. Returns `{ results, errors }`
+ * (never throws on partial GraphQL errors); throws only on a whole-request /
+ * network failure.
+ */
+export async function runSearch(requests: SourceRequest[]): Promise<RunSearchOutcome> {
+	const { document, variables } = buildSearchQuery(requests);
+
+	const data = await createDataSDK();
+	const response = await data.graphql!.query<unknown, Record<string, unknown>>({
+		query: document,
+		variables,
+	});
+
+	const root = response.data as Record<string, unknown> | undefined;
+	const gqlErrors = (response.errors ?? []) as GraphQLErrorLike[];
+
+	// Whole-request failure: no data at all. Surface as a page-level error
+	// (preserves the original network-failure behaviour).
+	if (root == null) {
+		const message = gqlErrors
+			.map((e) => e.message)
+			.filter((m): m is string => !!m)
+			.join("; ");
+		throw new Error(message || "Unified search failed");
+	}
+
+	const results: Record<string, SourceResult> = {};
+	const errors: Record<string, string> = {};
+
+	for (const request of requests) {
+		const key = request.source.key;
+		let parsed: SourceResult | null = null;
+		try {
+			parsed = getAdapter(request.source.kind).parseResponse(root, request);
+		} catch {
+			// An adapter that throws while parsing its own subtree is a
+			// per-source failure, not a page-level one.
+			parsed = null;
+		}
+
+		if (parsed != null) {
+			results[key] = parsed;
+		} else if (gqlErrors.length > 0) {
+			// No data for this source AND the request reported errors — attribute
+			// a message so the UI can show a per-source error.
+			errors[key] = attributeError(request, gqlErrors);
+		}
+		// else: no data and no errors — the source simply returned nothing;
+		// leave it absent from both maps (empty result, no error).
+	}
+
+	return { results, errors };
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/components/GlobalSearchBox.tsx

@@ -0,0 +1,98 @@
+/**
+ * GlobalSearchBox — pure launcher component for global search.
+ *
+ * A self-contained search input + button that navigates to `/search?q=...`
+ * when the user submits a query of at least MIN_QUERY_LENGTH characters.
+ *
+ * Props are purely cosmetic (className, placeholder, autoFocus) — all behavior
+ * (the gate, the route, the query key) is owned by this component, not the caller.
+ *
+ * Usage:
+ * ```tsx
+ * import { GlobalSearchBox } from "../features/search";
+ * <GlobalSearchBox className="mb-8" placeholder="Search everything..." />
+ * ```
+ */
+
+import { Search } from "lucide-react";
+import { useId, useState } from "react";
+import { useNavigate } from "react-router";
+import { Input } from "../../../components/ui/input";
+import { Button } from "../../../components/ui/button";
+import { GLOBAL_QUERY_KEY } from "../utils/filterUtils";
+import { MIN_QUERY_LENGTH } from "../constants";
+
+export interface GlobalSearchBoxProps {
+	/** Optional CSS class for container styling/placement. */
+	className?: string;
+	/** Placeholder text for the search input. */
+	placeholder?: string;
+	/** Whether the input should autofocus on mount. */
+	autoFocus?: boolean;
+	/**
+	 * Accessible (screen-reader) label for the input. Exposed as a prop so
+	 * callers can localize it; defaults to English. */
+	label?: string;
+	/** Visible text for the submit button. Exposed for localization. */
+	submitLabel?: string;
+	/**
+	 * Minimum length of keyword required by search. `{min}` is replaced with
+	 * {@link MIN_QUERY_LENGTH}. Exposed for localization. */
+	minLengthHint?: string;
+}
+
+export function GlobalSearchBox({
+	className,
+	placeholder = "Search…",
+	autoFocus,
+	label = "Search",
+	submitLabel = "Search",
+	minLengthHint = "Enter at least {min} characters to search.",
+}: GlobalSearchBoxProps) {
+	const navigate = useNavigate();
+	const [text, setText] = useState("");
+	const inputId = useId();
+	const hintId = useId();
+
+	const canSearch = text.trim().length >= MIN_QUERY_LENGTH;
+	const hintText = minLengthHint.replace("{min}", String(MIN_QUERY_LENGTH));
+
+	const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+		e.preventDefault();
+		if (!canSearch) return;
+		const params = `?${GLOBAL_QUERY_KEY}=${encodeURIComponent(text.trim())}`;
+		navigate(`/search${params}`);
+	};
+
+	return (
+		<form onSubmit={handleSubmit} className={className} role="search">
+			<label htmlFor={inputId} className="sr-only">
+				{label}
+			</label>
+			<div className="flex gap-2">
+				<div className="relative flex-1">
+					<Search
+						aria-hidden="true"
+						className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground"
+					/>
+					<Input
+						id={inputId}
+						type="text"
+						value={text}
+						onChange={(e) => setText(e.target.value)}
+						placeholder={placeholder}
+						autoFocus={autoFocus}
+						className="pl-9"
+						aria-describedby={hintId}
+					/>
+				</div>
+				<Button type="submit" disabled={!canSearch}>
+					{submitLabel}
+				</Button>
+			</div>
+			<p id={hintId} className="sr-only">
+				{hintText}
+			</p>
+		</form>
+	);
+}