@salesforce/ui-bundle-template-feature-react-search 11.3.0

package/dist/force-app/main/default/uiBundles/feature-react-search/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/feature-react-search/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/feature-react-search/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/feature-react-search/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>
+	);
+}

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

@@ -0,0 +1,122 @@
+/**
+ * Default filter panel used when no `renderFilters` is supplied for a source.
+ *
+ * Renders one input per entry in `source.filterFields`, picking the right
+ * component for each `FilterFieldType`:
+ *
+ *   - text                                  → TextFilter
+ *   - picklist                              → SelectFilter (inline options or auto-fetched)
+ *   - multipicklist                         → MultiSelectFilter (inline options or auto-fetched)
+ *   - numeric                               → NumericRangeFilter
+ *   - boolean                               → BooleanFilter
+ *   - date / daterange / datetime / datetimerange → DateRangeFilter
+ *
+ * Applications can still pass `renderFilters[sourceKey]` to override the
+ * entire panel for a specific source.
+ */
+
+import { TextFilter } from "./inputs/TextFilter";
+import { SelectFilter } from "./inputs/SelectFilter";
+import { MultiSelectFilter } from "./inputs/MultiSelectFilter";
+import { NumericRangeFilter } from "./inputs/NumericRangeFilter";
+import { BooleanFilter } from "./inputs/BooleanFilter";
+import { DateRangeFilter } from "./inputs/DateRangeFilter";
+import { useDistinctValues } from "../../hooks/useDistinctValues";
+import type { FilterFieldConfig } from "../../utils/filterUtils";
+import type { SObjectSourceConfig } from "../../types";
+
+interface DefaultFilterPanelProps {
+	source: SObjectSourceConfig;
+}
+
+export function DefaultFilterPanel({ source }: DefaultFilterPanelProps) {
+	const filters = source.filterFields ?? [];
+	if (filters.length === 0) return null;
+	return (
+		<>
+			{filters.map((filter) => (
+				<DefaultFilterField key={filter.field} filter={filter} source={source} />
+			))}
+		</>
+	);
+}
+
+interface DefaultFilterFieldProps {
+	filter: FilterFieldConfig;
+	source: SObjectSourceConfig;
+}
+
+function DefaultFilterField({ filter, source }: DefaultFilterFieldProps) {
+	switch (filter.type) {
+		case "text":
+			return (
+				<TextFilter
+					field={filter.field}
+					label={filter.label}
+					placeholder={filter.placeholder}
+					helpText={filter.helpText}
+				/>
+			);
+		case "picklist":
+			return <PicklistField filter={filter} source={source} multi={false} />;
+		case "multipicklist":
+			return <PicklistField filter={filter} source={source} multi={true} />;
+		case "numeric":
+			return (
+				<NumericRangeFilter field={filter.field} label={filter.label} helpText={filter.helpText} />
+			);
+		case "boolean":
+			return <BooleanFilter field={filter.field} label={filter.label} helpText={filter.helpText} />;
+		case "date":
+		case "daterange":
+			return (
+				<DateRangeFilter
+					field={filter.field}
+					label={filter.label}
+					helpText={filter.helpText}
+					filterType="daterange"
+				/>
+			);
+		case "datetime":
+		case "datetimerange":
+			return (
+				<DateRangeFilter
+					field={filter.field}
+					label={filter.label}
+					helpText={filter.helpText}
+					filterType="datetimerange"
+				/>
+			);
+		default:
+			return null;
+	}
+}
+
+/**
+ * Resolves picklist options from inline config first; falls back to fetching
+ * distinct values from the GraphQL aggregate API on first render.
+ */
+function PicklistField({
+	filter,
+	source,
+	multi,
+}: {
+	filter: FilterFieldConfig;
+	source: SObjectSourceConfig;
+	multi: boolean;
+}) {
+	const inline = filter.options;
+	const fetched = useDistinctValues(
+		inline ? null : { objectName: source.objectName, fieldName: filter.field },
+	);
+	const options = inline ?? fetched ?? [];
+	const Component = multi ? MultiSelectFilter : SelectFilter;
+	return (
+		<Component
+			field={filter.field}
+			label={filter.label}
+			options={options}
+			helpText={filter.helpText}
+		/>
+	);
+}

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

@@ -0,0 +1,70 @@
+import { createContext, useCallback, useContext, type ReactNode } from "react";
+import { Button } from "../../../../components/ui/button";
+import type { ActiveFilterValue } from "../../utils/filterUtils";
+
+interface FilterContextValue {
+	filters: ActiveFilterValue[];
+	onFilterChange: (field: string, value: ActiveFilterValue | undefined) => void;
+	onFilterRemove: (field: string) => void;
+	onReset: () => void;
+}
+
+const FilterContext = createContext<FilterContextValue | null>(null);
+
+interface FilterProviderProps {
+	filters: ActiveFilterValue[];
+	onFilterChange: (field: string, value: ActiveFilterValue | undefined) => void;
+	onFilterRemove: (field: string) => void;
+	onReset: () => void;
+	children: ReactNode;
+}
+
+export function FilterProvider({
+	filters,
+	onFilterChange,
+	onFilterRemove,
+	onReset,
+	children,
+}: FilterProviderProps) {
+	return (
+		<FilterContext.Provider value={{ filters, onFilterChange, onFilterRemove, onReset }}>
+			{children}
+		</FilterContext.Provider>
+	);
+}
+
+function useFilterContext() {
+	const ctx = useContext(FilterContext);
+	if (!ctx) throw new Error("useFilterField must be used within a FilterProvider");
+	return ctx;
+}
+
+export function useFilterField(field: string) {
+	const { filters, onFilterChange, onFilterRemove } = useFilterContext();
+	const value = filters.find((f) => f.field === field);
+	const onChange = useCallback(
+		(next: ActiveFilterValue | undefined) => {
+			if (next) onFilterChange(field, next);
+			else onFilterRemove(field);
+		},
+		[field, onFilterChange, onFilterRemove],
+	);
+	return { value, onChange };
+}
+
+export function useFilterPanel() {
+	const { filters, onReset } = useFilterContext();
+	return { hasActiveFilters: filters.length > 0, resetAll: onReset };
+}
+
+type FilterResetButtonProps = Omit<React.ComponentProps<typeof Button>, "onClick">;
+
+export function FilterResetButton({ children, ...props }: FilterResetButtonProps) {
+	const { hasActiveFilters, resetAll } = useFilterPanel();
+	if (!hasActiveFilters) return null;
+	return (
+		<Button onClick={resetAll} aria-label="Reset filters" variant="destructive" {...props}>
+			{children ?? "Reset"}
+		</Button>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/filters/inputs/BooleanFilter.tsx

@@ -0,0 +1,50 @@
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../../components/ui/select";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+
+const ANY_VALUE = "__any__";
+
+interface BooleanFilterProps {
+	field: string;
+	label: string;
+	trueLabel?: string;
+	falseLabel?: string;
+	helpText?: string;
+}
+
+export function BooleanFilter({
+	field,
+	label,
+	trueLabel = "Yes",
+	falseLabel = "No",
+	helpText,
+}: BooleanFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const id = `filter-${field}`;
+	return (
+		<FilterFieldWrapper label={label} htmlFor={id} helpText={helpText}>
+			<Select
+				value={value?.value ?? ANY_VALUE}
+				onValueChange={(v) => {
+					if (v === ANY_VALUE) onChange(undefined);
+					else onChange({ field, label, type: "boolean", value: v });
+				}}
+			>
+				<SelectTrigger id={id} className="w-full">
+					<SelectValue />
+				</SelectTrigger>
+				<SelectContent>
+					<SelectItem value={ANY_VALUE}>Any</SelectItem>
+					<SelectItem value="true">{trueLabel}</SelectItem>
+					<SelectItem value="false">{falseLabel}</SelectItem>
+				</SelectContent>
+			</Select>
+		</FilterFieldWrapper>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/filters/inputs/DateRangeFilter.tsx

@@ -0,0 +1,50 @@
+import { Input } from "../../../../../components/ui/input";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+import type { FilterFieldType } from "../../../utils/filterUtils";
+
+interface DateRangeFilterProps {
+	field: string;
+	label: string;
+	helpText?: string;
+	/** "daterange" (Date scalar) or "datetimerange" (DateTime scalar). */
+	filterType?: Extract<FilterFieldType, "daterange" | "datetimerange">;
+}
+
+/**
+ * Two `<input type="date">` controls bound to `min` / `max` of the active
+ * filter. Uses the platform-native picker — no popover/calendar dependency.
+ */
+export function DateRangeFilter({
+	field,
+	label,
+	helpText,
+	filterType = "daterange",
+}: DateRangeFilterProps) {
+	const { value, onChange } = useFilterField(field);
+
+	const update = (nextMin: string | undefined, nextMax: string | undefined) => {
+		if (!nextMin && !nextMax) onChange(undefined);
+		else onChange({ field, label, type: filterType, min: nextMin, max: nextMax });
+	};
+
+	return (
+		<FilterFieldWrapper label={label} helpText={helpText}>
+			<div className="flex items-center gap-2">
+				<Input
+					type="date"
+					value={value?.min ?? ""}
+					onChange={(e) => update(e.target.value || undefined, value?.max)}
+					aria-label={`${label} from`}
+				/>
+				<span className="text-sm text-muted-foreground">–</span>
+				<Input
+					type="date"
+					value={value?.max ?? ""}
+					onChange={(e) => update(value?.min, e.target.value || undefined)}
+					aria-label={`${label} to`}
+				/>
+			</div>
+		</FilterFieldWrapper>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/filters/inputs/FilterFieldWrapper.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import { Label } from "../../../../../components/ui/label";
+
+interface FilterFieldWrapperProps {
+	label: string;
+	htmlFor?: string;
+	helpText?: string;
+	className?: string;
+	children: ReactNode;
+}
+
+export function FilterFieldWrapper({
+	label,
+	htmlFor,
+	helpText,
+	className,
+	children,
+}: FilterFieldWrapperProps) {
+	return (
+		<div className={`space-y-1 ${className ?? ""}`}>
+			<Label htmlFor={htmlFor}>{label}</Label>
+			{children}
+			{helpText && <p className="text-xs text-muted-foreground min-h-4">{helpText}</p>}
+		</div>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/filters/inputs/MultiSelectFilter.tsx

@@ -0,0 +1,47 @@
+import { Checkbox } from "../../../../../components/ui/checkbox";
+import { Label } from "../../../../../components/ui/label";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+
+interface MultiSelectFilterProps {
+	field: string;
+	label: string;
+	options: Array<{ value: string; label: string }>;
+	helpText?: string;
+}
+
+export function MultiSelectFilter({ field, label, options, helpText }: MultiSelectFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const selected = new Set(value?.value ? value.value.split(",").filter(Boolean) : []);
+
+	const toggle = (v: string, on: boolean) => {
+		const next = new Set(selected);
+		if (on) next.add(v);
+		else next.delete(v);
+		const joined = Array.from(next).join(",");
+		if (joined === "") onChange(undefined);
+		else onChange({ field, label, type: "multipicklist", value: joined });
+	};
+
+	return (
+		<FilterFieldWrapper label={label} helpText={helpText}>
+			<div className="flex flex-col gap-1">
+				{options.map((opt) => {
+					const id = `filter-${field}-${opt.value}`;
+					return (
+						<div key={opt.value} className="flex items-center gap-2">
+							<Checkbox
+								id={id}
+								checked={selected.has(opt.value)}
+								onCheckedChange={(checked) => toggle(opt.value, checked === true)}
+							/>
+							<Label htmlFor={id} className="text-sm font-normal cursor-pointer">
+								{opt.label}
+							</Label>
+						</div>
+					);
+				})}
+			</div>
+		</FilterFieldWrapper>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/filters/inputs/NumericRangeFilter.tsx

@@ -0,0 +1,78 @@
+import { useEffect, useRef, useState } from "react";
+import { Input } from "../../../../../components/ui/input";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+import { debounce, FILTER_DEBOUNCE_MS } from "../../../utils/debounce";
+
+interface NumericRangeFilterProps {
+	field: string;
+	label: string;
+	helpText?: string;
+	min?: number;
+	max?: number;
+}
+
+export function NumericRangeFilter({ field, label, helpText, min, max }: NumericRangeFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const [draftMin, setDraftMin] = useState(value?.min ?? "");
+	const [draftMax, setDraftMax] = useState(value?.max ?? "");
+
+	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<((nextMin: string, nextMax: string) => void) | undefined>(undefined);
+	useEffect(() => {
+		debouncedRef.current = debounce((nextMin: string, nextMax: string) => {
+			if (!nextMin && !nextMax) onChangeRef.current(undefined);
+			else
+				onChangeRef.current({
+					field,
+					label,
+					type: "numeric",
+					min: nextMin || undefined,
+					max: nextMax || undefined,
+				});
+		}, FILTER_DEBOUNCE_MS);
+	}, [field, label]);
+
+	useEffect(() => {
+		setDraftMin(value?.min ?? "");
+		setDraftMax(value?.max ?? "");
+	}, [value?.min, value?.max]);
+
+	return (
+		<FilterFieldWrapper label={label} helpText={helpText}>
+			<div className="flex items-center gap-2">
+				<Input
+					type="number"
+					placeholder="Min"
+					min={min}
+					max={max}
+					value={draftMin}
+					onChange={(e) => {
+						setDraftMin(e.target.value);
+						debouncedRef.current?.(e.target.value, draftMax);
+					}}
+					aria-label={`${label} minimum`}
+				/>
+				<span className="text-sm text-muted-foreground">–</span>
+				<Input
+					type="number"
+					placeholder="Max"
+					min={min}
+					max={max}
+					value={draftMax}
+					onChange={(e) => {
+						setDraftMax(e.target.value);
+						debouncedRef.current?.(draftMin, e.target.value);
+					}}
+					aria-label={`${label} maximum`}
+				/>
+			</div>
+		</FilterFieldWrapper>
+	);
+}