@salesforce/templates 66.1.0 → 66.2.0

package/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/auth/sessionTimeout/sessionTimeService.ts

@@ -0,0 +1,161 @@
+/**
+ * SessionTimeServlet API service
+ * Handles communication with the session validation endpoint
+ */
+
+import { SESSION_CONFIG } from "./sessionTimeoutConfig";
+
+/**
+ * Response from SessionTimeServlet API
+ */
+export interface SessionResponse {
+	/** Session phase */
+	sp: number;
+	/** Seconds remaining in session */
+	sr: number;
+}
+
+/**
+ * Parse the servlet response text into SessionResponse object
+ * Handles CSRF protection prefix
+ *
+ * @param text - Raw response text from servlet
+ * @returns Parsed session response
+ * @throws Error if response cannot be parsed
+ */
+function parseResponseResult(text: string): SessionResponse {
+	let cleanedText = text;
+
+	// Strip CSRF protection prefix if present
+	if (cleanedText.startsWith(SESSION_CONFIG.CSRF_TOKEN)) {
+		cleanedText = cleanedText.substring(SESSION_CONFIG.CSRF_TOKEN.length);
+	}
+
+	// Trim whitespace
+	cleanedText = cleanedText.trim();
+
+	try {
+		const parsed = JSON.parse(cleanedText) as SessionResponse;
+
+		// Validate response structure
+		if (typeof parsed.sp !== "number" || typeof parsed.sr !== "number") {
+			throw new Error("Invalid response structure: missing sp or sr properties");
+		}
+
+		return parsed;
+	} catch (error) {
+		console.error("[sessionTimeService] Failed to parse response:", error, "Text:", cleanedText);
+		throw new Error(
+			`Failed to parse session response: ${error instanceof Error ? error.message : "Unknown error"}`,
+		);
+	}
+}
+
+/**
+ * Call SessionTimeServlet API
+ * Internal function used by both poll and extend functions
+ *
+ * @param basePath - Community base path (e.g., "/sfsites/c/")
+ * @param extend - Whether to extend the session (updateTimedOutSession param)
+ * @returns Session response with remaining time
+ * @throws Error if API call fails or security checks fail
+ */
+async function callSessionTimeServlet(
+	basePath: string,
+	extend: boolean = false,
+): Promise<SessionResponse> {
+	// Build URL with cache-busting timestamp
+	const timestamp = Date.now();
+	let url = `${basePath}${SESSION_CONFIG.SERVLET_URL}?buster=${timestamp}`;
+
+	if (extend) {
+		url += "&updateTimedOutSession=true";
+	}
+
+	try {
+		const response = await fetch(url, {
+			method: "GET",
+			credentials: "same-origin", // Include cookies for session
+			cache: "no-cache",
+			// Security headers
+			headers: {
+				"X-Requested-With": "XMLHttpRequest", // Helps identify XHR requests
+			},
+		});
+
+		if (!response.ok) {
+			// Provide more context for common error codes
+			if (response.status === 401) {
+				throw new Error("Session expired or unauthorized");
+			} else if (response.status === 403) {
+				throw new Error("Access forbidden");
+			} else if (response.status === 404) {
+				throw new Error("Session endpoint not found");
+			} else {
+				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			}
+		}
+
+		// Security: Validate content type (should be text or JSON)
+		const contentType = response.headers.get("content-type");
+		if (contentType && !contentType.includes("text") && !contentType.includes("json")) {
+			throw new Error(`Unexpected content type: ${contentType}`);
+		}
+
+		const text = await response.text();
+		const parsed = parseResponseResult(text);
+
+		// Apply latency buffer to account for network delay
+		const adjustedSecondsRemaining = Math.max(0, parsed.sr - SESSION_CONFIG.LATENCY_BUFFER_SECONDS);
+
+		return {
+			sp: parsed.sp,
+			sr: adjustedSecondsRemaining,
+		};
+	} catch (error) {
+		// Don't log the full URL in production to avoid leaking sensitive info
+		console.error("[sessionTimeService] API call failed:", error);
+		throw error;
+	}
+}
+
+/**
+ * Poll SessionTimeServlet to check remaining session time
+ * Called periodically to monitor session status
+ *
+ * @param basePath - Community base path (e.g., "/sfsites/c/")
+ * @returns Session response with remaining time (after latency buffer adjustment)
+ * @throws Error if API call fails
+ *
+ * @example
+ * const { sr, sp } = await pollSessionTimeServlet('/sfsites/c/');
+ * if (sr <= 300) {
+ *   // Less than 5 minutes remaining
+ *   showWarning();
+ * }
+ */
+export async function pollSessionTimeServlet(basePath: string): Promise<SessionResponse> {
+	return callSessionTimeServlet(basePath, false);
+}
+
+/**
+ * Extend the current session time
+ * Called when user clicks "Continue Working" in warning modal
+ *
+ * @param basePath - Community base path (e.g., "/sfsites/c/")
+ * @returns Session response with new remaining time
+ * @throws Error if API call fails
+ *
+ * @example
+ * const { sr } = await extendSessionTime('/sfsites/c/');
+ * console.log(`Session extended. ${sr} seconds remaining.`);
+ */
+export async function extendSessionTime(basePath: string): Promise<SessionResponse> {
+	return callSessionTimeServlet(basePath, true);
+}
+
+/**
+ * Export parseResponseResult for testing purposes
+ * @internal
+ */
+export { parseResponseResult };

package/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/auth/sessionTimeout/sessionTimeoutConfig.ts

@@ -0,0 +1,77 @@
+/**
+ * Configuration constants for session timeout monitoring
+ */
+
+// ============================================================================
+// Retry Configuration
+// ============================================================================
+
+/** Initial delay for first retry attempt (2 seconds) */
+export const INITIAL_RETRY_DELAY = 2000;
+
+/** Maximum number of retry attempts before giving up */
+export const MAX_RETRY_ATTEMPTS = 10;
+
+/** Maximum retry delay (30 minutes) */
+export const MAX_RETRY_DELAY = 30 * 60 * 1000;
+
+// ============================================================================
+// Session Storage Keys
+// ============================================================================
+
+/** sessionStorage keys used by session validator */
+export const STORAGE_KEYS = {
+	/** Flag to show session expired message on login page */
+	SHOW_SESSION_MESSAGE: "lwrSessionValidator.showSessionMessage",
+} as const;
+
+// ============================================================================
+// Servlet Configuration
+// ============================================================================
+
+/** SessionTimeServlet configuration */
+export const SESSION_CONFIG = {
+	/** Relative URL to SessionTimeServlet */
+	SERVLET_URL: "/sfsites/c/_nc_external/system/security/session/SessionTimeServlet",
+
+	/** Latency buffer to subtract from server response (seconds) */
+	LATENCY_BUFFER_SECONDS: 3,
+
+	/** CSRF protection prefix in servlet responses */
+	CSRF_TOKEN: "while(1);\n",
+} as const;
+
+// ============================================================================
+// UI Labels
+// ============================================================================
+
+/**
+ * UI labels for session timeout components
+ */
+export const LABELS = {
+	/** Title for session warning modal */
+	sessionWarningTitle: "Session Timeout Warning",
+
+	/** Message text in session warning modal */
+	sessionWarningMessage:
+		"For security, we log you out if you’re inactive for too long. To continue working, click Continue before the time expires.",
+
+	/** Text for "Continue" button */
+	continueButton: "Continue",
+
+	/** Text for "Log Out" button */
+	logoutButton: "Log Out",
+
+	/** Message shown on login page after session expires */
+	invalidSessionMessage: "Your session has expired. Please log in again.",
+
+	/** Accessibility label for close button */
+	closeLabel: "Close",
+} as const;
+
+// ============================================================================
+// Session Timeout Configuration
+// ============================================================================
+
+/** Session warning time in seconds (30 seconds) */
+export const SESSION_WARNING_TIME = 30;

package/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/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/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/forms/auth-form.tsx

@@ -0,0 +1,81 @@
+import { FieldGroup } from "../ui/field";
+import { StatusAlert } from "../alerts/status-alert";
+import { FooterLink } from "../footers/footer-link";
+import { SubmitButton } from "./submit-button";
+import { CardLayout } from "../layout/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/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/forms/submit-button.tsx

@@ -0,0 +1,49 @@
+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"> {
+	/** 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/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/layout/card-layout.tsx

@@ -0,0 +1,23 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "../ui/card";
+
+interface CardLayoutProps {
+	title: string;
+	description?: string;
+	children: React.ReactNode;
+}
+
+/**
+ * Card layout component for authentication pages.
+ * Provides CardHeader with title and optional description, and CardContent.
+ */
+export function CardLayout({ title, description, children }: CardLayoutProps) {
+	return (
+		<Card>
+			<CardHeader>
+				<CardTitle className="text-2xl">{title}</CardTitle>
+				{description && <CardDescription>{description}</CardDescription>}
+			</CardHeader>
+			<CardContent>{children}</CardContent>
+		</Card>
+	);
+}

package/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/layout/card-skeleton.tsx

@@ -0,0 +1,38 @@
+import { CenteredPageLayout } from "./centered-page-layout";
+import { Card, CardContent, CardHeader } from "../ui/card";
+import { Skeleton } from "../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>
+	);
+}

package/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/layout/centered-page-layout.tsx

@@ -0,0 +1,73 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/utils";
+
+/**
+ * Variant styles for the content container's maximum width.
+ * Controls the maximum width of the inner content area within the page layout.
+ */
+const contentContainerVariants = cva("w-full", {
+	variants: {
+		contentMaxWidth: {
+			sm: "max-w-sm",
+			md: "max-w-md",
+			lg: "max-w-lg",
+		},
+	},
+	defaultVariants: {
+		contentMaxWidth: "sm",
+	},
+});
+
+/**
+ * Props for the CenteredPageLayout component.
+ */
+interface CenteredPageLayoutProps
+	extends React.ComponentProps<"div">,
+		VariantProps<typeof contentContainerVariants> {
+	/** The content to be displayed within the page layout */
+	children: React.ReactNode;
+	/**
+	 * Maximum width of the content container.
+	 * @default "sm"
+	 */
+	contentMaxWidth?: "sm" | "md" | "lg";
+	/**
+	 * Optional page title. If provided, will render a <title> component that React will place in the document head.
+	 */
+	title?: string;
+}
+
+/**
+ * CenteredPageLayout component that provides consistent page structure and spacing.
+ *
+ * This component creates a full-viewport-height container that centers its content
+ * both horizontally and vertically. The inner content area has a configurable maximum width
+ * to prevent content from becoming too wide on large screens.
+ *
+ * @example
+ * ```tsx
+ * <CenteredPageLayout contentMaxWidth="md">
+ *   <YourPageContent />
+ * </CenteredPageLayout>
+ * ```
+ */
+export function CenteredPageLayout({
+	contentMaxWidth,
+	className,
+	children,
+	title,
+	...props
+}: CenteredPageLayoutProps) {
+	return (
+		<>
+			{title && <title>{title}</title>}
+			<main
+				className={cn("flex min-h-svh w-full items-center justify-center p-6 md:p-10", className)}
+				data-slot="page-layout"
+				{...props}
+			>
+				<div className={contentContainerVariants({ contentMaxWidth })}>{children}</div>
+			</main>
+		</>
+	);
+}

package/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/ui/alert.tsx

@@ -0,0 +1,69 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../../lib/utils";
+
+const alertVariants = cva(
+	"grid gap-0.5 rounded-lg border px-2.5 py-2 text-left text-sm has-data-[slot=alert-action]:relative has-data-[slot=alert-action]:pr-18 has-[>svg]:grid-cols-[auto_1fr] has-[>svg]:gap-x-2 *:[svg]:row-span-2 *:[svg]:translate-y-0.5 *:[svg]:text-current *:[svg:not([class*='size-'])]:size-4 w-full relative group/alert",
+	{
+		variants: {
+			variant: {
+				default: "bg-card text-card-foreground",
+				destructive:
+					"text-destructive bg-card *:data-[slot=alert-description]:text-destructive/90 *:[svg]:text-current",
+			},
+		},
+		defaultVariants: {
+			variant: "default",
+		},
+	},
+);
+
+function Alert({
+	className,
+	variant,
+	...props
+}: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
+	return (
+		<div
+			data-slot="alert"
+			role="alert"
+			className={cn(alertVariants({ variant }), className)}
+			{...props}
+		/>
+	);
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
+	return (
+		<div
+			data-slot="alert-title"
+			className={cn(
+				"font-medium group-has-[>svg]/alert:col-start-2 [&_a]:hover:text-foreground [&_a]:underline [&_a]:underline-offset-3",
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function AlertDescription({ className, ...props }: React.ComponentProps<"div">) {
+	return (
+		<div
+			data-slot="alert-description"
+			className={cn(
+				"text-muted-foreground text-sm text-balance md:text-pretty [&_p:not(:last-child)]:mb-4 [&_a]:hover:text-foreground [&_a]:underline [&_a]:underline-offset-3",
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function AlertAction({ className, ...props }: React.ComponentProps<"div">) {
+	return (
+		<div data-slot="alert-action" className={cn("absolute top-2 right-2", className)} {...props} />
+	);
+}
+
+export { Alert, AlertTitle, AlertDescription, AlertAction };

package/lib/templates/project/react-b2x/force-app/main/default/webapplications/appreacttemplateb2x/src/components/ui/button.tsx

@@ -0,0 +1,67 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Slot } from "radix-ui";
+
+import { cn } from "../../lib/utils";
+
+const buttonVariants = cva(
+	"focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 rounded-lg border border-transparent bg-clip-padding text-sm font-medium focus-visible:ring-3 aria-invalid:ring-3 [&_svg:not([class*='size-'])]:size-4 inline-flex items-center justify-center whitespace-nowrap transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none shrink-0 [&_svg]:shrink-0 outline-none group/button select-none",
+	{
+		variants: {
+			variant: {
+				default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
+				outline:
+					"border-border bg-background hover:bg-muted hover:text-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 aria-expanded:bg-muted aria-expanded:text-foreground",
+				secondary:
+					"bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
+				ghost:
+					"hover:bg-muted hover:text-foreground dark:hover:bg-muted/50 aria-expanded:bg-muted aria-expanded:text-foreground",
+				destructive:
+					"bg-destructive/10 hover:bg-destructive/20 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/20 text-destructive focus-visible:border-destructive/40 dark:hover:bg-destructive/30",
+				link: "text-primary underline-offset-4 hover:underline",
+			},
+			size: {
+				default:
+					"h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+				xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+				sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+				lg: "h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3",
+				icon: "size-8",
+				"icon-xs":
+					"size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+				"icon-sm":
+					"size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
+				"icon-lg": "size-9",
+			},
+		},
+		defaultVariants: {
+			variant: "default",
+			size: "default",
+		},
+	},
+);
+
+function Button({
+	className,
+	variant = "default",
+	size = "default",
+	asChild = false,
+	...props
+}: React.ComponentProps<"button"> &
+	VariantProps<typeof buttonVariants> & {
+		asChild?: boolean;
+	}) {
+	const Comp = asChild ? Slot.Root : "button";
+
+	return (
+		<Comp
+			data-slot="button"
+			data-variant={variant}
+			data-size={size}
+			className={cn(buttonVariants({ variant, size, className }))}
+			{...props}
+		/>
+	);
+}
+
+export { Button, buttonVariants };