@salesforce/templates 66.13.5 → 66.13.6

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

@@ -0,0 +1,55 @@
+import { Search } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { Input } from "../../../../components/ui/input";
+import { debounce } from "../../utils/debounce";
+
+const TYPE_DEBOUNCE_MS = 250;
+
+interface SearchBarProps {
+	value: string;
+	onChange: (next: string) => void;
+	placeholder?: string;
+	className?: string;
+}
+
+/**
+ * Debounced text input for the global `q` term. Keeps a local `draft` so
+ * keystrokes feel responsive while the upstream `onChange` is rate-limited.
+ */
+export function SearchBar({ value, onChange, placeholder = "Search…", className }: SearchBarProps) {
+	const [draft, setDraft] = useState(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) => onChangeRef.current(next), TYPE_DEBOUNCE_MS);
+	}, []);
+
+	// External value can change (URL restore, reset). Keep draft in sync.
+	useEffect(() => {
+		setDraft(value);
+	}, [value]);
+
+	return (
+		<div className={`relative flex-1 ${className ?? ""}`}>
+			<Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+			<Input
+				type="text"
+				value={draft}
+				onChange={(e) => {
+					setDraft(e.target.value);
+					debouncedRef.current?.(e.target.value);
+				}}
+				placeholder={placeholder}
+				className="pl-9"
+				aria-label="Unified search"
+			/>
+		</div>
+	);
+}

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

@@ -0,0 +1,62 @@
+import { ArrowDown, ArrowUp } from "lucide-react";
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "../../../../components/ui/select";
+import { Button } from "../../../../components/ui/button";
+import type { SortFieldConfig, SortState } from "../../utils/sortUtils";
+
+const NONE_VALUE = "__none__";
+
+interface SortControlProps {
+	configs: SortFieldConfig[];
+	sort: SortState | null;
+	onSortChange: (sort: SortState | null) => void;
+	className?: string;
+}
+
+export function SortControl({ configs, sort, onSortChange, className }: SortControlProps) {
+	if (configs.length === 0) return null;
+	return (
+		<div className={`flex items-center gap-2 ${className ?? ""}`}>
+			<span className="text-sm text-muted-foreground whitespace-nowrap">Sort by</span>
+			<Select
+				value={sort?.field ?? NONE_VALUE}
+				onValueChange={(v) => {
+					if (v === NONE_VALUE) onSortChange(null);
+					else onSortChange({ field: v, direction: sort?.direction ?? "ASC" });
+				}}
+			>
+				<SelectTrigger size="sm" className="w-[160px]" aria-label="Sort by">
+					<SelectValue placeholder="Default" />
+				</SelectTrigger>
+				<SelectContent>
+					<SelectItem value={NONE_VALUE}>Default</SelectItem>
+					{configs.map((c) => (
+						<SelectItem key={c.field} value={c.field}>
+							{c.label}
+						</SelectItem>
+					))}
+				</SelectContent>
+			</Select>
+			{sort && (
+				<Button
+					variant="ghost"
+					size="icon-sm"
+					onClick={() =>
+						onSortChange({
+							...sort,
+							direction: sort.direction === "ASC" ? "DESC" : "ASC",
+						})
+					}
+					aria-label={`Sort ${sort.direction === "ASC" ? "descending" : "ascending"}`}
+				>
+					{sort.direction === "ASC" ? <ArrowUp /> : <ArrowDown />}
+				</Button>
+			)}
+		</div>
+	);
+}

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

@@ -0,0 +1,61 @@
+import { X } from "lucide-react";
+import { Button } from "../../../../components/ui/button";
+import type { ActiveFilterValue } from "../../utils/filterUtils";
+
+function formatLabel(filter: ActiveFilterValue): string {
+	const { label, type, value, min, max } = filter;
+	switch (type) {
+		case "text":
+		case "picklist":
+			return `${label}: ${value ?? ""}`;
+		case "multipicklist": {
+			const values = value ? value.split(",") : [];
+			if (values.length <= 2) return `${label}: ${values.join(", ")}`;
+			return `${label}: ${values.length} selected`;
+		}
+		case "boolean":
+			return `${label}: ${value === "true" ? "Yes" : "No"}`;
+		case "numeric": {
+			if (min && max) return `${label}: ${min} – ${max}`;
+			if (min) return `${label}: ≥ ${min}`;
+			return `${label}: ≤ ${max ?? ""}`;
+		}
+		case "date":
+		case "daterange":
+		case "datetime":
+		case "datetimerange": {
+			if (min && max) return `${label}: ${min} → ${max}`;
+			if (min) return `${label}: from ${min}`;
+			return `${label}: until ${max ?? ""}`;
+		}
+		default:
+			return label;
+	}
+}
+
+interface ActiveFiltersProps {
+	filters: ActiveFilterValue[];
+	onRemove: (field: string) => void;
+	className?: string;
+}
+
+export function ActiveFilters({ filters, onRemove, className }: ActiveFiltersProps) {
+	if (filters.length === 0) return null;
+	return (
+		<div className={`flex flex-wrap gap-2 ${className ?? ""}`}>
+			{filters.map((filter) => (
+				<Button
+					key={filter.field}
+					variant="outline"
+					size="sm"
+					className="gap-1 h-7 text-xs"
+					aria-label={`Remove ${formatLabel(filter)}`}
+					onClick={() => onRemove(filter.field)}
+				>
+					{formatLabel(filter)}
+					<X className="h-3 w-3" aria-hidden="true" />
+				</Button>
+			))}
+		</div>
+	);
+}

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