@salesforce/ui-bundle-template-feature-react-search 11.3.0

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/filters/inputs/SelectFilter.tsx

@@ -0,0 +1,46 @@
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../../components/ui/select";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+
+const ALL_VALUE = "__all__";
+
+interface SelectFilterProps {
+	field: string;
+	label: string;
+	options: Array<{ value: string; label: string }>;
+	helpText?: string;
+}
+
+export function SelectFilter({ field, label, options, helpText }: SelectFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const id = `filter-${field}`;
+	return (
+		<FilterFieldWrapper label={label} htmlFor={id} helpText={helpText}>
+			<Select
+				value={value?.value ?? ALL_VALUE}
+				onValueChange={(v) => {
+					if (v === ALL_VALUE) onChange(undefined);
+					else onChange({ field, label, type: "picklist", value: v });
+				}}
+			>
+				<SelectTrigger id={id} className="w-full">
+					<SelectValue placeholder={`Select ${label.toLowerCase()}`} />
+				</SelectTrigger>
+				<SelectContent>
+					<SelectItem value={ALL_VALUE}>All</SelectItem>
+					{options.map((opt) => (
+						<SelectItem key={opt.value} value={opt.value}>
+							{opt.label}
+						</SelectItem>
+					))}
+				</SelectContent>
+			</Select>
+		</FilterFieldWrapper>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/filters/inputs/TextFilter.tsx

@@ -0,0 +1,52 @@
+import { useEffect, useRef, useState } from "react";
+import { Input } from "../../../../../components/ui/input";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+import { debounce, FILTER_DEBOUNCE_MS } from "../../../utils/debounce";
+
+interface TextFilterProps {
+	field: string;
+	label: string;
+	placeholder?: string;
+	helpText?: string;
+}
+
+export function TextFilter({ field, label, placeholder, helpText }: TextFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const [draft, setDraft] = useState(value?.value ?? "");
+
+	const onChangeRef = useRef(onChange);
+	useEffect(() => {
+		onChangeRef.current = onChange;
+	});
+	// Build the debounced caller in a mount effect, not during render: creating it
+	// inline would read onChangeRef.current at render time (react-hooks/refs). It
+	// stays a single stable instance and always calls the latest onChange via the ref.
+	const debouncedRef = useRef<((next: string) => void) | undefined>(undefined);
+	useEffect(() => {
+		debouncedRef.current = debounce((next: string) => {
+			if (next === "") onChangeRef.current(undefined);
+			else onChangeRef.current({ field, label, type: "text", value: next });
+		}, FILTER_DEBOUNCE_MS);
+	}, [field, label]);
+
+	useEffect(() => {
+		setDraft(value?.value ?? "");
+	}, [value?.value]);
+
+	const id = `filter-${field}`;
+	return (
+		<FilterFieldWrapper label={label} htmlFor={id} helpText={helpText}>
+			<Input
+				id={id}
+				type="text"
+				value={draft}
+				placeholder={placeholder}
+				onChange={(e) => {
+					setDraft(e.target.value);
+					debouncedRef.current?.(e.target.value);
+				}}
+			/>
+		</FilterFieldWrapper>
+	);
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/components/results/DefaultResultRow.tsx

@@ -0,0 +1,109 @@
+/**
+ * Default per-node row used when no `renderResult` is supplied for a source.
+ *
+ * Layout:
+ *   - Title: first entry in `displayFields` (preferring displayValue).
+ *   - Subtitle: remaining display fields joined with " · ".
+ *   - When `routePattern` is configured on the source, the row is wrapped in
+ *     a react-router `<Link>` whose `to` is built by substituting `:fieldName`
+ *     tokens with the corresponding field values (special token `:id`
+ *     resolves to the configured `idField`, default "Id").
+ *
+ * Applications can still pass `renderResult[sourceKey]` to override.
+ */
+
+import type { ReactNode } from "react";
+import { Link } from "react-router";
+import { fieldValue } from "../../utils/fieldUtils";
+import type { DisplayField, SObjectSourceConfig } from "../../types";
+
+const ROUTE_TOKEN = /:([A-Za-z_][A-Za-z0-9_]*)/g;
+
+function fieldName(f: DisplayField): string {
+	return typeof f === "string" ? f : f.name;
+}
+
+/** Resolves a single dot-path against a node, returning a string or null. */
+function readPath(node: unknown, path: string): string | null {
+	if (!node || typeof node !== "object") return null;
+	const parts = path.split(".");
+	let cursor: unknown = node;
+	for (let i = 0; i < parts.length - 1; i++) {
+		if (!cursor || typeof cursor !== "object") return null;
+		cursor = (cursor as Record<string, unknown>)[parts[i]];
+	}
+	const leaf = (cursor as Record<string, unknown> | null)?.[parts[parts.length - 1]];
+	if (leaf == null) return null;
+	if (typeof leaf === "object") {
+		return fieldValue(leaf as { value?: unknown; displayValue?: string | null });
+	}
+	return String(leaf);
+}
+
+/** Reads the user-facing string for a top-level display field. */
+function readDisplayField(node: unknown, field: DisplayField): string | null {
+	if (typeof field === "string") return readPath(node, field);
+	if ("raw" in field) return readPath(node, field.name);
+	// Relationship: prefer the first scalar subfield's display value.
+	const sub = field.subfields[0];
+	if (!sub) return null;
+	const subName = fieldName(sub);
+	return readPath(node, `${field.name}.${subName}`);
+}
+
+/** Substitutes `:fieldName` tokens in routePattern with node values. */
+function resolveRoute(pattern: string, node: unknown, idField: string): string | null {
+	let failed = false;
+	const out = pattern.replace(ROUTE_TOKEN, (_, token) => {
+		const path = token === "id" ? idField : token;
+		const value = readPath(node, path);
+		if (value == null) {
+			failed = true;
+			return "";
+		}
+		return encodeURIComponent(value);
+	});
+	return failed ? null : out;
+}
+
+interface DefaultResultRowProps {
+	node: unknown;
+	source: SObjectSourceConfig;
+}
+
+export function DefaultResultRow({ node, source }: DefaultResultRowProps) {
+	const idField = source.idField ?? "Id";
+	const fields = source.displayFields;
+	const titleField = fields[0];
+	const title = titleField ? readDisplayField(node, titleField) : null;
+
+	const subtitleParts = fields
+		.slice(1)
+		.map((f) => readDisplayField(node, f))
+		.filter((s): s is string => s != null && s !== "");
+
+	const content: ReactNode = (
+		<>
+			<span className="font-medium">{title ?? "—"}</span>
+			{subtitleParts.length > 0 && (
+				<p className="text-sm text-muted-foreground">{subtitleParts.join(" · ")}</p>
+			)}
+		</>
+	);
+
+	if (source.routePattern) {
+		const href = resolveRoute(source.routePattern, node, idField);
+		if (href) {
+			return (
+				<Link
+					to={href}
+					className="block hover:bg-accent rounded-md px-3 -mx-3 py-1 transition-colors"
+				>
+					{content}
+				</Link>
+			);
+		}
+	}
+
+	return <div className="px-3 -mx-3 py-1">{content}</div>;
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/config.json

@@ -0,0 +1,82 @@
+{
+  "sources": [
+    {
+      "kind": "sobject",
+      "key": "accounts",
+      "objectName": "Account",
+      "label": "Accounts",
+      "routePattern": "/accounts/:id",
+      "searchableFields": ["Name", "Phone", "Industry"],
+      "displayFields": [
+        "Name",
+        "Industry",
+        "Type",
+        "Phone",
+        "AnnualRevenue",
+        { "name": "Owner", "subfields": ["Name"] }
+      ],
+      "filterFields": [
+        { "field": "Industry", "label": "Industry", "type": "picklist" },
+        { "field": "Type", "label": "Type", "type": "picklist" },
+        { "field": "AnnualRevenue", "label": "Annual Revenue", "type": "numeric" }
+      ],
+      "sortFields": [
+        { "field": "Name", "label": "Name" },
+        { "field": "Industry", "label": "Industry" },
+        { "field": "AnnualRevenue", "label": "Annual Revenue" },
+        { "field": "CreatedDate", "label": "Created Date" }
+      ],
+      "pageSize": 10,
+      "validPageSizes": [5, 10, 20]
+    },
+    {
+      "kind": "sobject",
+      "key": "contacts",
+      "objectName": "Contact",
+      "label": "Contacts",
+      "routePattern": "/contacts/:id",
+      "searchableFields": ["Name", "Email", "Phone"],
+      "displayFields": [
+        "Name",
+        "Title",
+        "Email",
+        "Phone",
+        { "name": "Account", "subfields": ["Name"] }
+      ],
+      "sortFields": [
+        { "field": "Name", "label": "Name" },
+        { "field": "CreatedDate", "label": "Created Date" }
+      ],
+      "pageSize": 10,
+      "validPageSizes": [5, 10, 20]
+    },
+    {
+      "kind": "sobject",
+      "key": "opportunities",
+      "objectName": "Opportunity",
+      "label": "Opportunities",
+      "routePattern": "/opportunities/:id",
+      "searchableFields": ["Name"],
+      "displayFields": [
+        "Name",
+        "StageName",
+        "Amount",
+        "CloseDate",
+        { "name": "Account", "subfields": ["Name"] }
+      ],
+      "filterFields": [
+        { "field": "StageName", "label": "Stage", "type": "picklist" },
+        { "field": "Amount", "label": "Amount", "type": "numeric" },
+        { "field": "CloseDate", "label": "Close Date", "type": "daterange" }
+      ],
+      "sortFields": [
+        { "field": "CloseDate", "label": "Close Date" },
+        { "field": "Amount", "label": "Amount" },
+        { "field": "Name", "label": "Name" }
+      ],
+      "defaultSort": { "field": "CloseDate", "direction": "DESC" },
+      "pageSize": 10,
+      "validPageSizes": [5, 10, 20]
+    }
+  ]
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/hooks/useAsyncData.ts

@@ -0,0 +1,56 @@
+import { useEffect, useRef, useState } from "react";
+
+interface UseAsyncDataResult<T> {
+	data: T | null;
+	loading: boolean;
+	error: string | null;
+}
+
+/**
+ * Runs an async fetcher on mount and whenever `deps` change. Stale responses
+ * (deps changed during a fetch, or component unmounted) are dropped via a
+ * cancellation flag.
+ */
+export function useAsyncData<T>(
+	fetcher: () => Promise<T>,
+	deps: React.DependencyList,
+): UseAsyncDataResult<T> {
+	const [data, setData] = useState<T | null>(null);
+	const [loading, setLoading] = useState(true);
+	const [error, setError] = useState<string | null>(null);
+	const [generation, setGeneration] = useState(0);
+
+	const fetcherRef = useRef(fetcher);
+	useEffect(() => {
+		fetcherRef.current = fetcher;
+	});
+
+	const [prevDeps, setPrevDeps] = useState(deps);
+	if (deps.length !== prevDeps.length || deps.some((d, i) => d !== prevDeps[i])) {
+		setPrevDeps(deps);
+		setGeneration((g) => g + 1);
+		if (!loading) setLoading(true);
+		if (error !== null) setError(null);
+	}
+
+	useEffect(() => {
+		let cancelled = false;
+		fetcherRef
+			.current()
+			.then((result) => {
+				if (!cancelled) setData(result);
+			})
+			.catch((err) => {
+				console.error(err);
+				if (!cancelled) setError(err instanceof Error ? err.message : "An error occurred");
+			})
+			.finally(() => {
+				if (!cancelled) setLoading(false);
+			});
+		return () => {
+			cancelled = true;
+		};
+	}, [generation]);
+
+	return { data, loading, error };
+}

package/dist/force-app/main/default/uiBundles/feature-react-search/src/features/search/hooks/useDistinctValues.ts

@@ -0,0 +1,59 @@
+/**
+ * Caches and serves distinct picklist values fetched via the GraphQL
+ * aggregate API. The cache key is `${objectName}.${fieldName}`; entries
+ * persist for the lifetime of the page so repeated mounts of the same
+ * picklist filter share the same response.
+ *
+ * Pass `null` to short-circuit the fetch (e.g. when inline options are
+ * available on the filter config).
+ */
+
+import { useEffect, useState } from "react";
+import { fetchDistinctValues, type PicklistOption } from "../api/distinctValuesService";
+
+const cache = new Map<string, PicklistOption[]>();
+const inflight = new Map<string, Promise<PicklistOption[]>>();
+
+interface DistinctValuesQuery {
+	objectName: string;
+	fieldName: string;
+}
+
+export function useDistinctValues(query: DistinctValuesQuery | null): PicklistOption[] | null {
+	const cacheKey = query ? `${query.objectName}.${query.fieldName}` : null;
+	const [options, setOptions] = useState<PicklistOption[] | null>(() =>
+		cacheKey ? (cache.get(cacheKey) ?? null) : null,
+	);
+
+	useEffect(() => {
+		if (!query || !cacheKey) return;
+		const cached = cache.get(cacheKey);
+		if (cached) {
+			setOptions(cached);
+			return;
+		}
+		let cancelled = false;
+		const existing = inflight.get(cacheKey);
+		const promise =
+			existing ??
+			fetchDistinctValues(query.objectName, query.fieldName).then((result) => {
+				cache.set(cacheKey, result);
+				inflight.delete(cacheKey);
+				return result;
+			});
+		if (!existing) inflight.set(cacheKey, promise);
+		promise
+			.then((result) => {
+				if (!cancelled) setOptions(result);
+			})
+			.catch((err: unknown) => {
+				inflight.delete(cacheKey);
+				console.error(`Failed to fetch distinct values for ${cacheKey}:`, err);
+			});
+		return () => {
+			cancelled = true;
+		};
+	}, [cacheKey, query]);
+
+	return options;
+}