@salesforce/templates 66.13.5 → 66.13.7

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

@@ -0,0 +1,294 @@
+/**
+ * Merged results layout — a single combined grid across every in-scope source,
+ * driven by one global pager over the cumulative result set.
+ *
+ * This is the counterpart to {@link SearchResults} (which renders one stacked
+ * section per source). Use it when you want a unified "search everything" grid:
+ * heterogeneous cards laid out together, one shared pagination control, and a
+ * single results count — the layout the drop-in `<Search>` renders when the
+ * config sets `pagination.mode: "merged"`, and the same shape most apps
+ * hand-build on top of `useSearch`.
+ *
+ * It reads three aggregate accessors off the {@link SearchHandle}
+ * (`mergedResults`, `globalPagination`, `inScopeSources`), so it honours the
+ * config's `pagination.mode` / `mergeOrder` automatically. For a true combined
+ * grid, pair it with `pagination.mode: "merged"` (see the feature README, §9).
+ *
+ * Layout, top to bottom:
+ *   - **Single-source filter chrome** — when the scope is narrowed to one
+ *     source (selected or `lockedScope`), that source's filter panel + sort +
+ *     active-filter chips render here. Under "All", per-source filters can't be
+ *     combined across heterogeneous objects, so this row is omitted.
+ *   - **Results count** — the cumulative in-scope total, on its own row directly
+ *     above the grid, in every scope. Hidden when there are no results.
+ *   - **The grid** — one card per `mergedResults` item, rendered via the
+ *     per-source `renderResult[sourceKey]` callback. In a mixed grid (2+ sources
+ *     in scope) each card is topped with an auto source badge — the source's
+ *     `labelSingular` (falling back to `label`), colored from a palette by its
+ *     config order — so heterogeneous results stay self-identifying with no
+ *     configuration. Skeletons while loading; an empty-state message when there
+ *     are none.
+ *   - **Global pager** — one {@link PaginationControls} over the cumulative set.
+ */
+
+import { AlertCircle } from "lucide-react";
+import { Alert, AlertDescription, AlertTitle } from "../../../components/ui/alert";
+import { Skeleton } from "../../../components/ui/skeleton";
+import { ActiveFilters } from "./filters/ActiveFilters";
+import { DefaultFilterPanel } from "./filters/DefaultFilterPanel";
+import { FilterProvider, FilterResetButton } from "./filters/FilterContext";
+import { PaginationControls } from "./controls/PaginationControls";
+import { SortControl } from "./controls/SortControl";
+import { resolveResultRenderer, type ResultRenderer } from "./results/resolveResultRenderer";
+import { ALL_SCOPE, type SearchHandle, type SourceController } from "../types";
+
+export interface MergedSearchResultsProps {
+	handle: SearchHandle;
+	/**
+	 * Per source key: how to render one node in the merged grid. Falls back to
+	 * the built-in {@link DefaultResultRow} for any source without an entry.
+	 * Pass `false` to skip a source's cards entirely.
+	 */
+	renderResult?: Record<string, ResultRenderer>;
+	/** Message shown when there are no results. Defaults to "No results found." */
+	emptyMessage?: 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. */
+	className?: string;
+}
+
+const DEFAULT_GRID_CLASS = "grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3";
+
+/**
+ * Palette for the auto source badges in a mixed grid. A source's color is its
+ * index in the config's `sources` array, wrapped around the palette — so badges
+ * stay stable and distinct without any per-source configuration. Add more
+ * entries here if you routinely mix more source types than there are colors.
+ */
+const BADGE_PALETTE = [
+	"bg-blue-100 text-blue-700",
+	"bg-amber-100 text-amber-700",
+	"bg-purple-100 text-purple-700",
+	"bg-pink-100 text-pink-700",
+	"bg-emerald-100 text-emerald-700",
+	"bg-sky-100 text-sky-700",
+] as const;
+
+export function MergedSearchResults({
+	handle,
+	renderResult,
+	emptyMessage,
+	skeletonCount,
+	gridClassName = DEFAULT_GRID_CLASS,
+	className,
+}: MergedSearchResultsProps) {
+	const { globalPagination: page, mergedResults, loading, error } = handle;
+
+	// A single source is in scope when the scope is narrowed (selected from the
+	// dropdown) or locked (`lockedScope` / restrictTo). Its filter chrome can
+	// render meaningfully; under "All" it can't (heterogeneous sources).
+	const singleSourceInScope = handle.scope !== ALL_SCOPE;
+	const soleController = singleSourceInScope ? handle.inScopeSources[0] : undefined;
+	// Per-card source badges only make sense when the grid is genuinely mixed —
+	// a single-source grid (narrowed or locked) has one type throughout.
+	const showSourceBadges = !singleSourceInScope;
+	// Assign each source a stable badge color by its declaration order. Badges
+	// only show in "All" scope, where `inScopeSources` is every source in config
+	// order, so the index here is the source's config position.
+	const badgeColorByKey: Record<string, string> = {};
+	handle.inScopeSources.forEach((controller, i) => {
+		badgeColorByKey[controller.config.key] = BADGE_PALETTE[i % BADGE_PALETTE.length];
+	});
+
+	const skeletons = skeletonCount ?? page.pageSize;
+
+	// Persistent, always-mounted live region: screen readers announce result
+	// updates (searching → count → empty → error) without an Enter keypress.
+	const liveMessage = loading
+		? "Searching…"
+		: error
+			? "Search failed."
+			: mergedResults.length === 0
+				? (emptyMessage ?? "No results found.")
+				: `${page.totalCount} result${page.totalCount === 1 ? "" : "s"}`;
+
+	return (
+		<div className={`space-y-6 ${className ?? ""}`}>
+			<p className="sr-only" role="status" aria-live="polite">
+				{liveMessage}
+			</p>
+
+			{soleController && <SingleSourceChrome controller={soleController} />}
+
+			{/* Page-level error — set only when every in-scope source failed (or a
+			    whole-request/network failure). Shown once, above the grid. */}
+			{error && (
+				<Alert variant="destructive" role="alert">
+					<AlertCircle />
+					<AlertTitle>Search failed</AlertTitle>
+					<AlertDescription>{error}</AlertDescription>
+				</Alert>
+			)}
+
+			{/* Per-source errors — a source that failed while a sibling succeeded
+			    surfaces its own banner without blanking the shared grid. Suppressed
+			    when the page-level error already covers the all-failed case. */}
+			{!error &&
+				handle.inScopeSources
+					.filter((c) => !!c.error)
+					.map((c) => (
+						<Alert key={c.config.key} variant="destructive" role="alert">
+							<AlertCircle />
+							<AlertTitle>Failed to load {c.config.label}</AlertTitle>
+							<AlertDescription>{c.error}</AlertDescription>
+						</Alert>
+					))}
+
+			{/* Results count — its own row, directly above the grid, in every scope.
+			    Hidden when there are none (the empty state covers that case). */}
+			{!loading && !error && page.totalCount > 0 && (
+				<p className="text-sm text-muted-foreground">
+					{page.totalCount} result{page.totalCount === 1 ? "" : "s"}
+				</p>
+			)}
+
+			{loading ? (
+				<div className={gridClassName}>
+					{Array.from({ length: Math.min(skeletons, 6) }, (_, i) => (
+						<Skeleton key={i} className="h-48 w-full rounded-lg" />
+					))}
+				</div>
+			) : mergedResults.length === 0 ? (
+				<p className="py-12 text-center text-sm text-muted-foreground">
+					{emptyMessage ?? "No results found."}
+				</p>
+			) : (
+				<ul className={gridClassName}>
+					{mergedResults.map(({ sourceKey, node }, i) => {
+						const source = handle.sources[sourceKey]?.config;
+						if (!source) return null;
+						// Resolve via the shared helper so CMS nodes render through
+						// CmsResultRow (never DefaultResultRow) in the merged grid too;
+						// a `renderResult[key]` override — including `false` — still wins.
+						const renderer = resolveResultRenderer(source, renderResult);
+						if (renderer === false) return null;
+						const rendered = renderer(node);
+						const badge =
+							showSourceBadges && source ? (
+								<SourceBadge
+									label={source.labelSingular ?? source.label}
+									colorClass={badgeColorByKey[sourceKey]}
+								/>
+							) : null;
+						return (
+							<li
+								key={getItemKey(sourceKey, node, i)}
+								className="flex flex-col gap-1.5 [&>:last-child]:min-h-0 [&>:last-child]:flex-1"
+							>
+								{badge}
+								{rendered}
+							</li>
+						);
+					})}
+				</ul>
+			)}
+
+			{page.totalCount > 0 && (
+				<PaginationControls
+					pageIndex={page.pageIndex}
+					pageCount={page.pageCount}
+					hasNextPage={page.hasNextPage}
+					hasPreviousPage={page.hasPreviousPage}
+					pageSize={page.pageSize}
+					pageSizeOptions={page.pageSizeOptions}
+					onNextPage={page.goToNextPage}
+					onPreviousPage={page.goToPreviousPage}
+					onGoToPage={page.goToPage}
+					onPageSizeChange={page.setPageSize}
+					disabled={loading || !!error}
+				/>
+			)}
+		</div>
+	);
+}
+
+function getItemKey(sourceKey: string, node: unknown, fallback: number): string {
+	const id = node && typeof node === "object" ? (node as { Id?: unknown }).Id : undefined;
+	return typeof id === "string" ? `${sourceKey}:${id}` : `${sourceKey}:${fallback}`;
+}
+
+interface SourceBadgeProps {
+	label: string;
+	colorClass: string;
+}
+
+/**
+ * Auto source badge shown above each card in a mixed grid — the source's
+ * `labelSingular` (falling back to `label`), colored from {@link BADGE_PALETTE}
+ * by its config order. Identifies which object type a heterogeneous card came
+ * from with no per-app config.
+ */
+function SourceBadge({ label, colorClass }: SourceBadgeProps) {
+	return (
+		<span className={`w-fit rounded-full px-2.5 py-0.5 text-xs font-medium ${colorClass}`}>
+			{label}
+		</span>
+	);
+}
+
+interface SingleSourceChromeProps {
+	controller: SourceController;
+}
+
+/**
+ * Filter panel + sort + active-filter chips for the one source in scope. Shown
+ * whenever the search is narrowed to a single object (selected or locked).
+ * Hidden under "All", where heterogeneous per-source filters can't be combined.
+ */
+function SingleSourceChrome({ controller }: SingleSourceChromeProps) {
+	const { config: source, filters, sort } = controller;
+	// Filter/sort chrome is SObject-only — narrow on `kind` so the union widening
+	// doesn't regress SObject behavior. CMS sources render no filter/sort chrome.
+	const sObjectSource = source.kind === "sobject" ? source : null;
+	const sortBy = sObjectSource?.sortBy;
+	const showFilterPanel = (sObjectSource?.filterBy?.length ?? 0) > 0;
+	const showSortControl = (sortBy?.length ?? 0) > 0;
+	const showActiveChips = filters.active.length > 0;
+
+	if (!showFilterPanel && !showSortControl && !showActiveChips) return null;
+
+	return (
+		<div className="flex flex-col gap-4">
+			{showFilterPanel && sObjectSource && (
+				<FilterProvider
+					filters={filters.active}
+					onFilterChange={filters.set}
+					onFilterRemove={filters.remove}
+					onReset={() => filters.active.forEach((f) => filters.remove(f.field))}
+				>
+					<div className="rounded-md border p-3 space-y-3">
+						<div className="flex items-center justify-between">
+							<h2 className="text-sm font-semibold">Filters</h2>
+							<FilterResetButton size="sm" />
+						</div>
+						<div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
+							<DefaultFilterPanel source={sObjectSource} />
+						</div>
+					</div>
+				</FilterProvider>
+			)}
+
+			{(showSortControl || showActiveChips) && (
+				<div className="flex flex-wrap items-center gap-2">
+					{showSortControl && sortBy && (
+						<SortControl configs={sortBy} sort={sort.current} onSortChange={sort.set} />
+					)}
+					{showActiveChips && <ActiveFilters filters={filters.active} onRemove={filters.remove} />}
+				</div>
+			)}
+		</div>
+	);
+}

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

@@ -0,0 +1,203 @@
+/**
+ * Drop-in search component. Given a `SearchConfig`, renders a complete
+ * search experience: search bar, an aggregate result count, and results.
+ *
+ * The results layout follows the config's pagination mode — no separate prop:
+ *   - `pagination.mode: "per-source"` (default): one stacked section per
+ *     source, each with its own filters, sort, and pagination.
+ *   - `pagination.mode: "merged"`: a single combined grid across every in-scope
+ *     source, driven by one global pager over the cumulative result set (with a
+ *     results count and, under a single scope, that source's filter chrome).
+ *
+ * The simplest possible integration:
+ *
+ * ```tsx
+ * import { Search, config } from ".../features/search";
+ * export default function MySearchPage() {
+ *   return <Search config={config} />;
+ * }
+ * ```
+ *
+ * Override slots:
+ *   - `renderResult[sourceKey]` — replace the default row renderer for one
+ *     source. Pass `false` to hide that source entirely.
+ *   - `renderFilters[sourceKey]` — replace the default filter sidebar for
+ *     one source. Pass `false` to suppress filters for that source.
+ *   - `renderHeader` — replace the default header (title + subtitle).
+ *   - `searchPlaceholder` — placeholder text for the search input.
+ *   - `title`, `subtitle` — defaults passed to the built-in header.
+ */
+
+import { useMemo, type ReactNode } from "react";
+import { AlertCircle } from "lucide-react";
+import { Alert, AlertDescription, AlertTitle } from "../../../components/ui/alert";
+import { useSearch } from "../hooks/useSearch";
+import { SearchBar } from "./controls/SearchBar";
+import { ScopeSelector } from "./controls/ScopeSelector";
+import { SearchResults } from "./SearchResults";
+import { MergedSearchResults } from "./MergedSearchResults";
+import { ALL_SCOPE } from "../types";
+import type { SearchConfig, SearchHandle, SObjectSourceConfig } from "../types";
+
+type ResultRenderer = ((node: unknown) => ReactNode) | false;
+type FilterRenderer = (() => ReactNode) | false;
+
+/**
+ * Locks the search to a single source. Reuses the same shared `config.json`
+ * but shows only results matching the given (kind, key) tuple.
+ *
+ * When set:
+ *   - The scope dropdown is hidden.
+ *   - URL `?scope=` is not written (the page route already implies the source).
+ *   - Only the matching source is fetched and rendered.
+ */
+export interface RestrictTo {
+	kind: SObjectSourceConfig["kind"];
+	key: string;
+}
+
+interface SearchProps {
+	config: SearchConfig;
+	renderResult?: Record<string, ResultRenderer>;
+	renderFilters?: Record<string, FilterRenderer>;
+	emptyMessages?: Record<string, string>;
+	searchPlaceholder?: string;
+	title?: string;
+	subtitle?: string;
+	/**
+	 * Lock the search to a single source by `(kind, key)`. Hides the scope
+	 * dropdown and forces results to that one source. Useful for embedding
+	 * a single-object search inside a page where the source is implicit.
+	 */
+	restrictTo?: RestrictTo;
+	/**
+	 * Show the source-scope dropdown next to the search bar.
+	 * Defaults to `true` when the config has 2+ sources, `false` otherwise
+	 * (a one-source dropdown would be redundant). Always hidden when
+	 * `restrictTo` is set.
+	 */
+	showScopeSelector?: boolean;
+	/** Label for the "search everything" entry in the scope dropdown. */
+	allScopeLabel?: string;
+	/** Optional override for the entire header region. */
+	renderHeader?: (handle: SearchHandle) => ReactNode;
+	className?: string;
+}
+
+export function Search({
+	config,
+	renderResult,
+	renderFilters,
+	emptyMessages,
+	searchPlaceholder = "Search…",
+	title = "Search",
+	subtitle,
+	restrictTo,
+	showScopeSelector,
+	allScopeLabel,
+	renderHeader,
+	className,
+}: SearchProps) {
+	// Resolve restrictTo to a lockedScope value, surfacing a clear error if
+	// the (kind, key) pair doesn't match any source. Memoize so it's
+	// stable across renders.
+	const lockedScope = useMemo<string | undefined>(() => {
+		if (!restrictTo) return undefined;
+		const match = config.sources.find(
+			(s) => s.kind === restrictTo.kind && s.key === restrictTo.key,
+		);
+		if (!match) {
+			console.warn(
+				`<Search restrictTo>: no source with kind="${restrictTo.kind}" and key="${restrictTo.key}" in config. Falling back to "all".`,
+			);
+			return undefined;
+		}
+		return match.key;
+	}, [restrictTo, config.sources]);
+
+	const handle = useSearch(config, { lockedScope });
+	// The results layout follows the pagination mode — a "merged" config means a
+	// single combined grid, "per-source" (default) means one section per source.
+	// There is no separate `layout` prop: the two would only ever be set in lockstep.
+	const merged = config.pagination?.mode === "merged";
+	const totalResults = Object.values(handle.sources).reduce(
+		(acc, controller) => acc + (controller.result?.totalCount ?? 0),
+		0,
+	);
+	const shouldShowScope = !handle.scopeLocked && (showScopeSelector ?? config.sources.length >= 2);
+	// The aggregate count is only meaningful when results from more than one
+	// source are combined. With a single configured source, a locked scope, or
+	// a specific source picked in the dropdown, exactly one source is on screen
+	// and that source's own section already shows its count — so suppress the
+	// redundant total here.
+	const sourcesInScope = handle.scope === ALL_SCOPE ? config.sources.length : 1;
+	// In merged mode the results grid renders its own count row directly above the
+	// grid (in every scope), so the inline aggregate here would be redundant.
+	const showTotalResults = !merged && sourcesInScope >= 2;
+
+	return (
+		<div className={`max-w-6xl mx-auto px-4 sm:px-6 lg:px-8 py-6 space-y-6 ${className ?? ""}`}>
+			{renderHeader ? (
+				renderHeader(handle)
+			) : (
+				<header className="space-y-2">
+					<h1 className="text-2xl font-bold">{title}</h1>
+					{subtitle && <p className="text-sm text-muted-foreground">{subtitle}</p>}
+				</header>
+			)}
+
+			<div className="flex flex-wrap items-center gap-3">
+				<SearchBar value={handle.q} onChange={handle.setQ} placeholder={searchPlaceholder} />
+				{shouldShowScope && (
+					<ScopeSelector
+						config={config}
+						scope={handle.scope}
+						onScopeChange={handle.setScope}
+						allLabel={allScopeLabel}
+						discoveredContentTypes={handle.discoveredContentTypes}
+					/>
+				)}
+			</div>
+
+			{merged ? (
+				<MergedSearchResults
+					handle={handle}
+					renderResult={renderResult}
+					emptyMessage={emptyMessages?.[handle.scope]}
+				/>
+			) : (
+				<>
+					{handle.error ? (
+						/* Page-level failure (every queried source failed, or a
+						   whole-request/network error). Show the single consolidated
+						   banner and nothing else — the per-source sections would each
+						   repeat the same "Failed to load <source>" error and their
+						   (now empty) filter/sort chrome, so suppress them entirely. */
+						<Alert variant="destructive" role="alert">
+							<AlertCircle aria-hidden="true" />
+							<AlertTitle>Search failed</AlertTitle>
+							<AlertDescription>{handle.error}</AlertDescription>
+						</Alert>
+					) : (
+						<>
+							{/* Aggregate count on its own row, directly above the results —
+							    only in "All" scope, where the per-source sections don't each
+							    carry a single meaningful total. */}
+							{showTotalResults && !handle.loading && (
+								<p className="text-sm text-muted-foreground" role="status">
+									{totalResults} total result{totalResults === 1 ? "" : "s"}
+								</p>
+							)}
+							<SearchResults
+								handle={handle}
+								renderResult={renderResult}
+								renderFilters={renderFilters}
+								emptyMessages={emptyMessages}
+							/>
+						</>
+					)}
+				</>
+			)}
+		</div>
+	);
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Renders one SourceSection per configured source, in declaration order.
+ *
+ * Customization is optional — sensible defaults kick in for any source you
+ * don't override:
+ *   - `renderResult[sourceKey]` — per-node renderer. Default: title from
+ *     `displayFields[0]`, subtitle from the rest, optional `<Link>` driven
+ *     by `routePattern`.
+ *   - `renderFilters[sourceKey]` — sidebar filter UI. Default: one input per
+ *     `filterBy` entry, with picklist options resolved from inline
+ *     config or auto-fetched from the GraphQL aggregate API.
+ *
+ * Pass `false` for either entry to suppress the default for that source.
+ *
+ * Filter chrome (sidebar + active-filter chips + sort dropdown) is
+ * automatically hidden when `handle.scope === "all"` — per-source controls
+ * would be unreachable with every source on screen, and dangling chips
+ * would be confusing. Pre-existing filter / sort selections stay in state,
+ * so narrowing the scope brings them back unchanged.
+ */
+
+import type { ReactNode } from "react";
+import { SourceSection } from "./SourceSection";
+import { DefaultFilterPanel } from "./filters/DefaultFilterPanel";
+import { resolveResultRenderer, type ResultRenderer } from "./results/resolveResultRenderer";
+import { ALL_SCOPE, parseScope, type SearchHandle } from "../types";
+import { isCmsSearchSupported } from "../adapters/cms/api/orgApiVersionService";
+
+type FilterRenderer = (() => ReactNode) | false;
+
+interface SearchResultsProps {
+	handle: SearchHandle;
+	renderResult?: Record<string, ResultRenderer>;
+	renderFilters?: Record<string, FilterRenderer>;
+	emptyMessages?: Record<string, string>;
+}
+
+export function SearchResults({
+	handle,
+	renderResult,
+	renderFilters,
+	emptyMessages,
+}: SearchResultsProps) {
+	const filtersHidden = handle.scope === ALL_SCOPE;
+	// Match sections against the base scope so a "<cmsKey>:<fqn>" scope still
+	// renders the CMS source's section (the fqn only narrows the query).
+	const { base: scopeBase } = parseScope(handle.scope);
+	return (
+		<div className="space-y-10">
+			{Object.entries(handle.sources).map(([key, controller]) => {
+				if (scopeBase !== ALL_SCOPE && scopeBase !== key) return null;
+				// CMS search is skipped on builds below the CMS-search API version, so a
+				// CMS source never returns rows — rendering its section would only show
+				// an empty "Content" heading. Hide it (same gate as the CMS fetch skip).
+				if (controller.config.kind === "cms" && !isCmsSearchSupported()) return null;
+				// Resolve the renderer through the shared helper so a CMS source
+				// renders via CmsResultRow (never DefaultResultRow) in this mode; a
+				// `renderResult[key]` override — including `false` (hide) — still wins.
+				const resolvedRenderResult = resolveResultRenderer(controller.config, renderResult);
+				if (resolvedRenderResult === false) return null;
+
+				// CMS sources have no `filterBy`; the guard below keeps their chrome off.
+				const overrideFilters = renderFilters?.[key];
+				const sourceConfig = controller.config;
+				const hasFilterFields =
+					sourceConfig.kind === "sobject" && (sourceConfig.filterBy?.length ?? 0) > 0;
+				const resolvedRenderFilters: (() => ReactNode) | undefined =
+					overrideFilters === false
+						? undefined
+						: (overrideFilters ??
+							(hasFilterFields && sourceConfig.kind === "sobject"
+								? () => <DefaultFilterPanel source={sourceConfig} />
+								: undefined));
+
+				return (
+					<SourceSection
+						key={key}
+						controller={controller}
+						renderResult={resolvedRenderResult}
+						renderFilters={resolvedRenderFilters}
+						hideFilterChrome={filtersHidden}
+						emptyMessage={emptyMessages?.[key]}
+					/>
+				);
+			})}
+		</div>
+	);
+}