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

package/dist/force-app/main/default/uiBundles/angularinternalapp/src/app/features/object-search/components/search-bar/search-bar.component.ts

@@ -0,0 +1,108 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import {
+	ChangeDetectionStrategy,
+	Component,
+	computed,
+	DestroyRef,
+	inject,
+	input,
+	type OnInit,
+	signal,
+} from "@angular/core";
+import { takeUntilDestroyed, toObservable } from "@angular/core/rxjs-interop";
+import { debounceTime } from "rxjs/operators";
+import { ButtonComponent } from "../../../../components/ui/button/button.component";
+import { InputComponent } from "../../../../components/ui/input/input.component";
+import { PopoverComponent } from "../../../../components/ui/popover/popover.component";
+import { ObjectSearchStateService } from "../../object-search-state.service";
+import type { FilterFieldConfig } from "../../utils/filter-utils";
+
+/** How long to wait after the last keystroke before writing to state. */
+const SEARCH_DEBOUNCE_MS = 300;
+
+/**
+ * Search-bar header for an object-search page: a debounced text input bound to
+ * the `search` filter, plus an optional filter popover that content-projects
+ * the sibling filter components (owned by the filters wave).
+ *
+ * Mirrors the React `SearchBar`, with the composed additions from the ground-
+ * truth example page (filter panel toggle). Filter components are NOT imported
+ * here — the hosting page projects them via the `[filters]` slot so the
+ * feature can pick which filters it renders.
+ *
+ * ## Usage
+ * ```html
+ * <app-search-bar [searchConfig]="searchCfg" [filterConfigs]="filterCfgs">
+ *   <div filters>
+ *     <app-text-filter .../>
+ *     <app-select-filter .../>
+ *   </div>
+ * </app-search-bar>
+ * ```
+ */
+@Component({
+	selector: "app-search-bar",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [ButtonComponent, InputComponent, PopoverComponent],
+	templateUrl: "./search-bar.component.html",
+})
+export class SearchBarComponent implements OnInit {
+	/** Config for the multi-field search filter (its label, placeholder, etc.). */
+	readonly searchConfig = input.required<FilterFieldConfig>();
+	/**
+	 * Configs for the filters projected into the popover. Not consumed directly
+	 * here — surfaced so the hosting page and this component agree on which
+	 * filters exist, and reserved for a future filter-count badge.
+	 */
+	readonly filterConfigs = input<FilterFieldConfig[]>([]);
+
+	private readonly state = inject(ObjectSearchStateService);
+	private readonly destroyRef = inject(DestroyRef);
+
+	/** Local, debounced mirror of the search filter's `value`. */
+	protected readonly term = signal<string>("");
+	protected readonly popoverOpen = signal<boolean>(false);
+
+	/** Count of currently active filters minus the search itself (for the badge). */
+	protected readonly nonSearchFilterCount = computed(
+		() => this.state.filters().filter((f) => f.type !== "search").length,
+	);
+
+	constructor() {
+		// Required inputs are not yet resolved in the constructor, so the search
+		// config is read lazily inside the subscription (which emits after init).
+		toObservable(this.term)
+			.pipe(debounceTime(SEARCH_DEBOUNCE_MS), takeUntilDestroyed(this.destroyRef))
+			.subscribe((value) => {
+				const cfg = this.searchConfig();
+				if (value) {
+					this.state.setFilter(cfg.field, {
+						field: cfg.field,
+						label: cfg.label,
+						type: cfg.type,
+						value,
+					});
+				} else {
+					this.state.removeFilter(cfg.field);
+				}
+			});
+	}
+
+	ngOnInit(): void {
+		// Seed the local term from any existing search filter (deep-link support).
+		// Done here (not the constructor) so the required `searchConfig` input is
+		// resolved before it is read.
+		const existing = this.state.filterFor(this.searchConfig().field);
+		if (existing?.value) {
+			this.term.set(existing.value);
+		}
+	}
+
+	protected togglePopover(): void {
+		this.popoverOpen.set(!this.popoverOpen());
+	}
+}

package/dist/force-app/main/default/uiBundles/angularinternalapp/src/app/features/object-search/components/sort-control/sort-control.component.html

@@ -0,0 +1,50 @@
+<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"
+			[attr.aria-label]="'Sort ' + (active.direction === 'ASC' ? 'descending' : 'ascending')"
+			(clicked)="toggleDirection()"
+		>
+			@if (active.direction === "ASC") {
+				<svg
+					xmlns="http://www.w3.org/2000/svg"
+					class="h-4 w-4"
+					viewBox="0 0 24 24"
+					fill="none"
+					stroke="currentColor"
+					stroke-width="2"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+					aria-hidden="true"
+				>
+					<path d="m5 12 7-7 7 7" />
+					<path d="M12 19V5" />
+				</svg>
+			} @else {
+				<svg
+					xmlns="http://www.w3.org/2000/svg"
+					class="h-4 w-4"
+					viewBox="0 0 24 24"
+					fill="none"
+					stroke="currentColor"
+					stroke-width="2"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+					aria-hidden="true"
+				>
+					<path d="M12 5v14" />
+					<path d="m19 12-7 7-7-7" />
+				</svg>
+			}
+		</app-button>
+	}
+</div>

package/dist/force-app/main/default/uiBundles/angularinternalapp/src/app/features/object-search/components/sort-control/sort-control.component.ts

@@ -0,0 +1,72 @@
+/**
+ * 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.component";
+import {
+	SelectComponent,
+	type AppSelectOption,
+} from "../../../../components/ui/select/select.component";
+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. Mirrors the React `SortControl`.
+ *
+ * Reads `sort()` from the {@link ObjectSearchStateService} and drives changes
+ * via `setSort`. 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, SelectComponent],
+	templateUrl: "./sort-control.component.html",
+})
+export class SortControlComponent {
+	/** Sortable fields to expose in the select. */
+	readonly sortFields = input.required<SortFieldConfig[]>();
+	/** Override for the leading label (default `Sort by`). */
+	readonly label = input<string>("Sort by");
+
+	private readonly state = inject(ObjectSearchStateService);
+	/** Current sort state from the shared state service. */
+	protected readonly sort = this.state.sort;
+
+	/** Select options — the `Default` sentinel plus one per sortable field. */
+	protected readonly options = computed<AppSelectOption[]>(() => [
+		{ value: NONE_VALUE, label: "Default" },
+		...this.sortFields().map((c) => ({ value: c.field, label: c.label })),
+	]);
+
+	/** Value shown in the select — either the current field or the sentinel. */
+	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/angularinternalapp/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/angularinternalapp/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/angularinternalapp/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);
+}