@salesforce/templates 66.3.1 → 66.3.2

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

@@ -0,0 +1,61 @@
+import { z } from "zod";
+
+/**
+ * Type definitions and Zod schemas for Record Detail APIs:
+ * - Layout API (layout/{objectApiName}?layoutType=Full&mode=View&recordTypeId=...)
+ * - Record API (records/{recordId}?optionalFields=...)
+ */
+
+const LayoutComponentSchema = z.object({
+	apiName: z.string().nullable(),
+	behavior: z.string().optional(),
+	componentType: z.enum(["Field", "CustomLink", "EmptySpace"]),
+	customLinkUrl: z.string().optional(),
+	label: z.string().optional(),
+});
+
+export type LayoutComponent = z.infer<typeof LayoutComponentSchema>;
+
+const LayoutItemSchema = z.object({
+	editableForNew: z.boolean(),
+	editableForUpdate: z.boolean(),
+	label: z.string(),
+	layoutComponents: z.array(LayoutComponentSchema),
+	lookupIdApiName: z.string().nullable(),
+	required: z.boolean(),
+	sortable: z.boolean(),
+	uiBehavior: z.string().nullable(),
+});
+
+export type LayoutItem = z.infer<typeof LayoutItemSchema>;
+
+const LayoutRowSchema = z.object({
+	layoutItems: z.array(LayoutItemSchema),
+});
+
+const LayoutSectionSchema = z.object({
+	collapsible: z.boolean(),
+	columns: z.number(),
+	heading: z.string(),
+	id: z.string(),
+	layoutRows: z.array(LayoutRowSchema),
+	rows: z.number(),
+	tabOrder: z.string(),
+	useHeading: z.boolean(),
+});
+
+export type LayoutSection = z.infer<typeof LayoutSectionSchema>;
+
+export const LayoutResponseSchema = z.object({
+	eTag: z.string(),
+	id: z.string(),
+	layoutType: z.string(),
+	mode: z.string(),
+	objectApiName: z.string(),
+	recordTypeId: z.string(),
+	saveOptions: z.array(z.unknown()).optional(),
+	sections: z.array(LayoutSectionSchema),
+});
+
+export type LayoutResponse = z.infer<typeof LayoutResponseSchema>;
+export type LayoutRow = z.infer<typeof LayoutRowSchema>;

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

@@ -0,0 +1,229 @@
+import { z } from "zod";
+
+/**
+ * Type definitions for search results and column structures.
+ * * ARCHITECTURE NOTE:
+ * We define recursive interfaces MANUALLY first.
+ * If we rely on z.infer<typeof LazySchema> where the schema is z.ZodTypeAny,
+ * TypeScript defaults the type to 'any', destroying type safety.
+ */
+export type ComplexFieldValue = {
+	apiName?: string;
+	childRelationships?: Record<string, unknown>;
+	eTag?: string;
+	fields?: Record<string, FieldValue>; // Recursive reference
+	id?: string;
+	lastModifiedById?: string | null;
+	lastModifiedDate?: string | null;
+	recordTypeId?: string | null;
+	recordTypeInfo?: unknown;
+	systemModstamp?: string | null;
+	weakEtag?: number;
+};
+export type FieldValue = {
+	displayValue: string | null;
+	value: string | number | boolean | null | ComplexFieldValue; // Recursive union
+};
+
+// Zod Schema for Inline Edit Attributes
+export const InlineEditAttributesSchema = z.record(
+	z.string(),
+	z.object({
+		editable: z.boolean(),
+		required: z.boolean(),
+	}),
+);
+
+/**
+ * Inline edit attributes for a field
+ */
+export type InlineEditAttributes = z.infer<typeof InlineEditAttributesSchema>;
+
+// Zod Schema for Column
+export const ColumnSchema = z.object({
+	fieldApiName: z.string(),
+	inlineEditAttributes: InlineEditAttributesSchema.optional(),
+	label: z.string(),
+	lookupId: z.string().nullish(),
+	searchable: z.boolean(),
+	sortable: z.boolean(),
+});
+
+/**
+ * Column definition for list/result UI. Can be derived from Filter[] via targetFieldPath and label
+ * (e.g. filters.map(f => ({ fieldApiName: f.targetFieldPath, label: f.label, searchable: true, sortable: true }))).
+ */
+export type Column = z.infer<typeof ColumnSchema>;
+
+// Export schema for validation
+export const ColumnArraySchema = z.array(ColumnSchema);
+
+// Zod Schema for Complex Field Value (recursive structure)
+// Using z.lazy() to handle circular reference with FieldValueSchema
+// Note: This schema is exported for advanced use cases but should be used carefully
+// due to potential performance implications with deeply nested structures
+export const ComplexFieldValueSchema: z.ZodType<ComplexFieldValue> = z.lazy(() =>
+	z.object({
+		apiName: z.string().optional(),
+		childRelationships: z.record(z.string(), z.unknown()).optional(),
+		eTag: z.string().optional(),
+		fields: z.record(z.string(), FieldValueSchema).optional(),
+		id: z.string().optional(),
+		lastModifiedById: z.string().nullish(),
+		lastModifiedDate: z.string().nullish(),
+		recordTypeId: z.string().nullish(),
+		recordTypeInfo: z.unknown().optional(),
+		systemModstamp: z.string().nullish(),
+		weakEtag: z.number().optional(),
+	}),
+);
+
+// Zod Schema for Field Value (using z.lazy() to handle circular reference)
+// Note: This schema is exported for validating individual field values on-demand
+// Use FieldValueValidationSchema alias for clarity
+// Using z.union([z.string(), z.null()]) instead of .nullish() to match FieldValue type definition
+export const FieldValueSchema: z.ZodType<FieldValue> = z.lazy(() =>
+	z.object({
+		displayValue: z.union([z.string(), z.null()]),
+		value: z.union([
+			z.string(),
+			z.number(),
+			z.boolean(),
+			z.null(),
+			ComplexFieldValueSchema as z.ZodType<ComplexFieldValue>,
+		]),
+	}),
+);
+
+// Zod Schema for Search Result Record Data (lightweight validation)
+// Using z.unknown() for fields to avoid expensive recursive validation of every field value
+// This prevents UI freezing when validating large result sets (e.g., 100 records × 50 fields = 5,000 validations)
+// Individual fields can be validated later when needed using FieldValueSchema
+// Note: z.unknown() is safer than z.any() as it requires explicit type checking before use
+export const SearchResultRecordDataSchema = z.object({
+	apiName: z.string(),
+	childRelationships: z.record(z.string(), z.unknown()),
+	eTag: z.string(),
+	fields: z.record(z.string(), z.unknown()), // Lightweight: avoids recursive validation, uses unknown for type safety
+	id: z.string(),
+	lastModifiedById: z.string().nullish(),
+	lastModifiedDate: z.string().nullish(),
+	recordTypeId: z.string().nullish(),
+	recordTypeInfo: z.unknown().nullish(),
+	systemModstamp: z.string().nullish(),
+	weakEtag: z.number(),
+});
+
+// Full validation schema for individual field values (use when validating specific fields)
+// This can be used to validate a single field value when needed
+export const FieldValueValidationSchema = FieldValueSchema;
+
+// Zod Schema for Highlight Info
+export const HighlightInfoSchema = z.object({
+	fields: z.record(z.string(), z.unknown()),
+	snippet: z.string().nullish(),
+});
+
+// Zod Schema for Search Info
+export const SearchInfoSchema = z.object({
+	isPromoted: z.boolean(),
+	isSpellCorrected: z.boolean(),
+});
+
+// Zod Schema for Search Result Record
+export const SearchResultRecordSchema = z.object({
+	highlightInfo: HighlightInfoSchema,
+	record: SearchResultRecordDataSchema,
+	searchInfo: SearchInfoSchema,
+});
+
+/**
+ * Record structure within search results
+ * Note: The fields property is typed as Record<string, FieldValue> for type safety,
+ * but validation uses z.unknown() for performance (avoids recursive validation of all fields)
+ */
+export type SearchResultRecordData = Omit<
+	z.infer<typeof SearchResultRecordDataSchema>,
+	"fields"
+> & {
+	fields: Record<string, FieldValue>;
+};
+
+/**
+ * Highlight information for search results
+ */
+export type HighlightInfo = z.infer<typeof HighlightInfoSchema>;
+
+/**
+ * Search information for results
+ */
+export type SearchInfo = z.infer<typeof SearchInfoSchema>;
+
+/**
+ * Single record in search results (complete structure from API)
+ * Note: The record.fields property is typed as Record<string, FieldValue> for type safety,
+ * but validation uses z.unknown() for performance (avoids recursive validation of all fields)
+ */
+export type SearchResultRecord = Omit<z.infer<typeof SearchResultRecordSchema>, "record"> & {
+	record: SearchResultRecordData;
+};
+
+// Export schemas for validation
+export const SearchResultRecordArraySchema = z.array(SearchResultRecordSchema);
+
+// Zod Schema for Order By
+export const OrderBySchema = z.object({
+	fieldApiName: z.string(),
+	isAscending: z.boolean(),
+	label: z.string(),
+});
+
+/**
+ * Order by configuration
+ */
+export type OrderBy = z.infer<typeof OrderBySchema>;
+
+// Zod Schema for Keyword Search Result
+export const KeywordSearchResultSchema = z.object({
+	currentPageToken: z.string(),
+	error: z.string().nullish(),
+	nextPageToken: z.string().nullish(),
+	objectApiName: z.string(),
+	orderBy: z.array(OrderBySchema),
+	pageSize: z.number(),
+	previousPageToken: z.string().nullish(),
+	records: z.array(SearchResultRecordSchema),
+	relatedObjectApiNames: z.array(z.string()),
+});
+
+/**
+ * Keyword search result structure
+ */
+export type KeywordSearchResult = z.infer<typeof KeywordSearchResultSchema>;
+
+// Zod Schema for Search Results Response
+export const SearchResultsResponseSchema = z.object({
+	configurationName: z.string().nullish(),
+	keywordSearchResult: KeywordSearchResultSchema,
+	objectApiName: z.string(),
+	query: z.string(),
+	queryId: z.string(),
+});
+
+/**
+ * Search results response structure
+ */
+export type SearchResultsResponse = z.infer<typeof SearchResultsResponseSchema>;
+
+// Zod Schema for Column Info Response
+export const ColumnInfoResponseSchema = z.record(z.string(), z.unknown()).and(
+	z.object({
+		columns: ColumnArraySchema.optional(),
+		fields: ColumnArraySchema.optional(),
+	}),
+);
+
+/**
+ * Column info response structure
+ */
+export type ColumnInfoResponse = z.infer<typeof ColumnInfoResponseSchema>;

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

@@ -0,0 +1,125 @@
+/**
+ * API Utilities
+ *
+ * Generic utility functions for API requests, validation, and URL handling.
+ * These utilities are framework-agnostic and can be reused across different API services.
+ */
+
+import type { ZodSchema } from "zod";
+
+/**
+ * Options for fetchAndValidate utility function
+ */
+export interface FetchAndValidateOptions<T> {
+	/** Zod schema for validation */
+	schema: ZodSchema<T>;
+	/** Error context for better error messages (e.g., "object info batch", "list info") */
+	errorContext: string;
+	/** Optional function to extract/transform data from response before validation */
+	extractData?: (data: unknown) => unknown;
+	/** Optional AbortSignal to cancel the request */
+	signal?: AbortSignal;
+}
+
+/**
+ * Generic utility function to fetch, parse, and validate API responses.
+ * Handles common patterns: fetch -> check status -> parse JSON -> validate Zod -> handle errors
+ *
+ * @param fetchFn - Function that returns a Promise<Response> (e.g., uiApiClient.get or uiApiClient.post)
+ * @param options - Configuration options including schema, error context, optional data extraction, and AbortSignal
+ * @returns Promise resolving to validated data of type T
+ *
+ * @remarks
+ * - Handles abort signals properly to prevent race conditions
+ * - Provides detailed error messages with context
+ * - Validates responses using Zod schemas for type safety
+ * - Supports data extraction/transformation before validation
+ *
+ * @example
+ * ```tsx
+ * const data = await fetchAndValidate(
+ *   (signal) => apiClient.get('/endpoint', { signal }),
+ *   {
+ *     schema: MySchema,
+ *     errorContext: 'user data',
+ *     extractData: (data) => data.items,
+ *     signal: abortController.signal
+ *   }
+ * );
+ * ```
+ */
+export async function fetchAndValidate<T>(
+	fetchFn: (signal?: AbortSignal) => Promise<Response>,
+	options: FetchAndValidateOptions<T>,
+): Promise<T> {
+	const { schema, errorContext, extractData, signal } = options;
+
+	try {
+		const response = await fetchFn(signal);
+
+		if (signal?.aborted) {
+			throw new DOMException("The operation was aborted.", "AbortError");
+		}
+
+		if (!response.ok) {
+			throw new Error(`Failed to fetch ${errorContext}: ${response.status} ${response.statusText}`);
+		}
+
+		const data = await response.json();
+
+		if (signal?.aborted) {
+			throw new DOMException("The operation was aborted.", "AbortError");
+		}
+
+		const dataToValidate = extractData ? extractData(data) : data;
+
+		const validationResult = schema.safeParse(dataToValidate);
+
+		if (!validationResult.success) {
+			throw new Error(`Invalid ${errorContext} response format: ${validationResult.error.message}`);
+		}
+
+		return validationResult.data;
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "AbortError") {
+			throw error;
+		}
+
+		if (error instanceof Error && error.name === "AbortError") {
+			throw error;
+		}
+
+		if (error instanceof Error && error.name === "ZodError") {
+			throw new Error(`Invalid ${errorContext} response format: ${error.message}`);
+		}
+
+		if (
+			error instanceof Error &&
+			(error.message.includes("Failed to fetch") || error.message.includes("Invalid"))
+		) {
+			throw error;
+		}
+
+		throw new Error(
+			`Error fetching ${errorContext}: ${
+				error instanceof Error ? error.message : (error?.toString() ?? "Unknown error")
+			}`,
+		);
+	}
+}
+
+/**
+ * Helper to safely encode path components for URLs
+ * Wraps encodeURIComponent for better semantic meaning
+ *
+ * @param segment - The path segment to encode
+ * @returns URL-encoded path segment
+ *
+ * @example
+ * ```tsx
+ * const safePath = safeEncodePath('Account Name'); // 'Account%20Name'
+ * ```
+ */
+export function safeEncodePath(segment: string): string {
+	return encodeURIComponent(segment);
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Cache Utilities
+ *
+ * Utility functions for creating deterministic cache keys and managing cache operations.
+ */
+
+import type { FilterCriteria } from "../types/filters/filters";
+
+/**
+ * Creates a deterministic cache key from filter criteria array.
+ * Sorts filters and their values to ensure consistent keys regardless of input order.
+ *
+ * @param filters - Array of filter criteria (FilterCriteria[])
+ * @returns Deterministic string key for caching
+ *
+ * @remarks
+ * - Sorts filters by objectApiName, then fieldPath, then operator
+ * - Sorts values within each filter to ensure consistency
+ * - Handles null/undefined values safely
+ * - Prevents cache key collisions from different object ordering
+ *
+ * Why is sorting required?
+ * If a user filters by "Name" then "Date", the array is [Name, Date].
+ * If they filter by "Date" then "Name", the array is [Date, Name].
+ * - Without sorting, these would generate different cache keys ("Name-Date" vs "Date-Name"),
+ * causing the app to re-fetch data it actually already has. Sorting ensures that
+ * the order of user clicks doesn't invalidate the cache.
+ *
+ 
+ * @example
+ * ```tsx
+ * const cacheKey = createFiltersKey(filters);
+ * ```
+ */
+export function createFiltersKey(filters: FilterCriteria[]): string {
+	if (!Array.isArray(filters) || filters.length === 0) {
+		return "[]";
+	}
+
+	const normalized = filters
+		.map((filter) => {
+			if (!filter || typeof filter !== "object") {
+				return null;
+			}
+
+			const f = filter as FilterCriteria;
+
+			const sortedValues =
+				Array.isArray(f.values) && f.values.length > 0
+					? [...f.values].sort((a, b) => {
+							const aStr = a.toString();
+							const bStr = b.toString();
+							return aStr.localeCompare(bStr);
+						})
+					: [];
+
+			return {
+				objectApiName: f.objectApiName ?? "",
+				fieldPath: f.fieldPath ?? "",
+				operator: f.operator ?? "",
+				values: sortedValues,
+			};
+		})
+		.filter((f): f is NonNullable<typeof f> => f !== null)
+		.sort((a, b) => {
+			const objectCompare = a.objectApiName.localeCompare(b.objectApiName);
+			if (objectCompare !== 0) return objectCompare;
+
+			const fieldCompare = a.fieldPath.localeCompare(b.fieldPath);
+			if (fieldCompare !== 0) return fieldCompare;
+
+			return a.operator.localeCompare(b.operator);
+		});
+
+	return JSON.stringify(normalized);
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Debounce Utility
+ *
+ * Provides debouncing functionality for functions with React-safe cleanup methods.
+ */
+
+/**
+ * Interface for the debounced function, exposing utility methods.
+ */
+export interface DebouncedFunc<T extends (...args: any[]) => any> {
+	/**
+	 * Call the original function, but delayed.
+	 */
+	(...args: Parameters<T>): void;
+	/**
+	 * Cancel any pending execution.
+	 */
+	cancel: () => void;
+	/**
+	 * Immediately execute the pending function (if any) and clear the timer.
+	 * Useful for saving data before unmounting.
+	 */
+	flush: () => void;
+}
+
+/**
+ * Creates a debounced function that delays invoking func until after wait milliseconds
+ * have elapsed since the last time the debounced function was invoked.
+ *
+ * @param func - The function to debounce
+ * @param wait - The number of milliseconds to delay
+ * @returns A debounced function with .cancel() and .flush() methods
+ *
+ * @remarks
+ * - Includes .cancel() method for cleanup in React useEffects
+ * - Includes .flush() method to immediately execute pending calls
+ * - Preserves function context (this binding)
+ * - Type-safe with TypeScript generics
+ *
+ * @example
+ * ```tsx
+ * const debouncedSearch = debounce((query: string) => {
+ *   performSearch(query);
+ * }, 300);
+ *
+ * // In useEffect cleanup
+ * return () => debouncedSearch.cancel();
+ * ```
+ */
+export function debounce<T extends (...args: any[]) => any>(
+	func: T,
+	wait: number,
+): DebouncedFunc<T> {
+	// 1. Type Safety: Use a generic return type compatible with Browser and Node
+	let timeoutId: ReturnType<typeof setTimeout> | null = null;
+	let lastContext: ThisParameterType<T> | null = null;
+	let lastArgs: Parameters<T> | null = null;
+	function debounced(this: ThisParameterType<T>, ...args: Parameters<T>) {
+		// 2. Context Safety: Capture 'this' to support class methods
+		lastContext = this;
+		lastArgs = args;
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+		}
+		timeoutId = setTimeout(() => {
+			func.apply(lastContext, lastArgs as Parameters<T>);
+			timeoutId = null;
+			lastArgs = null;
+			lastContext = null;
+		}, wait);
+	}
+	// 3. React Safety: Add a cancel method to clear pending timers
+	debounced.cancel = () => {
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		lastArgs = null;
+		lastContext = null;
+	};
+
+	debounced.flush = () => {
+		if (timeoutId && lastArgs) {
+			func.apply(lastContext, lastArgs);
+			debounced.cancel();
+		}
+	};
+	return debounced;
+}