@salesforce/ui-bundle-template-feature-react-authentication 1.117.2

package/dist/force-app/main/default/uiBundles/feature-react-authentication/src/features/authentication/api/userProfileApi.ts

@@ -0,0 +1,95 @@
+/**
+ * Extensible user profile fetching and updating via UI API GraphQL.
+ */
+import { createDataSDK } from "@salesforce/sdk-data";
+import { flattenGraphQLRecord } from "../utils/helpers";
+
+const USER_PROFILE_FIELDS_FULL = `
+    Id
+    FirstName @optional { value }
+    LastName @optional { value }
+    Email @optional { value }
+    Phone @optional { value }
+    Street @optional { value }
+    City @optional { value }
+    State @optional { value }
+    PostalCode @optional { value }
+    Country @optional { value }`;
+
+const USER_CONTACT_FIELDS = `
+    Id
+    ContactId @optional { value }`;
+
+function getUserProfileQuery(fields: string): string {
+	return `
+    query GetUserProfile($userId: ID) {
+        uiapi {
+            query {
+                User(where: { Id: { eq: $userId } }) {
+                    edges {
+                        node {${fields}}
+                    }
+                }
+            }
+        }
+    }`;
+}
+
+function getUserProfileMutation(fields: string): string {
+	return `
+    mutation UpdateUserProfile($input: UserUpdateInput!) {
+      uiapi {
+        UserUpdate(input: $input) {
+          Record {${fields}}
+        }
+      }
+    }`;
+}
+
+function throwOnGraphQLErrors(response: any): void {
+	if (response?.errors?.length) {
+		throw new Error(response.errors.map((e: any) => e.message).join("; "));
+	}
+}
+
+/**
+ * Fetches the user profile via GraphQL and returns a flattened record.
+ * @param userId - The Salesforce User Id.
+ * @param fields - GraphQL field selection (defaults to USER_PROFILE_FIELDS_FULL).
+ */
+export async function fetchUserProfile<T>(
+	userId: string,
+	fields: string = USER_PROFILE_FIELDS_FULL,
+): Promise<T> {
+	const data = await createDataSDK();
+	const response: any = await data.graphql?.(getUserProfileQuery(fields), {
+		userId,
+	});
+	throwOnGraphQLErrors(response);
+	return flattenGraphQLRecord<T>(response?.data?.uiapi?.query?.User?.edges?.[0]?.node);
+}
+
+/**
+ * Fetches the user's associated contact record ID via GraphQL and returns a flattened record.
+ * @param userId - The Salesforce User Id.
+ */
+export async function fetchUserContact<T>(userId: string): Promise<T> {
+	return fetchUserProfile<T>(userId, USER_CONTACT_FIELDS);
+}
+
+/**
+ * Updates the user profile via GraphQL and returns the flattened updated record.
+ * @param userId - The Salesforce User Id.
+ * @param values - The field values to update.
+ */
+export async function updateUserProfile<T>(
+	userId: string,
+	values: Record<string, unknown>,
+): Promise<T> {
+	const data = await createDataSDK();
+	const response: any = await data.graphql?.(getUserProfileMutation(USER_PROFILE_FIELDS_FULL), {
+		input: { Id: userId, User: { ...values } },
+	});
+	throwOnGraphQLErrors(response);
+	return flattenGraphQLRecord<T>(response?.data?.uiapi?.UserUpdate?.Record);
+}

package/dist/force-app/main/default/uiBundles/feature-react-authentication/src/features/authentication/authHelpers.ts

@@ -0,0 +1,73 @@
+import { AUTH_REDIRECT_PARAM } from "./authenticationConfig";
+import { z } from "zod";
+
+/** Email field validation */
+export const emailSchema = z.string().trim().email("Please enter a valid email address");
+
+/** Password field validation (minimum 8 characters) */
+export const passwordSchema = z.string().min(8, "Password must be at least 8 characters");
+
+/**
+ * Shared schema for new password + confirmation fields.
+ * Validates password length and matching confirmation.
+ */
+export const newPasswordSchema = z
+	.object({
+		newPassword: passwordSchema,
+		confirmPassword: z.string().min(1, "Please confirm your password"),
+	})
+	.refine((data) => data.newPassword === data.confirmPassword, {
+		message: "Passwords do not match",
+		path: ["confirmPassword"],
+	});
+
+/**
+ *
+ * Extracts the startUrl from URLSearchParams, defaulting to '/'.
+ *
+ * SECURITY NOTE: This function strictly validates the URL to prevent
+ * Open Redirect vulnerabilities. It allows only relative paths.
+ *
+ * @param searchParams - The URLSearchParams object from useSearchParams()
+ * @returns The start URL for post-authentication redirect
+ */
+export function getStartUrl(searchParams: URLSearchParams): string {
+	// 1. Check for the standard redirect parameter
+	const url = searchParams.get(AUTH_REDIRECT_PARAM);
+	// 2. Security Check: Validation Logic
+	if (url && isValidRedirect(url)) {
+		return url;
+	}
+	// 3. Fallback: Default to root
+	return "/";
+}
+
+/**
+ * [Dev Note] Security: Validates that the redirect URL is a relative path
+ * to prevent Open Redirect vulnerabilities.
+ *
+ * Security Checks:
+ * 1. Rejects protocol-relative URLs (//)
+ * 2. Rejects backslash usage which some browsers treat as slashes (/\)
+ * 3. Rejects control characters
+ */
+function isValidRedirect(url: string): boolean {
+	// Basic structure check
+	if (!url.startsWith("/") || url.startsWith("//")) return false;
+	// Security: Reject backslashes to prevent /\example.com bypasses
+	if (url.includes("\\")) return false;
+	// Robustness: Ensure it doesn't contain whitespace/control characters
+	if (/[^\u0021-\u00ff]/.test(url)) return false;
+	return true;
+}
+
+/**
+ * Shared response type for authentication endpoints (login/register).
+ * Success responses contain `success: true` and `redirectUrl`.
+ * Error responses contain `errors` array.
+ */
+export interface AuthResponse {
+	success?: boolean;
+	redirectUrl?: string | null;
+	errors?: string[];
+}

package/dist/force-app/main/default/uiBundles/feature-react-authentication/src/features/authentication/authenticationConfig.ts

@@ -0,0 +1,61 @@
+/**
+ * [Dev Note] Centralized configuration for Auth routes.
+ * Each route contains both the path and page title.
+ * Using constants prevents typos in route paths across the application.
+ */
+export const ROUTES = {
+	LOGIN: {
+		PATH: "/login",
+		TITLE: "Login | MyApp",
+	},
+	REGISTER: {
+		PATH: "/register",
+		TITLE: "Create Account | MyApp",
+	},
+	FORGOT_PASSWORD: {
+		PATH: "/forgot-password",
+		TITLE: "Recover Password | MyApp",
+	},
+	RESET_PASSWORD: {
+		PATH: "/reset-password",
+		TITLE: "Reset Password | MyApp",
+	},
+	PROFILE: {
+		PATH: "/profile",
+		TITLE: "My Profile | MyApp",
+	},
+	CHANGE_PASSWORD: {
+		PATH: "/change-password",
+		TITLE: "Change Password | MyApp",
+	},
+} as const;
+
+/**
+ * [Dev Note] Centralized configuration for API endpoints.
+ * These are server-side endpoints, not client-side routes.
+ */
+export const API_ROUTES = {
+	// W-21253864: Logout URL integration is not currently supported
+	LOGOUT: "/secur/logout.jsp",
+} as const;
+
+/**
+ * [Dev Note] Query parameter key used to store the return URL.
+ * e.g. /login?startUrl=/profile
+ */
+export const AUTH_REDIRECT_PARAM = "startUrl";
+
+/**
+ * Placeholder text constants for authentication form inputs.
+ */
+export const AUTH_PLACEHOLDERS = {
+	EMAIL: "asalesforce@example.com",
+	PASSWORD: "",
+	PASSWORD_CREATE: "",
+	PASSWORD_CONFIRM: "",
+	PASSWORD_NEW: "",
+	PASSWORD_NEW_CONFIRM: "",
+	FIRST_NAME: "Astro",
+	LAST_NAME: "Salesforce",
+	USERNAME: "asalesforce",
+} as const;

package/dist/force-app/main/default/uiBundles/feature-react-authentication/src/features/authentication/context/AuthContext.tsx

@@ -0,0 +1,95 @@
+import { createContext, useContext, useState, useEffect, useCallback, type ReactNode } from "react";
+import { getCurrentUser } from "@salesforce/ui-bundle/api";
+import { API_ROUTES } from "../authenticationConfig";
+
+interface User {
+	readonly id: string;
+	readonly name: string;
+}
+
+interface AuthContextType {
+	user: User | null;
+	isAuthenticated: boolean;
+	loading: boolean;
+	error: string | null;
+	checkAuth: () => Promise<void>;
+	logout: (startURL?: string) => void;
+}
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined);
+
+interface AuthProviderProps {
+	children: ReactNode;
+}
+
+export function AuthProvider({ children }: AuthProviderProps) {
+	const [user, setUser] = useState<User | null>(null);
+	const [loading, setLoading] = useState(true);
+	const [error, setError] = useState<string | null>(null);
+
+	const checkAuth = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+
+		try {
+			const userData = await getCurrentUser();
+			setUser(userData);
+		} catch (err) {
+			const errorMessage = err instanceof Error ? err.message : "Authentication failed";
+			setError(errorMessage);
+			setUser(null);
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	const logout = useCallback((startURL?: string) => {
+		// Navigate to logout URL (server-side endpoint)
+		// Use replace to prevent back button from returning to authenticated session
+		const finalLogoutUrl = startURL
+			? `${API_ROUTES.LOGOUT}?startURL=${encodeURIComponent(startURL)}`
+			: API_ROUTES.LOGOUT;
+		window.location.replace(finalLogoutUrl);
+	}, []);
+
+	useEffect(() => {
+		checkAuth();
+	}, [checkAuth]);
+
+	const value: AuthContextType = {
+		user,
+		isAuthenticated: user !== null,
+		loading,
+		error,
+		checkAuth,
+		logout,
+	};
+
+	return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+/**
+ * Hook to access the authentication context.
+ * @returns {AuthContextType} Authentication state (user, isAuthenticated, loading, error, checkAuth)
+ * @throws {Error} If used outside of an AuthProvider
+ */
+export function useAuth(): AuthContextType {
+	const context = useContext(AuthContext);
+	if (context === undefined) {
+		throw new Error("useAuth must be used within an AuthProvider");
+	}
+	return context;
+}
+
+/**
+ * Returns the current authenticated user.
+ * @returns {User} The authenticated user object
+ * @throws {Error} If not used within AuthProvider or user is not authenticated
+ */
+export function useUser(): User {
+	const context = useAuth();
+	if (!context.user) {
+		throw new Error("Authenticated context not established");
+	}
+	return context.user;
+}

package/dist/force-app/main/default/uiBundles/feature-react-authentication/src/features/authentication/footers/footer-link.tsx

@@ -0,0 +1,36 @@
+import { Link } from "react-router";
+import { cn } from "../../../lib/utils";
+
+interface FooterLinkProps extends Omit<React.ComponentProps<typeof Link>, "children"> {
+	/** Link text prefix (e.g., "Don't have an account?") */
+	text?: string;
+	/** Link label (e.g., "Sign up") */
+	linkText: string;
+}
+
+/**
+ * Footer link component.
+ */
+export function FooterLink({ text, to, linkText, className, ...props }: FooterLinkProps) {
+	return (
+		<p className={cn("w-full text-center text-sm text-muted-foreground", className)}>
+			{text && (
+				<>
+					{text}
+					{/* Robustness: Explicit space ensures formatting tools don't strip it */}
+					{"\u00A0"}
+				</>
+			)}
+			<Link
+				to={to}
+				className={cn(
+					"font-medium underline hover:text-primary transition-colors",
+					"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+				)}
+				{...props}
+			>
+				{linkText}
+			</Link>
+		</p>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-authentication/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/uiBundles/feature-react-authentication/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/uiBundles/feature-react-authentication/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: {},
+});