@salesforce/ui-bundle-template-feature-angular-object-search 12.5.4

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/filters/text-filter.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import {
+	ChangeDetectionStrategy,
+	Component,
+	DestroyRef,
+	effect,
+	inject,
+	input,
+	signal,
+} from "@angular/core";
+import { takeUntilDestroyed } from "@angular/core/rxjs-interop";
+import { Subject } from "rxjs";
+import { debounceTime } from "rxjs/operators";
+import { InputComponent } from "../../../components/ui/input/input";
+import { ObjectSearchStateService } from "../object-search-state.service";
+import { FILTER_DEBOUNCE_MS } from "../utils/debounce";
+import type { FilterFieldConfig } from "../utils/filter-utils";
+import { FilterFieldWrapperComponent } from "./filter-field-wrapper";
+
+/**
+ * Text filter — free-text input that writes a `like %value%` clause via
+ * {@link ObjectSearchStateService.setFilter}. Keystrokes update the local
+ * signal immediately and flush to shared state on a
+ * {@link FILTER_DEBOUNCE_MS}ms trailing debounce.
+ */
+@Component({
+	selector: "app-text-filter",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [InputComponent, FilterFieldWrapperComponent],
+	templateUrl: "./text-filter.html",
+})
+export class TextFilterComponent {
+	private readonly state = inject(ObjectSearchStateService);
+	private readonly destroyRef = inject(DestroyRef);
+
+	readonly config = input.required<FilterFieldConfig>();
+
+	protected readonly localValue = signal<string>("");
+	private readonly commit$ = new Subject<string>();
+
+	constructor() {
+		this.commit$
+			.pipe(debounceTime(FILTER_DEBOUNCE_MS), takeUntilDestroyed(this.destroyRef))
+			.subscribe((v) => this.commit(v));
+
+		// Sync the input with shared state (URL restore, reset-all, ...).
+		effect(() => {
+			const cfg = this.config();
+			const external = this.state.filterFor(cfg.field)?.value ?? "";
+			this.localValue.set(external);
+		});
+	}
+
+	protected onValueChange(v: string): void {
+		this.localValue.set(v);
+		this.commit$.next(v);
+	}
+
+	private commit(v: string): void {
+		const cfg = this.config();
+		if (v) {
+			this.state.setFilter(cfg.field, {
+				field: cfg.field,
+				label: cfg.label,
+				type: "text",
+				value: v,
+			});
+		} else {
+			this.state.removeFilter(cfg.field);
+		}
+	}
+}

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/object-search-state.service.ts

@@ -0,0 +1,232 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { computed, DestroyRef, inject, Injectable, signal, type Signal } from "@angular/core";
+import { takeUntilDestroyed } from "@angular/core/rxjs-interop";
+import { ActivatedRoute, Router } from "@angular/router";
+import { Subject } from "rxjs";
+import { debounceTime } from "rxjs/operators";
+import {
+	buildFilter,
+	filtersToQueryParams,
+	queryParamsToFilters,
+	type ActiveFilterValue,
+	type FilterFieldConfig,
+} from "./utils/filter-utils";
+import { buildOrderBy, type SortState } from "./utils/sort-utils";
+
+/** How long to wait before flushing state changes to the URL. */
+const URL_SYNC_DEBOUNCE_MS = 300;
+
+/** Cursor-pagination configuration for an object-search page. */
+export interface PaginationConfig {
+	defaultPageSize: number;
+	validPageSizes: number[];
+}
+
+/** Derived, API-ready query signals returned from {@link ObjectSearchStateService.init}. */
+export interface ObjectSearchQuery<TFilter, TOrderBy> {
+	where: Signal<TFilter | undefined>;
+	orderBy: Signal<TOrderBy | undefined>;
+}
+
+/**
+ * Filter / sort / cursor-pagination state for one object-search page — the
+ * Angular analogue of the React `useObjectSearchParams` hook plus
+ * `FilterContext`.
+ *
+ * ## State model
+ * Signals drive instant UI updates. The URL query params are the durable source
+ * of truth so a refresh or shared link restores the same view. URL writes are
+ * debounced (300 ms) to avoid history spam.
+ *
+ * Unlike the React reference, the pagination cursor (`after`) is part of the URL
+ * (see {@link filtersToQueryParams}), so a deep-linked page N fetches page N's
+ * rows rather than page 1's rows shown under a higher page number.
+ *
+ * ## Scope
+ * Provide per route/component (`providers: [ObjectSearchStateService]`), NOT in
+ * root — each search page owns its own state and cursor stack.
+ *
+ * ## Usage
+ * Call {@link init} once from the hosting component with the field/pagination
+ * config, then read the exposed signals and call the mutators.
+ */
+@Injectable()
+export class ObjectSearchStateService {
+	private readonly router = inject(Router);
+	private readonly route = inject(ActivatedRoute);
+	private readonly destroyRef = inject(DestroyRef);
+
+	private filterConfigs: FilterFieldConfig[] = [];
+	private defaultPageSize = 10;
+	private validPageSizes: number[] = [10];
+	private initialized = false;
+
+	// -- Core state signals -----------------------------------------------------
+	private readonly _filters = signal<ActiveFilterValue[]>([]);
+	private readonly _sort = signal<SortState | null>(null);
+	private readonly _pageSize = signal<number>(10);
+	private readonly _pageIndex = signal<number>(0);
+	private readonly _afterCursor = signal<string | undefined>(undefined);
+
+	/** Cursor stack for "previous page" — mirrors the React ref-held stack. */
+	private cursorStack: string[] = [];
+	/** Coalesces rapid state changes into a single debounced URL write. */
+	private readonly urlSync$ = new Subject<void>();
+
+	// -- Public read signals -----------------------------------------------------
+	readonly filters: Signal<ActiveFilterValue[]> = this._filters.asReadonly();
+	readonly sort: Signal<SortState | null> = this._sort.asReadonly();
+	readonly pageSize: Signal<number> = this._pageSize.asReadonly();
+	readonly pageIndex: Signal<number> = this._pageIndex.asReadonly();
+	readonly afterCursor: Signal<string | undefined> = this._afterCursor.asReadonly();
+	readonly hasActiveFilters = computed(() => this._filters().length > 0);
+	readonly hasPreviousPage = computed(() => this._pageIndex() > 0);
+
+	constructor() {
+		this.urlSync$
+			.pipe(debounceTime(URL_SYNC_DEBOUNCE_MS), takeUntilDestroyed(this.destroyRef))
+			.subscribe(() => this.flushToUrl());
+	}
+
+	/**
+	 * Initializes the service from the given config and seeds state from the
+	 * current URL. Safe to call once; subsequent calls only recompute the
+	 * derived query signals.
+	 */
+	init<TFilter, TOrderBy>(
+		filterConfigs: FilterFieldConfig[],
+		paginationConfig?: PaginationConfig,
+	): ObjectSearchQuery<TFilter, TOrderBy> {
+		if (!this.initialized) {
+			this.initialized = true;
+			this.filterConfigs = filterConfigs;
+			this.defaultPageSize = paginationConfig?.defaultPageSize ?? 10;
+			this.validPageSizes = paginationConfig?.validPageSizes ?? [this.defaultPageSize];
+			this.seedFromUrl();
+		}
+
+		const where = computed(() => buildFilter<TFilter>(this._filters(), this.filterConfigs));
+		const orderBy = computed(() => buildOrderBy<TOrderBy>(this._sort()));
+		return { where, orderBy };
+	}
+
+	// -- Filter mutators ---------------------------------------------------------
+
+	/** Adds or replaces the filter for `field`; `undefined` removes it. */
+	setFilter(field: string, value: ActiveFilterValue | undefined): void {
+		this._filters.update((prev) => {
+			const next = prev.filter((f) => f.field !== field);
+			if (value) next.push(value);
+			return next;
+		});
+		this.resetPagination();
+		this.urlSync$.next();
+	}
+
+	/** Removes the active filter for `field`, if any. */
+	removeFilter(field: string): void {
+		this._filters.update((prev) => prev.filter((f) => f.field !== field));
+		this.resetPagination();
+		this.urlSync$.next();
+	}
+
+	/** Reads the active filter value for a field (for filter components). */
+	filterFor(field: string): ActiveFilterValue | undefined {
+		return this._filters().find((f) => f.field === field);
+	}
+
+	// -- Sort mutator ------------------------------------------------------------
+
+	/** Sets (or clears) the sort; resets pagination to the first page. */
+	setSort(sort: SortState | null): void {
+		this._sort.set(sort);
+		this.resetPagination();
+		this.urlSync$.next();
+	}
+
+	// -- Pagination mutators -----------------------------------------------------
+
+	/** Advances to the next page using the supplied `endCursor`. */
+	goToNextPage(endCursor: string): void {
+		this.cursorStack = [...this.cursorStack, endCursor];
+		this._afterCursor.set(endCursor);
+		this._pageIndex.update((i) => i + 1);
+		this.urlSync$.next();
+	}
+
+	/** Returns to the previous page by popping the cursor stack. */
+	goToPreviousPage(): void {
+		this.cursorStack = this.cursorStack.slice(0, -1);
+		const prev =
+			this.cursorStack.length > 0 ? this.cursorStack[this.cursorStack.length - 1] : undefined;
+		this._afterCursor.set(prev);
+		this._pageIndex.update((i) => Math.max(0, i - 1));
+		this.urlSync$.next();
+	}
+
+	/** Sets a validated page size and resets pagination. */
+	setPageSize(size: number): void {
+		this._pageSize.set(this.getValidPageSize(size));
+		this.resetPagination();
+		this.urlSync$.next();
+	}
+
+	// -- Reset -------------------------------------------------------------------
+
+	/** Clears all filters, sort, and pagination in one call (flushed at once). */
+	resetAll(): void {
+		this._filters.set([]);
+		this._sort.set(null);
+		this._pageSize.set(this.defaultPageSize);
+		this.resetPagination();
+		this.flushToUrl();
+	}
+
+	// -- Internals ---------------------------------------------------------------
+
+	private resetPagination(): void {
+		this._pageIndex.set(0);
+		this._afterCursor.set(undefined);
+		this.cursorStack = [];
+	}
+
+	private getValidPageSize(size: number): number {
+		return this.validPageSizes.includes(size) ? size : this.defaultPageSize;
+	}
+
+	private seedFromUrl(): void {
+		const params = this.route.snapshot.queryParams as Record<string, string | undefined>;
+		const parsed = queryParamsToFilters(params, this.filterConfigs);
+		this._filters.set(parsed.filters);
+		this._sort.set(parsed.sort);
+		this._pageSize.set(this.getValidPageSize(parsed.pageSize ?? this.defaultPageSize));
+		this._pageIndex.set(parsed.pageIndex);
+		this._afterCursor.set(parsed.afterCursor);
+		// Rebuild a minimal cursor stack so "previous" works after a deep link.
+		// Pages before the current one are unknown, so pad the stack with the
+		// current cursor; going back drains it and eventually returns to page 1.
+		if (parsed.pageIndex > 0 && parsed.afterCursor) {
+			this.cursorStack = Array<string>(parsed.pageIndex).fill(parsed.afterCursor);
+		}
+	}
+
+	private flushToUrl(): void {
+		const queryParams = filtersToQueryParams({
+			filters: this._filters(),
+			sort: this._sort(),
+			pageSize: this._pageSize(),
+			pageIndex: this._pageIndex(),
+			afterCursor: this._afterCursor(),
+		});
+		void this.router.navigate([], {
+			relativeTo: this.route,
+			queryParams,
+			// Replace so filter typing doesn't flood browser history.
+			replaceUrl: true,
+		});
+	}
+}

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/pagination/pagination.html

@@ -0,0 +1,8 @@
+<app-paginator
+	[length]="totalCount() ?? 0"
+	[pageIndex]="pageIndex()"
+	[pageSize]="pageSize()"
+	[pageSizeOptions]="pageSizeOptions()"
+	[disabled]="disabled()"
+	(page)="onPage($event)"
+/>

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/pagination/pagination.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, inject, input } from "@angular/core";
+import { PaginatorComponent } from "../../../components/ui/paginator/paginator";
+import type { PageEvent } from "../../../components/ui/paginator/types";
+import { ObjectSearchStateService } from "../object-search-state.service";
+
+/**
+ * Cursor-pagination bridge. Feeds shared cursor state into {@link PaginatorComponent}
+ * and translates its offset-style `(page)` event back into the cursor walk the
+ * state service understands.
+ */
+@Component({
+	selector: "app-pagination-controls",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [PaginatorComponent],
+	templateUrl: "./pagination.html",
+})
+export class PaginationControlsComponent {
+	readonly totalCount = input<number | undefined>(undefined);
+	readonly hasNextPage = input<boolean>(false);
+	readonly endCursor = input<string | undefined>(undefined);
+	readonly pageSizeOptions = input.required<readonly number[]>();
+	readonly disabled = input<boolean>(false);
+
+	private readonly state = inject(ObjectSearchStateService);
+	protected readonly pageIndex = this.state.pageIndex;
+	protected readonly pageSize = this.state.pageSize;
+
+	protected onPage(event: PageEvent): void {
+		if (event.pageSize !== this.pageSize()) {
+			this.state.setPageSize(event.pageSize);
+			return;
+		}
+		if (event.pageIndex > this.pageIndex()) {
+			const cursor = this.endCursor();
+			if (cursor && this.hasNextPage()) this.state.goToNextPage(cursor);
+		} else if (event.pageIndex < this.pageIndex()) {
+			this.state.goToPreviousPage();
+		}
+	}
+}

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/search-bar/search-bar.html

@@ -0,0 +1,10 @@
+<app-input
+	class="block"
+	type="search"
+	icon="search"
+	[label]="label()"
+	[placeholder]="placeholder()"
+	[ariaLabel]="ariaLabel()"
+	[id]="inputId()"
+	[(value)]="value"
+/>

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/search-bar/search-bar.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, input, model } from "@angular/core";
+import { InputComponent } from "../../../components/ui/input/input";
+
+/**
+ * Presentational search box: a text input with a leading search icon inside
+ * its border, purely controlled via `value` with no search state of its own.
+ * Reused by the Home landing form and by `app-search-filter` (which adds the
+ * debounce + shared-state wiring around it).
+ */
+@Component({
+	selector: "app-search-bar",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [InputComponent],
+	host: { class: "flex-1 block" },
+	templateUrl: "./search-bar.html",
+})
+export class SearchBarComponent {
+	readonly value = model<string>("");
+	readonly placeholder = input<string>("");
+	readonly label = input<string>("");
+	readonly ariaLabel = input<string>("");
+	readonly inputId = input<string>("");
+}

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/sort-control/sort-control.html

@@ -0,0 +1,24 @@
+<div class="flex items-center gap-2">
+	<span class="text-sm text-muted-foreground whitespace-nowrap">{{ label() }}</span>
+	<app-select
+		class="w-[160px]"
+		[options]="options()"
+		[value]="selectedValue()"
+		(valueChange)="onFieldChange($event)"
+		placeholder="Default"
+	/>
+	@if (sort(); as active) {
+	<app-button
+		appearance="text"
+		size="icon-sm"
+		[ariaLabel]="'Sort ' + (active.direction === 'ASC' ? 'descending' : 'ascending')"
+		(clicked)="toggleDirection()"
+	>
+		@if (active.direction === "ASC") {
+		<app-icon name="arrowUp" />
+		} @else {
+		<app-icon name="arrowDown" />
+		}
+	</app-button>
+	}
+</div>

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/sort-control/sort-control.ts

@@ -0,0 +1,65 @@
+/**
+ * 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";
+import { ButtonComponent } from "../../../components/ui/button/button";
+import { IconComponent } from "../../../components/ui/icon/icon";
+import {
+	SelectComponent,
+	type AppSelectOption,
+} from "../../../components/ui/select/select";
+import { ObjectSearchStateService } from "../object-search-state.service";
+import type { SortFieldConfig, SortState } from "../utils/sort-utils";
+
+/** Sentinel value used in the select to represent "no sort". */
+const NONE_VALUE = "__none__";
+
+/**
+ * Sort field + direction toggle. Choosing a field applies ASC by default; the
+ * direction button flips ASC/DESC and only appears while a sort is active.
+ * Selecting `Default` clears the sort (`setSort(null)`).
+ */
+@Component({
+	selector: "app-sort-control",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [ButtonComponent, IconComponent, SelectComponent],
+	templateUrl: "./sort-control.html",
+})
+export class SortControlComponent {
+	readonly sortFields = input.required<SortFieldConfig[]>();
+	readonly label = input<string>("Sort by");
+
+	private readonly state = inject(ObjectSearchStateService);
+	protected readonly sort = this.state.sort;
+
+	protected readonly options = computed<AppSelectOption[]>(() => [
+		{ value: NONE_VALUE, label: "Default" },
+		...this.sortFields().map((c) => ({ value: c.field, label: c.label })),
+	]);
+
+	protected readonly selectedValue = computed(() => this.sort()?.field ?? NONE_VALUE);
+
+	protected onFieldChange(field: string): void {
+		if (field === NONE_VALUE) {
+			this.state.setSort(null);
+			return;
+		}
+		const current = this.sort();
+		const next: SortState = {
+			field,
+			direction: current?.direction ?? "ASC",
+		};
+		this.state.setSort(next);
+	}
+
+	protected toggleDirection(): void {
+		const current = this.sort();
+		if (!current) return;
+		this.state.setSort({
+			field: current.field,
+			direction: current.direction === "ASC" ? "DESC" : "ASC",
+		});
+	}
+}

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/utils/debounce.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/** Default debounce delay for keystroke-driven filter inputs (search, text, numeric). */
+export const FILTER_DEBOUNCE_MS = 300;
+
+/**
+ * Creates a debounced version of the provided function.
+ *
+ * Each call to the returned function resets the internal timer. The wrapped
+ * function is only invoked once the timer expires without being reset. This
+ * makes it ideal for rate-limiting high-frequency events like input changes.
+ *
+ * @typeParam T - The function signature to debounce.
+ * @param fn - The function to debounce.
+ * @param ms - The debounce delay in milliseconds.
+ * @returns A new function with the same signature that delays execution.
+ */
+export function debounce<T extends (...args: never[]) => void>(
+	fn: T,
+	ms: number,
+): (...args: Parameters<T>) => void {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	return (...args: Parameters<T>) => {
+		clearTimeout(timer);
+		timer = setTimeout(() => fn(...args), ms);
+	};
+}

package/dist/force-app/main/default/uiBundles/feature-angular-object-search/src/app/features/object-search/utils/field-utils.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/** A Salesforce GraphQL scalar field: `{ value, displayValue }`. */
+export interface UiField {
+	displayValue?: string | null;
+	value?: unknown;
+}
+
+/**
+ * Extracts a human-readable string from a Salesforce GraphQL scalar field,
+ * preferring the server-formatted `displayValue` over the raw `value`.
+ *
+ * @returns The display string, or `null` when the field is empty.
+ */
+export function fieldValue(field: UiField | null | undefined): string | null {
+	if (field?.displayValue != null) return field.displayValue;
+	if (field?.value != null) return String(field.value);
+	return null;
+}
+
+/**
+ * Formats a Salesforce address into display lines (street / city-state-zip /
+ * country), omitting empty parts. Returns `null` when nothing is present.
+ */
+export function getAddressFieldLines(address: {
+	street?: string | null;
+	city?: string | null;
+	state?: string | null;
+	postalCode?: string | null;
+	country?: string | null;
+}): string[] | null {
+	const cityStateZip = [address.city, address.state].filter(Boolean).join(", ");
+	const cityStateZipLine = [cityStateZip, address.postalCode].filter(Boolean).join(" ");
+	const lines = [address.street, cityStateZipLine, address.country].filter(Boolean) as string[];
+	if (lines.length === 0) return null;
+	return lines;
+}
+
+/**
+ * Formats an ISO datetime string via `Intl`/`toLocaleString`. Returns `null`
+ * for empty input so callers can fall back cleanly.
+ */
+export function formatDateTimeField(
+	value: string | null | undefined,
+	locales?: Intl.LocalesArgument,
+	options?: Intl.DateTimeFormatOptions,
+): string | null {
+	if (!value) return null;
+	return new Date(value).toLocaleString(locales, options);
+}