@salesforce/templates 66.3.0 → 66.3.2

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

@@ -0,0 +1,260 @@
+/**
+ * Transforms UI API record + object info into detail form shape: Reference fields get
+ * relationshipField, compound fields get constituents, metadata gets editable flag.
+ * Aligns with LWC detailForm _calculateFormData and uiApiDataTransformHelper.
+ */
+
+import type { FieldValue } from "../types/search/searchResults";
+
+/** Field metadata from object info API (subset used by form transform). */
+export interface ObjectInfoFieldMetadata {
+	compound?: boolean;
+	compoundFieldName?: string;
+	compoundComponentName?: string;
+	dataType?: string;
+	relationshipName?: string;
+	updateable?: boolean;
+	calculated?: boolean;
+	polymorphicForeignKey?: boolean;
+	apiName?: string;
+	label?: string;
+	[name: string]: unknown;
+}
+
+/** Minimal UI API object info (metadata) for form data transform. */
+export interface ObjectInfoMetadata {
+	apiName?: string;
+	fields?: Record<string, ObjectInfoFieldMetadata>;
+	[name: string]: unknown;
+}
+
+/** Transformed field value: base FieldValue + relationshipField (Reference) and constituents (compound). */
+export interface TransformedFieldValue extends FieldValue {
+	relationshipField?: FieldValue;
+	constituents?: Record<string, TransformedFieldValue & { metadata?: ObjectInfoFieldMetadata }>;
+}
+
+export type TransformedDataFields = Record<string, TransformedFieldValue>;
+
+/** Form values keyed by record context id (e.g. record.id). */
+export type FormValues = Record<string, TransformedDataFields>;
+
+/** Form metadata keyed by metadata context (e.g. object apiName). */
+export type FormMetadata = Record<string, ObjectInfoMetadata>;
+
+/** Contexts: recordId -> objectApiName. */
+export type FormContexts = Record<string, string>;
+
+/** Result of calculateFormData (single record). */
+export interface FormData {
+	formValues: FormValues;
+	formMetadata: FormMetadata;
+	formContexts: FormContexts;
+}
+
+/** Fields never editable per UI API (platform convention). */
+const NON_EDITABLE_FIELDS = ["OwnerId", "RecordTypeId"];
+
+/** Created By / Last Modified By: synthetic compound from Id + Date (modstampMetadataTransform). */
+const SYSTEM_FIELDS = [
+	{
+		fieldName: "CreatedBy",
+		idFieldName: "CreatedById",
+		dateFieldName: "CreatedDate",
+		apiName: "CreatedBy",
+		compound: true,
+		dataType: "String",
+		label: "Created By",
+	},
+	{
+		fieldName: "LastModifiedBy",
+		idFieldName: "LastModifiedById",
+		dateFieldName: "LastModifiedDate",
+		apiName: "LastModifiedBy",
+		compound: true,
+		dataType: "String",
+		label: "Last Modified By",
+	},
+];
+
+function modstampMetadataTransform(metadata: ObjectInfoMetadata): ObjectInfoMetadata {
+	const fields = { ...metadata.fields };
+	if (!fields) return metadata;
+
+	SYSTEM_FIELDS.forEach((systemField) => {
+		const field = systemField.fieldName;
+		const idField = systemField.idFieldName;
+		const dateField = systemField.dateFieldName;
+		if (idField in fields && dateField in fields && metadata.fields) {
+			fields[field] = { ...metadata.fields[idField], ...systemField };
+			fields[idField] = {
+				...(metadata.fields[idField] ?? {}),
+				compoundComponentName: "Id",
+				compoundFieldName: field,
+			};
+			fields[dateField] = {
+				...(metadata.fields[dateField] ?? {}),
+				compoundComponentName: "Date",
+				compoundFieldName: field,
+			};
+		}
+	});
+	return { ...metadata, fields };
+}
+
+export function metaDataTransform(metadata: ObjectInfoMetadata): ObjectInfoMetadata {
+	const newMetadata = modstampMetadataTransform(metadata);
+	const fields: Record<string, ObjectInfoFieldMetadata> = {};
+	const metaFields = newMetadata.fields ?? {};
+	Object.keys(metaFields).forEach((fieldName) => {
+		const fieldRep = metaFields[fieldName];
+		const isCalculated = Boolean(fieldRep.calculated);
+		const isUpdateable = Boolean(fieldRep.updateable);
+		const isPolymorphicLookup = Boolean(fieldRep.polymorphicForeignKey);
+		fields[fieldName] = {
+			...fieldRep,
+			editable:
+				!isCalculated &&
+				isUpdateable &&
+				!isPolymorphicLookup &&
+				!NON_EDITABLE_FIELDS.includes(fieldName),
+		} as ObjectInfoFieldMetadata;
+	});
+	return { ...newMetadata, fields };
+}
+
+export function getConstituentMap(
+	dataFields: Record<string, FieldValue>,
+	fieldMetadata: Record<string, ObjectInfoFieldMetadata>,
+): Record<string, Record<string, TransformedFieldValue & { metadata?: ObjectInfoFieldMetadata }>> {
+	const constituentMap: Record<
+		string,
+		Record<string, TransformedFieldValue & { metadata?: ObjectInfoFieldMetadata }>
+	> = {};
+	Object.keys(fieldMetadata).forEach((fieldApiName) => {
+		const { compoundFieldName } = fieldMetadata[fieldApiName];
+		if (compoundFieldName && dataFields[fieldApiName]) {
+			const constituentFields =
+				constituentMap[compoundFieldName] ??
+				({} as Record<string, TransformedFieldValue & { metadata?: ObjectInfoFieldMetadata }>);
+			const raw = dataFields[fieldApiName] as TransformedFieldValue;
+			constituentFields[fieldApiName] = {
+				...raw,
+				metadata: fieldMetadata[fieldApiName],
+			};
+			constituentMap[compoundFieldName] = constituentFields;
+
+			const compoundMeta = fieldMetadata[compoundFieldName];
+			if (
+				compoundMeta?.dataType === "Address" &&
+				(fieldApiName.endsWith("StateCode") || fieldApiName.endsWith("CountryCode"))
+			) {
+				const nonPicklistName = fieldApiName.replace("Code", "");
+				if (fieldMetadata[nonPicklistName] && dataFields[nonPicklistName]) {
+					constituentFields[nonPicklistName] = {
+						...(dataFields[nonPicklistName] as TransformedFieldValue),
+						metadata: fieldMetadata[nonPicklistName],
+					};
+				}
+			}
+		}
+	});
+	if (constituentMap.Name) {
+		const constituentApiNames = Object.keys(constituentMap.Name);
+		if (constituentApiNames.length === 1 && constituentApiNames[0] === "Name") {
+			delete constituentMap.Name;
+		}
+	}
+	return constituentMap;
+}
+
+export function objectInfoFieldsTransform(
+	dataFields: Record<string, FieldValue>,
+	metadata: ObjectInfoMetadata,
+): TransformedDataFields {
+	const fieldMetadata = metadata.fields ?? {};
+	const transformedDataFields: TransformedDataFields = { ...dataFields };
+
+	Object.keys(fieldMetadata).forEach((field) => {
+		const meta = fieldMetadata[field];
+		if (meta.dataType === "Reference" && meta.relationshipName != null) {
+			const existing = dataFields[field];
+			const relField = dataFields[meta.relationshipName];
+			transformedDataFields[field] = {
+				...(existing ?? {}),
+				relationshipField: {
+					...(relField ?? {}),
+					value: null,
+				},
+			};
+		}
+	});
+
+	Object.keys(fieldMetadata).forEach((field) => {
+		const meta = fieldMetadata[field];
+		const { compound, dataType } = meta;
+		const existing = dataFields[field];
+		if (dataType === "Reference") return;
+		if (compound) {
+			transformedDataFields[field] = { ...(existing ?? {}) };
+		} else if (existing) {
+			transformedDataFields[field] = existing as TransformedFieldValue;
+		}
+	});
+
+	const constituentMap = getConstituentMap(transformedDataFields, fieldMetadata);
+	Object.keys(constituentMap).forEach((field) => {
+		if (transformedDataFields[field]) {
+			transformedDataFields[field] = {
+				...transformedDataFields[field],
+				constituents: constituentMap[field],
+			};
+		}
+	});
+	return transformedDataFields;
+}
+
+export function multiRecordMetadataTransform(
+	metadata: Record<string, ObjectInfoMetadata>,
+): FormMetadata {
+	const result: FormMetadata = {};
+	Object.keys(metadata).forEach((metadataContext) => {
+		result[metadataContext] = metaDataTransform(metadata[metadataContext]);
+	});
+	return result;
+}
+
+export function multiRecordValuesTransform(
+	values: Record<string, Record<string, FieldValue>>,
+	metadata: FormMetadata,
+	contexts: FormContexts,
+): FormValues {
+	const result: FormValues = {};
+	Object.keys(values).forEach((recordContext) => {
+		const metadataContext = contexts[recordContext];
+		if (metadataContext && metadata[metadataContext]) {
+			result[recordContext] = objectInfoFieldsTransform(
+				values[recordContext],
+				metadata[metadataContext],
+			);
+		}
+	});
+	return result;
+}
+
+export function calculateFormData(
+	record: { id: string; apiName: string; fields: Record<string, FieldValue> },
+	metadata: ObjectInfoMetadata | null | undefined,
+): FormData {
+	const formValues: FormValues = {};
+	const formMetadata: FormMetadata = {};
+	const formContexts: FormContexts = { [record.id]: record.apiName };
+
+	if (!metadata?.fields) {
+		return { formValues, formMetadata, formContexts };
+	}
+
+	formMetadata[record.apiName] = metaDataTransform(metadata);
+	formValues[record.id] = objectInfoFieldsTransform(record.fields, formMetadata[record.apiName]);
+	return { formValues, formMetadata, formContexts };
+}

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

@@ -0,0 +1,142 @@
+/**
+ * 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) {
+			return null;
+		}
+		if (typeof val === "number") {
+			return val;
+		}
+		const parsed = parseInt(val, 10);
+		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;
+}
+
+export function getFormValueByPath(record: Record<string, unknown>, fieldPath: string): string {
+	if (!fieldPath) return "";
+	const parts = fieldPath.split(".");
+	let current: Record<string, unknown> = record;
+	for (const part of parts) {
+		if (current == null || typeof current !== "object") return "";
+		current = (current as Record<string, unknown>)[part] as unknown as Record<string, unknown>;
+	}
+	if (current === undefined || current === null) return "";
+	return "" + current;
+}

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

@@ -0,0 +1,186 @@
+/**
+ * GraphQL record node → display values for detail view.
+ *
+ * getGraphQLNodeValue: primitive by field path. getDisplayValueForDetailFieldFromNode: single field,
+ * uses metadata to show relationship name instead of Id. getDisplayValueForLayoutItemFromNode:
+ * single or compound (address, modstamp). getGraphQLRecordDisplayName: record title from nameFields.
+ *
+ * @module utils/graphQLNodeFieldUtils
+ */
+
+import type { FieldValue } from "../types/search/searchResults";
+import type { GraphQLRecordNode } from "../api/recordListGraphQLService";
+import type { ObjectInfoMetadata } from "./formDataTransformUtils";
+import { getDisplayValueForLayoutItem, type LayoutItemDisplayResult } from "./fieldUtils";
+
+/** Metadata from getObjectInfoBatch (object metadata) used to resolve reference fields by relationshipName. */
+export type ObjectMetadataForDisplay = ObjectInfoMetadata | null | undefined;
+
+/**
+ * Gets a primitive value from a GraphQL node by field path.
+ * - "Id" -> node.Id (scalar)
+ * - "Name" -> node.Name?.value
+ * - "Owner.Alias" -> node.Owner?.Alias?.value
+ */
+export function getGraphQLNodeValue(
+	node: GraphQLRecordNode | null | undefined,
+	fieldPath: string,
+): string | number | boolean | null {
+	if (!node || !fieldPath) return null;
+	const parts = fieldPath.split(".");
+	let current: unknown = node;
+	for (let i = 0; i < parts.length; i++) {
+		if (current == null || typeof current !== "object") return null;
+		current = (current as Record<string, unknown>)[parts[i]];
+	}
+	if (current == null) return null;
+	if (typeof current === "object" && current !== null && "value" in current) {
+		const v = (current as { value: unknown }).value;
+		if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+			return v;
+		}
+		if (v === null) return null;
+		return v as string;
+	}
+	if (typeof current === "string" || typeof current === "number" || typeof current === "boolean") {
+		return current as string | number | boolean;
+	}
+	// Relationship/lookup objects: try DisplayValue (scalar or object), Name.value, then Id
+	if (typeof current === "object" && current !== null) {
+		const obj = current as Record<string, unknown>;
+		const displayVal = obj.DisplayValue ?? obj.displayValue;
+		if (displayVal != null) {
+			if (
+				typeof displayVal === "string" ||
+				typeof displayVal === "number" ||
+				typeof displayVal === "boolean"
+			) {
+				return displayVal;
+			}
+			if (typeof displayVal === "object" && "value" in displayVal) {
+				const v = (displayVal as { value: unknown }).value;
+				if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+				if (v === null) return null;
+				return v as string;
+			}
+		}
+		const nameObj = obj.Name ?? obj.name;
+		if (nameObj != null && typeof nameObj === "object" && "value" in nameObj) {
+			const v = (nameObj as { value: unknown }).value;
+			if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+			if (v === null) return null;
+			return v as string;
+		}
+		const idVal = obj.Id ?? obj.id;
+		if (
+			idVal != null &&
+			(typeof idVal === "string" || typeof idVal === "number" || typeof idVal === "boolean")
+		) {
+			return idVal;
+		}
+	}
+	return null;
+}
+
+/** Builds a minimal Record<string, FieldValue> from node for the given api names (for reuse with fieldUtils formatters). */
+function nodeToConstituentFields(
+	node: GraphQLRecordNode,
+	componentApiNames: string[],
+	metadata?: ObjectMetadataForDisplay,
+): Record<string, FieldValue> {
+	const fields: Record<string, FieldValue> = {};
+	for (const apiName of componentApiNames) {
+		const v = getDisplayValueForDetailFieldFromNode(node, apiName, metadata);
+		const displayValue = v as string | null;
+		fields[apiName] = { displayValue, value: v };
+	}
+	return fields;
+}
+
+/**
+ * Resolves display value for a layout item from a GraphQL node (single or multiple components).
+ * Reuses address/modstamp formatting from fieldUtils by building minimal constituent fields from the node.
+ * Pass metadata from getObjectInfoBatch so reference fields show the relationship's name instead of Id.
+ */
+export function getDisplayValueForLayoutItemFromNode(
+	node: GraphQLRecordNode | null | undefined,
+	componentApiNames: string[],
+	metadata?: ObjectMetadataForDisplay,
+): LayoutItemDisplayResult {
+	if (!node || componentApiNames.length === 0) {
+		return { value: null };
+	}
+	if (componentApiNames.length === 1) {
+		const apiName = componentApiNames[0];
+		const value = getDisplayValueForDetailFieldFromNode(node, apiName, metadata);
+		const dataType = metadata?.fields?.[apiName]?.dataType;
+		return { value, dataType };
+	}
+	const constituents = nodeToConstituentFields(node, componentApiNames, metadata);
+	const result = getDisplayValueForLayoutItem(constituents, componentApiNames);
+	return { value: result.value, dataType: result.dataType };
+}
+
+/**
+ * Resolves display value for a single detail field from a GraphQL node.
+ * When metadata from getObjectInfoBatch is provided and the field is a Reference (dataType === "Reference")
+ * with a relationshipName, shows the related record's display value (e.g. Owner.Name) instead of the Id.
+ */
+/** Treat dataType as Reference regardless of casing (e.g. REFERENCE from GraphQL). */
+function isReferenceDataType(dataType: string | undefined): boolean {
+	return dataType != null && dataType.toLowerCase() === "reference";
+}
+
+export function getDisplayValueForDetailFieldFromNode(
+	node: GraphQLRecordNode | null | undefined,
+	apiName: string,
+	metadata?: ObjectMetadataForDisplay,
+): string | number | boolean | null {
+	if (!node || !apiName) return null;
+	const fieldMeta = metadata?.fields?.[apiName];
+	if (
+		fieldMeta &&
+		isReferenceDataType(fieldMeta.dataType) &&
+		fieldMeta.relationshipName != null &&
+		fieldMeta.relationshipName !== ""
+	) {
+		const displayValue = getGraphQLNodeValue(node, fieldMeta.relationshipName);
+		if (displayValue !== null && displayValue !== undefined && displayValue !== "") {
+			return displayValue;
+		}
+	}
+	return getGraphQLNodeValue(node, apiName);
+}
+
+/** Fallback field names for record display name when nameFields are not available. */
+const DISPLAY_FIELD_CANDIDATES = [
+	"Name",
+	"CaseNumber",
+	"Subject",
+	"Title",
+	"DeveloperName",
+	"ContractNumber",
+] as const;
+
+/** Minimal metadata for record display name. */
+export type GraphQLRecordDisplayNameMetadata = { nameFields?: string[] } | null;
+
+/**
+ * Resolves a display name for a record from a GraphQL node.
+ * Tries metadata.nameFields first, then DISPLAY_FIELD_CANDIDATES, then node.Id.
+ */
+export function getGraphQLRecordDisplayName(
+	node: GraphQLRecordNode | null | undefined,
+	metadata?: GraphQLRecordDisplayNameMetadata,
+): string {
+	if (!node) return "";
+	const id = (node.Id as string) ?? "";
+	const candidates = [...(metadata?.nameFields ?? []), ...DISPLAY_FIELD_CANDIDATES];
+	for (const fieldPath of candidates) {
+		const v = getGraphQLNodeValue(node, fieldPath);
+		if (v !== null && v !== undefined && v !== "") {
+			return v as string;
+		}
+	}
+	return id;
+}