@salesforce/webapp-template-app-react-sample-b2x-experimental 1.79.2 → 1.80.0

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/features/authentication/forms/auth-form.tsx

@@ -0,0 +1,81 @@
+import { FieldGroup } from "../../../components/ui/field";
+import { StatusAlert } from "../../../components/alerts/status-alert";
+import { FooterLink } from "../footers/footer-link";
+import { SubmitButton } from "./submit-button";
+import { CardLayout } from "../../../components/layouts/card-layout";
+import { useFormContext } from "../hooks/form";
+import { useId } from "react";
+
+/**
+ * [Dev Note] A wrapper component that enforces consistent layout (Card) and error/success alert positioning
+ * for all authentication forms.
+ */
+interface AuthFormProps extends Omit<React.ComponentProps<"form">, "onSubmit"> {
+	title: string;
+	description: string;
+	error?: React.ReactNode;
+	success?: React.ReactNode;
+	submit: {
+		text: string;
+		loadingText?: string;
+		disabled?: boolean;
+	};
+	footer?: {
+		text?: string;
+		link: string;
+		linkText: string;
+	};
+}
+
+/**
+ * [Dev Note] Standardized Authentication Layout:
+ * Wraps the specific logic of Login/Register forms with a consistent visual frame (Card),
+ * title, and error alert placement. Extends form element props for flexibility.
+ * This ensures all auth-related pages look and behave similarly.
+ */
+export function AuthForm({
+	id: providedId,
+	title,
+	description,
+	error,
+	success,
+	children,
+	submit,
+	footer,
+	...props
+}: AuthFormProps) {
+	const form = useFormContext();
+	const generatedId = useId();
+	const id = providedId ?? generatedId;
+
+	return (
+		<CardLayout title={title} description={description}>
+			<div className="space-y-6">
+				{/* [Dev Note] Global form error alert (e.g. "Invalid Credentials") */}
+				{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>
+					<SubmitButton
+						form={id}
+						label={submit.text}
+						loadingLabel={submit.loadingText}
+						disabled={submit.disabled}
+						className="mt-6"
+					/>
+				</form>
+				{/* [Dev Note] Navigation links (e.g. "Forgot Password?") */}
+				{footer && <FooterLink text={footer.text} to={footer.link} linkText={footer.linkText} />}
+			</div>
+		</CardLayout>
+	);
+}

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/features/authentication/forms/submit-button.tsx

@@ -0,0 +1,49 @@
+import { Button } from "../../../components/ui/button";
+import { Spinner } from "../../../components/ui/spinner";
+import { cn } from "../../../lib/utils";
+import { useFormContext } from "../hooks/form";
+
+interface SubmitButtonProps extends Omit<React.ComponentProps<typeof Button>, "type"> {
+	/** 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.
+ * UX Best Practice:
+ * 1. Disables interaction immediately upon click (via isLoading) to prevent
+ * accidental double-submissions.
+ * 2. Provides immediate visual feedback (Spinner).
+ */
+export function SubmitButton({
+	label,
+	loadingLabel = "Submitting…",
+	className,
+	form: formId,
+	disabled,
+	...props
+}: SubmitButtonProps) {
+	const form = useFormContext();
+	return (
+		<form.Subscribe selector={isSubmittingSelector}>
+			{(isSubmitting: boolean) => (
+				<Button
+					type="submit"
+					form={formId}
+					className={cn("w-full", className)}
+					disabled={isSubmitting || disabled}
+					{...props}
+				>
+					{isSubmitting && <Spinner className="mr-2" aria-hidden="true" />}
+					{isSubmitting ? loadingLabel : label}
+				</Button>
+			)}
+		</form.Subscribe>
+	);
+}

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/features/authentication/hooks/form.tsx

@@ -0,0 +1,120 @@
+import { useId } from "react";
+import { createFormHookContexts, createFormHook } from "@tanstack/react-form";
+import {
+	Field,
+	FieldDescription,
+	FieldError,
+	FieldLabel,
+} from "../../../components/ui/field";
+import { Input } from "../../../components/ui/input";
+import { cn } from "../../../lib/utils";
+import { AUTH_PLACEHOLDERS } from "../authenticationConfig";
+
+// Create form hook contexts
+export const { fieldContext, formContext, useFieldContext, useFormContext } =
+	createFormHookContexts();
+
+// ============================================================================
+// Field Components
+// ============================================================================
+
+interface TextFieldProps extends Omit<
+	React.ComponentProps<typeof Input>,
+	"name" | "value" | "onBlur" | "onChange" | "aria-invalid"
+> {
+	label: string;
+	labelAction?: React.ReactNode;
+	description?: React.ReactNode;
+}
+
+function TextField({
+	label,
+	id: providedId,
+	labelAction,
+	description,
+	type = "text",
+	...props
+}: TextFieldProps) {
+	const field = useFieldContext<string>();
+	const generatedId = useId();
+	const id = providedId ?? generatedId;
+	const descriptionId = `${id}-description`;
+	const errorId = `${id}-error`;
+	const isInvalid = field.state.meta.isTouched && field.state.meta.errors.length > 0;
+
+	// Deduplicate errors by message
+	const errors = field.state.meta.errors;
+	const uniqueErrors = [...new Map(errors.map((item: any) => [item["message"], item])).values()];
+
+	return (
+		<Field data-invalid={isInvalid}>
+			<div className="flex items-center">
+				<FieldLabel htmlFor={id}>{label}</FieldLabel>
+				{labelAction && <div className="ml-auto">{labelAction}</div>}
+			</div>
+			{description && <FieldDescription id={descriptionId}>{description}</FieldDescription>}
+			<Input
+				id={id}
+				name={field.name as string}
+				type={type}
+				value={field.state.value ?? ""}
+				onBlur={field.handleBlur}
+				onChange={(e: React.ChangeEvent<HTMLInputElement>) => field.handleChange(e.target.value)}
+				aria-invalid={isInvalid}
+				aria-describedby={cn(description && descriptionId, isInvalid && errorId)}
+				{...props}
+			/>
+			{isInvalid && uniqueErrors.length > 0 && <FieldError errors={uniqueErrors} />}
+		</Field>
+	);
+}
+
+/** Password field with preset type and autocomplete */
+function PasswordField({
+	label,
+	autoComplete = "current-password",
+	placeholder = AUTH_PLACEHOLDERS.PASSWORD,
+	...props
+}: Omit<TextFieldProps, "type">) {
+	return (
+		<TextField
+			label={label}
+			type="password"
+			autoComplete={autoComplete}
+			placeholder={placeholder}
+			{...props}
+		/>
+	);
+}
+
+/** Email field with preset type and autocomplete */
+function EmailField({
+	label,
+	placeholder = AUTH_PLACEHOLDERS.EMAIL,
+	...props
+}: Omit<TextFieldProps, "type">) {
+	return (
+		<TextField
+			label={label}
+			type="email"
+			autoComplete="username"
+			placeholder={placeholder}
+			{...props}
+		/>
+	);
+}
+
+// ============================================================================
+// Create Form Hook
+// ============================================================================
+
+export const { useAppForm } = createFormHook({
+	fieldContext,
+	formContext,
+	fieldComponents: {
+		TextField,
+		PasswordField,
+		EmailField,
+	},
+	formComponents: {},
+});

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/features/authentication/hooks/useCountdownTimer.ts

@@ -0,0 +1,266 @@
+/**
+ * Custom hook for countdown timer with accessibility features
+ */
+
+import { useState, useEffect, useRef, useCallback } from "react";
+
+/**
+ * Accessibility configuration for countdown timer
+ */
+export interface CountdownTimerA11yConfig {
+	/** Announce time remaining at these specific second marks */
+	ANNOUNCE_AT_SECONDS: readonly number[];
+	/** Announce every N seconds (after initial period) */
+	ANNOUNCE_INTERVAL_SECONDS: number;
+	/** Minimum elapsed time before starting interval announcements */
+	MIN_ELAPSED_FOR_INTERVAL: number;
+}
+
+/**
+ * Return value from useCountdownTimer hook
+ */
+export interface CountdownTimerResult {
+	/** Current time remaining in seconds */
+	displayTime: number;
+	/** Formatted time string (MM:SS) */
+	formattedTime: string;
+	/** ISO 8601 duration string (e.g., PT2M15S) */
+	isoTime: string;
+	/** Accessibility announcement text for screen readers */
+	accessibilityAnnouncement: string;
+	/** Start the countdown timer */
+	start: () => void;
+	/** Stop the countdown timer */
+	stop: () => void;
+	/** Reset the countdown timer to initial time */
+	reset: () => void;
+}
+
+/**
+ * Configuration for countdown timer hook
+ */
+export interface CountdownTimerConfig {
+	/** Initial time in seconds */
+	initialTime: number;
+	/** Callback when countdown reaches 0 */
+	onExpire: () => void;
+	/** Optional accessibility configuration */
+	a11yConfig?: CountdownTimerA11yConfig;
+}
+
+/**
+ * Default accessibility configuration
+ */
+const DEFAULT_A11Y_CONFIG: CountdownTimerA11yConfig = {
+	ANNOUNCE_AT_SECONDS: [5, 1],
+	ANNOUNCE_INTERVAL_SECONDS: 10,
+	MIN_ELAPSED_FOR_INTERVAL: 10,
+};
+
+/**
+ * Format time remaining as MM:SS string
+ * Uses Intl.NumberFormat for zero-padding and internationalization
+ *
+ * @param seconds - Total seconds remaining
+ * @returns Formatted time string (e.g., "05:23")
+ */
+function formatTimeRemaining(seconds: number): string {
+	const minutes = Math.floor(seconds / 60);
+	const secs = seconds % 60;
+
+	// Use Intl.NumberFormat for zero-padding with internationalization
+	const formatter = new Intl.NumberFormat(navigator.language, {
+		minimumIntegerDigits: 2,
+		useGrouping: false,
+	});
+
+	return `${formatter.format(minutes)}:${formatter.format(secs)}`;
+}
+
+/**
+ * Format time remaining as ISO 8601 duration for ARIA
+ * Used in datetime attribute of <time> element
+ *
+ * @param seconds - Total seconds remaining
+ * @returns ISO 8601 duration string (e.g., "PT2M15S")
+ */
+function formatISODuration(seconds: number): string {
+	const minutes = Math.floor(seconds / 60);
+	const secs = seconds % 60;
+	return `PT${minutes}M${secs}S`;
+}
+
+/**
+ * Format time remaining for screen reader announcement
+ * Uses Intl.DurationFormat if available, falls back to manual formatting
+ *
+ * @param seconds - Total seconds remaining
+ * @returns Formatted announcement text (e.g., "2 minutes 15 seconds")
+ */
+function formatAccessibilityAnnouncement(seconds: number): string {
+	const minutes = Math.floor(seconds / 60);
+	const secs = seconds % 60;
+
+	// Try using Intl.DurationFormat (newer API, may not be available in all browsers)
+	if (typeof Intl !== "undefined" && "DurationFormat" in Intl) {
+		try {
+			// @ts-expect-error - DurationFormat is not yet in TypeScript lib
+			const formatter = new Intl.DurationFormat(navigator.language, { style: "long" });
+			return formatter.format({ minutes, seconds: secs });
+		} catch (e) {
+			// Fallback to manual formatting
+		}
+	}
+
+	// Manual fallback
+	const parts: string[] = [];
+	if (minutes > 0) {
+		parts.push(`${minutes} ${minutes === 1 ? "minute" : "minutes"}`);
+	}
+	if (secs > 0 || minutes === 0) {
+		parts.push(`${secs} ${secs === 1 ? "second" : "seconds"}`);
+	}
+	return parts.join(" ");
+}
+
+/**
+ * Determine if an accessibility announcement should be made at this time
+ *
+ * @param currentTime - Current countdown time in seconds
+ * @param initialTime - Initial countdown time in seconds
+ * @param config - Accessibility configuration
+ * @returns True if announcement should be made
+ */
+function shouldAnnounce(
+	currentTime: number,
+	initialTime: number,
+	config: CountdownTimerA11yConfig,
+): boolean {
+	// Announce at specific second marks (5s, 1s)
+	if (config.ANNOUNCE_AT_SECONDS.includes(currentTime)) {
+		return true;
+	}
+
+	// Calculate elapsed time
+	const elapsed = initialTime - currentTime;
+
+	// Announce every N seconds after minimum elapsed time
+	if (elapsed >= config.MIN_ELAPSED_FOR_INTERVAL) {
+		return currentTime % config.ANNOUNCE_INTERVAL_SECONDS === 0;
+	}
+
+	return false;
+}
+
+/**
+ * Custom hook for countdown timer with accessibility
+ * Decrements from initial time to 0, provides formatted output for display and ARIA
+ *
+ * @param config - Timer configuration
+ * @returns Timer state and control functions
+ *
+ * @example
+ * const timer = useCountdownTimer({
+ *   initialTime: 300, // 5 minutes
+ *   onExpire: () => handleLogout()
+ * });
+ *
+ * timer.start(); // Begin countdown
+ *
+ * <time dateTime={timer.isoTime} role="timer">
+ *   {timer.formattedTime}
+ * </time>
+ * <div role="status" aria-live="polite" className="sr-only">
+ *   {timer.accessibilityAnnouncement}
+ * </div>
+ */
+export function useCountdownTimer({
+	initialTime,
+	onExpire,
+	a11yConfig = DEFAULT_A11Y_CONFIG,
+}: CountdownTimerConfig): CountdownTimerResult {
+	const [displayTime, setDisplayTime] = useState(initialTime);
+	const [accessibilityAnnouncement, setAccessibilityAnnouncement] = useState("");
+	const [isActive, setIsActive] = useState(false);
+
+	// Use refs to avoid stale closure issues
+	const initialTimeRef = useRef(initialTime);
+	const onExpireRef = useRef(onExpire);
+	const a11yConfigRef = useRef(a11yConfig);
+	const endTimeRef = useRef<number>(0);
+	const previousTimeRef = useRef<number>(initialTime);
+
+	// Update refs when props change
+	useEffect(() => {
+		initialTimeRef.current = initialTime;
+	}, [initialTime]);
+
+	useEffect(() => {
+		onExpireRef.current = onExpire;
+	}, [onExpire]);
+
+	useEffect(() => {
+		a11yConfigRef.current = a11yConfig;
+	}, [a11yConfig]);
+
+	// Countdown effect using Date.now() for accuracy
+	useEffect(() => {
+		if (!isActive) return;
+
+		// Set the target end time when timer starts
+		endTimeRef.current = Date.now() + initialTimeRef.current * 1000;
+		previousTimeRef.current = initialTimeRef.current;
+
+		const intervalId = setInterval(() => {
+			const now = Date.now();
+			const remainingMs = endTimeRef.current - now;
+			const newTime = Math.max(0, Math.ceil(remainingMs / 1000));
+
+			setDisplayTime(newTime);
+
+			// Check if we should make an accessibility announcement
+			// Only announce when the second value changes
+			if (
+				newTime !== previousTimeRef.current &&
+				shouldAnnounce(newTime, initialTimeRef.current, a11yConfigRef.current)
+			) {
+				setAccessibilityAnnouncement(formatAccessibilityAnnouncement(newTime));
+			}
+			previousTimeRef.current = newTime;
+
+			// Check if countdown expired
+			if (newTime <= 0) {
+				clearInterval(intervalId);
+				setIsActive(false);
+				onExpireRef.current();
+			}
+		}, 100); // Check more frequently for smoother updates
+
+		return () => clearInterval(intervalId);
+	}, [isActive]);
+
+	// Control functions
+	const start = useCallback(() => {
+		setIsActive(true);
+	}, []);
+
+	const stop = useCallback(() => {
+		setIsActive(false);
+	}, []);
+
+	const reset = useCallback(() => {
+		setDisplayTime(initialTimeRef.current);
+		setIsActive(false);
+		setAccessibilityAnnouncement("");
+	}, []);
+
+	return {
+		displayTime,
+		formattedTime: formatTimeRemaining(displayTime),
+		isoTime: formatISODuration(displayTime),
+		accessibilityAnnouncement,
+		start,
+		stop,
+		reset,
+	};
+}

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/features/authentication/hooks/useRetryWithBackoff.ts

@@ -0,0 +1,109 @@
+/**
+ * Custom hook for retry logic with exponential backoff
+ */
+
+import { useState, useCallback } from "react";
+
+export interface UseRetryWithBackoffOptions {
+	/** Initial delay in milliseconds */
+	initialDelay: number;
+	/** Maximum number of retry attempts */
+	maxAttempts: number;
+	/** Maximum delay in milliseconds */
+	maxDelay: number;
+}
+
+export interface UseRetryWithBackoffResult {
+	/** Current number of retry attempts */
+	retryAttempts: number;
+	/** Current retry delay in milliseconds */
+	currentRetryDelay: number;
+	/** Whether max retry attempts have been reached */
+	maxRetriesReached: boolean;
+	/** Schedule a retry with exponential backoff, returns timeout ID for cancellation */
+	scheduleRetry: (callback: () => void) => ReturnType<typeof setTimeout> | undefined;
+	/** Reset retry state after successful operation */
+	resetRetry: () => void;
+}
+
+/**
+ * Hook for managing retry logic with exponential backoff
+ *
+ * @param options - Configuration for retry behavior
+ * @returns Retry state and control functions
+ *
+ * @example
+ * const retry = useRetryWithBackoff({
+ *   initialDelay: 2000,
+ *   maxAttempts: 10,
+ *   maxDelay: 1800000
+ * });
+ *
+ * async function fetchData() {
+ *   try {
+ *     const data = await apiCall();
+ *     retry.resetRetry();
+ *     return data;
+ *   } catch (error) {
+ *     if (retry.maxRetriesReached) {
+ *       console.error('Max retries reached');
+ *       return;
+ *     }
+ *     retry.scheduleRetry(() => fetchData());
+ *   }
+ * }
+ */
+export function useRetryWithBackoff(
+	options: UseRetryWithBackoffOptions,
+): UseRetryWithBackoffResult {
+	const { initialDelay, maxAttempts, maxDelay } = options;
+
+	const [retryAttempts, setRetryAttempts] = useState<number>(0);
+	const [currentRetryDelay, setCurrentRetryDelay] = useState<number>(initialDelay);
+
+	const maxRetriesReached = retryAttempts >= maxAttempts;
+
+	/**
+	 * Reset retry state after successful operation
+	 */
+	const resetRetry = useCallback(() => {
+		setRetryAttempts(0);
+		setCurrentRetryDelay(initialDelay);
+	}, [initialDelay]);
+
+	/**
+	 * Schedule a retry with exponential backoff
+	 * Returns the timeout ID which can be used to cancel the retry if needed
+	 */
+	const scheduleRetry = useCallback(
+		(callback: () => void) => {
+			if (retryAttempts >= maxAttempts) {
+				console.error("[useRetryWithBackoff] Max retry attempts reached");
+				return undefined;
+			}
+
+			console.warn(
+				`[useRetryWithBackoff] Retry attempt ${retryAttempts + 1}/${maxAttempts} in ${currentRetryDelay}ms`,
+			);
+
+			const timeoutId = setTimeout(() => {
+				callback();
+			}, currentRetryDelay);
+
+			setRetryAttempts((prev) => prev + 1);
+			// Double the delay for next retry, capped at maxDelay
+			setCurrentRetryDelay((prev) => Math.min(prev * 2, maxDelay));
+
+			return timeoutId;
+		},
+		[retryAttempts, currentRetryDelay, maxAttempts, maxDelay],
+	);
+
+	return {
+		retryAttempts,
+		currentRetryDelay,
+		maxRetriesReached,
+		scheduleRetry,
+		resetRetry,
+	};
+}

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/features/authentication/layout/card-skeleton.tsx

@@ -0,0 +1,38 @@
+import { CenteredPageLayout } from "./centered-page-layout";
+import { Card, CardContent, CardHeader } from "../../../components/ui/card";
+import { Skeleton } from "../../../components/ui/skeleton";
+
+interface CardSkeletonProps {
+	/**
+	 * Maximum width of the content container.
+	 * @default "sm"
+	 */
+	contentMaxWidth?: "sm" | "md" | "lg";
+	/**
+	 * Accessible label for screen readers.
+	 * @default "Loading…"
+	 */
+	loadingText?: string;
+}
+
+/**
+ * Full-page loading indicator with skeleton card placeholder.
+ */
+export function CardSkeleton({ contentMaxWidth, loadingText = "Loading…" }: CardSkeletonProps) {
+	return (
+		<CenteredPageLayout contentMaxWidth={contentMaxWidth}>
+			<div role="status" aria-live="polite">
+				<Card className="w-full">
+					<CardHeader>
+						<Skeleton className="h-4 w-2/3" />
+						<Skeleton className="h-4 w-1/2" />
+					</CardHeader>
+					<CardContent>
+						<Skeleton className="aspect-video w-full" />
+					</CardContent>
+				</Card>
+				<span className="sr-only">{loadingText}</span>
+			</div>
+		</CenteredPageLayout>
+	);
+}