@salesforce/ui-bundle-template-feature-react-global-search 1.117.2

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

@@ -0,0 +1,114 @@
+/**
+ * GlobalSearchInput Component
+ *
+ * Search input with two actions: Search (navigate to results for query) and
+ * Browse All (navigate to same results UI with all records for the object).
+ */
+import { useState, useCallback, useMemo, useId } from "react";
+import type { KeyboardEvent, ChangeEvent } from "react";
+import { useNavigate } from "react-router";
+import { Card, CardContent } from "../../../../components/ui/__inherit__card";
+import { Input } from "../../../../components/ui/__inherit__input";
+import { Button } from "../../../../components/ui/__inherit__button";
+import { Search } from "lucide-react";
+import { OBJECT_API_NAMES } from "../../constants";
+import { useObjectInfoBatch } from "../../hooks/useObjectInfoBatch";
+
+const BROWSE_SEGMENT = "browse__all";
+
+const FALLBACK_LABEL_PLURAL = "records";
+
+export function GlobalSearchInput() {
+	const [searchQuery, setSearchQuery] = useState("");
+	const navigate = useNavigate();
+	const inputId = useId();
+	const searchButtonId = useId();
+	const browseButtonId = useId();
+	const inputDescriptionId = `${inputId}-description`;
+	const { objectInfos } = useObjectInfoBatch([...OBJECT_API_NAMES]);
+	const labelPlural = (objectInfos[0]?.labelPlural as string | undefined) ?? FALLBACK_LABEL_PLURAL;
+
+	const handleInputChange = useCallback((e: ChangeEvent<HTMLInputElement>) => {
+		setSearchQuery(e.target.value);
+	}, []);
+
+	const handleSearch = useCallback(() => {
+		const trimmed = searchQuery.trim();
+		if (trimmed) {
+			navigate(`/global-search/${encodeURIComponent(trimmed)}`);
+		}
+	}, [searchQuery, navigate]);
+
+	const handleBrowseAll = useCallback(() => {
+		navigate(`/global-search/${BROWSE_SEGMENT}`);
+	}, [navigate]);
+
+	const handleKeyDown = useCallback(
+		(e: KeyboardEvent<HTMLInputElement>) => {
+			if (e.key === "Enter") {
+				e.preventDefault();
+				handleSearch();
+			}
+		},
+		[handleSearch],
+	);
+
+	const isSearchDisabled = useMemo(() => !searchQuery.trim(), [searchQuery]);
+
+	return (
+		<div className="w-full max-w-4xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
+			<Card className="w-full">
+				<CardContent className="pt-6">
+					<div className="flex flex-col sm:flex-row gap-3">
+						<div className="flex-1 relative">
+							<Search
+								className="absolute left-3 top-1/2 transform -translate-y-1/2 h-4 w-4 text-gray-600"
+								aria-hidden="true"
+							/>
+							<Input
+								id={inputId}
+								type="search"
+								placeholder={`Search for ${labelPlural}`}
+								value={searchQuery}
+								onChange={handleInputChange}
+								onKeyDown={handleKeyDown}
+								className="pl-10"
+								aria-label={`Search for ${labelPlural}`}
+								aria-describedby={inputDescriptionId}
+							/>
+							<p id={inputDescriptionId} className="sr-only">
+								Enter your search query and press Enter or click Search. Or click Browse All to see
+								all {labelPlural}.
+							</p>
+						</div>
+
+						<div className="flex flex-col sm:flex-row gap-2 sm:gap-3">
+							<Button
+								id={searchButtonId}
+								onClick={handleSearch}
+								disabled={isSearchDisabled}
+								className="w-full sm:w-auto"
+								aria-label="Search"
+								aria-describedby={inputDescriptionId}
+								variant="default"
+							>
+								<Search className="h-4 w-4 mr-2" aria-hidden="true" />
+								Search
+							</Button>
+							<Button
+								id={browseButtonId}
+								variant="outline"
+								onClick={handleBrowseAll}
+								className="w-full sm:w-auto"
+								aria-label={`Browse all ${labelPlural}`}
+								aria-describedby={inputDescriptionId}
+							>
+								Browse All {labelPlural}
+							</Button>
+						</div>
+					</div>
+				</CardContent>
+			</Card>
+		</div>
+	);
+}

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

@@ -0,0 +1,71 @@
+/**
+ * ResultCardFields Component
+ *
+ * Displays secondary fields (up to 3) for a search result card.
+ * Excludes the primary field and handles nested field values.
+ *
+ * @param record - The search result record data
+ * @param columns - Array of column definitions
+ * @param excludeFieldApiName - Field API name to exclude (usually the primary field)
+ *
+ * @remarks
+ * - Displays up to 3 secondary fields
+ * - Handles nested field paths (e.g., "Owner.Alias")
+ * - Skips fields with null/undefined/empty values
+ * - Responsive layout (vertical on mobile, horizontal on desktop)
+ *
+ * @example
+ * ```tsx
+ * <ResultCardFields
+ *   record={searchResult}
+ *   columns={columns}
+ *   excludeFieldApiName="Name"
+ * />
+ * ```
+ */
+import type { Column, SearchResultRecordData } from "../../types/search/searchResults";
+import { getNestedFieldValue } from "../../utils/fieldUtils";
+
+interface ResultCardFieldsProps {
+	record: SearchResultRecordData;
+	columns: Column[];
+	excludeFieldApiName?: string;
+}
+
+export default function ResultCardFields({
+	record,
+	columns,
+	excludeFieldApiName,
+}: ResultCardFieldsProps) {
+	const secondaryFields = columns.filter(
+		(col) => col && col.fieldApiName && col.fieldApiName !== excludeFieldApiName,
+	);
+
+	return (
+		<dl className="space-y-2" aria-label="Additional record information">
+			{secondaryFields.map((column) => {
+				if (!column || !column.fieldApiName) {
+					return null;
+				}
+
+				const displayValue = getNestedFieldValue(record.fields, column.fieldApiName);
+
+				if (displayValue === null || displayValue === undefined || displayValue === "") {
+					return null;
+				}
+
+				return (
+					<div
+						key={column.fieldApiName}
+						className="flex flex-col sm:flex-row sm:items-center gap-1 sm:gap-2"
+					>
+						<dt className="text-sm font-medium text-muted-foreground min-w-[100px]">
+							{column.label || column.fieldApiName}:
+						</dt>
+						<dd className="text-sm text-foreground">{displayValue}</dd>
+					</div>
+				);
+			})}
+		</dl>
+	);
+}

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

@@ -0,0 +1,31 @@
+/**
+ * SearchHeader Component
+ *
+ * Displays the header for search results or browse-all (same UI).
+ * labelPlural comes from object metadata (e.g. useObjectInfoBatch) so it is not hard-coded.
+ */
+interface SearchHeaderProps {
+	query?: string;
+	isBrowseAll?: boolean;
+	/** Plural label for the primary object (e.g. "Accounts"). From object metadata. */
+	labelPlural?: string;
+}
+
+export default function SearchHeader({
+	query,
+	isBrowseAll,
+	labelPlural = "records",
+}: SearchHeaderProps) {
+	return (
+		<header className="mb-6" aria-label="Search results header">
+			<h1 className="text-3xl font-bold mb-2">
+				{isBrowseAll ? `Browse All ${labelPlural}` : "Search Results"}
+			</h1>
+			{!isBrowseAll && query && (
+				<p className="text-lg" aria-live="polite">
+					Results for: <span className="font-semibold">"{query}"</span>
+				</p>
+			)}
+		</header>
+	);
+}

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

@@ -0,0 +1,144 @@
+/**
+ * SearchPagination Component
+ *
+ * Displays pagination controls for search results.
+ * Previous/Next are disabled using hasPreviousPage/hasNextPage from the API so no request is made when there is no page.
+ *
+ * @remarks
+ * - Layout: page size selector on the left, prev/page/next controls on the right (corners).
+ * - Previous disabled when !hasPreviousPage (cursor stack enables prev when pageIndex > 0).
+ * - Next disabled when !hasNextPage or nextPageToken is null.
+ */
+import { Button } from "../../../../components/ui/__inherit__button";
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../components/ui/__inherit__select";
+import { Label } from "../../../../components/ui/__inherit__label";
+import { PAGE_SIZE_OPTIONS, getValidPageSize, isValidPageSize } from "../../utils/paginationUtils";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+interface SearchPaginationProps {
+	currentPageToken: string;
+	nextPageToken: string | null;
+	previousPageToken: string | null;
+	hasNextPage?: boolean;
+	hasPreviousPage?: boolean;
+	pageSize: number;
+	/** direction: 'prev' | 'next' | 'first'. When 'first' (e.g. page size change), parent typically resets pagination; token may be '' for prev when going to page 0. */
+	onPageChange: (newPageToken: string, direction?: "next" | "prev" | "first") => void;
+	onPageSizeChange: (newPageSize: number) => void;
+}
+
+export default function SearchPagination({
+	currentPageToken,
+	nextPageToken,
+	previousPageToken,
+	hasNextPage = false,
+	hasPreviousPage = false,
+	pageSize,
+	onPageChange,
+	onPageSizeChange,
+}: SearchPaginationProps) {
+	const validPageSize = getValidPageSize(pageSize);
+
+	const currentPageTokenNum = parseInt(currentPageToken, 10) || 0;
+	const currentPage = currentPageTokenNum + 1;
+
+	const canGoPrevious = Boolean(hasPreviousPage);
+	const canGoNext = Boolean(hasNextPage && nextPageToken != null);
+
+	const handlePrevious = () => {
+		if (canGoPrevious) {
+			onPageChange(previousPageToken ?? "", "prev");
+		}
+	};
+
+	const handleNext = () => {
+		if (canGoNext && nextPageToken != null) {
+			onPageChange(nextPageToken, "next");
+		}
+	};
+
+	const handlePageSizeChange = (newPageSize: string) => {
+		const newSize = parseInt(newPageSize, 10);
+		if (!isNaN(newSize) && isValidPageSize(newSize) && newSize !== validPageSize) {
+			onPageSizeChange(newSize);
+			onPageChange("0", "first");
+		}
+	};
+
+	return (
+		<nav
+			className="w-full flex flex-row flex-wrap items-center justify-between gap-4 py-2"
+			aria-label="Search results pagination"
+		>
+			<div
+				className="flex items-center gap-2 shrink-0"
+				role="group"
+				aria-label="Page size selector"
+			>
+				<Label htmlFor="page-size-select" className="text-sm font-normal whitespace-nowrap">
+					Results per page:
+				</Label>
+				<Select value={validPageSize.toString()} onValueChange={handlePageSizeChange}>
+					<SelectTrigger
+						id="page-size-select"
+						className="w-[70px]"
+						aria-label="Select number of results per page"
+					>
+						<SelectValue />
+					</SelectTrigger>
+					<SelectContent>
+						{PAGE_SIZE_OPTIONS.map((option) => (
+							<SelectItem key={option.value} value={option.value}>
+								{option.label}
+							</SelectItem>
+						))}
+					</SelectContent>
+				</Select>
+			</div>
+
+			<div className="flex items-center gap-1 shrink-0" role="group" aria-label="Page navigation">
+				<Button
+					type="button"
+					variant="outline"
+					size="sm"
+					disabled={!canGoPrevious}
+					onClick={handlePrevious}
+					aria-label={
+						canGoPrevious
+							? `Go to previous page (Page ${currentPage - 1})`
+							: "Previous page (disabled)"
+					}
+				>
+					<ChevronLeft className="size-4" aria-hidden />
+					Previous
+				</Button>
+				<span
+					className="min-w-[4rem] text-center text-sm text-muted-foreground px-2"
+					aria-label={`Page ${currentPage}, current page`}
+					aria-current="page"
+				>
+					Page {currentPage}
+				</span>
+				<Button
+					type="button"
+					variant="outline"
+					size="sm"
+					disabled={!canGoNext}
+					onClick={handleNext}
+					aria-label={
+						canGoNext ? `Go to next page (Page ${currentPage + 1})` : "Next page (disabled)"
+					}
+				>
+					Next
+					<ChevronRight className="size-4" aria-hidden />
+				</Button>
+			</div>
+		</nav>
+	);
+}

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

@@ -0,0 +1,138 @@
+/**
+ * SearchResultCard Component
+ *
+ * Displays a single search result as a card with primary and secondary fields.
+ * Clicking the card navigates to the detail page for that record.
+ *
+ * @param record - The search result record data to display
+ * @param columns - Array of column definitions for field display
+ * @param objectApiName - API name of the object (path param in detail URL: /object/:objectApiName/:recordId)
+ *
+ * @remarks
+ * - Automatically identifies the primary field (usually "Name")
+ * - Displays up to 3 secondary fields
+ * - Supports keyboard navigation (Enter/Space to navigate)
+ * - Handles nested field values (e.g., "Owner.Alias")
+ *
+ * @example
+ * ```tsx
+ * <SearchResultCard
+ *   record={searchResult}
+ *   columns={columns}
+ *   objectApiName="Account"
+ * />
+ * ```
+ */
+import React from "react";
+import { useNavigate } from "react-router";
+import { useMemo, useCallback } from "react";
+import {
+	Card,
+	CardContent,
+	CardHeader,
+	CardTitle,
+} from "../../../../components/ui/__inherit__card";
+import type { Column, SearchResultRecordData } from "../../types/search/searchResults";
+import { getNestedFieldValue } from "../../utils/fieldUtils";
+import ResultCardFields from "./ResultCardFields";
+import { OBJECT_API_NAMES } from "../../constants";
+
+interface SearchResultCardProps {
+	record: SearchResultRecordData;
+	columns: Column[];
+	objectApiName?: string;
+}
+
+export default function SearchResultCard({
+	record,
+	columns,
+	objectApiName,
+}: SearchResultCardProps) {
+	const navigate = useNavigate();
+
+	const validColumns = useMemo(
+		() => (columns && Array.isArray(columns) && columns.length > 0 ? columns : []),
+		[columns],
+	);
+	const validRecord =
+		record?.id && record?.fields && typeof record.fields === "object" ? record : null;
+
+	const detailPath = useMemo(
+		() =>
+			validRecord
+				? `/object/${objectApiName?.trim() || OBJECT_API_NAMES[0]}/${validRecord.id}`
+				: "",
+		[validRecord, objectApiName],
+	);
+
+	const handleClick = useCallback(() => {
+		if (validRecord?.id) navigate(detailPath);
+	}, [validRecord?.id, detailPath, navigate]);
+
+	const handleKeyDown = useCallback(
+		(e: React.KeyboardEvent) => {
+			if (e.key === "Enter" || e.key === " ") {
+				e.preventDefault();
+				handleClick();
+			}
+		},
+		[handleClick],
+	);
+
+	const primaryField = useMemo(() => {
+		return (
+			validColumns.find(
+				(col) =>
+					col &&
+					col.fieldApiName &&
+					(col.fieldApiName.toLowerCase() === "name" ||
+						col.fieldApiName.toLowerCase().includes("name")),
+			) ||
+			validColumns[0] ||
+			null
+		);
+	}, [validColumns]);
+
+	const primaryValue = useMemo(() => {
+		return primaryField && primaryField.fieldApiName && validRecord?.fields
+			? getNestedFieldValue(validRecord.fields, primaryField.fieldApiName) || "Untitled"
+			: "Untitled";
+	}, [primaryField, validRecord]);
+
+	const secondaryColumns = useMemo(() => {
+		return validColumns.filter(
+			(col) => col && col.fieldApiName && col.fieldApiName !== primaryField?.fieldApiName,
+		);
+	}, [validColumns, primaryField]);
+
+	if (!validRecord) return null;
+	if (validColumns.length === 0) return null;
+
+	return (
+		<Card
+			className="cursor-pointer hover:shadow-md transition-shadow focus-within:ring-2 focus-within:ring-blue-500 focus-within:ring-offset-2"
+			onClick={handleClick}
+			onKeyDown={handleKeyDown}
+			role="button"
+			tabIndex={0}
+			aria-label={`View details for ${primaryValue}`}
+			aria-describedby={`result-${validRecord.id}-description`}
+		>
+			<CardHeader>
+				<CardTitle className="text-lg" id={`result-${validRecord.id}-title`}>
+					{primaryValue}
+				</CardTitle>
+			</CardHeader>
+			<CardContent>
+				<div id={`result-${validRecord.id}-description`} className="sr-only">
+					Search result: {primaryValue}
+				</div>
+				<ResultCardFields
+					record={validRecord}
+					columns={secondaryColumns}
+					excludeFieldApiName={primaryField?.fieldApiName}
+				/>
+			</CardContent>
+		</Card>
+	);
+}

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

@@ -0,0 +1,197 @@
+/**
+ * SearchResultsPanel Component
+ *
+ * Displays the search results panel with loading, error, and empty states.
+ * Renders a list of SearchResultCard components and pagination controls.
+ *
+ * @param columns - Array of column definitions for displaying result data
+ * @param results - Array of search result records to display
+ * @param columnsLoading - Whether column metadata is currently loading
+ * @param resultsLoading - Whether search results are currently loading
+ * @param columnsError - Error message if column fetch failed
+ * @param resultsError - Error message if results fetch failed
+ * @param currentPageToken - Current pagination token
+ * @param pageSize - Number of results per page
+ * @param onPageChange - Callback when pagination changes; second arg optional: "next" | "prev" | "first" (cursor-stack pagination)
+ * @param onPageSizeChange - Callback when page size changes
+ *
+ * @example
+ * ```tsx
+ * <SearchResultsPanel
+ *   columns={columns}
+ *   results={results}
+ *   columnsLoading={false}
+ *   resultsLoading={false}
+ *   columnsError={null}
+ *   resultsError={null}
+ *   currentPageToken="0"
+ *   pageSize={25}
+ *   onPageChange={(token, direction) => handlePageChange(token, direction)}
+ *   onPageSizeChange={(size) => setPageSize(size)}
+ * />
+ * ```
+ */
+import { useMemo } from "react";
+import { Alert, AlertDescription, AlertTitle } from "../../../../components/ui/__inherit__alert";
+import { Skeleton } from "../../../../components/ui/__inherit__skeleton";
+import { AlertCircle } from "lucide-react";
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../components/ui/__inherit__select";
+import { Label } from "../../../../components/ui/__inherit__label";
+import SearchResultCard from "./SearchResultCard";
+import SearchPagination from "./SearchPagination";
+import type { Column, SearchResultRecord } from "../../types/search/searchResults";
+import { getSafeKey } from "../../utils/recordUtils";
+
+interface SearchResultsPanelProps {
+	/** API name of the object being searched (e.g. for detail page navigation). */
+	objectApiName?: string;
+	columns: Column[];
+	results: SearchResultRecord[];
+	columnsLoading: boolean;
+	resultsLoading: boolean;
+	columnsError: string | null;
+	resultsError: string | null;
+	currentPageToken: string;
+	nextPageToken: string | null;
+	previousPageToken: string | null;
+	hasNextPage?: boolean;
+	hasPreviousPage?: boolean;
+	pageSize: number;
+	sortBy: string;
+	onPageChange: (newPageToken: string, direction?: "next" | "prev" | "first") => void;
+	onPageSizeChange: (newPageSize: number) => void;
+	onSortByChange: (newSortBy: string) => void;
+}
+
+export default function SearchResultsPanel({
+	objectApiName,
+	columns,
+	results,
+	columnsLoading,
+	resultsLoading,
+	columnsError,
+	resultsError,
+	currentPageToken,
+	nextPageToken,
+	previousPageToken,
+	hasNextPage = false,
+	hasPreviousPage = false,
+	pageSize,
+	sortBy,
+	onPageChange,
+	onPageSizeChange,
+	onSortByChange,
+}: SearchResultsPanelProps) {
+	const sortableColumns = useMemo(() => columns.filter(({ sortable }) => sortable), [columns]);
+
+	const validResults = useMemo(
+		() => results.filter((record) => record && record.record && record.record.id),
+		[results],
+	);
+	if (columnsError || resultsError) {
+		return (
+			<Alert variant="destructive" role="alert">
+				<AlertCircle className="h-4 w-4" aria-hidden="true" />
+				<AlertTitle>Error</AlertTitle>
+				<AlertDescription>
+					{columnsError || resultsError || "Failed to load search results"}
+				</AlertDescription>
+			</Alert>
+		);
+	}
+
+	if (resultsLoading || columnsLoading) {
+		return (
+			<div
+				className="space-y-4"
+				role="status"
+				aria-live="polite"
+				aria-label="Loading search results"
+			>
+				<span className="sr-only">Loading search results</span>
+				{[1, 2, 3].map((i) => (
+					<div key={i} className="border rounded-lg p-6" aria-hidden="true">
+						<Skeleton className="h-6 w-3/4 mb-4" />
+						<Skeleton className="h-4 w-full mb-2" />
+						<Skeleton className="h-4 w-2/3" />
+					</div>
+				))}
+			</div>
+		);
+	}
+
+	if (results.length === 0) {
+		return (
+			<div className="text-center py-12" role="status" aria-live="polite">
+				<p className="text-lg mb-2">No results found</p>
+				<p className="text-sm">Try adjusting your search query or filters</p>
+			</div>
+		);
+	}
+
+	return (
+		<>
+			{sortableColumns.length > 0 && (
+				<div
+					className="mb-6 flex items-center gap-2 justify-end"
+					role="group"
+					aria-label="Sort options"
+				>
+					<Label htmlFor="sort-by-select" className="text-sm font-normal whitespace-nowrap">
+						Sort by:
+					</Label>
+					<Select value={sortBy || ""} onValueChange={onSortByChange}>
+						<SelectTrigger
+							id="sort-by-select"
+							className="w-[200px]"
+							aria-label="Sort search results by field"
+						>
+							<SelectValue placeholder="Select field..." />
+						</SelectTrigger>
+						<SelectContent>
+							<SelectItem value="relevance">Relevance</SelectItem>
+							{sortableColumns.map((column) => (
+								<SelectItem key={column.fieldApiName} value={column.fieldApiName}>
+									{column.label}
+								</SelectItem>
+							))}
+						</SelectContent>
+					</Select>
+				</div>
+			)}
+
+			<div className="space-y-4 mb-6" role="list" aria-label="Search results list">
+				{validResults.map((record, index) => {
+					const recordId = record.record.id;
+					const safeKey = getSafeKey(recordId, index);
+					return (
+						<div key={safeKey} role="listitem">
+							<SearchResultCard
+								record={record.record}
+								columns={columns}
+								objectApiName={objectApiName}
+							/>
+						</div>
+					);
+				})}
+			</div>
+
+			<SearchPagination
+				currentPageToken={currentPageToken}
+				nextPageToken={nextPageToken}
+				previousPageToken={previousPageToken}
+				hasNextPage={hasNextPage}
+				hasPreviousPage={hasPreviousPage}
+				pageSize={pageSize}
+				onPageChange={onPageChange}
+				onPageSizeChange={onPageSizeChange}
+			/>
+		</>
+	);
+}