@salesforce/templates 66.3.0 → 66.3.2

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/Section.tsx

@@ -0,0 +1,108 @@
+import { useState, useCallback, useEffect, useRef } from "react";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import type { ReactNode } from "react";
+
+export interface SectionProps {
+	sectionId: string;
+	titleLabel: string;
+	showHeader: boolean;
+	collapsible: boolean;
+	/** When provided, section is controlled (parent owns state). When undefined, section is uncontrolled (internal state). */
+	collapsed?: boolean;
+	onToggle?: (sectionId: string, collapsed: boolean) => void;
+	children: ReactNode;
+}
+
+/**
+ * Section block with optional heading and collapsible content. Controlled when
+ * `collapsed` is passed; uncontrolled otherwise. Accessible: aria-expanded, aria-controls, keyboard (Enter/Space).
+ */
+export function Section({
+	sectionId,
+	titleLabel,
+	showHeader,
+	collapsible,
+	collapsed: controlledCollapsed,
+	onToggle,
+	children,
+}: SectionProps) {
+	const [internalCollapsed, setInternalCollapsed] = useState(false);
+	const isControlled = controlledCollapsed !== undefined;
+	const collapsed = isControlled ? controlledCollapsed : internalCollapsed;
+
+	const warnedUncontrolledRef = useRef(false);
+	useEffect(() => {
+		if (
+			process.env.NODE_ENV === "development" &&
+			onToggle != null &&
+			!isControlled &&
+			!warnedUncontrolledRef.current
+		) {
+			warnedUncontrolledRef.current = true;
+			console.warn(
+				"[Section] onToggle is passed but collapsed is undefined; section is uncontrolled. Pass collapsed to control from parent.",
+			);
+		}
+	}, [onToggle, isControlled]);
+
+	const contentId = `section-content-${sectionId}`;
+	const headerId = `section-header-${sectionId}`;
+
+	const handleToggle = useCallback(() => {
+		const next = !collapsed;
+		if (!isControlled) setInternalCollapsed(next);
+		onToggle?.(sectionId, next);
+	}, [collapsed, isControlled, onToggle, sectionId]);
+
+	const handleKeyDown = useCallback(
+		(e: React.KeyboardEvent) => {
+			if (!collapsible) return;
+			if (e.key === "Enter" || e.key === " ") {
+				e.preventDefault();
+				handleToggle();
+			}
+		},
+		[collapsible, handleToggle],
+	);
+
+	return (
+		<section
+			className="border-b border-border last:border-b-0 pb-6 last:pb-0"
+			aria-labelledby={showHeader ? headerId : undefined}
+		>
+			{showHeader && titleLabel && (
+				<h3 id={headerId} className="text-base font-semibold text-foreground mb-4">
+					{collapsible ? (
+						<button
+							type="button"
+							className="flex items-center gap-2 w-full text-left hover:opacity-80 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 rounded"
+							onClick={handleToggle}
+							onKeyDown={handleKeyDown}
+							aria-expanded={!collapsed}
+							aria-controls={contentId}
+							aria-label={`${titleLabel}, ${collapsed ? "expand" : "collapse"} section`}
+							aria-roledescription="Section toggle"
+						>
+							{collapsed ? (
+								<ChevronRight className="h-4 w-4 shrink-0" aria-hidden />
+							) : (
+								<ChevronDown className="h-4 w-4 shrink-0" aria-hidden />
+							)}
+							<span>{titleLabel}</span>
+						</button>
+					) : (
+						<span className="block">{titleLabel}</span>
+					)}
+				</h3>
+			)}
+			<div
+				id={contentId}
+				className={showHeader && collapsible ? "mt-2" : ""}
+				aria-hidden={collapsible ? collapsed : undefined}
+				hidden={collapsible && collapsed}
+			>
+				{children}
+			</div>
+		</section>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/SectionRow.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+
+export interface SectionRowProps {
+	children: ReactNode;
+}
+
+/**
+ * One row of the detail form: definition list (dl) with two-column grid. Each child
+ * is a layout item (field cell or placeholder) from the layout API row.
+ */
+export function SectionRow({ children }: SectionRowProps) {
+	return (
+		<dl
+			className="grid grid-cols-1 sm:grid-cols-2 gap-x-8 gap-y-4 sm:gap-y-2"
+			aria-label="Row of fields"
+		>
+			{children}
+		</dl>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/UiApiDetailForm.tsx

@@ -0,0 +1,140 @@
+import { useEffect, useMemo } from "react";
+import type { LayoutResponse } from "../../types/recordDetail/recordDetail";
+import { useRecordDetailLayout } from "../../hooks/useRecordDetailLayout";
+import { toRecordDisplayNameMetadata } from "../../utils/fieldUtils";
+import { DetailForm } from "./DetailForm";
+import type { ObjectInfoResult } from "../../types/objectInfo/objectInfo";
+import type { ObjectInfoMetadata } from "../../utils/formDataTransformUtils";
+import type { ObjectInfo } from "../../utils/layoutTransformUtils";
+import type { GraphQLRecordNode } from "../../api/recordListGraphQLService";
+import { getGraphQLRecordDisplayName } from "../../utils/graphQLNodeFieldUtils";
+
+export interface UiApiDetailFormProps {
+	objectApiName: string;
+	recordId: string;
+	recordTypeId?: string | null;
+	/** When provided, skips fetching and uses this layout (controlled mode). */
+	layout?: LayoutResponse | null;
+	/** When provided with layout, skips fetching and uses this record (controlled mode). */
+	record?: GraphQLRecordNode | null;
+	/** When provided, skips fetching and uses this object metadata (controlled mode). */
+	objectMetadata?: ObjectInfoResult | null;
+	/** When true, shows a loading spinner until layout and record are ready. */
+	loadsWithSpinner?: boolean;
+	/** Reserved for future edit mode; no-op in read-only. */
+	hideFooter?: boolean;
+	/** Callback when layout and record are ready (e.g. for parent to show record title). */
+	onRecordDataUpdate?: (payload: { recordName: string; record: unknown }) => void;
+}
+
+/**
+ * Entry component for the record detail view. When layout/record are not provided,
+ * fetches them via useRecordDetailLayout. Shows optional loading spinner and renders
+ * a read-only DetailForm when ready. Mirrors LWC uiApiDetailForm (read-only).
+ *
+ * Passes objectInfo (mapped from object metadata) to DetailForm for layout transform.
+ * lookupRecords (picklist/lookup options) are not fetched in this flow; DetailForm
+ * accepts them when provided (e.g. from a future picklist API). Omit for read-only
+ * display without API-driven picklist labels.
+ */
+export function UiApiDetailForm({
+	objectApiName,
+	recordId,
+	recordTypeId = null,
+	layout: layoutProp,
+	record: recordProp,
+	objectMetadata: objectMetadataProp,
+	loadsWithSpinner = false,
+	onRecordDataUpdate,
+}: UiApiDetailFormProps) {
+	// Memoize so hook dependency doesn't change every render (avoids duplicate fetches)
+	const initialData = useMemo(
+		() =>
+			layoutProp && recordProp && objectMetadataProp
+				? {
+						layout: layoutProp,
+						record: recordProp,
+						objectMetadata: objectMetadataProp,
+					}
+				: null,
+		[layoutProp, recordProp, objectMetadataProp],
+	);
+
+	const fetched = useRecordDetailLayout({
+		objectApiName,
+		recordId,
+		recordTypeId,
+		initialData,
+	});
+
+	const layout = layoutProp ?? fetched.layout;
+	const record = recordProp ?? fetched.record;
+	const metadata = objectMetadataProp ?? fetched.objectMetadata;
+	const loading = layoutProp == null || recordProp == null ? fetched.loading : false;
+	const error = layoutProp == null || recordProp == null ? fetched.error : null;
+
+	const objectInfo: ObjectInfo | null = useMemo(() => {
+		if (!metadata?.fields) return null;
+		const apiName = typeof metadata.apiName === "string" ? metadata.apiName : undefined;
+		return {
+			apiName,
+			fields: Object.fromEntries(
+				Object.entries(metadata.fields).map(([name, f]) => [
+					name,
+					{
+						compoundFieldName: f.compoundFieldName ?? undefined,
+						dataType: f.dataType,
+					},
+				]),
+			),
+		};
+	}, [metadata]);
+
+	const isReadyToRender = Boolean(layout && record && layout.sections?.length);
+
+	const showSpinner = !isReadyToRender && loadsWithSpinner && loading;
+
+	useEffect(() => {
+		if (!record || !onRecordDataUpdate || !isReadyToRender) return;
+		onRecordDataUpdate({
+			recordName: getGraphQLRecordDisplayName(record, toRecordDisplayNameMetadata(metadata)),
+			record,
+		});
+	}, [record, metadata, onRecordDataUpdate, isReadyToRender]);
+
+	if (showSpinner) {
+		return (
+			<div
+				className="min-h-[80px] flex items-center justify-center"
+				role="status"
+				aria-live="polite"
+				aria-label="Loading record details"
+			>
+				<span className="sr-only">Loading record details</span>
+				<div
+					className="h-8 w-8 animate-spin rounded-full border-2 border-primary border-t-transparent"
+					aria-hidden
+				/>
+			</div>
+		);
+	}
+
+	if (error || !layout || !record) {
+		return null;
+	}
+
+	if (!isReadyToRender) {
+		return null;
+	}
+
+	return (
+		<DetailForm
+			layout={layout}
+			record={record}
+			metadata={metadata as ObjectInfoMetadata}
+			objectInfo={objectInfo}
+			showSectionHeaders
+			collapsibleSections
+		/>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/formatted/FieldValueDisplay.tsx

@@ -0,0 +1,73 @@
+/**
+ * Picks formatter by dataType (Address, Phone, Url, Email) or plain text. Empty values show "—" with a11y label.
+ */
+import { FormattedAddress } from "./FormattedAddress";
+import { FormattedEmail } from "./FormattedEmail";
+import { FormattedPhone } from "./FormattedPhone";
+import { FormattedText } from "./FormattedText";
+import { FormattedUrl } from "./FormattedUrl";
+
+/** Salesforce UI API dataType values that have dedicated formatters. */
+const DATA_TYPES = {
+	Address: "Address",
+	Email: "Email",
+	Phone: "Phone",
+	Url: "Url",
+} as const;
+
+/** Normalize dataType to canonical casing so "PHONE" / "phone" match Phone, etc. */
+function normalizeDataType(dataType: string | undefined): string | undefined {
+	if (dataType == null || dataType === "") return dataType;
+	const lower = dataType.toLowerCase();
+	const canonical: Record<string, string> = {
+		phone: DATA_TYPES.Phone,
+		email: DATA_TYPES.Email,
+		url: DATA_TYPES.Url,
+		address: DATA_TYPES.Address,
+	};
+	return canonical[lower] ?? dataType;
+}
+
+export interface FieldValueDisplayProps {
+	/** Resolved display value (string, number, boolean, or null). */
+	value: string | number | boolean | null | undefined;
+	/** Field dataType from object info (e.g. Phone, Email, Url, Address). */
+	dataType?: string;
+	className?: string;
+}
+
+const DEFAULT_CLASS = "text-sm text-foreground";
+const LINK_CLASS =
+	"text-sm text-foreground text-primary underline underline-offset-2 hover:opacity-80";
+
+export function FieldValueDisplay({
+	value,
+	dataType,
+	className = DEFAULT_CLASS,
+}: FieldValueDisplayProps) {
+	const str = value || null;
+
+	if (str === null) {
+		return (
+			<span className={className} aria-label="No value">
+				—
+			</span>
+		);
+	}
+
+	const linkClassName = className === DEFAULT_CLASS ? LINK_CLASS : className;
+	const normalizedType = normalizeDataType(dataType);
+
+	switch (normalizedType) {
+		case DATA_TYPES.Address:
+			return <FormattedAddress value={str as string} className={linkClassName} />;
+		case DATA_TYPES.Phone:
+			return <FormattedPhone value={str as string} className={linkClassName} />;
+		case DATA_TYPES.Url:
+			return <FormattedUrl value={str as string} className={linkClassName} />;
+		case DATA_TYPES.Email:
+			return <FormattedEmail value={str as string} className={linkClassName} />;
+		default:
+			return <FormattedText value={value} className={className} />;
+	}
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/formatted/FormattedAddress.tsx

@@ -0,0 +1,29 @@
+/** Address as link to Google Maps search. External link: target _blank, rel noopener noreferrer. */
+
+const GOOGLE_MAPS_SEARCH_BASE = "https://www.google.com/maps/search/?api=1&query=";
+
+export interface FormattedAddressProps {
+	/** Full address string (e.g. "10 Main Rd.\nNew York, NY 31349\nUSA"). */
+	value: string;
+	className?: string;
+}
+
+export function FormattedAddress({ value, className }: FormattedAddressProps) {
+	if (!value || !value.trim()) return null;
+	const url = GOOGLE_MAPS_SEARCH_BASE + encodeURIComponent(value.trim());
+	return (
+		<a
+			href={url}
+			target="_blank"
+			rel="noopener noreferrer"
+			className={className}
+			aria-label="Open address in Google Maps"
+		>
+			{value.split("\n").map((line, i) => (
+				<span key={i} className="block">
+					{line}
+				</span>
+			))}
+		</a>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/formatted/FormattedEmail.tsx

@@ -0,0 +1,17 @@
+/** Email as mailto: link. */
+
+export interface FormattedEmailProps {
+	value: string;
+	className?: string;
+}
+
+export function FormattedEmail({ value, className }: FormattedEmailProps) {
+	const str = (value || "").trim();
+	if (!str) return null;
+	const href = `mailto:${encodeURIComponent(str)}`;
+	return (
+		<a href={href} className={className} aria-label={`Email ${str}`}>
+			{str}
+		</a>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/formatted/FormattedPhone.tsx

@@ -0,0 +1,24 @@
+/** Phone value as tel: link for dialer/VoIP. */
+
+export interface FormattedPhoneProps {
+	value: string;
+	className?: string;
+}
+
+/** Normalizes value for tel: (digits and + only). */
+function telHref(value: string): string {
+	const cleaned = value.replace(/[^\d+]/g, "");
+	return cleaned ? `tel:${cleaned}` : "#";
+}
+
+export function FormattedPhone({ value, className }: FormattedPhoneProps) {
+	if (!value) return null;
+	const trimmed = (value || "").trim();
+	const href = telHref(trimmed);
+	if (href === "#") return <span className={className}>{trimmed}</span>;
+	return (
+		<a href={href} className={className} aria-label={`Call ${trimmed}`}>
+			{trimmed}
+		</a>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/formatted/FormattedText.tsx

@@ -0,0 +1,11 @@
+/** Plain-text field value when dataType has no dedicated formatter. */
+
+export interface FormattedTextProps {
+	value: string | number | boolean | null | undefined;
+	className?: string;
+}
+
+export function FormattedText({ value, className }: FormattedTextProps) {
+	if (!value) return null;
+	return <span className={className}>{value as string}</span>;
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/formatted/FormattedUrl.tsx

@@ -0,0 +1,29 @@
+/** URL as external link (new tab, noopener noreferrer). Falls back to plain text if not http(s). */
+
+import { isAllowedLinkUrl } from "../../../utils/linkUtils";
+
+export interface FormattedUrlProps {
+	value: string;
+	className?: string;
+	/** Optional display text; defaults to the URL. */
+	displayText?: string;
+}
+
+export function FormattedUrl({ value, className, displayText }: FormattedUrlProps) {
+	const str = (value || "").trim();
+	if (!str) return null;
+	const href = str.startsWith("http://") || str.startsWith("https://") ? str : `https://${str}`;
+	if (!isAllowedLinkUrl(href)) return <span className={className}>{str}</span>;
+	const label = displayText ?? str;
+	return (
+		<a
+			href={href}
+			target="_blank"
+			rel="noopener noreferrer"
+			className={className}
+			aria-label={`Open link in new tab: ${label}`}
+		>
+			{label}
+		</a>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/detail/formatted/index.ts

@@ -0,0 +1,6 @@
+export { FieldValueDisplay } from "./FieldValueDisplay";
+export { FormattedAddress } from "./FormattedAddress";
+export { FormattedEmail } from "./FormattedEmail";
+export { FormattedPhone } from "./FormattedPhone";
+export { FormattedText } from "./FormattedText";
+export { FormattedUrl } from "./FormattedUrl";

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/filters/FilterField.tsx

@@ -0,0 +1,54 @@
+/**
+ * FilterField Component
+ *
+ * Wrapper component that renders the appropriate filter input type based on filter affordance.
+ * Routes to FilterInput for text fields or FilterSelect for picklist fields.
+ *
+ * @param filter - Filter definition containing field path, label, and affordance
+ * @param value - Current filter value
+ * @param picklistValues - Array of picklist options (for select fields)
+ * @param onChange - Callback when filter value changes
+ *
+ * @remarks
+ * - Automatically determines input type from filter.affordance
+ * - Returns null if filter is invalid
+ * - Defaults to text input if affordance is not 'select'
+ *
+ * @example
+ * ```tsx
+ * <FilterField
+ *   filter={filter}
+ *   value={filterValue}
+ *   picklistValues={picklistOptions}
+ *   onChange={(value) => setFilterValue(value)}
+ * />
+ * ```
+ */
+import FilterInput from "./FilterInput";
+import FilterSelect from "./FilterSelect";
+import type { Filter } from "../../types/filters/filters";
+import type { PicklistValue } from "../../types/filters/picklist";
+
+interface FilterFieldProps {
+	filter: Filter;
+	value: string;
+	picklistValues: PicklistValue[];
+	onChange: (value: string) => void;
+}
+
+export default function FilterField({ filter, value, picklistValues, onChange }: FilterFieldProps) {
+	// Guard against invalid filter objects
+	if (!filter || !filter.targetFieldPath) {
+		return null;
+	}
+
+	const affordance = filter.affordance?.toLowerCase() || "";
+
+	if (affordance === "select") {
+		const options = picklistValues || [];
+		return <FilterSelect filter={filter} value={value} options={options} onChange={onChange} />;
+	}
+
+	// Default to text input
+	return <FilterInput filter={filter} value={value} onChange={onChange} />;
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/filters/FilterInput.tsx

@@ -0,0 +1,55 @@
+/**
+ * FilterInput Component
+ *
+ * Renders a text input field for filter values.
+ * Used for filters that don't have a picklist (affordance !== 'select').
+ *
+ * @param filter - Filter definition containing field path, label, and attributes
+ * @param value - Current filter input value
+ * @param onChange - Callback when input value changes
+ *
+ * @remarks
+ * - Displays filter label or field path as the label
+ * - Shows placeholder text from filter attributes or generates default
+ * - Displays help message if available
+ *
+ * @example
+ * ```tsx
+ * <FilterInput
+ *   filter={textFilter}
+ *   value={filterValue}
+ *   onChange={(value) => setFilterValue(value)}
+ * />
+ * ```
+ */
+import { Input } from "../../../../components/ui/input";
+import { Field, FieldLabel, FieldDescription } from "../../../../components/ui/field";
+import type { Filter } from "../../types/filters/filters";
+
+interface FilterInputProps {
+	filter: Filter;
+	value: string;
+	onChange: (value: string) => void;
+}
+
+export default function FilterInput({ filter, value, onChange }: FilterInputProps) {
+	return (
+		<Field>
+			<FieldLabel htmlFor={filter.targetFieldPath}>
+				{filter.label || filter.targetFieldPath}
+			</FieldLabel>
+			<Input
+				id={filter.targetFieldPath}
+				type="text"
+				value={value}
+				onChange={(e: React.ChangeEvent<HTMLInputElement>) => onChange(e.target.value)}
+				placeholder={
+					filter.attributes?.placeholder ||
+					`Enter ${(filter.label || filter.targetFieldPath).toLowerCase()}`
+				}
+				aria-label={filter.label || filter.targetFieldPath}
+			/>
+			{filter.helpMessage && <FieldDescription>{filter.helpMessage}</FieldDescription>}
+		</Field>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search/components/filters/FilterSelect.tsx

@@ -0,0 +1,72 @@
+/**
+ * FilterSelect Component
+ *
+ * Renders a dropdown select field for filter values with picklist options.
+ * Used for filters with affordance === 'select'.
+ *
+ * @param filter - Filter definition containing field path, label, and attributes
+ * @param value - Currently selected filter value
+ * @param options - Array of picklist values to display as options
+ * @param onChange - Callback when selection changes
+ *
+ * @remarks
+ * - Filters out invalid options (null/undefined values)
+ * - Displays option label if available, otherwise uses value
+ * - Shows placeholder from filter attributes or default "Select..."
+ *
+ * @example
+ * ```tsx
+ * <FilterSelect
+ *   filter={selectFilter}
+ *   value={selectedValue}
+ *   options={picklistOptions}
+ *   onChange={(value) => setSelectedValue(value)}
+ * />
+ * ```
+ */
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../components/ui/select";
+import { Field, FieldLabel, FieldDescription } from "../../../../components/ui/field";
+import type { Filter } from "../../types/filters/filters";
+import type { PicklistValue } from "../../types/filters/picklist";
+
+interface FilterSelectProps {
+	filter: Filter;
+	value: string;
+	options: PicklistValue[];
+	onChange: (value: string) => void;
+}
+
+export default function FilterSelect({ filter, value, options, onChange }: FilterSelectProps) {
+	return (
+		<Field>
+			<FieldLabel htmlFor={filter.targetFieldPath}>
+				{filter.label || filter.targetFieldPath}
+			</FieldLabel>
+			<Select value={value} onValueChange={onChange}>
+				<SelectTrigger
+					id={filter.targetFieldPath}
+					aria-label={filter.label || filter.targetFieldPath}
+				>
+					<SelectValue placeholder={filter.attributes?.placeholder || "Select..."} />
+				</SelectTrigger>
+				<SelectContent>
+					{options.map((option) => {
+						if (!option || !option.value) return null;
+						return (
+							<SelectItem key={option.value} value={option.value}>
+								{option.label || option.value}
+							</SelectItem>
+						);
+					})}
+				</SelectContent>
+			</Select>
+			{filter.helpMessage && <FieldDescription>{filter.helpMessage}</FieldDescription>}
+		</Field>
+	);
+}