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

package/src/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/src/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;
 };