@salesforce/templates 66.5.5 → 66.6.0

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/_os_/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/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/_os_/hooks/useObjectSearchParams.ts

@@ -0,0 +1,247 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useSearchParams } from "react-router";
+import type { FilterFieldConfig, ActiveFilterValue } from "../utils/filterUtils";
+import type { SortFieldConfig, SortState } from "../utils/sortUtils";
+import { filtersToSearchParams, searchParamsToFilters, buildFilter } from "../utils/filterUtils";
+import { buildOrderBy } from "../utils/sortUtils";
+import { debounce } from "../utils/debounce";
+
+/** How long to wait before flushing local state changes to the URL. */
+const URL_SYNC_DEBOUNCE_MS = 300;
+
+export interface PaginationConfig {
+	defaultPageSize: number;
+	validPageSizes: number[];
+}
+
+export interface UseObjectSearchParamsReturn<TFilter, TOrderBy> {
+	filters: {
+		active: ActiveFilterValue[];
+		set: (field: string, value: ActiveFilterValue | undefined) => void;
+		remove: (field: string) => void;
+	};
+	sort: {
+		current: SortState | null;
+		set: (sort: SortState | null) => void;
+	};
+	query: { where: TFilter; orderBy: TOrderBy };
+	pagination: {
+		pageSize: number;
+		pageIndex: number;
+		afterCursor: string | undefined;
+		setPageSize: (size: number) => void;
+		goToNextPage: (cursor: string) => void;
+		goToPreviousPage: () => void;
+	};
+	resetAll: () => void;
+}
+
+/**
+ * Manages filter, sort, and cursor-based pagination state for an object search page.
+ *
+ * ## State model
+ * Local React state is the primary driver for instant UI updates.
+ * URL search params act as the durable source of truth so that a page
+ * refresh or shared link restores the same view. Changes are synced to
+ * the URL via a debounced write (300 ms) to avoid excessive history entries.
+ *
+ * ## Return shape
+ * Returns memoized groups so each group's reference is stable unless its
+ * contents change — safe to pass directly as props to `React.memo` children.
+ *
+ * - `filters`    — active filter values + set/remove callbacks
+ * - `sort`       — current sort state + set callback
+ * - `query`      — derived `where` / `orderBy` objects ready for the API
+ * - `pagination` — page size, page index, cursor, and navigation callbacks
+ * - `resetAll`   — clears all filters, sort, and pagination in one call
+ */
+export function useObjectSearchParams<TFilter, TOrderBy>(
+	filterConfigs: FilterFieldConfig[],
+	_sortConfigs?: SortFieldConfig[],
+	paginationConfig?: PaginationConfig,
+) {
+	const defaultPageSize = paginationConfig?.defaultPageSize ?? 10;
+	const validPageSizes = paginationConfig?.validPageSizes ?? [defaultPageSize];
+	const [searchParams, setSearchParams] = useSearchParams();
+
+	// Seed local state from URL on initial load
+	const initial = useMemo(
+		() => searchParamsToFilters(searchParams, filterConfigs),
+		// Only run on mount — local state takes over after that, no deps needed
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+		[],
+	);
+
+	const [filters, setFilters] = useState<ActiveFilterValue[]>(initial.filters);
+	const [sort, setLocalSort] = useState<SortState | null>(initial.sort);
+
+	// Pagination — cursor-based with a stack to support "previous page" navigation.
+	const getValidPageSize = (size: number) =>
+		validPageSizes.includes(size) ? size : defaultPageSize;
+
+	const [pageSize, setPageSizeState] = useState<number>(
+		getValidPageSize(initial.pageSize ?? defaultPageSize),
+	);
+	const [pageIndex, setPageIndex] = useState(initial.pageIndex);
+	const [afterCursor, setAfterCursor] = useState<string | undefined>(undefined);
+	const cursorStackRef = useRef<string[]>([]);
+
+	// Debounced URL sync — keeps URL in sync without blocking the UI
+	const syncToUrl = useCallback(
+		(
+			nextFilters: ActiveFilterValue[],
+			nextSort: SortState | null,
+			nextPageSize?: number,
+			nextPageIndex?: number,
+		) => {
+			const params = filtersToSearchParams(nextFilters, nextSort, nextPageSize, nextPageIndex);
+			setSearchParams(params, { replace: true });
+		},
+		[setSearchParams],
+	);
+
+	const debouncedSyncRef = useRef(debounce(syncToUrl, URL_SYNC_DEBOUNCE_MS));
+	useEffect(() => {
+		debouncedSyncRef.current = debounce(syncToUrl, URL_SYNC_DEBOUNCE_MS);
+	}, [syncToUrl]);
+
+	// Snapshot ref — lets callbacks read the latest state without being
+	// recreated on every render (avoids infinite useCallback chains).
+	const stateRef = useRef({ filters, sort, pageSize, pageIndex });
+	stateRef.current = { filters, sort, pageSize, pageIndex };
+
+	// Any filter/sort change resets pagination to the first page.
+	const resetPagination = useCallback(() => {
+		setPageIndex(0);
+		setAfterCursor(undefined);
+		cursorStackRef.current = [];
+	}, []);
+
+	// -- Filter callbacks -------------------------------------------------------
+
+	const setFilter = useCallback(
+		(field: string, value: ActiveFilterValue | undefined) => {
+			const { sort: s, pageSize: ps } = stateRef.current;
+			setFilters((prev) => {
+				const next = prev.filter((f) => f.field !== field);
+				if (value) next.push(value);
+				debouncedSyncRef.current(next, s, ps);
+				return next;
+			});
+			resetPagination();
+		},
+		[resetPagination],
+	);
+
+	const removeFilter = useCallback(
+		(field: string) => {
+			const { sort: s, pageSize: ps } = stateRef.current;
+			setFilters((prev) => {
+				const next = prev.filter((f) => f.field !== field);
+				debouncedSyncRef.current(next, s, ps);
+				return next;
+			});
+			resetPagination();
+		},
+		[resetPagination],
+	);
+
+	// -- Sort callback ----------------------------------------------------------
+
+	const setSort = useCallback(
+		(nextSort: SortState | null) => {
+			const { filters: f, pageSize: ps } = stateRef.current;
+			setLocalSort(nextSort);
+			debouncedSyncRef.current(f, nextSort, ps);
+			resetPagination();
+		},
+		[resetPagination],
+	);
+
+	// -- Reset ------------------------------------------------------------------
+
+	const resetAll = useCallback(() => {
+		setFilters([]);
+		setLocalSort(null);
+		resetPagination();
+		syncToUrl([], null, defaultPageSize, 0);
+		setPageSizeState(defaultPageSize);
+	}, [syncToUrl, resetPagination]);
+
+	// -- Pagination callbacks ---------------------------------------------------
+	// Uses a cursor stack to track visited pages. "Next" pushes the current
+	// endCursor onto the stack; "Previous" pops it to restore the prior cursor.
+
+	const goToNextPage = useCallback((endCursor: string) => {
+		cursorStackRef.current = [...cursorStackRef.current, endCursor];
+		setAfterCursor(endCursor);
+		setPageIndex((prev) => {
+			const nextIndex = prev + 1;
+			const { filters: f, sort: s, pageSize: ps } = stateRef.current;
+			debouncedSyncRef.current(f, s, ps, nextIndex);
+			return nextIndex;
+		});
+	}, []);
+
+	const goToPreviousPage = useCallback(() => {
+		const stack = cursorStackRef.current;
+		const next = stack.slice(0, -1);
+		cursorStackRef.current = next;
+		setAfterCursor(next.length > 0 ? next[next.length - 1] : undefined);
+		setPageIndex((prev) => {
+			const nextIndex = Math.max(0, prev - 1);
+			const { filters: f, sort: s, pageSize: ps } = stateRef.current;
+			debouncedSyncRef.current(f, s, ps, nextIndex);
+			return nextIndex;
+		});
+	}, []);
+
+	const setPageSize = useCallback(
+		(newSize: number) => {
+			const validated = getValidPageSize(newSize);
+			const { filters: f, sort: s } = stateRef.current;
+			setPageSizeState(validated);
+			resetPagination();
+			debouncedSyncRef.current(f, s, validated);
+		},
+		[resetPagination],
+	);
+
+	// -- Derived query objects ---------------------------------------------------
+	// Translate local filter/sort state into API-ready `where` and `orderBy`.
+
+	const where = useMemo(
+		() => buildFilter<TFilter>(filters, filterConfigs),
+		[filters, filterConfigs],
+	);
+
+	const orderBy = useMemo(() => buildOrderBy<TOrderBy>(sort), [sort]);
+
+	// -- Memoized return groups -------------------------------------------------
+	// Each group is individually memoized so its object reference stays stable
+	// unless the contained values change. This makes it safe to pass a group
+	// (e.g. `pagination`) directly as props to a React.memo child without
+	// causing unnecessary re-renders.
+
+	const filtersGroup = useMemo(
+		() => ({ active: filters, set: setFilter, remove: removeFilter }),
+		[filters, setFilter, removeFilter],
+	);
+
+	const sortGroup = useMemo(() => ({ current: sort, set: setSort }), [sort, setSort]);
+
+	const query = useMemo(() => ({ where, orderBy }), [where, orderBy]);
+
+	const pagination = useMemo(
+		() => ({ pageSize, pageIndex, afterCursor, setPageSize, goToNextPage, goToPreviousPage }),
+		[pageSize, pageIndex, afterCursor, setPageSize, goToNextPage, goToPreviousPage],
+	);
+
+	return {
+		filters: filtersGroup,
+		sort: sortGroup,
+		query,
+		pagination,
+		resetAll,
+	};
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/_os_/utils/debounce.ts

@@ -0,0 +1,22 @@
+/**
+ * Creates a debounced version of the provided function.
+ *
+ * Each call to the returned function resets the internal timer. The wrapped
+ * function is only invoked once the timer expires without being reset. This
+ * makes it ideal for rate-limiting high-frequency events like input changes.
+ *
+ * @typeParam T - The function signature to debounce.
+ * @param fn - The function to debounce.
+ * @param ms - The debounce delay in milliseconds.
+ * @returns A new function with the same signature that delays execution.
+ */
+export function debounce<T extends (...args: never[]) => void>(
+	fn: T,
+	ms: number,
+): (...args: Parameters<T>) => void {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	return (...args: Parameters<T>) => {
+		clearTimeout(timer);
+		timer = setTimeout(() => fn(...args), ms);
+	};
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/_os_/utils/fieldUtils.ts

@@ -0,0 +1,29 @@
+export function fieldValue(
+	field: { displayValue?: string | null; value?: unknown } | null | undefined,
+): string | null {
+	if (field?.displayValue != null) return field.displayValue;
+	if (field?.value != null) return String(field.value);
+	return null;
+}
+
+export function getAddressFieldLines(address: {
+	street?: string | null;
+	city?: string | null;
+	state?: string | null;
+	postalCode?: string | null;
+	country?: string | null;
+}) {
+	const cityStateZip = [address.city, address.state].filter(Boolean).join(", ");
+	const cityStateZipLine = [cityStateZip, address.postalCode].filter(Boolean).join(" ");
+	const lines = [address.street, cityStateZipLine, address.country].filter(Boolean);
+	if (lines.length === 0) return null;
+	return lines;
+}
+
+export function formatDateTimeField(
+	value?: string | null,
+	...args: Parameters<Date["toLocaleString"]>
+) {
+	if (!value) return null;
+	return new Date(value).toLocaleString(...args);
+}