@salesforce/webapp-template-app-react-template-b2e-experimental 1.109.5 → 1.109.6

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/features/object-search/hooks/useObjectSearchParams.ts

@@ -0,0 +1,225 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useSearchParams } from "react-router";
+import type { FilterFieldConfig, ActiveFilterValue } from "../utils/filterUtils";
+import type { SortFieldConfig, SortState } from "../utils/sortUtils";
+import { filtersToSearchParams, searchParamsToFilters, buildFilter } from "../utils/filterUtils";
+import { buildOrderBy } from "../utils/sortUtils";
+import { debounce } from "../utils/debounce";
+
+/** How long to wait before flushing local state changes to the URL. */
+const URL_SYNC_DEBOUNCE_MS = 300;
+
+export interface PaginationConfig {
+	defaultPageSize: number;
+	validPageSizes: number[];
+}
+
+/**
+ * Manages filter, sort, and cursor-based pagination state for an object search page.
+ *
+ * ## State model
+ * Local React state is the primary driver for instant UI updates.
+ * URL search params act as the durable source of truth so that a page
+ * refresh or shared link restores the same view. Changes are synced to
+ * the URL via a debounced write (300 ms) to avoid excessive history entries.
+ *
+ * ## Return shape
+ * Returns memoized groups so each group's reference is stable unless its
+ * contents change — safe to pass directly as props to `React.memo` children.
+ *
+ * - `filters`    — active filter values + set/remove callbacks
+ * - `sort`       — current sort state + set callback
+ * - `query`      — derived `where` / `orderBy` objects ready for the API
+ * - `pagination` — page size, page index, cursor, and navigation callbacks
+ * - `resetAll`   — clears all filters, sort, and pagination in one call
+ */
+export function useObjectSearchParams<TFilter, TOrderBy>(
+	filterConfigs: FilterFieldConfig[],
+	_sortConfigs?: SortFieldConfig[],
+	paginationConfig?: PaginationConfig,
+) {
+	const defaultPageSize = paginationConfig?.defaultPageSize ?? 10;
+	const validPageSizes = paginationConfig?.validPageSizes ?? [defaultPageSize];
+	const [searchParams, setSearchParams] = useSearchParams();
+
+	// Seed local state from URL on initial load
+	const initial = useMemo(
+		() => searchParamsToFilters(searchParams, filterConfigs),
+		// Only run on mount — local state takes over after that, no deps needed
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+		[],
+	);
+
+	const [filters, setFilters] = useState<ActiveFilterValue[]>(initial.filters);
+	const [sort, setLocalSort] = useState<SortState | null>(initial.sort);
+
+	// Pagination — cursor-based with a stack to support "previous page" navigation.
+	const getValidPageSize = (size: number) =>
+		validPageSizes.includes(size) ? size : defaultPageSize;
+
+	const [pageSize, setPageSizeState] = useState<number>(
+		getValidPageSize(initial.pageSize ?? defaultPageSize),
+	);
+	const [pageIndex, setPageIndex] = useState(initial.pageIndex);
+	const [afterCursor, setAfterCursor] = useState<string | undefined>(undefined);
+	const cursorStackRef = useRef<string[]>([]);
+
+	// Debounced URL sync — keeps URL in sync without blocking the UI
+	const syncToUrl = useCallback(
+		(
+			nextFilters: ActiveFilterValue[],
+			nextSort: SortState | null,
+			nextPageSize?: number,
+			nextPageIndex?: number,
+		) => {
+			const params = filtersToSearchParams(nextFilters, nextSort, nextPageSize, nextPageIndex);
+			setSearchParams(params, { replace: true });
+		},
+		[setSearchParams],
+	);
+
+	const debouncedSyncRef = useRef(debounce(syncToUrl, URL_SYNC_DEBOUNCE_MS));
+	useEffect(() => {
+		debouncedSyncRef.current = debounce(syncToUrl, URL_SYNC_DEBOUNCE_MS);
+	}, [syncToUrl]);
+
+	// Snapshot ref — lets callbacks read the latest state without being
+	// recreated on every render (avoids infinite useCallback chains).
+	const stateRef = useRef({ filters, sort, pageSize, pageIndex });
+	stateRef.current = { filters, sort, pageSize, pageIndex };
+
+	// Any filter/sort change resets pagination to the first page.
+	const resetPagination = useCallback(() => {
+		setPageIndex(0);
+		setAfterCursor(undefined);
+		cursorStackRef.current = [];
+	}, []);
+
+	// -- Filter callbacks -------------------------------------------------------
+
+	const setFilter = useCallback(
+		(field: string, value: ActiveFilterValue | undefined) => {
+			const { sort: s, pageSize: ps } = stateRef.current;
+			setFilters((prev) => {
+				const next = prev.filter((f) => f.field !== field);
+				if (value) next.push(value);
+				debouncedSyncRef.current(next, s, ps);
+				return next;
+			});
+			resetPagination();
+		},
+		[resetPagination],
+	);
+
+	const removeFilter = useCallback(
+		(field: string) => {
+			const { sort: s, pageSize: ps } = stateRef.current;
+			setFilters((prev) => {
+				const next = prev.filter((f) => f.field !== field);
+				debouncedSyncRef.current(next, s, ps);
+				return next;
+			});
+			resetPagination();
+		},
+		[resetPagination],
+	);
+
+	// -- Sort callback ----------------------------------------------------------
+
+	const setSort = useCallback(
+		(nextSort: SortState | null) => {
+			const { filters: f, pageSize: ps } = stateRef.current;
+			setLocalSort(nextSort);
+			debouncedSyncRef.current(f, nextSort, ps);
+			resetPagination();
+		},
+		[resetPagination],
+	);
+
+	// -- Reset ------------------------------------------------------------------
+
+	const resetAll = useCallback(() => {
+		setFilters([]);
+		setLocalSort(null);
+		resetPagination();
+		syncToUrl([], null, defaultPageSize, 0);
+		setPageSizeState(defaultPageSize);
+	}, [syncToUrl, resetPagination]);
+
+	// -- Pagination callbacks ---------------------------------------------------
+	// Uses a cursor stack to track visited pages. "Next" pushes the current
+	// endCursor onto the stack; "Previous" pops it to restore the prior cursor.
+
+	const goToNextPage = useCallback((endCursor: string) => {
+		cursorStackRef.current = [...cursorStackRef.current, endCursor];
+		setAfterCursor(endCursor);
+		setPageIndex((prev) => {
+			const nextIndex = prev + 1;
+			const { filters: f, sort: s, pageSize: ps } = stateRef.current;
+			debouncedSyncRef.current(f, s, ps, nextIndex);
+			return nextIndex;
+		});
+	}, []);
+
+	const goToPreviousPage = useCallback(() => {
+		const stack = cursorStackRef.current;
+		const next = stack.slice(0, -1);
+		cursorStackRef.current = next;
+		setAfterCursor(next.length > 0 ? next[next.length - 1] : undefined);
+		setPageIndex((prev) => {
+			const nextIndex = Math.max(0, prev - 1);
+			const { filters: f, sort: s, pageSize: ps } = stateRef.current;
+			debouncedSyncRef.current(f, s, ps, nextIndex);
+			return nextIndex;
+		});
+	}, []);
+
+	const setPageSize = useCallback(
+		(newSize: number) => {
+			const validated = getValidPageSize(newSize);
+			const { filters: f, sort: s } = stateRef.current;
+			setPageSizeState(validated);
+			resetPagination();
+			debouncedSyncRef.current(f, s, validated);
+		},
+		[resetPagination],
+	);
+
+	// -- Derived query objects ---------------------------------------------------
+	// Translate local filter/sort state into API-ready `where` and `orderBy`.
+
+	const where = useMemo(
+		() => buildFilter<TFilter>(filters, filterConfigs),
+		[filters, filterConfigs],
+	);
+
+	const orderBy = useMemo(() => buildOrderBy<TOrderBy>(sort), [sort]);
+
+	// -- Memoized return groups -------------------------------------------------
+	// Each group is individually memoized so its object reference stays stable
+	// unless the contained values change. This makes it safe to pass a group
+	// (e.g. `pagination`) directly as props to a React.memo child without
+	// causing unnecessary re-renders.
+
+	const filtersGroup = useMemo(
+		() => ({ active: filters, set: setFilter, remove: removeFilter }),
+		[filters, setFilter, removeFilter],
+	);
+
+	const sortGroup = useMemo(() => ({ current: sort, set: setSort }), [sort, setSort]);
+
+	const query = useMemo(() => ({ where, orderBy }), [where, orderBy]);
+
+	const pagination = useMemo(
+		() => ({ pageSize, pageIndex, afterCursor, setPageSize, goToNextPage, goToPreviousPage }),
+		[pageSize, pageIndex, afterCursor, setPageSize, goToNextPage, goToPreviousPage],
+	);
+
+	return {
+		filters: filtersGroup,
+		sort: sortGroup,
+		query,
+		pagination,
+		resetAll,
+	};
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/features/object-search/utils/debounce.ts

@@ -0,0 +1,22 @@
+/**
+ * Creates a debounced version of the provided function.
+ *
+ * Each call to the returned function resets the internal timer. The wrapped
+ * function is only invoked once the timer expires without being reset. This
+ * makes it ideal for rate-limiting high-frequency events like input changes.
+ *
+ * @typeParam T - The function signature to debounce.
+ * @param fn - The function to debounce.
+ * @param ms - The debounce delay in milliseconds.
+ * @returns A new function with the same signature that delays execution.
+ */
+export function debounce<T extends (...args: never[]) => void>(
+	fn: T,
+	ms: number,
+): (...args: Parameters<T>) => void {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	return (...args: Parameters<T>) => {
+		clearTimeout(timer);
+		timer = setTimeout(() => fn(...args), ms);
+	};
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/features/object-search/utils/fieldUtils.ts

@@ -0,0 +1,29 @@
+export function fieldValue(
+	field: { displayValue?: string | null; value?: unknown } | null | undefined,
+): string | null {
+	if (field?.displayValue != null) return field.displayValue;
+	if (field?.value != null) return String(field.value);
+	return null;
+}
+
+export function getAddressFieldLines(address: {
+	street?: string | null;
+	city?: string | null;
+	state?: string | null;
+	postalCode?: string | null;
+	country?: string | null;
+}) {
+	const cityStateZip = [address.city, address.state].filter(Boolean).join(", ");
+	const cityStateZipLine = [cityStateZip, address.postalCode].filter(Boolean).join(" ");
+	const lines = [address.street, cityStateZipLine, address.country].filter(Boolean);
+	if (lines.length === 0) return null;
+	return lines;
+}
+
+export function formatDateTimeField(
+	value?: string | null,
+	...args: Parameters<Date["toLocaleString"]>
+) {
+	if (!value) return null;
+	return new Date(value).toLocaleString(...args);
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/features/object-search/utils/filterUtils.ts

@@ -0,0 +1,372 @@
+/**
+ * filterUtils.ts
+ *
+ * Centralizes all filter-related transformations for the object search feature.
+ * This module handles two distinct concerns:
+ *
+ * 1. **URL serialization** — Converting filter/sort state to and from
+ *    URLSearchParams so that search criteria can be bookmarked, shared, and
+ *    restored on page load.
+ *
+ * 2. **GraphQL query building** — Converting the same filter state into the
+ *    `where` clause shape expected by the GraphQL API.
+ *
+ * Both concerns operate on the shared {@link ActiveFilterValue} type, which
+ * represents a single active filter with a field name, filter type, and one or
+ * more values (value, min, max).
+ */
+
+import type { SortState } from "./sortUtils";
+
+export type FilterFieldType =
+	| "text"
+	| "picklist"
+	| "numeric"
+	| "boolean"
+	| "date"
+	| "daterange"
+	| "multipicklist"
+	| "search";
+
+export type FilterFieldConfig<TFieldName extends string = string> = {
+	field: TFieldName;
+	label: string;
+	type: FilterFieldType;
+	placeholder?: string;
+	/** Required for picklist type. */
+	options?: Array<{ value: string; label: string }>;
+	helpText?: string;
+	/** Required for search type — the fields to match against with `or`. */
+	searchFields?: string[];
+};
+
+export type ActiveFilterValue<TFieldName extends string = string> = {
+	field: TFieldName;
+	label: string;
+	type: FilterFieldType;
+	value?: string;
+	min?: string;
+	max?: string;
+};
+
+// ---------------------------------------------------------------------------
+// URL Serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Prefix applied to all filter-related URL search params.
+ * This namespaces filter params so they don't collide with other query params
+ * (e.g. pagination, feature flags).
+ *
+ * @example "f.Industry=Technology" or "f.AnnualRevenue.min=1000000"
+ */
+const FILTER_PREFIX = "f.";
+
+/** URL param key for the multi-field search term. */
+const SEARCH_KEY = "q";
+
+/** URL param key for the currently sorted field name. */
+const SORT_KEY = "sort";
+
+/** URL param key for the sort direction (ASC or DESC). */
+const DIR_KEY = "dir";
+
+/** URL param key for the page size preference. */
+const PAGE_SIZE_KEY = "ps";
+const PAGE_KEY = "page";
+
+/**
+ * Serializes filter and sort state into URLSearchParams.
+ *
+ * Encoding scheme:
+ *   - Simple values (text, picklist, boolean, multipicklist):
+ *       `f.<field>=<value>`
+ *   - Range values (numeric, date, daterange):
+ *       `f.<field>.min=<min>` and/or `f.<field>.max=<max>`
+ *   - Sort: `sort=<field>&dir=ASC|DESC`
+ *
+ * @param filters - The currently active filters to serialize.
+ * @param sort    - The current sort state, or null if no sort is applied.
+ * @returns A URLSearchParams instance representing the full search state.
+ *
+ * @example
+ * ```ts
+ * const params = filtersToSearchParams(
+ *   [{ field: "Industry", type: "picklist", value: "Technology" }],
+ *   { field: "Name", direction: "ASC" },
+ * );
+ * // params.toString() => "f.Industry=Technology&sort=Name&dir=ASC"
+ * ```
+ */
+export function filtersToSearchParams(
+	filters: ActiveFilterValue[],
+	sort: SortState | null,
+	pageSize?: number,
+	pageIndex?: number,
+): URLSearchParams {
+	const params = new URLSearchParams();
+
+	for (const filter of filters) {
+		if (filter.type === "search") {
+			if (filter.value) params.set(SEARCH_KEY, filter.value);
+			continue;
+		}
+		if (filter.value !== undefined && filter.value !== "") {
+			params.set(`${FILTER_PREFIX}${filter.field}`, filter.value);
+		}
+		if (filter.min !== undefined && filter.min !== "") {
+			params.set(`${FILTER_PREFIX}${filter.field}.min`, filter.min);
+		}
+		if (filter.max !== undefined && filter.max !== "") {
+			params.set(`${FILTER_PREFIX}${filter.field}.max`, filter.max);
+		}
+	}
+
+	if (sort) {
+		params.set(SORT_KEY, sort.field);
+		params.set(DIR_KEY, sort.direction);
+	}
+
+	if (pageSize !== undefined) {
+		params.set(PAGE_SIZE_KEY, String(pageSize));
+	}
+
+	if (pageIndex !== undefined && pageIndex > 0) {
+		params.set(PAGE_KEY, String(pageIndex + 1));
+	}
+
+	return params;
+}
+
+/**
+ * Deserializes URLSearchParams back into filter and sort state.
+ *
+ * Requires the full list of filter configs so it knows which URL params to look
+ * for and what type each filter is. Params that don't match a known config are
+ * silently ignored, making this safe against stale or hand-edited URLs.
+ *
+ * @param params  - The URLSearchParams to parse (typically from the browser URL).
+ * @param configs - The filter field configurations defining available filters.
+ * @returns An object containing the deserialized `filters` array and `sort` state.
+ *
+ * @example
+ * ```ts
+ * const url = new URLSearchParams("f.Industry=Technology&sort=Name&dir=ASC");
+ * const { filters, sort } = searchParamsToFilters(url, filterConfigs);
+ * // filters => [{ field: "Industry", type: "picklist", value: "Technology" }]
+ * // sort    => { field: "Name", direction: "ASC" }
+ * ```
+ */
+export function searchParamsToFilters(
+	params: URLSearchParams,
+	configs: FilterFieldConfig[],
+): {
+	filters: ActiveFilterValue[];
+	sort: SortState | null;
+	pageSize: number | undefined;
+	pageIndex: number;
+} {
+	const filters: ActiveFilterValue[] = [];
+
+	for (const config of configs) {
+		const { field, label, type } = config;
+
+		if (type === "search") {
+			const q = params.get(SEARCH_KEY);
+			if (q) {
+				filters.push({ field, label, type: "search", value: q });
+			}
+			continue;
+		}
+
+		const value = params.get(`${FILTER_PREFIX}${field}`) ?? undefined;
+		const min = params.get(`${FILTER_PREFIX}${field}.min`) ?? undefined;
+		const max = params.get(`${FILTER_PREFIX}${field}.max`) ?? undefined;
+
+		const hasValue = value !== undefined && value !== "";
+		const hasRange = (min !== undefined && min !== "") || (max !== undefined && max !== "");
+
+		if (hasValue || hasRange) {
+			filters.push({ field, label, type, value, min, max });
+		}
+	}
+
+	let sort: SortState | null = null;
+	const sortField = params.get(SORT_KEY);
+	const sortDir = params.get(DIR_KEY);
+	if (sortField) {
+		sort = {
+			field: sortField,
+			direction: sortDir === "DESC" ? "DESC" : "ASC",
+		};
+	}
+
+	const pageSizeRaw = params.get(PAGE_SIZE_KEY);
+	const pageSize = pageSizeRaw ? parseInt(pageSizeRaw, 10) : undefined;
+
+	const pageRaw = params.get(PAGE_KEY);
+	const page = pageRaw ? parseInt(pageRaw, 10) : 1;
+	const pageIndex = !isNaN(page) && page > 1 ? page - 1 : 0;
+
+	return {
+		filters,
+		sort,
+		pageSize: pageSize && !isNaN(pageSize) ? pageSize : undefined,
+		pageIndex,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL Filter Building
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts an array of active filter values into a GraphQL `where` clause.
+ *
+ * Each filter is individually converted to a clause via {@link buildSingleFilter},
+ * then multiple clauses are combined with a top-level `and` operator. This ensures
+ * all active filters are applied simultaneously (intersection semantics).
+ *
+ * @typeParam TFilter - The GraphQL filter input type (e.g. `AccountFilterInput`).
+ * @param filters - The active filters to convert.
+ * @returns A filter object for the GraphQL `where` variable, or `undefined` if
+ *          no filters are active (which tells the API to return unfiltered results).
+ *
+ * @example
+ * ```ts
+ * const where = buildFilter<AccountFilterInput>([
+ *   { field: "Industry", type: "picklist", value: "Technology" },
+ *   { field: "AnnualRevenue", type: "numeric", min: "1000000" },
+ * ]);
+ * // where => { and: [
+ * //   { Industry: { eq: "Technology" } },
+ * //   { AnnualRevenue: { gte: 1000000 } },
+ * // ]}
+ * ```
+ */
+export function buildFilter<TFilter>(
+	filters: ActiveFilterValue[],
+	configs: FilterFieldConfig[],
+): TFilter | undefined {
+	const configMap = new Map(configs.map((c) => [c.field, c]));
+	const clauses: TFilter[] = [];
+
+	for (const filter of filters) {
+		const clause = buildSingleFilter<TFilter>(filter, configMap.get(filter.field));
+		if (clause) clauses.push(clause);
+	}
+
+	if (clauses.length === 0) return undefined;
+	if (clauses.length === 1) return clauses[0];
+	return { and: clauses } as TFilter;
+}
+
+/**
+ * Converts a YYYY-MM-DD date string to a full ISO-8601 datetime at midnight UTC.
+ * Used as the inclusive lower bound for date range queries.
+ */
+function toStartOfDay(dateStr: string): string {
+	return `${dateStr}T00:00:00.000Z`;
+}
+
+/**
+ * Converts a YYYY-MM-DD date string to a full ISO-8601 datetime at the last
+ * millisecond of the day in UTC. Used as the inclusive upper bound for date
+ * range queries.
+ */
+function toEndOfDay(dateStr: string): string {
+	return `${dateStr}T23:59:59.999Z`;
+}
+
+/**
+ * Converts a single active filter value into a GraphQL filter clause.
+ *
+ * Supported filter types and their GraphQL mappings:
+ *
+ * | Type            | GraphQL operator(s) | Example output                                           |
+ * |-----------------|---------------------|----------------------------------------------------------|
+ * | `text`          | `like`              | `{ Name: { like: "%Acme%" } }`                           |
+ * | `picklist`      | `eq`                | `{ Industry: { eq: "Technology" } }`                      |
+ * | `multipicklist` | `eq` or `in`        | `{ Type: { in: ["A", "B"] } }`                            |
+ * | `numeric`       | `gte` / `lte`       | `{ Revenue: { gte: 1000, lte: 5000 } }`                   |
+ * | `boolean`       | `eq`                | `{ IsActive: { eq: true } }`                              |
+ * | `date`          | dynamic operator    | `{ CreatedDate: { gte: { value: "..." } } }`              |
+ * | `daterange`     | `gte` + `lte`       | Combined with `and` if both bounds set                    |
+ * | `search`        | `like` + `or`       | `{ or: [{ Name: { like: "%x%" } }, { Phone: { like: "%x%" } }] }` |
+ *
+ * The `search` type uses `config.searchFields` to build an `or` clause that
+ * matches the search term across multiple fields simultaneously (union semantics).
+ *
+ * @param filter - The active filter value to convert.
+ * @param config - The corresponding field config. Required for `search` type
+ *                 (provides `searchFields`); optional for all other types.
+ * @returns A single filter clause, or `null` if the filter has no meaningful value.
+ */
+function buildSingleFilter<TFilter>(
+	filter: ActiveFilterValue,
+	config?: FilterFieldConfig,
+): TFilter | null {
+	const { field, type, value, min, max } = filter;
+
+	switch (type) {
+		case "text": {
+			if (!value) return null;
+			return { [field]: { like: `%${value}%` } } as TFilter;
+		}
+		case "picklist": {
+			if (!value) return null;
+			return { [field]: { eq: value } } as TFilter;
+		}
+		case "numeric": {
+			if (!min && !max) return null;
+			const ops: Record<string, number> = {};
+			if (min) ops.gte = Number(min);
+			if (max) ops.lte = Number(max);
+			return { [field]: ops } as TFilter;
+		}
+		case "boolean": {
+			if (value === undefined || value === "") return null;
+			return { [field]: { eq: value === "true" } } as TFilter;
+		}
+		case "multipicklist": {
+			if (!value) return null;
+			const values = value.split(",");
+			if (values.length === 1) {
+				return { [field]: { eq: values[0] } } as TFilter;
+			}
+			return { [field]: { in: values } } as TFilter;
+		}
+		case "date": {
+			if (!min && !max) return null;
+			const op = value ?? (min ? "gte" : "lte");
+			const dateStr = min ?? max;
+			const isoStr = op === "gte" || op === "gt" ? toStartOfDay(dateStr!) : toEndOfDay(dateStr!);
+			return { [field]: { [op]: { value: isoStr } } } as TFilter;
+		}
+		case "daterange": {
+			if (!min && !max) return null;
+			const clauses: TFilter[] = [];
+			if (min) {
+				clauses.push({
+					[field]: { gte: { value: toStartOfDay(min) } },
+				} as TFilter);
+			}
+			if (max) {
+				clauses.push({
+					[field]: { lte: { value: toEndOfDay(max) } },
+				} as TFilter);
+			}
+			return clauses.length === 1 ? clauses[0] : ({ and: clauses } as TFilter);
+		}
+		case "search": {
+			if (!value) return null;
+			const searchFields = config?.searchFields ?? [];
+			if (searchFields.length === 0) return null;
+			const clauses = searchFields.map((f) => ({ [f]: { like: `%${value}%` } }) as TFilter);
+			if (clauses.length === 1) return clauses[0];
+			return { or: clauses } as TFilter;
+		}
+		default:
+			return null;
+	}
+}

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/src/features/object-search/utils/sortUtils.ts

@@ -0,0 +1,38 @@
+import { ResultOrder, NullOrder } from "../../../api/graphql-operations-types";
+
+export type SortFieldConfig<TFieldName extends string = string> = {
+	field: TFieldName;
+	label: string;
+};
+
+export type SortState<TFieldName extends string = string> = {
+	field: TFieldName;
+	direction: "ASC" | "DESC";
+};
+
+/**
+ * Converts a {@link SortState} into a GraphQL order-by object.
+ *
+ * @typeParam TOrderBy - The GraphQL order-by input type (e.g. `AccountOrderByInput`).
+ * @param sort - The current sort state from the UI, or `null` if no sort is applied.
+ * @returns An order-by object for the GraphQL query's `orderBy` variable, or
+ *          `undefined` if no sort is active (which uses the API's default ordering).
+ *
+ * @example
+ * ```ts
+ * const orderBy = buildOrderBy<AccountOrderByInput>({
+ *   field: "Name",
+ *   direction: "ASC",
+ * });
+ * // orderBy => { Name: { order: ResultOrder.Asc, nulls: NullOrder.Last } }
+ * ```
+ */
+export function buildOrderBy<TOrderBy>(sort: SortState | null): TOrderBy | undefined {
+	if (!sort) return undefined;
+	return {
+		[sort.field]: {
+			order: sort.direction === "ASC" ? ResultOrder.Asc : ResultOrder.Desc,
+			nulls: NullOrder.Last,
+		},
+	} as TOrderBy;
+}