@salesforce/webapp-template-app-react-template-b2e-experimental 1.59.2 → 1.60.0

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/components/FiltersPanel.tsx

@@ -0,0 +1,375 @@
+/**
+ * FiltersPanel Component
+ *
+ * Displays a panel of filter inputs for refining search results.
+ * Supports both text inputs and select dropdowns based on filter affordance.
+ *
+ * @param filters - Array of filter definitions to display
+ * @param picklistValues - Record of picklist values keyed by field path
+ * @param loading - Whether filters are currently loading
+ * @param onApplyFilters - Callback when filters are applied, receives filter values object
+ *
+ * @remarks
+ * - Automatically initializes filter values from defaultValues
+ * - Shows loading skeleton while filters are being fetched
+ * - Supports "Apply Filters" and "Reset" actions
+ * - Uses TanStack Form for form state management (similar to Login page)
+ * - Uses FiltersForm wrapper for consistent UX/UI (similar to AuthForm pattern)
+ *
+ * @example
+ * ```tsx
+ * <FiltersPanel
+ *   filters={filters}
+ *   picklistValues={picklistValues}
+ *   loading={false}
+ *   onApplyFilters={(values) => applyFilters(values)}
+ * />
+ * ```
+ */
+import { useState, useMemo, useCallback, useEffect, useRef } from "react";
+import { Card, CardContent, CardHeader, CardTitle } from "./ui/card";
+import { Skeleton } from "./ui/skeleton";
+import { FiltersForm } from "./forms/filters-form";
+import { Field, FieldLabel, FieldDescription } from "./ui/field";
+import { useAppForm, validateRangeValues } from "../hooks/form";
+import type { Filter, FilterCriteria } from "../types/filters/filters";
+import type { PicklistValue } from "../types/filters/picklist";
+import { parseFilterValue } from "../utils/filterUtils";
+import { sanitizeFilterValue } from "../utils/sanitizationUtils";
+import { getFormValueByPath } from "../utils/formUtils";
+
+interface FiltersPanelProps {
+	filters: Filter[];
+	picklistValues: Record<string, PicklistValue[]>;
+	loading: boolean;
+	objectApiName: string;
+	onApplyFilters: (filterCriteria: FilterCriteria[]) => void;
+}
+
+export default function FiltersPanel({
+	filters,
+	picklistValues,
+	loading,
+	objectApiName,
+	onApplyFilters,
+}: FiltersPanelProps) {
+	const [submitError, setSubmitError] = useState<string | null>(null);
+	const [submitSuccess, setSubmitSuccess] = useState<string | null>(null);
+
+	const defaultValues = useMemo(() => {
+		if (!filters || !Array.isArray(filters)) {
+			return {};
+		}
+
+		const values: Record<string, string> = {};
+		filters.forEach((filter) => {
+			if (filter && filter.targetFieldPath) {
+				const affordance = filter.affordance?.toLowerCase() || "";
+
+				if (affordance === "range") {
+					const minFieldName = `${filter.targetFieldPath}_min`;
+					const maxFieldName = `${filter.targetFieldPath}_max`;
+
+					if (filter.defaultValues && filter.defaultValues.length >= 2) {
+						values[minFieldName] = filter.defaultValues[0] || "";
+						values[maxFieldName] = filter.defaultValues[1] || "";
+					} else {
+						values[minFieldName] = "";
+						values[maxFieldName] = "";
+					}
+				} else {
+					if (filter.defaultValues && filter.defaultValues.length > 0) {
+						values[filter.targetFieldPath] = filter.defaultValues[0];
+					} else {
+						values[filter.targetFieldPath] = "";
+					}
+				}
+			}
+		});
+		return values;
+	}, [filters]);
+
+	const form = useAppForm({
+		defaultValues,
+		onSubmit: async ({ value }) => {
+			setSubmitError(null);
+			setSubmitSuccess(null);
+			try {
+				const filterCriteria: FilterCriteria[] = [];
+
+				for (const filter of filters) {
+					if (!filter || !filter.targetFieldPath) {
+						continue;
+					}
+
+					const affordance = filter.affordance?.toLowerCase() || "";
+
+					if (affordance === "range") {
+						const minFieldName = `${filter.targetFieldPath}_min`;
+						const maxFieldName = `${filter.targetFieldPath}_max`;
+						const minValueRaw = value[minFieldName] || "";
+						const maxValueRaw = value[maxFieldName] || "";
+
+						const minValue = sanitizeFilterValue(minValueRaw);
+						const maxValue = sanitizeFilterValue(maxValueRaw);
+
+						if (minValue && maxValue) {
+							const rangeError = validateRangeValues(minValue, maxValue);
+							if (rangeError) {
+								setSubmitError(rangeError);
+								return;
+							}
+						}
+
+						if (minValue) {
+							const parsedMin = parseFilterValue(minValue);
+							if (parsedMin !== "") {
+								filterCriteria.push({
+									objectApiName,
+									fieldPath: filter.targetFieldPath,
+									operator: "gte",
+									values: [parsedMin],
+								});
+							}
+						}
+
+						if (maxValue) {
+							const parsedMax = parseFilterValue(maxValue);
+							if (parsedMax !== "") {
+								filterCriteria.push({
+									objectApiName,
+									fieldPath: filter.targetFieldPath,
+									operator: "lte",
+									values: [parsedMax],
+								});
+							}
+						}
+					} else {
+						const fieldValueRaw =
+							getFormValueByPath(value as Record<string, unknown>, filter.targetFieldPath) || "";
+						const fieldValue = sanitizeFilterValue(fieldValueRaw);
+
+						if (fieldValue) {
+							if (affordance === "select") {
+								filterCriteria.push({
+									objectApiName,
+									fieldPath: filter.targetFieldPath,
+									operator: "eq",
+									values: [fieldValue],
+								});
+							} else {
+								const likeValue = `%${fieldValue}%`;
+								filterCriteria.push({
+									objectApiName,
+									fieldPath: filter.targetFieldPath,
+									operator: "like",
+									values: [likeValue],
+								});
+							}
+						}
+					}
+				}
+
+				if (filterCriteria.length === 0) {
+					setSubmitSuccess("No filters applied. Showing all results.");
+				} else {
+					setSubmitSuccess("Filters applied successfully");
+				}
+
+				onApplyFilters(filterCriteria);
+			} catch (err) {
+				const errorMessage = err instanceof Error ? err.message : "Failed to apply filters";
+				setSubmitError(errorMessage);
+			}
+		},
+		onSubmitInvalid: () => {},
+	});
+
+	const previousDefaultValuesRef = useRef<Record<string, string>>({});
+	const previousLoadingRef = useRef<boolean>(true);
+
+	useEffect(() => {
+		const loadingJustCompleted = previousLoadingRef.current && !loading;
+		const defaultValuesChanged =
+			JSON.stringify(previousDefaultValuesRef.current) !== JSON.stringify(defaultValues);
+
+		if (loadingJustCompleted && defaultValues && Object.keys(defaultValues).length > 0) {
+			form.reset(defaultValues);
+			previousDefaultValuesRef.current = defaultValues;
+		} else if (defaultValuesChanged && !loading && Object.keys(defaultValues).length > 0) {
+			form.reset(defaultValues);
+			previousDefaultValuesRef.current = defaultValues;
+		}
+
+		previousLoadingRef.current = loading;
+	}, [loading, defaultValues]);
+
+	const handleSuccessDismiss = useCallback(() => {
+		setSubmitSuccess(null);
+	}, []);
+
+	const handleReset = useCallback(() => {
+		if (!filters || !Array.isArray(filters)) {
+			form.reset();
+			onApplyFilters([]);
+			setSubmitError(null);
+			setSubmitSuccess(null);
+			return;
+		}
+
+		const resetValues: Record<string, string> = {};
+		filters.forEach((filter) => {
+			if (filter && filter.targetFieldPath) {
+				const affordance = filter.affordance?.toLowerCase() || "";
+
+				if (affordance === "range") {
+					resetValues[`${filter.targetFieldPath}_min`] = "";
+					resetValues[`${filter.targetFieldPath}_max`] = "";
+				} else {
+					resetValues[filter.targetFieldPath] = "";
+				}
+			}
+		});
+		form.reset(resetValues);
+		onApplyFilters([]);
+		setSubmitError(null);
+		setSubmitSuccess(null);
+	}, [filters, onApplyFilters, form]);
+
+	if (loading) {
+		return (
+			<Card className="w-full" role="region" aria-label="Filters panel">
+				<CardHeader>
+					<CardTitle>Filters</CardTitle>
+				</CardHeader>
+				<CardContent
+					className="space-y-4"
+					role="status"
+					aria-live="polite"
+					aria-label="Loading filters"
+				>
+					<span className="sr-only">Loading filters</span>
+					{[1, 2, 3].map((i) => (
+						<div key={i} className="space-y-2" aria-hidden="true">
+							<Skeleton className="h-4 w-24" />
+							<Skeleton className="h-9 w-full" />
+						</div>
+					))}
+				</CardContent>
+			</Card>
+		);
+	}
+
+	if (!filters || !Array.isArray(filters) || filters.length === 0) {
+		return (
+			<Card className="w-full" role="region" aria-label="Filters panel">
+				<CardHeader>
+					<CardTitle>Filters</CardTitle>
+				</CardHeader>
+				<CardContent>
+					<p className="text-sm text-muted-foreground">No filters available</p>
+				</CardContent>
+			</Card>
+		);
+	}
+
+	return (
+		<form.AppForm>
+			<FiltersForm
+				title="Filters"
+				description="Refine your search results by applying filters"
+				error={submitError}
+				success={submitSuccess}
+				onSuccessDismiss={handleSuccessDismiss}
+				submit={{
+					text: "Apply Filters",
+					loadingText: "Applying filters…",
+				}}
+				reset={{
+					text: "Reset",
+					onReset: handleReset,
+				}}
+			>
+				{filters.map((filter) => {
+					if (!filter || !filter.targetFieldPath) {
+						return null;
+					}
+
+					const fieldPicklistValues = picklistValues[filter.targetFieldPath] || [];
+					const affordance = filter.affordance?.toLowerCase() || "";
+
+					if (affordance === "range") {
+						const minFieldName = `${filter.targetFieldPath}_min`;
+						const maxFieldName = `${filter.targetFieldPath}_max`;
+						const inputType = "text";
+						const placeholder =
+							filter.attributes?.placeholder === "null"
+								? undefined
+								: filter.attributes?.placeholder;
+
+						return (
+							<Field key={filter.targetFieldPath}>
+								<FieldLabel>{filter.label || filter.targetFieldPath}</FieldLabel>
+								{filter.helpMessage && <FieldDescription>{filter.helpMessage}</FieldDescription>}
+								<div
+									className="grid grid-cols-2 gap-3"
+									role="group"
+									aria-label={`${filter.label || filter.targetFieldPath} range filter`}
+								>
+									<form.AppField name={minFieldName}>
+										{(field) => (
+											<field.FilterRangeMinField
+												placeholder={placeholder || "Min"}
+												type={inputType}
+												aria-label={`${filter.label || filter.targetFieldPath} - Minimum`}
+											/>
+										)}
+									</form.AppField>
+									<form.AppField name={maxFieldName}>
+										{(field) => (
+											<field.FilterRangeMaxField
+												placeholder={placeholder || "Max"}
+												type={inputType}
+												aria-label={`${filter.label || filter.targetFieldPath} - Maximum`}
+											/>
+										)}
+									</form.AppField>
+								</div>
+							</Field>
+						);
+					}
+
+					if (affordance === "select") {
+						return (
+							<form.AppField key={filter.targetFieldPath} name={filter.targetFieldPath}>
+								{(field) => (
+									<field.FilterSelectField
+										label={filter.label || filter.targetFieldPath}
+										description={filter.helpMessage || undefined}
+										placeholder={filter.attributes?.placeholder || "Select..."}
+										options={fieldPicklistValues}
+									/>
+								)}
+							</form.AppField>
+						);
+					}
+
+					return (
+						<form.AppField key={filter.targetFieldPath} name={filter.targetFieldPath}>
+							{(field) => (
+								<field.FilterTextField
+									label={filter.label || filter.targetFieldPath}
+									description={filter.helpMessage || undefined}
+									placeholder={
+										filter.attributes?.placeholder ||
+										`Enter ${(filter.label || filter.targetFieldPath).toLowerCase()}`
+									}
+								/>
+							)}
+						</form.AppField>
+					);
+				})}
+			</FiltersForm>
+		</form.AppForm>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/components/LoadingFallback.tsx

@@ -0,0 +1,61 @@
+/**
+ * LoadingFallback Component
+ *
+ * Loading fallback component for Suspense boundaries.
+ * Displays a centered spinner while lazy-loaded components are being fetched.
+ *
+ * @remarks
+ * - Used with React Suspense for code splitting
+ * - Simple centered spinner design
+ * - Responsive and accessible
+ *
+ * @example
+ * ```tsx
+ * <Suspense fallback={<LoadingFallback />}>
+ *   <LazyComponent />
+ * </Suspense>
+ * ```
+ */
+import { cva, type VariantProps } from "class-variance-authority";
+import { Spinner } from "./ui/spinner";
+
+/**
+ * Spinner size variants based on content width.
+ */
+const spinnerVariants = cva("", {
+	variants: {
+		contentMaxWidth: {
+			sm: "size-6",
+			md: "size-8",
+			lg: "size-10",
+		},
+	},
+	defaultVariants: {
+		contentMaxWidth: "sm",
+	},
+});
+
+interface LoadingFallbackProps extends VariantProps<typeof spinnerVariants> {
+	/**
+	 * Maximum width of the content container. Also scales the spinner size.
+	 * @default "sm"
+	 */
+	contentMaxWidth?: "sm" | "md" | "lg";
+	/**
+	 * Accessible label for screen readers.
+	 * @default "Loading…"
+	 */
+	loadingText?: string;
+}
+
+export default function LoadingFallback({
+	contentMaxWidth = "sm",
+	loadingText = "Loading…",
+}: LoadingFallbackProps) {
+	return (
+		<div className="flex justify-center" role="status" aria-live="polite">
+			<Spinner className={spinnerVariants({ contentMaxWidth })} aria-hidden="true" />
+			<span className="sr-only">{loadingText}</span>
+		</div>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/components/SearchResultCard.tsx

@@ -0,0 +1,131 @@
+/**
+ * SearchResultCard Component
+ *
+ * Displays a single search result as a card with primary and secondary fields.
+ * Clicking the card navigates to the detail page for that record.
+ *
+ * @param record - The search result record data to display
+ * @param columns - Array of column definitions for field display
+ * @param objectApiName - API name of the object (path param in detail URL: /object/:objectApiName/:recordId)
+ *
+ * @remarks
+ * - Automatically identifies the primary field (usually "Name")
+ * - Displays up to 3 secondary fields
+ * - Supports keyboard navigation (Enter/Space to navigate)
+ * - Handles nested field values (e.g., "Owner.Alias")
+ *
+ * @example
+ * ```tsx
+ * <SearchResultCard
+ *   record={searchResult}
+ *   columns={columns}
+ *   objectApiName="Account"
+ * />
+ * ```
+ */
+import { useNavigate } from "react-router";
+import { useMemo, useCallback } from "react";
+import { Card, CardContent, CardHeader, CardTitle } from "./ui/card";
+import type { Column, SearchResultRecordData } from "../types/search/searchResults";
+import { getNestedFieldValue } from "../utils/fieldUtils";
+import ResultCardFields from "./search/ResultCardFields";
+import { OBJECT_API_NAMES } from "../constants";
+
+interface SearchResultCardProps {
+	record: SearchResultRecordData;
+	columns: Column[];
+	objectApiName?: string;
+}
+
+export default function SearchResultCard({
+	record,
+	columns,
+	objectApiName,
+}: SearchResultCardProps) {
+	const navigate = useNavigate();
+
+	if (!record || !record.id) {
+		return null;
+	}
+
+	if (!columns || !Array.isArray(columns) || columns.length === 0) {
+		return null;
+	}
+
+	if (!record.fields || typeof record.fields !== "object") {
+		return null;
+	}
+
+	const detailPath = useMemo(
+		() => `/object/${objectApiName?.trim() || OBJECT_API_NAMES[0]}/${record.id}`,
+		[record.id, objectApiName],
+	);
+
+	const handleClick = useCallback(() => {
+		if (record.id) navigate(detailPath);
+	}, [record.id, detailPath, navigate]);
+
+	const handleKeyDown = useCallback(
+		(e: React.KeyboardEvent) => {
+			if (e.key === "Enter" || e.key === " ") {
+				e.preventDefault();
+				handleClick();
+			}
+		},
+		[handleClick],
+	);
+
+	const primaryField = useMemo(() => {
+		return (
+			columns.find(
+				(col) =>
+					col &&
+					col.fieldApiName &&
+					(col.fieldApiName.toLowerCase() === "name" ||
+						col.fieldApiName.toLowerCase().includes("name")),
+			) ||
+			columns[0] ||
+			null
+		);
+	}, [columns]);
+
+	const primaryValue = useMemo(() => {
+		return primaryField && primaryField.fieldApiName
+			? getNestedFieldValue(record.fields, primaryField.fieldApiName) || "Untitled"
+			: "Untitled";
+	}, [primaryField, record.fields]);
+
+	const secondaryColumns = useMemo(() => {
+		return columns.filter(
+			(col) => col && col.fieldApiName && col.fieldApiName !== primaryField?.fieldApiName,
+		);
+	}, [columns, primaryField]);
+
+	return (
+		<Card
+			className="cursor-pointer hover:shadow-md transition-shadow focus-within:ring-2 focus-within:ring-blue-500 focus-within:ring-offset-2"
+			onClick={handleClick}
+			onKeyDown={handleKeyDown}
+			role="button"
+			tabIndex={0}
+			aria-label={`View details for ${primaryValue}`}
+			aria-describedby={`result-${record.id}-description`}
+		>
+			<CardHeader>
+				<CardTitle className="text-lg" id={`result-${record.id}-title`}>
+					{primaryValue}
+				</CardTitle>
+			</CardHeader>
+			<CardContent>
+				<div id={`result-${record.id}-description`} className="sr-only">
+					Search result: {primaryValue}
+				</div>
+				<ResultCardFields
+					record={record}
+					columns={secondaryColumns}
+					excludeFieldApiName={primaryField?.fieldApiName}
+				/>
+			</CardContent>
+		</Card>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/components/alerts/status-alert.tsx

@@ -0,0 +1,45 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { Alert, AlertDescription } from "../ui/alert";
+import { useId } from "react";
+import { AlertCircle, CheckCircle } from "lucide-react";
+
+const statusAlertVariants = cva("", {
+	variants: {
+		variant: {
+			error: "",
+			success: "",
+		},
+	},
+	defaultVariants: {
+		variant: "error",
+	},
+});
+
+interface StatusAlertProps extends VariantProps<typeof statusAlertVariants> {
+	children?: React.ReactNode;
+	/** Alert variant type. @default "error" */
+	variant?: "error" | "success";
+}
+
+/**
+ * Status alert component for displaying error or success messages.
+ * Returns null if no children are provided.
+ */
+export function StatusAlert({ children, variant = "error" }: StatusAlertProps) {
+	if (!children) return null;
+
+	const isError = variant === "error";
+	const descriptionId = useId();
+
+	return (
+		<Alert
+			variant={isError ? "destructive" : "default"}
+			className={statusAlertVariants({ variant })}
+			aria-describedby={descriptionId}
+			role={isError ? "alert" : "status"}
+		>
+			{isError ? <AlertCircle aria-hidden="true" /> : <CheckCircle aria-hidden="true" />}
+			<AlertDescription id={descriptionId}>{children}</AlertDescription>
+		</Alert>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/components/detail/DetailFields.tsx

@@ -0,0 +1,55 @@
+/**
+ * Alternative detail rendering: columns + record → label/value list.
+ *
+ * Use when you have list columns + record (e.g. from filters-derived columns + searchResults)
+ * and do not need the Layout API. The primary detail view (DetailPage) uses DetailForm
+ * via UiApiDetailForm (layout + GraphQL record).
+ *
+ * @param record - Record data to display
+ * @param columns - Column definitions (e.g. derived from getObjectListFilters)
+ */
+import type { Column, SearchResultRecordData } from "../../types/search/searchResults";
+import { getNestedFieldValue } from "../../utils/fieldUtils";
+
+interface DetailFieldsProps {
+	record: SearchResultRecordData;
+	columns: Column[];
+}
+
+function hasVisibleValue(value: string | number | boolean | null | undefined): boolean {
+	return value !== null && value !== undefined && value !== "";
+}
+
+export default function DetailFields({ record, columns }: DetailFieldsProps) {
+	const rows = columns.filter(
+		(col) =>
+			col?.fieldApiName && hasVisibleValue(getNestedFieldValue(record.fields, col.fieldApiName)),
+	);
+
+	if (columns.length > 0 && rows.length === 0) {
+		return (
+			<div role="status" className="text-sm text-muted-foreground py-4">
+				No field values to display
+			</div>
+		);
+	}
+
+	return (
+		<dl className="space-y-4" role="list">
+			{rows.map((column) => {
+				const fieldApiName = column.fieldApiName as string;
+				const displayValue = getNestedFieldValue(record.fields, fieldApiName);
+				return (
+					<div key={fieldApiName} className="border-b pb-4 last:border-0" role="listitem">
+						<div className="flex flex-col sm:flex-row sm:items-start gap-2">
+							<dt className="font-semibold text-sm text-muted-foreground min-w-[150px]">
+								{column.label || fieldApiName}:
+							</dt>
+							<dd className="text-sm text-foreground flex-1">{displayValue}</dd>
+						</div>
+					</div>
+				);
+			})}
+		</dl>
+	);
+}