@salesforce/ui-bundle-template-app-react-template-b2x 11.17.1 → 11.19.0

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/search/components/SearchResults.tsx

@@ -0,0 +1,77 @@
+/**
+ * Renders one SourceSection per configured source, in declaration order.
+ *
+ * Customization is optional — sensible defaults kick in for any source you
+ * don't override:
+ *   - `renderResult[sourceKey]` — per-node renderer. Default: title from
+ *     `displayFields[0]`, subtitle from the rest, optional `<Link>` driven
+ *     by `routePattern`.
+ *   - `renderFilters[sourceKey]` — sidebar filter UI. Default: one input per
+ *     `filterBy` entry, with picklist options resolved from inline
+ *     config or auto-fetched from the GraphQL aggregate API.
+ *
+ * Pass `false` for either entry to suppress the default for that source.
+ *
+ * Filter chrome (sidebar + active-filter chips + sort dropdown) is
+ * automatically hidden when `handle.scope === "all"` — per-source controls
+ * would be unreachable with every source on screen, and dangling chips
+ * would be confusing. Pre-existing filter / sort selections stay in state,
+ * so narrowing the scope brings them back unchanged.
+ */
+
+import type { ReactNode } from "react";
+import { SourceSection } from "./SourceSection";
+import { DefaultResultRow } from "./results/DefaultResultRow";
+import { DefaultFilterPanel } from "./filters/DefaultFilterPanel";
+import { ALL_SCOPE, type SearchHandle } from "../types";
+
+type ResultRenderer = ((node: unknown) => ReactNode) | false;
+type FilterRenderer = (() => ReactNode) | false;
+
+interface SearchResultsProps {
+	handle: SearchHandle;
+	renderResult?: Record<string, ResultRenderer>;
+	renderFilters?: Record<string, FilterRenderer>;
+	emptyMessages?: Record<string, string>;
+}
+
+export function SearchResults({
+	handle,
+	renderResult,
+	renderFilters,
+	emptyMessages,
+}: SearchResultsProps) {
+	const filtersHidden = handle.scope === ALL_SCOPE;
+	return (
+		<div className="space-y-10">
+			{Object.entries(handle.sources).map(([key, controller]) => {
+				if (handle.scope !== ALL_SCOPE && handle.scope !== key) return null;
+				const overrideResult = renderResult?.[key];
+				if (overrideResult === false) return null;
+				const resolvedRenderResult: (node: unknown) => ReactNode =
+					overrideResult ?? ((node) => <DefaultResultRow node={node} source={controller.config} />);
+
+				const overrideFilters = renderFilters?.[key];
+				const hasFilterFields = (controller.config.filterBy?.length ?? 0) > 0;
+				const resolvedRenderFilters: (() => ReactNode) | undefined =
+					overrideFilters === false
+						? undefined
+						: (overrideFilters ??
+							(hasFilterFields
+								? () => <DefaultFilterPanel source={controller.config} />
+								: undefined));
+
+				return (
+					<SourceSection
+						key={key}
+						controller={controller}
+						renderResult={resolvedRenderResult}
+						renderFilters={resolvedRenderFilters}
+						hideFilterChrome={filtersHidden}
+						emptyMessage={emptyMessages?.[key]}
+					/>
+				);
+			})}
+		</div>
+	);
+}

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/search/components/SourceSection.tsx

@@ -0,0 +1,166 @@
+/**
+ * Renders one source's slice of a search result: optional filter
+ * panel, sort dropdown, active-filter chips, the result list (delegated to
+ * the caller via `renderResult`), and pagination controls.
+ *
+ * The component is "smart" only about orchestration. The actual list-item UI
+ * is owned by the application via the `renderResult(node)` callback —
+ * search never decides how an Account or Contact card looks.
+ */
+
+import type { ReactNode } from "react";
+import { AlertCircle, SearchX } from "lucide-react";
+import { Alert, AlertDescription, AlertTitle } from "../../../components/ui/alert";
+import { Skeleton } from "../../../components/ui/skeleton";
+import { ActiveFilters } from "./filters/ActiveFilters";
+import { FilterProvider, FilterResetButton } from "./filters/FilterContext";
+import { PaginationControls } from "./controls/PaginationControls";
+import { SortControl } from "./controls/SortControl";
+import type { SourceController } from "../types";
+
+interface SourceSectionProps {
+	controller: SourceController;
+	renderResult: (node: unknown) => ReactNode;
+	/** Optional filter UI (TextFilter, SelectFilter, ...) rendered above the results. */
+	renderFilters?: () => ReactNode;
+	/**
+	 * Suppress the filter panel, the active-filter chips, and the sort
+	 * dropdown. Pre-existing filter / sort selections stay in state (and
+	 * apply to the GraphQL query) so the caller can restore the chrome
+	 * without losing the user's selections, but no chrome surface is rendered.
+	 *
+	 * Set by `<SearchResults>` when the current scope is "all" — per-source
+	 * controls would be unreachable while every source is on screen, and
+	 * dangling chips would be confusing.
+	 */
+	hideFilterChrome?: boolean;
+	emptyMessage?: string;
+	className?: string;
+}
+
+export function SourceSection({
+	controller,
+	renderResult,
+	renderFilters,
+	hideFilterChrome,
+	emptyMessage,
+	className,
+}: SourceSectionProps) {
+	const { config, result, loading, error, filters, sort, pagination } = controller;
+	const nodes = result?.nodes ?? [];
+	const totalCount = result?.totalCount;
+	const showResults = !loading && !error && nodes.length > 0;
+	const showEmpty = !loading && !error && nodes.length === 0;
+
+	const pageSizeOptions = pagination.pageSizeOptions ?? [pagination.pageSize];
+
+	const showFilterPanel = !!renderFilters && !hideFilterChrome;
+	const showActiveChips = !hideFilterChrome && filters.active.length > 0;
+	const showSortControl = !hideFilterChrome && (config.sortBy?.length ?? 0) > 0;
+
+	return (
+		<section className={`flex flex-col gap-6 ${className ?? ""}`}>
+			{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">
+							{renderFilters!()}
+						</div>
+					</div>
+				</FilterProvider>
+			)}
+
+			<div className="min-w-0">
+				<header className="flex flex-wrap items-baseline gap-3 mb-3">
+					<h2 className="text-lg font-semibold">{config.label}</h2>
+				</header>
+
+				{(showSortControl || showActiveChips) && (
+					<div className="flex flex-wrap items-center gap-2 mb-3">
+						{showSortControl && config.sortBy ? (
+							<SortControl configs={config.sortBy} sort={sort.current} onSortChange={sort.set} />
+						) : null}
+						{showActiveChips && (
+							<ActiveFilters filters={filters.active} onRemove={filters.remove} />
+						)}
+					</div>
+				)}
+
+				{/* Result count, shown just above the results in every scope —
+				    including a locked / single-source (restrictTo) view. */}
+				{!loading && !error && totalCount != null && (
+					<p className="text-sm text-muted-foreground mb-3">
+						{totalCount} {totalCount === 1 ? "result" : "results"}
+					</p>
+				)}
+
+				<div className="min-h-32">
+					{loading && (
+						<div className="space-y-2">
+							{Array.from({ length: Math.min(pagination.pageSize, 5) }, (_, i) => (
+								<Skeleton key={i} className="h-12 w-full" />
+							))}
+						</div>
+					)}
+
+					{error && (
+						<Alert variant="destructive" role="alert">
+							<AlertCircle />
+							<AlertTitle>Failed to load {config.label}</AlertTitle>
+							<AlertDescription>{error}</AlertDescription>
+						</Alert>
+					)}
+
+					{showResults && (
+						<ul className="divide-y">
+							{nodes.map((node, i) => (
+								<li key={getNodeKey(node, config.idField, i)} className="py-3">
+									{renderResult(node)}
+								</li>
+							))}
+						</ul>
+					)}
+
+					{showEmpty && (
+						<div className="flex flex-col items-center justify-center py-10 text-center">
+							<SearchX className="size-10 text-muted-foreground mb-3" />
+							<p className="text-sm text-muted-foreground">
+								{emptyMessage ?? `No ${config.label.toLowerCase()} found.`}
+							</p>
+						</div>
+					)}
+				</div>
+
+				<PaginationControls
+					pageIndex={pagination.pageIndex}
+					hasNextPage={pagination.hasNextPage}
+					hasPreviousPage={pagination.hasPreviousPage}
+					pageSize={pagination.pageSize}
+					pageSizeOptions={pageSizeOptions}
+					onNextPage={pagination.goToNextPage}
+					onPreviousPage={pagination.goToPreviousPage}
+					onPageSizeChange={pagination.setPageSize}
+					disabled={loading || !!error}
+					idPrefix={`page-size-${config.key}`}
+				/>
+			</div>
+		</section>
+	);
+}
+
+function getNodeKey(node: unknown, idField: string | undefined, fallback: number): string | number {
+	if (node && typeof node === "object") {
+		const id = (node as Record<string, unknown>)[idField ?? "Id"];
+		if (typeof id === "string" || typeof id === "number") return id;
+	}
+	return fallback;
+}

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/search/components/controls/PaginationControls.tsx

@@ -0,0 +1,185 @@
+import {
+	Pagination,
+	PaginationContent,
+	PaginationEllipsis,
+	PaginationItem,
+	PaginationLink,
+	PaginationNext,
+	PaginationPrevious,
+} from "../../../../components/ui/pagination";
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../components/ui/select";
+import { Label } from "../../../../components/ui/label";
+import type { KeyboardEvent } from "react";
+
+interface PaginationControlsProps {
+	pageIndex: number;
+	hasNextPage: boolean;
+	hasPreviousPage: boolean;
+	pageSize: number;
+	pageSizeOptions: readonly number[];
+	onNextPage: () => void;
+	onPreviousPage: () => void;
+	onPageSizeChange: (size: number) => void;
+	/**
+	 * Total number of pages. When provided (with {@link onGoToPage}) and `> 1`,
+	 * the control renders numbered page buttons with ellipsis truncation instead
+	 * of a plain "Page N" label. Omit for cursor-style sources where the total
+	 * page count is unknown.
+	 */
+	pageCount?: number;
+	/** Jump to a 0-based page. Required to render numbered page buttons. */
+	onGoToPage?: (pageIndex: number) => void;
+	disabled?: boolean;
+	idPrefix?: string;
+}
+
+/**
+ * Builds the list of page tokens to render: 0-based page numbers plus
+ * `"ellipsis"` gap markers. Always shows the first and last page, a window
+ * around the current page, and collapses the rest. e.g. for current=5,
+ * total=12 → [0, ellipsis, 4, 5, 6, ellipsis, 11].
+ */
+function getPageTokens(currentIndex: number, pageCount: number): Array<number | "ellipsis"> {
+	const SIBLINGS = 1; // pages shown on each side of the current page
+	const last = pageCount - 1;
+	const pages = new Set<number>([0, last]);
+	for (let p = currentIndex - SIBLINGS; p <= currentIndex + SIBLINGS; p++) {
+		if (p >= 0 && p <= last) pages.add(p);
+	}
+	const sorted = [...pages].sort((a, b) => a - b);
+	const tokens: Array<number | "ellipsis"> = [];
+	let prev = -1;
+	for (const p of sorted) {
+		if (prev !== -1 && p - prev > 1) tokens.push("ellipsis");
+		tokens.push(p);
+		prev = p;
+	}
+	return tokens;
+}
+
+export function PaginationControls({
+	pageIndex,
+	hasNextPage,
+	hasPreviousPage,
+	pageSize,
+	pageSizeOptions,
+	onNextPage,
+	onPreviousPage,
+	onPageSizeChange,
+	pageCount,
+	onGoToPage,
+	disabled = false,
+	idPrefix = "page-size",
+}: PaginationControlsProps) {
+	const handlePageSizeChange = (next: string) => {
+		const size = parseInt(next, 10);
+		if (!isNaN(size) && size !== pageSize) onPageSizeChange(size);
+	};
+	const prevDisabled = disabled || !hasPreviousPage;
+	const nextDisabled = disabled || !hasNextPage;
+	const selectId = `${idPrefix}-select`;
+
+	// Numbered page buttons require both a known page count and a seek callback.
+	const showNumberedPages = pageCount != null && pageCount > 1 && onGoToPage != null;
+
+	// The underlying pagination control renders an <a> without an href, so it is
+	// not keyboard-operable on its own. Activate it on Enter/Space to match the
+	// behaviour of a native button (WCAG 2.2 SC 2.1.1 Keyboard).
+	const handleActivationKey = (action: () => void) => (event: KeyboardEvent) => {
+		if (event.key === "Enter" || event.key === " ") {
+			event.preventDefault();
+			action();
+		}
+	};
+
+	return (
+		<div className="w-full grid grid-cols-1 sm:grid-cols-2 items-center gap-4 py-2">
+			<div className="flex justify-center sm:justify-start items-center gap-2">
+				<Label htmlFor={selectId} className="text-sm font-normal whitespace-nowrap">
+					Results per page:
+				</Label>
+				<Select
+					value={pageSize.toString()}
+					onValueChange={handlePageSizeChange}
+					disabled={disabled}
+				>
+					<SelectTrigger id={selectId} className="w-16">
+						<SelectValue />
+					</SelectTrigger>
+					<SelectContent>
+						{pageSizeOptions.map((size) => (
+							<SelectItem key={size} value={size.toString()}>
+								{size}
+							</SelectItem>
+						))}
+					</SelectContent>
+				</Select>
+			</div>
+			<Pagination className="w-full mx-0 sm:justify-end">
+				<PaginationContent>
+					<PaginationItem>
+						<PaginationPrevious
+							role="button"
+							tabIndex={prevDisabled ? -1 : 0}
+							onClick={prevDisabled ? undefined : onPreviousPage}
+							onKeyDown={prevDisabled ? undefined : handleActivationKey(onPreviousPage)}
+							aria-disabled={prevDisabled}
+							className={prevDisabled ? "pointer-events-none opacity-50" : "cursor-pointer"}
+						/>
+					</PaginationItem>
+
+					{showNumberedPages ? (
+						getPageTokens(pageIndex, pageCount).map((token, i) =>
+							token === "ellipsis" ? (
+								<PaginationItem key={`ellipsis-${i}`}>
+									<PaginationEllipsis />
+								</PaginationItem>
+							) : (
+								<PaginationItem key={token}>
+									<PaginationLink
+										role="button"
+										tabIndex={disabled ? -1 : 0}
+										isActive={token === pageIndex}
+										aria-label={`Go to page ${token + 1}`}
+										aria-current={token === pageIndex ? "page" : undefined}
+										onClick={disabled ? undefined : () => onGoToPage(token)}
+										onKeyDown={disabled ? undefined : handleActivationKey(() => onGoToPage(token))}
+										aria-disabled={disabled}
+										className={disabled ? "pointer-events-none opacity-50" : "cursor-pointer"}
+									>
+										{token + 1}
+									</PaginationLink>
+								</PaginationItem>
+							),
+						)
+					) : (
+						<PaginationItem>
+							<span className="min-w-16 text-center text-sm text-muted-foreground px-2">
+								{pageCount != null && pageCount > 0
+									? `Page ${pageIndex + 1} of ${pageCount}`
+									: `Page ${pageIndex + 1}`}
+							</span>
+						</PaginationItem>
+					)}
+
+					<PaginationItem>
+						<PaginationNext
+							role="button"
+							tabIndex={nextDisabled ? -1 : 0}
+							onClick={nextDisabled ? undefined : onNextPage}
+							onKeyDown={nextDisabled ? undefined : handleActivationKey(onNextPage)}
+							aria-disabled={nextDisabled}
+							className={nextDisabled ? "pointer-events-none opacity-50" : "cursor-pointer"}
+						/>
+					</PaginationItem>
+				</PaginationContent>
+			</Pagination>
+		</div>
+	);
+}

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/search/components/controls/ScopeSelector.tsx

@@ -0,0 +1,55 @@
+/**
+ * Dropdown that narrows the search to a single source (or "All").
+ *
+ * Sits next to the search bar in the default {@link Search} layout. The
+ * options are derived from the configured sources: an "All" entry plus one
+ * entry per source (using each source's `label`).
+ *
+ * Selecting a non-"All" scope tells {@link useSearch} to fetch and render
+ * only that source. Switching scope resets per-source pagination cursors —
+ * the visible result set is changing.
+ */
+
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../components/ui/select";
+import { ALL_SCOPE, type SearchConfig, type SearchScope } from "../../types";
+
+interface ScopeSelectorProps {
+	config: SearchConfig;
+	scope: SearchScope;
+	onScopeChange: (scope: SearchScope) => void;
+	allLabel?: string;
+	className?: string;
+}
+
+export function ScopeSelector({
+	config,
+	scope,
+	onScopeChange,
+	allLabel = "All",
+	className,
+}: ScopeSelectorProps) {
+	if (config.sources.length === 0) return null;
+	return (
+		<div className={className}>
+			<Select value={scope} onValueChange={onScopeChange}>
+				<SelectTrigger size="sm" className="min-w-[140px]" aria-label="Search scope">
+					<SelectValue />
+				</SelectTrigger>
+				<SelectContent>
+					<SelectItem value={ALL_SCOPE}>{allLabel}</SelectItem>
+					{config.sources.map((source) => (
+						<SelectItem key={source.key} value={source.key}>
+							{source.label}
+						</SelectItem>
+					))}
+				</SelectContent>
+			</Select>
+		</div>
+	);
+}

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/search/components/controls/SearchBar.tsx

@@ -0,0 +1,55 @@
+import { Search } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { Input } from "../../../../components/ui/input";
+import { debounce } from "../../utils/debounce";
+
+const TYPE_DEBOUNCE_MS = 250;
+
+interface SearchBarProps {
+	value: string;
+	onChange: (next: string) => void;
+	placeholder?: string;
+	className?: string;
+}
+
+/**
+ * Debounced text input for the global `q` term. Keeps a local `draft` so
+ * keystrokes feel responsive while the upstream `onChange` is rate-limited.
+ */
+export function SearchBar({ value, onChange, placeholder = "Search…", className }: SearchBarProps) {
+	const [draft, setDraft] = useState(value);
+	const onChangeRef = useRef(onChange);
+	useEffect(() => {
+		onChangeRef.current = onChange;
+	});
+
+	// Build the debounced caller in a mount effect, not during render: creating it
+	// inline would read onChangeRef.current at render time (react-hooks/refs). It
+	// stays a single stable instance and always calls the latest onChange via the ref.
+	const debouncedRef = useRef<((next: string) => void) | undefined>(undefined);
+	useEffect(() => {
+		debouncedRef.current = debounce((next: string) => onChangeRef.current(next), TYPE_DEBOUNCE_MS);
+	}, []);
+
+	// External value can change (URL restore, reset). Keep draft in sync.
+	useEffect(() => {
+		setDraft(value);
+	}, [value]);
+
+	return (
+		<div className={`relative flex-1 ${className ?? ""}`}>
+			<Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+			<Input
+				type="text"
+				value={draft}
+				onChange={(e) => {
+					setDraft(e.target.value);
+					debouncedRef.current?.(e.target.value);
+				}}
+				placeholder={placeholder}
+				className="pl-9"
+				aria-label="Unified search"
+			/>
+		</div>
+	);
+}

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/search/components/controls/SortControl.tsx

@@ -0,0 +1,62 @@
+import { ArrowDown, ArrowUp } from "lucide-react";
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../components/ui/select";
+import { Button } from "../../../../components/ui/button";
+import type { SortFieldConfig, SortState } from "../../utils/sortUtils";
+
+const NONE_VALUE = "__none__";
+
+interface SortControlProps {
+	configs: SortFieldConfig[];
+	sort: SortState | null;
+	onSortChange: (sort: SortState | null) => void;
+	className?: string;
+}
+
+export function SortControl({ configs, sort, onSortChange, className }: SortControlProps) {
+	if (configs.length === 0) return null;
+	return (
+		<div className={`flex items-center gap-2 ${className ?? ""}`}>
+			<span className="text-sm text-muted-foreground whitespace-nowrap">Sort by</span>
+			<Select
+				value={sort?.field ?? NONE_VALUE}
+				onValueChange={(v) => {
+					if (v === NONE_VALUE) onSortChange(null);
+					else onSortChange({ field: v, direction: sort?.direction ?? "ASC" });
+				}}
+			>
+				<SelectTrigger size="sm" className="w-[160px]">
+					<SelectValue placeholder="Default" />
+				</SelectTrigger>
+				<SelectContent>
+					<SelectItem value={NONE_VALUE}>Default</SelectItem>
+					{configs.map((c) => (
+						<SelectItem key={c.field} value={c.field}>
+							{c.label}
+						</SelectItem>
+					))}
+				</SelectContent>
+			</Select>
+			{sort && (
+				<Button
+					variant="ghost"
+					size="icon-sm"
+					onClick={() =>
+						onSortChange({
+							...sort,
+							direction: sort.direction === "ASC" ? "DESC" : "ASC",
+						})
+					}
+					aria-label={`Sort ${sort.direction === "ASC" ? "descending" : "ascending"}`}
+				>
+					{sort.direction === "ASC" ? <ArrowUp /> : <ArrowDown />}
+				</Button>
+			)}
+		</div>
+	);
+}

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/search/components/filters/ActiveFilters.tsx

@@ -0,0 +1,61 @@
+import { X } from "lucide-react";
+import { Button } from "../../../../components/ui/button";
+import type { ActiveFilterValue } from "../../utils/filterUtils";
+
+function formatLabel(filter: ActiveFilterValue): string {
+	const { label, type, value, min, max } = filter;
+	switch (type) {
+		case "text":
+		case "picklist":
+			return `${label}: ${value ?? ""}`;
+		case "multipicklist": {
+			const values = value ? value.split(",") : [];
+			if (values.length <= 2) return `${label}: ${values.join(", ")}`;
+			return `${label}: ${values.length} selected`;
+		}
+		case "boolean":
+			return `${label}: ${value === "true" ? "Yes" : "No"}`;
+		case "numeric": {
+			if (min && max) return `${label}: ${min} – ${max}`;
+			if (min) return `${label}: ≥ ${min}`;
+			return `${label}: ≤ ${max ?? ""}`;
+		}
+		case "date":
+		case "daterange":
+		case "datetime":
+		case "datetimerange": {
+			if (min && max) return `${label}: ${min} → ${max}`;
+			if (min) return `${label}: from ${min}`;
+			return `${label}: until ${max ?? ""}`;
+		}
+		default:
+			return label;
+	}
+}
+
+interface ActiveFiltersProps {
+	filters: ActiveFilterValue[];
+	onRemove: (field: string) => void;
+	className?: string;
+}
+
+export function ActiveFilters({ filters, onRemove, className }: ActiveFiltersProps) {
+	if (filters.length === 0) return null;
+	return (
+		<div className={`flex flex-wrap gap-2 ${className ?? ""}`}>
+			{filters.map((filter) => (
+				<Button
+					key={filter.field}
+					variant="outline"
+					size="sm"
+					className="gap-1 h-7 text-xs"
+					aria-label={`Remove ${formatLabel(filter)}`}
+					onClick={() => onRemove(filter.field)}
+				>
+					{formatLabel(filter)}
+					<X className="h-3 w-3" aria-hidden="true" />
+				</Button>
+			))}
+		</div>
+	);
+}