@schandlergarcia/sf-web-components 2.2.1 → 2.3.0

package/brands/engine/app/features/object-search/__examples__/pages/AccountSearch.tsx

@@ -0,0 +1,312 @@
+import { useMemo, useState } from "react";
+import { Link } from "react-router";
+import { AlertCircle, ChevronDown, SearchX } from "lucide-react";
+import {
+	searchAccounts,
+	fetchDistinctIndustries,
+	fetchDistinctTypes,
+} from "../api/accountSearchService";
+import { useCachedAsyncData } from "../../hooks/useCachedAsyncData";
+import { fieldValue } from "../../utils/fieldUtils";
+import { useObjectSearchParams } from "../../hooks/useObjectSearchParams";
+import { Alert, AlertTitle, AlertDescription } from "../../../../components/ui/alert";
+import {
+	Card,
+	CardContent,
+	CardHeader,
+	CardTitle,
+} from "../../../../components/ui/card";
+import { Button } from "../../../../components/ui/button";
+import {
+	Collapsible,
+	CollapsibleContent,
+	CollapsibleTrigger,
+} from "../../../../components/ui/collapsible";
+import { Skeleton } from "../../../../components/ui/skeleton";
+import { FilterProvider, FilterResetButton } from "../../components/FilterContext";
+import { SearchFilter } from "../../components/filters/SearchFilter";
+import { TextFilter } from "../../components/filters/TextFilter";
+import { SelectFilter } from "../../components/filters/SelectFilter";
+import { MultiSelectFilter } from "../../components/filters/MultiSelectFilter";
+import { NumericRangeFilter } from "../../components/filters/NumericRangeFilter";
+import { DateFilter } from "../../components/filters/DateFilter";
+import { DateRangeFilter } from "../../components/filters/DateRangeFilter";
+import { ActiveFilters } from "../../components/ActiveFilters";
+import { SortControl } from "../../components/SortControl";
+import type { FilterFieldConfig } from "../../utils/filterUtils";
+import type { SortFieldConfig } from "../../utils/sortUtils";
+import type { Account_Filter, Account_OrderBy } from "../../../../api/graphql-operations-types";
+import type { AccountSearchResult } from "../api/accountSearchService";
+import { ObjectBreadcrumb } from "../../components/ObjectBreadcrumb";
+import PaginationControls from "../../components/PaginationControls";
+import type { PaginationConfig } from "../../hooks/useObjectSearchParams";
+
+const PAGINATION_CONFIG: PaginationConfig = {
+	defaultPageSize: 6,
+	validPageSizes: [6, 12, 24, 48],
+};
+
+type AccountNode = NonNullable<
+	NonNullable<NonNullable<AccountSearchResult["edges"]>[number]>["node"]
+>;
+
+const FILTER_CONFIGS: FilterFieldConfig[] = [
+	{
+		field: "search",
+		label: "Search",
+		type: "search",
+		searchFields: ["Name", "Phone", "Industry"],
+		placeholder: "Search by name, phone, or industry...",
+	},
+	{ field: "Name", label: "Account Name", type: "text", placeholder: "Search by name..." },
+	{ field: "Industry", label: "Industry", type: "picklist" },
+	{ field: "Type", label: "Type", type: "multipicklist" },
+	{ field: "AnnualRevenue", label: "Annual Revenue", type: "numeric" },
+	{ field: "CreatedDate", label: "Created Date", type: "datetime" },
+	{ field: "LastModifiedDate", label: "Last Modified Date", type: "datetimerange" },
+];
+
+const ACCOUNT_SORT_CONFIGS: SortFieldConfig<keyof Account_OrderBy>[] = [
+	{ field: "Name", label: "Name" },
+	{ field: "AnnualRevenue", label: "Annual Revenue" },
+	{ field: "Industry", label: "Industry" },
+	{ field: "CreatedDate", label: "Created Date" },
+];
+
+// -- Component --------------------------------------------------------------
+
+export default function AccountSearch() {
+	const [filtersOpen, setFiltersOpen] = useState(true);
+	const { data: industryOptions } = useCachedAsyncData(fetchDistinctIndustries, [], {
+		key: "distinctIndustries",
+		ttl: 300_000,
+	});
+	const { data: typeOptions } = useCachedAsyncData(fetchDistinctTypes, [], {
+		key: "distinctTypes",
+		ttl: 300_000,
+	});
+
+	const { filters, sort, query, pagination, resetAll } = useObjectSearchParams<
+		Account_Filter,
+		Account_OrderBy
+	>(FILTER_CONFIGS, ACCOUNT_SORT_CONFIGS, PAGINATION_CONFIG);
+
+	const searchKey = `accounts:${JSON.stringify({ where: query.where, orderBy: query.orderBy, first: pagination.pageSize, after: pagination.afterCursor })}`;
+	const { data, loading, error } = useCachedAsyncData(
+		() =>
+			searchAccounts({
+				where: query.where,
+				orderBy: query.orderBy,
+				first: pagination.pageSize,
+				after: pagination.afterCursor,
+			}),
+		[query.where, query.orderBy, pagination.pageSize, pagination.afterCursor],
+		{ key: searchKey },
+	);
+
+	const pageInfo = data?.pageInfo;
+	const totalCount = data?.totalCount;
+	const hasNextPage = pageInfo?.hasNextPage ?? false;
+	const hasPreviousPage = pagination.pageIndex > 0;
+
+	const validAccountNodes = useMemo(
+		() =>
+			(data?.edges ?? []).reduce<AccountNode[]>((acc, edge) => {
+				if (edge?.node) acc.push(edge.node);
+				return acc;
+			}, []),
+		[data?.edges],
+	);
+
+	return (
+		<div className="max-w-6xl mx-auto px-4 sm:px-6 lg:px-8 py-6">
+			<ObjectBreadcrumb listPath="/accounts" listLabel="Accounts" />
+
+			<h1 className="text-2xl font-bold mb-4">Search Accounts</h1>
+
+			<div className="flex flex-col lg:flex-row gap-6">
+				{/* Sidebar — Filter Panel */}
+				<aside className="w-full lg:w-80 shrink-0">
+					<FilterProvider
+						filters={filters.active}
+						onFilterChange={filters.set}
+						onFilterRemove={filters.remove}
+						onReset={resetAll}
+					>
+						<Card>
+							<Collapsible open={filtersOpen} onOpenChange={setFiltersOpen}>
+								<CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
+									<CardTitle className="text-base font-semibold">
+										<h2>Filters</h2>
+									</CardTitle>
+									<div className="flex items-center gap-1">
+										<FilterResetButton variant="destructive" size="sm" />
+										<CollapsibleTrigger asChild>
+											<Button variant="ghost" size="icon">
+												<ChevronDown
+													className={`h-4 w-4 transition-transform ${filtersOpen ? "" : "-rotate-90"}`}
+												/>
+												<span className="sr-only">Toggle filters</span>
+											</Button>
+										</CollapsibleTrigger>
+									</div>
+								</CardHeader>
+								<CollapsibleContent>
+									<CardContent className="space-y-1 pt-0">
+										<SearchFilter
+											field="search"
+											label="Search"
+											placeholder="Search by name, phone, or industry..."
+										/>
+										<TextFilter field="Name" label="Account Name" placeholder="Search by name..." />
+										<SelectFilter
+											field="Industry"
+											label="Industry"
+											options={industryOptions ?? []}
+										/>
+										<MultiSelectFilter field="Type" label="Type" options={typeOptions ?? []} />
+										<NumericRangeFilter
+											field="AnnualRevenue"
+											label="Annual Revenue"
+											min={0}
+											max={1_000_000_000_000}
+										/>
+										<DateFilter field="CreatedDate" label="Created Date" filterType="datetime" />
+										<DateRangeFilter
+											field="LastModifiedDate"
+											label="Last Modified Date"
+											filterType="datetimerange"
+										/>
+									</CardContent>
+								</CollapsibleContent>
+							</Collapsible>
+						</Card>
+					</FilterProvider>
+				</aside>
+
+				{/* Main area — Sort + Results */}
+				<div className="flex-1 min-w-0">
+					{/* Sort control + active filters */}
+					<div className="flex flex-wrap items-center gap-2 mb-4">
+						<SortControl
+							configs={ACCOUNT_SORT_CONFIGS}
+							sort={sort.current}
+							onSortChange={sort.set}
+						/>
+						<ActiveFilters filters={filters.active} onRemove={filters.remove} />
+					</div>
+
+					<div className="min-h-112">
+						{/* Loading state */}
+						{loading && (
+							<>
+								<Skeleton className="h-5 w-30 mb-3" />
+								<div className="divide-y">
+									{Array.from({ length: pagination.pageSize }, (_, i) => (
+										<div key={i} className="flex items-center justify-between py-3">
+											<div className="space-y-2">
+												<Skeleton className="h-5 w-40" />
+												<Skeleton className="h-4 w-28" />
+											</div>
+											<div className="space-y-2 flex flex-col items-end">
+												<Skeleton className="h-4 w-24" />
+												<Skeleton className="h-4 w-20" />
+											</div>
+										</div>
+									))}
+								</div>
+							</>
+						)}
+
+						{/* Error state */}
+						{error && (
+							<>
+								<p className="text-sm text-muted-foreground mb-3">0 accounts found</p>
+								<Alert variant="destructive" role="alert">
+									<AlertCircle />
+									<AlertTitle>Failed to load accounts</AlertTitle>
+									<AlertDescription>
+										Something went wrong while loading accounts. Please try again later.
+									</AlertDescription>
+								</Alert>
+							</>
+						)}
+
+						{/* Results list */}
+						{!loading && !error && validAccountNodes.length > 0 && (
+							<>
+								<p className="text-sm text-muted-foreground mb-3">
+									{totalCount != null && (hasNextPage || hasPreviousPage)
+										? `${totalCount} account${totalCount !== 1 ? "s" : ""} found`
+										: `Showing ${validAccountNodes.length} account${validAccountNodes.length !== 1 ? "s" : ""}`}
+								</p>
+								<AccountResultsList nodes={validAccountNodes} />
+							</>
+						)}
+
+						{/* No results state */}
+						{!loading && !error && validAccountNodes.length === 0 && (
+							<div className="flex flex-col items-center justify-center py-16 text-center">
+								<SearchX className="size-12 text-muted-foreground mb-4" />
+								<h2 className="text-lg font-semibold mb-1">No accounts found</h2>
+								<p className="text-sm text-muted-foreground">
+									Try adjusting your filters or search criteria.
+								</p>
+							</div>
+						)}
+					</div>
+
+					{/* Pagination — always visible, disabled while loading or on error */}
+					<PaginationControls
+						pageIndex={pagination.pageIndex}
+						hasNextPage={hasNextPage}
+						hasPreviousPage={hasPreviousPage}
+						pageSize={pagination.pageSize}
+						pageSizeOptions={PAGINATION_CONFIG.validPageSizes}
+						onNextPage={() => {
+							if (pageInfo?.endCursor) pagination.goToNextPage(pageInfo.endCursor);
+						}}
+						onPreviousPage={pagination.goToPreviousPage}
+						onPageSizeChange={pagination.setPageSize}
+						disabled={loading || !!error}
+					/>
+				</div>
+			</div>
+		</div>
+	);
+}
+
+// -- Result Components ------------------------------------------------------
+
+function AccountResultsList({ nodes }: { nodes: AccountNode[] }) {
+	return (
+		<ul className="divide-y">
+			{nodes.map((node) => (
+				<AccountResultItem key={node.Id} node={node} />
+			))}
+		</ul>
+	);
+}
+
+function AccountResultItem({ node }: { node: AccountNode }) {
+	return (
+		<li>
+			<Link
+				to={`/accounts/${node.Id}`}
+				className="flex items-center justify-between py-3 px-3 -mx-3 rounded-md transition-colors hover:bg-accent"
+			>
+				<div>
+					<span className="font-medium">{fieldValue(node.Name) ?? "\u2014"}</span>
+					<p className="text-sm text-muted-foreground">
+						{[fieldValue(node.Industry), fieldValue(node.Type)].filter(Boolean).join(" \u00B7 ") ||
+							"\u2014"}
+					</p>
+				</div>
+				<div className="text-right text-sm">
+					<p>{fieldValue(node.Phone) ?? ""}</p>
+					<p className="text-muted-foreground">{fieldValue(node.Owner?.Name) ?? ""}</p>
+				</div>
+			</Link>
+		</li>
+	);
+}

package/brands/engine/app/features/object-search/__examples__/pages/Home.tsx

@@ -0,0 +1,34 @@
+import { useState } from "react";
+import { useNavigate } from "react-router";
+import { SearchBar } from "../../components/SearchBar";
+import { Button } from "../../../../components/ui/button";
+
+export default function HomePage() {
+	const navigate = useNavigate();
+	const [text, setText] = useState("");
+
+	const handleSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => {
+		e.preventDefault();
+		const params = text ? `?q=${encodeURIComponent(text)}` : "";
+		navigate(`/accounts${params}`);
+	};
+
+	return (
+		<div className="max-w-2xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
+			<div className="flex items-center gap-6 mb-6">
+				<h1 className="text-2xl font-bold">Account Search</h1>
+				<Button variant="outline" size="sm" onClick={() => navigate("/accounts")}>
+					Browse All Accounts
+				</Button>
+			</div>
+			<form onSubmit={handleSubmit} className="flex gap-2">
+				<SearchBar
+					placeholder="Search by name, phone, or industry..."
+					value={text}
+					handleChange={setText}
+				/>
+				<Button type="submit">Search</Button>
+			</form>
+		</div>
+	);
+}

package/brands/engine/app/features/object-search/api/objectSearchService.ts

@@ -0,0 +1,84 @@
+import { createDataSDK } from "@salesforce/sdk-data";
+
+export interface ObjectSearchOptions<TWhere, TOrderBy> {
+	where?: TWhere;
+	orderBy?: TOrderBy;
+	first?: number;
+	after?: string;
+}
+
+export type PicklistOption = { value: string; label: string };
+
+/**
+ * Executes a GraphQL search query and extracts the result for the given object name
+ * from the standard `uiapi.query.<ObjectName>` response shape.
+ */
+export async function searchObjects<TResult, TQuery, TVariables>(
+	query: string,
+	objectName: string,
+	options: ObjectSearchOptions<unknown, unknown> = {},
+): Promise<TResult> {
+	const { where, orderBy, first = 20, after } = options;
+
+	const data = await createDataSDK();
+	const response = await data.graphql?.<TQuery, TVariables>(query, {
+		first,
+		after,
+		where,
+		orderBy,
+	} as TVariables);
+
+	if (response?.errors?.length) {
+		throw new Error(response.errors.map((e) => e.message).join("; "));
+	}
+
+	const result = (response?.data as Record<string, unknown> | undefined)?.uiapi as
+		| Record<string, unknown>
+		| undefined;
+	const queryResult = (result?.query as Record<string, unknown> | undefined)?.[objectName] as
+		| TResult
+		| undefined;
+
+	if (!queryResult) {
+		throw new Error(`No ${objectName} data returned`);
+	}
+
+	return queryResult;
+}
+
+/**
+ * Executes a GraphQL aggregate/groupBy query and extracts picklist options
+ * from the standard `uiapi.aggregate.<ObjectName>` response shape.
+ */
+export async function fetchDistinctValues<TQuery>(
+	query: string,
+	objectName: string,
+	fieldName: string,
+): Promise<PicklistOption[]> {
+	const data = await createDataSDK();
+	const response = await data.graphql?.<TQuery>(query);
+	const errors = response?.errors;
+
+	if (errors?.length) {
+		throw new Error(errors.map((e) => e.message).join("; "));
+	}
+
+	const result = (response?.data as Record<string, unknown> | undefined)?.uiapi as
+		| Record<string, unknown>
+		| undefined;
+	const aggregate = (result?.aggregate as Record<string, unknown> | undefined)?.[objectName] as
+		| { edges?: Array<{ node?: { aggregate?: Record<string, unknown> } }> }
+		| undefined;
+
+	const edges = aggregate?.edges ?? [];
+	return edges
+		.map((edge) => {
+			const field = edge?.node?.aggregate?.[fieldName] as
+				| { value?: string | null; displayValue?: string | null; label?: string | null }
+				| undefined;
+			const value = field?.value;
+			if (!value) return null;
+			return { value, label: field.label ?? field.displayValue ?? value };
+		})
+		.filter((opt): opt is PicklistOption => opt !== null);
+}

package/brands/engine/app/features/object-search/components/ActiveFilters.tsx

@@ -0,0 +1,89 @@
+import { X } from "lucide-react";
+import { Button } from "../../../components/ui/button";
+import { cn } from "../../../lib/utils";
+import type { ActiveFilterValue } from "../utils/filterUtils";
+
+function formatFilterLabel(filter: ActiveFilterValue): string {
+	const { label, type, value, min, max } = filter;
+
+	switch (type) {
+		case "search":
+			return `Search: ${value}`;
+		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": {
+			if (min && max) return `${label}: ${min} to ${max}`;
+			if (min) return `${label}: from ${min}`;
+			return `${label}: until ${max}`;
+		}
+		default:
+			return label;
+	}
+}
+
+interface ActiveFiltersProps extends React.ComponentProps<"div"> {
+	filters: ActiveFilterValue[];
+	onRemove: (field: string) => void;
+	buttonProps?: Omit<React.ComponentProps<typeof ActiveFilterButton>, "filter" | "onRemove">;
+}
+
+export function ActiveFilters({
+	filters,
+	onRemove,
+	className,
+	buttonProps,
+	...props
+}: ActiveFiltersProps) {
+	if (filters.length === 0) return null;
+
+	return (
+		<div className={cn("flex flex-wrap gap-2", className)} {...props}>
+			{filters.map((filter) => (
+				<ActiveFilterButton
+					key={filter.field}
+					filter={filter}
+					onRemove={onRemove}
+					{...buttonProps}
+				/>
+			))}
+		</div>
+	);
+}
+
+interface ActiveFilterButtonProps extends React.ComponentProps<typeof Button> {
+	filter: ActiveFilterValue;
+	onRemove: (field: string) => void;
+}
+
+export function ActiveFilterButton({
+	filter,
+	onRemove,
+	className,
+	...props
+}: ActiveFilterButtonProps) {
+	return (
+		<Button
+			variant="outline"
+			size="sm"
+			className={cn("gap-1 h-7 text-xs", className)}
+			onClick={() => onRemove(filter.field)}
+			{...props}
+		>
+			{formatFilterLabel(filter)}
+			<X className="h-3 w-3" />
+		</Button>
+	);
+}

package/brands/engine/app/features/object-search/components/FilterContext.tsx

@@ -0,0 +1,83 @@
+import { createContext, useContext, useCallback, type ReactNode } from "react";
+import { Button } from "../../../components/ui/button";
+import type { ActiveFilterValue } from "../utils/filterUtils";
+
+interface FilterContextValue {
+	filters: ActiveFilterValue[];
+	onFilterChange: (field: string, value: ActiveFilterValue | undefined) => void;
+	onFilterRemove: (field: string) => void;
+	onReset: () => void;
+}
+
+const FilterContext = createContext<FilterContextValue | null>(null);
+
+interface FilterProviderProps {
+	filters: ActiveFilterValue[];
+	onFilterChange: (field: string, value: ActiveFilterValue | undefined) => void;
+	onFilterRemove: (field: string) => void;
+	onReset: () => void;
+	children: ReactNode;
+}
+
+export function FilterProvider({
+	filters,
+	onFilterChange,
+	onFilterRemove,
+	onReset,
+	children,
+}: FilterProviderProps) {
+	return (
+		<FilterContext.Provider
+			value={{
+				filters,
+				onFilterChange,
+				onFilterRemove,
+				onReset,
+			}}
+		>
+			{children}
+		</FilterContext.Provider>
+	);
+}
+
+function useFilterContext() {
+	const ctx = useContext(FilterContext);
+	if (!ctx) throw new Error("useFilterField must be used within a FilterProvider");
+	return ctx;
+}
+
+export function useFilterField(field: string) {
+	const { filters, onFilterChange, onFilterRemove } = useFilterContext();
+	const value = filters.find((f) => f.field === field);
+	const onChange = useCallback(
+		(next: ActiveFilterValue | undefined) => {
+			if (next) {
+				onFilterChange(field, next);
+			} else {
+				onFilterRemove(field);
+			}
+		},
+		[field, onFilterChange, onFilterRemove],
+	);
+	return { value, onChange };
+}
+
+export function useFilterPanel() {
+	const { filters, onReset } = useFilterContext();
+	return {
+		hasActiveFilters: filters.length > 0,
+		resetAll: onReset,
+	};
+}
+
+type FilterResetButtonProps = Omit<React.ComponentProps<typeof Button>, "onClick">;
+
+export function FilterResetButton({ children, ...props }: FilterResetButtonProps) {
+	const { hasActiveFilters, resetAll } = useFilterPanel();
+	if (!hasActiveFilters) return null;
+	return (
+		<Button onClick={resetAll} aria-label="Reset filters" variant="destructive" {...props}>
+			{children ?? "Reset"}
+		</Button>
+	);
+}

package/brands/engine/app/features/object-search/components/ObjectBreadcrumb.tsx

@@ -0,0 +1,66 @@
+import { Link } from "react-router";
+import {
+	Breadcrumb,
+	BreadcrumbList,
+	BreadcrumbItem,
+	BreadcrumbLink,
+	BreadcrumbSeparator,
+	BreadcrumbPage,
+} from "../../../components/ui/breadcrumb";
+import { Skeleton } from "../../../components/ui/skeleton";
+
+interface ObjectBreadcrumbProps {
+	listPath: string;
+	listLabel: string;
+	recordName?: string;
+	loading?: boolean;
+	includeHome?: boolean; // default is true
+	homeLabel?: string; // default is "Home"
+}
+
+export function ObjectBreadcrumb({
+	listPath,
+	listLabel,
+	recordName,
+	loading,
+	includeHome = true,
+	homeLabel = "Home",
+}: ObjectBreadcrumbProps) {
+	const isDetailView = loading || recordName;
+
+	return (
+		<Breadcrumb className="mb-3">
+			<BreadcrumbList>
+				{includeHome && (
+					<BreadcrumbItem>
+						<BreadcrumbLink asChild>
+							<Link to="/">{homeLabel}</Link>
+						</BreadcrumbLink>
+					</BreadcrumbItem>
+				)}
+				<BreadcrumbSeparator />
+				{isDetailView ? (
+					<>
+						<BreadcrumbItem>
+							<BreadcrumbLink asChild>
+								<Link to={listPath}>{listLabel}</Link>
+							</BreadcrumbLink>
+						</BreadcrumbItem>
+						<BreadcrumbSeparator />
+						<BreadcrumbItem>
+							{loading && !recordName ? (
+								<Skeleton className="h-4 w-32" />
+							) : (
+								<BreadcrumbPage>{recordName}</BreadcrumbPage>
+							)}
+						</BreadcrumbItem>
+					</>
+				) : (
+					<BreadcrumbItem>
+						<BreadcrumbPage>{listLabel}</BreadcrumbPage>
+					</BreadcrumbItem>
+				)}
+			</BreadcrumbList>
+		</Breadcrumb>
+	);
+}