@salesforce/ui-bundle-template-feature-angular-search 0.0.0-stage → 12.14.0

package/dist/force-app/main/default/uiBundles/feature-angular-search/src/app/features/search/components/results/source-section.ts

@@ -0,0 +1,146 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import {
+	ChangeDetectionStrategy,
+	Component,
+	computed,
+	ElementRef,
+	inject,
+	input,
+	viewChild,
+} from "@angular/core";
+import { AlertComponent } from "../../../../components/ui/alert/alert";
+import { IconComponent } from "../../../../components/ui/icon/icon";
+import {
+	PaginatorComponent,
+	type PageEvent,
+} from "../../../../components/ui/paginator/paginator";
+import { SkeletonComponent } from "../../../../components/ui/skeleton/skeleton";
+import { ActiveFiltersComponent } from "../active-filters/active-filters";
+import { FilterBoxComponent } from "../filter-panel/filter-box";
+import { SortControlComponent } from "../sort-control/sort-control";
+import { SearchStateService } from "../../state/search-state.service";
+import type { SourceView } from "../../state/search-state.types";
+import type { SourceConfig } from "../../types/search-config.types";
+import type { SortState } from "../../types/sort.types";
+import { nodeKey, ResultItemComponent, type ResultTemplates } from "./result-item";
+
+/**
+ * One source's slice of the results: filter box, sort + active-filter chips,
+ * the result list, and the source's own cursor pagination. Orchestration only;
+ * how a node looks is up to the source's `appSearchResult` template.
+ */
+@Component({
+	selector: "app-source-section",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [
+		AlertComponent,
+		IconComponent,
+		SkeletonComponent,
+		ActiveFiltersComponent,
+		FilterBoxComponent,
+		PaginatorComponent,
+		SortControlComponent,
+		ResultItemComponent,
+	],
+	templateUrl: "./source-section.html",
+})
+export class SourceSectionComponent {
+	protected readonly state = inject(SearchStateService);
+
+	readonly source = input.required<SourceConfig>();
+	readonly templates = input<ResultTemplates | undefined>(undefined);
+	/**
+	 * Hide the filter box, sort control and chips. Selections stay in state (and
+	 * keep applying to the query) so narrowing the scope restores them.
+	 */
+	readonly hideFilterChrome = input(false);
+	readonly emptyMessage = input<string | undefined>(undefined);
+	readonly shortQueryMessage = input("Start your search…");
+
+	private readonly region = viewChild<ElementRef<HTMLElement>>("region");
+
+	protected readonly view = computed<SourceView | undefined>(
+		() => this.state.sources()[this.source().key],
+	);
+	protected readonly loading = this.state.loading;
+	protected readonly nodes = computed(() => this.view()?.result?.nodes ?? []);
+	protected readonly totalCount = computed(() => this.view()?.result?.totalCount ?? null);
+	protected readonly error = computed(() => this.view()?.error ?? null);
+	protected readonly hasTotal = computed(() => this.totalCount() !== null);
+
+	/**
+	 * Always a number for the paginator. Uses the server total when known; otherwise
+	 * (cursor source without a count) the minimum that keeps Next enabled only while
+	 * another page exists.
+	 */
+	protected readonly pagerLength = computed(() => {
+		const v = this.view();
+		if (!v) return 0;
+		const total = v.result?.totalCount;
+		if (total != null) return total;
+		return (v.pageIndex + 1) * v.pageSize + (v.hasNextPage ? 1 : 0);
+	});
+
+	protected readonly showResults = computed(
+		() => !this.loading() && !this.error() && this.nodes().length > 0,
+	);
+	protected readonly showEmpty = computed(
+		() => !this.loading() && !this.error() && this.nodes().length === 0,
+	);
+	protected readonly emptyText = computed(
+		() => this.emptyMessage() ?? `No ${this.source().label.toLowerCase()} found.`,
+	);
+	protected readonly skeletonRows = computed(() =>
+		Array.from({ length: Math.min(this.view()?.pageSize ?? 5, 5) }, (_, i) => i),
+	);
+	protected readonly showFilters = computed(() => !this.hideFilterChrome());
+	protected readonly showChips = computed(
+		() => !this.hideFilterChrome() && (this.view()?.filters.length ?? 0) > 0,
+	);
+	protected readonly showSort = computed(
+		() => !this.hideFilterChrome() && (this.source().sortBy?.length ?? 0) > 0,
+	);
+
+	protected readonly liveMessage = computed(() => {
+		const label = this.source().label;
+		const total = this.totalCount();
+		if (this.loading()) return "Searching…";
+		if (this.error()) return `Failed to load ${label}.`;
+		if (this.showEmpty()) {
+			return this.state.isShortQuery() ? this.shortQueryMessage() : this.emptyText();
+		}
+		return total != null ? `${label}: ${total} ${total === 1 ? "result" : "results"}` : "";
+	});
+
+	protected key(node: unknown, index: number): string | number {
+		return nodeKey(node, this.source().idField, index);
+	}
+
+	protected onSort(sort: SortState | undefined): void {
+		this.state.setSort(this.source().key, sort ?? null);
+	}
+
+	/** Cursor paging: the paginator only ever steps one page or changes the size. */
+	protected onPage(event: PageEvent): void {
+		const key = this.source().key;
+		const view = this.view();
+		if (!view) return;
+		if (event.pageSize !== view.pageSize) {
+			this.state.setSourcePageSize(key, event.pageSize);
+		} else if (event.pageIndex > view.pageIndex) {
+			this.state.goToNextSourcePage(key);
+		} else if (event.pageIndex < view.pageIndex) {
+			this.state.goToPreviousSourcePage(key);
+		}
+		this.focusResults();
+	}
+
+	/** Moves focus to the list so screen-reader users land on the new page. */
+	private focusResults(): void {
+		this.region()?.nativeElement.focus();
+	}
+}

package/dist/force-app/main/default/uiBundles/feature-angular-search/src/app/features/search/components/scope/scope-selector.html

@@ -0,0 +1,9 @@
+<div class="min-w-36 [&_label]:sr-only">
+	<app-select
+		size="sm"
+		[label]="label()"
+		[options]="options()"
+		[value]="scope()"
+		(valueChange)="onChange($event)"
+	/>
+</div>

package/dist/force-app/main/default/uiBundles/feature-angular-search/src/app/features/search/components/scope/scope-selector.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, computed, input, output } from "@angular/core";
+import {
+	SelectComponent,
+	type AppSelectOption,
+} from "../../../../components/ui/select/select";
+import { ALL_SCOPE, type SearchScope } from "../../types/scope.types";
+
+/** A selectable source. */
+export interface ScopeOption {
+	key: string;
+	label: string;
+}
+
+/**
+ * State-agnostic dropdown that narrows the search to one source (or "All").
+ * The options are an "All" entry plus one per source.
+ */
+@Component({
+	selector: "app-scope-selector",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [SelectComponent],
+	templateUrl: "./scope-selector.html",
+})
+export class ScopeSelectorComponent {
+	readonly sources = input.required<readonly ScopeOption[]>();
+	readonly scope = input<SearchScope>(ALL_SCOPE);
+	readonly allLabel = input("All");
+	/** Accessible name of the dropdown (visually hidden). */
+	readonly label = input("Search scope");
+	readonly scopeChange = output<SearchScope>();
+
+	protected readonly options = computed<AppSelectOption[]>(() => [
+		{ value: ALL_SCOPE, label: this.allLabel() },
+		...this.sources().map((s) => ({ value: s.key, label: s.label })),
+	]);
+
+	protected onChange(value: string): void {
+		if (value && value !== this.scope()) this.scopeChange.emit(value);
+	}
+}

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

@@ -0,0 +1,55 @@
+<div class="max-w-6xl mx-auto px-4 sm:px-6 lg:px-8 py-6 space-y-6">
+	<header class="space-y-2">
+		<h1 class="text-2xl font-bold">{{ title() }}</h1>
+		@if (subtitle()) {
+		<p class="text-sm text-muted-foreground">{{ subtitle() }}</p>
+		}
+	</header>
+
+	@if (state.configError(); as invalid) {
+	<app-alert
+		role="alert"
+		variant="destructive"
+		icon="error"
+		title="Invalid search configuration"
+		[description]="invalid"
+	/>
+	} @else {
+	<div class="flex flex-wrap items-center gap-3" role="search">
+		<app-search-bar
+			[value]="state.q()"
+			[placeholder]="searchPlaceholder()"
+			(valueChange)="state.setQ($event)"
+		/>
+		@if (showScope()) {
+		<app-scope-selector
+			[sources]="scopeOptions()"
+			[scope]="state.scope()"
+			[allLabel]="allScopeLabel()"
+			(scopeChange)="state.setScope($event)"
+		/>
+		}
+	</div>
+
+	@if (merged()) {
+	<app-merged-search-results
+		[templates]="templates()"
+		[emptyMessage]="emptyMessages()[state.scope()]"
+	/>
+	} @else if (state.error(); as message) {
+	<!-- Page-level failure: one banner instead of a repeated error per source. -->
+	<app-alert
+		role="alert"
+		variant="destructive"
+		icon="error"
+		title="Search failed"
+		[description]="message"
+	/>
+	} @else { @if (showTotal()) {
+	<p class="text-sm text-muted-foreground" role="status">
+		{{ totalResults() }} total result{{ totalResults() === 1 ? '' : 's' }}
+	</p>
+	}
+	<app-search-results [templates]="templates()" [emptyMessages]="emptyMessages()" />
+	} }
+</div>

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

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import {
+	ChangeDetectionStrategy,
+	Component,
+	computed,
+	contentChildren,
+	inject,
+	input,
+	type OnInit,
+} from "@angular/core";
+import { AlertComponent } from "../../../../components/ui/alert/alert";
+import { SearchResultTemplateDirective } from "../../directives/search-result-template/search-result-template";
+import { SearchStateService } from "../../state/search-state.service";
+import type { RestrictTo } from "../../state/search-state.types";
+import { ALL_SCOPE } from "../../types/scope.types";
+import type { SearchConfig } from "../../types/search-config.types";
+import { MergedSearchResultsComponent } from "../results/merged-search-results";
+import type { ResultTemplates } from "../results/result-item";
+import { SearchResultsComponent } from "../results/search-results";
+import { ScopeSelectorComponent } from "../scope/scope-selector";
+import { SearchBarComponent } from "../search-bar/search-bar";
+
+/**
+ * Drop-in search. Given a {@link SearchConfig}, renders a complete experience:
+ * search bar, scope selector, an aggregate count, and the results.
+ *
+ * The results layout follows `config.pagination.mode`: `"per-source"` (default)
+ * stacks one section per source, each with its own filters, sort and paging;
+ * `"merged"` renders one combined grid with a single global pager.
+ *
+ * ```html
+ * <app-search [config]="config" title="Search">
+ *   <ng-template appSearchResult="Property__c" let-node>...</ng-template>
+ * </app-search>
+ * ```
+ *
+ * `config` is read once; it must be stable for the component's lifetime.
+ */
+@Component({
+	selector: "app-search",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	providers: [SearchStateService],
+	imports: [
+		AlertComponent,
+		SearchBarComponent,
+		ScopeSelectorComponent,
+		SearchResultsComponent,
+		MergedSearchResultsComponent,
+	],
+	templateUrl: "./search.html",
+})
+export class SearchComponent implements OnInit {
+	protected readonly state = inject(SearchStateService);
+
+	readonly config = input.required<SearchConfig>();
+	readonly title = input("Search");
+	readonly subtitle = input<string | undefined>(undefined);
+	readonly searchPlaceholder = input("Search…");
+	/**
+	 * Lock the search to one source by `(kind, key)`: hides the scope selector
+	 * and fetches only that source. An unknown pair warns and falls back to "all".
+	 */
+	readonly restrictTo = input<RestrictTo | undefined>(undefined);
+	/** Defaults to `true` with 2+ sources; always hidden when `restrictTo` is set. */
+	readonly showScopeSelector = input<boolean | undefined>(undefined);
+	readonly allScopeLabel = input("All");
+	/** Per source key (merged mode: per scope): message shown when nothing matches. */
+	readonly emptyMessages = input<Readonly<Record<string, string>>>({});
+
+	private readonly resultTemplates = contentChildren(SearchResultTemplateDirective);
+
+	protected readonly templates = computed<ResultTemplates>(
+		() => new Map(this.resultTemplates().map((t) => [t.sourceKey(), t.template])),
+	);
+
+	protected readonly merged = computed(() => this.state.mergedMode());
+	protected readonly scopeOptions = computed(() =>
+		this.config().sources.map((s) => ({ key: s.key, label: s.label })),
+	);
+	protected readonly showScope = computed(
+		() =>
+			!this.state.scopeLocked() && (this.showScopeSelector() ?? this.config().sources.length >= 2),
+	);
+
+	/**
+	 * Aggregate count: meaningful only when 2+ sources are combined. Merged mode
+	 * renders its own count above the grid.
+	 */
+	protected readonly showTotal = computed(
+		() =>
+			!this.merged() &&
+			!this.state.loading() &&
+			(this.state.scope() === ALL_SCOPE ? this.config().sources.length : 1) >= 2,
+	);
+	protected readonly totalResults = computed(() =>
+		Object.values(this.state.sources()).reduce((sum, v) => sum + (v.result?.totalCount ?? 0), 0),
+	);
+
+	ngOnInit(): void {
+		const config = this.config();
+		const restrict = this.restrictTo();
+		let lockedScope: string | undefined;
+		if (restrict) {
+			const match = config.sources.find((s) => s.kind === restrict.kind && s.key === restrict.key);
+			if (match) lockedScope = match.key;
+			else {
+				console.warn(
+					`<app-search restrictTo>: no source with kind="${restrict.kind}" and key="${restrict.key}" in config. Falling back to "all".`,
+				);
+			}
+		}
+		this.state.init(config, { lockedScope });
+	}
+}

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

@@ -0,0 +1,10 @@
+<app-input
+	class="block"
+	type="search"
+	icon="search"
+	[label]="label() ?? ''"
+	[ariaLabel]="label() ? '' : 'Search'"
+	[placeholder]="placeholder()"
+	[value]="draft()"
+	(valueChange)="onInput($event)"
+/>

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

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { TestBed } from "@angular/core/testing";
+import { By } from "@angular/platform-browser";
+import { afterEach, beforeEach, vi } from "vitest";
+import { InputComponent } from "../../../../components/ui/input/input";
+import { FILTER_DEBOUNCE_MS } from "../../utils/debounce";
+import { SearchBarComponent } from "./search-bar";
+
+describe("SearchBarComponent", () => {
+	beforeEach(() => vi.useFakeTimers());
+	afterEach(() => vi.useRealTimers());
+
+	function setup(inputs: Record<string, unknown> = {}) {
+		const fixture = TestBed.createComponent(SearchBarComponent);
+		for (const [k, v] of Object.entries(inputs)) fixture.componentRef.setInput(k, v);
+		const emitted: string[] = [];
+		fixture.componentInstance.valueChange.subscribe((v) => emitted.push(v));
+		fixture.detectChanges();
+		const input = fixture.debugElement.query(By.directive(InputComponent))
+			.componentInstance as InputComponent;
+		return { fixture, input, emitted };
+	}
+
+	it("seeds the input from the value", () => {
+		const { input } = setup({ value: "acme" });
+		expect(input.value()).toBe("acme");
+	});
+
+	it("debounces typing and emits the last value", () => {
+		const { fixture, input, emitted } = setup();
+		input.value.set("a");
+		input.value.set("ac");
+		fixture.detectChanges();
+		vi.advanceTimersByTime(FILTER_DEBOUNCE_MS - 1);
+		expect(emitted).toEqual([]);
+		vi.advanceTimersByTime(1);
+		expect(emitted).toEqual(["ac"]);
+	});
+
+	it("re-seeds the draft when the bound value changes externally", () => {
+		const { fixture, input } = setup({ value: "a" });
+		fixture.componentRef.setInput("value", "");
+		fixture.detectChanges();
+		expect(input.value()).toBe("");
+	});
+
+	it("withholds non-empty values shorter than minLength but always emits empty", () => {
+		const { fixture, input, emitted } = setup({ minLength: 3 });
+		input.value.set("ab");
+		fixture.detectChanges();
+		vi.advanceTimersByTime(FILTER_DEBOUNCE_MS);
+		expect(emitted).toEqual([]);
+		input.value.set("abc");
+		fixture.detectChanges();
+		vi.advanceTimersByTime(FILTER_DEBOUNCE_MS);
+		input.value.set("");
+		fixture.detectChanges();
+		vi.advanceTimersByTime(FILTER_DEBOUNCE_MS);
+		expect(emitted).toEqual(["abc", ""]);
+	});
+});

package/dist/force-app/main/default/uiBundles/feature-angular-search/src/app/features/search/components/search-bar/search-bar.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,
+	DestroyRef,
+	effect,
+	inject,
+	input,
+	output,
+	signal,
+	untracked,
+} 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 { FILTER_DEBOUNCE_MS } from "../../utils/debounce";
+
+/**
+ * State-agnostic search box: a text input with a leading search icon. Keystrokes
+ * update a local draft immediately and are emitted on a trailing
+ * {@link FILTER_DEBOUNCE_MS}ms debounce. An empty value always emits (so the
+ * container can clear); when `minLength` is set, non-empty values whose trimmed
+ * length is below it are withheld.
+ */
+@Component({
+	selector: "app-search-bar",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [InputComponent],
+	host: { class: "flex-1 block" },
+	templateUrl: "./search-bar.html",
+})
+export class SearchBarComponent {
+	private readonly destroyRef = inject(DestroyRef);
+
+	readonly value = input<string>("");
+	readonly placeholder = input<string>("");
+	readonly label = input<string | undefined>(undefined);
+	readonly minLength = input<number | undefined>(undefined);
+	readonly valueChange = output<string>();
+
+	protected readonly draft = signal("");
+	private readonly commit$ = new Subject<string>();
+
+	constructor() {
+		this.commit$
+			.pipe(debounceTime(FILTER_DEBOUNCE_MS), takeUntilDestroyed(this.destroyRef))
+			.subscribe((v) => {
+				const min = this.minLength();
+				const len = v.trim().length;
+				if (min !== undefined && len > 0 && len < min) return;
+				this.valueChange.emit(v);
+			});
+
+		// Re-seed the draft when the bound value changes externally (URL restore, reset).
+		effect(() => {
+			const external = this.value();
+			untracked(() => {
+				if (external !== this.draft()) this.draft.set(external);
+			});
+		});
+	}
+
+	protected onInput(v: string): void {
+		this.draft.set(v);
+		this.commit$.next(v);
+	}
+}

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

@@ -0,0 +1,24 @@
+<div class="flex items-center gap-2" role="group" [attr.aria-label]="label()">
+	<span class="text-sm text-muted-foreground whitespace-nowrap">{{ label() }}</span>
+	<app-select
+		class="w-[160px]"
+		[options]="selectOptions()"
+		[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-search/src/app/features/search/components/sort-control/sort-control.spec.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { TestBed } from "@angular/core/testing";
+import { By } from "@angular/platform-browser";
+import { ButtonComponent } from "../../../../components/ui/button/button";
+import { SelectComponent } from "../../../../components/ui/select/select";
+import type { SortFieldConfig, SortState } from "../../types/sort.types";
+import { SortControlComponent } from "./sort-control";
+
+const OPTIONS: SortFieldConfig[] = [
+	{ field: "Name", label: "Name" },
+	{ field: "Industry", label: "Industry" },
+];
+
+describe("SortControlComponent", () => {
+	function setup(sort?: SortState) {
+		const fixture = TestBed.createComponent(SortControlComponent);
+		fixture.componentRef.setInput("options", OPTIONS);
+		fixture.componentRef.setInput("sort", sort);
+		const emitted: (SortState | undefined)[] = [];
+		fixture.componentInstance.sortChange.subscribe((v) => emitted.push(v));
+		fixture.detectChanges();
+		const select = () =>
+			fixture.debugElement.query(By.directive(SelectComponent))
+				.componentInstance as SelectComponent;
+		const button = () => fixture.debugElement.query(By.directive(ButtonComponent));
+		return { fixture, select, button, emitted };
+	}
+
+	it("offers Default plus the configured fields", () => {
+		const { select } = setup();
+		expect(
+			select()
+				.options()
+				.map((o) => o.label),
+		).toEqual(["Default", "Name", "Industry"]);
+		expect(select().value()).toBe("__none__");
+	});
+
+	it("emits ASC when a field is chosen with no active sort", () => {
+		const { select, emitted } = setup();
+		select().value.set("Name");
+		expect(emitted).toEqual([{ field: "Name", direction: "ASC" }]);
+	});
+
+	it("keeps the current direction when switching field", () => {
+		const { select, emitted } = setup({ field: "Name", direction: "DESC" });
+		select().value.set("Industry");
+		expect(emitted).toEqual([{ field: "Industry", direction: "DESC" }]);
+	});
+
+	it("emits undefined when Default is chosen", () => {
+		const { select, emitted } = setup({ field: "Name", direction: "ASC" });
+		select().value.set("__none__");
+		expect(emitted).toEqual([undefined]);
+	});
+
+	it("hides the direction button without a sort and toggles it with one", () => {
+		expect(setup().button()).toBeNull();
+		const { button, emitted } = setup({ field: "Name", direction: "ASC" });
+		button().componentInstance.clicked.emit(new MouseEvent("click"));
+		expect(emitted).toEqual([{ field: "Name", direction: "DESC" }]);
+	});
+});

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

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, computed, input, output } 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 type { SortFieldConfig, SortState } from "../../types/sort.types";
+
+/** Sentinel value used in the select to represent "no sort". */
+const NONE_VALUE = "__none__";
+
+/**
+ * State-agnostic sort field + direction toggle. Choosing a field applies ASC by
+ * default (keeping the current direction if one is active); the direction button
+ * flips ASC/DESC and only appears while a sort is active. Selecting `Default`
+ * emits `undefined`.
+ */
+@Component({
+	selector: "app-sort-control",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [ButtonComponent, IconComponent, SelectComponent],
+	templateUrl: "./sort-control.html",
+})
+export class SortControlComponent {
+	readonly options = input.required<SortFieldConfig[]>();
+	readonly sort = input<SortState | undefined>(undefined);
+	readonly label = input<string>("Sort by");
+	readonly sortChange = output<SortState | undefined>();
+
+	protected readonly selectOptions = computed<AppSelectOption[]>(() => [
+		{ value: NONE_VALUE, label: "Default" },
+		...this.options().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.sortChange.emit(undefined);
+			return;
+		}
+		this.sortChange.emit({ field, direction: this.sort()?.direction ?? "ASC" });
+	}
+
+	protected toggleDirection(): void {
+		const current = this.sort();
+		if (!current) return;
+		this.sortChange.emit({
+			field: current.field,
+			direction: current.direction === "ASC" ? "DESC" : "ASC",
+		});
+	}
+}