@salesforce/templates 66.1.1 → 66.2.1

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/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/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/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/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/layouts/AuthAppLayout.tsx

@@ -0,0 +1,12 @@
+import SessionTimeoutValidator from "../components/auth/sessionTimeout/SessionTimeoutValidator";
+import { AuthProvider } from "../context/AuthContext";
+import AppLayout from "../appLayout";
+
+export default function AuthAppLayout() {
+	return (
+		<AuthProvider>
+			<SessionTimeoutValidator basePath="" />
+			<AppLayout />
+		</AuthProvider>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/lib/data-sdk.ts

@@ -0,0 +1,21 @@
+import { createDataSDK, type DataSDK } from "@salesforce/sdk-data";
+
+type FetchableSDK = DataSDK & { fetch: typeof fetch };
+
+let sdkPromise: Promise<FetchableSDK> | null = null;
+
+/**
+ * Returns a singleton DataSDK instance with a guaranteed fetch method.
+ * Lazily initialized on first call; subsequent calls return the same instance.
+ */
+export function getDataSDK(): Promise<FetchableSDK> {
+	if (!sdkPromise) {
+		sdkPromise = createDataSDK().then((sdk) => {
+			if (!sdk.fetch) {
+				throw new Error("DataSDK fetch is not available on this surface.");
+			}
+			return sdk as FetchableSDK;
+		});
+	}
+	return sdkPromise;
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/navigationMenu.tsx

@@ -0,0 +1,80 @@
+import { Link, useLocation } from 'react-router';
+import { getAllRoutes } from './router-utils';
+import { useState } from 'react';
+
+export default function NavigationMenu() {
+  const [isOpen, setIsOpen] = useState(false);
+  const location = useLocation();
+
+  const isActive = (path: string) => location.pathname === path;
+
+  const toggleMenu = () => setIsOpen(!isOpen);
+
+  const navigationRoutes: { path: string; label: string }[] = getAllRoutes()
+    .filter(
+      route =>
+        route.handle?.showInNavigation === true &&
+        route.fullPath !== undefined &&
+        route.handle?.label !== undefined
+    )
+    .map(
+      route =>
+        ({
+          path: route.fullPath,
+          label: route.handle?.label,
+        }) as { path: string; label: string }
+    );
+
+  return (
+    <nav className="bg-white border-b border-gray-200">
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="flex justify-between items-center h-16">
+          <Link to="/" className="text-xl font-semibold text-gray-900">
+            React App
+          </Link>
+          <button
+            onClick={toggleMenu}
+            className="p-2 rounded-md text-gray-700 hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500"
+            aria-label="Toggle menu"
+          >
+            <div className="w-6 h-6 flex flex-col justify-center space-y-1.5">
+              <span
+                className={`block h-0.5 w-6 bg-current transition-all ${
+                  isOpen ? 'rotate-45 translate-y-2' : ''
+                }`}
+              />
+              <span
+                className={`block h-0.5 w-6 bg-current transition-all ${isOpen ? 'opacity-0' : ''}`}
+              />
+              <span
+                className={`block h-0.5 w-6 bg-current transition-all ${
+                  isOpen ? '-rotate-45 -translate-y-2' : ''
+                }`}
+              />
+            </div>
+          </button>
+        </div>
+        {isOpen && (
+          <div className="pb-4">
+            <div className="flex flex-col space-y-2">
+              {navigationRoutes.map(item => (
+                <Link
+                  key={item.path}
+                  to={item.path}
+                  onClick={() => setIsOpen(false)}
+                  className={`px-3 py-2 rounded-md text-sm font-medium transition-colors ${
+                    isActive(item.path)
+                      ? 'bg-blue-100 text-blue-700'
+                      : 'text-gray-700 hover:bg-gray-100'
+                  }`}
+                >
+                  {item.label}
+                </Link>
+              ))}
+            </div>
+          </div>
+        )}
+      </div>
+    </nav>
+  );
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/pages/ChangePassword.tsx

@@ -0,0 +1,107 @@
+import { useState } from "react";
+import { Link } from "react-router";
+import { z } from "zod";
+import { CenteredPageLayout } from "../components/layout/centered-page-layout";
+import { AuthForm } from "../components/forms/auth-form";
+import { useAppForm } from "../hooks/form";
+import { getDataSDK } from "../lib/data-sdk";
+import { ROUTES, AUTH_PLACEHOLDERS } from "../components/auth/authenticationConfig";
+import { newPasswordSchema } from "../components/auth/authHelpers";
+import { handleApiResponse, getErrorMessage } from "../utils/helpers";
+
+const changePasswordSchema = z
+	.object({
+		currentPassword: z.string().min(1, "Current password is required"),
+	})
+	.and(newPasswordSchema);
+
+export default function ChangePassword() {
+	const [success, setSuccess] = useState(false);
+	const [submitError, setSubmitError] = useState<string | null>(null);
+
+	const form = useAppForm({
+		defaultValues: { currentPassword: "", newPassword: "", confirmPassword: "" },
+		validators: { onChange: changePasswordSchema, onSubmit: changePasswordSchema },
+		onSubmit: async ({ value: formFieldValues }) => {
+			setSubmitError(null);
+			setSuccess(false);
+			try {
+				// [Dev Note] Custom Apex Endpoint: /auth/change-password
+				// You must ensure this Apex class exists in your org
+				const sdk = await getDataSDK();
+				const response = await sdk.fetch("/sfdcapi/services/apexrest/auth/change-password", {
+					method: "POST",
+					body: JSON.stringify({
+						currentPassword: formFieldValues.currentPassword,
+						newPassword: formFieldValues.newPassword,
+					}),
+					headers: {
+						"Content-Type": "application/json",
+						Accept: "application/json",
+					},
+				});
+				await handleApiResponse(response, "Password change failed");
+				setSuccess(true);
+				form.reset();
+			} catch (err) {
+				setSubmitError(getErrorMessage(err, "Password change failed"));
+			}
+		},
+		onSubmitInvalid: () => {},
+	});
+
+	return (
+		<CenteredPageLayout title={ROUTES.CHANGE_PASSWORD.TITLE}>
+			<form.AppForm>
+				<AuthForm
+					title="Change Password"
+					description="Enter your current and new password below"
+					error={submitError}
+					success={
+						success && (
+							<>
+								Password changed successfully!{" "}
+								<Link to={ROUTES.PROFILE.PATH} className="underline">
+									Back to Profile
+								</Link>
+							</>
+						)
+					}
+					submit={{ text: "Change Password", loadingText: "Changing…", disabled: success }}
+					footer={{ link: ROUTES.PROFILE.PATH, linkText: "Back to Profile" }}
+				>
+					<form.AppField name="currentPassword">
+						{(field) => (
+							<field.PasswordField
+								label="Current Password"
+								placeholder={AUTH_PLACEHOLDERS.PASSWORD}
+								autoComplete="current-password"
+								disabled={success}
+							/>
+						)}
+					</form.AppField>
+					<form.AppField name="newPassword">
+						{(field) => (
+							<field.PasswordField
+								label="New Password"
+								placeholder={AUTH_PLACEHOLDERS.PASSWORD_NEW}
+								autoComplete="new-password"
+								disabled={success}
+							/>
+						)}
+					</form.AppField>
+					<form.AppField name="confirmPassword">
+						{(field) => (
+							<field.PasswordField
+								label="Confirm Password"
+								placeholder={AUTH_PLACEHOLDERS.PASSWORD_NEW_CONFIRM}
+								autoComplete="new-password"
+								disabled={success}
+							/>
+						)}
+					</form.AppField>
+				</AuthForm>
+			</form.AppForm>
+		</CenteredPageLayout>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/pages/ForgotPassword.tsx

@@ -0,0 +1,73 @@
+import { useState } from "react";
+import { z } from "zod";
+import { CenteredPageLayout } from "../components/layout/centered-page-layout";
+import { AuthForm } from "../components/forms/auth-form";
+import { useAppForm } from "../hooks/form";
+import { getDataSDK } from "../lib/data-sdk";
+import { ROUTES, AUTH_PLACEHOLDERS } from "../components/auth/authenticationConfig";
+import { handleApiResponse, getErrorMessage } from "../utils/helpers";
+
+const forgotPasswordSchema = z.object({
+	username: z.string().trim().toLowerCase().email("Please enter a valid username"),
+});
+
+export default function ForgotPassword() {
+	const [success, setSuccess] = useState(false);
+	const [submitError, setSubmitError] = useState<string | null>(null);
+
+	const form = useAppForm({
+		defaultValues: { username: "" },
+		validators: { onChange: forgotPasswordSchema, onSubmit: forgotPasswordSchema },
+		onSubmit: async ({ value }) => {
+			setSubmitError(null);
+			setSuccess(false);
+			try {
+				// [Dev Note] Custom Apex Endpoint: /auth/forgot-password
+				// You must ensure this Apex class exists in your org
+				const sdk = await getDataSDK();
+				const response = await sdk.fetch("/sfdcapi/services/apexrest/auth/forgot-password", {
+					method: "POST",
+					body: JSON.stringify({ username: value.username.trim() }),
+					headers: {
+						"Content-Type": "application/json",
+						Accept: "application/json",
+					},
+				});
+				await handleApiResponse(response, "Failed to send reset link");
+				setSuccess(true);
+			} catch (err) {
+				setSubmitError(getErrorMessage(err, "Failed to send reset link"));
+			}
+		},
+		onSubmitInvalid: () => {},
+	});
+
+	return (
+		<CenteredPageLayout title={ROUTES.FORGOT_PASSWORD.TITLE}>
+			<form.AppForm>
+				<AuthForm
+					title="Forgot Password"
+					description="Enter your username and we'll send you a reset link"
+					error={submitError}
+					success={
+						success &&
+						"If that username exists in our system, you will receive a reset link shortly."
+					}
+					submit={{ text: "Send Reset Link", loadingText: "Sending…", disabled: success }}
+					footer={{ text: "Remember your password?", link: ROUTES.LOGIN.PATH, linkText: "Sign in" }}
+				>
+					<form.AppField name="username">
+						{(field) => (
+							<field.TextField
+								label="Username"
+								placeholder={AUTH_PLACEHOLDERS.USERNAME}
+								autoComplete="username"
+								disabled={success}
+							/>
+						)}
+					</form.AppField>
+				</AuthForm>
+			</form.AppForm>
+		</CenteredPageLayout>
+	);
+}

package/lib/templates/project/reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/pages/Home.tsx

@@ -0,0 +1,12 @@
+export default function Home() {
+  return (
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold text-gray-900 mb-4">Home</h1>
+        <p className="text-lg text-gray-600 mb-8">
+          Welcome to your React application.
+        </p>
+      </div>
+    </div>
+  );
+}