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

package/README.md

@@ -1,8 +1,15 @@
 # @salesforce/ui-bundle-template-feature-react-search
 
+![Status: Beta](https://img.shields.io/badge/status-beta-orange)
+
 Configuration-driven, multi-source search for **React** applications on the
 Salesforce platform.
 
+> 🧪 **Beta.** This feature is in beta. It is usable today, but the API
+> (component props, config schema, and exported primitives) may change in a
+> future release, and breaking changes can land in a minor version. Pin the
+> package version and review the [CHANGELOG](./CHANGELOG.md) before upgrading.
+
 > ⚛️ **React only.** This package ships React components and hooks built on
 > `react` 19 and `react-router` 7. Use it in a React application; it is not
 > compatible with LWC or other non-React UIs — see [Requirements](#requirements).
@@ -35,8 +42,8 @@ changes.
 - [Creating your own config](#creating-your-own-config)
   - [Source fields](#source-fields-sobjectsourceconfig)
   - [`displayFields` shapes](#displayfields-shapes)
-  - [`filterFields` types](#filterfields-types)
-  - [`sortFields` and `defaultSort`](#sortfields-and-defaultsort)
+  - [`filterBy` types](#filterby-types)
+  - [`sortBy` and `defaultSort`](#sortby-and-defaultsort)
   - [`routePattern` tokens](#routepattern-tokens)
   - [A complete source, annotated](#a-complete-source-annotated)
 - [Use cases](#use-cases)
@@ -49,6 +56,8 @@ changes.
   - [7. Headless — drive your own UI with `useSearch`](#7-headless--drive-your-own-ui-with-usesearch)
   - [8. Mixed card layouts per source](#8-mixed-card-layouts-per-source)
   - [9. Global pagination across all sources](#9-global-pagination-across-all-sources)
+  - [10. Build a custom unified-results UI (grid + pager + filters + count)](#10-build-a-custom-unified-results-ui-grid--pager--filters--count)
+  - [11. Choosing a merge order (sequential vs proportional)](#11-choosing-a-merge-order-sequential-vs-proportional)
 - [URL and state conventions](#url-and-state-conventions)
 - [Public API](#public-api)
 - [Common mistakes](#common-mistakes)
@@ -98,10 +107,14 @@ export default function SearchPage() {
 }
 ```
 
-This renders: a search bar, a Reset button, a live total-result count, a scope
-dropdown (when the config has 2+ sources), and one results section per source —
-each with auto-rendered rows, a filter sidebar, a sort dropdown, and
-pagination. Everything is driven by the config you pass in.
+This renders: a search bar, a live total-result count, a scope dropdown (when
+the config has 2+ sources), and one results section per source — each with
+auto-rendered rows, a filter sidebar, a sort dropdown, per-source pagination,
+and a per-source Reset button inside its filter panel. (Reset is per-source;
+there is no global reset button.) Set `pagination.mode: "merged"` and the same
+component instead renders one combined grid with a single shared pager
+([§9](#9-global-pagination-across-all-sources)). Everything is driven by the
+config you pass in.
 
 For a real application you'll typically pass [your own config](#creating-your-own-config).
 
@@ -147,14 +160,26 @@ slots, or drop down to the `useSearch` hook for full control:
 
 ## Creating your own config
 
-A `SearchConfig` is just `{ sources: SObjectSourceConfig[] }`. Define it in
-your own code and pass it to `<Search config={...} />`:
+A `SearchConfig` is `{ sources: SObjectSourceConfig[] }` plus an optional global
+`pagination` block. Define it in your own code and pass it to
+`<Search config={...} />`:
 
 ```tsx
 import { Search } from "@salesforce/ui-bundle-template-feature-react-search";
 import type { SearchConfig } from "@salesforce/ui-bundle-template-feature-react-search";
 
 const config: SearchConfig = {
+  // One global pagination block — the single source of truth for the whole
+  // search experience. `mode` / `mergeOrder` / `pageSize` / `pageSizeOptions`
+  // apply to every object type and in every scope, including when the dropdown
+  // narrows to one source and on single-object pages (restrictTo / lockedScope).
+  // Omit to default to per-source mode, page size 10, options [10, 25, 50].
+  pagination: {
+    mode: "merged", // "per-source" (default) | "merged"
+    mergeOrder: "proportional", // "sequential" (default) | "interleaved" | "proportional"
+    pageSize: 12,
+    pageSizeOptions: [12, 24, 48],
+  },
   sources: [
     {
       kind: "sobject",
@@ -173,6 +198,16 @@ export default function SearchPage() {
 }
 ```
 
+**One pagination config for everything.** There is no per-source pagination
+_config_ — `config.pagination` is the single source of truth. The same
+`pageSize` / `pageSizeOptions` apply across every object type and in every
+scope — the unified `/search` page, when the scope dropdown narrows to one
+source, and single-object pages locked with `restrictTo` / `lockedScope`.
+How that config is _displayed_ depends on `mode`: the default `"per-source"`
+paginates each object's section on its own cursor, while `"merged"` collapses
+in-scope sources into one combined grid whose page order is set by `mergeOrder`
+(see [§9](#9-global-pagination-across-all-sources)).
+
 You can also keep the config as a JSON file and import it — cast it to
 `SearchConfig` since the structure is not validated at runtime (see the note at
 the end of this section).
@@ -182,23 +217,37 @@ uiapi GraphQL bridge.
 
 ### Source fields (`SObjectSourceConfig`)
 
-| Field              | Required | Type                      | Description                                                                                                            |
-| ------------------ | -------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `kind`             | ✅       | `"sobject"`               | Discriminator selecting the runtime adapter.                                                                           |
-| `key`              | ✅       | `string`                  | Stable id — used as the GraphQL alias, URL namespace, and result-map key. Must match `/^[A-Za-z_][A-Za-z0-9_]*$/`.     |
-| `objectName`       | ✅       | `string`                  | GraphQL object name (`"Account"`, `"Contact"`, …).                                                                     |
-| `label`            | ✅       | `string`                  | Display label for the section header and scope dropdown.                                                               |
-| `searchableFields` | ✅       | `string[]`                | Fields the global `q` term matches. OR-ed as `like %q%`. Supports dot-paths (`"Owner.Name"`).                          |
-| `displayFields`    | ✅       | `DisplayField[]`          | Fields selected in the GraphQL query and used by the default row layout. (See below.)                                  |
-| `routePattern`     |          | `string`                  | Makes the default row a `<Link>`. Tokens like `:id` / `:Name` are substituted per record. Omit for non-clickable rows. |
-| `idField`          |          | `string` (default `"Id"`) | Unique-id field. Drives the `:id` route token. Always selected automatically — **do not** list it in `displayFields`.  |
-| `filterFields`     |          | `FilterFieldConfig[]`     | Structured filters shown in the per-source sidebar.                                                                    |
-| `sortFields`       |          | `SortFieldConfig[]`       | Options in the per-source sort dropdown.                                                                               |
-| `defaultSort`      |          | `{ field, direction }`    | Initial sort applied when the URL has none. `direction` is `"ASC"` or `"DESC"`.                                        |
-| `pageSize`         |          | `number` (default `10`)   | Default page size.                                                                                                     |
-| `validPageSizes`   |          | `number[]`                | Allowed page sizes for the page-size selector.                                                                         |
-| `whereTypeName`    |          | `string`                  | GraphQL `where` variable type. Defaults to `${objectName}_Filter`. Override only for non-conventional schemas.         |
-| `orderByTypeName`  |          | `string`                  | GraphQL `orderBy` variable type. Defaults to `${objectName}_OrderBy`.                                                  |
+| Field              | Required | Type                      | Description                                                                                                                                                                                                            |
+| ------------------ | -------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`             | ✅       | `"sobject"`               | Discriminator selecting the runtime adapter.                                                                                                                                                                           |
+| `key`              | ✅       | `string`                  | Stable id — used as the GraphQL alias, URL namespace, and result-map key. Must match `/^[A-Za-z_][A-Za-z0-9_]*$/`.                                                                                                     |
+| `objectName`       | ✅       | `string`                  | GraphQL object name (`"Account"`, `"Contact"`, …).                                                                                                                                                                     |
+| `label`            | ✅       | `string`                  | Plural display label — section header, scope dropdown, empty-state messages (`"Accounts"`).                                                                                                                            |
+| `labelSingular`    |          | `string`                  | Singular label for one record (`"Account"`) — used for the merged-grid source badge. Falls back to `label`.                                                                                                            |
+| `searchableFields` | ✅       | `string[]`                | Fields the global `q` term matches. OR-ed as `like %q%`. Supports dot-paths (`"Owner.Name"`).                                                                                                                          |
+| `displayFields`    | ✅       | `DisplayField[]`          | Fields selected in the GraphQL query and used by the default row layout. (See below.)                                                                                                                                  |
+| `routePattern`     |          | `string`                  | Makes the default row a `<Link>`. Tokens like `:id` / `:Name` are substituted per record. Your app must register a matching route to render the target ([details](#routepattern-tokens)). Omit for non-clickable rows. |
+| `idField`          |          | `string` (default `"Id"`) | Unique-id field. Drives the `:id` route token. Always selected automatically — **do not** list it in `displayFields`.                                                                                                  |
+| `filterBy`         |          | `FilterFieldConfig[]`     | Structured filters for the source. Today each renders an input in the per-source sidebar.                                                                                                                              |
+| `sortBy`           |          | `SortFieldConfig[]`       | Options in the per-source sort dropdown.                                                                                                                                                                               |
+| `defaultSort`      |          | `{ field, direction }`    | Initial sort applied when the URL has none. `direction` is `"ASC"` or `"DESC"`.                                                                                                                                        |
+| `whereTypeName`    |          | `string`                  | GraphQL `where` variable type. Defaults to `${objectName}_Filter`. Override only for non-conventional schemas.                                                                                                         |
+| `orderByTypeName`  |          | `string`                  | GraphQL `orderBy` variable type. Defaults to `${objectName}_OrderBy`.                                                                                                                                                  |
+
+### Global pagination (`SearchConfig.pagination`)
+
+Optional. One block governs pagination for the whole search experience —
+sources carry no pagination config of their own. Omit it to default to
+per-source mode, page size `10`, options `[10, 25, 50]`. (Note: `mode`
+`"per-source"` still paginates each object's section independently — see the
+`mode` row below and [§9](#9-global-pagination-across-all-sources).)
+
+| Field             | Required | Type                                                                         | Description                                                                                                                                                                       |
+| ----------------- | -------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pageSize`        | ✅       | `number`                                                                     | Items per page (across all sources in `"merged"` mode; per source otherwise).                                                                                                     |
+| `pageSizeOptions` | ✅       | `number[]`                                                                   | Page sizes offered in the "results per page" control.                                                                                                                             |
+| `mode`            |          | `"per-source"` \| `"merged"` (default `per-source`)                          | `"merged"` windows the cumulative result set into fixed pages of `pageSize`; `"per-source"` advances each source's own cursor. See [§9](#9-global-pagination-across-all-sources). |
+| `mergeOrder`      |          | `"sequential"` \| `"interleaved"` \| `"proportional"` (default `sequential`) | In `"merged"` mode, how nodes from different sources are ordered. Ignored in `"per-source"` mode. See [§9](#9-global-pagination-across-all-sources).                              |
 
 ### `displayFields` shapes
 
@@ -213,43 +262,52 @@ layout (first entry → row title; the rest → subtitle, joined with `·`):
 
 > The `idField` (default `"Id"`) is always emitted — never list it explicitly.
 
-### `filterFields` types
+### `filterBy` types
 
-Each `FilterFieldConfig` is `{ field, label, type, options?, placeholder?, helpText? }`.
+Each `FilterFieldConfig` is `{ field, label, type, options?, placeholder?, dateMode?, helpText? }`.
 The `type` drives which input renders and how the `where` clause is built:
 
-| `type`          | UI                         | `where` clause                               |
-| --------------- | -------------------------- | -------------------------------------------- |
-| `text`          | Text input                 | `{ field: { like: "%value%" } }`             |
-| `picklist`      | Single-select dropdown     | `{ field: { eq: value } }`                   |
-| `multipicklist` | Multi-select               | `{ field: { in: [...] } }` (or `eq` for one) |
-| `numeric`       | min / max number inputs    | `{ field: { gte, lte } }`                    |
-| `boolean`       | Tri-state (any/true/false) | `{ field: { eq: true \| false } }`           |
-| `date`          | Single date                | `{ field: { gte \| lte: { value } } }`       |
-| `daterange`     | Date min / max             | `and` of `gte` / `lte`                       |
-| `datetime`      | Single datetime            | start/end-of-day ISO bounds                  |
-| `datetimerange` | Datetime min / max         | `and` of start/end-of-day ISO bounds         |
+| `type`          | UI                                 | `where` clause                               |
+| --------------- | ---------------------------------- | -------------------------------------------- |
+| `text`          | Text input                         | `{ field: { like: "%value%" } }`             |
+| `picklist`      | Single-select dropdown             | `{ field: { eq: value } }`                   |
+| `multipicklist` | Multi-select dropdown (checkboxes) | `{ field: { in: [...] } }` (or `eq` for one) |
+| `numeric`       | min / max number inputs            | `{ field: { gte, lte } }`                    |
+| `boolean`       | Tri-state (any/true/false)         | `{ field: { eq: true \| false } }`           |
+| `date`          | See `dateMode`                     | `{ field: { gte \| lte: { value } } }`       |
+| `daterange`     | See `dateMode`                     | `and` of `gte` / `lte`                       |
+| `datetime`      | See `dateMode`                     | start/end-of-day ISO bounds                  |
+| `datetimerange` | See `dateMode`                     | `and` of start/end-of-day ISO bounds         |
 
 For `picklist` / `multipicklist`, options are **auto-fetched** from the GraphQL
 aggregate API (`groupBy`) on first render. Skip the fetch by supplying inline
 `options: [{ value, label }]` — required for fields that aren't group-by-able
 (formulas, long text, etc.).
 
-### `sortFields` and `defaultSort`
+For the date-family types, `dateMode` selects the comparison chrome (defaults to
+`"comparison"`):
+
+| `dateMode`     | UI                                                                  |
+| -------------- | ------------------------------------------------------------------- |
+| `"comparison"` | An **After** / **Before** selector with one date input (default).   |
+| `"range"`      | A single **Between** control — two date inputs (lower–upper bound). |
+| `"both"`       | A **Between** / **After** / **Before** selector spanning the two.   |
 
-`sortFields` is a list of `{ field, label }`. Each becomes an option in the
+### `sortBy` and `defaultSort`
+
+`sortBy` is a list of `{ field, label }`. Each becomes an option in the
 per-source sort dropdown (with an ASC/DESC toggle). `defaultSort` sets the
 initial order when no sort is present in the URL:
 
 ```jsonc
-"sortFields": [
+"sortBy": [
 	{ "field": "CloseDate", "label": "Close Date" },
 	{ "field": "Amount", "label": "Amount" }
 ],
 "defaultSort": { "field": "CloseDate", "direction": "DESC" }
 ```
 
-Omit `sortFields` entirely to hide the sort dropdown for that source.
+Omit `sortBy` entirely to hide the sort dropdown for that source.
 
 ### `routePattern` tokens
 
@@ -262,6 +320,20 @@ If **any** token resolves to `null` for a record, that row falls back to a
 plain, non-clickable layout. Make sure tokenized fields are present in
 `displayFields`.
 
+> **`routePattern` only builds the link — you must supply the destination.**
+> This feature turns a result row into a `<Link to="/accounts/<id>">`; it does
+> **not** create the page that link points at. For `"/accounts/:id"` to actually
+> show an account, your app must register a matching route (e.g.
+> `<Route path="/accounts/:id" element={<AccountDetail />} />`) and implement the
+> `AccountDetail` page/component that reads the `:id` param and renders that
+> object's details. Without a corresponding route the link resolves to a blank or
+> not-found page. Point `routePattern` at routes you already have (or add them
+> alongside), and give every searchable source its own detail route. If you don't
+> want clickable rows — for example when details open in a modal instead of on a
+> route — omit `routePattern` entirely (this is what the `propertymanagementapp`
+> template does: it has no `routePattern` and opens a detail modal from a custom
+> `renderResult` instead).
+
 ### A complete source, annotated
 
 ```jsonc
@@ -269,7 +341,8 @@ plain, non-clickable layout. Make sure tokenized fields are present in
   "kind": "sobject", // discriminator
   "key": "leads", // GraphQL alias + URL namespace + result key
   "objectName": "Lead", // GraphQL type
-  "label": "Leads", // section header + scope option
+  "label": "Leads", // plural — section header + scope option
+  "labelSingular": "Lead", // singular — merged-grid source badge (optional; falls back to label)
   "routePattern": "/leads/:id", // default row → <Link to="/leads/<id>">
   "idField": "Id", // default; drives :id (don't add to displayFields)
   "searchableFields": ["Name", "Company", "Email"], // global q is OR-ed across these
@@ -280,23 +353,22 @@ plain, non-clickable layout. Make sure tokenized fields are present in
     "Email", // ┘
     { "name": "Owner", "subfields": ["Name"] }, // relationship traversal
   ],
-  "filterFields": [
+  "filterBy": [
     { "field": "Status", "label": "Status", "type": "picklist" },
     { "field": "Industry", "label": "Industry", "type": "picklist" },
   ],
-  "sortFields": [
+  "sortBy": [
     { "field": "Name", "label": "Name" },
     { "field": "CreatedDate", "label": "Created Date" },
   ],
   "defaultSort": { "field": "CreatedDate", "direction": "DESC" },
-  "pageSize": 10,
-  "validPageSizes": [5, 10, 20],
 }
 ```
 
 That single entry gives Leads a full search experience: a global-term match
 across name/company/email, two auto-populated picklist filters, a sort
-dropdown, pagination, and clickable result rows linking to `/leads/<id>`.
+dropdown, pagination (governed by the top-level `pagination` block), and
+clickable result rows linking to `/leads/<id>`.
 
 > **No runtime schema validation.** A config object is trusted as-is; a typo
 > surfaces at GraphQL query time, not when the config loads. Layer your own
@@ -491,13 +563,45 @@ same pattern) and wrap each source's `result.nodes` in your own grid container.
 
 ### 9. Global pagination across all sources
 
-The drop-in `<Search>` paginates each source independently. If you want a
-single, shared pagination control that advances **every** in-scope source at
-once, build a headless layout with `useSearch` and the exported
-`PaginationControls`. Each source exposes its own
-`controller.pagination` (`goToNextPage` / `goToPreviousPage` / `setPageSize`
-plus `pageIndex` / `hasNextPage` / `hasPreviousPage`); a global control simply
-fans an action out across all of them:
+By default the drop-in `<Search>` paginates each source independently. Set
+`config.pagination.mode: "merged"` and `<Search>` switches to a single combined
+grid with one shared pager over the **cumulative** result set automatically — no
+prop needed (that's exactly what [§10](#10-build-a-custom-unified-results-ui-grid--pager--filters--count)
+assembles by hand for a fully custom UI). Either way, the merged behaviour is
+built from three aggregate accessors `useSearch` derives from the in-scope
+sources:
+
+| Accessor                  | Use                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------- |
+| `handle.inScopeSources`   | The `SourceController[]` participating in the current scope (config order).   |
+| `handle.mergedResults`    | In-scope nodes flattened into one `{ sourceKey, node }[]` for a single grid.  |
+| `handle.globalPagination` | Aggregate `pageIndex` / `pageCount` / `pageSize` / `hasNext…` + page actions. |
+
+**Pick a pagination mode** via `config.pagination.mode`:
+
+| Mode           | `mergedResults`                      | Page size means…                  | `goToPage`       |
+| -------------- | ------------------------------------ | --------------------------------- | ---------------- |
+| `"merged"`     | exactly the current page's window    | items **per page** (e.g. 6 total) | jump to any page |
+| `"per-source"` | every in-scope source's current page | items **per source** (6 × N)      | adjacent only    |
+
+Use `"merged"` when you want a true combined list — "6 per page" shows exactly 6
+cards and `pageCount = ceil(totalCount / pageSize)`. The default `"per-source"`
+keeps each source on its own cursor (cheaper for deep lists, but a page can hold
+up to `sources × pageSize` items).
+
+**Order sources** with `config.pagination.mergeOrder`:
+
+| Order                    | `mergedResults` layout                                                  |
+| ------------------------ | ----------------------------------------------------------------------- |
+| `"sequential"` (default) | all of source 1, then source 2, … — the first source leads.             |
+| `"interleaved"`          | round-robin, one per source per round — every source ranks **equally**. |
+| `"proportional"`         | each source spread evenly by its result count — share **matches size**. |
+
+Pass `"interleaved"` to give every object type equal footing regardless of how
+many results it has; pass `"proportional"` to weight types by their result count
+(a source with 100 hits appears ~10× as often as one with 10, so each page
+mirrors the overall mix). Proportional reads each source's `totalCount`. Page
+boundaries stay exact under all three orders.
 
 ```tsx
 import {
@@ -508,48 +612,45 @@ import {
 } from "@salesforce/ui-bundle-template-feature-react-search";
 
 function GloballyPaginatedSearch() {
+  // mode + mergeOrder live in config.pagination (e.g. { mode: "merged",
+  // mergeOrder: "interleaved", pageSize: 6, pageSizeOptions: [6, 12, 24] }).
   const handle = useSearch(config);
-  const controllers = Object.values(handle.sources);
-
-  // Aggregate paging state: there's a next page if ANY source has one;
-  // you can go back only once every source is past its first page.
-  const hasNextPage = controllers.some((c) => c.pagination.hasNextPage);
-  const hasPreviousPage =
-    controllers.length > 0 && controllers.every((c) => c.pagination.hasPreviousPage);
-  const pageSize = controllers[0]?.pagination.pageSize ?? 10;
-  const pageIndex = controllers[0]?.pagination.pageIndex ?? 0;
+  const { mergedResults, globalPagination: page } = handle;
 
-  const goNext = () => controllers.forEach((c) => c.pagination.goToNextPage());
-  const goPrev = () => controllers.forEach((c) => c.pagination.goToPreviousPage());
-  const setSize = (size: number) => controllers.forEach((c) => c.pagination.setPageSize(size));
+  // One combined, cumulatively-paginated grid. Each item knows its source, so
+  // you can pick the right card/row per node.
+  const sourceByKey = Object.fromEntries(
+    handle.inScopeSources.map((c) => [c.config.key, c.config]),
+  );
 
   return (
     <div className="max-w-4xl mx-auto py-6 space-y-6">
       <SearchBar value={handle.q} onChange={handle.setQ} placeholder="Search…" />
 
-      {controllers.map((c) => (
-        <section key={c.config.key}>
-          <h2 className="text-lg font-semibold mb-2">{c.config.label}</h2>
-          <ul className="divide-y">
-            {(c.result?.nodes ?? []).map((node, i) => (
-              <li key={i} className="py-2">
-                <DefaultResultRow node={node} source={c.config} />
-              </li>
-            ))}
-          </ul>
-        </section>
-      ))}
-
-      {/* One control drives every source. */}
+      <p className="text-sm text-muted-foreground">
+        {page.totalCount} results · Page {page.pageIndex + 1} of {page.pageCount}
+      </p>
+
+      <ul className="divide-y">
+        {mergedResults.map(({ sourceKey, node }, i) => (
+          <li key={i} className="py-2">
+            <DefaultResultRow node={node} source={sourceByKey[sourceKey]} />
+          </li>
+        ))}
+      </ul>
+
+      {/* Passing pageCount + onGoToPage renders numbered page buttons. */}
       <PaginationControls
-        pageIndex={pageIndex}
-        hasNextPage={hasNextPage}
-        hasPreviousPage={hasPreviousPage}
-        pageSize={pageSize}
-        pageSizeOptions={[5, 10, 20]}
-        onNextPage={goNext}
-        onPreviousPage={goPrev}
-        onPageSizeChange={setSize}
+        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={handle.loading}
       />
     </div>
@@ -557,10 +658,246 @@ function GloballyPaginatedSearch() {
 }
 ```
 
-> Each source keeps its own cursor stack, so per-source `pageIndex` values can
-> drift if a source runs out of pages before the others. Read aggregate state
-> from whichever source you treat as the "lead" (above uses the first), or
-> compute a max/min across `controllers` to suit your UX.
+These accessors track scope automatically: in `"all"` scope they span every
+source; under a single scope (or `lockedScope`) they collapse to just that one,
+so the same layout serves both the unified page and per-object pages.
+
+See [§10](#10-build-a-custom-unified-results-ui-grid--pager--filters--count) for
+a complete custom UI — merged grid, pagination widget, per-source filter panels,
+and a result count — assembled from these accessors and the exported primitives.
+
+> **How `"merged"` is exact.** For global page `P`, every in-scope source fetches
+> `(P + 1) × pageSize` rows from its front; concatenating them in config order
+> and slicing `[P × pageSize, (P + 1) × pageSize)` yields the precise page,
+> because the first `(P + 1) × pageSize` items of the concatenation are always
+> the true cumulative prefix. Cost grows with page depth (each Next refetches a
+> larger window), so it suits a combined grid, not an infinite feed.
+>
+> **`"per-source"` model.** Sources paginate with independent cursors — no global
+> offset — so the "global page" is the furthest-advanced in-scope source's page.
+> `goToNextPage` advances only sources that still have data; a source that runs
+> out is **left behind** and drops out of `mergedResults` on later pages (its
+> final page was already shown). `pageCount` is the max of
+> `ceil(totalCount / pageSize)` across in-scope sources, and `goToPage` honours
+> only adjacent pages. For fully independent pagers, render one `<SourceSection>`
+> (or `PaginationControls`) per `handle.sources[key]` and skip the aggregate API.
+
+### 10. Build a custom unified-results UI (grid + pager + filters + count)
+
+For a combined **card grid** with one **shared** pager, a **total-results
+count**, and **per-source filter panels**, the fastest path is
+`config.pagination.mode: "merged"` on the drop-in `<Search>` — it renders all of
+this ([§9](#9-global-pagination-across-all-sources)). Drop to the headless
+recipe below only when you need control the drop-in doesn't expose (a bespoke
+grid container, custom chrome placement, extra surrounding UI): assemble it
+yourself from `useSearch` plus the exported primitives. This is what the
+`propertymanagementapp` template's `UnifiedSearch` component used to hand-roll
+before adopting merged mode; the skeleton below is the same recipe, trimmed to
+the essentials.
+
+The pieces you compose:
+
+| Piece                 | What renders it                                                 | Source of truth                       |
+| --------------------- | --------------------------------------------------------------- | ------------------------------------- |
+| Search box            | `<SearchBar value={handle.q} onChange={handle.setQ} />`         | `handle.q` / `handle.setQ`            |
+| Scope selector        | `<ScopeSelector config scope onScopeChange />`                  | `handle.scope` / `handle.setScope`    |
+| **Result count**      | your own `<p>` reading `page.totalCount`                        | `handle.globalPagination.totalCount`  |
+| **Merged grid**       | map over `handle.mergedResults` → your card per `sourceKey`     | `handle.mergedResults`                |
+| **Pagination widget** | `<PaginationControls …{page} />`                                | `handle.globalPagination`             |
+| **Filter panel**      | `<FilterProvider>` + `<DefaultFilterPanel source>` (per source) | `handle.inScopeSources[i]` controller |
+
+Two rules make the layout work in **every** scope — the unified "All" view, a
+single source picked in the selector, and a `lockedScope` page — from one
+implementation:
+
+1. **Render the count on its own row, directly above the grid, unconditionally.**
+   `page.totalCount` is the cumulative in-scope total, so it's meaningful whether
+   one source or all of them are in scope. Don't gate it on scope.
+2. **Show per-source filter chrome only when a single source is in scope.** Under
+   "All", heterogeneous per-source filters can't be combined into one panel, so
+   collapse to just the count. Detect this with `handle.scope !== ALL_SCOPE`
+   (then `handle.inScopeSources[0]` is the sole controller).
+
+```tsx
+import {
+  useSearch,
+  SearchBar,
+  ScopeSelector,
+  SortControl,
+  ActiveFilters,
+  FilterProvider,
+  FilterResetButton,
+  DefaultFilterPanel,
+  PaginationControls,
+  ALL_SCOPE,
+} from "@salesforce/ui-bundle-template-feature-react-search";
+
+function UnifiedSearch({ restrictTo }: { restrictTo?: string }) {
+  // config.pagination = { mode: "merged", mergeOrder: "proportional",
+  //   pageSize: 6, pageSizeOptions: [6, 12, 24] } — see §9 and §11.
+  const handle = useSearch(config, { lockedScope: restrictTo });
+  const { globalPagination: page, mergedResults } = handle;
+
+  const singleSourceInScope = handle.scope !== ALL_SCOPE;
+  const soleController = singleSourceInScope ? handle.inScopeSources[0] : undefined;
+
+  return (
+    <div className="max-w-6xl mx-auto px-4 py-6 space-y-6">
+      {/* Row 1 — search box + scope selector (hidden when the scope is locked). */}
+      <div className="flex flex-wrap items-center gap-3">
+        <SearchBar value={handle.q} onChange={handle.setQ} placeholder="Search…" />
+        {!handle.scopeLocked && (
+          <ScopeSelector config={config} scope={handle.scope} onScopeChange={handle.setScope} />
+        )}
+      </div>
+
+      {/* Row 2 — the sole source's filters + sort, only under a single scope. */}
+      {singleSourceInScope && soleController && (
+        <FilterProvider
+          filters={soleController.filters.active}
+          onFilterChange={soleController.filters.set}
+          onFilterRemove={soleController.filters.remove}
+          onReset={() =>
+            soleController.filters.active.forEach((f) => soleController.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-3">
+              <DefaultFilterPanel source={soleController.config} />
+            </div>
+            {soleController.config.sortBy && (
+              <SortControl
+                configs={soleController.config.sortBy}
+                sort={soleController.sort.current}
+                onSortChange={soleController.sort.set}
+              />
+            )}
+            <ActiveFilters
+              filters={soleController.filters.active}
+              onRemove={soleController.filters.remove}
+            />
+          </div>
+        </FilterProvider>
+      )}
+
+      {/* Count — its own row, directly above the grid, in EVERY scope. */}
+      {!handle.loading && !handle.error && (
+        <p className="text-sm text-muted-foreground" role="status">
+          {page.totalCount} total result{page.totalCount === 1 ? "" : "s"}
+        </p>
+      )}
+
+      {/* Merged, cumulatively-paginated card grid. Each item knows its source. */}
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+        {mergedResults.map(({ sourceKey, node }, i) => (
+          <MyCard key={i} sourceKey={sourceKey} node={node} />
+        ))}
+      </div>
+
+      {/* One shared pager over the cumulative set. Passing pageCount + onGoToPage
+          renders numbered page buttons; omit them for prev/next only. */}
+      {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={handle.loading || !!handle.error}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+Notes:
+
+- **`MyCard`** switches on `sourceKey` to pick the right card component per
+  object type (see [§8](#8-mixed-card-layouts-per-source)). Read node fields with
+  the exported `fieldValue()`, or render a `<DefaultResultRow node source>` for a
+  built-in row.
+- **Filter primitives are wired through `FilterProvider`**, not props — anything
+  inside it (`DefaultFilterPanel`, or individual `TextFilter` / `SelectFilter`
+  from [§6](#6-replace-a-sources-filter-sidebar)) reads and writes that source's
+  filter state automatically.
+- **The pager needs `mode: "merged"`** in `config.pagination` for the "shows
+  exactly `pageSize` cards, `goToPage` jumps anywhere" behavior above. Under the
+  default `"per-source"` mode the same widget still works but paginates each
+  source on its own cursor (see the §9 mode table).
+- **This same component serves single-object pages** — pass `restrictTo` (a
+  source key) as `lockedScope`; `scopeLocked` becomes `true`, the selector hides,
+  and `mergedResults` / `page` collapse to that one source. The count and pager
+  code paths are unchanged.
+
+### 11. Choosing a merge order (sequential vs proportional)
+
+`config.pagination.mergeOrder` decides how `"merged"`-mode results from
+different sources are ordered within each page. It only matters when 2+ sources
+are in scope; it's ignored in `"per-source"` mode and under a single scope.
+
+| Order                    | Behavior                                                                | Reach for it when…                                                                                              |
+| ------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `"sequential"` (default) | All of source 1, then all of source 2, … in config order.               | One source is primary and the rest are secondary — e.g. Accounts first, then supporting Contacts/Opportunities. |
+| `"interleaved"`          | Round-robin, one per source per round — every source ranks **equally**. | You want a fair sample of each type up front regardless of how many hits each has (e.g. a "spotlight" grid).    |
+| `"proportional"`         | Each source spread across the list in proportion to its result count.   | You want each page to mirror the overall mix — larger result sets appear more often, matching their share.      |
+
+**Sequential — front-loads by config order.** The first source fills the early
+pages; later sources only appear once the earlier ones are exhausted. Best when
+there's a natural priority. With `pageSize: 6` and Accounts (100 hits) before
+Contacts (20), page 1 is 6 Accounts, and Contacts don't surface until ~page 17.
+
+```tsx
+const config: SearchConfig = {
+  pagination: {
+    mode: "merged",
+    mergeOrder: "sequential",
+    pageSize: 6,
+    pageSizeOptions: [6, 12, 24],
+  },
+  sources: [
+    { kind: "sobject", key: "accounts" /* … */ }, // leads
+    { kind: "sobject", key: "contacts" /* … */ }, // follows
+    { kind: "sobject", key: "opportunities" /* … */ }, // last
+  ],
+};
+```
+
+**Proportional — every page reflects the mix.** Each source is spread evenly by
+its `totalCount`, so a source with 100 hits appears ~5× as often as one with 20.
+With the same 100 Accounts / 20 Contacts and `pageSize: 6`, roughly every page is
+5 Accounts + 1 Contact — the 5:1 ratio of the whole result set — so a user sees
+all types from page 1 without one type monopolizing the front.
+
+```tsx
+const config: SearchConfig = {
+  pagination: {
+    mode: "merged",
+    mergeOrder: "proportional",
+    pageSize: 6,
+    pageSizeOptions: [6, 12, 24],
+  },
+  sources: [
+    { kind: "sobject", key: "accounts" /* … */ },
+    { kind: "sobject", key: "contacts" /* … */ },
+    { kind: "sobject", key: "opportunities" /* … */ },
+  ],
+};
+```
+
+> Proportional reads each source's `totalCount` to compute its share, so a source
+> that omits `totalCount` falls back to its fetched node count for weighting. Page
+> boundaries stay exact under all three orders — only the **order within** the
+> cumulative list changes, never which items belong to page `P`.
 
 ---
 
@@ -683,6 +1020,11 @@ import type {
   it again duplicates the selection.
 - **`routePattern` token not in `displayFields`** — the token can't resolve and
   every row silently falls back to a non-clickable layout.
+- **`routePattern` without a matching route** — the feature only builds the
+  `<Link>`; it doesn't create the destination. If nothing in your app routes
+  `"/accounts/:id"` to a detail page, the link lands on a blank/not-found view.
+  Register the route + page yourself (or omit `routePattern` and render details
+  another way, e.g. a modal).
 - **Non-conforming `key`** — must match `/^[A-Za-z_][A-Za-z0-9_]*$/`; it becomes
   a GraphQL alias and variable prefix. Invalid keys produce malformed documents.
 - **Picklist auto-fetch failing** — the aggregate `groupBy` requires a