@salesforce/ui-bundle-template-feature-react-search 11.3.0

package/README.md

@@ -0,0 +1,692 @@
+# @salesforce/ui-bundle-template-feature-react-search
+
+Configuration-driven, multi-source search for **React** applications on the
+Salesforce platform.
+
+> ⚛️ **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).
+
+You describe **what** is searchable in a single config object; the package owns
+**how** it's searched — GraphQL query construction, filter/sort/pagination
+state, URL sync, default rendering, and the orchestration UI. Most apps drop in
+one component and get a complete search page with zero custom code:
+
+```tsx
+import { Search, config } from "@salesforce/ui-bundle-template-feature-react-search";
+
+export default function SearchPage() {
+  return <Search config={config} />;
+}
+```
+
+Adding a new searchable object is a single entry in your config — no code
+changes.
+
+---
+
+## Table of contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [The `<Search>` component](#the-search-component)
+  - [Props](#props)
+- [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)
+  - [`routePattern` tokens](#routepattern-tokens)
+  - [A complete source, annotated](#a-complete-source-annotated)
+- [Use cases](#use-cases)
+  - [1. Unified search across many objects](#1-unified-search-across-many-objects)
+  - [2. Single-object search (`restrictTo`)](#2-single-object-search-restrictto)
+  - [3. Hand off a term from another page](#3-hand-off-a-term-from-another-page)
+  - [4. Custom row layout for one source](#4-custom-row-layout-for-one-source)
+  - [5. Hide a source from the results](#5-hide-a-source-from-the-results)
+  - [6. Replace a source's filter sidebar](#6-replace-a-sources-filter-sidebar)
+  - [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)
+- [URL and state conventions](#url-and-state-conventions)
+- [Public API](#public-api)
+- [Common mistakes](#common-mistakes)
+
+---
+
+## Requirements
+
+This is a **React-only** package. Your application must provide:
+
+- **React 19** and **react-router 7** — the components render React elements and
+  use react-router for navigation, URL sync, and result links.
+- **`@salesforce/platform-sdk`** — data is fetched via
+  `createDataSDK().graphql.query()` against the Salesforce uiapi GraphQL bridge.
+  Every source today is an SObject queried through this bridge.
+- **lucide-react** — used for the control icons.
+
+Your app must be wrapped in a react-router router (e.g. a `<BrowserRouter>` or a
+data router), since the search components read and write the URL.
+
+---
+
+## Installation
+
+```bash
+npm install @salesforce/ui-bundle-template-feature-react-search
+```
+
+Then import what you need from the package entry point:
+
+```tsx
+import { Search, config } from "@salesforce/ui-bundle-template-feature-react-search";
+```
+
+---
+
+## Quick start
+
+The package ships an example `config` you can import to try things out
+immediately. Render the drop-in `<Search>` against it:
+
+```tsx
+import { Search, config } from "@salesforce/ui-bundle-template-feature-react-search";
+
+export default function SearchPage() {
+  return <Search config={config} title="Search" searchPlaceholder="Search across Salesforce…" />;
+}
+```
+
+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.
+
+For a real application you'll typically pass [your own config](#creating-your-own-config).
+
+---
+
+## The `<Search>` component
+
+`<Search>` is the top of a layered API. Use it as-is, override individual
+slots, or drop down to the `useSearch` hook for full control:
+
+```
+<Search config />                         ← drop-in (most apps)
+   │
+   ├── <SearchBar /> + <SearchResults />  ← compose primitives + own header
+   │      └── <SourceSection /> per source
+   │             ├── <DefaultResultRow />     ← override per source
+   │             └── <DefaultFilterPanel />   ← override per source
+   │
+   └── useSearch(config)                  ← headless: build your own UI
+```
+
+### Props
+
+| Prop                | Type                                             | Default                        | Purpose                                                                                     |
+| ------------------- | ------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------- |
+| `config`            | `SearchConfig`                                   | — (required)                   | The source list. Pass your own, or the example `config` export.                             |
+| `title`             | `string`                                         | `"Search"`                     | Heading shown by the default header.                                                        |
+| `subtitle`          | `string`                                         | —                              | Sub-heading shown by the default header.                                                    |
+| `searchPlaceholder` | `string`                                         | `"Search…"`                    | Placeholder for the search input.                                                           |
+| `restrictTo`        | `{ kind: "sobject"; key: string }`               | —                              | Lock the page to one source. Hides the scope dropdown and only fetches/renders that source. |
+| `showScopeSelector` | `boolean`                                        | `true` when 2+ sources         | Force-show or hide the scope dropdown. Always hidden when `restrictTo` is set.              |
+| `allScopeLabel`     | `string`                                         | `"All"`                        | Label for the "search everything" entry in the scope dropdown.                              |
+| `renderResult`      | `Record<string, ((node) => ReactNode) \| false>` | —                              | Per source key: custom row renderer, or `false` to hide that source.                        |
+| `renderFilters`     | `Record<string, (() => ReactNode) \| false>`     | —                              | Per source key: custom filter sidebar, or `false` to suppress filters for that source.      |
+| `emptyMessages`     | `Record<string, string>`                         | —                              | Per source key: message shown when that source has no results.                              |
+| `renderHeader`      | `(handle: SearchHandle) => ReactNode`            | built-in title/subtitle header | Replace the entire header region.                                                           |
+| `className`         | `string`                                         | —                              | Extra classes on the outer container.                                                       |
+
+`renderResult` / `renderFilters` / `emptyMessages` are keyed by the source
+`key` from your config (e.g. `accounts`, `contacts`).
+
+---
+
+## Creating your own config
+
+A `SearchConfig` is just `{ sources: SObjectSourceConfig[] }`. 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 = {
+  sources: [
+    {
+      kind: "sobject",
+      key: "accounts",
+      objectName: "Account",
+      label: "Accounts",
+      routePattern: "/accounts/:id",
+      searchableFields: ["Name", "Phone", "Industry"],
+      displayFields: ["Name", "Industry", "Phone"],
+    },
+  ],
+};
+
+export default function SearchPage() {
+  return <Search config={config} />;
+}
+```
+
+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).
+
+Today every source is `kind: "sobject"`, queried through the platform-sdk
+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`.                                                  |
+
+### `displayFields` shapes
+
+Each entry controls both the GraphQL selection set **and** the default row
+layout (first entry → row title; the rest → subtitle, joined with `·`):
+
+| Form                                     | GraphQL emitted                            | Use for                                                           |
+| ---------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------- |
+| `"Name"` (string)                        | `Name @optional { value displayValue }`    | Ordinary scalar fields.                                           |
+| `{ name: "Owner", subfields: ["Name"] }` | `Owner @optional { Name @optional { … } }` | Relationship traversal (parent/lookup).                           |
+| `{ name: "SomeId", raw: true }`          | `SomeId`                                   | Fields not wrapped in `{ value displayValue }` (Id-like scalars). |
+
+> The `idField` (default `"Id"`) is always emitted — never list it explicitly.
+
+### `filterFields` types
+
+Each `FilterFieldConfig` is `{ field, label, type, options?, placeholder?, 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         |
+
+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`
+
+`sortFields` 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": [
+	{ "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.
+
+### `routePattern` tokens
+
+When set, the default row becomes a react-router `<Link>`:
+
+- `:id` → the configured `idField` value.
+- `:fieldName` → that field's value; supports dot-paths (`:Owner.Name`).
+
+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`.
+
+### A complete source, annotated
+
+```jsonc
+{
+  "kind": "sobject", // discriminator
+  "key": "leads", // GraphQL alias + URL namespace + result key
+  "objectName": "Lead", // GraphQL type
+  "label": "Leads", // section header + scope option
+  "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
+  "displayFields": [
+    "Name", // row title
+    "Title", // ┐
+    "Company", // ├ subtitle (joined with " · ")
+    "Email", // ┘
+    { "name": "Owner", "subfields": ["Name"] }, // relationship traversal
+  ],
+  "filterFields": [
+    { "field": "Status", "label": "Status", "type": "picklist" },
+    { "field": "Industry", "label": "Industry", "type": "picklist" },
+  ],
+  "sortFields": [
+    { "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>`.
+
+> **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
+> validation (e.g. a zod schema) if you need stricter guarantees.
+
+---
+
+## Use cases
+
+### 1. Unified search across many objects
+
+The default. Every source in the config is searched from one box; a scope
+dropdown lets the user narrow to a single object. Best for a global
+"search everything" page.
+
+```tsx
+<Search config={config} title="Search" />
+```
+
+### 2. Single-object search (`restrictTo`)
+
+Reuse the same config but lock the page to one source. The scope dropdown is
+hidden and only the matching source is fetched and rendered — ideal for a
+dedicated "Account search" or "Browse Contacts" page where the object is
+implied by the route.
+
+```tsx
+<Search
+  config={config}
+  title="Search Accounts"
+  searchPlaceholder="Search by name, phone, or industry…"
+  restrictTo={{ kind: "sobject", key: "accounts" }}
+/>
+```
+
+### 3. Hand off a term from another page
+
+The global term lives in the URL under `?q=` (the exported `GLOBAL_QUERY_KEY`).
+Navigate to the search page with `?q=` pre-filled and the input + results
+populate on arrival — handy for a simple search box on a Home page:
+
+```tsx
+import { useNavigate } from "react-router";
+
+function HomeSearchBox() {
+  const navigate = useNavigate();
+  const onSubmit = (term: string) => {
+    // `q` matches GLOBAL_QUERY_KEY, so the search page pre-fills on arrival.
+    navigate(`/accounts${term ? `?q=${encodeURIComponent(term)}` : ""}`);
+  };
+  // …render an input that calls onSubmit…
+}
+```
+
+### 4. Custom row layout for one source
+
+Override the default renderer for specific sources by key; others keep the
+default. Return `ReactNode` from `(node) => …` — narrow `node` to your own
+type. Use the exported `fieldValue()` to read `{ value, displayValue }` fields:
+
+```tsx
+import { Search, fieldValue } from "@salesforce/ui-bundle-template-feature-react-search";
+
+<Search
+  config={config}
+  renderResult={{
+    opportunities: (node) => {
+      const o = node as OpportunityNode;
+      return (
+        <div className="flex justify-between">
+          <span>{fieldValue(o.Name)}</span>
+          <span className="text-muted-foreground">{fieldValue(o.StageName)}</span>
+        </div>
+      );
+    },
+  }}
+/>;
+```
+
+### 5. Hide a source from the results
+
+Pass `false` for that source's `renderResult`. The source skips both the
+network request and its UI section:
+
+```tsx
+<Search config={config} renderResult={{ accounts: false }} />
+```
+
+### 6. Replace a source's filter sidebar
+
+Supply your own filter UI built from the exported filter inputs (they wire into
+the search state via `FilterContext`). Pass `false` to suppress filters
+entirely for a source.
+
+```tsx
+import {
+  Search,
+  TextFilter,
+  SelectFilter,
+} from "@salesforce/ui-bundle-template-feature-react-search";
+
+<Search
+  config={config}
+  renderFilters={{
+    accounts: () => (
+      <>
+        <TextFilter field="Name" label="Account Name" />
+        {/* SelectFilter / MultiSelectFilter take an explicit `options` list. */}
+        <SelectFilter
+          field="Industry"
+          label="Industry"
+          options={[
+            { value: "Technology", label: "Technology" },
+            { value: "Finance", label: "Finance" },
+          ]}
+        />
+      </>
+    ),
+  }}
+/>;
+```
+
+### 7. Headless — drive your own UI with `useSearch`
+
+Skip the orchestration components entirely and build a bespoke layout. The hook
+owns state, URL sync, and fetching; you render whatever you like from the
+returned `SearchHandle`.
+
+```tsx
+import { useSearch } from "@salesforce/ui-bundle-template-feature-react-search";
+
+function MySearch() {
+  const { q, setQ, sources, loading, error, resetAll } = useSearch(config);
+  // sources[key].result.nodes, .filters, .sort, .pagination …
+  // build your own UI from these.
+}
+```
+
+Lock the headless hook to a single source with
+`useSearch(config, { lockedScope: "accounts" })`.
+
+### 8. Mixed card layouts per source
+
+`renderResult` is keyed by source, so each object type can render a completely
+different card while the search bar, scope, and pagination stay shared. Sources
+without an entry fall back to the default row. Here Accounts render as a stat
+card and Contacts as an avatar row:
+
+```tsx
+import { Search, fieldValue } from "@salesforce/ui-bundle-template-feature-react-search";
+
+<Search
+  config={config}
+  renderResult={{
+    // Accounts → a bordered "stat" card.
+    accounts: (node) => {
+      const a = node as AccountNode;
+      return (
+        <div className="rounded-lg border p-4 flex items-center justify-between">
+          <div>
+            <p className="font-semibold">{fieldValue(a.Name)}</p>
+            <p className="text-sm text-muted-foreground">{fieldValue(a.Industry)}</p>
+          </div>
+          <span className="text-sm tabular-nums">{fieldValue(a.AnnualRevenue) ?? "—"}</span>
+        </div>
+      );
+    },
+    // Contacts → an avatar + two-line card.
+    contacts: (node) => {
+      const c = node as ContactNode;
+      const name = fieldValue(c.Name) ?? "—";
+      return (
+        <div className="flex items-center gap-3 py-1">
+          <span className="flex size-9 items-center justify-center rounded-full bg-muted text-sm font-medium">
+            {name.slice(0, 1)}
+          </span>
+          <div>
+            <p className="font-medium">{name}</p>
+            <p className="text-sm text-muted-foreground">{fieldValue(c.Email)}</p>
+          </div>
+        </div>
+      );
+    },
+    // `opportunities` omitted → keeps the built-in default row.
+  }}
+/>;
+```
+
+To render every source's results as cards in a responsive grid instead of the
+default stacked list, drop down to the headless hook (next example shows the
+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:
+
+```tsx
+import {
+  useSearch,
+  SearchBar,
+  DefaultResultRow,
+  PaginationControls,
+} from "@salesforce/ui-bundle-template-feature-react-search";
+
+function GloballyPaginatedSearch() {
+  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 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));
+
+  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. */}
+      <PaginationControls
+        pageIndex={pageIndex}
+        hasNextPage={hasNextPage}
+        hasPreviousPage={hasPreviousPage}
+        pageSize={pageSize}
+        pageSizeOptions={[5, 10, 20]}
+        onNextPage={goNext}
+        onPreviousPage={goPrev}
+        onPageSizeChange={setSize}
+        disabled={handle.loading}
+      />
+    </div>
+  );
+}
+```
+
+> 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.
+
+---
+
+## URL and state conventions
+
+State is reflected in the URL (debounced 300 ms), so searches are
+bookmarkable and shareable:
+
+| URL param                       | Meaning                                       |
+| ------------------------------- | --------------------------------------------- |
+| `q`                             | Global search term (broadcast to all sources) |
+| `scope=<key>`                   | Narrow to one source (omitted = "all")        |
+| `s.<key>.f.<field>=<value>`     | Single-value filter for a source              |
+| `s.<key>.f.<field>.min=<value>` | Range/numeric/date lower bound                |
+| `s.<key>.f.<field>.max=<value>` | Range/numeric/date upper bound                |
+| `s.<key>.sort=<field>`          | Source-specific sort field                    |
+| `s.<key>.dir=ASC\|DESC`         | Source-specific sort direction                |
+| `s.<key>.ps=<n>`                | Source-specific page size                     |
+| `s.<key>.page=<n>`              | Source-specific 1-based page index            |
+
+Changing `q` resets every source's pagination; changing a source's filter or
+sort resets that source's pagination only. Cursors back the prev/next paging
+but are not persisted to the URL (only the page index is).
+
+When `restrictTo` / `lockedScope` is set, `?scope=` is **not** written — the
+route already implies the source.
+
+---
+
+## Public API
+
+Everything is exported from the package entry point:
+
+```ts
+// Drop-in + example config
+import { Search, config } from "@salesforce/ui-bundle-template-feature-react-search";
+
+// Hooks
+import {
+  useSearch,
+  useAsyncData,
+  useDistinctValues,
+} from "@salesforce/ui-bundle-template-feature-react-search";
+
+// Composition primitives
+import {
+  SearchBar,
+  SearchResults,
+  SourceSection,
+  SortControl,
+  PaginationControls,
+  ScopeSelector,
+  ActiveFilters,
+  DefaultResultRow,
+  DefaultFilterPanel,
+} from "@salesforce/ui-bundle-template-feature-react-search";
+
+// Filter inputs + context
+import {
+  FilterProvider,
+  FilterResetButton,
+  useFilterField,
+  useFilterPanel,
+  TextFilter,
+  SelectFilter,
+  MultiSelectFilter,
+  NumericRangeFilter,
+  BooleanFilter,
+  DateRangeFilter,
+  FilterFieldWrapper,
+} from "@salesforce/ui-bundle-template-feature-react-search";
+
+// Utilities / lower-level building blocks
+import {
+  fieldValue,
+  buildFilter,
+  buildGlobalQueryClause,
+  buildOrderBy,
+  readSourceParams,
+  writeSourceParams,
+  GLOBAL_QUERY_KEY,
+  buildSearchQuery,
+  runSearch,
+  fetchDistinctValues,
+  ALL_SCOPE,
+} from "@salesforce/ui-bundle-template-feature-react-search";
+
+// Types
+import type {
+  SearchConfig,
+  SObjectSourceConfig,
+  DisplayField,
+  SourceController,
+  SourceResult,
+  SourcePageInfo,
+  SearchHandle,
+  SearchScope,
+  RenderResultFn,
+  FilterFieldConfig,
+  FilterFieldType,
+  ActiveFilterValue,
+  SortFieldConfig,
+  SortState,
+  PicklistOption,
+  SourceRequest,
+  SearchQueryPayload,
+} from "@salesforce/ui-bundle-template-feature-react-search";
+```
+
+---
+
+## Common mistakes
+
+- **Missing `searchableFields`** — the global `q` won't match that source.
+  Provide at least one field, or omit the source when `q` is non-empty.
+- **Relationship field without `subfields`** — `"Owner"` as a bare string emits
+  `Owner @optional { value displayValue }`, which is wrong for a relationship.
+  Use `{ name: "Owner", subfields: ["Name"] }`.
+- **Listing `idField` in `displayFields`** — it's selected automatically; listing
+  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.
+- **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
+  group-by-able field. For formulas / long text, supply inline `options`.
+- **Overriding `whereTypeName` / `orderByTypeName` needlessly** — only set these
+  when the schema deviates from `${ObjectName}_Filter` / `${ObjectName}_OrderBy`.
+  Wrong names cause GraphQL parse errors.