@salesforce/webapp-template-feature-react-global-search-experimental 1.3.3

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

@@ -0,0 +1,208 @@
+import { 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: {},
+});

package/dist/force-app/main/default/webapplications/feature-react-global-search/src/hooks/useObjectSearchData.ts

@@ -0,0 +1,419 @@
+/**
+ * Object Search Data Hooks
+ *
+ * Custom hooks for managing object search data including columns, results, and filters.
+ * Each hook is responsible for a specific aspect of the search functionality.
+ *
+ * @remarks
+ * All hooks coordinate API calls separately from UI components.
+ * This ensures proper separation of concerns and allows for coordinated chained calls per page.
+ */
+
+import { useState, useEffect, useRef, useMemo } from "react";
+import { objectInfoService, type SearchParams } from "../api/objectInfoService";
+import type {
+	Column,
+	SearchResultRecord,
+	SearchResultRecordData,
+} from "../types/search/searchResults";
+import type { Filter, FilterCriteria } from "../types/filters/filters";
+import type { PicklistValue } from "../types/filters/picklist";
+import { createFiltersKey } from "../utils/cacheUtils";
+
+// --- Shared Types ---
+export interface FiltersData {
+	filters: Filter[];
+	picklistValues: Record<string, PicklistValue[]>;
+	loading: boolean;
+	error: string | null;
+}
+
+/**
+ * Hook: useObjectColumns
+ *
+ * Fetches and caches column definitions for a specific object.
+ * Columns are metadata that rarely changes, so they are cached per object.
+ *
+ * @param objectApiName - The API name of the object to fetch columns for
+ * @returns Object containing columns array, loading state, and error state
+ *
+ * @example
+ * ```tsx
+ * const { columns, columnsLoading, columnsError } = useObjectColumns('Account');
+ * ```
+ */
+export function useObjectColumns(objectApiName: string | null) {
+	const [columnsCache, setColumnsCache] = useState<Record<string, Column[]>>({});
+	const [loading, setLoading] = useState<Record<string, boolean>>({});
+	const [error, setError] = useState<Record<string, string | null>>({});
+
+	const columnsCacheRef = useRef(columnsCache);
+	useEffect(() => {
+		columnsCacheRef.current = columnsCache;
+	}, [columnsCache]);
+
+	useEffect(() => {
+		if (!objectApiName) return;
+
+		if (columnsCacheRef.current[objectApiName]) {
+			return;
+		}
+
+		let isCancelled = false;
+		const abortController = new AbortController();
+
+		const fetchColumns = async () => {
+			setLoading((prev) => ({ ...prev, [objectApiName]: true }));
+			setError((prev) => ({ ...prev, [objectApiName]: null }));
+
+			try {
+				const columns = await objectInfoService.getObjectListInfo(
+					objectApiName,
+					"__SearchResult",
+					abortController.signal,
+				);
+
+				if (isCancelled) return;
+
+				setColumnsCache((prev) => ({ ...prev, [objectApiName]: columns }));
+			} catch (err) {
+				if (isCancelled || (err instanceof Error && err.name === "AbortError")) {
+					return;
+				}
+				setError((prev) => ({ ...prev, [objectApiName]: "Failed to load columns" }));
+			} finally {
+				if (!isCancelled) {
+					setLoading((prev) => ({ ...prev, [objectApiName]: false }));
+				}
+			}
+		};
+
+		fetchColumns();
+
+		return () => {
+			isCancelled = true;
+			abortController.abort();
+		};
+	}, [objectApiName]);
+
+	return {
+		columns: objectApiName ? columnsCache[objectApiName] || [] : [],
+		columnsLoading: objectApiName ? loading[objectApiName] || false : false,
+		columnsError: objectApiName ? error[objectApiName] || null : null,
+	};
+}
+
+/**
+ * Hook: useObjectSearchResults
+ *
+ * Fetches search results for a specific object based on the provided query parameters.
+ * Maintains the *latest* result set for the object in state to prevent redundant
+ * network requests when the component re-renders with the same parameters.
+ * Includes debouncing for search queries (but not pagination).
+ *
+ * @param objectApiName - The API name of the object to search
+ * @param searchQuery - The search query string
+ * @param searchPageSize - Number of results per page (default: 50)
+ * @param searchPageToken - Pagination token (default: '0')
+ * @param filters - Array of filter criteria to apply (default: [])
+ * @param sortBy - Sort field and direction (default: 'relevance')
+ * @returns Object containing results array, pagination tokens, loading state, and error state
+ *
+ * @example
+ * ```tsx
+ * const { results, nextPageToken, previousPageToken, currentPageToken, resultsLoading, resultsError } = useObjectSearchResults(
+ *   'Account',
+ *   'test query',
+ *   25,
+ *   '0',
+ *   [{ objectApiName: 'Account', fieldPath: 'Name', operator: 'contains', values: ['test'] }]
+ * );
+ * ```
+ */
+export function useObjectSearchResults(
+	objectApiName: string | null,
+	searchQuery: string,
+	searchPageSize: number = 50,
+	searchPageToken: string = "0",
+	filters: FilterCriteria[] = [],
+	sortBy: string = "relevance",
+) {
+	const [resultsCache, setResultsCache] = useState<
+		Record<
+			string,
+			{
+				results: SearchResultRecord[];
+				query: string;
+				pageToken: string;
+				pageSize: number;
+				filtersKey: string;
+				sortBy: string;
+				nextPageToken: string | null;
+				previousPageToken: string | null;
+				currentPageToken: string;
+			}
+		>
+	>({});
+	const [loading, setLoading] = useState<Record<string, boolean>>({});
+	const [error, setError] = useState<Record<string, string | null>>({});
+
+	const debounceTimeout = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const abortControllerRef = useRef<AbortController | null>(null);
+	const resultsCacheRef = useRef(resultsCache);
+
+	const filtersKey = useMemo(() => {
+		const filtersArray = Array.isArray(filters) ? filters : [];
+		return createFiltersKey(filtersArray);
+	}, [filters]);
+
+	useEffect(() => {
+		resultsCacheRef.current = resultsCache;
+	}, [resultsCache]);
+
+	useEffect(() => {
+		if (!objectApiName || !searchQuery.trim()) {
+			return;
+		}
+
+		let isCancelled = false;
+		const abortController = new AbortController();
+
+		if (abortControllerRef.current) {
+			abortControllerRef.current.abort();
+		}
+		abortControllerRef.current = abortController;
+
+		if (debounceTimeout.current) {
+			clearTimeout(debounceTimeout.current);
+			debounceTimeout.current = null;
+		}
+
+		const cached = resultsCacheRef.current[objectApiName];
+		if (
+			!abortController.signal.aborted &&
+			cached &&
+			cached.query === searchQuery &&
+			cached.pageToken === searchPageToken &&
+			cached.pageSize === searchPageSize &&
+			cached.filtersKey === filtersKey &&
+			cached.sortBy === sortBy
+		) {
+			return;
+		}
+
+		if (abortController.signal.aborted) {
+			return;
+		}
+
+		const fetchResults = async () => {
+			setLoading((prev) => ({ ...prev, [objectApiName]: true }));
+			setError((prev) => ({ ...prev, [objectApiName]: null }));
+
+			try {
+				const searchParams: SearchParams = {
+					sortBy: sortBy === "relevance" ? "" : sortBy,
+					filters: filters,
+					pageSize: searchPageSize,
+					pageToken: searchPageToken,
+				};
+
+				const keywordSearchResult = await objectInfoService.searchResults(
+					searchQuery,
+					objectApiName,
+					searchParams,
+					abortController.signal,
+				);
+
+				if (isCancelled || abortController.signal.aborted) return;
+
+				const normalizedRecords = keywordSearchResult.records.map((r) => ({
+					record: r.record as SearchResultRecordData,
+					highlightInfo: r.highlightInfo,
+					searchInfo: r.searchInfo,
+				}));
+
+				const nextPageToken: string | null = keywordSearchResult.nextPageToken ?? null;
+				const previousPageToken: string | null = keywordSearchResult.previousPageToken ?? null;
+
+				setResultsCache((prev): typeof prev => ({
+					...prev,
+					[objectApiName]: {
+						results: normalizedRecords,
+						query: searchQuery,
+						pageToken: searchPageToken,
+						pageSize: searchPageSize,
+						filtersKey: filtersKey,
+						sortBy,
+						nextPageToken,
+						previousPageToken,
+						currentPageToken: keywordSearchResult.currentPageToken,
+					},
+				}));
+			} catch (err) {
+				if (isCancelled || (err instanceof Error && err.name === "AbortError")) {
+					return;
+				}
+				setError((prev) => ({ ...prev, [objectApiName]: "Unable to load search results" }));
+			} finally {
+				if (!isCancelled) {
+					setLoading((prev) => ({ ...prev, [objectApiName]: false }));
+				}
+			}
+		};
+
+		if (searchPageToken === "0") {
+			debounceTimeout.current = setTimeout(() => {
+				fetchResults();
+			}, 300);
+		} else {
+			fetchResults();
+		}
+
+		return () => {
+			isCancelled = true;
+			abortController.abort();
+			if (debounceTimeout.current) {
+				clearTimeout(debounceTimeout.current);
+				debounceTimeout.current = null;
+			}
+			if (abortControllerRef.current === abortController) {
+				abortControllerRef.current = null;
+			}
+		};
+	}, [objectApiName, searchQuery, searchPageSize, searchPageToken, filtersKey, sortBy]);
+
+	return {
+		results: objectApiName ? resultsCache[objectApiName]?.results || [] : [],
+		nextPageToken: objectApiName ? resultsCache[objectApiName]?.nextPageToken || null : null,
+		previousPageToken: objectApiName
+			? resultsCache[objectApiName]?.previousPageToken || null
+			: null,
+		currentPageToken: objectApiName ? resultsCache[objectApiName]?.currentPageToken || "0" : "0",
+		resultsLoading: objectApiName ? loading[objectApiName] || false : false,
+		resultsError: objectApiName ? error[objectApiName] || null : null,
+	};
+}
+
+/**
+ * Hook: useObjectFilters
+ *
+ * Fetches and caches filter definitions and picklist values for a specific object.
+ * Filters and picklists are fetched in parallel to avoid network waterfalls.
+ *
+ * @param objectApiName - The API name of the object to fetch filters for
+ * @returns Object containing filtersData record keyed by object API name
+ *
+ * @example
+ * ```tsx
+ * const { filtersData } = useObjectFilters('Account');
+ * const filtersInfo = filtersData['Account'];
+ * ```
+ */
+export function useObjectFilters(objectApiName: string | null) {
+	const [filtersCache, setFiltersCache] = useState<Record<string, FiltersData>>({});
+
+	const filtersCacheRef = useRef(filtersCache);
+	const abortControllerRef = useRef<AbortController | null>(null);
+
+	useEffect(() => {
+		filtersCacheRef.current = filtersCache;
+	}, [filtersCache]);
+
+	useEffect(() => {
+		if (!objectApiName) return;
+
+		const cached = filtersCacheRef.current[objectApiName];
+		if (cached && (cached.filters?.length > 0 || cached.loading)) {
+			return;
+		}
+
+		if (abortControllerRef.current) {
+			abortControllerRef.current.abort();
+		}
+
+		let isCancelled = false;
+		const abortController = new AbortController();
+		abortControllerRef.current = abortController;
+
+		const fetchFilters = async () => {
+			setFiltersCache((prev) => ({
+				...prev,
+				[objectApiName]: {
+					filters: prev[objectApiName]?.filters || [],
+					picklistValues: prev[objectApiName]?.picklistValues || {},
+					loading: true,
+					error: null,
+				},
+			}));
+
+			try {
+				const filters = await objectInfoService.getObjectListFilters(
+					objectApiName,
+					abortController.signal,
+				);
+
+				if (isCancelled) return;
+
+				const selectFilters = filters.filter((f) => f.affordance?.toLowerCase() === "select");
+
+				const picklistPromises = selectFilters.map((f) =>
+					objectInfoService
+						.getPicklistValues(objectApiName, f.targetFieldPath, undefined, abortController.signal)
+						.then((values) => ({ fieldPath: f.targetFieldPath, values }))
+						.catch((err) => {
+							if (err instanceof Error && err.name === "AbortError") {
+								throw err;
+							}
+							return { fieldPath: f.targetFieldPath, values: [] };
+						}),
+				);
+
+				const picklistResults = await Promise.all(picklistPromises);
+
+				if (isCancelled) return;
+
+				const picklistValuesRecord: Record<string, PicklistValue[]> = {};
+				picklistResults.forEach(({ fieldPath, values }) => {
+					picklistValuesRecord[fieldPath] = values;
+				});
+
+				setFiltersCache((prev) => ({
+					...prev,
+					[objectApiName]: {
+						filters,
+						picklistValues: picklistValuesRecord,
+						loading: false,
+						error: null,
+					},
+				}));
+			} catch (err) {
+				if (isCancelled || (err instanceof Error && err.name === "AbortError")) {
+					return;
+				}
+				setFiltersCache((prev) => ({
+					...prev,
+					[objectApiName]: {
+						filters: [],
+						picklistValues: {},
+						loading: false,
+						error: "Failed to load filters",
+					},
+				}));
+			}
+		};
+
+		fetchFilters();
+
+		return () => {
+			isCancelled = true;
+			abortController.abort();
+			if (abortControllerRef.current === abortController) {
+				abortControllerRef.current = null;
+			}
+		};
+	}, [objectApiName]);
+
+	return {
+		filtersData: filtersCache,
+	};
+}