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

package/dist/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/alert";
+import { Skeleton } from "../../../../components/ui/skeleton";
+import { AlertCircle } from "lucide-react";
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../components/ui/select";
+import { Label } from "../../../../components/ui/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}
+			/>
+		</>
+	);
+}

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

@@ -0,0 +1,61 @@
+/**
+ * LoadingFallback Component
+ *
+ * Loading fallback component for Suspense boundaries.
+ * Displays a centered spinner while lazy-loaded components are being fetched.
+ *
+ * @remarks
+ * - Used with React Suspense for code splitting
+ * - Simple centered spinner design
+ * - Responsive and accessible
+ *
+ * @example
+ * ```tsx
+ * <Suspense fallback={<LoadingFallback />}>
+ *   <LazyComponent />
+ * </Suspense>
+ * ```
+ */
+import { cva, type VariantProps } from "class-variance-authority";
+import { Spinner } from "../../../../components/ui/spinner";
+
+/**
+ * Spinner size variants based on content width.
+ */
+const spinnerVariants = cva("", {
+	variants: {
+		contentMaxWidth: {
+			sm: "size-6",
+			md: "size-8",
+			lg: "size-10",
+		},
+	},
+	defaultVariants: {
+		contentMaxWidth: "sm",
+	},
+});
+
+interface LoadingFallbackProps extends VariantProps<typeof spinnerVariants> {
+	/**
+	 * Maximum width of the content container. Also scales the spinner size.
+	 * @default "sm"
+	 */
+	contentMaxWidth?: "sm" | "md" | "lg";
+	/**
+	 * Accessible label for screen readers.
+	 * @default "Loading…"
+	 */
+	loadingText?: string;
+}
+
+export default function LoadingFallback({
+	contentMaxWidth = "sm",
+	loadingText = "Loading…",
+}: LoadingFallbackProps) {
+	return (
+		<div className="flex justify-center" role="status" aria-live="polite">
+			<Spinner className={spinnerVariants({ contentMaxWidth })} aria-hidden="true" />
+			<span className="sr-only">{loadingText}</span>
+		</div>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-global-search/src/features/global-search/constants.ts

@@ -0,0 +1,39 @@
+/**
+ * Application-wide Constants
+ *
+ * Defines constants used throughout the global search feature.
+ */
+
+/**
+ * Object API names to search across in the global search feature.
+ * Currently supports single object search.
+ *
+ * @remarks
+ * - Array of Salesforce object API names
+ * - First element is used as the primary search object
+ * - Can be extended to support multiple objects in the future
+ *
+ * @example
+ * ```tsx
+ * const objectApiName = OBJECT_API_NAMES[0]; // 'Account'
+ * ```
+ */
+export const OBJECT_API_NAMES = ["Account"] as const;
+
+/** Fallback title when record display name cannot be resolved (e.g. before load or no name field). */
+export const DEFAULT_DETAIL_PAGE_TITLE = "Untitled";
+
+/**
+ * Default page size for search results pagination.
+ * This should match one of the values in PAGE_SIZE_OPTIONS from paginationUtils.
+ *
+ * @remarks
+ * - Default value is 20 (second option in PAGE_SIZE_OPTIONS)
+ * - Can be changed by user via pagination controls
+ *
+ * @example
+ * ```tsx
+ * const [pageSize, setPageSize] = useState(DEFAULT_PAGE_SIZE);
+ * ```
+ */
+export const DEFAULT_PAGE_SIZE = 20;

package/dist/force-app/main/default/uiBundles/feature-react-global-search/src/features/global-search/filters/FilterInput.tsx

@@ -0,0 +1,55 @@
+/**
+ * FilterInput Component
+ *
+ * Renders a text input field for filter values.
+ * Used for filters that don't have a picklist (affordance !== 'select').
+ *
+ * @param filter - Filter definition containing field path, label, and attributes
+ * @param value - Current filter input value
+ * @param onChange - Callback when input value changes
+ *
+ * @remarks
+ * - Displays filter label or field path as the label
+ * - Shows placeholder text from filter attributes or generates default
+ * - Displays help message if available
+ *
+ * @example
+ * ```tsx
+ * <FilterInput
+ *   filter={textFilter}
+ *   value={filterValue}
+ *   onChange={(value) => setFilterValue(value)}
+ * />
+ * ```
+ */
+import { Input } from "../../../components/ui/input";
+import { Field, FieldLabel, FieldDescription } from "../../../components/ui/field";
+import type { Filter } from "../types/filters/filters";
+
+interface FilterInputProps {
+	filter: Filter;
+	value: string;
+	onChange: (value: string) => void;
+}
+
+export default function FilterInput({ filter, value, onChange }: FilterInputProps) {
+	return (
+		<Field>
+			<FieldLabel htmlFor={filter.targetFieldPath}>
+				{filter.label || filter.targetFieldPath}
+			</FieldLabel>
+			<Input
+				id={filter.targetFieldPath}
+				type="text"
+				value={value}
+				onChange={(e: React.ChangeEvent<HTMLInputElement>) => onChange(e.target.value)}
+				placeholder={
+					filter.attributes?.placeholder ||
+					`Enter ${(filter.label || filter.targetFieldPath).toLowerCase()}`
+				}
+				aria-label={filter.label || filter.targetFieldPath}
+			/>
+			{filter.helpMessage && <FieldDescription>{filter.helpMessage}</FieldDescription>}
+		</Field>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-global-search/src/features/global-search/filters/FilterSelect.tsx

@@ -0,0 +1,72 @@
+/**
+ * FilterSelect Component
+ *
+ * Renders a dropdown select field for filter values with picklist options.
+ * Used for filters with affordance === 'select'.
+ *
+ * @param filter - Filter definition containing field path, label, and attributes
+ * @param value - Currently selected filter value
+ * @param options - Array of picklist values to display as options
+ * @param onChange - Callback when selection changes
+ *
+ * @remarks
+ * - Filters out invalid options (null/undefined values)
+ * - Displays option label if available, otherwise uses value
+ * - Shows placeholder from filter attributes or default "Select..."
+ *
+ * @example
+ * ```tsx
+ * <FilterSelect
+ *   filter={selectFilter}
+ *   value={selectedValue}
+ *   options={picklistOptions}
+ *   onChange={(value) => setSelectedValue(value)}
+ * />
+ * ```
+ */
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../components/ui/select";
+import { Field, FieldLabel, FieldDescription } from "../../../components/ui/field";
+import type { Filter } from "../types/filters/filters";
+import type { PicklistValue } from "../types/filters/picklist";
+
+interface FilterSelectProps {
+	filter: Filter;
+	value: string;
+	options: PicklistValue[];
+	onChange: (value: string) => void;
+}
+
+export default function FilterSelect({ filter, value, options, onChange }: FilterSelectProps) {
+	return (
+		<Field>
+			<FieldLabel htmlFor={filter.targetFieldPath}>
+				{filter.label || filter.targetFieldPath}
+			</FieldLabel>
+			<Select value={value} onValueChange={onChange}>
+				<SelectTrigger
+					id={filter.targetFieldPath}
+					aria-label={filter.label || filter.targetFieldPath}
+				>
+					<SelectValue placeholder={filter.attributes?.placeholder || "Select..."} />
+				</SelectTrigger>
+				<SelectContent>
+					{options.map((option) => {
+						if (!option || !option.value) return null;
+						return (
+							<SelectItem key={option.value} value={option.value}>
+								{option.label || option.value}
+							</SelectItem>
+						);
+					})}
+				</SelectContent>
+			</Select>
+			{filter.helpMessage && <FieldDescription>{filter.helpMessage}</FieldDescription>}
+		</Field>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-global-search/src/features/global-search/hooks/form.tsx

@@ -0,0 +1,209 @@
+import React, { useId } from "react";
+import { createFormHookContexts, createFormHook } from "@tanstack/react-form";
+import {
+	Field,
+	FieldDescription,
+	FieldError,
+	FieldLabel,
+} from "../../../components/ui/field";
+import { Input } from "../../../components/ui/input";
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../components/ui/select";
+import { cn } from "../../../lib/utils";
+import type { PicklistValue } from "../types/filters/picklist";
+import { getUniqueErrors } from "../utils/formUtils";
+
+export type { FormError } from "../utils/formUtils";
+export { validateRangeValues } from "../utils/formUtils";
+
+export const { fieldContext, formContext, useFieldContext, useFormContext } =
+	createFormHookContexts();
+
+interface FilterTextFieldProps extends Omit<
+	React.ComponentProps<typeof Input>,
+	"name" | "value" | "onBlur" | "onChange" | "aria-invalid"
+> {
+	label: string;
+	description?: React.ReactNode;
+	placeholder?: string;
+}
+
+function FilterTextField({
+	label,
+	id: providedId,
+	description,
+	placeholder,
+	type = "text",
+	...props
+}: FilterTextFieldProps) {
+	const field = useFieldContext<string>();
+	const generatedId = useId();
+	const id = providedId ?? generatedId;
+	const descriptionId = `${id}-description`;
+	const errorId = `${id}-error`;
+	const isInvalid = field.state.meta.isTouched && field.state.meta.errors.length > 0;
+
+	const uniqueErrors = getUniqueErrors(field.state.meta.errors);
+
+	return (
+		<Field data-invalid={isInvalid}>
+			<FieldLabel htmlFor={id}>{label}</FieldLabel>
+			{description && <FieldDescription id={descriptionId}>{description}</FieldDescription>}
+			<Input
+				id={id}
+				name={field.name as string}
+				type={type}
+				value={field.state.value ?? ""}
+				onBlur={field.handleBlur}
+				onChange={(e: React.ChangeEvent<HTMLInputElement>) => field.handleChange(e.target.value)}
+				placeholder={placeholder}
+				aria-invalid={isInvalid}
+				aria-describedby={cn(description && descriptionId, isInvalid && errorId)}
+				{...props}
+			/>
+			{isInvalid && uniqueErrors.length > 0 && <FieldError errors={uniqueErrors} />}
+		</Field>
+	);
+}
+
+interface FilterSelectFieldProps {
+	label: string;
+	id?: string;
+	description?: React.ReactNode;
+	placeholder?: string;
+	options: PicklistValue[];
+}
+
+function FilterSelectField({
+	label,
+	id: providedId,
+	description,
+	placeholder = "Select...",
+	options,
+}: FilterSelectFieldProps) {
+	const field = useFieldContext<string>();
+	const generatedId = useId();
+	const id = providedId ?? generatedId;
+	const descriptionId = `${id}-description`;
+	const errorId = `${id}-error`;
+	const isInvalid = field.state.meta.isTouched && field.state.meta.errors.length > 0;
+
+	const uniqueErrors = getUniqueErrors(field.state.meta.errors);
+
+	return (
+		<Field data-invalid={isInvalid}>
+			<FieldLabel htmlFor={id}>{label}</FieldLabel>
+			{description && <FieldDescription id={descriptionId}>{description}</FieldDescription>}
+			<Select value={field.state.value ?? ""} onValueChange={(value) => field.handleChange(value)}>
+				<SelectTrigger
+					id={id}
+					aria-invalid={isInvalid}
+					aria-describedby={cn(description && descriptionId, isInvalid && errorId)}
+				>
+					<SelectValue placeholder={placeholder} />
+				</SelectTrigger>
+				<SelectContent>
+					{options.map((option) => {
+						if (!option || !option.value) return null;
+						return (
+							<SelectItem key={option.value} value={option.value}>
+								{option.label || option.value}
+							</SelectItem>
+						);
+					})}
+				</SelectContent>
+			</Select>
+			{isInvalid && uniqueErrors.length > 0 && <FieldError errors={uniqueErrors} />}
+		</Field>
+	);
+}
+
+interface FilterRangeFieldProps extends Omit<
+	React.ComponentProps<typeof Input>,
+	"name" | "value" | "onBlur" | "onChange" | "aria-invalid"
+> {
+	label?: string;
+	description?: React.ReactNode;
+	placeholder?: string;
+}
+
+function FilterRangeFieldBase({
+	label,
+	id: providedId,
+	description,
+	placeholder,
+	type = "text",
+	...props
+}: FilterRangeFieldProps) {
+	const field = useFieldContext<string>();
+	const generatedId = useId();
+	const id = providedId ?? generatedId;
+	const descriptionId = `${id}-description`;
+	const errorId = `${id}-error`;
+	const isInvalid = field.state.meta.isTouched && field.state.meta.errors.length > 0;
+
+	const uniqueErrors = getUniqueErrors(field.state.meta.errors);
+
+	return (
+		<div>
+			{label && <FieldLabel htmlFor={id}>{label}</FieldLabel>}
+			{description && <FieldDescription id={descriptionId}>{description}</FieldDescription>}
+			<Input
+				id={id}
+				name={field.name as string}
+				type={type}
+				value={field.state.value ?? ""}
+				onBlur={field.handleBlur}
+				onChange={(e: React.ChangeEvent<HTMLInputElement>) => field.handleChange(e.target.value)}
+				placeholder={placeholder}
+				aria-invalid={isInvalid}
+				aria-describedby={cn(description && descriptionId, isInvalid && errorId)}
+				{...props}
+			/>
+			{isInvalid && uniqueErrors.length > 0 && <FieldError errors={uniqueErrors} />}
+		</div>
+	);
+}
+
+interface FilterRangeMinFieldProps extends Omit<
+	React.ComponentProps<typeof Input>,
+	"name" | "value" | "onBlur" | "onChange" | "aria-invalid"
+> {
+	label?: string;
+	description?: React.ReactNode;
+	placeholder?: string;
+}
+
+interface FilterRangeMaxFieldProps extends Omit<
+	React.ComponentProps<typeof Input>,
+	"name" | "value" | "onBlur" | "onChange" | "aria-invalid"
+> {
+	label?: string;
+	description?: React.ReactNode;
+	placeholder?: string;
+}
+
+function FilterRangeMinField({ placeholder = "Min", ...props }: FilterRangeMinFieldProps) {
+	return <FilterRangeFieldBase placeholder={placeholder} {...props} />;
+}
+
+function FilterRangeMaxField({ placeholder = "Max", ...props }: FilterRangeMaxFieldProps) {
+	return <FilterRangeFieldBase placeholder={placeholder} {...props} />;
+}
+
+export const { useAppForm } = createFormHook({
+	fieldContext,
+	formContext,
+	fieldComponents: {
+		FilterTextField,
+		FilterSelectField,
+		FilterRangeMinField,
+		FilterRangeMaxField,
+	},
+	formComponents: {},
+});