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

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/types/filters/picklist.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+/**
+ * Type definitions for picklist value structures
+ */
+
+// Zod Schema for Picklist Value
+const PicklistValueSchema = z
+	.object({
+		// 1. Cleanup: Attributes are usually an object, not just 'unknown'
+		attributes: z.record(z.string(), z.unknown()).nullish(),
+		label: z.string(),
+
+		// 2. Precise Typing: 'validFor' is an array of indices (numbers)
+		// pointing to the controlling field's values.
+		validFor: z.array(z.number()).nullish(),
+		value: z.string(),
+
+		// 3. Usability: Added common API fields that are useful for UI logic
+		// (marked optional in case the specific API version omits them)
+		defaultValue: z.boolean().nullish(),
+		active: z.boolean().nullish(),
+	})
+	.passthrough();
+
+/**
+ * Single picklist value from the API
+ */
+export type PicklistValue = z.infer<typeof PicklistValueSchema>;
+
+// Export schema for validation
+export const PicklistValueArraySchema = z.array(PicklistValueSchema);

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from "./filters/filters";
+export * from "./objectInfo/objectInfo";
+export * from "./recordDetail/recordDetail";
+export * from "./search/searchResults";

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/types/leaflet.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Type declarations for leaflet and react-leaflet when types are not installed in the type-check context.
+ * The app lists these in feature packageJson; this file satisfies TypeScript during source builds.
+ */
+declare module "leaflet" {
+	const L: Record<string, unknown>;
+	export default L;
+}
+
+declare module "react-leaflet" {
+	import type { ComponentType } from "react";
+	export const MapContainer: ComponentType<Record<string, unknown>>;
+	export const TileLayer: ComponentType<Record<string, unknown>>;
+	export const Marker: ComponentType<Record<string, unknown>>;
+	export const Popup: ComponentType<Record<string, unknown>>;
+	export function useMap(): Record<string, unknown>;
+}

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/types/objectInfo/objectInfo.ts

@@ -0,0 +1,166 @@
+import { z } from "zod";
+
+/**
+ * Type definitions and Zod schemas for Object Info Batch API response
+ */
+
+// Zod Schema for Child Relationship
+const ChildRelationshipSchema = z.object({
+	childObjectApiName: z.string(),
+	fieldName: z.string(),
+	junctionIdListNames: z.array(z.string()),
+	junctionReferenceTo: z.array(z.string()),
+	relationshipName: z.string(),
+});
+
+// Zod Schema for Reference To Info
+const ReferenceToInfoSchema = z.object({
+	apiName: z.string(),
+	nameFields: z.array(z.string()),
+});
+
+// Zod Schema for Filtered Lookup Info (can be null or object)
+const FilteredLookupInfoSchema = z.record(z.string(), z.unknown()).nullable();
+
+// Zod Schema for Field Definition
+// Using passthrough to allow extra fields that might be present in the API response
+const FieldSchema = z
+	.object({
+		apiName: z.string(),
+		calculated: z.boolean(),
+		compound: z.boolean(),
+		compoundComponentName: z.string().nullable(),
+		compoundFieldName: z.string().nullable(),
+		controllerName: z.string().nullable(),
+		controllingFields: z.array(z.string()),
+		createable: z.boolean(),
+		custom: z.boolean(),
+		dataType: z.string(),
+		defaultValue: z.unknown().nullable(),
+		defaultedOnCreate: z.boolean(),
+		digits: z.number(),
+		externalId: z.boolean(),
+		extraTypeInfo: z.string().nullable(),
+		filterable: z.boolean(),
+		filteredLookupInfo: FilteredLookupInfoSchema,
+		highScaleNumber: z.boolean(),
+		htmlFormatted: z.boolean(),
+		inlineHelpText: z.string().nullable(),
+		label: z.string(),
+		length: z.number(),
+		maskType: z.string().nullable(),
+		nameField: z.boolean(),
+		polymorphicForeignKey: z.boolean(),
+		precision: z.number(),
+		reference: z.boolean(),
+		referenceTargetField: z.string().nullable(),
+		referenceToInfos: z.array(ReferenceToInfoSchema),
+		relationshipName: z.string().nullable(),
+		required: z.boolean(),
+		scale: z.number(),
+		searchPrefilterable: z.boolean(),
+		sortable: z.boolean(),
+		unique: z.boolean(),
+		updateable: z.boolean(),
+	})
+	.passthrough();
+
+// Zod Schema for Record Type Info
+// Using passthrough to allow extra fields that might be present in the API response
+const RecordTypeInfoSchema = z
+	.object({
+		available: z.boolean(),
+		defaultRecordTypeMapping: z.boolean(),
+		master: z.boolean(),
+		name: z.string(),
+		recordTypeId: z.string(),
+	})
+	.passthrough();
+
+// Zod Schema for Theme Info
+const ThemeInfoSchema = z.object({
+	color: z.string(),
+	iconUrl: z.string(),
+});
+
+// Zod Schema for Object Info Result
+// Using passthrough to allow extra fields and using FieldSchema/RecordTypeInfoSchema with passthrough
+const ObjectInfoResultSchema = z
+	.object({
+		apiName: z.string(),
+		associateEntityType: z.string().nullable(),
+		associateParentEntity: z.string().nullable(),
+		childRelationships: z.array(ChildRelationshipSchema),
+		compactLayoutable: z.boolean(),
+		createable: z.boolean(),
+		custom: z.boolean(),
+		defaultRecordTypeId: z.string(),
+		deletable: z.boolean(),
+		dependentFields: z.record(z.string(), z.unknown()),
+		eTag: z.string(),
+		feedEnabled: z.boolean(),
+		// Avoid using FieldSchema because of performance concerns with validating the high number of fields returned from the Salesforce API and causing the UI to freeze.
+		fields: z.record(z.string(), z.any()),
+		keyPrefix: z.string(),
+		label: z.string(),
+		labelPlural: z.string(),
+		layoutable: z.boolean(),
+		mruEnabled: z.boolean(),
+		nameFields: z.array(z.string()),
+		queryable: z.boolean(),
+		// Avoid using RecordTypeInfoSchema because of performance concerns with validating the high number of fields returned from the Salesforce API and causing the UI to freeze.
+		recordTypeInfos: z.record(z.string(), z.any()),
+		searchLayoutable: z.boolean(),
+		searchable: z.boolean(),
+		themeInfo: ThemeInfoSchema,
+		updateable: z.boolean(),
+	})
+	.passthrough();
+
+// Zod Schema for Object Info Batch Result Item
+const ObjectInfoBatchResultItemSchema = z.object({
+	result: ObjectInfoResultSchema,
+	statusCode: z.number(),
+});
+
+// Zod Schema for Object Info Batch Response (array of items)
+export const ObjectInfoBatchResponseSchema = z.object({
+	results: z.array(ObjectInfoBatchResultItemSchema),
+});
+
+// TypeScript Types (inferred from Zod schemas)
+export type ChildRelationship = z.infer<typeof ChildRelationshipSchema>;
+export type ReferenceToInfo = z.infer<typeof ReferenceToInfoSchema>;
+export type FilteredLookupInfo = z.infer<typeof FilteredLookupInfoSchema>;
+export type Field = z.infer<typeof FieldSchema>;
+export type RecordTypeInfo = z.infer<typeof RecordTypeInfoSchema>;
+export type ThemeInfo = z.infer<typeof ThemeInfoSchema>;
+export type ObjectInfoBatchResponse = z.infer<typeof ObjectInfoBatchResponseSchema>;
+// Type Patching: Overwriting the "any" from the performance-optimized schema
+// with the strict types defined above. This ensures Developers get strict typing
+// even though the Runtime Validator skips the deep check.
+export type ObjectInfoResult = Omit<
+	z.infer<typeof ObjectInfoResultSchema>,
+	"fields" | "recordTypeInfos"
+> & {
+	fields: Record<string, Field>;
+	recordTypeInfos: Record<string, RecordTypeInfo>;
+};
+export type ObjectInfoBatchResultItem = Omit<
+	z.infer<typeof ObjectInfoBatchResultItemSchema>,
+	"result"
+> & {
+	result: ObjectInfoResult;
+};
+
+// Export schemas for validation
+export {
+	ChildRelationshipSchema,
+	ReferenceToInfoSchema,
+	FilteredLookupInfoSchema,
+	FieldSchema,
+	RecordTypeInfoSchema,
+	ThemeInfoSchema,
+	ObjectInfoResultSchema,
+	ObjectInfoBatchResultItemSchema,
+};

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/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/dist/force-app/main/default/webapplications/appreactsampleb2x/src/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/dist/force-app/main/default/webapplications/appreactsampleb2x/src/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);
+}