@salesforce/templates 66.13.4 → 66.13.6

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/components/filters/inputs/MultiSelectFilter.tsx

@@ -0,0 +1,89 @@
+import { ChevronDown } from "lucide-react";
+import { Button } from "../../../../../components/ui/button";
+import { Checkbox } from "../../../../../components/ui/checkbox";
+import { Label } from "../../../../../components/ui/label";
+import {
+	Popover,
+	PopoverContent,
+	PopoverTrigger,
+} from "../../../../../components/ui/popover";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+
+interface MultiSelectFilterProps {
+	field: string;
+	label: string;
+	options: Array<{ value: string; label: string }>;
+	helpText?: string;
+}
+
+export function MultiSelectFilter({ field, label, options, helpText }: MultiSelectFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const selected = new Set(value?.value ? value.value.split(",").filter(Boolean) : []);
+
+	const toggle = (v: string, on: boolean) => {
+		const next = new Set(selected);
+		if (on) next.add(v);
+		else next.delete(v);
+		const joined = Array.from(next).join(",");
+		if (joined === "") onChange(undefined);
+		else onChange({ field, label, type: "multipicklist", value: joined });
+	};
+
+	// Summarize the selection on the collapsed trigger: the sole label when one is
+	// picked, a count when several are, and a placeholder when none.
+	const summary =
+		selected.size === 0
+			? `Select ${label.toLowerCase()}`
+			: selected.size === 1
+				? (options.find((o) => selected.has(o.value))?.label ?? `${selected.size} selected`)
+				: `${selected.size} selected`;
+	const triggerId = `filter-${field}`;
+
+	return (
+		<FilterFieldWrapper label={label} htmlFor={triggerId} helpText={helpText}>
+			<Popover>
+				<PopoverTrigger asChild>
+					<Button
+						id={triggerId}
+						variant="outline"
+						className="w-full justify-between font-normal"
+						aria-label={`${label}: ${summary}`}
+					>
+						<span className={`truncate ${selected.size === 0 ? "text-foreground/70" : ""}`}>
+							{summary}
+						</span>
+						<ChevronDown className="ml-2 size-4 shrink-0 opacity-50" aria-hidden="true" />
+					</Button>
+				</PopoverTrigger>
+				<PopoverContent
+					align="start"
+					aria-label={label}
+					className="w-(--radix-popover-trigger-width) max-h-72 overflow-y-auto"
+				>
+					<div role="group" className="flex flex-col gap-1">
+						{options.length === 0 ? (
+							<p className="px-1 py-2 text-sm text-muted-foreground">No options available.</p>
+						) : (
+							options.map((opt) => {
+								const id = `filter-${field}-${opt.value}`;
+								return (
+									<div key={opt.value} className="flex items-center gap-2">
+										<Checkbox
+											id={id}
+											checked={selected.has(opt.value)}
+											onCheckedChange={(checked) => toggle(opt.value, checked === true)}
+										/>
+										<Label htmlFor={id} className="text-sm font-normal cursor-pointer">
+											{opt.label}
+										</Label>
+									</div>
+								);
+							})
+						)}
+					</div>
+				</PopoverContent>
+			</Popover>
+		</FilterFieldWrapper>
+	);
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/components/filters/inputs/NumericRangeFilter.tsx

@@ -0,0 +1,108 @@
+import { useEffect, useId, 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 NumericRangeFilterProps {
+	field: string;
+	label: string;
+	helpText?: string;
+	min?: number;
+	max?: number;
+}
+
+export function NumericRangeFilter({ field, label, helpText, min, max }: NumericRangeFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const errorId = useId();
+	const [draftMin, setDraftMin] = useState(value?.min ?? "");
+	const [draftMax, setDraftMax] = useState(value?.max ?? "");
+
+	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<((nextMin: string, nextMax: string) => void) | undefined>(undefined);
+	useEffect(() => {
+		debouncedRef.current = debounce((nextMin: string, nextMax: string) => {
+			if (!nextMin && !nextMax) onChangeRef.current(undefined);
+			else
+				onChangeRef.current({
+					field,
+					label,
+					type: "numeric",
+					min: nextMin || undefined,
+					max: nextMax || undefined,
+				});
+		}, FILTER_DEBOUNCE_MS);
+	}, [field, label]);
+
+	useEffect(() => {
+		setDraftMin(value?.min ?? "");
+		setDraftMax(value?.max ?? "");
+	}, [value?.min, value?.max]);
+
+	const isOutOfBounds = (v: string) => {
+		if (v === "") return false;
+		const n = Number(v);
+		return (min != null && n < min) || (max != null && n > max);
+	};
+	const minOutOfBounds = isOutOfBounds(draftMin);
+	const maxOutOfBounds = isOutOfBounds(draftMax);
+	const isRangeInverted = draftMin !== "" && draftMax !== "" && Number(draftMin) > Number(draftMax);
+	const hasError = minOutOfBounds || maxOutOfBounds || isRangeInverted;
+
+	const boundsLabel =
+		min != null && max != null
+			? `${min}–${max}`
+			: min != null
+				? `${min} or more`
+				: max != null
+					? `${max} or less`
+					: null;
+
+	const errorMessage = isRangeInverted
+		? "Min must not exceed max"
+		: (minOutOfBounds || maxOutOfBounds) && boundsLabel
+			? `Value must be between ${boundsLabel}`
+			: undefined;
+
+	return (
+		<FilterFieldWrapper label={label} helpText={helpText} error={errorMessage} errorId={errorId}>
+			<div className="flex items-center gap-2">
+				<Input
+					type="number"
+					placeholder="Min"
+					min={min}
+					max={max}
+					value={draftMin}
+					onChange={(e) => {
+						setDraftMin(e.target.value);
+						debouncedRef.current?.(e.target.value, draftMax);
+					}}
+					aria-label={`${label} minimum`}
+					aria-invalid={hasError || undefined}
+					aria-describedby={hasError ? errorId : undefined}
+				/>
+				<span className="text-sm text-muted-foreground">–</span>
+				<Input
+					type="number"
+					placeholder="Max"
+					min={min}
+					max={max}
+					value={draftMax}
+					onChange={(e) => {
+						setDraftMax(e.target.value);
+						debouncedRef.current?.(draftMin, e.target.value);
+					}}
+					aria-label={`${label} maximum`}
+					aria-invalid={hasError || undefined}
+					aria-describedby={hasError ? errorId : undefined}
+				/>
+			</div>
+		</FilterFieldWrapper>
+	);
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/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/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/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/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/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/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/config.json

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

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/{_os_ → search}/hooks/useAsyncData.ts

@@ -7,13 +7,9 @@ interface UseAsyncDataResult<T> {
 }
 
 /**
- * Runs an async fetcher on mount and whenever `deps` change.
- * Returns the loading/error/data state. Does not cache — every call
- * to the fetcher hits the source directly.
- *
- * A cleanup flag prevents state updates if the component unmounts
- * or deps change before the fetch completes (avoids React warnings
- * and stale updates from out-of-order responses).
+ * 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>,
@@ -29,7 +25,6 @@ export function useAsyncData<T>(
 		fetcherRef.current = fetcher;
 	});
 
-	// Detect dep changes during render to reset loading state and bump generation
 	const [prevDeps, setPrevDeps] = useState(deps);
 	if (deps.length !== prevDeps.length || deps.some((d, i) => d !== prevDeps[i])) {
 		setPrevDeps(deps);
@@ -40,7 +35,6 @@ export function useAsyncData<T>(
 
 	useEffect(() => {
 		let cancelled = false;
-
 		fetcherRef
 			.current()
 			.then((result) => {
@@ -53,7 +47,6 @@ export function useAsyncData<T>(
 			.finally(() => {
 				if (!cancelled) setLoading(false);
 			});
-
 		return () => {
 			cancelled = true;
 		};

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/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;
+}