@scalepad/ui 0.1.0

package/src/hooks/useTableSort.ts

@@ -0,0 +1,259 @@
+import { useCallback, useMemo, useState } from 'react';
+
+/**
+ * Options for the useTableSort hook (client-side sorting)
+ */
+export interface UseTableSortOptionsClientSide<TData, TSortField> {
+  /**
+   * Data array to sort (for client-side sorting)
+   */
+  data: TData[];
+  /**
+   * Custom comparator function for sorting
+   * @param a - First item to compare
+   * @param b - Second item to compare
+   * @param field - Field to sort by
+   * @param order - Sort order ('asc' or 'desc')
+   * @returns Negative if a < b, positive if a > b, 0 if equal
+   */
+  sortComparator: (
+    a: TData,
+    b: TData,
+    field: TSortField,
+    order: 'asc' | 'desc',
+  ) => number;
+  /**
+   * Whether to use client-side sorting (must be true for this overload)
+   */
+  enableClientSort: true;
+}
+
+/**
+ * Options for the useTableSort hook (server-side sorting)
+ */
+export interface UseTableSortOptionsServerSide {
+  /**
+   * Whether to use client-side sorting (must be false for this overload)
+   */
+  enableClientSort: false;
+}
+
+/**
+ * Legacy options interface for backward compatibility
+ */
+export interface UseTableSortOptions<TData, TSortField> {
+  /**
+   * Data array to sort (for client-side sorting)
+   */
+  data?: TData[];
+  /**
+   * Custom comparator function for sorting
+   * @param a - First item to compare
+   * @param b - Second item to compare
+   * @param field - Field to sort by
+   * @param order - Sort order ('asc' or 'desc')
+   * @returns Negative if a < b, positive if a > b, 0 if equal
+   */
+  sortComparator?: (
+    a: TData,
+    b: TData,
+    field: TSortField,
+    order: 'asc' | 'desc',
+  ) => number;
+  /**
+   * Whether to use client-side sorting
+   * - true: Sort data in-memory (instant, but only works with complete dataset)
+   * - false: Return sort state for API queries (works with pagination)
+   * @default false
+   */
+  enableClientSort?: boolean;
+}
+
+/**
+ * Return type for the useTableSort hook
+ */
+export interface UseTableSortReturn<TData, TSortField> {
+  /**
+   * Current sort field (null if no sort applied)
+   */
+  sortBy: TSortField | null;
+  /**
+   * Current sort order (null if no sort applied)
+   */
+  sortOrder: 'asc' | 'desc' | null;
+  /**
+   * Toggle sort for a field
+   * Cycles through: null → 'asc' → 'desc' → null
+   */
+  toggleSort: (field: TSortField) => void;
+  /**
+   * Get props to spread on column header element
+   * Provides onClick handler and aria-sort attribute
+   */
+  getSortProps: (field: TSortField) => {
+    onClick: () => void;
+    'aria-sort': 'ascending' | 'descending' | 'none';
+  };
+  /**
+   * Sorted data array
+   * - If enableClientSort is true: returns sorted data
+   * - If enableClientSort is false: returns original data (API handles sorting)
+   */
+  sortedData: TData[];
+  /**
+   * Sort state for API queries (server-side sorting)
+   * Pass these to your API query options when enableClientSort is false
+   */
+  sortState: {
+    sort_by: TSortField | null;
+    sort_order: 'asc' | 'desc' | null;
+  };
+}
+
+/**
+ * Hook for managing table sorting with hybrid client/server-side support
+ *
+ * This hook provides a smart sorting strategy:
+ * - Client-side sorting: Instant sorting when all data is loaded
+ * - Server-side sorting: API-based sorting when data is paginated
+ *
+ * @example Client-side sorting (all data loaded)
+ * ```tsx
+ * const sort = useTableSort({
+ *   data: users,
+ *   sortComparator: (a, b, field, order) => {
+ *     const result = a[field] - b[field];
+ *     return order === 'desc' ? -result : result;
+ *   },
+ *   enableClientSort: true
+ * });
+ *
+ * // Use sorted data
+ * return <Table data={sort.sortedData} />
+ * ```
+ *
+ * @example Server-side sorting (paginated data)
+ * ```tsx
+ * const sort = useTableSort<'username' | 'email'>({
+ *   enableClientSort: false
+ * });
+ *
+ * // Pass sort state to API query
+ * const { data } = useQuery(
+ *   usersQueryOptions(clientId, {
+ *     sort_by: sort.sortState.sort_by,
+ *     sort_order: sort.sortState.sort_order
+ *   })
+ * );
+ * ```
+ */
+export function useTableSort<TData, TSortField extends string>(
+  options: UseTableSortOptionsClientSide<TData, TSortField>,
+): UseTableSortReturn<TData, TSortField>;
+export function useTableSort<TSortField extends string>(
+  options: UseTableSortOptionsServerSide,
+): UseTableSortReturn<never, TSortField>;
+export function useTableSort<TData, TSortField extends string>({
+  data,
+  sortComparator,
+  enableClientSort = false,
+}: UseTableSortOptions<TData, TSortField>): UseTableSortReturn<
+  TData,
+  TSortField
+> {
+  const [sortBy, setSortBy] = useState<TSortField | null>(null);
+  const [sortOrder, setSortOrder] = useState<'asc' | 'desc' | null>(null);
+
+  /**
+   * Toggle sort for a field
+   * Cycles through: null → 'asc' → 'desc' → null
+   */
+  const toggleSort = useCallback(
+    (field: TSortField) => {
+      // If clicking a different field, start with ascending
+      if (sortBy !== field) {
+        setSortBy(field);
+        setSortOrder('asc');
+        return;
+      }
+
+      // If clicking the same field, cycle through states
+      if (sortOrder === null) {
+        // null → asc
+        setSortOrder('asc');
+      } else if (sortOrder === 'asc') {
+        // asc → desc
+        setSortOrder('desc');
+      } else {
+        // desc → null (clear sort)
+        setSortBy(null);
+        setSortOrder(null);
+      }
+    },
+    [sortBy, sortOrder],
+  );
+
+  /**
+   * Get props to spread on column header
+   */
+  const getSortProps = useCallback(
+    (field: TSortField) => ({
+      onClick: () => toggleSort(field),
+      'aria-sort': (sortBy === field
+        ? sortOrder === 'asc'
+          ? 'ascending'
+          : sortOrder === 'desc'
+            ? 'descending'
+            : 'none'
+        : 'none') as 'ascending' | 'descending' | 'none',
+    }),
+    [sortBy, sortOrder, toggleSort],
+  );
+
+  /**
+   * Sort data client-side if enabled and sort is active
+   */
+  const sortedData = useMemo(() => {
+    // If client-side sorting is disabled, return empty array (not used in server-side mode)
+    if (!enableClientSort) {
+      return (data ?? []) as TData[];
+    }
+
+    // If no data provided, return empty array
+    if (!data) {
+      return [];
+    }
+
+    // If no sort applied, return original data
+    if (sortBy === null || sortOrder === null) {
+      return data;
+    }
+
+    // Sort data using the provided comparator
+    if (!sortComparator) {
+      return data;
+    }
+
+    return [...data].sort((a, b) => sortComparator(a, b, sortBy, sortOrder));
+  }, [data, sortBy, sortOrder, enableClientSort, sortComparator]);
+
+  /**
+   * Sort state for API queries (server-side sorting)
+   */
+  const sortState = useMemo(
+    () => ({
+      sort_by: sortBy,
+      sort_order: sortOrder,
+    }),
+    [sortBy, sortOrder],
+  );
+
+  return {
+    sortBy,
+    sortOrder,
+    toggleSort,
+    getSortProps,
+    sortedData,
+    sortState,
+  };
+}