@salesforce/templates 66.11.0 → 66.12.0

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

@@ -0,0 +1,12 @@
+<app-filter-field-wrapper
+	[label]="config().label"
+	[htmlFor]="inputId()"
+	[helpText]="config().helpText"
+>
+	<app-input
+		type="text"
+		[placeholder]="config().placeholder ?? 'Filter by ' + config().label.toLowerCase() + '...'"
+		[value]="localValue()"
+		(valueChange)="onValueChange($event)"
+	/>
+</app-filter-field-wrapper>

package/lib/templates/project/angularintapp/_p_/_m_/_w_/_a_/src/app/features/object-search/filters/text-filter.ts

@@ -0,0 +1,90 @@
+/**
+ * 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";
+// Base-app UI wrapper, inherited (not recreated) by this feature. Post-compose
+// it lands at uiBundles/<target>/src/app/components/ui/input/..., three levels up.
+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 (for a responsive UI) and flush to shared state on a
+ * {@link FILTER_DEBOUNCE_MS}ms trailing debounce (to avoid a query per key).
+ *
+ * Reads the current value from `state.filterFor(config.field)` so URL /
+ * reset-all changes reflect back into the input.
+ */
+@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);
+
+	/** Field config: `field`, `label`, `placeholder`, `helpText`, ... */
+	readonly config = input.required<FilterFieldConfig>();
+
+	/** Local (uncommitted) value that drives the input while the user is typing. */
+	protected readonly localValue = signal<string>("");
+
+	/** DOM id shared by the wrapper label and the underlying input. */
+	protected readonly inputId = signal<string>("");
+
+	/** Coalesces rapid keystrokes into one shared-state write. */
+	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 the shared state (URL restore, reset-all, ...).
+		// Mirrors the React "reset local when external changes" pattern.
+		effect(() => {
+			const cfg = this.config();
+			this.inputId.set(`filter-${cfg.field}`);
+			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/lib/templates/project/angularintapp/_p_/_m_/_w_/_a_/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/lib/templates/project/angularintapp/_p_/_m_/_w_/_a_/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/lib/templates/project/angularintapp/_p_/_m_/_w_/_a_/src/app/features/object-search/pagination/pagination.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 type { PageEvent } from "@angular/material/paginator";
+import { PaginatorComponent } from "../../../components/ui/paginator/paginator";
+import { ObjectSearchStateService } from "../object-search-state.service";
+
+/**
+ * Cursor-pagination bridge. Feeds the shared cursor state into the presentational
+ * {@link PaginatorComponent} (`app-paginator`) and translates its offset-style
+ * `(page)` event back into the cursor walk the state service understands.
+ *
+ * State comes from the shared {@link ObjectSearchStateService} (`pageIndex`,
+ * `pageSize`); the hosting page supplies the cursor-derived inputs
+ * (`totalCount`, `hasNextPage`, `endCursor`) after each fetch. A next-page step
+ * needs the current `endCursor`; a previous step and page-size changes are
+ * handled entirely by the state service's cursor stack.
+ */
+@Component({
+	selector: "app-pagination-controls",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [PaginatorComponent],
+	templateUrl: "./pagination.html",
+})
+export class PaginationControlsComponent {
+	/** Total row count from the latest fetch; drives the paginator's range label. */
+	readonly totalCount = input<number | undefined>(undefined);
+	/** Whether the API reports another page after the current one. */
+	readonly hasNextPage = input<boolean>(false);
+	/** `endCursor` from the latest page-info; forwarded to `goToNextPage`. */
+	readonly endCursor = input<string | undefined>(undefined);
+	/** Allowed page-size choices. */
+	readonly pageSizeOptions = input.required<readonly number[]>();
+	/** Disable navigation and the size select (e.g. while loading). */
+	readonly disabled = input<boolean>(false);
+
+	private readonly state = inject(ObjectSearchStateService);
+	protected readonly pageIndex = this.state.pageIndex;
+	protected readonly pageSize = this.state.pageSize;
+
+	/**
+	 * Route Material's offset-style page event onto the cursor model: a page-size
+	 * change resets pagination; a forward step walks the `endCursor`; a backward
+	 * step pops the cursor stack.
+	 */
+	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/lib/templates/project/angularintapp/_p_/_m_/_w_/_a_/src/app/features/object-search/search-bar/search-bar.html

@@ -0,0 +1,59 @@
+<div class="flex items-center gap-2 w-full">
+	<div class="relative flex-1">
+		<svg
+			xmlns="http://www.w3.org/2000/svg"
+			class="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground pointer-events-none z-10"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="2"
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			aria-hidden="true"
+		>
+			<circle cx="11" cy="11" r="8" />
+			<path d="m21 21-4.3-4.3" />
+		</svg>
+		<app-input
+			class="pl-9 block"
+			type="text"
+			[placeholder]="searchConfig().placeholder ?? ''"
+			[label]="searchConfig().label"
+			[(value)]="term"
+		/>
+	</div>
+	<app-popover [(open)]="popoverOpen" align="end">
+		<app-button
+			trigger
+			appearance="outlined"
+			[attr.aria-expanded]="popoverOpen()"
+			aria-label="Toggle filters"
+			class="gap-2"
+		>
+			<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="M3 6h18M7 12h10M10 18h4" />
+			</svg>
+			<span>Filters</span>
+			@if (nonSearchFilterCount() > 0) {
+			<span
+				class="inline-flex items-center justify-center h-5 min-w-5 rounded-full bg-primary text-primary-foreground text-xs px-1"
+			>
+				{{ nonSearchFilterCount() }}
+			</span>
+			}
+		</app-button>
+		<div class="p-3 min-w-72 max-w-96 space-y-3">
+			<ng-content select="[filters]" />
+		</div>
+	</app-popover>
+</div>

package/lib/templates/project/angularintapp/_p_/_m_/_w_/_a_/src/app/features/object-search/search-bar/search-bar.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";
+import { InputComponent } from "../../../components/ui/input/input";
+import { PopoverComponent } from "../../../components/ui/popover/popover";
+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.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/lib/templates/project/angularintapp/_p_/_m_/_w_/_a_/src/app/features/object-search/sort-control/sort-control.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>