@multiplatform.one/table 6.0.0

package/src/hooks/useTableGrouping.ts

@@ -0,0 +1,176 @@
+import { useMemo, useState } from "react";
+
+// ---- Types (duplicated from DataTableGrouping to avoid importing JSX component) ----
+
+export type AggregationFunction = "count" | "sum" | "avg" | "min" | "max" | "custom";
+
+export interface AggregationConfig {
+  column: string;
+  function: AggregationFunction;
+  label?: string;
+  customFunction?: (values: any[]) => any;
+}
+
+export interface GroupedData<T = any> {
+  key: string;
+  value: any;
+  count: number;
+  aggregations: Record<string, any>;
+  items: T[];
+  children?: GroupedData<T>[];
+  level: number;
+  path: any[];
+}
+
+// ---- Grouping Utility (duplicated from DataTableGrouping) ----
+
+function groupDataInternal<T>(
+  data: T[],
+  groupByColumns: string[],
+  aggregations: AggregationConfig[],
+  maxDepth = 5,
+): GroupedData<T>[] | null {
+  if (!groupByColumns.length) return null;
+
+  const grouped = new Map<string, { items: T[]; key: any; path: any[] }>();
+
+  data.forEach((item) => {
+    const firstGroupValue = (item as any)[groupByColumns[0]];
+    const key = String(firstGroupValue || "null");
+
+    if (!grouped.has(key)) {
+      grouped.set(key, {
+        items: [],
+        key: firstGroupValue,
+        path: [firstGroupValue],
+      });
+    }
+
+    const group = grouped.get(key);
+    if (group) {
+      group.items.push(item);
+    }
+  });
+
+  const result = Array.from(grouped.entries()).map(([key, group]) => {
+    const aggregationsResult: Record<string, any> = {};
+
+    aggregations.forEach((agg) => {
+      if (!aggregationsResult[agg.column]) {
+        aggregationsResult[agg.column] = {};
+      }
+
+      const values = group.items
+        .map((item) => (item as any)[agg.column])
+        .filter((val) => val != null);
+
+      switch (agg.function) {
+        case "count":
+          aggregationsResult[agg.column].count = group.items.length;
+          break;
+        case "sum": {
+          aggregationsResult[agg.column].sum = values.reduce(
+            (sum, val) => sum + (Number(val) || 0),
+            0,
+          );
+          break;
+        }
+        case "avg": {
+          const sum = values.reduce((sum, val) => sum + (Number(val) || 0), 0);
+          aggregationsResult[agg.column].avg =
+            values.length > 0 ? Math.round((sum / values.length) * 100) / 100 : 0;
+          break;
+        }
+        case "min": {
+          aggregationsResult[agg.column].min =
+            values.length > 0 ? Math.min(...values.map(Number)) : 0;
+          break;
+        }
+        case "max": {
+          aggregationsResult[agg.column].max =
+            values.length > 0 ? Math.max(...values.map(Number)) : 0;
+          break;
+        }
+        case "custom":
+          aggregationsResult[agg.column].custom = agg.customFunction
+            ? agg.customFunction(values)
+            : null;
+          break;
+      }
+    });
+
+    const groupedItem: GroupedData<T> = {
+      key,
+      value: group.key,
+      count: group.items.length,
+      aggregations: aggregationsResult,
+      items: group.items,
+      level: 0,
+      path: group.path,
+    };
+
+    if (groupByColumns.length > 1 && groupedItem.level < maxDepth - 1) {
+      const childGroups = groupDataInternal(
+        group.items,
+        groupByColumns.slice(1),
+        aggregations,
+        maxDepth,
+      );
+      if (childGroups) {
+        groupedItem.children = childGroups.map((child) => ({
+          ...child,
+          level: child.level + 1,
+          path: [group.key, ...child.path],
+        }));
+      }
+    }
+
+    return groupedItem;
+  });
+
+  return result;
+}
+
+// ---- Hook ----
+
+export interface UseTableGroupingOptions<T = any> {
+  data?: T[];
+  initialGrouping?: string[];
+  initialAggregations?: AggregationConfig[];
+  maxDepth?: number;
+}
+
+export interface UseTableGroupingReturn<T = any> {
+  grouping: string[];
+  setGrouping: React.Dispatch<React.SetStateAction<string[]>>;
+  aggregations: AggregationConfig[];
+  setAggregations: React.Dispatch<React.SetStateAction<AggregationConfig[]>>;
+  groupedData: GroupedData<T>[] | null;
+  isGrouped: boolean;
+}
+
+export function useTableGrouping<T = any>({
+  data = [],
+  initialGrouping = [],
+  initialAggregations = [],
+  maxDepth = 5,
+}: UseTableGroupingOptions<T> = {}): UseTableGroupingReturn<T> {
+  const [grouping, setGrouping] = useState<string[]>(initialGrouping);
+  const [aggregations, setAggregations] = useState<AggregationConfig[]>(initialAggregations);
+
+  const groupedData = useMemo(() => {
+    if (!grouping.length) return null;
+    return groupDataInternal(data, grouping, aggregations, maxDepth);
+  }, [data, grouping, aggregations, maxDepth]);
+
+  const isGrouped = grouping.length > 0;
+
+  return {
+    grouping,
+    setGrouping,
+    aggregations,
+    setAggregations,
+    groupedData,
+    isGrouped,
+  };
+}

package/src/hooks/useTableKeyboard.ts

@@ -0,0 +1,127 @@
+/**
+ * useTableKeyboard - keyboard navigation for table rows.
+ *
+ * Renamed from useDataTableKeyboard, keeping the same implementation.
+ * Supports ArrowDown, ArrowUp, Home, End, PageDown, PageUp,
+ * Enter, and Space key handlers.
+ */
+
+import type { Row, Table } from "@tanstack/react-table";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+const rowHeightPx = 40;
+
+export interface UseTableKeyboardOptions<TData> {
+  table: Table<TData>;
+  enabled: boolean;
+  viewportHeight?: number;
+  onScrollToRow?: (rowIndex: number) => void;
+  onRowActivate?: (row: Row<TData>) => void;
+}
+
+export interface UseTableKeyboardReturn {
+  handleKeyDown: (event: React.KeyboardEvent) => void;
+  handleContainerClick: () => void;
+  handleContainerBlur: () => void;
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  focusedRowIndex: number;
+}
+
+export function useTableKeyboard<TData>({
+  table,
+  enabled,
+  viewportHeight = 400,
+  onScrollToRow,
+  onRowActivate,
+}: UseTableKeyboardOptions<TData>): UseTableKeyboardReturn {
+  const [focusedRowIndex, setFocusedRowIndex] = useState(-1);
+  const [_isNavigating, setIsNavigating] = useState(false);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  const rows = table.getRowModel().rows;
+  const rowCount = rows.length;
+  const pageSize = Math.max(1, Math.floor(viewportHeight / rowHeightPx));
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (!enabled || rowCount === 0) return;
+
+      switch (event.key) {
+        case "ArrowDown":
+          event.preventDefault();
+          setIsNavigating(true);
+          setFocusedRowIndex((prev) => (prev < 0 ? 0 : Math.min(prev + 1, rowCount - 1)));
+          break;
+        case "ArrowUp":
+          event.preventDefault();
+          setIsNavigating(true);
+          setFocusedRowIndex((prev) => (prev < 0 ? rowCount - 1 : Math.max(prev - 1, 0)));
+          break;
+        case "Home":
+          event.preventDefault();
+          setIsNavigating(true);
+          setFocusedRowIndex(0);
+          break;
+        case "End":
+          event.preventDefault();
+          setIsNavigating(true);
+          setFocusedRowIndex(rowCount - 1);
+          break;
+        case "PageDown":
+          event.preventDefault();
+          setIsNavigating(true);
+          setFocusedRowIndex((prev) => {
+            const start = prev < 0 ? 0 : prev;
+            return Math.min(start + pageSize, rowCount - 1);
+          });
+          break;
+        case "PageUp":
+          event.preventDefault();
+          setIsNavigating(true);
+          setFocusedRowIndex((prev) => {
+            const start = prev < 0 ? rowCount - 1 : prev;
+            return Math.max(start - pageSize, 0);
+          });
+          break;
+        case "Enter":
+        case " ":
+          event.preventDefault();
+          if (focusedRowIndex >= 0 && focusedRowIndex < rowCount) {
+            const row = rows[focusedRowIndex];
+            onRowActivate?.(row);
+          }
+          break;
+        default:
+          break;
+      }
+    },
+    [enabled, rowCount, pageSize, focusedRowIndex, rows, onRowActivate],
+  );
+
+  const handleContainerClick = useCallback(() => {
+    if (enabled && containerRef.current) {
+      containerRef.current.focus();
+      if (focusedRowIndex < 0 && rowCount > 0) {
+        setFocusedRowIndex(0);
+      }
+    }
+  }, [enabled, focusedRowIndex, rowCount]);
+
+  const handleContainerBlur = useCallback(() => {
+    setIsNavigating(false);
+  }, []);
+
+  useEffect(() => {
+    if (focusedRowIndex >= 0 && focusedRowIndex < rowCount && onScrollToRow) {
+      onScrollToRow(focusedRowIndex);
+    }
+  }, [focusedRowIndex, rowCount, onScrollToRow]);
+
+  return {
+    handleKeyDown,
+    handleContainerClick,
+    handleContainerBlur,
+    containerRef,
+    focusedRowIndex,
+  };
+}

package/src/hooks/useTablePagination.ts

@@ -0,0 +1,53 @@
+import type { PaginationState } from "@tanstack/react-table";
+import { useState } from "react";
+
+const defaultPageSize = 10;
+
+export interface UseTablePaginationOptions {
+  enablePagination?: boolean;
+  manualPagination?: boolean;
+  initialPagination?: PaginationState;
+  rowCount?: number;
+  pageCount?: number;
+}
+
+export interface UseTablePaginationReturn {
+  pagination: PaginationState;
+  setPagination: React.Dispatch<React.SetStateAction<PaginationState>>;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+}
+
+export function useTablePagination({
+  manualPagination = false,
+  initialPagination,
+  rowCount,
+  pageCount,
+}: UseTablePaginationOptions = {}): UseTablePaginationReturn {
+  const [pagination, setPagination] = useState<PaginationState>(
+    initialPagination || {
+      pageIndex: 0,
+      pageSize: defaultPageSize,
+    },
+  );
+
+  const totalPages =
+    manualPagination && pageCount != null
+      ? pageCount
+      : manualPagination && rowCount != null
+        ? Math.ceil(rowCount / pagination.pageSize)
+        : 0;
+
+  const hasNextPage = manualPagination ? pagination.pageIndex < totalPages - 1 : false;
+
+  const hasPreviousPage = pagination.pageIndex > 0;
+
+  return {
+    pagination,
+    setPagination,
+    totalPages,
+    hasNextPage,
+    hasPreviousPage,
+  };
+}

package/src/hooks/useTableSearch.ts

@@ -0,0 +1,51 @@
+import { useState } from "react";
+
+export interface TableSearchOptions {
+  searchTerm: string;
+  columns: string[];
+  caseSensitive: boolean;
+  wholeWord: boolean;
+  regex: boolean;
+  highlightResults: boolean;
+}
+
+export interface UseTableSearchOptions<T = any> {
+  data?: T[];
+  columns?: Array<{
+    accessorKey?: string;
+    header?: string;
+    id?: string;
+    searchable?: boolean;
+  }>;
+  debounceMs?: number;
+  defaultSearchColumns?: string[];
+}
+
+export interface UseTableSearchReturn {
+  searchQuery: string;
+  setSearchQuery: (query: string) => void;
+  searchOptions: TableSearchOptions;
+  setSearchOptions: React.Dispatch<React.SetStateAction<TableSearchOptions>>;
+}
+
+export function useTableSearch<T = any>({
+  columns = [],
+  defaultSearchColumns,
+}: UseTableSearchOptions<T> = {}): UseTableSearchReturn {
+  const [searchQuery, setSearchQuery] = useState("");
+  const [searchOptions, setSearchOptions] = useState<TableSearchOptions>({
+    searchTerm: "",
+    columns: defaultSearchColumns || columns.map((col) => col.accessorKey || col.id || ""),
+    caseSensitive: false,
+    wholeWord: false,
+    regex: false,
+    highlightResults: true,
+  });
+
+  return {
+    searchQuery,
+    setSearchQuery,
+    searchOptions,
+    setSearchOptions,
+  };
+}

package/src/hooks/useTableSelection.ts

@@ -0,0 +1,62 @@
+import type { RowSelectionState } from "@tanstack/react-table";
+import { useCallback, useState } from "react";
+
+export interface UseTableSelectionOptions {
+  initialSelection?: RowSelectionState;
+  onSelectionChange?: (selection: RowSelectionState) => void;
+}
+
+export interface UseTableSelectionReturn {
+  rowSelection: RowSelectionState;
+  setRowSelection: React.Dispatch<React.SetStateAction<RowSelectionState>>;
+  selectedRows: string[];
+  selectAll: (rowIds: string[]) => void;
+  clearSelection: () => void;
+}
+
+export function useTableSelection({
+  initialSelection = {},
+  onSelectionChange,
+}: UseTableSelectionOptions = {}): UseTableSelectionReturn {
+  const [rowSelection, setRowSelectionState] = useState<RowSelectionState>(initialSelection);
+
+  const setRowSelection: React.Dispatch<React.SetStateAction<RowSelectionState>> = useCallback(
+    (updater) => {
+      setRowSelectionState((prev) => {
+        const next = typeof updater === "function" ? updater(prev) : updater;
+        onSelectionChange?.(next);
+        return next;
+      });
+    },
+    [onSelectionChange],
+  );
+
+  const selectedRows = Object.entries(rowSelection)
+    .filter(([_, selected]) => selected)
+    .map(([id]) => id);
+
+  const selectAll = useCallback(
+    (rowIds: string[]) => {
+      const next: RowSelectionState = {};
+      for (const id of rowIds) {
+        next[id] = true;
+      }
+      setRowSelectionState(next);
+      onSelectionChange?.(next);
+    },
+    [onSelectionChange],
+  );
+
+  const clearSelection = useCallback(() => {
+    setRowSelectionState({});
+    onSelectionChange?.({});
+  }, [onSelectionChange]);
+
+  return {
+    rowSelection,
+    setRowSelection,
+    selectedRows,
+    selectAll,
+    clearSelection,
+  };
+}

package/src/hooks/useTableSorting.ts

@@ -0,0 +1,24 @@
+import type { SortingState } from "@tanstack/react-table";
+import { useState } from "react";
+
+export interface UseTableSortingOptions {
+  enableSorting?: boolean;
+  manualSorting?: boolean;
+  initialSorting?: SortingState;
+}
+
+export interface UseTableSortingReturn {
+  sorting: SortingState;
+  setSorting: React.Dispatch<React.SetStateAction<SortingState>>;
+}
+
+export function useTableSorting({
+  initialSorting = [],
+}: UseTableSortingOptions = {}): UseTableSortingReturn {
+  const [sorting, setSorting] = useState<SortingState>(initialSorting);
+
+  return {
+    sorting,
+    setSorting,
+  };
+}

package/src/hooks/useTableUrlSync.ts

@@ -0,0 +1,49 @@
+import { useMemo } from "react";
+import type { DataTableState } from "../types";
+import type { UrlStateStrategy } from "./useDataTable";
+import { deserializeTableState, serializeTableState } from "../utils/urlStateUtils";
+
+export interface UseTableUrlSyncOptions {
+  syncWithUrl?: boolean;
+  urlDebounceMs?: number;
+  urlStrategy?: UrlStateStrategy;
+  state?: Partial<DataTableState>;
+}
+
+export interface UseTableUrlSyncReturn {
+  syncState: (state: Partial<DataTableState>) => void;
+  loadFromUrl: () => Partial<DataTableState>;
+  deserializedState: Partial<DataTableState>;
+}
+
+export function useTableUrlSync({
+  syncWithUrl = false,
+  urlDebounceMs: _urlDebounceMs = 500,
+  urlStrategy,
+  state,
+}: UseTableUrlSyncOptions = {}): UseTableUrlSyncReturn {
+  const defaultState: Record<string, string> = {};
+
+  const [urlState, setUrlState] =
+    syncWithUrl && urlStrategy
+      ? urlStrategy.getState(state ? serializeTableState(state) : defaultState)
+      : [defaultState, () => {}];
+
+  const deserializedState = useMemo(() => deserializeTableState(urlState), [urlState]);
+
+  const syncState = (newState: Partial<DataTableState>) => {
+    if (!syncWithUrl) return;
+    const serialized = serializeTableState(newState);
+    setUrlState(serialized);
+  };
+
+  const loadFromUrl = (): Partial<DataTableState> => {
+    return deserializedState;
+  };
+
+  return {
+    syncState,
+    loadFromUrl,
+    deserializedState,
+  };
+}

package/src/hooks/useTableViews.ts

@@ -0,0 +1,113 @@
+import type {
+  ColumnSizingState,
+  PaginationState,
+  SortingState,
+  VisibilityState,
+} from "@tanstack/react-table";
+import { useCallback, useState } from "react";
+import type { TableFilter, TableView } from "../types";
+
+export interface UseTableViewsOptions {
+  initialViews?: TableView[];
+  initialActiveViewId?: string;
+}
+
+export interface UseTableViewsReturn {
+  views: TableView[];
+  activeViewId: string | undefined;
+  saveView: (
+    name: string,
+    currentState: {
+      columnVisibility: VisibilityState;
+      columnSizing: ColumnSizingState;
+      columnOrder: string[];
+      filters: TableFilter[];
+      sorting: SortingState;
+      pagination: PaginationState;
+      globalFilter: string;
+    },
+  ) => void;
+  loadView: (viewId: string) => TableView | undefined;
+  deleteView: (viewId: string) => void;
+  resetToDefault: () => void;
+  setViews: React.Dispatch<React.SetStateAction<TableView[]>>;
+  setActiveViewId: React.Dispatch<React.SetStateAction<string | undefined>>;
+}
+
+export function useTableViews({
+  initialViews = [],
+  initialActiveViewId,
+}: UseTableViewsOptions = {}): UseTableViewsReturn {
+  const [views, setViews] = useState<TableView[]>(initialViews);
+  const [activeViewId, setActiveViewId] = useState<string | undefined>(initialActiveViewId);
+
+  const saveView = useCallback(
+    (
+      name: string,
+      currentState: {
+        columnVisibility: VisibilityState;
+        columnSizing: ColumnSizingState;
+        columnOrder: string[];
+        filters: TableFilter[];
+        sorting: SortingState;
+        pagination: PaginationState;
+        globalFilter: string;
+      },
+    ) => {
+      const view: TableView = {
+        id: `view-${Date.now()}`,
+        name,
+        columns: Object.keys(currentState.columnVisibility).reduce((acc, colId) => {
+          acc[colId] = {
+            id: colId,
+            visible: currentState.columnVisibility[colId],
+            width: currentState.columnSizing[colId],
+            order: currentState.columnOrder.indexOf(colId),
+          };
+          return acc;
+        }, {} as any),
+        filters: currentState.filters,
+        sorting: currentState.sorting,
+        pagination: {
+          pageIndex: currentState.pagination.pageIndex,
+          pageSize: currentState.pagination.pageSize,
+        },
+        searchQuery: currentState.globalFilter,
+      };
+
+      setViews((prev) => [...prev, view]);
+    },
+    [],
+  );
+
+  const loadView = useCallback(
+    (viewId: string): TableView | undefined => {
+      const view = views.find((v) => v.id === viewId);
+      if (view) {
+        setActiveViewId(viewId);
+      }
+      return view;
+    },
+    [views],
+  );
+
+  const deleteView = useCallback((viewId: string) => {
+    setViews((prev) => prev.filter((v) => v.id !== viewId));
+    setActiveViewId((prev) => (prev === viewId ? undefined : prev));
+  }, []);
+
+  const resetToDefault = useCallback(() => {
+    setActiveViewId(undefined);
+  }, []);
+
+  return {
+    views,
+    activeViewId,
+    saveView,
+    loadView,
+    deleteView,
+    resetToDefault,
+    setViews,
+    setActiveViewId,
+  };
+}