@salesforce/templates 66.11.0 → 66.12.0

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/utils/session-time-servlet.ts

@@ -0,0 +1,130 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * SessionTimeServlet API helpers — direct (pure-TS) port of the React
+ * `sessionTimeService.ts`. Handles communication with the session validation
+ * endpoint, strips the CSRF prefix, and subtracts the latency buffer. Returns
+ * `undefined` on any failure so the session-timeout feature never crashes the
+ * running application.
+ */
+
+import { SESSION_CONFIG } from "./session-timeout.config";
+
+/** Response from SessionTimeServlet API. */
+export interface SessionResponse {
+	/** Session phase. */
+	sp: number;
+	/** Seconds remaining in session. */
+	sr: number;
+}
+
+/**
+ * Parse the servlet response text into a SessionResponse object. Handles the
+ * CSRF protection prefix.
+ *
+ * @param text - Raw response text from servlet.
+ * @returns Parsed session response, or undefined if parsing fails.
+ */
+export function parseResponseResult(text: string): SessionResponse | undefined {
+	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);
+		return undefined;
+	}
+}
+
+/**
+ * Call SessionTimeServlet API. Internal function used by both poll and extend.
+ * Returns undefined on any failure.
+ *
+ * @param basePath - Community base path (e.g., "/sfsites/c/").
+ * @param extend - Whether to extend the session (updateTimedOutSession param).
+ */
+async function callSessionTimeServlet(
+	basePath: string,
+	extend = false,
+): Promise<SessionResponse | undefined> {
+	// 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",
+			cache: "no-cache",
+			headers: {
+				"X-Requested-With": "XMLHttpRequest",
+			},
+		});
+
+		if (!response.ok) {
+			console.error(`[sessionTimeService] HTTP ${response.status}: ${response.statusText}`);
+			return undefined;
+		}
+
+		const contentType = response.headers.get("content-type");
+		if (contentType && !contentType.includes("text") && !contentType.includes("json")) {
+			console.error(`[sessionTimeService] Unexpected content type: ${contentType}`);
+			return undefined;
+		}
+
+		const text = await response.text();
+		const parsed = parseResponseResult(text);
+		if (!parsed) {
+			return undefined;
+		}
+
+		return {
+			sp: parsed.sp,
+			sr: Math.max(0, parsed.sr - SESSION_CONFIG.LATENCY_BUFFER_SECONDS),
+		};
+	} catch (error) {
+		console.error("[sessionTimeService] API call failed:", error);
+		return undefined;
+	}
+}
+
+/**
+ * Poll SessionTimeServlet to check remaining session time. Called periodically
+ * to monitor session status.
+ */
+export async function pollSessionTimeServlet(
+	basePath: string,
+): Promise<SessionResponse | undefined> {
+	return callSessionTimeServlet(basePath, false);
+}
+
+/**
+ * Extend the current session time. Called when the user clicks "Continue" in the
+ * warning modal.
+ */
+export async function extendSessionTime(basePath: string): Promise<SessionResponse | undefined> {
+	return callSessionTimeServlet(basePath, true);
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/utils/session-timeout.config.ts

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Configuration constants for session timeout monitoring. Direct port of the
+ * React `sessionTimeoutConfig.ts` — values are byte-for-byte identical so the
+ * polling cadence, retry backoff, and warning window match exactly.
+ */
+
+// ---------------------------------------------------------------------------
+// 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 the 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/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/utils/session-timeout.service.ts

@@ -0,0 +1,201 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { Injectable, signal } from "@angular/core";
+import {
+	extendSessionTime,
+	pollSessionTimeServlet,
+	type SessionResponse,
+} from "./session-time-servlet";
+import {
+	INITIAL_RETRY_DELAY,
+	MAX_RETRY_ATTEMPTS,
+	MAX_RETRY_DELAY,
+	SESSION_WARNING_TIME,
+} from "./session-timeout.config";
+
+/**
+ * Session-timeout monitoring service — the Angular port of the React
+ * `useSessionTimeout` hook (plus the inlined `useRetryWithBackoff`). Polls
+ * SessionTimeServlet at calculated intervals, shows the warning window when the
+ * session nears expiry, and retries failed polls with exponential backoff.
+ *
+ * State is exposed as signals; the owning `SessionTimeoutValidatorComponent`
+ * reacts to them and performs navigation/logout (this service, like the React
+ * hook, never navigates — it only tracks time and schedules checks).
+ *
+ * NOT `providedIn: 'root'`: it is provided by the validator component so its
+ * timers are torn down with that component (mirrors the hook's unmount cleanup).
+ */
+@Injectable()
+export class SessionTimeoutService {
+	// -- Public session state (signals) --------------------------------------
+	/** Seconds remaining in the current session (null until first response). */
+	readonly timeLeftInSession = signal<number | null>(null);
+	/** Whether the warning modal should be displayed. */
+	readonly showWarningModal = signal<boolean>(false);
+	/** Whether a poll is currently in flight. */
+	readonly isPolling = signal<boolean>(false);
+
+	// -- Retry (exponential backoff) state ------------------------------------
+	private retryAttempts = 0;
+	private currentRetryDelay = INITIAL_RETRY_DELAY;
+
+	// -- Timer / guard bookkeeping --------------------------------------------
+	private basePath = "";
+	private pollTimeoutId: ReturnType<typeof setTimeout> | null = null;
+	private retryTimeoutId: ReturnType<typeof setTimeout> | null = null;
+	private isPollingGuard = false;
+
+	private get maxRetriesReached(): boolean {
+		return this.retryAttempts >= MAX_RETRY_ATTEMPTS;
+	}
+
+	private resetRetry(): void {
+		this.retryAttempts = 0;
+		this.currentRetryDelay = INITIAL_RETRY_DELAY;
+	}
+
+	private clearPollTimeout(): void {
+		if (this.pollTimeoutId) {
+			clearTimeout(this.pollTimeoutId);
+			this.pollTimeoutId = null;
+		}
+	}
+
+	private clearRetryTimeout(): void {
+		if (this.retryTimeoutId) {
+			clearTimeout(this.retryTimeoutId);
+			this.retryTimeoutId = null;
+		}
+	}
+
+	/**
+	 * Schedule the next session check, clearing any pending poll/retry to prevent
+	 * concurrent polling. Mirrors the hook's `scheduleCheck`.
+	 */
+	private scheduleCheck(delay: number): void {
+		this.clearPollTimeout();
+		this.clearRetryTimeout();
+		this.pollTimeoutId = setTimeout(() => {
+			void this.checkSession();
+		}, delay);
+	}
+
+	/**
+	 * Handle a failed poll/extend with exponential backoff. Mirrors the hook's
+	 * `handleRetryWithBackoff` + `useRetryWithBackoff.scheduleRetry`.
+	 */
+	private handleRetryWithBackoff(retryAction: () => void): void {
+		if (this.maxRetriesReached) {
+			console.error("[SessionTimeout] Max retry attempts reached. Stopping polling.");
+			this.isPolling.set(false);
+			this.isPollingGuard = false;
+			return;
+		}
+
+		if (this.isPollingGuard) {
+			console.warn("[SessionTimeout] Poll already in progress, skipping retry scheduling");
+			return;
+		}
+
+		this.clearRetryTimeout();
+
+		const delay = this.currentRetryDelay;
+		console.warn(
+			`[SessionTimeout] Scheduling retry attempt ${this.retryAttempts + 1}/${MAX_RETRY_ATTEMPTS} in ${delay}ms`,
+		);
+
+		this.retryTimeoutId = setTimeout(() => {
+			this.retryTimeoutId = null;
+			retryAction();
+		}, delay);
+
+		this.retryAttempts += 1;
+		// Double the delay for the next retry, capped at maxDelay.
+		this.currentRetryDelay = Math.min(this.currentRetryDelay * 2, MAX_RETRY_DELAY);
+	}
+
+	/**
+	 * Process a session response and schedule the next check. Mirrors the hook's
+	 * `processTimeoutResponse`. When `sr <= 0` the component's effect performs
+	 * logout; when within the warning window the modal is shown and a check is
+	 * scheduled for expiry; otherwise a check is scheduled for when the warning
+	 * should appear.
+	 */
+	private processTimeoutResponse(secondsRemaining: number): void {
+		this.timeLeftInSession.set(secondsRemaining);
+
+		if (secondsRemaining <= 0) {
+			this.showWarningModal.set(false);
+			// logout() is triggered by the component reacting to timeLeftInSession.
+			return;
+		}
+
+		const shouldShowWarning = secondsRemaining <= SESSION_WARNING_TIME;
+
+		if (shouldShowWarning) {
+			this.showWarningModal.set(true);
+			this.scheduleCheck(secondsRemaining * 1000);
+		} else {
+			const timeUntilWarning = (secondsRemaining - SESSION_WARNING_TIME) * 1000;
+			this.showWarningModal.set(false);
+			this.scheduleCheck(timeUntilWarning);
+		}
+	}
+
+	/** Check session status via the servlet. Mirrors the hook's `checkSession`. */
+	async checkSession(): Promise<void> {
+		if (this.isPollingGuard) {
+			return;
+		}
+
+		this.isPollingGuard = true;
+		this.isPolling.set(true);
+
+		const response = await pollSessionTimeServlet(this.basePath);
+		this.isPollingGuard = false;
+		this.isPolling.set(false);
+
+		this.applyResponse(response, () => void this.checkSession());
+	}
+
+	/** Extend the session (user clicked "Continue"). Mirrors `extendSession`. */
+	async extendSession(): Promise<void> {
+		const response = await extendSessionTime(this.basePath);
+		this.applyResponse(response, () => void this.extendSession());
+	}
+
+	private applyResponse(response: SessionResponse | undefined, retryAction: () => void): void {
+		if (response) {
+			this.resetRetry();
+			this.processTimeoutResponse(response.sr);
+		} else {
+			this.handleRetryWithBackoff(retryAction);
+		}
+	}
+
+	/**
+	 * Begin monitoring. Skips guests (mirrors the hook's guest short-circuit) and
+	 * kicks off the first check.
+	 */
+	start(basePath: string, isGuest: boolean): void {
+		this.basePath = basePath;
+		if (isGuest) {
+			return;
+		}
+		void this.checkSession();
+	}
+
+	/** Stop monitoring and reset state. Mirrors the hook's `logout` cleanup. */
+	stop(): void {
+		this.clearPollTimeout();
+		this.clearRetryTimeout();
+		this.showWarningModal.set(false);
+		this.timeLeftInSession.set(null);
+		this.isPolling.set(false);
+		this.isPollingGuard = false;
+	}
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/object-search/breadcrumb/breadcrumb.html

@@ -0,0 +1,54 @@
+<nav aria-label="Breadcrumb" class="mb-3">
+	<ol
+		class="text-muted-foreground flex flex-wrap items-center gap-1.5 text-sm break-words sm:gap-2.5"
+	>
+		@if (includeHome()) {
+		<li class="inline-flex items-center gap-1.5">
+			<a [routerLink]="'/'" class="hover:text-foreground transition-colors">{{ homeLabel() }}</a>
+		</li>
+		<li aria-hidden="true" class="[&>svg]:size-3.5">
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+			>
+				<polyline points="9 18 15 12 9 6" />
+			</svg>
+		</li>
+		} @if (isDetailView()) {
+		<li class="inline-flex items-center gap-1.5">
+			<a [routerLink]="listPath()" class="hover:text-foreground transition-colors"
+				>{{ listLabel() }}</a
+			>
+		</li>
+		<li aria-hidden="true" class="[&>svg]:size-3.5">
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+			>
+				<polyline points="9 18 15 12 9 6" />
+			</svg>
+		</li>
+		<li class="inline-flex items-center gap-1.5">
+			@if (loading() && !recordName()) {
+			<app-skeleton class="h-4 w-32" />
+			} @else {
+			<span class="text-foreground font-normal" aria-current="page">{{ recordName() }}</span>
+			}
+		</li>
+		} @else {
+		<li class="inline-flex items-center gap-1.5">
+			<span class="text-foreground font-normal" aria-current="page">{{ listLabel() }}</span>
+		</li>
+		}
+	</ol>
+</nav>

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/object-search/breadcrumb/breadcrumb.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, computed, input } from "@angular/core";
+import { RouterLink } from "@angular/router";
+import { SkeletonComponent } from "../../../components/ui/skeleton/skeleton";
+
+/**
+ * Object-search breadcrumb — Home > Records list > (optional) Record name.
+ *
+ * Mirrors the React `ObjectBreadcrumb`. Renders the list-only crumb by default
+ * and switches to the detail-view crumb (with record name + skeleton fallback)
+ * as soon as `loading` or `recordName` is set. Uses Angular `routerLink` where
+ * the React version uses `react-router`'s `Link`.
+ */
+@Component({
+	selector: "app-object-breadcrumb",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [RouterLink, SkeletonComponent],
+	templateUrl: "./breadcrumb.html",
+})
+export class ObjectBreadcrumbComponent {
+	/** Router path for the object list view (e.g. `/accounts`). */
+	readonly listPath = input.required<string>();
+	/** Label for the list crumb (e.g. `Accounts`). */
+	readonly listLabel = input.required<string>();
+	/** Record name for the detail-view leaf crumb; omit for list-only view. */
+	readonly recordName = input<string | undefined>(undefined);
+	/** Show a skeleton in the leaf crumb while the record is loading. */
+	readonly loading = input<boolean>(false);
+	/** Prepend a Home crumb (default `true`). */
+	readonly includeHome = input<boolean>(true);
+	/** Label for the Home crumb (default `Home`). */
+	readonly homeLabel = input<string>("Home");
+
+	/** `true` when the crumb should render list + record leaves. */
+	protected readonly isDetailView = computed(() => this.loading() || !!this.recordName());
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/object-search/filters/active-filters.html

@@ -0,0 +1,23 @@
+@if (chips().length > 0) {
+<div class="flex flex-wrap gap-2">
+	@for (chip of chips(); track chip.field) {
+	<app-button
+		appearance="outlined"
+		size="sm"
+		iconEnd="close"
+		[ariaLabel]="'Remove filter ' + chip.label"
+		(clicked)="onRemove(chip.field)"
+	>
+		{{ chip.label }}
+	</app-button>
+	}
+	<app-button
+		appearance="destructive"
+		size="sm"
+		ariaLabel="Clear all filters"
+		(clicked)="onClearAll()"
+	>
+		Clear all
+	</app-button>
+</div>
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/object-search/filters/active-filters.ts

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, computed, inject } from "@angular/core";
+import { ButtonComponent } from "../../../components/ui/button/button";
+import { ObjectSearchStateService } from "../object-search-state.service";
+import type { ActiveFilterValue } from "../utils/filter-utils";
+
+/**
+ * Format the display label for one active filter chip. Mirrors the React
+ * `formatFilterLabel`; a switch over the filter's declared `type`.
+ */
+function formatFilterLabel(filter: ActiveFilterValue): string {
+	const { label, type, value, min, max } = filter;
+	switch (type) {
+		case "search":
+			return `Search: ${value}`;
+		case "text":
+		case "picklist":
+			return `${label}: ${value}`;
+		case "multipicklist": {
+			const values = value ? value.split(",") : [];
+			if (values.length <= 2) return `${label}: ${values.join(", ")}`;
+			return `${label}: ${values.length} selected`;
+		}
+		case "boolean":
+			return `${label}: ${value === "true" ? "Yes" : "No"}`;
+		case "numeric": {
+			if (min && max) return `${label}: ${min} - ${max}`;
+			if (min) return `${label}: >= ${min}`;
+			return `${label}: <= ${max}`;
+		}
+		case "date":
+		case "datetime":
+		case "daterange":
+		case "datetimerange": {
+			if (min && max) return `${label}: ${min} to ${max}`;
+			if (min) return `${label}: from ${min}`;
+			return `${label}: until ${max}`;
+		}
+		default:
+			return label;
+	}
+}
+
+/**
+ * Removable-chip strip for the currently active filters.
+ *
+ * Reads `filters()` from {@link ObjectSearchStateService}; clicking a chip
+ * removes that filter, and the `Clear all` chip clears everything via
+ * `resetAll()`. Mirrors the React `ActiveFilters` component.
+ */
+@Component({
+	selector: "app-active-filters",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [ButtonComponent],
+	templateUrl: "./active-filters.html",
+})
+export class ActiveFiltersComponent {
+	private readonly state = inject(ObjectSearchStateService);
+
+	/** Active filters signal from the state service. */
+	protected readonly filters = this.state.filters;
+	/** Display strings paired with the underlying field for chip actions. */
+	protected readonly chips = computed(() =>
+		this.filters().map((f) => ({ field: f.field, label: formatFilterLabel(f) })),
+	);
+
+	protected onRemove(field: string): void {
+		this.state.removeFilter(field);
+	}
+
+	protected onClearAll(): void {
+		this.state.resetAll();
+	}
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/object-search/filters/date-filter.html

@@ -0,0 +1,18 @@
+<app-filter-field-wrapper [label]="config().label" [helpText]="config().helpText">
+	<div class="flex gap-2">
+		<app-select
+			class="flex-1"
+			[options]="operatorOptions"
+			[value]="operator()"
+			(valueChange)="onOperatorChange($event)"
+		/>
+		<app-date-picker
+			class="flex-1"
+			placeholder="Pick a date"
+			[readonly]="true"
+			[max]="maxDate()"
+			[value]="currentDate()"
+			(valueChange)="onDateChange($event)"
+		/>
+	</div>
+</app-filter-field-wrapper>