@scalepad/ui 0.1.0

package/src/hooks/useServerTable.ts

@@ -0,0 +1,495 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import {
+  useInfiniteQuery,
+  type InfiniteData,
+  type UseInfiniteQueryOptions,
+} from '@tanstack/react-query';
+import {
+  type ExpandedState,
+  type VisibilityState,
+  getCoreRowModel,
+  getExpandedRowModel,
+  useReactTable,
+  type ColumnDef,
+  type OnChangeFn,
+  type RowSelectionState,
+  type SortingState,
+  type Table,
+} from '@tanstack/react-table';
+
+import { useStableValue } from '@scalepad/ui-utils/hooks';
+
+import { nestFlatRows, type WithSubRows } from '../utils/nestFlatRows';
+
+import type { InfiniteScrollState } from '../components/InfiniteScrollTrigger';
+
+/**
+ * Generic list response type for paginated API endpoints.
+ * Shared contract between useServerTable and query options functions.
+ */
+export interface ListResponse<TData> {
+  data: TData[];
+  nextCursor?: string | null;
+}
+
+/**
+ * Options for the useServerTable hook
+ */
+export interface UseServerTableOptions<TData, TFilters extends object> {
+  /**
+   * Column definitions for TanStack Table
+   */
+  columns: ColumnDef<TData, unknown>[];
+  /**
+   * Function that returns infinite query options given filters
+   * The filters will include converted sort params (sort_by, sort_order)
+   */
+  queryOptions: (
+    filters: TFilters,
+  ) => UseInfiniteQueryOptions<
+    ListResponse<TData>,
+    Error,
+    InfiniteData<ListResponse<TData>>,
+    readonly unknown[],
+    string
+  >;
+  /**
+   * Filter params to pass to the query (search, view mode, date range, etc.)
+   * Sort params will be added automatically based on table sorting state
+   */
+  filters: TFilters;
+  /**
+   * Optional function to extract row ID from data
+   * @default (row) => row.id
+   */
+  getRowId?: (row: TData) => string;
+  /**
+   * Optional field name mapping from TanStack Table column IDs to API sort field names
+   * @example { app_name: 'name', unique_users: 'users_count' }
+   */
+  sortFieldMapping?: Record<string, string>;
+  /**
+   * Enable row selection
+   * @default false
+   */
+  enableRowSelection?: boolean;
+  /**
+   * Initial sorting state (e.g. [{ id: 'canonical_name', desc: false }]).
+   * Use when the API expects a default sort on first load.
+   */
+  initialSorting?: SortingState;
+  /**
+   * Initial column visibility map keyed by column ID.
+   * Omitted IDs default to visible.
+   * @example { approval_status: false, discovered_date: false }
+   */
+  initialColumnVisibility?: VisibilityState;
+  /**
+   * Opt in to tree rows (row grouping via expansion).
+   *
+   * Exactly one of `getSubRows` or `getParentId` must be provided:
+   * - `getSubRows`: server already returns nested data; the hook uses it
+   *   directly.
+   * - `getParentId`: server returns a flat list with a parent reference on
+   *   each row; the hook nests it via {@link nestFlatRows} before handing it
+   *   to TanStack Table.
+   *
+   * Expand state can be either uncontrolled (seeded via `initialExpanded`)
+   * or controlled (`expanded` + `onExpandedChange`). Default is all
+   * collapsed.
+   */
+  tree?: {
+    /**
+     * Return nested child rows for a given row. Mutually exclusive with
+     * `getParentId`.
+     */
+    getSubRows?: (row: TData) => TData[] | undefined;
+    /**
+     * Return the `id` of this row's parent (or nullish for a root). Mutually
+     * exclusive with `getSubRows`. When present the hook nests the flat
+     * result of the infinite query via `nestFlatRows`.
+     */
+    getParentId?: (row: TData) => string | null | undefined;
+    /**
+     * How to handle rows that reference a parentId not present in the data.
+     * Only honored when using `getParentId`.
+     * @default "throw"
+     */
+    onOrphan?: 'throw' | 'drop';
+    /**
+     * Initial expand state (uncontrolled mode only).
+     * - `"none"` (default): everything collapsed.
+     * - `"all"`: every row with children starts expanded.
+     * - An explicit `ExpandedState` for fine-grained control.
+     */
+    initialExpanded?: 'all' | 'none' | ExpandedState;
+    /**
+     * Controlled expand state. When provided the hook does not maintain its
+     * own state; pair with `onExpandedChange`.
+     */
+    expanded?: ExpandedState;
+    /**
+     * Called when the table wants to change expanded state. Required in
+     * controlled mode.
+     */
+    onExpandedChange?: OnChangeFn<ExpandedState>;
+  };
+}
+
+/**
+ * Return type for the useServerTable hook
+ */
+export interface UseServerTableReturn<TData> {
+  /**
+   * TanStack Table instance (use for rendering)
+   */
+  table: Table<TData>;
+  /**
+   * Flattened data array from all pages
+   */
+  data: TData[];
+  /**
+   * True ONLY on first load (no cached data) -> show skeleton
+   */
+  isInitialLoading: boolean;
+  /**
+   * True when data exists but refetching (sort/filter change) -> show subtle indicator
+   */
+  isRefetching: boolean;
+  /**
+   * True when query failed
+   */
+  isError: boolean;
+  /**
+   * True when the data is empty (no results) and not loading
+   * Use this to disable controls or show "no data" UI
+   */
+  hasNoData: boolean;
+  /**
+   * Pagination state for InfiniteScrollTrigger
+   */
+  pagination: InfiniteScrollState;
+  /**
+   * Selected row IDs (when enableRowSelection is true)
+   */
+  selectedIds: Set<string>;
+  /**
+   * Clear row selection
+   */
+  clearSelection: () => void;
+  /**
+   * Set table sorting state (e.g. for external sort controls like a grid sort dropdown).
+   * Uses the same signature as TanStack Table's onSortingChange.
+   */
+  setSorting: OnChangeFn<SortingState>;
+  /**
+   * Current expand state. Only meaningful when `tree` was configured.
+   * In uncontrolled mode this reflects the hook's internal state; in
+   * controlled mode it mirrors the `tree.expanded` prop.
+   */
+  expanded: ExpandedState;
+  /**
+   * Programmatically set expand state (e.g. "expand all" / "collapse all"
+   * toolbar buttons). A no-op when `tree` was not configured.
+   */
+  setExpanded: OnChangeFn<ExpandedState>;
+}
+
+/**
+ * Flatten infinite query pages into a single array
+ */
+function flattenInfinitePages<TData>(
+  data: InfiniteData<ListResponse<TData>>,
+): TData[] {
+  return data.pages.flatMap(page => page.data);
+}
+
+/**
+ * Convert TanStack Table sorting state to API query params
+ * @example [{ id: 'app_name', desc: true }] -> { sort_by: 'app_name', sort_order: 'desc' }
+ */
+function convertSortingToApiParams(
+  sorting: SortingState,
+  sortFieldMapping?: Record<string, string>,
+): { sort_by?: string; sort_order?: 'asc' | 'desc' } {
+  if (sorting.length === 0) {
+    return { sort_by: undefined, sort_order: undefined };
+  }
+
+  // SortingState is an array (TanStack Table supports multi-column sorting),
+  // but our API only accepts a single sort_by/sort_order pair, so we use the first entry.
+  const sortState = sorting[0];
+  const apiFieldName = sortFieldMapping?.[sortState.id] ?? sortState.id;
+
+  return {
+    sort_by: apiFieldName,
+    sort_order: sortState.desc ? 'desc' : 'asc',
+  };
+}
+
+/**
+ * Hook for server-side table with TanStack Table + useInfiniteQuery
+ *
+ * Combines TanStack Table's state management with TanStack Query's data fetching
+ * to create a seamless server-side table experience with:
+ * - Declarative column definitions
+ * - Automatic sort state -> API params conversion
+ * - Clean loading state semantics (isInitialLoading vs isRefetching)
+ * - Smooth transitions with placeholderData
+ * - Built-in row selection (optional)
+ *
+ * @example Basic usage
+ * ```tsx
+ * const { table, ...states } = useServerTable({
+ *   columns: appColumns,
+ *   queryOptions: (filters) => appsInfiniteQueryOptions(clientId, filters),
+ *   filters: { granularity, date, q: search },
+ * });
+ *
+ * <DataTable {...states} table={table} emptyState={...} />
+ * ```
+ *
+ * @example With row selection
+ * ```tsx
+ * const { table, selectedIds, clearSelection, ...states } = useServerTable({
+ *   columns: userColumns,
+ *   queryOptions: (filters) => usersInfiniteQueryOptions(clientId, filters),
+ *   filters: { q: search },
+ *   enableRowSelection: true,
+ * });
+ * ```
+ */
+export function useServerTable<TData, TFilters extends object>({
+  columns,
+  queryOptions,
+  filters,
+  getRowId = row => String((row as { id: string | number }).id),
+  sortFieldMapping,
+  enableRowSelection = false,
+  initialSorting,
+  initialColumnVisibility,
+  tree,
+}: UseServerTableOptions<TData, TFilters>): UseServerTableReturn<TData> {
+  // TanStack Table state: sorting
+  const [sorting, setSorting] = useState<SortingState>(initialSorting ?? []);
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(
+    initialColumnVisibility ?? {},
+  );
+
+  // TanStack Table state: row selection (optional)
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+
+  // Dev-time validation: exactly one of getSubRows / getParentId must be set
+  // when tree is enabled. We don't guard on NODE_ENV here because this is
+  // cheap and the hook is only used inside React.
+  if (tree) {
+    const hasSub = !!tree.getSubRows;
+    const hasParent = !!tree.getParentId;
+    if (hasSub === hasParent) {
+      console.warn(
+        '[useServerTable] `tree` requires exactly one of `getSubRows` or `getParentId`.',
+      );
+    }
+    if (tree.expanded !== undefined && tree.onExpandedChange === undefined) {
+      console.warn(
+        '[useServerTable] `tree.expanded` was provided without `tree.onExpandedChange`; expand toggling will be a no-op.',
+      );
+    }
+  }
+
+  // TanStack Table state: expanded (only used when tree is enabled and
+  // consumer has not taken control). We always instantiate the state hook
+  // (rules of hooks) but only feed it into useReactTable when relevant.
+  // TanStack's `ExpandedState` supports `true` as a shorthand for
+  // "every expandable row is expanded", which is exactly what `'all'`
+  // means here.
+  const [internalExpanded, setInternalExpanded] = useState<ExpandedState>(
+    () => {
+      if (!tree) return {};
+      const initial = tree.initialExpanded;
+      if (initial === undefined || initial === 'none') return {};
+      if (initial === 'all') return true;
+      return initial;
+    },
+  );
+
+  // Stabilize filters object to prevent unnecessary refetches when parent components
+  // re-render with new filter object references but same values
+  const stableFilters = useStableValue(filters);
+
+  // Convert TanStack Table sorting to API params
+  const sortParams = useMemo(
+    () => convertSortingToApiParams(sorting, sortFieldMapping),
+    [sorting, sortFieldMapping],
+  );
+
+  // Merge sort params with user filters
+  const queryFilters = useMemo(
+    () => ({ ...stableFilters, ...sortParams }) as TFilters,
+    [stableFilters, sortParams],
+  );
+
+  // Fetch data with infinite query
+  const queryResult = useInfiniteQuery({
+    ...queryOptions(queryFilters),
+    // Keep previous data visible while fetching new sorted data
+    // This makes sorting feel instant instead of showing a skeleton
+    // CRITICAL: Don't use placeholderData if we don't have data yet for THIS query
+    // (data might exist from a previous query with different filters)
+    placeholderData: previousData => {
+      // If there's no previous data, don't use placeholder
+      if (!previousData) return undefined;
+      // Use placeholder to keep UI smooth during refetches
+      return previousData;
+    },
+  });
+
+  const {
+    data,
+    hasNextPage,
+    isFetchingNextPage,
+    fetchNextPage,
+    isLoading,
+    isError,
+    isFetching,
+  } = queryResult;
+
+  // Flatten pages into single array
+  const flattenedData = useMemo(
+    () => (data ? flattenInfinitePages(data) : []),
+    [data],
+  );
+
+  // When tree is enabled with `getParentId`, nest the flat result into a
+  // tree. When tree is enabled with `getSubRows`, the server already
+  // returns nested data and we pass it through untouched. When tree is
+  // disabled, pass the flat data through untouched.
+  const tableData = useMemo<TData[]>(() => {
+    if (!tree || !tree.getParentId) {
+      return flattenedData;
+    }
+    const nested = nestFlatRows(flattenedData, {
+      getId: getRowId,
+      getParentId: tree.getParentId,
+      onOrphan: tree.onOrphan ?? 'throw',
+    }) as (TData & WithSubRows<TData>)[];
+    return nested;
+  }, [flattenedData, tree, getRowId]);
+
+  // Pick the effective expand state + setter (controlled vs uncontrolled).
+  const expandedState: ExpandedState = tree
+    ? (tree.expanded ?? internalExpanded)
+    : {};
+  const onExpandedChange: OnChangeFn<ExpandedState> = tree
+    ? (tree.onExpandedChange ??
+      (setInternalExpanded as OnChangeFn<ExpandedState>))
+    : (setInternalExpanded as OnChangeFn<ExpandedState>);
+
+  // Resolve `getSubRows` for TanStack. Priority:
+  // 1. Consumer-provided `tree.getSubRows`.
+  // 2. When nesting via `getParentId`, read off the `subRows` field written
+  //    by `nestFlatRows`.
+  // 3. Otherwise, undefined (flat table behavior).
+  const treeGetSubRows: ((row: TData) => TData[] | undefined) | undefined =
+    tree?.getSubRows ??
+    (tree?.getParentId
+      ? (row: TData) => (row as WithSubRows<TData>).subRows
+      : undefined);
+
+  // Derive clean loading states
+  const isInitialLoading = isLoading;
+  const isRefetching = !isLoading && isFetching;
+
+  // Derive initial column pinning from column meta (meta.pinned: 'left' | 'right')
+  const initialColumnPinning = useMemo(() => {
+    const left: string[] = [];
+    const right: string[] = [];
+    for (const col of columns) {
+      const id = (col as ColumnDef<TData>).id;
+      const pinned = (col as ColumnDef<TData>).meta as
+        | { pinned?: 'left' | 'right' }
+        | undefined;
+      if (typeof id === 'string' && pinned?.pinned === 'left') left.push(id);
+      if (typeof id === 'string' && pinned?.pinned === 'right') right.push(id);
+    }
+    return { left, right };
+  }, [columns]);
+
+  // Create TanStack Table instance
+  const table = useReactTable({
+    data: tableData,
+    columns,
+    getCoreRowModel: getCoreRowModel(),
+    // Always provide getRowId so row.id is a stable entity ID (used as React key),
+    // not the default array index which causes reconciliation bugs on sort/page changes.
+    getRowId,
+    // Server-side sorting
+    manualSorting: true,
+    // Enable column sizing - columns without explicit size will use default 150px
+    defaultColumn: {
+      size: 150,
+      minSize: 40,
+      maxSize: 500,
+    },
+    initialState: {
+      columnPinning: initialColumnPinning,
+    },
+    state: {
+      sorting,
+      columnVisibility,
+      ...(enableRowSelection && { rowSelection }),
+      ...(tree && { expanded: expandedState }),
+    },
+    onSortingChange: setSorting as OnChangeFn<SortingState>,
+    onColumnVisibilityChange:
+      setColumnVisibility as OnChangeFn<VisibilityState>,
+    ...(enableRowSelection && {
+      onRowSelectionChange: setRowSelection as OnChangeFn<RowSelectionState>,
+      enableRowSelection: true,
+      // Select descendants alongside a group row so checkbox + chevron can
+      // coexist meaningfully on grouped rows.
+      enableSubRowSelection: true,
+    }),
+    ...(tree && {
+      getSubRows: treeGetSubRows,
+      getExpandedRowModel: getExpandedRowModel(),
+      onExpandedChange,
+    }),
+  });
+
+  // Extract selected row IDs
+  const selectedIds = useMemo(() => {
+    if (!enableRowSelection) return new Set<string>();
+    return new Set(Object.keys(rowSelection));
+  }, [rowSelection, enableRowSelection]);
+
+  const clearSelection = useCallback(() => {
+    setRowSelection({});
+  }, []);
+
+  // Detect "no data" state - empty result set that's not due to loading.
+  // When nesting via `getParentId` we compare the root-level array length,
+  // so a fully-orphaned response still renders as empty.
+  const hasNoData = tableData.length === 0 && !isInitialLoading;
+
+  return {
+    table,
+    data: flattenedData,
+    isInitialLoading,
+    isRefetching,
+    isError,
+    hasNoData,
+    pagination: {
+      hasNextPage,
+      isFetchingNextPage,
+      fetchNextPage,
+      totalPages: data?.pages.length ?? 0,
+    },
+    selectedIds,
+    clearSelection,
+    setSorting: setSorting as OnChangeFn<SortingState>,
+    expanded: expandedState,
+    setExpanded: onExpandedChange,
+  };
+}

package/src/hooks/useTableSelection.ts

@@ -0,0 +1,102 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+
+export interface UseTableSelectionReturn {
+  isSelectionMode: boolean;
+  selectedIds: Set<string>;
+  selectedCount: number;
+  toggleSelectionMode: () => void;
+  toggleRow: (id: string) => void;
+  toggleSelectAll: () => void;
+  isRowSelected: (id: string) => boolean;
+  isAllSelected: boolean;
+  clearSelection: () => void;
+  getRowProps: (id: string) => {
+    onClick: (() => void) | undefined;
+    className: string | undefined;
+  };
+}
+
+export function useTableSelection<T extends Record<string, unknown>>(
+  data: T[],
+  idKey: keyof T = 'id',
+): UseTableSelectionReturn {
+  const [isSelectionMode, setIsSelectionMode] = useState(false);
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set());
+
+  // Use a ref to store the current selectedIds to avoid recreating callbacks
+  const selectedIdsRef = useRef(selectedIds);
+  selectedIdsRef.current = selectedIds;
+
+  // Toggle selection mode on/off (clears selections when turning off)
+  const toggleSelectionMode = useCallback(() => {
+    setIsSelectionMode(prev => !prev);
+    setSelectedIds(new Set());
+  }, []);
+
+  // Toggle individual row selection
+  const toggleRow = useCallback((id: string) => {
+    setSelectedIds(prev => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+  }, []);
+
+  // Select/deselect all visible rows
+  const toggleSelectAll = useCallback(() => {
+    const allIds = data.map(item => String(item[idKey]));
+
+    setSelectedIds(prev => {
+      const allSelected = allIds.every(id => prev.has(id));
+      return allSelected ? new Set() : new Set(allIds);
+    });
+  }, [data, idKey]);
+
+  // Check if specific row is selected
+  // Uses ref to avoid recreating callback on every selection change
+  const isRowSelected = useCallback(
+    (id: string) => selectedIdsRef.current.has(id),
+    [],
+  );
+
+  // Check if all visible rows are selected
+  const isAllSelected = useMemo(() => {
+    if (data.length === 0) return false;
+    return data.every(item => selectedIds.has(String(item[idKey])));
+  }, [data, idKey, selectedIds]);
+
+  // Clear all selections
+  const clearSelection = useCallback(() => {
+    setSelectedIds(new Set());
+  }, []);
+
+  // Get props for table row (handles click + styling)
+  const getRowProps = useCallback(
+    (id: string) => ({
+      onClick: isSelectionMode ? () => toggleRow(id) : undefined,
+      className: isSelectionMode
+        ? isRowSelected(id)
+          ? 'selectable-row selected-row'
+          : 'selectable-row'
+        : undefined,
+    }),
+    [isSelectionMode, isRowSelected, toggleRow],
+  );
+
+  return {
+    isSelectionMode,
+    selectedIds,
+    selectedCount: selectedIds.size,
+    toggleSelectionMode,
+    toggleRow,
+    toggleSelectAll,
+    isRowSelected,
+    isAllSelected,
+    clearSelection,
+    getRowProps,
+  };
+}