@salesforce/templates 66.13.5 → 66.13.7

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/CmsResultRow.tsx

@@ -0,0 +1,101 @@
+/**
+ * Per-node row for a CMS source. Used by both the per-source section
+ * (`SearchResults`) and the merged grid (`MergedSearchResults`) via the shared
+ * `resolveResultRenderer` (UI-owned) whenever `source.kind === "cms"`.
+ *
+ * Renders a title, a published-date subtitle, an optional content-type badge,
+ * and a react-router `<Link>` when a route can be built.
+ *
+ * Link target:
+ *   - `source.routePattern` tokens: `:id` (managedContentId), `:key`
+ *     (managedContentKey), `:contentType` (contentType).
+ *   - falls back to `/content/:contentType/:id` when no `routePattern` is
+ *     configured.
+ *
+ * The content-type label is rendered only when its FQN passes `isValidCmsFqn`.
+ */
+
+import type { ReactNode } from "react";
+import { Link } from "react-router";
+import type { CmsSourceConfig, CmsSearchItem } from "../../adapters/cms/types";
+import { formatContentTypeLabel, isValidCmsFqn } from "../../adapters/cms/contentTypeUtils";
+
+/** Formats an ISO date string for display; echoes the raw string on failure. */
+function formatPublishedDate(dateStr: string): string {
+	const date = new Date(dateStr);
+	if (isNaN(date.getTime())) return dateStr;
+	return date.toLocaleDateString(undefined, {
+		year: "numeric",
+		month: "short",
+		day: "numeric",
+	});
+}
+
+/**
+ * Substitutes `:id` / `:key` / `:contentType` tokens in a route pattern with
+ * the item's values (URL-encoded). Returns `null` if a required token has no
+ * value.
+ */
+function resolveRoute(pattern: string, item: CmsSearchItem): string | null {
+	const tokens: Record<string, string | undefined> = {
+		id: item.managedContentId,
+		key: item.managedContentKey,
+		contentType: item.contentType,
+	};
+	let failed = false;
+	const out = pattern.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_match, token: string) => {
+		const value = tokens[token];
+		if (value == null || value === "") {
+			failed = true;
+			return "";
+		}
+		return encodeURIComponent(value);
+	});
+	return failed ? null : out;
+}
+
+interface CmsResultRowProps {
+	node: unknown;
+	source: CmsSourceConfig;
+}
+
+export function CmsResultRow({ node, source }: CmsResultRowProps) {
+	const item = node as CmsSearchItem;
+
+	const publishedDate = item.managedContentChannelDeliveryDetails?.[0]?.publishedDate;
+	const showType = typeof item.contentType === "string" && isValidCmsFqn(item.contentType);
+
+	const subtitleParts: string[] = [];
+	if (showType) subtitleParts.push(formatContentTypeLabel(item.contentType));
+	if (publishedDate) subtitleParts.push(`Published: ${formatPublishedDate(publishedDate)}`);
+
+	const content: ReactNode = (
+		<>
+			<span className="font-medium">{item.title ?? "—"}</span>
+			{item.highlightedSnippet && (
+				<p className="text-sm text-muted-foreground">{item.highlightedSnippet}</p>
+			)}
+			{subtitleParts.length > 0 && (
+				<p className="text-sm text-muted-foreground">{subtitleParts.join(" · ")}</p>
+			)}
+		</>
+	);
+
+	// Only render a drill-down link when the source explicitly configures a
+	// routePattern. Without one, content rows render as plain (non-linked) rows
+	// so they never navigate to an unbuilt detail route.
+	const href = source.routePattern ? resolveRoute(source.routePattern, item) : null;
+	if (href) {
+		return (
+			<Link
+				to={href}
+				className="block hover:bg-accent rounded-md px-3 -mx-3 py-1 transition-colors"
+				aria-label={`View content: ${item.title}`}
+			>
+				{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/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/components/results/resolveResultRenderer.ts

@@ -0,0 +1,49 @@
+/**
+ * Single source of truth for choosing how one source's result node is rendered.
+ *
+ * Every result layout (`SearchResults`, `MergedSearchResults`, and any future
+ * grid/list) MUST resolve its per-node renderer through this helper so the
+ * kind-aware default can never be missed in one mode. The rule, in order:
+ *
+ *   1. A `renderResult[source.key]` config override wins in EVERY mode —
+ *      including `false`, which hides the source entirely.
+ *   2. Otherwise `source.kind === "cms"` → {@link CmsResultRow}.
+ *   3. Otherwise (SObject) → {@link DefaultResultRow}.
+ *
+ * Returning the same union the callers already use (`renderer | false`) lets a
+ * component early-return `null` for a hidden source without special-casing.
+ */
+
+import { createElement, type ReactNode } from "react";
+import type { SourceConfig } from "../../types";
+import { DefaultResultRow } from "./DefaultResultRow";
+import { CmsResultRow } from "./CmsResultRow";
+
+/** A per-node renderer, or `false` to hide the source's results. */
+export type ResultRenderer = ((node: unknown) => ReactNode) | false;
+
+/**
+ * Resolves the renderer for one source. See the module doc for the precedence
+ * rules. `renderResult` is the optional per-source override map from `<Search>`.
+ */
+export function resolveResultRenderer(
+	source: SourceConfig,
+	renderResult?: Record<string, ResultRenderer>,
+): ResultRenderer {
+	const override = renderResult?.[source.key];
+	// A config override wins in every mode — including `false` (hide).
+	if (override !== undefined) return override;
+
+	// Assign a `displayName` so React DevTools shows a readable label for the
+	// per-node component factory and the `react/display-name` lint rule is
+	// satisfied. (This is a debug label only — it does not affect reference
+	// identity; a new function is still created on each call.)
+	if (source.kind === "cms") {
+		const renderCmsRow = (node: unknown) => createElement(CmsResultRow, { node, source });
+		renderCmsRow.displayName = "CmsResultRowRenderer";
+		return renderCmsRow;
+	}
+	const renderDefaultRow = (node: unknown) => createElement(DefaultResultRow, { node, source });
+	renderDefaultRow.displayName = "DefaultResultRowRenderer";
+	return renderDefaultRow;
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/config.json

@@ -0,0 +1,88 @@
+{
+  "pagination": {
+    "mode": "per-source",
+    "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",
+      "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",
+      "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" }
+    },
+    {
+      "kind": "cms",
+      "key": "content",
+      "label": "Content",
+      "labelSingular": "Content"
+    }
+  ]
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/constants.ts

@@ -0,0 +1,8 @@
+/**
+ * Minimum trimmed keyword length before a search fires. Both the SObject and
+ * CMS search backends reject terms shorter than this (returning errors that the
+ * UI would otherwise render as "Search failed for this source." on every
+ * source), so the query is gated client-side until the user types at least this
+ * many characters. Shared so every `<Search>` consumer inherits the same floor.
+ */
+export const MIN_QUERY_LENGTH = 3;

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;
+}