@salesforce/ui-bundle-template-app-react-sample-b2e 1.117.2

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/object-search/components/filters/NumericRangeFilter.tsx

@@ -0,0 +1,163 @@
+import { useEffect, useState } from "react";
+import { Input } from "../../../../components/ui/input";
+
+import { useFilterField } from "../FilterContext";
+import { useDebouncedCallback } from "../../hooks/useDebouncedCallback";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+import type { ActiveFilterValue } from "../../utils/filterUtils";
+
+interface NumericRangeFilterProps extends Omit<React.ComponentProps<"div">, "onChange"> {
+	field: string;
+	label: string;
+	helpText?: string;
+	min?: number;
+	max?: number;
+}
+
+export function NumericRangeFilter({
+	field,
+	label,
+	helpText,
+	min,
+	max,
+	className,
+	...props
+}: NumericRangeFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	return (
+		<NumericRangeFilterInputs
+			field={field}
+			label={label}
+			helpText={helpText}
+			value={value}
+			onChange={onChange}
+			min={min}
+			max={max}
+			className={className}
+			{...props}
+		/>
+	);
+}
+
+interface NumericRangeFilterInputsProps extends Omit<React.ComponentProps<"div">, "onChange"> {
+	field: string;
+	label: string;
+	helpText?: string;
+	value: ActiveFilterValue | undefined;
+	onChange: (value: ActiveFilterValue | undefined) => void;
+	min?: number;
+	max?: number;
+	minInputProps?: React.ComponentProps<typeof Input>;
+	maxInputProps?: React.ComponentProps<typeof Input>;
+}
+
+export function NumericRangeFilterInputs({
+	field,
+	label,
+	helpText,
+	value,
+	onChange,
+	min: boundMin,
+	max: boundMax,
+	className,
+	...props
+}: NumericRangeFilterInputsProps) {
+	const [localMin, setLocalMin] = useState(value?.min ?? "");
+	const [localMax, setLocalMax] = useState(value?.max ?? "");
+
+	const externalMin = value?.min ?? "";
+	const externalMax = value?.max ?? "";
+	useEffect(() => {
+		setLocalMin(externalMin);
+	}, [externalMin]);
+	useEffect(() => {
+		setLocalMax(externalMax);
+	}, [externalMax]);
+
+	const isOutOfBounds = (v: string) => {
+		if (v === "") return false;
+		const n = Number(v);
+		return (boundMin != null && n < boundMin) || (boundMax != null && n > boundMax);
+	};
+	const minOutOfBounds = isOutOfBounds(localMin);
+	const maxOutOfBounds = isOutOfBounds(localMax);
+	const isRangeInverted = localMin !== "" && localMax !== "" && Number(localMin) > Number(localMax);
+	const hasError = minOutOfBounds || maxOutOfBounds || isRangeInverted;
+
+	const debouncedOnChange = useDebouncedCallback((min: string, max: string) => {
+		if (!min && !max) {
+			onChange(undefined);
+			return;
+		}
+		const minNum = min !== "" ? Number(min) : null;
+		const maxNum = max !== "" ? Number(max) : null;
+		if (minNum != null && maxNum != null && minNum > maxNum) return;
+		if (
+			minNum != null &&
+			((boundMin != null && minNum < boundMin) || (boundMax != null && minNum > boundMax))
+		)
+			return;
+		if (
+			maxNum != null &&
+			((boundMin != null && maxNum < boundMin) || (boundMax != null && maxNum > boundMax))
+		)
+			return;
+		onChange({ field, label, type: "numeric" as const, min, max });
+	});
+
+	const boundsLabel =
+		boundMin != null && boundMax != null
+			? `${boundMin}–${boundMax}`
+			: boundMin != null
+				? `${boundMin} or more`
+				: boundMax != null
+					? `${boundMax} or less`
+					: null;
+
+	const errorMessage = isRangeInverted
+		? "Min must not exceed max"
+		: (minOutOfBounds || maxOutOfBounds) && boundsLabel
+			? `Value must be between ${boundsLabel}`
+			: undefined;
+
+	return (
+		<FilterFieldWrapper
+			label={label}
+			helpText={helpText}
+			error={errorMessage}
+			className={className}
+			{...props}
+		>
+			<div className="flex gap-2">
+				<Input
+					type="number"
+					placeholder="Min"
+					value={localMin}
+					min={boundMin}
+					max={boundMax}
+					onChange={(e) => {
+						const v = e.target.value;
+						setLocalMin(v);
+						debouncedOnChange(v, localMax);
+					}}
+					aria-label={`${label} minimum`}
+					aria-invalid={hasError || undefined}
+				/>
+				<Input
+					type="number"
+					placeholder="Max"
+					value={localMax}
+					min={boundMin}
+					max={boundMax}
+					onChange={(e) => {
+						const v = e.target.value;
+						setLocalMax(v);
+						debouncedOnChange(localMin, v);
+					}}
+					aria-label={`${label} maximum`}
+					aria-invalid={hasError || undefined}
+				/>
+			</div>
+		</FilterFieldWrapper>
+	);
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/object-search/components/filters/SearchFilter.tsx

@@ -0,0 +1,50 @@
+import { useEffect, useState } from "react";
+
+import { SearchBar } from "../SearchBar";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+import { useDebouncedCallback } from "../../hooks/useDebouncedCallback";
+
+interface SearchFilterProps extends Omit<React.ComponentProps<"div">, "onChange"> {
+	field: string;
+	label: string;
+	placeholder?: string;
+}
+
+export function SearchFilter({
+	field,
+	label,
+	placeholder,
+	className,
+	...props
+}: SearchFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const [localValue, setLocalValue] = useState(value?.value ?? "");
+
+	const externalValue = value?.value ?? "";
+	useEffect(() => {
+		setLocalValue(externalValue);
+	}, [externalValue]);
+
+	const debouncedOnChange = useDebouncedCallback((v: string) => {
+		if (v) {
+			onChange({ field, label, type: "search", value: v });
+		} else {
+			onChange(undefined);
+		}
+	});
+
+	return (
+		<FilterFieldWrapper label={label} htmlFor={`filter-${field}`} className={className} {...props}>
+			<SearchBar
+				value={localValue}
+				handleChange={(v) => {
+					setLocalValue(v);
+					debouncedOnChange(v);
+				}}
+				placeholder={placeholder}
+				inputProps={{ id: `filter-${field}` }}
+			/>
+		</FilterFieldWrapper>
+	);
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/object-search/components/filters/SelectFilter.tsx

@@ -0,0 +1,97 @@
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../components/ui/select";
+import { cn } from "../../../../lib/utils";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+import type { ActiveFilterValue } from "../../utils/filterUtils";
+
+const ALL_VALUE = "__all__";
+
+interface SelectFilterProps extends Omit<React.ComponentProps<"div">, "onChange"> {
+	field: string;
+	label: string;
+	options: Array<{ value: string; label: string }>;
+	helpText?: string;
+}
+
+export function SelectFilter({
+	field,
+	label,
+	options,
+	helpText,
+	className,
+	...props
+}: SelectFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	return (
+		<FilterFieldWrapper
+			label={label}
+			htmlFor={`filter-${field}`}
+			helpText={helpText}
+			className={className}
+			{...props}
+		>
+			<SelectFilterControl
+				field={field}
+				label={label}
+				options={options}
+				value={value}
+				onChange={onChange}
+			/>
+		</FilterFieldWrapper>
+	);
+}
+
+interface SelectFilterControlProps {
+	field: string;
+	label: string;
+	options: Array<{ value: string; label: string }>;
+	value: ActiveFilterValue | undefined;
+	onChange: (value: ActiveFilterValue | undefined) => void;
+	triggerProps?: React.ComponentProps<typeof SelectTrigger>;
+	contentProps?: React.ComponentProps<typeof SelectContent>;
+}
+
+export function SelectFilterControl({
+	field,
+	label,
+	options,
+	value,
+	onChange,
+	triggerProps,
+	contentProps,
+}: SelectFilterControlProps) {
+	return (
+		<Select
+			value={value?.value ?? ALL_VALUE}
+			onValueChange={(v) => {
+				if (v === ALL_VALUE) {
+					onChange(undefined);
+				} else {
+					onChange({ field, label, type: "picklist", value: v });
+				}
+			}}
+		>
+			<SelectTrigger
+				id={`filter-${field}`}
+				{...triggerProps}
+				className={cn("w-full", triggerProps?.className)}
+			>
+				<SelectValue placeholder={`Select ${label.toLowerCase()}`} />
+			</SelectTrigger>
+			<SelectContent {...contentProps}>
+				<SelectItem value={ALL_VALUE}>All</SelectItem>
+				{options.map((opt) => (
+					<SelectItem key={opt.value} value={opt.value}>
+						{opt.label}
+					</SelectItem>
+				))}
+			</SelectContent>
+		</Select>
+	);
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/object-search/components/filters/TextFilter.tsx

@@ -0,0 +1,91 @@
+import { useEffect, useState } from "react";
+import { Input } from "../../../../components/ui/input";
+import { cn } from "../../../../lib/utils";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+import { useDebouncedCallback } from "../../hooks/useDebouncedCallback";
+import type { ActiveFilterValue } from "../../utils/filterUtils";
+
+interface TextFilterProps extends Omit<React.ComponentProps<"div">, "onChange"> {
+	field: string;
+	label: string;
+	placeholder?: string;
+	helpText?: string;
+}
+
+export function TextFilter({
+	field,
+	label,
+	placeholder,
+	helpText,
+	className,
+	...props
+}: TextFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	return (
+		<FilterFieldWrapper
+			label={label}
+			htmlFor={`filter-${field}`}
+			helpText={helpText}
+			className={className}
+			{...props}
+		>
+			<TextFilterInput
+				field={field}
+				label={label}
+				placeholder={placeholder}
+				value={value}
+				onChange={onChange}
+			/>
+		</FilterFieldWrapper>
+	);
+}
+
+interface TextFilterInputProps extends Omit<
+	React.ComponentProps<typeof Input>,
+	"onChange" | "value"
+> {
+	field: string;
+	label: string;
+	value: ActiveFilterValue | undefined;
+	onChange: (value: ActiveFilterValue | undefined) => void;
+}
+
+export function TextFilterInput({
+	field,
+	label,
+	value,
+	onChange,
+	className,
+	...props
+}: TextFilterInputProps) {
+	const [localValue, setLocalValue] = useState(value?.value ?? "");
+
+	const externalValue = value?.value ?? "";
+	useEffect(() => {
+		setLocalValue(externalValue);
+	}, [externalValue]);
+
+	const debouncedOnChange = useDebouncedCallback((v: string) => {
+		if (v) {
+			onChange({ field, label, type: "text", value: v });
+		} else {
+			onChange(undefined);
+		}
+	});
+
+	return (
+		<Input
+			id={`filter-${field}`}
+			type="text"
+			placeholder={props.placeholder ?? `Filter by ${label.toLowerCase()}...`}
+			value={localValue}
+			onChange={(e) => {
+				setLocalValue(e.target.value);
+				debouncedOnChange(e.target.value);
+			}}
+			className={cn(className)}
+			{...props}
+		/>
+	);
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/object-search/hooks/useAsyncData.ts

@@ -0,0 +1,54 @@
+import { useCallback, useEffect, useState } from "react";
+
+interface UseAsyncDataResult<T> {
+	data: T | null;
+	loading: boolean;
+	error: string | null;
+}
+
+/**
+ * Runs an async fetcher on mount and whenever `deps` change.
+ * Returns the loading/error/data state. Does not cache — every call
+ * to the fetcher hits the source directly.
+ *
+ * A cleanup flag prevents state updates if the component unmounts
+ * or deps change before the fetch completes (avoids React warnings
+ * and stale updates from out-of-order responses).
+ */
+export function useAsyncData<T>(
+	fetcher: () => Promise<T>,
+	deps: React.DependencyList,
+): UseAsyncDataResult<T> {
+	const [data, setData] = useState<T | null>(null);
+	const [loading, setLoading] = useState(true);
+	const [error, setError] = useState<string | null>(null);
+
+	// Re-create the fetcher reference only when deps change.
+	// eslint-disable-next-line react-hooks/exhaustive-deps --- deps are explicitly managed by the caller
+	const memoizedFetcher = useCallback(fetcher, deps);
+
+	useEffect(() => {
+		// Guard against setting state after unmount or dep change.
+		let cancelled = false;
+		setLoading(true);
+		setError(null);
+
+		memoizedFetcher()
+			.then((result) => {
+				if (!cancelled) setData(result);
+			})
+			.catch((err) => {
+				console.error(err);
+				if (!cancelled) setError(err instanceof Error ? err.message : "An error occurred");
+			})
+			.finally(() => {
+				if (!cancelled) setLoading(false);
+			});
+
+		return () => {
+			cancelled = true;
+		};
+	}, [memoizedFetcher]);
+
+	return { data, loading, error };
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/object-search/hooks/useCachedAsyncData.ts

@@ -0,0 +1,184 @@
+import { useCallback, useEffect, useState } from "react";
+
+interface UseAsyncDataResult<T> {
+	data: T | null;
+	loading: boolean;
+	error: string | null;
+}
+
+interface CacheOptions {
+	/** Unique cache key. Used for lookups and invalidation via `clearCacheEntry`. */
+	key: string;
+	/** Time-to-live in ms. Default: 30_000 (30s) */
+	ttl?: number;
+	/** Max entries in the cache. Default: 50. Evicts oldest entry when exceeded. */
+	maxSize?: number;
+}
+
+interface CacheEntry {
+	data: unknown;
+	timestamp: number;
+}
+
+/**
+ * Module-level cache shared across all useCachedAsyncData consumers.
+ * Cleared automatically on page reload since it only lives in memory.
+ * Keys are caller-provided so different hook call-sites get independent entries.
+ */
+const cache = new Map<string, CacheEntry>();
+
+/**
+ * Returns a cached entry if it exists and hasn't exceeded its TTL.
+ * Expired entries are deleted lazily here rather than on a timer,
+ * so there's no background cleanup overhead.
+ */
+function getValidEntry(key: string, ttl: number): CacheEntry | undefined {
+	const entry = cache.get(key);
+	if (!entry) return undefined;
+	if (Date.now() - entry.timestamp > ttl) {
+		cache.delete(key);
+		return undefined;
+	}
+	return entry;
+}
+
+/**
+ * Stores a result in the cache. If the cache is at capacity and the key
+ * is new, the oldest entry (first in Map insertion order — FIFO) is evicted.
+ */
+function setEntry(key: string, data: unknown, maxSize: number): void {
+	if (!cache.has(key) && cache.size >= maxSize) {
+		const firstKey = cache.keys().next().value;
+		if (firstKey !== undefined) cache.delete(firstKey);
+	}
+	cache.set(key, { data, timestamp: Date.now() });
+}
+
+/**
+ * Removes a single cache entry by key. The key must match the
+ * `options.key` passed to `useCachedAsyncData`.
+ *
+ * @example
+ * // Hook:
+ * useCachedAsyncData(() => fetchAccountDetail(id), [id], { key: `account:${id}` });
+ *
+ * // Invalidate after a mutation:
+ * await updateAccount(id, fields);
+ * clearCacheEntry(`account:${id}`);
+ */
+export function clearCacheEntry(key: string): void {
+	cache.delete(key);
+}
+
+/**
+ * Removes all cache entries. Useful for global invalidation scenarios
+ * like user logout or after a bulk operation.
+ *
+ * @example
+ * async function handleLogout() {
+ *   await logout();
+ *   clearCache();
+ *   navigate("/login");
+ * }
+ */
+export function clearCache(): void {
+	cache.clear();
+}
+
+/**
+ * Async data hook with in-memory caching. Works like `useAsyncData` but
+ * avoids redundant network calls when the same data is requested again
+ * (e.g. navigating away from a page and back).
+ *
+ * Cache behaviour:
+ * - **Key**: Provided via `options.key`. Must be unique per logical data source.
+ *   Use the same key with `clearCacheEntry` to invalidate.
+ * - **Hit**: Data is returned synchronously on the initial render —
+ *   `loading` starts as `false`, so there's no flash of a loading state.
+ * - **Miss**: The fetcher runs, and the result is stored for future hits.
+ * - **TTL**: Entries expire after `options.ttl` ms (default 30 s).
+ *   Expiry is checked lazily on read, not on a timer.
+ * - **Max size**: Oldest entries are evicted FIFO when the cache exceeds
+ *   `options.maxSize` (default 50).
+ *
+ * @example
+ * // Cache picklist options for 5 minutes (data rarely changes)
+ * const { data: types } = useCachedAsyncData(fetchDistinctTypes, [], {
+ *   key: "distinctTypes",
+ *   ttl: 300_000,
+ * });
+ *
+ * // Cache search results with default 30 s TTL (back-nav returns instantly)
+ * const { data } = useCachedAsyncData(
+ *   () => searchAccounts({ where, orderBy, first, after }),
+ *   [where, orderBy, first, after],
+ *   { key: `accounts:${JSON.stringify({ where, orderBy, first, after })}` },
+ * );
+ *
+ * // Invalidate a specific entry after a mutation
+ * await updateAccount(id, fields);
+ * clearCacheEntry(`account:${id}`);
+ *
+ * // Or clear everything (e.g. on logout)
+ * clearCache();
+ */
+export function useCachedAsyncData<T>(
+	fetcher: () => Promise<T>,
+	deps: React.DependencyList,
+	options: CacheOptions,
+): UseAsyncDataResult<T> {
+	const ttl = options.ttl ?? 30_000;
+	const maxSize = options.maxSize ?? 50;
+	const cacheKey = options.key;
+
+	// Synchronous cache check during state initialization so a cache hit
+	// never triggers a loading → loaded transition (avoids UI flicker).
+	const cached = getValidEntry(cacheKey, ttl);
+
+	const [data, setData] = useState<T | null>((cached?.data as T) ?? null);
+	const [loading, setLoading] = useState(!cached);
+	const [error, setError] = useState<string | null>(null);
+
+	// eslint-disable-next-line react-hooks/exhaustive-deps --- deps are explicitly managed by the caller
+	const memoizedFetcher = useCallback(fetcher, deps);
+
+	useEffect(() => {
+		// Re-check the cache inside the effect because deps may have changed
+		// since the initial render (e.g. StrictMode double-invoke).
+		const entry = getValidEntry(cacheKey, ttl);
+		if (entry) {
+			setData(entry.data as T);
+			setLoading(false);
+			setError(null);
+			return;
+		}
+
+		// No cache hit — fetch from the network.
+		let cancelled = false;
+		setLoading(true);
+		setError(null);
+
+		memoizedFetcher()
+			.then((result) => {
+				if (!cancelled) {
+					setEntry(cacheKey, result, maxSize);
+					setData(result);
+				}
+			})
+			.catch((err) => {
+				console.error(err);
+				if (!cancelled) setError(err instanceof Error ? err.message : "An error occurred");
+			})
+			.finally(() => {
+				if (!cancelled) setLoading(false);
+			});
+
+		// Cleanup: if deps change or the component unmounts before the fetch
+		// completes, the cancelled flag prevents stale state updates.
+		return () => {
+			cancelled = true;
+		};
+	}, [memoizedFetcher, cacheKey, ttl, maxSize]);
+
+	return { data, loading, error };
+}

package/dist/force-app/main/default/uiBundles/propertymanagementapp/src/features/object-search/hooks/useDebouncedCallback.ts

@@ -0,0 +1,34 @@
+import { useCallback, useEffect, useRef } from "react";
+import { debounce, FILTER_DEBOUNCE_MS } from "../utils/debounce";
+
+/**
+ * Returns a stable debounced wrapper around the provided callback.
+ *
+ * The wrapper always invokes the *latest* version of `fn` (via a ref),
+ * so the debounce timer is never reset when `fn` changes — only when
+ * the caller invokes the returned function again.
+ *
+ * @param fn - The callback to debounce.
+ * @param delay - Debounce delay in ms. Defaults to `FILTER_DEBOUNCE_MS`.
+ */
+export function useDebouncedCallback<T extends (...args: any[]) => void>(
+	fn: T,
+	delay: number = FILTER_DEBOUNCE_MS,
+): (...args: Parameters<T>) => void {
+	const fnRef = useRef(fn);
+	const debouncedRef = useRef<((...args: any[]) => void) | null>(null);
+
+	useEffect(() => {
+		fnRef.current = fn;
+	});
+
+	useEffect(() => {
+		debouncedRef.current = debounce((...args: any[]) => {
+			fnRef.current(...(args as Parameters<T>));
+		}, delay);
+	}, [delay]);
+
+	return useCallback((...args: Parameters<T>) => {
+		debouncedRef.current?.(...args);
+	}, []);
+}