@salesforce/templates 66.3.0 → 66.3.2

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/hooks/useObjectSearchData.ts

@@ -0,0 +1,395 @@
+/**
+ * Object Search Data Hooks
+ *
+ * - useObjectListMetadata: single source for list-view metadata (filters → columns + picklists). Use in list pages to avoid duplicate state and API calls.
+ * - useObjectColumns / useObjectFilters: thin wrappers over useObjectListMetadata for backward compatibility.
+ * - getSharedFilters: module-level deduplication for getObjectListFilters across hook instances.
+ */
+
+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 filters cache (deduplicates getObjectListFilters across useObjectColumns + useObjectFilters) ---
+const sharedFiltersCache = new Map<string, Filter[]>();
+const sharedFiltersInFlight = new Map<string, Promise<Filter[]>>();
+
+/**
+ * Returns filters for the object, deduplicating the API call across hook instances.
+ * Does not pass abort signal to the API so the shared request is not aborted when
+ * one consumer's effect cleans up (e.g. React Strict Mode); callers still guard with isCancelled.
+ */
+function getSharedFilters(objectApiName: string): Promise<Filter[]> {
+	const cached = sharedFiltersCache.get(objectApiName);
+	if (cached) return Promise.resolve(cached);
+	const inFlight = sharedFiltersInFlight.get(objectApiName);
+	if (inFlight) return inFlight;
+	const promise = objectInfoService
+		.getObjectListFilters(objectApiName)
+		.then((filters) => {
+			sharedFiltersCache.set(objectApiName, filters);
+			sharedFiltersInFlight.delete(objectApiName);
+			return filters;
+		})
+		.catch((err) => {
+			sharedFiltersInFlight.delete(objectApiName);
+			throw err;
+		});
+	sharedFiltersInFlight.set(objectApiName, promise);
+	return promise;
+}
+
+// --- Shared Types ---
+export interface FiltersData {
+	filters: Filter[];
+	picklistValues: Record<string, PicklistValue[]>;
+	loading: boolean;
+	error: string | null;
+}
+
+/**
+ * Derives column definitions from filter definitions for list/result UI.
+ */
+function filtersToColumns(filters: Filter[]): Column[] {
+	return filters.map((f) => ({
+		fieldApiName: f.targetFieldPath,
+		label: f.label,
+		searchable: true,
+		sortable: true,
+	}));
+}
+
+export interface ObjectListMetadata {
+	columns: Column[];
+	filters: Filter[];
+	picklistValues: Record<string, PicklistValue[]>;
+	loading: boolean;
+	error: string | null;
+}
+
+/**
+ * Single hook for list-view metadata: filters (shared API), derived columns, and picklist values.
+ * Use this in list/search pages to avoid duplicate useObjectColumns + useObjectFilters and duplicate state.
+ */
+export function useObjectListMetadata(objectApiName: string | null): ObjectListMetadata {
+	const [state, setState] = useState<{
+		columns: Column[];
+		filters: Filter[];
+		picklistValues: Record<string, PicklistValue[]>;
+		loading: boolean;
+		error: string | null;
+	}>({
+		columns: [],
+		filters: [],
+		picklistValues: {},
+		loading: true,
+		error: null,
+	});
+
+	useEffect(() => {
+		if (!objectApiName) {
+			setState((s) => ({ ...s, loading: false, error: "Invalid object" }));
+			return;
+		}
+
+		let isCancelled = false;
+		const ac = new AbortController();
+
+		const run = async () => {
+			setState((s) => ({ ...s, loading: true, error: null }));
+			try {
+				const filters = await getSharedFilters(objectApiName!);
+				if (isCancelled) return;
+
+				const selectFilters = filters.filter((f) => f.affordance?.toLowerCase() === "select");
+				const picklistPromises = selectFilters.map((f) =>
+					objectInfoService
+						.getPicklistValues(objectApiName!, f.targetFieldPath, undefined, ac.signal)
+						.then((values) => ({ fieldPath: f.targetFieldPath, values }))
+						.catch((err) => {
+							if (err?.name === "AbortError") throw err;
+							return { fieldPath: f.targetFieldPath, values: [] as PicklistValue[] };
+						}),
+				);
+				const picklistResults = await Promise.all(picklistPromises);
+				if (isCancelled) return;
+
+				const picklistValues: Record<string, PicklistValue[]> = {};
+				picklistResults.forEach(({ fieldPath, values }) => {
+					picklistValues[fieldPath] = values;
+				});
+
+				setState({
+					columns: filtersToColumns(filters),
+					filters,
+					picklistValues,
+					loading: false,
+					error: null,
+				});
+			} catch (err) {
+				if (isCancelled || (err instanceof Error && err.name === "AbortError")) return;
+				setState((s) => ({
+					...s,
+					columns: [],
+					filters: [],
+					picklistValues: {},
+					loading: false,
+					error: "Failed to load list metadata",
+				}));
+			}
+		};
+
+		run();
+		return () => {
+			isCancelled = true;
+			ac.abort();
+		};
+	}, [objectApiName]);
+
+	return state;
+}
+
+/**
+ * Hook: useObjectColumns
+ * Thin wrapper over useObjectListMetadata for backward compatibility.
+ */
+export function useObjectColumns(objectApiName: string | null) {
+	const { columns, loading, error } = useObjectListMetadata(objectApiName);
+	return {
+		columns: objectApiName ? columns : [],
+		columnsLoading: loading,
+		columnsError: error,
+	};
+}
+
+/**
+ * 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" }));
+				// Cache empty result so we skip refetch on remount (avoid infinite loop on API error)
+				setResultsCache((prev) => ({
+					...prev,
+					[objectApiName]: {
+						results: [],
+						query: searchQuery,
+						pageToken: searchPageToken,
+						pageSize: searchPageSize,
+						filtersKey: filtersKey,
+						sortBy,
+						nextPageToken: null,
+						previousPageToken: null,
+						currentPageToken: searchPageToken,
+					},
+				}));
+			} 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
+ * Thin wrapper over useObjectListMetadata for backward compatibility.
+ */
+export function useObjectFilters(objectApiName: string | null) {
+	const { filters, picklistValues, loading, error } = useObjectListMetadata(objectApiName);
+	const filtersData: Record<string, FiltersData> = objectApiName
+		? {
+				[objectApiName]: {
+					filters,
+					picklistValues,
+					loading,
+					error,
+				},
+			}
+		: {};
+	return { filtersData };
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/hooks/useRecordDetailLayout.ts

@@ -0,0 +1,156 @@
+import { useState, useEffect, useRef } from "react";
+import { objectDetailService } from "../api/objectDetailService";
+import type { LayoutResponse } from "../types/recordDetail/recordDetail";
+import type { ObjectInfoResult } from "../types/objectInfo/objectInfo";
+import type { GraphQLRecordNode } from "../api/recordListGraphQLService";
+
+export interface UseRecordDetailLayoutReturn {
+	layout: LayoutResponse | null;
+	record: GraphQLRecordNode | null;
+	objectMetadata: ObjectInfoResult | null;
+	loading: boolean;
+	error: string | null;
+}
+
+export interface UseRecordDetailLayoutParams {
+	objectApiName: string | null;
+	recordId: string | null;
+	recordTypeId?: string | null;
+	/** When provided, skips the fetch and uses this data (avoids duplicate API calls when parent already fetched). Callers should memoize this (e.g. useMemo) to avoid unnecessary effect runs. */
+	initialData?: {
+		layout: LayoutResponse;
+		record: GraphQLRecordNode;
+		objectMetadata: ObjectInfoResult;
+	} | null;
+}
+
+const MAX_CACHE_SIZE = 50;
+/** Cache entries older than this are treated as stale and refetched. */
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+type CacheEntry = {
+	layout: LayoutResponse;
+	record: GraphQLRecordNode;
+	objectMetadata: ObjectInfoResult;
+	cachedAt: number;
+};
+
+/**
+ * Detail page data: layout (REST), object metadata (GraphQL), single record (GraphQL).
+ *
+ * Calls objectDetailService.getRecordDetail once per objectApiName/recordId/recordTypeId.
+ * Caches result in memory (TTL 5min, max 50 entries). Used by DetailPage and UiApiDetailForm.
+ *
+ * @param objectApiName - Object API name.
+ * @param recordId - Record Id.
+ * @param recordTypeId - Optional record type (default master).
+ * @returns { layout, record, objectMetadata, loading, error }.
+ */
+export function useRecordDetailLayout({
+	objectApiName,
+	recordId,
+	recordTypeId = null,
+	initialData = null,
+}: UseRecordDetailLayoutParams): UseRecordDetailLayoutReturn {
+	const [layout, setLayout] = useState<LayoutResponse | null>(initialData?.layout ?? null);
+	const [record, setRecord] = useState<GraphQLRecordNode | null>(initialData?.record ?? null);
+	const [objectMetadata, setObjectMetadata] = useState<ObjectInfoResult | null>(
+		initialData?.objectMetadata ?? null,
+	);
+	const [loading, setLoading] = useState(!initialData);
+	const [error, setError] = useState<string | null>(null);
+
+	const cacheKey =
+		objectApiName && recordId ? `${objectApiName}:${recordId}:${recordTypeId ?? "default"}` : null;
+	const cacheRef = useRef<Map<string, CacheEntry>>(new Map());
+
+	useEffect(() => {
+		if (!objectApiName || !recordId) {
+			setError("Invalid object or record ID");
+			setLoading(false);
+			return;
+		}
+
+		// Skip fetch when parent already provided data (avoids duplicate API calls)
+		if (
+			initialData?.layout != null &&
+			initialData?.record != null &&
+			initialData?.objectMetadata != null
+		) {
+			return;
+		}
+
+		const cached = cacheRef.current.get(cacheKey!);
+		const now = Date.now();
+		if (cached && now - cached.cachedAt < CACHE_TTL_MS) {
+			setLayout(cached.layout);
+			setRecord(cached.record);
+			setObjectMetadata(cached.objectMetadata);
+			setLoading(false);
+			setError(null);
+			return;
+		}
+
+		let isCancelled = false;
+		const abortController = new AbortController();
+
+		const fetchDetail = async () => {
+			setLoading(true);
+			setError(null);
+
+			try {
+				const {
+					layout: layoutData,
+					record: recordData,
+					objectMetadata: objectMetadataData,
+				} = await objectDetailService.getRecordDetail(
+					objectApiName,
+					recordId,
+					recordTypeId ?? undefined,
+					abortController.signal,
+				);
+
+				if (isCancelled) return;
+
+				const cache = cacheRef.current;
+				if (cache.size >= MAX_CACHE_SIZE) {
+					const firstKey = cache.keys().next().value;
+					if (firstKey != null) cache.delete(firstKey);
+				}
+				cache.set(cacheKey!, {
+					layout: layoutData,
+					record: recordData,
+					objectMetadata: objectMetadataData,
+					cachedAt: Date.now(),
+				});
+				setLayout(layoutData);
+				setRecord(recordData);
+				setObjectMetadata(objectMetadataData);
+			} catch (err) {
+				if (isCancelled || (err instanceof Error && err.name === "AbortError")) {
+					return;
+				}
+				setError("Failed to load record details");
+			} finally {
+				if (!isCancelled) {
+					setLoading(false);
+				}
+			}
+		};
+
+		fetchDetail();
+
+		return () => {
+			isCancelled = true;
+			abortController.abort();
+		};
+	}, [objectApiName, recordId, recordTypeId, cacheKey, initialData]);
+
+	return {
+		layout,
+		record,
+		objectMetadata,
+		loading,
+		error,
+	};
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/hooks/useRecordListGraphQL.ts

@@ -0,0 +1,135 @@
+/**
+ * Record list hook: GraphQL records with filter, sort, pagination, search.
+ * Use for list/search views; detail view uses useRecordDetailLayout instead.
+ *
+ * @module hooks/useRecordListGraphQL
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import { useObjectColumns } from "./useObjectSearchData";
+import {
+	getRecordsGraphQL,
+	buildOrderByFromSort,
+	type RecordListGraphQLResult,
+} from "../api/recordListGraphQLService";
+import type { Column } from "../types/search/searchResults";
+import type { FilterCriteria } from "../types/filters/filters";
+
+const EMPTY_FILTERS: FilterCriteria[] = [];
+
+export interface UseRecordListGraphQLOptions {
+	objectApiName: string;
+	first?: number;
+	after?: string | null;
+	filters?: FilterCriteria[];
+	sortBy?: string;
+	searchQuery?: string;
+	/** When provided, skips useObjectColumns (use from parent e.g. useObjectListMetadata). */
+	columns?: Column[];
+	columnsLoading?: boolean;
+	columnsError?: string | null;
+}
+
+export interface UseRecordListGraphQLReturn {
+	data: RecordListGraphQLResult | null;
+	edges: Array<{ node?: Record<string, unknown> }>;
+	pageInfo: {
+		hasNextPage?: boolean;
+		hasPreviousPage?: boolean;
+		endCursor?: string | null;
+		startCursor?: string | null;
+	} | null;
+	loading: boolean;
+	error: string | null;
+	columnsLoading: boolean;
+	columnsError: string | null;
+	refetch: () => void;
+}
+
+/**
+ * Fetches records via GraphQL for the given object with filter, sort, pagination, and search.
+ */
+export function useRecordListGraphQL(
+	options: UseRecordListGraphQLOptions,
+): UseRecordListGraphQLReturn {
+	const {
+		objectApiName,
+		first = 50,
+		after = null,
+		filters = EMPTY_FILTERS,
+		sortBy = "",
+		searchQuery = "",
+		columns: columnsProp,
+		columnsLoading: columnsLoadingProp,
+		columnsError: columnsErrorProp,
+	} = options;
+
+	const fromParent = columnsProp !== undefined;
+	const fromHook = useObjectColumns(fromParent ? null : objectApiName);
+
+	const columns = fromParent ? columnsProp : fromHook.columns;
+	const columnsLoading = fromParent ? (columnsLoadingProp ?? false) : fromHook.columnsLoading;
+	const columnsError = fromParent ? (columnsErrorProp ?? null) : fromHook.columnsError;
+
+	const [data, setData] = useState<RecordListGraphQLResult | null>(null);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+
+	const fetchRecords = useCallback(() => {
+		if (columnsLoading || columnsError || columns.length === 0) return;
+
+		setLoading(true);
+		setError(null);
+		const orderBy = buildOrderByFromSort(sortBy);
+
+		getRecordsGraphQL({
+			objectApiName,
+			columns,
+			first,
+			after,
+			filters,
+			orderBy,
+			searchQuery: searchQuery.trim() || undefined,
+		})
+			.then((result) => {
+				setData(result);
+			})
+			.catch((err) => {
+				setError(err instanceof Error ? err.message : "Failed to load records");
+			})
+			.finally(() => {
+				setLoading(false);
+			});
+	}, [
+		objectApiName,
+		columns,
+		columnsLoading,
+		columnsError,
+		first,
+		after,
+		filters,
+		sortBy,
+		searchQuery,
+	]);
+
+	useEffect(() => {
+		if (!objectApiName || columnsLoading || columnsError) return;
+		if (columns.length === 0 && !columnsLoading) return;
+		fetchRecords();
+	}, [objectApiName, columns, columnsLoading, columnsError, fetchRecords]);
+
+	const objectData = data?.uiapi?.query?.[objectApiName];
+	const edges = objectData?.edges ?? [];
+	const pageInfo = objectData?.pageInfo ?? null;
+
+	return {
+		data,
+		edges,
+		pageInfo,
+		loading: columnsLoading || loading,
+		error: columnsError || error,
+		columnsLoading,
+		columnsError,
+		refetch: fetchRecords,
+	};
+}