@salesforce/templates 66.17.5 → 66.18.0

package/lib/templates/project/vueinternalapp/_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/vueinternalapp/_p_/_m_/_w_/_a_/src/_f_/search/adapters/types.ts

@@ -0,0 +1,103 @@
+/**
+ * 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;
+	/** CMS-only, optional. The current user's language tag fed to the CMS search `language` argument. */
+	language?: 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/vueinternalapp/_p_/_m_/_w_/_a_/src/_f_/search/api/distinctValuesService.ts

@@ -0,0 +1,81 @@
+/**
+ * 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/vueinternalapp/_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/vueinternalapp/_p_/_m_/_w_/_a_/src/_f_/search/components/GlobalSearchBox.types.ts

@@ -0,0 +1,18 @@
+/** Props for `<GlobalSearchBox>` (kept in a .ts module so plain `tsc` can import the type). */
+export interface GlobalSearchBoxProps {
+	/** Optional CSS class for container styling/placement. */
+	class?: 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 for localization. */
+	label?: string;
+	/** Visible text for the submit button. Exposed for localization. */
+	submitLabel?: string;
+	/**
+	 * Minimum length of keyword required by search. `{min}` is replaced with
+	 * MIN_QUERY_LENGTH. Exposed for localization.
+	 */
+	minLengthHint?: string;
+}

package/lib/templates/project/vueinternalapp/_p_/_m_/_w_/_a_/src/_f_/search/components/GlobalSearchBox.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+/**
+ * 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 (class, placeholder, autoFocus, localization
+ * strings) — all behavior (the gate, the route, the query key) is owned by this
+ * component, not the caller.
+ *
+ * Usage:
+ *   <GlobalSearchBox class="mb-8" placeholder="Search everything..." />
+ */
+import { computed, onMounted, ref, useId, useTemplateRef } from "vue";
+import { useRouter } from "vue-router";
+import { Search } from "@lucide/vue";
+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";
+import type { GlobalSearchBoxProps } from "./GlobalSearchBox.types";
+
+const props = withDefaults(defineProps<GlobalSearchBoxProps>(), {
+	placeholder: "Search…",
+	label: "Search",
+	submitLabel: "Search",
+	minLengthHint: "Enter at least {min} characters to search.",
+});
+
+const router = useRouter();
+const text = ref("");
+const inputId = useId();
+const hintId = useId();
+const inputRef = useTemplateRef<{ $el: HTMLInputElement }>("inputRef");
+
+onMounted(() => {
+	if (props.autoFocus) inputRef.value?.$el?.focus();
+});
+
+const canSearch = computed(() => text.value.trim().length >= MIN_QUERY_LENGTH);
+const hintText = computed(() => props.minLengthHint.replace("{min}", String(MIN_QUERY_LENGTH)));
+
+const handleSubmit = () => {
+	if (!canSearch.value) return;
+	void router.push(`/search?${GLOBAL_QUERY_KEY}=${encodeURIComponent(text.value.trim())}`);
+};
+</script>
+
+<template>
+	<form :class="$props.class" role="search" @submit.prevent="handleSubmit">
+		<label :for="inputId" class="sr-only">{{ label }}</label>
+		<div class="flex gap-2">
+			<div class="relative flex-1">
+				<Search
+					aria-hidden="true"
+					class="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground"
+				/>
+				<Input
+					:id="inputId"
+					ref="inputRef"
+					v-model="text"
+					type="text"
+					:placeholder="placeholder"
+					class="pl-9"
+					:aria-describedby="hintId"
+				/>
+			</div>
+			<Button type="submit" :disabled="!canSearch">{{ submitLabel }}</Button>
+		</div>
+		<p :id="hintId" class="sr-only">{{ hintText }}</p>
+	</form>
+</template>

package/lib/templates/project/vueinternalapp/_p_/_m_/_w_/_a_/src/_f_/search/components/MergedSearchResults.types.ts

@@ -0,0 +1,24 @@
+/** Props for `<MergedSearchResults>` (kept in a .ts module so plain `tsc` can import the type). */
+import type { SearchHandle } from "../types";
+import type { ResultRenderer } from "./results/resolveResultRenderer";
+
+export interface MergedSearchResultsProps {
+	handle: SearchHandle;
+	/**
+	 * Per source key: how to render one node in the merged grid. Falls back to
+	 * the built-in default row for any source without an entry. Pass `false` to
+	 * skip a source's cards entirely. The `#result` scoped slot is the
+	 * alternative for all sources.
+	 */
+	renderResult?: Record<string, ResultRenderer>;
+	/** Message shown when there are no results. Defaults to "No results found." */
+	emptyMessage?: string;
+	/** Message shown when the query is below MIN_QUERY_LENGTH. Defaults to "Start your search…" */
+	shortQueryMessage?: string;
+	/** Number of skeleton placeholders to show while loading. Defaults to `pageSize`. */
+	skeletonCount?: number;
+	/** Extra classes on the grid container. Defaults to a responsive 1/2/3-column grid. */
+	gridClassName?: string;
+	/** Extra classes on the outer wrapper. */
+	class?: string;
+}