@salesforce/templates 66.13.5 → 66.13.7

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

@@ -0,0 +1,125 @@
+/**
+ * Default filter panel used when no `renderFilters` is supplied for a source.
+ *
+ * Renders one input per entry in `source.filterBy`, picking the right
+ * component for each `FilterFieldType`:
+ *
+ *   - text                                  → TextFilter
+ *   - picklist                              → SelectFilter (inline options or auto-fetched)
+ *   - multipicklist                         → MultiSelectFilter (inline options or auto-fetched)
+ *   - numeric                               → NumericRangeFilter
+ *   - boolean                               → BooleanFilter
+ *   - date / daterange / datetime / datetimerange → DateRangeFilter
+ *       (its Between / After / Before chrome is chosen by `filter.dateMode`)
+ *
+ * Applications can still pass `renderFilters[sourceKey]` to override the
+ * entire panel for a specific source.
+ */
+
+import { TextFilter } from "./inputs/TextFilter";
+import { SelectFilter } from "./inputs/SelectFilter";
+import { MultiSelectFilter } from "./inputs/MultiSelectFilter";
+import { NumericRangeFilter } from "./inputs/NumericRangeFilter";
+import { BooleanFilter } from "./inputs/BooleanFilter";
+import { DateRangeFilter } from "./inputs/DateRangeFilter";
+import { useDistinctValues } from "../../hooks/useDistinctValues";
+import type { FilterFieldConfig } from "../../utils/filterUtils";
+import type { SObjectSourceConfig } from "../../types";
+
+interface DefaultFilterPanelProps {
+	source: SObjectSourceConfig;
+}
+
+export function DefaultFilterPanel({ source }: DefaultFilterPanelProps) {
+	const filters = source.filterBy ?? [];
+	if (filters.length === 0) return null;
+	return (
+		<>
+			{filters.map((filter) => (
+				<DefaultFilterField key={filter.field} filter={filter} source={source} />
+			))}
+		</>
+	);
+}
+
+interface DefaultFilterFieldProps {
+	filter: FilterFieldConfig;
+	source: SObjectSourceConfig;
+}
+
+function DefaultFilterField({ filter, source }: DefaultFilterFieldProps) {
+	switch (filter.type) {
+		case "text":
+			return (
+				<TextFilter
+					field={filter.field}
+					label={filter.label}
+					placeholder={filter.placeholder}
+					helpText={filter.helpText}
+				/>
+			);
+		case "picklist":
+			return <PicklistField filter={filter} source={source} multi={false} />;
+		case "multipicklist":
+			return <PicklistField filter={filter} source={source} multi={true} />;
+		case "numeric":
+			return (
+				<NumericRangeFilter field={filter.field} label={filter.label} helpText={filter.helpText} />
+			);
+		case "boolean":
+			return <BooleanFilter field={filter.field} label={filter.label} helpText={filter.helpText} />;
+		case "date":
+		case "daterange":
+			return (
+				<DateRangeFilter
+					field={filter.field}
+					label={filter.label}
+					helpText={filter.helpText}
+					filterType="daterange"
+					mode={filter.dateMode}
+				/>
+			);
+		case "datetime":
+		case "datetimerange":
+			return (
+				<DateRangeFilter
+					field={filter.field}
+					label={filter.label}
+					helpText={filter.helpText}
+					filterType="datetimerange"
+					mode={filter.dateMode}
+				/>
+			);
+		default:
+			return null;
+	}
+}
+
+/**
+ * Resolves picklist options from inline config first; falls back to fetching
+ * distinct values from the GraphQL aggregate API on first render.
+ */
+function PicklistField({
+	filter,
+	source,
+	multi,
+}: {
+	filter: FilterFieldConfig;
+	source: SObjectSourceConfig;
+	multi: boolean;
+}) {
+	const inline = filter.options;
+	const fetched = useDistinctValues(
+		inline ? null : { objectName: source.objectName, fieldName: filter.field },
+	);
+	const options = inline ?? fetched ?? [];
+	const Component = multi ? MultiSelectFilter : SelectFilter;
+	return (
+		<Component
+			field={filter.field}
+			label={filter.label}
+			options={options}
+			helpText={filter.helpText}
+		/>
+	);
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/{_os_/components → search/components/filters}/FilterContext.tsx

@@ -1,6 +1,6 @@
-import { createContext, useContext, useCallback, type ReactNode } from "react";
-import { Button } from "../../../components/ui/button";
-import type { ActiveFilterValue } from "../utils/filterUtils";
+import { createContext, useCallback, useContext, type ReactNode } from "react";
+import { Button } from "../../../../components/ui/button";
+import type { ActiveFilterValue } from "../../utils/filterUtils";
 
 interface FilterContextValue {
 	filters: ActiveFilterValue[];
@@ -27,14 +27,7 @@ export function FilterProvider({
 	children,
 }: FilterProviderProps) {
 	return (
-		<FilterContext.Provider
-			value={{
-				filters,
-				onFilterChange,
-				onFilterRemove,
-				onReset,
-			}}
-		>
+		<FilterContext.Provider value={{ filters, onFilterChange, onFilterRemove, onReset }}>
 			{children}
 		</FilterContext.Provider>
 	);
@@ -51,11 +44,8 @@ export function useFilterField(field: string) {
 	const value = filters.find((f) => f.field === field);
 	const onChange = useCallback(
 		(next: ActiveFilterValue | undefined) => {
-			if (next) {
-				onFilterChange(field, next);
-			} else {
-				onFilterRemove(field);
-			}
+			if (next) onFilterChange(field, next);
+			else onFilterRemove(field);
 		},
 		[field, onFilterChange, onFilterRemove],
 	);
@@ -64,10 +54,7 @@ export function useFilterField(field: string) {
 
 export function useFilterPanel() {
 	const { filters, onReset } = useFilterContext();
-	return {
-		hasActiveFilters: filters.length > 0,
-		resetAll: onReset,
-	};
+	return { hasActiveFilters: filters.length > 0, resetAll: onReset };
 }
 
 type FilterResetButtonProps = Omit<React.ComponentProps<typeof Button>, "onClick">;

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

@@ -0,0 +1,50 @@
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../../components/ui/select";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+
+const ANY_VALUE = "__any__";
+
+interface BooleanFilterProps {
+	field: string;
+	label: string;
+	trueLabel?: string;
+	falseLabel?: string;
+	helpText?: string;
+}
+
+export function BooleanFilter({
+	field,
+	label,
+	trueLabel = "Yes",
+	falseLabel = "No",
+	helpText,
+}: BooleanFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const id = `filter-${field}`;
+	return (
+		<FilterFieldWrapper label={label} htmlFor={id} helpText={helpText}>
+			<Select
+				value={value?.value ?? ANY_VALUE}
+				onValueChange={(v) => {
+					if (v === ANY_VALUE) onChange(undefined);
+					else onChange({ field, label, type: "boolean", value: v });
+				}}
+			>
+				<SelectTrigger id={id} className="w-full">
+					<SelectValue />
+				</SelectTrigger>
+				<SelectContent>
+					<SelectItem value={ANY_VALUE}>Any</SelectItem>
+					<SelectItem value="true">{trueLabel}</SelectItem>
+					<SelectItem value="false">{falseLabel}</SelectItem>
+				</SelectContent>
+			</Select>
+		</FilterFieldWrapper>
+	);
+}

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

@@ -0,0 +1,160 @@
+import { useState } from "react";
+import { Input } from "../../../../../components/ui/input";
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../../components/ui/select";
+import { useFilterField } from "../FilterContext";
+import { FilterFieldWrapper } from "./FilterFieldWrapper";
+import type {
+	ActiveFilterValue,
+	DateFilterMode,
+	FilterFieldType,
+} from "../../../utils/filterUtils";
+
+interface DateRangeFilterProps {
+	field: string;
+	label: string;
+	helpText?: string;
+	/** "daterange" (Date scalar) or "datetimerange" (DateTime scalar). */
+	filterType?: Extract<FilterFieldType, "daterange" | "datetimerange">;
+	/**
+	 * Which comparison chrome to show. See {@link DateFilterMode}. Defaults to
+	 * `"comparison"` (an After / Before selector with one date input).
+	 */
+	mode?: DateFilterMode;
+}
+
+/**
+ * The three ways to constrain a date field. They map directly onto the
+ * `min`/`max` bounds the query builder already understands:
+ *   - after   → only `min` set  → `gte`
+ *   - before  → only `max` set  → `lte`
+ *   - between → both set        → `gte` AND `lte`
+ */
+type DateOperator = "between" | "after" | "before";
+
+const OPERATOR_LABELS: Record<DateOperator, string> = {
+	between: "Between",
+	after: "After",
+	before: "Before",
+};
+
+/** The operators offered for each {@link DateFilterMode}. */
+const MODE_OPERATORS: Record<DateFilterMode, DateOperator[]> = {
+	range: ["between"],
+	comparison: ["after", "before"],
+	both: ["between", "after", "before"],
+};
+
+/** Pick the operator implied by an already-active filter (e.g. restored from the URL). */
+function operatorFor(value: ActiveFilterValue | undefined): DateOperator {
+	const hasMin = !!value?.min;
+	const hasMax = !!value?.max;
+	if (hasMax && !hasMin) return "before";
+	if (hasMin && !hasMax) return "after";
+	return "between";
+}
+
+/**
+ * A date constraint whose chrome is driven by `mode`:
+ *   - `"range"`: a single Between control (two date inputs).
+ *   - `"comparison"` (default): an After / Before selector with one input.
+ *   - `"both"`: a Between / After / Before selector spanning the two.
+ *
+ * "Between" shows two `<input type="date">` controls; "After" / "Before"
+ * collapse to one bound to the relevant end. Uses the platform-native picker —
+ * no popover/calendar dependency.
+ */
+export function DateRangeFilter({
+	field,
+	label,
+	helpText,
+	filterType = "daterange",
+	mode = "comparison",
+}: DateRangeFilterProps) {
+	const { value, onChange } = useFilterField(field);
+	const operators = MODE_OPERATORS[mode];
+
+	// Operator is local UI state: it must survive a moment where no date is yet
+	// entered (which clears the active filter), so it can't be derived from
+	// `value` on every render. Seed it from any filter restored on mount, clamped
+	// to an operator this mode actually offers.
+	const [operator, setOperator] = useState<DateOperator>(() => {
+		const restored = operatorFor(value);
+		return operators.includes(restored) ? restored : operators[0];
+	});
+
+	const emit = (nextMin: string | undefined, nextMax: string | undefined) => {
+		if (!nextMin && !nextMax) onChange(undefined);
+		else onChange({ field, label, type: filterType, min: nextMin, max: nextMax });
+	};
+
+	const changeOperator = (next: DateOperator) => {
+		setOperator(next);
+		// Re-emit, keeping only the bound(s) the new operator uses.
+		if (next === "after") emit(value?.min, undefined);
+		else if (next === "before") emit(undefined, value?.max);
+		else emit(value?.min, value?.max);
+	};
+
+	const operatorId = `filter-${field}-op`;
+	// A lone "between" operator (mode="range") needs no selector — it can't change.
+	const showSelector = operators.length > 1;
+
+	return (
+		<FilterFieldWrapper label={label} helpText={helpText}>
+			<div className="flex flex-col gap-2">
+				{showSelector && (
+					<Select value={operator} onValueChange={(v) => changeOperator(v as DateOperator)}>
+						<SelectTrigger id={operatorId} className="w-full" aria-label={`${label} comparison`}>
+							<SelectValue />
+						</SelectTrigger>
+						<SelectContent>
+							{operators.map((op) => (
+								<SelectItem key={op} value={op}>
+									{OPERATOR_LABELS[op]}
+								</SelectItem>
+							))}
+						</SelectContent>
+					</Select>
+				)}
+
+				{operator === "between" ? (
+					<div className="flex items-center gap-2">
+						<Input
+							type="date"
+							value={value?.min ?? ""}
+							onChange={(e) => emit(e.target.value || undefined, value?.max)}
+							aria-label={`${label} from`}
+						/>
+						<span className="text-sm text-muted-foreground">–</span>
+						<Input
+							type="date"
+							value={value?.max ?? ""}
+							onChange={(e) => emit(value?.min, e.target.value || undefined)}
+							aria-label={`${label} to`}
+						/>
+					</div>
+				) : operator === "after" ? (
+					<Input
+						type="date"
+						value={value?.min ?? ""}
+						onChange={(e) => emit(e.target.value || undefined, undefined)}
+						aria-label={`${label} after`}
+					/>
+				) : (
+					<Input
+						type="date"
+						value={value?.max ?? ""}
+						onChange={(e) => emit(undefined, e.target.value || undefined)}
+						aria-label={`${label} before`}
+					/>
+				)}
+			</div>
+		</FilterFieldWrapper>
+	);
+}

package/lib/templates/project/{reactinternalapp/_p_/_m_/_w_/_a_/src/_f_/_os_/components/filters → reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/components/filters/inputs}/FilterFieldWrapper.tsx

@@ -1,29 +1,34 @@
-import { Label } from "../../../../components/ui/label";
-import { cn } from "../../../../lib/utils";
+import type { ReactNode } from "react";
+import { Label } from "../../../../../components/ui/label";
 
-interface FilterFieldWrapperProps extends React.ComponentProps<"div"> {
+interface FilterFieldWrapperProps {
 	label: string;
 	htmlFor?: string;
+	errorId?: string;
 	helpText?: string;
 	error?: string;
+	className?: string;
+	children: ReactNode;
 }
 
 export function FilterFieldWrapper({
 	label,
 	htmlFor,
+	errorId,
 	helpText,
 	error,
 	className,
 	children,
-	...props
 }: FilterFieldWrapperProps) {
 	return (
-		<div className={cn("space-y-1", className)} {...props}>
+		<div className={`space-y-1 ${className ?? ""}`}>
 			<Label htmlFor={htmlFor}>{label}</Label>
 			{children}
 			<div className="min-h-4">
 				{error ? (
-					<p className="text-xs text-destructive">{error}</p>
+					<p id={errorId} role="alert" className="text-xs text-destructive">
+						{error}
+					</p>
 				) : (
 					helpText && <p className="text-xs text-muted-foreground">{helpText}</p>
 				)}

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