@salesforce/webapp-template-feature-react-global-search-experimental 1.3.3

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

package/dist/force-app/main/default/webapplications/feature-react-global-search/src/utils/fieldUtils.ts

@@ -0,0 +1,186 @@
+/**
+ * Field Utilities
+ *
+ * Utility functions for extracting and working with field values from Salesforce record structures.
+ * Handles both simple fields and complex nested field paths (e.g., "Owner.Alias").
+ *
+ * @remarks
+ * These utilities handle the complex nested structure of Salesforce API responses,
+ * where fields can contain simple values, complex objects with nested fields, or display values.
+ */
+
+import type { FieldValue, ComplexFieldValue } from "../types/search/searchResults";
+
+/**
+ * List of field names to check when extracting display values from complex objects.
+ * Used when a field value is a complex object (like Owner) and we need to find a displayable field.
+ */
+const DISPLAY_FIELD_CANDIDATES = [
+	"Name",
+	"CaseNumber",
+	"Subject",
+	"Title",
+	"DeveloperName",
+	"ContractNumber",
+] as const;
+
+function isDefined(val: unknown): val is string | number | boolean {
+	return val !== null && val !== undefined;
+}
+
+function isComplexValue(val: unknown): val is ComplexFieldValue {
+	return typeof val === "object" && val !== null && "fields" in val;
+}
+
+function extractComplexValue(complex: ComplexFieldValue): string | null {
+	const fields = complex.fields;
+	if (!fields) return null;
+
+	for (const fieldName of DISPLAY_FIELD_CANDIDATES) {
+		const field = fields[fieldName];
+		if (field) {
+			if (isDefined(field.displayValue)) {
+				return field.displayValue;
+			}
+			if (isDefined(field.value)) {
+				return field.value.toString();
+			}
+		}
+	}
+
+	return null;
+}
+
+function extractFieldPrimitive(field: FieldValue): string | number | boolean | null {
+	if (isDefined(field.displayValue)) {
+		return field.displayValue;
+	}
+
+	if (isComplexValue(field.value)) {
+		const extracted = extractComplexValue(field.value);
+		return extracted !== null ? extracted : null;
+	}
+
+	if (isDefined(field.value)) {
+		return field.value;
+	}
+
+	return null;
+}
+
+/**
+ * Gets a field value from a nested object structure using a field path.
+ * Handles both simple fields (e.g., "Name") and nested fields (e.g., "Owner.Alias").
+ *
+ * @param fields - The fields object from the record
+ * @param fieldPath - The field path (e.g., "Name" or "Owner.Alias")
+ * @returns The displayValue or value, or null if not found
+ *
+ * @remarks
+ * - For simple fields: Returns displayValue if available, otherwise value
+ * - For nested fields: Navigates through the path and extracts the final field value
+ * - For complex objects: Uses DISPLAY_FIELD_CANDIDATES to find a displayable field
+ * - Returns null for missing fields or invalid paths
+ *
+ * @example
+ * ```tsx
+ * // Simple field
+ * const name = getNestedFieldValue(record.fields, 'Name');
+ *
+ * // Nested field
+ * const ownerAlias = getNestedFieldValue(record.fields, 'Owner.Alias');
+ *
+ * // Complex object (automatically extracts Name field)
+ * const ownerName = getNestedFieldValue(record.fields, 'Owner');
+ * ```
+ */
+export function getNestedFieldValue(
+	fields: Record<string, FieldValue> | undefined,
+	fieldPath: string,
+): string | number | boolean | null {
+	if (!fields || !fieldPath) {
+		return null;
+	}
+
+	// Split the path by "." to handle nested fields
+	const pathParts = fieldPath.split(".");
+
+	// If it's a simple field (no dots), handle it directly
+	if (pathParts.length === 1) {
+		const field = fields[fieldPath];
+		if (!field) return null;
+
+		return extractFieldPrimitive(field);
+	}
+
+	// Handle nested fields (e.g., "Owner.Alias")
+	let currentFields: Record<string, FieldValue> | undefined = fields;
+
+	// Navigate through the path parts (all except the last one)
+	for (let i = 0; i < pathParts.length - 1; i++) {
+		const part = pathParts[i];
+		if (!currentFields || !currentFields[part]) {
+			return null;
+		}
+
+		const field: FieldValue = currentFields[part];
+		// Check if the value is a complex object with fields
+		if (isComplexValue(field.value)) {
+			currentFields = field.value.fields;
+		} else {
+			return null;
+		}
+	}
+
+	// Get the final field value
+	const finalFieldName = pathParts[pathParts.length - 1];
+	if (!currentFields || !currentFields[finalFieldName]) {
+		return null;
+	}
+
+	const finalField = currentFields[finalFieldName];
+	return extractFieldPrimitive(finalField);
+}
+
+/**
+ * Extracts the display value from a single field value.
+ * Handles both simple fields and complex (nested) field values.
+ *
+ * @param fieldValue - The field value to extract from
+ * @param useDisplayValue - Whether to prefer displayValue over value (default: false)
+ * @returns Extracted string value or '—' if not found
+ *
+ * @remarks
+ * - Prioritizes displayValue when useDisplayValue is true
+ * - Handles complex nested objects by checking common display field candidates
+ * - Returns '—' for null/undefined values (useful for UI display)
+ *
+ * @example
+ * ```tsx
+ * // Extract with displayValue priority
+ * const displayValue = extractFieldValue(field, true);
+ *
+ * // Extract with value priority
+ * const value = extractFieldValue(field, false);
+ * ```
+ */
+export function extractFieldValue(
+	fieldValue: FieldValue | undefined,
+	useDisplayValue: boolean = false,
+): string {
+	if (!fieldValue) {
+		return "—";
+	}
+
+	if (useDisplayValue && isDefined(fieldValue.displayValue)) {
+		return fieldValue.displayValue;
+	}
+
+	const extracted = extractFieldPrimitive(fieldValue);
+
+	if (extracted !== null) {
+		return extracted.toString();
+	}
+
+	return "—";
+}

package/dist/force-app/main/default/webapplications/feature-react-global-search/src/utils/fieldValueExtractor.ts

@@ -0,0 +1,67 @@
+import type { FieldValue, ComplexFieldValue } from "../types/search/searchResults";
+
+const DISPLAY_FIELD_CANDIDATES = [
+	"Name",
+	"CaseNumber",
+	"Subject",
+	"Title",
+	"DeveloperName",
+	"ContractNumber",
+];
+/**
+ * Extracts the display value from a field value, handling nested structures
+ * For complex fields like Owner, extracts nested values from fields.Name.value
+ */
+export function extractFieldValue(
+	fieldValue: FieldValue | undefined,
+	useDisplayValue: boolean = false,
+): string {
+	if (!fieldValue) {
+		return "—";
+	}
+
+	// If displayValue exists and is not null, use it (highest priority)
+	if (useDisplayValue && isDefined(fieldValue.displayValue)) {
+		return fieldValue.displayValue;
+	}
+
+	// If value is a complex object (like Owner), extract nested value
+	if (isComplexValue(fieldValue.value)) {
+		return extractComplexValue(fieldValue.value as ComplexFieldValue) ?? "—";
+	}
+
+	// Otherwise use the value directly (for simple fields)
+	if (isDefined(fieldValue.value)) {
+		return fieldValue.value as string;
+	}
+
+	return "—";
+}
+
+/**
+ * Helper to safely extract name from related object
+ */
+function extractComplexValue(complex: ComplexFieldValue): string | null {
+	const fields = complex.fields;
+	if (!fields) return null;
+	// Scale: Check the candidate list until we find a field that exists and has a value
+	for (const fieldName of DISPLAY_FIELD_CANDIDATES) {
+		const field = fields[fieldName];
+		if (field) {
+			// Priority: DisplayValue -> Value
+			if (isDefined(field.displayValue)) return field.displayValue;
+			if (isDefined(field.value)) return String(field.value);
+		}
+	}
+
+	return null;
+}
+/**
+ * Type Guard checks
+ */
+function isDefined(val: unknown): val is string | number | boolean {
+	return val !== null && val !== undefined;
+}
+function isComplexValue(val: unknown): val is ComplexFieldValue {
+	return typeof val === "object" && val !== null;
+}

package/dist/force-app/main/default/webapplications/feature-react-global-search/src/utils/filterUtils.ts

@@ -0,0 +1,32 @@
+/**
+ * Filter Utilities
+ *
+ * Utility functions for filter value parsing and transformation.
+ * These utilities handle the conversion of form values to filter criteria.
+ */
+
+/**
+ * Parses a string value to either a number or string
+ * Attempts to parse as integer, falls back to trimmed string if not a valid number
+ *
+ * @param val - The value to parse (string)
+ * @returns Parsed number if valid, otherwise trimmed string, or empty string if input is empty
+ *
+ * @remarks
+ * - Returns empty string for empty/whitespace input
+ * - Attempts integer parsing first
+ * - Falls back to trimmed string if parsing fails
+ * - Used for filter values that can be either numeric or text
+ *
+ * @example
+ * ```tsx
+ * const parsed = parseFilterValue("123"); // 123 (number)
+ * const parsed = parseFilterValue("abc"); // "abc" (string)
+ * const parsed = parseFilterValue("  "); // "" (empty string)
+ * ```
+ */
+export function parseFilterValue(val: string): string | number {
+	if (!val.trim()) return "";
+	const numVal = parseInt(val.trim(), 10);
+	return isNaN(numVal) ? val.trim() : numVal;
+}

package/dist/force-app/main/default/webapplications/feature-react-global-search/src/utils/formUtils.ts

@@ -0,0 +1,130 @@
+/**
+ * Form Utilities
+ *
+ * Utility functions for form validation and error handling.
+ * These utilities are framework-agnostic and can be used with any form library.
+ */
+
+/**
+ * Form error structure from TanStack Form
+ * Errors can be objects with a message property or strings
+ */
+export interface FormError {
+	message: string;
+	[key: string]: unknown;
+}
+
+/**
+ * Type guard to check if an error has a message property
+ * @param error - The error to check
+ * @returns true if the error has a message property
+ */
+export function isFormError(error: unknown): error is FormError {
+	return (
+		typeof error === "object" &&
+		error !== null &&
+		"message" in error &&
+		typeof (error as FormError).message === "string"
+	);
+}
+
+/**
+ * Extracts unique errors by message, filtering out duplicates
+ * Handles both Error objects and string errors
+ * Converts FormError objects to Error instances for compatibility with UI components
+ *
+ * @param errors - Array of error objects or strings from form libraries
+ * @returns Array of unique Error objects (compatible with FieldError component)
+ *
+ * @example
+ * ```tsx
+ * const uniqueErrors = getUniqueErrors(formErrors);
+ * ```
+ */
+export function getUniqueErrors(errors: unknown[]): Error[] {
+	const errorMap = new Map<string, Error>();
+
+	for (const error of errors) {
+		if (isFormError(error)) {
+			// Use message as key to deduplicate
+			if (!errorMap.has(error.message)) {
+				// Convert FormError to Error for compatibility
+				const errorObj = new Error(error.message);
+				// Preserve additional properties if needed
+				Object.assign(errorObj, error);
+				errorMap.set(error.message, errorObj);
+			}
+		} else if (typeof error === "string") {
+			// Handle string errors
+			if (!errorMap.has(error)) {
+				errorMap.set(error, new Error(error));
+			}
+		} else if (error instanceof Error) {
+			// Handle Error objects directly
+			if (!errorMap.has(error.message)) {
+				errorMap.set(error.message, error);
+			}
+		}
+	}
+
+	return Array.from(errorMap.values());
+}
+
+/**
+ * Validates that min value is less than or equal to max value for range filters
+ * This utility can be used in form validation logic
+ *
+ * @param minValue - Minimum value (string or number)
+ * @param maxValue - Maximum value (string or number)
+ * @returns Error message if validation fails, null if valid
+ *
+ * @remarks
+ * - If both values are empty, validation passes
+ * - Only validates if both values can be parsed as numbers
+ * - Returns null if values cannot be parsed (lets other validators handle it)
+ *
+ * @example
+ * ```tsx
+ * // In form validation
+ * const minError = validateRangeValues(minFieldValue, maxFieldValue);
+ * if (minError) {
+ *   setFieldError('minField', minError);
+ * }
+ * ```
+ */
+export function validateRangeValues(
+	minValue: string | number | null | undefined,
+	maxValue: string | number | null | undefined,
+): string | null {
+	// If both are empty, validation passes
+	if (!minValue && !maxValue) {
+		return null;
+	}
+
+	// Parse values to numbers if possible
+	const parseValue = (val: string | number | null | undefined): number | null => {
+		if (val === null || val === undefined || val === "") {
+			return null;
+		}
+		if (typeof val === "number") {
+			return val;
+		}
+		const parsed = Number(val);
+		return isNaN(parsed) ? null : parsed;
+	};
+
+	const minNum = parseValue(minValue);
+	const maxNum = parseValue(maxValue);
+
+	// If one is not a number, skip numeric validation (let other validators handle it)
+	if (minNum === null || maxNum === null) {
+		return null;
+	}
+
+	// Validate min <= max
+	if (minNum > maxNum) {
+		return "Minimum value must be less than or equal to maximum value";
+	}
+
+	return null;
+}

package/dist/force-app/main/default/webapplications/feature-react-global-search/src/utils/paginationUtils.ts

@@ -0,0 +1,49 @@
+/**
+ * Pagination Utilities
+ *
+ * Utility functions for pagination-related operations including page size validation.
+ */
+
+/**
+ * Default page size options for pagination
+ */
+export const PAGE_SIZE_OPTIONS = [
+	{ value: "10", label: "10" },
+	{ value: "20", label: "20" },
+	{ value: "50", label: "50" },
+] as const;
+
+/**
+ * Valid page size values extracted from PAGE_SIZE_OPTIONS
+ */
+export const VALID_PAGE_SIZES = PAGE_SIZE_OPTIONS.map((opt) => Number(opt.value));
+
+/**
+ * Validates that a page size is one of the allowed options
+ * @param size - The page size to validate
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```tsx
+ * if (isValidPageSize(userInput)) {
+ *   setPageSize(userInput);
+ * }
+ * ```
+ */
+export function isValidPageSize(size: number): boolean {
+	return VALID_PAGE_SIZES.includes(size);
+}
+
+/**
+ * Gets a valid page size, defaulting to the first option if invalid
+ * @param size - The page size to validate
+ * @returns A valid page size
+ *
+ * @example
+ * ```tsx
+ * const safePageSize = getValidPageSize(userInput); // Returns valid size or default
+ * ```
+ */
+export function getValidPageSize(size: number): number {
+	return isValidPageSize(size) ? size : VALID_PAGE_SIZES[0];
+}

package/dist/force-app/main/default/webapplications/feature-react-global-search/src/utils/recordUtils.ts

@@ -0,0 +1,75 @@
+/**
+ * Record Utilities
+ *
+ * Utility functions for working with Salesforce record IDs and generating safe React keys.
+ * These utilities ensure type safety and prevent XSS vulnerabilities when using record IDs.
+ *
+ * @remarks
+ * Salesforce record IDs follow a specific format and should be validated before use
+ * as React keys or in other contexts where security is important.
+ */
+
+/**
+ * Type guard to validate that a record ID is safe to use as a React key
+ * Salesforce IDs follow a specific format (15 or 18 character alphanumeric)
+ *
+ * @param id - The record ID to validate
+ * @returns true if the ID appears to be a valid Salesforce ID format
+ *
+ * @remarks
+ * - Salesforce IDs are either 15 or 18 characters long
+ * - 18-character IDs include a 3-character checksum suffix
+ * - IDs are case-sensitive alphanumeric strings
+ * - Validates format to prevent XSS and ensure type safety
+ *
+ * @example
+ * ```tsx
+ * if (isValidSalesforceId(record.id)) {
+ *   // TypeScript knows record.id is string here
+ *   useRecordId(record.id);
+ * }
+ * ```
+ */
+export function isValidSalesforceId(id: string | null | undefined): id is string {
+	if (!id || typeof id !== "string") {
+		return false;
+	}
+	// Salesforce IDs are 15 or 18 characters, alphanumeric (case-sensitive)
+	// Pattern: 15 chars or 18 chars (15 + 3 checksum chars)
+	return /^[a-zA-Z0-9]{15}$|^[a-zA-Z0-9]{18}$/.test(id);
+}
+
+/**
+ * Generates a safe key for React list items
+ * Uses record ID if valid, otherwise falls back to index-based key
+ *
+ * @param recordId - The record ID (can be null or undefined)
+ * @param index - Fallback index to use if ID is invalid
+ * @param prefix - Optional prefix for fallback keys (default: "result")
+ * @returns A safe key string that can be used as a React key prop
+ *
+ * @remarks
+ * - Validates ID format before using it as a key
+ * - Prevents XSS by ensuring only valid Salesforce IDs are used
+ * - Provides fallback for missing or invalid IDs
+ * - Ensures React always has a unique, stable key
+ *
+ * @example
+ * ```tsx
+ * {records.map((record, index) => (
+ *   <RecordCard key={getSafeKey(record.id, index)} record={record} />
+ * ))}
+ * ```
+ */
+export function getSafeKey(
+	recordId: string | null | undefined,
+	index: number,
+	prefix: string = "result",
+): string {
+	if (isValidSalesforceId(recordId)) {
+		// TypeScript narrows recordId to string here due to type guard
+		return recordId;
+	}
+	// Fallback to index-based key if ID is invalid or missing
+	return `${prefix}-${index}`;
+}