@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/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/__inherit__select";
+import { Field, FieldLabel, FieldDescription } from "../../../../components/ui/__inherit__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/src/force-app/main/default/uiBundles/feature-react-global-search/src/features/global-search/components/filters/FiltersPanel.tsx

@@ -0,0 +1,380 @@
+/**
+ * FiltersPanel Component
+ *
+ * Displays a panel of filter inputs for refining search results.
+ * Supports both text inputs and select dropdowns based on filter affordance.
+ *
+ * @param filters - Array of filter definitions to display
+ * @param picklistValues - Record of picklist values keyed by field path
+ * @param loading - Whether filters are currently loading
+ * @param onApplyFilters - Callback when filters are applied, receives filter values object
+ *
+ * @remarks
+ * - Automatically initializes filter values from defaultValues
+ * - Shows loading skeleton while filters are being fetched
+ * - Supports "Apply Filters" and "Reset" actions
+ * - Uses TanStack Form for form state management (similar to Login page)
+ * - Uses FiltersForm wrapper for consistent UX/UI (similar to AuthForm pattern)
+ *
+ * @example
+ * ```tsx
+ * <FiltersPanel
+ *   filters={filters}
+ *   picklistValues={picklistValues}
+ *   loading={false}
+ *   onApplyFilters={(values) => applyFilters(values)}
+ * />
+ * ```
+ */
+import { useState, useMemo, useCallback, useEffect, useRef } from "react";
+import {
+	Card,
+	CardContent,
+	CardHeader,
+	CardTitle,
+} from "../../../../components/ui/__inherit__card";
+import { Skeleton } from "../../../../components/ui/__inherit__skeleton";
+import { FiltersForm } from "../forms/filters-form";
+import { Field, FieldLabel, FieldDescription } from "../../../../components/ui/__inherit__field";
+import { useAppForm, validateRangeValues } from "../../hooks/form";
+import type { Filter, FilterCriteria } from "../../types/filters/filters";
+import type { PicklistValue } from "../../types/filters/picklist";
+import { parseFilterValue } from "../../utils/filterUtils";
+import { sanitizeFilterValue } from "../../utils/sanitizationUtils";
+import { getFormValueByPath } from "../../utils/formUtils";
+
+interface FiltersPanelProps {
+	filters: Filter[];
+	picklistValues: Record<string, PicklistValue[]>;
+	loading: boolean;
+	objectApiName: string;
+	onApplyFilters: (filterCriteria: FilterCriteria[]) => void;
+}
+
+export default function FiltersPanel({
+	filters,
+	picklistValues,
+	loading,
+	objectApiName,
+	onApplyFilters,
+}: FiltersPanelProps) {
+	const [submitError, setSubmitError] = useState<string | null>(null);
+	const [submitSuccess, setSubmitSuccess] = useState<string | null>(null);
+
+	const defaultValues = useMemo(() => {
+		if (!filters || !Array.isArray(filters)) {
+			return {};
+		}
+
+		const values: Record<string, string> = {};
+		filters.forEach((filter) => {
+			if (filter && filter.targetFieldPath) {
+				const affordance = filter.affordance?.toLowerCase() || "";
+
+				if (affordance === "range") {
+					const minFieldName = `${filter.targetFieldPath}_min`;
+					const maxFieldName = `${filter.targetFieldPath}_max`;
+
+					if (filter.defaultValues && filter.defaultValues.length >= 2) {
+						values[minFieldName] = filter.defaultValues[0] || "";
+						values[maxFieldName] = filter.defaultValues[1] || "";
+					} else {
+						values[minFieldName] = "";
+						values[maxFieldName] = "";
+					}
+				} else {
+					if (filter.defaultValues && filter.defaultValues.length > 0) {
+						values[filter.targetFieldPath] = filter.defaultValues[0];
+					} else {
+						values[filter.targetFieldPath] = "";
+					}
+				}
+			}
+		});
+		return values;
+	}, [filters]);
+
+	const form = useAppForm({
+		defaultValues,
+		onSubmit: async ({ value }) => {
+			setSubmitError(null);
+			setSubmitSuccess(null);
+			try {
+				const filterCriteria: FilterCriteria[] = [];
+
+				for (const filter of filters) {
+					if (!filter || !filter.targetFieldPath) {
+						continue;
+					}
+
+					const affordance = filter.affordance?.toLowerCase() || "";
+
+					if (affordance === "range") {
+						const minFieldName = `${filter.targetFieldPath}_min`;
+						const maxFieldName = `${filter.targetFieldPath}_max`;
+						const minValueRaw = value[minFieldName] || "";
+						const maxValueRaw = value[maxFieldName] || "";
+
+						const minValue = sanitizeFilterValue(minValueRaw);
+						const maxValue = sanitizeFilterValue(maxValueRaw);
+
+						if (minValue && maxValue) {
+							const rangeError = validateRangeValues(minValue, maxValue);
+							if (rangeError) {
+								setSubmitError(rangeError);
+								return;
+							}
+						}
+
+						if (minValue) {
+							const parsedMin = parseFilterValue(minValue);
+							if (parsedMin !== "") {
+								filterCriteria.push({
+									objectApiName,
+									fieldPath: filter.targetFieldPath,
+									operator: "gte",
+									values: [parsedMin],
+								});
+							}
+						}
+
+						if (maxValue) {
+							const parsedMax = parseFilterValue(maxValue);
+							if (parsedMax !== "") {
+								filterCriteria.push({
+									objectApiName,
+									fieldPath: filter.targetFieldPath,
+									operator: "lte",
+									values: [parsedMax],
+								});
+							}
+						}
+					} else {
+						const fieldValueRaw =
+							getFormValueByPath(value as Record<string, unknown>, filter.targetFieldPath) || "";
+						const fieldValue = sanitizeFilterValue(fieldValueRaw);
+
+						if (fieldValue) {
+							if (affordance === "select") {
+								filterCriteria.push({
+									objectApiName,
+									fieldPath: filter.targetFieldPath,
+									operator: "eq",
+									values: [fieldValue],
+								});
+							} else {
+								const likeValue = `%${fieldValue}%`;
+								filterCriteria.push({
+									objectApiName,
+									fieldPath: filter.targetFieldPath,
+									operator: "like",
+									values: [likeValue],
+								});
+							}
+						}
+					}
+				}
+
+				if (filterCriteria.length === 0) {
+					setSubmitSuccess("No filters applied. Showing all results.");
+				} else {
+					setSubmitSuccess("Filters applied successfully");
+				}
+
+				onApplyFilters(filterCriteria);
+			} catch (err) {
+				const errorMessage = err instanceof Error ? err.message : "Failed to apply filters";
+				setSubmitError(errorMessage);
+			}
+		},
+		onSubmitInvalid: () => {},
+	});
+
+	const previousDefaultValuesRef = useRef<Record<string, string>>({});
+	const previousLoadingRef = useRef<boolean>(true);
+
+	useEffect(() => {
+		const loadingJustCompleted = previousLoadingRef.current && !loading;
+		const defaultValuesChanged =
+			JSON.stringify(previousDefaultValuesRef.current) !== JSON.stringify(defaultValues);
+
+		if (loadingJustCompleted && defaultValues && Object.keys(defaultValues).length > 0) {
+			form.reset(defaultValues);
+			previousDefaultValuesRef.current = defaultValues;
+		} else if (defaultValuesChanged && !loading && Object.keys(defaultValues).length > 0) {
+			form.reset(defaultValues);
+			previousDefaultValuesRef.current = defaultValues;
+		}
+
+		previousLoadingRef.current = loading;
+	}, [loading, defaultValues, form]);
+
+	const handleSuccessDismiss = useCallback(() => {
+		setSubmitSuccess(null);
+	}, []);
+
+	const handleReset = useCallback(() => {
+		if (!filters || !Array.isArray(filters)) {
+			form.reset();
+			onApplyFilters([]);
+			setSubmitError(null);
+			setSubmitSuccess(null);
+			return;
+		}
+
+		const resetValues: Record<string, string> = {};
+		filters.forEach((filter) => {
+			if (filter && filter.targetFieldPath) {
+				const affordance = filter.affordance?.toLowerCase() || "";
+
+				if (affordance === "range") {
+					resetValues[`${filter.targetFieldPath}_min`] = "";
+					resetValues[`${filter.targetFieldPath}_max`] = "";
+				} else {
+					resetValues[filter.targetFieldPath] = "";
+				}
+			}
+		});
+		form.reset(resetValues);
+		onApplyFilters([]);
+		setSubmitError(null);
+		setSubmitSuccess(null);
+	}, [filters, onApplyFilters, form]);
+
+	if (loading) {
+		return (
+			<Card className="w-full" role="region" aria-label="Filters panel">
+				<CardHeader>
+					<CardTitle>Filters</CardTitle>
+				</CardHeader>
+				<CardContent
+					className="space-y-4"
+					role="status"
+					aria-live="polite"
+					aria-label="Loading filters"
+				>
+					<span className="sr-only">Loading filters</span>
+					{[1, 2, 3].map((i) => (
+						<div key={i} className="space-y-2" aria-hidden="true">
+							<Skeleton className="h-4 w-24" />
+							<Skeleton className="h-9 w-full" />
+						</div>
+					))}
+				</CardContent>
+			</Card>
+		);
+	}
+
+	if (!filters || !Array.isArray(filters) || filters.length === 0) {
+		return (
+			<Card className="w-full" role="region" aria-label="Filters panel">
+				<CardHeader>
+					<CardTitle>Filters</CardTitle>
+				</CardHeader>
+				<CardContent>
+					<p className="text-sm text-muted-foreground">No filters available</p>
+				</CardContent>
+			</Card>
+		);
+	}
+
+	return (
+		<form.AppForm>
+			<FiltersForm
+				title="Filters"
+				description="Refine your search results by applying filters"
+				error={submitError}
+				success={submitSuccess}
+				onSuccessDismiss={handleSuccessDismiss}
+				submit={{
+					text: "Apply Filters",
+					loadingText: "Applying filters…",
+				}}
+				reset={{
+					text: "Reset",
+					onReset: handleReset,
+				}}
+			>
+				{filters.map((filter) => {
+					if (!filter || !filter.targetFieldPath) {
+						return null;
+					}
+
+					const fieldPicklistValues = picklistValues[filter.targetFieldPath] || [];
+					const affordance = filter.affordance?.toLowerCase() || "";
+
+					if (affordance === "range") {
+						const minFieldName = `${filter.targetFieldPath}_min`;
+						const maxFieldName = `${filter.targetFieldPath}_max`;
+						const inputType = "text";
+						const placeholder =
+							filter.attributes?.placeholder === "null"
+								? undefined
+								: filter.attributes?.placeholder;
+
+						return (
+							<Field key={filter.targetFieldPath}>
+								<FieldLabel>{filter.label || filter.targetFieldPath}</FieldLabel>
+								{filter.helpMessage && <FieldDescription>{filter.helpMessage}</FieldDescription>}
+								<div
+									className="grid grid-cols-2 gap-3"
+									role="group"
+									aria-label={`${filter.label || filter.targetFieldPath} range filter`}
+								>
+									<form.AppField name={minFieldName}>
+										{(field) => (
+											<field.FilterRangeMinField
+												placeholder={placeholder || "Min"}
+												type={inputType}
+												aria-label={`${filter.label || filter.targetFieldPath} - Minimum`}
+											/>
+										)}
+									</form.AppField>
+									<form.AppField name={maxFieldName}>
+										{(field) => (
+											<field.FilterRangeMaxField
+												placeholder={placeholder || "Max"}
+												type={inputType}
+												aria-label={`${filter.label || filter.targetFieldPath} - Maximum`}
+											/>
+										)}
+									</form.AppField>
+								</div>
+							</Field>
+						);
+					}
+
+					if (affordance === "select") {
+						return (
+							<form.AppField key={filter.targetFieldPath} name={filter.targetFieldPath}>
+								{(field) => (
+									<field.FilterSelectField
+										label={filter.label || filter.targetFieldPath}
+										description={filter.helpMessage || undefined}
+										placeholder={filter.attributes?.placeholder || "Select..."}
+										options={fieldPicklistValues}
+									/>
+								)}
+							</form.AppField>
+						);
+					}
+
+					return (
+						<form.AppField key={filter.targetFieldPath} name={filter.targetFieldPath}>
+							{(field) => (
+								<field.FilterTextField
+									label={filter.label || filter.targetFieldPath}
+									description={filter.helpMessage || undefined}
+									placeholder={
+										filter.attributes?.placeholder ||
+										`Enter ${(filter.label || filter.targetFieldPath).toLowerCase()}`
+									}
+								/>
+							)}
+						</form.AppField>
+					);
+				})}
+			</FiltersForm>
+		</form.AppForm>
+	);
+}

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

@@ -0,0 +1,114 @@
+import { FieldGroup } from "../../../../components/ui/__inherit__field";
+import { StatusAlert } from "../../../../components/alerts/__inherit__status-alert";
+import { CardLayout } from "../../../../components/layouts/__inherit__card-layout";
+import { SubmitButton } from "./submit-button";
+import { Button } from "../../../../components/ui/__inherit__button";
+import { useFormContext } from "../../hooks/form";
+import { useId, useEffect, useRef } from "react";
+
+const SUCCESS_AUTO_DISMISS_DELAY = 3000;
+
+interface FiltersFormProps extends Omit<React.ComponentProps<"form">, "onSubmit"> {
+	title: string;
+	description?: string;
+	error?: React.ReactNode;
+	success?: React.ReactNode;
+	submit: {
+		text: string;
+		loadingText?: string;
+	};
+	reset?: {
+		text: string;
+		onReset: () => void;
+	};
+	onSuccessDismiss?: () => void;
+}
+
+/**
+ * Wrapper component that provides consistent layout and error/success alert positioning
+ * for all filter forms.
+ */
+export function FiltersForm({
+	id: providedId,
+	title,
+	description,
+	error,
+	success,
+	children,
+	submit,
+	reset,
+	onSuccessDismiss,
+	...props
+}: FiltersFormProps) {
+	const form = useFormContext();
+	const generatedId = useId();
+	const id = providedId ?? generatedId;
+
+	const isSubmittingSelector = (state: { isSubmitting: boolean }) => state.isSubmitting;
+	const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	useEffect(() => {
+		if (timeoutRef.current) {
+			clearTimeout(timeoutRef.current);
+			timeoutRef.current = null;
+		}
+
+		if (success && onSuccessDismiss) {
+			timeoutRef.current = setTimeout(() => {
+				onSuccessDismiss();
+				timeoutRef.current = null;
+			}, SUCCESS_AUTO_DISMISS_DELAY);
+		}
+
+		return () => {
+			if (timeoutRef.current) {
+				clearTimeout(timeoutRef.current);
+				timeoutRef.current = null;
+			}
+		};
+	}, [success, onSuccessDismiss]);
+
+	return (
+		<CardLayout title={title} description={description}>
+			<div className="space-y-6">
+				{error && <StatusAlert variant="error">{error}</StatusAlert>}
+				{success && <StatusAlert variant="success">{success}</StatusAlert>}
+
+				<form
+					id={id}
+					onSubmit={(e) => {
+						e.preventDefault();
+						e.stopPropagation();
+						form.handleSubmit();
+					}}
+					{...props}
+				>
+					<FieldGroup>{children}</FieldGroup>
+					<div className="flex flex-col sm:flex-row gap-2 pt-4">
+						<SubmitButton
+							form={id}
+							label={submit.text}
+							loadingLabel={submit.loadingText}
+							className="flex-1"
+						/>
+						{reset && (
+							<form.Subscribe selector={isSubmittingSelector}>
+								{(isSubmitting: boolean) => (
+									<Button
+										type="button"
+										variant="outline"
+										onClick={reset.onReset}
+										className="flex-1"
+										disabled={isSubmitting}
+									>
+										{reset.text}
+									</Button>
+								)}
+							</form.Subscribe>
+						)}
+					</div>
+				</form>
+			</div>
+		</CardLayout>
+	);
+}

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

@@ -0,0 +1,47 @@
+import { Button } from "../../../../components/ui/__inherit__button";
+import { Spinner } from "../../../../components/ui/__inherit__spinner";
+import { cn } from "../../../../lib/__inherit__utils";
+import { useFormContext } from "../../hooks/form";
+
+interface SubmitButtonProps extends Omit<React.ComponentProps<typeof Button>, "type" | "disabled"> {
+	/** Button text when not submitting */
+	label: string;
+	/** Button text while submitting */
+	loadingLabel?: string;
+	/** Form id to associate with (for buttons outside form element) */
+	form?: string;
+}
+
+const isSubmittingSelector = (state: { isSubmitting: boolean }) => state.isSubmitting;
+
+/**
+ * Submit button that subscribes to form submission state.
+ * Disables interaction during submission and provides visual feedback.
+ */
+export function SubmitButton({
+	label,
+	loadingLabel = "Applying…",
+	className,
+	form: formId,
+	...props
+}: SubmitButtonProps) {
+	const form = useFormContext();
+	return (
+		<form.Subscribe selector={isSubmittingSelector}>
+			{(isSubmitting: boolean) => (
+				<Button
+					type="submit"
+					form={formId}
+					className={cn("w-full", className)}
+					disabled={isSubmitting}
+					aria-label={isSubmitting ? loadingLabel : label}
+					aria-busy={isSubmitting}
+					{...props}
+				>
+					{isSubmitting && <Spinner className="mr-2" aria-hidden="true" />}
+					<span aria-live="polite">{isSubmitting ? loadingLabel : label}</span>
+				</Button>
+			)}
+		</form.Subscribe>
+	);
+}