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

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/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/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/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/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/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/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/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 "../ui/input";
+import { Field, FieldLabel, FieldDescription } from "../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/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/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 "../ui/select";
+import { Field, FieldLabel, FieldDescription } from "../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>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/components/forms/filters-form.tsx

@@ -0,0 +1,114 @@
+import { FieldGroup } from "../ui/field";
+import { StatusAlert } from "../alerts/status-alert";
+import { CardLayout } from "../layout/card-layout";
+import { SubmitButton } from "./submit-button";
+import { Button } from "../ui/button";
+import { useFormContext } from "../../hooks/form";
+import { useId, useEffect, useRef } from "react";
+
+const SUCCESS_AUTO_DISMISS_DELAY = 3000;
+
+interface FiltersFormProps extends Omit<React.ComponentProps<"form">, "onSubmit"> {
+	title: string;
+	description?: string;
+	error?: React.ReactNode;
+	success?: React.ReactNode;
+	submit: {
+		text: string;
+		loadingText?: string;
+	};
+	reset?: {
+		text: string;
+		onReset: () => void;
+	};
+	onSuccessDismiss?: () => void;
+}
+
+/**
+ * Wrapper component that provides consistent layout and error/success alert positioning
+ * for all filter forms.
+ */
+export function FiltersForm({
+	id: providedId,
+	title,
+	description,
+	error,
+	success,
+	children,
+	submit,
+	reset,
+	onSuccessDismiss,
+	...props
+}: FiltersFormProps) {
+	const form = useFormContext();
+	const generatedId = useId();
+	const id = providedId ?? generatedId;
+
+	const isSubmittingSelector = (state: { isSubmitting: boolean }) => state.isSubmitting;
+	const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	useEffect(() => {
+		if (timeoutRef.current) {
+			clearTimeout(timeoutRef.current);
+			timeoutRef.current = null;
+		}
+
+		if (success && onSuccessDismiss) {
+			timeoutRef.current = setTimeout(() => {
+				onSuccessDismiss();
+				timeoutRef.current = null;
+			}, SUCCESS_AUTO_DISMISS_DELAY);
+		}
+
+		return () => {
+			if (timeoutRef.current) {
+				clearTimeout(timeoutRef.current);
+				timeoutRef.current = null;
+			}
+		};
+	}, [success, onSuccessDismiss]);
+
+	return (
+		<CardLayout title={title} description={description}>
+			<div className="space-y-6">
+				{error && <StatusAlert variant="error">{error}</StatusAlert>}
+				{success && <StatusAlert variant="success">{success}</StatusAlert>}
+
+				<form
+					id={id}
+					onSubmit={(e) => {
+						e.preventDefault();
+						e.stopPropagation();
+						form.handleSubmit();
+					}}
+					{...props}
+				>
+					<FieldGroup>{children}</FieldGroup>
+					<div className="flex flex-col sm:flex-row gap-2 pt-4">
+						<SubmitButton
+							form={id}
+							label={submit.text}
+							loadingLabel={submit.loadingText}
+							className="flex-1"
+						/>
+						{reset && (
+							<form.Subscribe selector={isSubmittingSelector}>
+								{(isSubmitting: boolean) => (
+									<Button
+										type="button"
+										variant="outline"
+										onClick={reset.onReset}
+										className="flex-1"
+										disabled={isSubmitting}
+									>
+										{reset.text}
+									</Button>
+								)}
+							</form.Subscribe>
+						)}
+					</div>
+				</form>
+			</div>
+		</CardLayout>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/components/forms/submit-button.tsx

@@ -0,0 +1,47 @@
+import { Button } from "../ui/button";
+import { Spinner } from "../ui/spinner";
+import { cn } from "../../lib/utils";
+import { useFormContext } from "../../hooks/form";
+
+interface SubmitButtonProps extends Omit<React.ComponentProps<typeof Button>, "type" | "disabled"> {
+	/** Button text when not submitting */
+	label: string;
+	/** Button text while submitting */
+	loadingLabel?: string;
+	/** Form id to associate with (for buttons outside form element) */
+	form?: string;
+}
+
+const isSubmittingSelector = (state: { isSubmitting: boolean }) => state.isSubmitting;
+
+/**
+ * Submit button that subscribes to form submission state.
+ * Disables interaction during submission and provides visual feedback.
+ */
+export function SubmitButton({
+	label,
+	loadingLabel = "Applying…",
+	className,
+	form: formId,
+	...props
+}: SubmitButtonProps) {
+	const form = useFormContext();
+	return (
+		<form.Subscribe selector={isSubmittingSelector}>
+			{(isSubmitting: boolean) => (
+				<Button
+					type="submit"
+					form={formId}
+					className={cn("w-full", className)}
+					disabled={isSubmitting}
+					aria-label={isSubmitting ? loadingLabel : label}
+					aria-busy={isSubmitting}
+					{...props}
+				>
+					{isSubmitting && <Spinner className="mr-2" aria-hidden="true" />}
+					<span aria-live="polite">{isSubmitting ? loadingLabel : label}</span>
+				</Button>
+			)}
+		</form.Subscribe>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/components/layout/card-layout.tsx

@@ -0,0 +1,19 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "../ui/card";
+
+interface CardLayoutProps {
+	title: string;
+	description?: string;
+	children: React.ReactNode;
+}
+
+export function CardLayout({ title, description, children }: CardLayoutProps) {
+	return (
+		<Card className="w-full">
+			<CardHeader>
+				<CardTitle className="text-2xl">{title}</CardTitle>
+				{description && <CardDescription>{description}</CardDescription>}
+			</CardHeader>
+			<CardContent>{children}</CardContent>
+		</Card>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/components/search/ResultCardFields.tsx

@@ -0,0 +1,71 @@
+/**
+ * ResultCardFields Component
+ *
+ * Displays secondary fields (up to 3) for a search result card.
+ * Excludes the primary field and handles nested field values.
+ *
+ * @param record - The search result record data
+ * @param columns - Array of column definitions
+ * @param excludeFieldApiName - Field API name to exclude (usually the primary field)
+ *
+ * @remarks
+ * - Displays up to 3 secondary fields
+ * - Handles nested field paths (e.g., "Owner.Alias")
+ * - Skips fields with null/undefined/empty values
+ * - Responsive layout (vertical on mobile, horizontal on desktop)
+ *
+ * @example
+ * ```tsx
+ * <ResultCardFields
+ *   record={searchResult}
+ *   columns={columns}
+ *   excludeFieldApiName="Name"
+ * />
+ * ```
+ */
+import type { Column, SearchResultRecordData } from "../../types/search/searchResults";
+import { getNestedFieldValue } from "../../utils/fieldUtils";
+
+interface ResultCardFieldsProps {
+	record: SearchResultRecordData;
+	columns: Column[];
+	excludeFieldApiName?: string;
+}
+
+export default function ResultCardFields({
+	record,
+	columns,
+	excludeFieldApiName,
+}: ResultCardFieldsProps) {
+	const secondaryFields = columns.filter(
+		(col) => col && col.fieldApiName && col.fieldApiName !== excludeFieldApiName,
+	);
+
+	return (
+		<dl className="space-y-2" aria-label="Additional record information">
+			{secondaryFields.map((column) => {
+				if (!column || !column.fieldApiName) {
+					return null;
+				}
+
+				const displayValue = getNestedFieldValue(record.fields, column.fieldApiName);
+
+				if (displayValue === null || displayValue === undefined || displayValue === "") {
+					return null;
+				}
+
+				return (
+					<div
+						key={column.fieldApiName}
+						className="flex flex-col sm:flex-row sm:items-center gap-1 sm:gap-2"
+					>
+						<dt className="text-sm font-medium text-muted-foreground min-w-[100px]">
+							{column.label || column.fieldApiName}:
+						</dt>
+						<dd className="text-sm text-foreground">{displayValue}</dd>
+					</div>
+				);
+			})}
+		</dl>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/components/search/SearchHeader.tsx

@@ -0,0 +1,31 @@
+/**
+ * SearchHeader Component
+ *
+ * Displays the header for search results or browse-all (same UI).
+ * labelPlural comes from object metadata (e.g. useObjectInfoBatch) so it is not hard-coded.
+ */
+interface SearchHeaderProps {
+	query?: string;
+	isBrowseAll?: boolean;
+	/** Plural label for the primary object (e.g. "Accounts"). From object metadata. */
+	labelPlural?: string;
+}
+
+export default function SearchHeader({
+	query,
+	isBrowseAll,
+	labelPlural = "records",
+}: SearchHeaderProps) {
+	return (
+		<header className="mb-6" aria-label="Search results header">
+			<h1 className="text-3xl font-bold mb-2">
+				{isBrowseAll ? `Browse All ${labelPlural}` : "Search Results"}
+			</h1>
+			{!isBrowseAll && query && (
+				<p className="text-lg" aria-live="polite">
+					Results for: <span className="font-semibold">"{query}"</span>
+				</p>
+			)}
+		</header>
+	);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/src/components/search/SearchPagination.tsx

@@ -0,0 +1,144 @@
+/**
+ * SearchPagination Component
+ *
+ * Displays pagination controls for search results.
+ * Previous/Next are disabled using hasPreviousPage/hasNextPage from the API so no request is made when there is no page.
+ *
+ * @remarks
+ * - Layout: page size selector on the left, prev/page/next controls on the right (corners).
+ * - Previous disabled when !hasPreviousPage (cursor stack enables prev when pageIndex > 0).
+ * - Next disabled when !hasNextPage or nextPageToken is null.
+ */
+import { Button } from "../ui/button";
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../ui/select";
+import { Label } from "../ui/label";
+import { PAGE_SIZE_OPTIONS, getValidPageSize, isValidPageSize } from "../../utils/paginationUtils";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+interface SearchPaginationProps {
+	currentPageToken: string;
+	nextPageToken: string | null;
+	previousPageToken: string | null;
+	hasNextPage?: boolean;
+	hasPreviousPage?: boolean;
+	pageSize: number;
+	/** direction: 'prev' | 'next' | 'first'. When 'first' (e.g. page size change), parent typically resets pagination; token may be '' for prev when going to page 0. */
+	onPageChange: (newPageToken: string, direction?: "next" | "prev" | "first") => void;
+	onPageSizeChange: (newPageSize: number) => void;
+}
+
+export default function SearchPagination({
+	currentPageToken,
+	nextPageToken,
+	previousPageToken,
+	hasNextPage = false,
+	hasPreviousPage = false,
+	pageSize,
+	onPageChange,
+	onPageSizeChange,
+}: SearchPaginationProps) {
+	const validPageSize = getValidPageSize(pageSize);
+
+	const currentPageTokenNum = parseInt(currentPageToken, 10) || 0;
+	const currentPage = currentPageTokenNum + 1;
+
+	const canGoPrevious = Boolean(hasPreviousPage);
+	const canGoNext = Boolean(hasNextPage && nextPageToken != null);
+
+	const handlePrevious = () => {
+		if (canGoPrevious) {
+			onPageChange(previousPageToken ?? "", "prev");
+		}
+	};
+
+	const handleNext = () => {
+		if (canGoNext && nextPageToken != null) {
+			onPageChange(nextPageToken, "next");
+		}
+	};
+
+	const handlePageSizeChange = (newPageSize: string) => {
+		const newSize = parseInt(newPageSize, 10);
+		if (!isNaN(newSize) && isValidPageSize(newSize) && newSize !== validPageSize) {
+			onPageSizeChange(newSize);
+			onPageChange("0", "first");
+		}
+	};
+
+	return (
+		<nav
+			className="w-full flex flex-row flex-wrap items-center justify-between gap-4 py-2"
+			aria-label="Search results pagination"
+		>
+			<div
+				className="flex items-center gap-2 shrink-0"
+				role="group"
+				aria-label="Page size selector"
+			>
+				<Label htmlFor="page-size-select" className="text-sm font-normal whitespace-nowrap">
+					Results per page:
+				</Label>
+				<Select value={validPageSize.toString()} onValueChange={handlePageSizeChange}>
+					<SelectTrigger
+						id="page-size-select"
+						className="w-[70px]"
+						aria-label="Select number of results per page"
+					>
+						<SelectValue />
+					</SelectTrigger>
+					<SelectContent>
+						{PAGE_SIZE_OPTIONS.map((option) => (
+							<SelectItem key={option.value} value={option.value}>
+								{option.label}
+							</SelectItem>
+						))}
+					</SelectContent>
+				</Select>
+			</div>
+
+			<div className="flex items-center gap-1 shrink-0" role="group" aria-label="Page navigation">
+				<Button
+					type="button"
+					variant="outline"
+					size="sm"
+					disabled={!canGoPrevious}
+					onClick={handlePrevious}
+					aria-label={
+						canGoPrevious
+							? `Go to previous page (Page ${currentPage - 1})`
+							: "Previous page (disabled)"
+					}
+				>
+					<ChevronLeft className="size-4" aria-hidden />
+					Previous
+				</Button>
+				<span
+					className="min-w-[4rem] text-center text-sm text-muted-foreground px-2"
+					aria-label={`Page ${currentPage}, current page`}
+					aria-current="page"
+				>
+					Page {currentPage}
+				</span>
+				<Button
+					type="button"
+					variant="outline"
+					size="sm"
+					disabled={!canGoNext}
+					onClick={handleNext}
+					aria-label={
+						canGoNext ? `Go to next page (Page ${currentPage + 1})` : "Next page (disabled)"
+					}
+				>
+					Next
+					<ChevronRight className="size-4" aria-hidden />
+				</Button>
+			</div>
+		</nav>
+	);
+}