@salesforce/ui-bundle-template-feature-react-search 11.10.0 → 11.11.0

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

@@ -40,8 +40,17 @@ export interface SObjectSourceConfig {
 	key: string;
 	/** GraphQL object name (e.g. "Account", "Contact"). */
 	objectName: string;
-	/** Display label used in section headers. */
+	/**
+	 * Plural display label — used in section headers, the scope dropdown, and
+	 * empty-state messages (e.g. "Accounts", "Maintenance Requests").
+	 */
 	label: string;
+	/**
+	 * Singular display label for a single record of this type (e.g. "Account",
+	 * "Maintenance Request"). Used for the per-card source badge in the merged
+	 * grid. Falls back to `label` when omitted.
+	 */
+	labelSingular?: string;
 	/** Field name that uniquely identifies a record. Defaults to "Id". */
 	idField?: string;
 	/**
@@ -67,16 +76,20 @@ export interface SObjectSourceConfig {
 	 * automatically; do not list it.
 	 */
 	displayFields: DisplayField[];
-	/** Optional structured filters surfaced in the per-source filter panel. */
-	filterFields?: FilterFieldConfig[];
+	/**
+	 * Optional structured filters for this source.
+	 *
+	 * Named `filterBy` (rather than "the filters shown in the panel") because a
+	 * future entry may constrain the query without rendering a control — e.g. a
+	 * default `Status != Completed` that hides completed items from results while
+	 * never appearing in the UI. Today every entry renders an input via
+	 * `DefaultFilterPanel`.
+	 */
+	filterBy?: FilterFieldConfig[];
 	/** Optional sort options surfaced in the per-source sort dropdown. */
-	sortFields?: SortFieldConfig[];
+	sortBy?: SortFieldConfig[];
 	/** Initial sort applied when no URL sort is present. */
 	defaultSort?: SortState;
-	/** Default page size for this source. */
-	pageSize?: number;
-	/** Allowed page sizes. */
-	validPageSizes?: number[];
 	/**
 	 * GraphQL type name for the `where` variable.
 	 * Defaults to `${objectName}_Filter` — override only for non-conventional schemas.
@@ -86,9 +99,48 @@ export interface SObjectSourceConfig {
 	orderByTypeName?: string;
 }
 
+/**
+ * One global pagination config for the whole search experience. It is the
+ * single source of truth — there is no per-source pagination. The same
+ * `pageSize` / `pageSizeOptions` apply across every object type and in every
+ * scope, including single-object pages (`restrictTo` / `lockedScope`) and when
+ * the scope dropdown narrows to one source.
+ */
+export interface SearchPaginationConfig {
+	/**
+	 * How results are paginated:
+	 *   - `"per-source"` (default): each source advances its own cursor; a page
+	 *     can hold up to `sources × pageSize` items. This is what the drop-in
+	 *     `<Search>` (one section per source) expects.
+	 *   - `"merged"`: treat the cumulative result set as one list and window it
+	 *     into fixed pages of `pageSize`. Each page shows exactly `pageSize` items
+	 *     across all sources — use for a single combined grid.
+	 */
+	mode?: "per-source" | "merged";
+	/**
+	 * In `"merged"` mode, how nodes from different sources are ordered:
+	 *   - `"sequential"` (default): source 1 in full, then source 2, …
+	 *   - `"interleaved"`: round-robin — every source gets equal priority.
+	 *   - `"proportional"`: each source spread by its result count, so larger
+	 *     sources appear more often. Ignored in `"per-source"` mode.
+	 */
+	mergeOrder?: "sequential" | "interleaved" | "proportional";
+	/** Items per page (across all sources in `"merged"` mode; per source otherwise). */
+	pageSize: number;
+	/** Page sizes offered in the "results per page" control. */
+	pageSizeOptions: number[];
+}
+
 /** Top-level config passed to {@link useSearch}. */
 export interface SearchConfig {
 	sources: SObjectSourceConfig[];
+	/**
+	 * Global pagination config — the single source of truth for page size, page
+	 * options, mode, and merge order. See {@link SearchPaginationConfig}. When
+	 * omitted, pagination defaults to per-source mode, page size 10, options
+	 * `[10, 25, 50]`.
+	 */
+	pagination?: SearchPaginationConfig;
 }
 
 // ---------------------------------------------------------------------------
@@ -129,6 +181,8 @@ export interface SourceController {
 	};
 	pagination: {
 		pageSize: number;
+		/** Allowed page sizes — from the global pagination config. */
+		pageSizeOptions: readonly number[];
 		pageIndex: number;
 		hasNextPage: boolean;
 		hasPreviousPage: boolean;
@@ -149,6 +203,70 @@ export type SearchScope = "all" | string;
 
 export const ALL_SCOPE = "all" as const;
 
+/**
+ * One result node tagged with the source it came from. Produced by
+ * {@link SearchHandle.mergedResults} so a single combined grid can render
+ * cross-source results and still pick the right card per node.
+ */
+export interface MergedResultItem {
+	/** The `key` of the source this node came from. */
+	sourceKey: string;
+	/** The raw result node (cast to your typed node in the renderer). */
+	node: unknown;
+}
+
+/**
+ * Aggregate pagination across every in-scope source, exposed by
+ * {@link SearchHandle.globalPagination}. Its exact behaviour depends on the
+ * `pagination` mode passed to {@link useSearch}:
+ *
+ * - **`"merged"`** (recommended for a single combined grid): the cumulative
+ *   result set is treated as one list and windowed into fixed pages of
+ *   `pageSize`. Page `P` always shows **exactly** `pageSize` items (the last
+ *   page may show fewer), `pageCount` is `ceil(totalCount / pageSize)`, and
+ *   `goToPage` can jump to any page. Under the hood each in-scope source fetches
+ *   `(P + 1) * pageSize` rows from its front, the results are concatenated in
+ *   config order, and the page-`P` slice is taken — so the math is exact, not an
+ *   estimate.
+ * - **`"per-source"`** (default): each source paginates with its own cursor and
+ *   a "global page" is the furthest-advanced in-scope source's page. `Next`
+ *   advances only the sources still on the current global page that have more
+ *   data; a source that runs out is left behind. `goToPage` is best-effort
+ *   (adjacent pages only) because cursors can't seek to an arbitrary offset.
+ */
+export interface GlobalPagination {
+	/** Current global page, 0-based. */
+	pageIndex: number;
+	/**
+	 * Total number of global pages. In `"merged"` mode this is exactly
+	 * `ceil(totalCount / pageSize)`. In `"per-source"` mode it is the `max` over
+	 * in-scope sources of `ceil(totalCount / pageSize)` and may be an estimate if
+	 * a source omits `totalCount`. `0` when there are no results, otherwise `>= 1`.
+	 */
+	pageCount: number;
+	/** Shared page size. */
+	pageSize: number;
+	/** Allowed page sizes (from the first in-scope source). */
+	pageSizeOptions: readonly number[];
+	/** True when there is a page after the current one. */
+	hasNextPage: boolean;
+	/** True when the current global page is past the first. */
+	hasPreviousPage: boolean;
+	/** Cumulative result count summed across in-scope sources. */
+	totalCount: number;
+	/** Advance to the next global page. */
+	goToNextPage: () => void;
+	/** Step back to the previous global page. */
+	goToPreviousPage: () => void;
+	/**
+	 * Jump to a specific 0-based page. Exact in `"merged"` mode; in
+	 * `"per-source"` mode only adjacent pages are honoured (others are a no-op).
+	 */
+	goToPage: (pageIndex: number) => void;
+	/** Set the page size (resets to the first page). */
+	setPageSize: (size: number) => void;
+}
+
 export interface SearchHandle {
 	q: string;
 	setQ: (q: string) => void;
@@ -160,6 +278,26 @@ export interface SearchHandle {
 	 */
 	scopeLocked: boolean;
 	sources: Record<string, SourceController>;
+	/**
+	 * Source controllers that participate in the current scope, in config
+	 * declaration order. In `"all"` scope this is every source; otherwise just
+	 * the selected one. Convenience for callers building aggregate UI.
+	 */
+	inScopeSources: SourceController[];
+	/**
+	 * In-scope nodes flattened into one list (config order, source by source),
+	 * each tagged with its `sourceKey` — for rendering a single combined grid
+	 * instead of one section per source. In `"merged"` pagination mode this is
+	 * exactly the current page's window (at most `globalPagination.pageSize`
+	 * items); in `"per-source"` mode it is every in-scope source's current page
+	 * concatenated.
+	 */
+	mergedResults: MergedResultItem[];
+	/**
+	 * Aggregate pagination across all in-scope sources — drive one shared
+	 * pager over the cumulative result set. See {@link GlobalPagination}.
+	 */
+	globalPagination: GlobalPagination;
 	loading: boolean;
 	error: string | null;
 	resetAll: () => void;

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

@@ -28,6 +28,17 @@ export type FilterFieldType =
 	| "datetimerange"
 	| "multipicklist";
 
+/**
+ * Which comparison UI a date/datetime filter exposes:
+ *   - `"range"`: a single Between control (two date inputs, lower–upper bound).
+ *   - `"comparison"`: an After / Before selector with one date input.
+ *   - `"both"`: a Between / After / Before selector that switches between the two.
+ *
+ * Applies only to the date-family `type`s (`date`, `daterange`, `datetime`,
+ * `datetimerange`); ignored for other field types. Defaults to `"comparison"`.
+ */
+export type DateFilterMode = "range" | "comparison" | "both";
+
 export type FilterFieldConfig<TFieldName extends string = string> = {
 	field: TFieldName;
 	label: string;
@@ -35,6 +46,8 @@ export type FilterFieldConfig<TFieldName extends string = string> = {
 	placeholder?: string;
 	/** Required for picklist / multipicklist. */
 	options?: Array<{ value: string; label: string }>;
+	/** Date-family only — see {@link DateFilterMode}. Defaults to `"comparison"`. */
+	dateMode?: DateFilterMode;
 	helpText?: string;
 };
 

package/dist/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "11.10.0",
+  "version": "11.11.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-      "version": "11.10.0",
+      "version": "11.11.0",
       "license": "SEE LICENSE IN LICENSE.txt",
       "devDependencies": {
         "@lwc/eslint-plugin-lwc": "^3.3.0",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/ui-bundle-template-base-sfdx-project",
-  "version": "11.10.0",
+  "version": "11.11.0",
   "description": "Base SFDX project template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "publishConfig": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/ui-bundle-template-feature-react-search",
-  "version": "11.10.0",
-  "description": "Configuration-driven multi-source search for UI Bundles",
+  "version": "11.11.0",
+  "description": "[Beta] Configuration-driven multi-source search for UI Bundles",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",
   "type": "module",

package/src/force-app/main/default/uiBundles/feature-react-search/src/components/ui/__inherit__popover.tsx

@@ -0,0 +1,40 @@
+import * as React from "react";
+import { Popover as PopoverPrimitive } from "radix-ui";
+
+function Popover({}: React.ComponentProps<typeof PopoverPrimitive.Root>) {
+	return <></>;
+}
+
+function PopoverTrigger({}: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
+	return <></>;
+}
+
+function PopoverContent({}: React.ComponentProps<typeof PopoverPrimitive.Content>) {
+	return <></>;
+}
+
+function PopoverAnchor({}: React.ComponentProps<typeof PopoverPrimitive.Anchor>) {
+	return <></>;
+}
+
+function PopoverHeader({}: React.ComponentProps<"div">) {
+	return <></>;
+}
+
+function PopoverTitle({}: React.ComponentProps<"h2">) {
+	return <></>;
+}
+
+function PopoverDescription({}: React.ComponentProps<"p">) {
+	return <></>;
+}
+
+export {
+	Popover,
+	PopoverAnchor,
+	PopoverContent,
+	PopoverDescription,
+	PopoverHeader,
+	PopoverTitle,
+	PopoverTrigger,
+};

package/src/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/MergedSearchResults.tsx

@@ -0,0 +1,263 @@
+/**
+ * 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 type { ReactNode } from "react";
+import { AlertCircle } from "lucide-react";
+import { Alert, AlertDescription, AlertTitle } from "../../../components/ui/__inherit__alert";
+import { Skeleton } from "../../../components/ui/__inherit__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 { DefaultResultRow } from "./results/DefaultResultRow";
+import { ALL_SCOPE, type SearchHandle, type SourceController } from "../types";
+
+type ResultRenderer = ((node: unknown) => ReactNode) | false;
+
+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;
+
+	return (
+		<div className={`space-y-6 ${className ?? ""}`}>
+			{soleController && <SingleSourceChrome controller={soleController} />}
+
+			{error && (
+				<Alert variant="destructive" role="alert">
+					<AlertCircle />
+					<AlertTitle>Search failed</AlertTitle>
+					<AlertDescription>{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" role="status">
+					{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>
+			) : (
+				<div className={gridClassName}>
+					{mergedResults.map(({ sourceKey, node }, i) => {
+						const override = renderResult?.[sourceKey];
+						if (override === false) return null;
+						const source = handle.sources[sourceKey]?.config;
+						const rendered = override ? (
+							override(node)
+						) : source ? (
+							<DefaultResultRow node={node} source={source} />
+						) : null;
+						const badge =
+							showSourceBadges && source ? (
+								<SourceBadge
+									label={source.labelSingular ?? source.label}
+									colorClass={badgeColorByKey[sourceKey]}
+								/>
+							) : null;
+						return (
+							<div
+								key={getItemKey(sourceKey, node, i)}
+								className="flex flex-col gap-1.5 [&>:last-child]:min-h-0 [&>:last-child]:flex-1"
+							>
+								{badge}
+								{rendered}
+							</div>
+						);
+					})}
+				</div>
+			)}
+
+			{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;
+	const showFilterPanel = (source.filterBy?.length ?? 0) > 0;
+	const showSortControl = (source.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 && (
+				<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">
+							<h3 className="text-sm font-semibold">Filters</h3>
+							<FilterResetButton size="sm" />
+						</div>
+						<div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
+							<DefaultFilterPanel source={source} />
+						</div>
+					</div>
+				</FilterProvider>
+			)}
+
+			{(showSortControl || showActiveChips) && (
+				<div className="flex flex-wrap items-center gap-2">
+					{showSortControl && source.sortBy && (
+						<SortControl configs={source.sortBy} sort={sort.current} onSortChange={sort.set} />
+					)}
+					{showActiveChips && <ActiveFilters filters={filters.active} onRemove={filters.remove} />}
+				</div>
+			)}
+		</div>
+	);
+}

package/src/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/Search.tsx

@@ -1,8 +1,13 @@
 /**
  * Drop-in search component. Given a `SearchConfig`, renders a complete
- * search experience: search bar, an aggregate result count (shown only when
- * 2+ sources are in scope), and one results section per configured source
- * (with auto-rendered rows + filters).
+ * 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:
  *
@@ -28,6 +33,7 @@ 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";
 
@@ -108,6 +114,10 @@ export function Search({
 	}, [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,
@@ -119,7 +129,9 @@ export function Search({
 	// 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;
-	const showTotalResults = sourcesInScope >= 2;
+	// 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 ?? ""}`}>
@@ -142,19 +154,32 @@ export function Search({
 						allLabel={allScopeLabel}
 					/>
 				)}
-				{showTotalResults && !handle.loading && (
-					<span className="text-sm text-muted-foreground">
-						{totalResults} total result{totalResults === 1 ? "" : "s"}
-					</span>
-				)}
 			</div>
 
-			<SearchResults
-				handle={handle}
-				renderResult={renderResult}
-				renderFilters={renderFilters}
-				emptyMessages={emptyMessages}
-			/>
+			{merged ? (
+				<MergedSearchResults
+					handle={handle}
+					renderResult={renderResult}
+					emptyMessage={emptyMessages?.[handle.scope]}
+				/>
+			) : (
+				<>
+					{/* 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/src/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/SearchResults.tsx

@@ -7,7 +7,7 @@
  *     `displayFields[0]`, subtitle from the rest, optional `<Link>` driven
  *     by `routePattern`.
  *   - `renderFilters[sourceKey]` — sidebar filter UI. Default: one input per
- *     `filterFields` entry, with picklist options resolved from inline
+ *     `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.
@@ -52,7 +52,7 @@ export function SearchResults({
 					overrideResult ?? ((node) => <DefaultResultRow node={node} source={controller.config} />);
 
 				const overrideFilters = renderFilters?.[key];
-				const hasFilterFields = (controller.config.filterFields?.length ?? 0) > 0;
+				const hasFilterFields = (controller.config.filterBy?.length ?? 0) > 0;
 				const resolvedRenderFilters: (() => ReactNode) | undefined =
 					overrideFilters === false
 						? undefined