@salesforce/webapp-template-app-react-sample-b2x-experimental 1.68.0 → 1.69.0

package/dist/force-app/main/default/webapplications/appreactsampleb2x/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/appreactsampleb2x/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/appreactsampleb2x/src/utils/fieldUtils.ts

@@ -0,0 +1,354 @@
+/**
+ * Field value extraction and formatting for Salesforce UI API record shapes.
+ * Handles primitives, nested paths (e.g. Owner.Alias), reference/relationship display,
+ * address and modstamp compound formatting, and layout-item value clubbing.
+ */
+
+import type { FieldValue, ComplexFieldValue } from "../types/search/searchResults";
+
+/** Fallback field names for reference/relationship display when object info nameFields are not available. */
+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;
+}
+
+export type FieldValueWithRelationship = FieldValue & {
+	relationshipField?: FieldValue | null;
+	constituents?: Record<string, FieldValue>;
+};
+
+/** Id + Date pairs for Created By / Last Modified By (UI API modstamp convention). */
+const MODSTAMP_FIELDS = [
+	{ idFieldName: "CreatedById", dateFieldName: "CreatedDate" },
+	{ idFieldName: "LastModifiedById", dateFieldName: "LastModifiedDate" },
+] as const;
+
+function isModstampConstituents(constituents: Record<string, FieldValue>): boolean {
+	return MODSTAMP_FIELDS.some(
+		({ idFieldName, dateFieldName }) =>
+			idFieldName in constituents && dateFieldName in constituents,
+	);
+}
+
+/**
+ * Formats an ISO 8601 date-time string to the user's locale and timezone.
+ * Uses the browser's default locale and local timezone.
+ */
+export function formatDateTimeForDisplay(isoOrDateString: string): string {
+	if (!isoOrDateString || typeof isoOrDateString !== "string") return isoOrDateString;
+	const trimmed = isoOrDateString.trim();
+	if (!trimmed) return isoOrDateString;
+	const date = new Date(trimmed);
+	if (Number.isNaN(date.getTime())) return isoOrDateString;
+	try {
+		return new Intl.DateTimeFormat(undefined, {
+			dateStyle: "medium",
+			timeStyle: "short",
+		}).format(date);
+	} catch {
+		return isoOrDateString;
+	}
+}
+
+function formatModstampDisplay(constituents: Record<string, FieldValue>): string {
+	for (const { idFieldName, dateFieldName } of MODSTAMP_FIELDS) {
+		const idField = constituents[idFieldName];
+		const dateField = constituents[dateFieldName];
+		if (!idField || !dateField) continue;
+		const idWithRel = idField as FieldValueWithRelationship;
+		const name =
+			idWithRel.relationshipField != null
+				? getPrimitiveString(idWithRel.relationshipField)
+				: getPrimitiveString(idField);
+		const dateRaw = getPrimitiveString(dateField);
+		const date = dateRaw ? formatDateTimeForDisplay(dateRaw) : "";
+		const parts = [name, date].filter(Boolean);
+		if (parts.length) return parts.join(" ");
+	}
+	return "";
+}
+
+const ADDRESS_STREET_SUFFIXES = ["Street"];
+const ADDRESS_CITY_SUFFIXES = ["City"];
+const ADDRESS_STATE_SUFFIXES = ["State", "StateCode"];
+const ADDRESS_POSTAL_SUFFIXES = ["PostalCode"];
+const ADDRESS_COUNTRY_SUFFIXES = ["Country", "CountryCode"];
+
+function getPrimitiveString(fv: FieldValue | undefined): string {
+	if (!fv) return "";
+	const p = extractFieldPrimitive(fv);
+	return ((p as string) || "").trim();
+}
+
+function fieldNameEndsWithOneOf(name: string, suffixes: string[]): boolean {
+	return suffixes.some(
+		(s) =>
+			name === s || name.endsWith(s) || (name.endsWith("__c") && name.slice(0, -3).endsWith(s)),
+	);
+}
+
+function findAddressPartKey(keys: string[], suffixes: string[]): string | undefined {
+	return keys.find((k) => fieldNameEndsWithOneOf(k, suffixes));
+}
+
+export interface AddressParts {
+	street: string;
+	city: string;
+	state: string;
+	postalCode: string;
+	country: string;
+}
+
+export function getAddressPartsFromConstituents(
+	constituents: Record<string, FieldValue>,
+): AddressParts {
+	const keys = Object.keys(constituents);
+	const streetKey = findAddressPartKey(keys, ADDRESS_STREET_SUFFIXES);
+	const cityKey = findAddressPartKey(keys, ADDRESS_CITY_SUFFIXES);
+	const stateKey = findAddressPartKey(keys, ADDRESS_STATE_SUFFIXES);
+	const postalKey = findAddressPartKey(keys, ADDRESS_POSTAL_SUFFIXES);
+	const countryKey = findAddressPartKey(keys, ADDRESS_COUNTRY_SUFFIXES);
+	return {
+		street: streetKey ? getPrimitiveString(constituents[streetKey]) : "",
+		city: cityKey ? getPrimitiveString(constituents[cityKey]) : "",
+		state: stateKey ? getPrimitiveString(constituents[stateKey]) : "",
+		postalCode: postalKey ? getPrimitiveString(constituents[postalKey]) : "",
+		country: countryKey ? getPrimitiveString(constituents[countryKey]) : "",
+	};
+}
+
+export function isAddressConstituents(constituents: Record<string, FieldValue>): boolean {
+	const keys = Object.keys(constituents);
+	const hasStreet = !!findAddressPartKey(keys, ADDRESS_STREET_SUFFIXES);
+	const hasCity = !!findAddressPartKey(keys, ADDRESS_CITY_SUFFIXES);
+	const hasState = !!findAddressPartKey(keys, ADDRESS_STATE_SUFFIXES);
+	const hasCountry = !!findAddressPartKey(keys, ADDRESS_COUNTRY_SUFFIXES);
+	return hasStreet && (hasCity || hasState || hasCountry);
+}
+
+export function formatAddressDisplay(parts: AddressParts): string {
+	const { street, city, state, postalCode, country } = parts;
+	const statePostal = [state, postalCode].filter(Boolean).join(" ");
+	const line2 = city ? (statePostal ? `${city}, ${statePostal}` : city) : statePostal;
+	const lines = [street, line2, country].filter(Boolean);
+	return lines.join("\n").trim();
+}
+
+export function formatAddressFromConstituents(constituents: Record<string, FieldValue>): string {
+	const parts = getAddressPartsFromConstituents(constituents);
+	return formatAddressDisplay(parts);
+}
+
+function isModstampApiNames(apiNames: string[]): boolean {
+	return MODSTAMP_FIELDS.some(
+		({ idFieldName, dateFieldName }) =>
+			apiNames.includes(idFieldName) && apiNames.includes(dateFieldName),
+	);
+}
+
+function isAddressApiNames(apiNames: string[]): boolean {
+	const hasStreet = apiNames.some((n) => fieldNameEndsWithOneOf(n, ADDRESS_STREET_SUFFIXES));
+	const hasCity = apiNames.some((n) => fieldNameEndsWithOneOf(n, ADDRESS_CITY_SUFFIXES));
+	const hasState = apiNames.some((n) => fieldNameEndsWithOneOf(n, ADDRESS_STATE_SUFFIXES));
+	const hasCountry = apiNames.some((n) => fieldNameEndsWithOneOf(n, ADDRESS_COUNTRY_SUFFIXES));
+	return hasStreet && (hasCity || hasState || hasCountry);
+}
+
+export interface LayoutItemDisplayResult {
+	value: string | number | boolean | null;
+	dataType?: string;
+}
+
+export function getDisplayValueForLayoutItem(
+	fields: Record<string, FieldValue> | undefined,
+	componentApiNames: string[],
+): LayoutItemDisplayResult {
+	if (!fields || componentApiNames.length === 0) {
+		return { value: null };
+	}
+	if (componentApiNames.length === 1) {
+		const value = getDisplayValueForDetailField(
+			fields[componentApiNames[0]] as FieldValueWithRelationship | undefined,
+		);
+		return { value };
+	}
+	const constituents: Record<string, FieldValue> = {};
+	for (const apiName of componentApiNames) {
+		if (fields[apiName] != null) constituents[apiName] = fields[apiName];
+	}
+	if (isModstampApiNames(componentApiNames)) {
+		const value = formatModstampDisplay(constituents);
+		return { value: value || null };
+	}
+	if (isAddressApiNames(componentApiNames)) {
+		const parts = getAddressPartsFromConstituents(constituents);
+		const value = formatAddressDisplay(parts);
+		return { value: value || null, dataType: "Address" };
+	}
+	const values = componentApiNames
+		.map((apiName) =>
+			getDisplayValueForDetailField(fields[apiName] as FieldValueWithRelationship | undefined),
+		)
+		.filter((v) => v !== null && v !== undefined && v !== "");
+	return { value: values.length > 0 ? values.join(", ") : null };
+}
+
+export function getDisplayValueForDetailField(
+	field: FieldValueWithRelationship | undefined,
+): string | number | boolean | null {
+	if (!field) return null;
+	const withExt = field as FieldValueWithRelationship;
+	if (withExt.relationshipField != null) {
+		const fromRel = extractFieldPrimitive(withExt.relationshipField);
+		if (fromRel !== null && fromRel !== undefined && fromRel !== "") {
+			return fromRel;
+		}
+	}
+	if (withExt.constituents != null) {
+		if (isModstampConstituents(withExt.constituents)) {
+			const formatted = formatModstampDisplay(withExt.constituents);
+			if (formatted) return formatted;
+		} else if (isAddressConstituents(withExt.constituents)) {
+			const formatted = formatAddressFromConstituents(withExt.constituents);
+			if (formatted) return formatted;
+		}
+	}
+	return extractFieldPrimitive(field);
+}
+
+export function getNestedFieldValue(
+	fields: Record<string, FieldValue> | undefined,
+	fieldPath: string,
+): string | number | boolean | null {
+	if (!fields || !fieldPath) {
+		return null;
+	}
+
+	const pathParts = fieldPath.split(".");
+	if (pathParts.length === 1) {
+		const field = fields[fieldPath];
+		if (!field) return null;
+
+		return extractFieldPrimitive(field);
+	}
+
+	let currentFields: Record<string, FieldValue> | undefined = fields;
+	for (let i = 0; i < pathParts.length - 1; i++) {
+		const part = pathParts[i];
+		if (!currentFields || !currentFields[part]) {
+			return null;
+		}
+
+		const field: FieldValue = currentFields[part];
+		if (isComplexValue(field.value)) {
+			currentFields = field.value.fields;
+		} else {
+			return null;
+		}
+	}
+
+	const finalFieldName = pathParts[pathParts.length - 1];
+	if (!currentFields || !currentFields[finalFieldName]) {
+		return null;
+	}
+
+	const finalField = currentFields[finalFieldName];
+	return extractFieldPrimitive(finalField);
+}
+
+/** Minimal metadata for record display name (nameFields from object info API). */
+export type RecordDisplayNameMetadata = { nameFields?: string[] } | null;
+
+/**
+ * Resolves a display name for a record: tries metadata.nameFields first, then
+ * DISPLAY_FIELD_CANDIDATES (Name, Subject, etc.), then record.id.
+ */
+export function getRecordDisplayName(
+	record: { id: string; fields: Record<string, FieldValue> },
+	metadata?: RecordDisplayNameMetadata,
+): string {
+	const candidates = [...(metadata?.nameFields ?? []), ...DISPLAY_FIELD_CANDIDATES];
+	for (const fieldPath of candidates) {
+		const v = getNestedFieldValue(record.fields, fieldPath);
+		return v as string;
+	}
+	return record.id;
+}
+
+/** Adapts object info (e.g. ObjectInfoResult) to the shape expected by getRecordDisplayName. */
+export function toRecordDisplayNameMetadata(obj: unknown): RecordDisplayNameMetadata {
+	if (obj != null && typeof obj === "object" && "nameFields" in obj) {
+		const nameFields = (obj as { nameFields?: string[] }).nameFields;
+		if (Array.isArray(nameFields)) return { nameFields };
+	}
+	return null;
+}
+
+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 as string;
+	}
+
+	return "—";
+}

package/dist/force-app/main/default/webapplications/appreactsampleb2x/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 field.value as string;
+		}
+	}
+
+	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/appreactsampleb2x/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;
+}