@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/state/search-state.types.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import type { ActiveFilterValue } from "../types/filter.types";
+import type { SourceConfig } from "../types/search-config.types";
+import type { SourceResult } from "../types/search-result.types";
+import type { SortState } from "../types/sort.types";
+
+/** Mutable per-source state (filters / sort / cursor pagination). */
+export interface SourceLocalState {
+	filters: ActiveFilterValue[];
+	sort: SortState | null;
+	pageSize: number;
+	pageIndex: number;
+	afterCursor: string | undefined;
+	/** Cursors of the pages already visited; popped by "previous". */
+	cursorStack: string[];
+}
+
+/** Read-only snapshot of one source: its config, latest result, and state. */
+export interface SourceView {
+	config: SourceConfig;
+	result: SourceResult | null;
+	/** Per-source failure message (a sibling may still have succeeded). */
+	error: string | null;
+	filters: ActiveFilterValue[];
+	sort: SortState | null;
+	pageSize: number;
+	pageIndex: number;
+	hasNextPage: boolean;
+	hasPreviousPage: boolean;
+}
+
+/**
+ * Locks the search to a single source: hides the scope selector and fetches
+ * only that source. `kind` + `key` must both match a configured source.
+ */
+export interface RestrictTo {
+	kind: SourceConfig["kind"];
+	key: string;
+}
+
+export interface SearchInitOptions {
+	/** Source key (or `"all"`) to lock the scope to. */
+	lockedScope?: string;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+export type FilterFieldType =
+	| "text"
+	| "picklist"
+	| "numeric"
+	| "boolean"
+	| "date"
+	| "daterange"
+	| "datetime"
+	| "datetimerange"
+	| "multipicklist";
+
+/**
+ * Which comparison UI a date/datetime filter exposes:
+ *   - `"range"`: a single Between control (two date inputs, lower-upper bound).
+ *   - `"comparison"`: an After / Before selector with one date input.
+ *   - `"both"`: a Between / After / Before selector that switches between the two.
+ *
+ * Applies only to the date-family types; defaults to `"comparison"`.
+ */
+export type DateFilterMode = "range" | "comparison" | "both";
+
+export type FilterFieldConfig<TFieldName extends string = string> = {
+	field: TFieldName;
+	label: string;
+	type: FilterFieldType;
+	placeholder?: string;
+	/**
+	 * Required for picklist / multipicklist. Multipicklist selections travel as a
+	 * comma-joined string (URL and `ActiveFilterValue.value`), so an option value
+	 * containing a comma cannot be selected reliably.
+	 */
+	options?: Array<{ value: string; label: string }>;
+	/** Date-family only. Defaults to `"comparison"`. */
+	dateMode?: DateFilterMode;
+	helpText?: string;
+	// Numeric-family only.
+	min?: number;
+	max?: number;
+};
+
+export type ActiveFilterValue<TFieldName extends string = string> = {
+	field: TFieldName;
+	label: string;
+	type: FilterFieldType;
+	value?: string;
+	min?: string;
+	max?: string;
+};
+
+/** Picklist option shape shared with filter components. */
+export type PicklistOption = { value: string; label: string };

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

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+export * from "./filter.types";
+export * from "./sort.types";
+export * from "./search-config.types";
+export * from "./search-result.types";
+export * from "./scope.types";

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

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/** `"all"` or the `key` of a configured source. */
+export type SearchScope = "all" | string;
+
+export const ALL_SCOPE = "all" as const;

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

@@ -0,0 +1,110 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Configuration types for unified (multi-source) search.
+ *
+ * The application declares a SearchConfig with one entry per searchable
+ * backend. Today every source is an SObject queried via the uiapi GraphQL
+ * bridge; a new backend plugs in by adding a `kind` to {@link SourceConfig}
+ * and registering a matching adapter (see `adapters/registry.ts`).
+ */
+import type { FilterFieldConfig } from "./filter.types";
+import type { SortFieldConfig, SortState } from "./sort.types";
+
+/**
+ * A single field to include in the GraphQL selection set of an SObject source.
+ *
+ * - `"Name"` (string shorthand): emits `Name @optional { value displayValue }`.
+ * - `{ name, subfields }`: emits a nested selection (relationship traversal).
+ * - `{ name, raw: true }`: emits the bare field name.
+ *
+ * The configured `idField` (default: "Id") is added automatically; do not list
+ * it explicitly.
+ */
+export type DisplayField =
+	string | { name: string; raw: true } | { name: string; subfields: DisplayField[] };
+
+/** Configuration for one SObject source in a search experience. */
+export interface SObjectSourceConfig {
+	/** Discriminator, selects the runtime adapter. */
+	kind: "sobject";
+	/**
+	 * Stable identifier. Used as the GraphQL alias, the URL namespace, and the
+	 * result-map key. Must match `/^[A-Za-z_][A-Za-z0-9_]*$/`.
+	 */
+	key: string;
+	/** GraphQL object name (e.g. "Account", "Contact"). */
+	objectName: string;
+	/** Plural display label (section headers, scope dropdown, empty states). */
+	label: string;
+	/** Singular display label for one record. Falls back to `label`. */
+	labelSingular?: string;
+	/** Field name that uniquely identifies a record. Defaults to "Id". */
+	idField?: string;
+	/**
+	 * URL pattern used by the default renderer to build a result link. Tokens of
+	 * the form `:fieldName` are replaced with the field's value (`:id` resolves
+	 * to the record's `idField`). Omit for non-clickable rows.
+	 */
+	routePattern?: string;
+	/**
+	 * Fields the global `q` term matches against, built into an `or` of
+	 * `like %q%`. Supports dot-notation for relationship fields ("Owner.Name").
+	 */
+	searchableFields: string[];
+	/** Fields in the GraphQL selection set. The id field is added automatically. */
+	displayFields: DisplayField[];
+	/** Optional structured filters for this source. */
+	filterBy?: FilterFieldConfig[];
+	/** Optional sort options surfaced in the per-source sort control. */
+	sortBy?: SortFieldConfig[];
+	/** Initial sort applied when no URL sort is present. */
+	defaultSort?: SortState;
+	/** GraphQL type name for `where`. Defaults to `${objectName}_Filter`. */
+	whereTypeName?: string;
+	/** GraphQL type name for `orderBy`. Defaults to `${objectName}_OrderBy`. */
+	orderByTypeName?: string;
+}
+
+/**
+ * Discriminated union of every source kind a search experience can query. New
+ * backends extend this union with a new `kind` plus a matching adapter.
+ */
+export type SourceConfig = SObjectSourceConfig;
+
+export type PaginationMode = "per-source" | "merged";
+export type MergeOrder = "sequential" | "interleaved" | "proportional";
+
+/**
+ * One global pagination config for the whole search experience; there is no
+ * per-source pagination.
+ */
+export interface SearchPaginationConfig {
+	/**
+	 *   - `"per-source"` (default): each source advances its own cursor; a page
+	 *     can hold up to `sources x pageSize` items.
+	 *   - `"merged"`: treat the cumulative result set as one list and window it
+	 *     into fixed pages of `pageSize`.
+	 */
+	mode?: PaginationMode;
+	/**
+	 * In `"merged"` mode, how nodes from different sources are ordered:
+	 * `"sequential"` (default), `"interleaved"` (round-robin) or
+	 * `"proportional"` (spread by each source's result count).
+	 */
+	mergeOrder?: MergeOrder;
+	/** Items per page (across all sources in `"merged"` mode; per source otherwise). */
+	pageSize: number;
+	/** Page sizes offered in the "results per page" control. */
+	pageSizeOptions: number[];
+}
+
+/** Top-level search config. */
+export interface SearchConfig {
+	sources: SourceConfig[];
+	/** Defaults to per-source mode, page size 10, options `[10, 25, 50]`. */
+	pagination?: SearchPaginationConfig;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import type { SourceConfig } from "./search-config.types";
+import type { ActiveFilterValue } from "./filter.types";
+import type { SortState } from "./sort.types";
+
+export interface SourcePageInfo {
+	hasNextPage: boolean;
+	hasPreviousPage: boolean;
+	endCursor: string | null;
+	startCursor: string | null;
+}
+
+/**
+ * Per-source result. Nodes are `unknown` at the library boundary; the
+ * application narrows them when rendering.
+ */
+export interface SourceResult {
+	nodes: unknown[];
+	pageInfo: SourcePageInfo | null;
+	totalCount: number | null;
+}
+
+/**
+ * The outcome of a combined `runSearch`: parsed results plus a per-source error
+ * map. A source appears in at most one of `results` / `errors`.
+ */
+export interface RunSearchOutcome {
+	results: Record<string, SourceResult>;
+	errors: Record<string, string>;
+}
+
+/** One result node tagged with the source it came from. */
+export interface MergedResultItem {
+	/** The `key` of the source this node came from. */
+	sourceKey: string;
+	/** The raw result node. */
+	node: unknown;
+}
+
+/** A per-source search request handed to the query builder and adapters. */
+export interface SourceRequest<T extends SourceConfig = SourceConfig> {
+	source: T;
+	/** The global search term, broadcast to every source. */
+	q: string;
+	filters: ActiveFilterValue[];
+	sort: SortState | null;
+	pageSize: number;
+	/** Opaque forward cursor for this fetch. */
+	afterCursor: string | undefined;
+}
+
+/** Aggregate pagination data across the in-scope sources (no behaviour). */
+export interface GlobalPaginationState {
+	/** Current global page, 0-based. */
+	pageIndex: number;
+	/** `0` when there are no results, otherwise `>= 1`. */
+	pageCount: number;
+	pageSize: number;
+	pageSizeOptions: readonly number[];
+	hasNextPage: boolean;
+	hasPreviousPage: boolean;
+	/** Cumulative result count summed across in-scope sources. */
+	totalCount: number;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+export type SortFieldConfig<TFieldName extends string = string> = {
+	field: TFieldName;
+	label: string;
+};
+
+export type SortState<TFieldName extends string = string> = {
+	field: TFieldName;
+	direction: "ASC" | "DESC";
+};

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

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/** Default debounce delay for keystroke-driven inputs. */
+export const FILTER_DEBOUNCE_MS = 300;
+
+/**
+ * Creates a debounced version of `fn`. Each call resets the internal timer;
+ * `fn` runs only after the timer expires without being reset.
+ */
+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-search/src/app/features/search/utils/field-utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Helpers for reading values out of uiapi GraphQL response nodes.
+ *
+ * Nodes typically come back wrapped as `{ value, displayValue }`. `fieldValue`
+ * picks the user-facing string (preferring displayValue) or returns null.
+ */
+
+export function fieldValue(
+	field: { displayValue?: string | null; value?: unknown } | null | undefined,
+): string | null {
+	if (field?.displayValue != null) return field.displayValue;
+	if (field?.value != null) return String(field.value);
+	return null;
+}