@salesforce/ui-bundle-template-app-angular-template-b2x 11.30.0

package/dist/force-app/main/default/uiBundles/angularexternalapp/src/app/features/authentication/session-timeout/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/dist/force-app/main/default/uiBundles/angularexternalapp/src/app/features/authentication/utils/auth-helpers.ts

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { AUTH_REDIRECT_PARAM } from "../config/authentication.config";
+
+/**
+ * Extracts the startUrl from the current query params, defaulting to '/'.
+ *
+ * SECURITY NOTE: This function strictly validates the URL to prevent Open
+ * Redirect vulnerabilities. It allows only relative paths.
+ *
+ * Direct port of the React `getStartUrl`. The React version takes a
+ * `URLSearchParams`; Angular's `ParamMap` exposes the same `get(key)` contract,
+ * so this accepts a minimal `{ get(name): string | null }` shape and works with
+ * both an `ActivatedRoute` `ParamMap` and a `URLSearchParams`.
+ *
+ * @param params - The query-param map (e.g. ActivatedRoute.snapshot.queryParamMap).
+ * @returns The start URL for post-authentication redirect.
+ */
+export function getStartUrl(params: { get(name: string): string | null }): string {
+	const url = params.get(AUTH_REDIRECT_PARAM);
+	if (url && isValidRedirect(url)) {
+		return url;
+	}
+	return "/";
+}
+
+/**
+ * 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
+ *
+ * Ported from the React `isValidRedirect`, with one intentional hardening: the
+ * character-range ceiling is tightened from the React source's U+00FF to the
+ * printable-ASCII bound U+007E (~) so DEL / C1 controls / NBSP are rejected in
+ * line with check #3. Do not relax any of these checks without security review.
+ */
+export 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.
+	// Allowed range is the printable-ASCII band U+0021 (!) through U+007E (~).
+	// This deliberately tightens the React reference's U+00FF ceiling, which
+	// admitted U+007F (DEL), the C1 control block (U+0080-U+009F, incl. NEL),
+	// and U+00A0 (NBSP) - all of which contradict the "reject control
+	// characters" contract and are open-redirect / request-splitting vectors.
+	if (/[^!-~]/.test(url)) return false;
+	return true;
+}
+
+/**
+ * Shared response type for authentication endpoints (login/register). Success
+ * responses contain `success: true` and `redirectUrl`. Error responses contain
+ * an `errors` array.
+ */
+export interface AuthResponse {
+	success?: boolean;
+	redirectUrl?: string | null;
+	errors?: string[];
+}

package/dist/force-app/main/default/uiBundles/angularexternalapp/src/app/features/authentication/utils/auth-validators.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { AbstractControl, ValidationErrors, ValidatorFn } from "@angular/forms";
+
+/**
+ * Angular Reactive Forms validators that mirror the React feature's zod schemas
+ * (`authHelpers.ts`). The React port dropped zod in favour of native Angular
+ * validators; these reproduce the same rules and messages so the UX is
+ * identical. Each validator returns `{ <key>: message }` on failure and `null`
+ * on success; templates read the first message via `control.errors`.
+ */
+
+/** Mirrors zod `emailSchema`: trimmed, valid email. */
+export const emailValidator: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
+	const value = (control.value ?? "").toString().trim();
+	if (value === "") {
+		return { email: "Please enter a valid email address" };
+	}
+	// Same intent as zod's email check: a single @ with non-empty local/domain
+	// parts and a dotted domain. Kept deliberately permissive, like zod.
+	const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+	return emailPattern.test(value) ? null : { email: "Please enter a valid email address" };
+};
+
+/** Mirrors zod `passwordSchema`: minimum 8 characters. */
+export const passwordMinValidator: ValidatorFn = (
+	control: AbstractControl,
+): ValidationErrors | null => {
+	const value = (control.value ?? "").toString();
+	return value.length >= 8 ? null : { password: "Password must be at least 8 characters" };
+};
+
+/** A required-with-custom-message validator (mirrors zod `min(1, message)`). */
+export function requiredWithMessage(message: string): ValidatorFn {
+	return (control: AbstractControl): ValidationErrors | null => {
+		const value = (control.value ?? "").toString().trim();
+		return value.length >= 1 ? null : { required: message };
+	};
+}
+
+/**
+ * Cross-field validator mirroring the `newPasswordSchema` refine: the
+ * `confirmPassword` control must equal the `newPassword` control. Attach to the
+ * FormGroup; sets `{ passwordMismatch: '...' }` on the confirm control (matching
+ * the zod `path: ['confirmPassword']`) so the error renders under that field.
+ */
+export function passwordsMatchValidator(
+	passwordKey = "newPassword",
+	confirmKey = "confirmPassword",
+): ValidatorFn {
+	return (group: AbstractControl): ValidationErrors | null => {
+		const password = group.get(passwordKey);
+		const confirm = group.get(confirmKey);
+		if (!password || !confirm) {
+			return null;
+		}
+		if (confirm.value !== password.value) {
+			const existing = confirm.errors ?? {};
+			confirm.setErrors({ ...existing, passwordMismatch: "Passwords do not match" });
+			return { passwordMismatch: "Passwords do not match" };
+		}
+		// Clear only our own error, preserving any other errors on the control.
+		if (confirm.errors) {
+			const { passwordMismatch: _removed, ...rest } = confirm.errors;
+			confirm.setErrors(Object.keys(rest).length ? rest : null);
+		}
+		return null;
+	};
+}

package/dist/force-app/main/default/uiBundles/angularexternalapp/src/app/features/authentication/utils/helpers.ts

@@ -0,0 +1,85 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Error thrown when the API returns a non-OK response with structured error
+ * messages. The `errors` array contains user-facing messages that are safe to
+ * display — backend Apex classes guarantee that system exceptions are never
+ * exposed. Direct port of the React `ApiError`.
+ */
+export class ApiError extends Error {
+	readonly errors: string[];
+	constructor(errors: string[]) {
+		super(errors[0]);
+		this.name = "ApiError";
+		this.errors = errors;
+	}
+}
+
+/**
+ * Helper to parse the fetch Response. Handles the distinction between success
+ * (JSON) and failure (throwing Error). Ported from the React `handleApiResponse`.
+ */
+export async function handleApiResponse<T = unknown>(response: Response): Promise<T> {
+	// Robustness: Handle 204 No Content gracefully
+	if (response.status === 204) {
+		return {} as T;
+	}
+
+	let data: { errors?: string[] } | null = null;
+
+	const contentType = response.headers.get("content-type");
+	if (contentType?.includes("application/json")) {
+		data = (await response.json()) as { errors?: string[] };
+	} else {
+		// If Salesforce returns HTML (e.g. standard error page), consume the text
+		// to avoid parsing errors.
+		await response.text();
+	}
+
+	if (!response.ok) {
+		console.error("API request failed", data);
+		if (data?.errors?.length) {
+			throw new ApiError(data.errors);
+		}
+		throw new Error("An unexpected error occurred");
+	}
+
+	return data as T;
+}
+
+/** UI API Record response structure. */
+export type RecordResponse = {
+	fields: Record<string, { value: string }>;
+};
+
+/**
+ * GraphQL can return a complex nested structure. This helper flattens it to a
+ * simple object for easier form binding. Ported from the React
+ * `flattenGraphQLRecord`.
+ *
+ * @param data - Extracted payload from the GraphQL response.
+ * @param fallbackError - Fallback error message if data is null/undefined or not an object.
+ * @throws {Error} If data is not valid.
+ * @returns Flattened object with values mapped directly to the fields.
+ */
+export function flattenGraphQLRecord<T>(
+	data: unknown,
+	fallbackError = "An unknown error occurred",
+): T {
+	if (!data || typeof data !== "object") {
+		throw new Error(fallbackError);
+	}
+
+	return Object.fromEntries(
+		Object.entries(data as Record<string, unknown>).map(([key, field]) => [
+			key,
+			field !== null && typeof field === "object" && "value" in field
+				? (field as { value: unknown }).value
+				: (field ?? null),
+		]),
+	) as T;
+}

package/dist/force-app/main/default/uiBundles/angularexternalapp/src/app/features/object-search/components/active-filters/active-filters.component.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/dist/force-app/main/default/uiBundles/angularexternalapp/src/app/features/object-search/components/active-filters/active-filters.component.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.component";
+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.component.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/dist/force-app/main/default/uiBundles/angularexternalapp/src/app/features/object-search/components/filters/date-filter/date-filter.component.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>

package/dist/force-app/main/default/uiBundles/angularexternalapp/src/app/features/object-search/components/filters/date-filter/date-filter.component.ts

@@ -0,0 +1,137 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, computed, inject, input } from "@angular/core";
+// Base-app UI wrappers, inherited (not recreated) by this feature. Post-compose
+// they land at uiBundles/<target>/src/app/components/ui/{date-picker,select}/..., four
+// levels up.
+import { DatePickerComponent } from "../../../../../components/ui/date-picker/date-picker.component";
+import {
+	SelectComponent,
+	type AppSelectOption,
+} from "../../../../../components/ui/select/select.component";
+import { ObjectSearchStateService } from "../../../object-search-state.service";
+import type { FilterFieldConfig, FilterFieldType } from "../../../utils/filter-utils";
+import { FilterFieldWrapperComponent } from "../filter-field-wrapper/filter-field-wrapper.component";
+
+/**
+ * Single-date filter — operator select ("After" / "Before") plus a date
+ * picker. Emits a filter whose `value` is the operator (`'gt'` or `'lt'`) and
+ * whose date is placed in `min` (for `gt`) or `max` (for `lt`), matching the
+ * React reference and the `date` / `datetime` branch of `buildSingleFilter`.
+ *
+ * The `filterType` input toggles the emitted `type` between `'date'` and
+ * `'datetime'` (the latter adds start/end-of-day promotion in the filter
+ * builder).
+ */
+type DateOperator = "gt" | "lt";
+
+const OPERATOR_OPTIONS: readonly AppSelectOption[] = [
+	{ value: "gt", label: "After" },
+	{ value: "lt", label: "Before" },
+];
+
+@Component({
+	selector: "app-date-filter",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [DatePickerComponent, SelectComponent, FilterFieldWrapperComponent],
+	templateUrl: "./date-filter.component.html",
+})
+export class DateFilterComponent {
+	private readonly state = inject(ObjectSearchStateService);
+
+	/** Field config: `field`, `label`, `helpText`, ... */
+	readonly config = input.required<FilterFieldConfig>();
+	/** Underlying filter type — `'date'` (default) or `'datetime'`. */
+	readonly filterType = input<FilterFieldType>("date");
+
+	protected readonly operatorOptions = OPERATOR_OPTIONS;
+
+	/** Active filter (if any) — the single source of truth for both fields. */
+	private readonly active = computed(() => this.state.filterFor(this.config().field));
+
+	/** Cap the picker at today when the field can't hold a future date. */
+	protected readonly maxDate = computed<Date | null>(() =>
+		this.config().disableFuture ? new Date() : null,
+	);
+
+	/**
+	 * Selected operator. Defaults to `'gt'` when no filter is active, mirroring
+	 * the React initial state (`min` present -> `gt`, else `lt`, but with no
+	 * active filter React ended up on `lt`; we prefer `'gt'` as the safer
+	 * "After a date" default when nothing is selected).
+	 */
+	protected readonly operator = computed<DateOperator>(() => {
+		const a = this.active();
+		if (a?.value === "gt" || a?.value === "lt") return a.value;
+		if (a?.min) return "gt";
+		if (a?.max) return "lt";
+		return "gt";
+	});
+
+	/** Date picker value — parsed from either `min` (gt) or `max` (lt). */
+	protected readonly currentDate = computed<Date | null>(() => {
+		const a = this.active();
+		return toDate(a?.min ?? a?.max);
+	});
+
+	protected onOperatorChange(v: string): void {
+		const op = v === "lt" ? "lt" : "gt";
+		const date = this.currentDate();
+		// Only re-emit if we already had a date; otherwise wait until the user
+		// picks one (matches React `emitChange` gate on `currentDate`).
+		if (date) this.emit(op, date);
+	}
+
+	protected onDateChange(date: Date | null): void {
+		const cfg = this.config();
+		if (!date) {
+			this.state.removeFilter(cfg.field);
+		} else {
+			this.emit(this.operator(), date);
+		}
+	}
+
+	private emit(op: DateOperator, date: Date): void {
+		const cfg = this.config();
+		const dateStr = toDateString(date);
+		const isMin = op === "gt";
+		this.state.setFilter(cfg.field, {
+			field: cfg.field,
+			label: cfg.label,
+			type: this.filterType(),
+			value: op,
+			min: isMin ? dateStr : undefined,
+			max: isMin ? undefined : dateStr,
+		});
+	}
+}
+
+/** Parses `YYYY-MM-DD` (or any ISO date) into a `Date`, or `null` on failure. */
+export function toDate(value: string | undefined): Date | null {
+	if (!value) return null;
+	// Interpret bare YYYY-MM-DD as a local-time date so the picker doesn't
+	// display "yesterday" in negative UTC offsets.
+	const parts = value.split("T")[0].split("-");
+	if (parts.length === 3) {
+		const [y, m, d] = parts.map((p) => Number(p));
+		const dt = new Date(y, m - 1, d);
+		return isNaN(dt.getTime()) ? null : dt;
+	}
+	const dt = new Date(value);
+	return isNaN(dt.getTime()) ? null : dt;
+}
+
+/** Formats a `Date` as `YYYY-MM-DD` in local time. */
+export function toDateString(date: Date | null | undefined): string {
+	if (!date || isNaN(date.getTime())) return "";
+	const y = date.getFullYear();
+	// Guard against partially-typed years (e.g. `202` instead of `2026`), which
+	// would serialize to an invalid `202-07-09` and be rejected by the API.
+	if (y < 1000 || y > 9999) return "";
+	const m = String(date.getMonth() + 1).padStart(2, "0");
+	const d = String(date.getDate()).padStart(2, "0");
+	return `${y}-${m}-${d}`;
+}