@multiplatform.one/table 6.0.0

package/src/hooks/useDataTable.ts

@@ -0,0 +1,540 @@
+import {
+  type ColumnDef,
+  type ColumnOrderState,
+  type ColumnPinningState,
+  type ColumnSizingState,
+  type ExpandedState,
+  type GroupingState,
+  type PaginationState,
+  type VisibilityState,
+  getCoreRowModel,
+  getExpandedRowModel,
+  getFacetedMinMaxValues,
+  getFacetedRowModel,
+  getFacetedUniqueValues,
+  getFilteredRowModel,
+  getGroupedRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+} from "@tanstack/react-table";
+import { useSearchParams, useUrlState as useUrlStateFromRouter } from "@multiplatform.one/router";
+const useUrlState: typeof useUrlStateFromRouter = useUrlStateFromRouter;
+
+// URL State Strategy Interface
+
+export interface UrlStateStrategy {
+  getState: <T extends Record<string, any>>(
+    defaultValue: T,
+  ) => [T, (value: Partial<T> | ((prev: T) => Partial<T>) | T | ((prev: T) => T)) => void];
+  debounceMs?: number;
+}
+
+// Default OneStack strategy
+const createOneStackUrlStrategy = (debounceMs?: number): UrlStateStrategy => ({
+  getState: <T extends Record<string, any>>(defaultValue: T) =>
+    useUrlState(defaultValue, { debounceMs }),
+  debounceMs,
+});
+
+// React Router strategy
+const createReactRouterUrlStrategy = (
+  useSearchParams: any,
+  debounceMs?: number,
+): UrlStateStrategy => ({
+  getState: <T extends Record<string, any>>(defaultValue: T) => {
+    const [searchParams, setSearchParams] = useSearchParams();
+
+    const getValueFromUrl = () => {
+      try {
+        const serialized = searchParams.get("tableState");
+        if (!serialized) return defaultValue;
+
+        return JSON.parse(decodeURIComponent(serialized));
+      } catch (error) {
+        console.warn("Failed to parse table state from URL:", error);
+        return defaultValue;
+      }
+    };
+
+    const [state, _setState] = React.useState<T>(getValueFromUrl());
+
+    const updateUrl = React.useCallback(
+      (newState: Partial<T> | ((prev: T) => Partial<T>)) => {
+        try {
+          const newSearchParams = new URLSearchParams(searchParams);
+          newSearchParams.set("tableState", encodeURIComponent(JSON.stringify(newState)));
+          setSearchParams(newSearchParams);
+        } catch (error) {
+          console.warn("Failed to update URL with table state:", error);
+        }
+      },
+      [searchParams, setSearchParams],
+    );
+
+    return [state, updateUrl];
+  },
+  debounceMs,
+});
+
+// Next.js App Router strategy
+const createNextJsAppRouterStrategy = (
+  useSearchParams: any,
+  useRouter: any,
+  debounceMs?: number,
+): UrlStateStrategy => ({
+  getState: <T extends Record<string, any>>(defaultValue: T) => {
+    const searchParams = useSearchParams();
+    const router = useRouter();
+
+    const getValueFromUrl = () => {
+      try {
+        const serialized = searchParams.get("tableState");
+        if (!serialized) return defaultValue;
+
+        return JSON.parse(decodeURIComponent(serialized));
+      } catch (error) {
+        console.warn("Failed to parse table state from URL:", error);
+        return defaultValue;
+      }
+    };
+
+    const [state, _setState] = React.useState<T>(getValueFromUrl());
+
+    const updateUrl = React.useCallback(
+      (newState: Partial<T> | ((prev: T) => Partial<T>)) => {
+        try {
+          const newSearchParams = new URLSearchParams(searchParams);
+          newSearchParams.set("tableState", encodeURIComponent(JSON.stringify(newState)));
+          router.replace(`?${newSearchParams.toString()}`, { scroll: false });
+        } catch (error) {
+          console.warn("Failed to update URL with table state:", error);
+        }
+      },
+      [searchParams, router],
+    );
+
+    return [state, updateUrl];
+  },
+  debounceMs,
+});
+
+// Universal strategy (works everywhere)
+const createUniversalUrlStrategy = (debounceMs?: number): UrlStateStrategy => ({
+  getState: <T extends Record<string, any>>(defaultValue: T) => {
+    const [searchParams, setSearchParams] = useSearchParams();
+
+    const state = React.useMemo<T>(() => {
+      try {
+        const serialized = searchParams["tableState"];
+        if (serialized && typeof serialized === "string") {
+          return JSON.parse(decodeURIComponent(serialized));
+        }
+      } catch (error) {
+        console.warn("Failed to parse table state from URL:", error);
+      }
+      return defaultValue;
+    }, [searchParams]);
+
+    const updateUrl = React.useCallback(
+      (newState: Partial<T> | ((prev: T) => Partial<T>)) => {
+        try {
+          setSearchParams(
+            { tableState: encodeURIComponent(JSON.stringify(newState)) },
+            { replace: true, debounceMs },
+          );
+        } catch (error) {
+          console.warn("Failed to update URL with table state:", error);
+        }
+      },
+      [setSearchParams, debounceMs],
+    );
+
+    return [state, updateUrl];
+  },
+  debounceMs,
+});
+
+// Strategy Factory
+
+export const createUrlStrategy = {
+  oneStack: createOneStackUrlStrategy,
+  reactRouter: (useSearchParams: any, debounceMs?: number) =>
+    createReactRouterUrlStrategy(useSearchParams, debounceMs),
+  nextJs: (useSearchParams: any, useRouter: any, debounceMs?: number) =>
+    createNextJsAppRouterStrategy(useSearchParams, useRouter, debounceMs),
+  universal: createUniversalUrlStrategy,
+  custom: (strategy: UrlStateStrategy) => strategy,
+};
+
+import React, { useMemo, useState, useCallback, useEffect } from "react";
+import type {
+  DataTableData,
+  DataTableState,
+  UseDataTableOptions,
+  UseDataTableReturn,
+} from "../types";
+import { deserializeTableState, serializeTableState } from "../utils/urlStateUtils";
+import { useTableFiltering } from "./useTableFiltering";
+import { useTableSorting } from "./useTableSorting";
+import { useTableViews } from "./useTableViews";
+
+const defaultPageSize = 10;
+
+export function useDataTable<TData extends DataTableData = DataTableData>({
+  data = [],
+  columns = [],
+  initialState,
+  onStateChange,
+  syncWithUrl = false,
+  urlDebounceMs = 500,
+  urlStrategy,
+  manualFiltering = false,
+  manualPagination = false,
+  manualSorting = false,
+  enableFiltering = true,
+  enableSorting = true,
+  enablePagination: _enablePagination = true,
+  enableColumnVisibility = true,
+  enableColumnOrdering: _enableColumnOrdering = false,
+  enableColumnResizing = false,
+  enableGlobalSearch = true,
+  enableViews: _enableViews = false,
+  enableRowExpansion = false,
+  getSubRows,
+  enableColumnPinning = false,
+  enableGrouping = false,
+  rowCount,
+  pageCount,
+}: UseDataTableOptions<TData> & {
+  urlStrategy?: UrlStateStrategy;
+} = {}): UseDataTableReturn<TData> {
+  // ---- Default State ----
+
+  const defaultTableState: Partial<DataTableState> = {
+    pagination: {
+      pageIndex: 0,
+      pageSize: defaultPageSize,
+    },
+    sorting: [],
+    filters: [],
+    columnFilters: [],
+    globalFilter: "",
+    columnVisibility: {},
+    columnOrder: columns.map((col) => col.id || ""),
+    columnSizing: {},
+    views: [],
+    ...initialState,
+  };
+
+  // ---- URL State ----
+
+  const urlStateStrategy = urlStrategy || createUrlStrategy.oneStack(urlDebounceMs);
+
+  const [urlState, setUrlState] = syncWithUrl
+    ? urlStateStrategy.getState(serializeTableState(defaultTableState))
+    : [serializeTableState(defaultTableState), () => {}];
+
+  const deserializedState = useMemo(() => deserializeTableState(urlState), [urlState]);
+
+  // ---- Feature Hooks: Filtering ----
+
+  const filtering = useTableFiltering({
+    enableFiltering,
+    manualFiltering,
+    initialFilters: deserializedState.filters || defaultTableState.filters!,
+    initialColumnFilters: deserializedState.columnFilters || defaultTableState.columnFilters!,
+    initialGlobalFilter: deserializedState.globalFilter || defaultTableState.globalFilter!,
+  });
+
+  // ---- Feature Hooks: Sorting ----
+
+  const sortingHook = useTableSorting({
+    enableSorting,
+    manualSorting,
+    initialSorting: deserializedState.sorting || defaultTableState.sorting!,
+  });
+
+  // ---- Feature Hooks: Views ----
+
+  const viewsHook = useTableViews({
+    initialViews: deserializedState.views || defaultTableState.views!,
+    initialActiveViewId: deserializedState.activeViewId || defaultTableState.activeViewId,
+  });
+
+  // ---- Pagination State ----
+
+  const [pagination, setPagination] = useState<PaginationState>(
+    deserializedState.pagination || defaultTableState.pagination!,
+  );
+
+  // ---- Column Management State ----
+
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(
+    deserializedState.columnVisibility || defaultTableState.columnVisibility!,
+  );
+
+  const [columnOrder, setColumnOrder] = useState<ColumnOrderState>(
+    deserializedState.columnOrder || defaultTableState.columnOrder!,
+  );
+
+  const [columnSizing, setColumnSizing] = useState<ColumnSizingState>(
+    deserializedState.columnSizing || defaultTableState.columnSizing!,
+  );
+
+  const [expanded, setExpanded] = useState<ExpandedState>({});
+  const [grouping, setGrouping] = useState<GroupingState>([]);
+
+  const [columnPinning, setColumnPinning] = useState<ColumnPinningState>({ left: [], right: [] });
+
+  // ---- URL State Synchronization ----
+
+  useEffect(() => {
+    if (!syncWithUrl) return;
+
+    const currentState: Partial<DataTableState> = {
+      pagination,
+      sorting: sortingHook.sorting,
+      columnFilters: filtering.columnFilters,
+      globalFilter: filtering.globalFilter,
+      columnVisibility,
+      columnOrder,
+      columnSizing,
+      filters: filtering.advancedFilters,
+      views: viewsHook.views,
+      activeViewId: viewsHook.activeViewId,
+    };
+
+    const serialized = serializeTableState(currentState);
+    setUrlState(serialized);
+  }, [
+    syncWithUrl,
+    pagination,
+    sortingHook.sorting,
+    filtering.columnFilters,
+    filtering.globalFilter,
+    columnVisibility,
+    columnOrder,
+    columnSizing,
+    filtering.advancedFilters,
+    viewsHook.views,
+    viewsHook.activeViewId,
+    setUrlState,
+  ]);
+
+  // ---- TanStack Table Configuration ----
+
+  const table = useReactTable({
+    data,
+    columns: columns as ColumnDef<TData>[],
+    getCoreRowModel: getCoreRowModel(),
+    getExpandedRowModel: enableRowExpansion ? getExpandedRowModel() : undefined,
+    getSubRows: getSubRows
+      ? (row) => getSubRows(row.original as TData)
+      : (row) => (row.original as any)?.subRows,
+
+    state: {
+      pagination,
+      sorting: sortingHook.sorting,
+      columnFilters: filtering.columnFilters,
+      globalFilter: filtering.globalFilter,
+      columnVisibility,
+      columnOrder,
+      columnSizing,
+      ...(enableRowExpansion ? { expanded } : {}),
+      ...(enableColumnPinning ? { columnPinning } : {}),
+      ...(enableGrouping ? { grouping } : {}),
+    },
+
+    onPaginationChange: setPagination,
+    onSortingChange: sortingHook.setSorting,
+    onColumnFiltersChange: filtering.setColumnFilters,
+    onGlobalFilterChange: filtering.setGlobalFilter,
+    onColumnVisibilityChange: setColumnVisibility,
+    onColumnOrderChange: setColumnOrder,
+    onColumnSizingChange: setColumnSizing,
+    ...(enableRowExpansion ? { onExpandedChange: setExpanded } : {}),
+    ...(enableColumnPinning ? { onColumnPinningChange: setColumnPinning } : {}),
+    ...(enableGrouping ? { onGroupingChange: setGrouping } : {}),
+
+    getFilteredRowModel: manualFiltering ? undefined : getFilteredRowModel(),
+    getPaginationRowModel: manualPagination ? undefined : getPaginationRowModel(),
+    getSortedRowModel: manualSorting ? undefined : getSortedRowModel(),
+    getGroupedRowModel: enableGrouping ? getGroupedRowModel() : undefined,
+    getFacetedRowModel: enableFiltering ? getFacetedRowModel() : undefined,
+    getFacetedUniqueValues: enableFiltering ? getFacetedUniqueValues() : undefined,
+    getFacetedMinMaxValues: enableFiltering ? getFacetedMinMaxValues() : undefined,
+
+    manualFiltering,
+    manualPagination,
+    manualSorting,
+
+    ...(manualPagination && rowCount != null ? { rowCount } : {}),
+    ...(manualPagination && pageCount != null ? { pageCount } : {}),
+
+    columnResizeMode: "onChange",
+
+    enableSorting,
+    enableMultiSort: true,
+    enableColumnFilters: enableFiltering,
+    enableGlobalFilter: enableGlobalSearch,
+    enableHiding: enableColumnVisibility,
+    enableColumnResizing,
+  });
+
+  // ---- View Management ----
+
+  const saveView = useCallback(
+    (name: string) => {
+      viewsHook.saveView(name, {
+        columnVisibility,
+        columnSizing,
+        columnOrder,
+        filters: filtering.advancedFilters,
+        sorting: sortingHook.sorting,
+        pagination,
+        globalFilter: filtering.globalFilter,
+      });
+    },
+    [
+      viewsHook,
+      columnVisibility,
+      columnSizing,
+      columnOrder,
+      filtering.advancedFilters,
+      sortingHook.sorting,
+      pagination,
+      filtering.globalFilter,
+    ],
+  );
+
+  const loadView = useCallback(
+    (viewId: string) => {
+      const view = viewsHook.loadView(viewId);
+      if (!view) return;
+
+      filtering.setFilters(view.filters);
+      sortingHook.setSorting(view.sorting);
+      setPagination({
+        pageIndex: view.pagination.pageIndex,
+        pageSize: view.pagination.pageSize,
+      });
+      filtering.setGlobalFilter(view.searchQuery || "");
+
+      const visibility: VisibilityState = {};
+      Object.values(view.columns).forEach((col) => {
+        visibility[col.id] = col.visible;
+      });
+      setColumnVisibility(visibility);
+
+      const sizing: ColumnSizingState = {};
+      Object.values(view.columns).forEach((col) => {
+        if (col.width) sizing[col.id] = col.width;
+      });
+      setColumnSizing(sizing);
+    },
+    [viewsHook, filtering, sortingHook],
+  );
+
+  // ---- Computed Values ----
+
+  const filteredData = useMemo(() => {
+    if (manualFiltering) return data;
+    return table.getFilteredRowModel().rows.map((row) => row.original);
+  }, [data, table, manualFiltering]);
+
+  const paginatedData = useMemo(() => {
+    if (manualPagination) return filteredData;
+    return table.getPaginationRowModel().rows.map((row) => row.original);
+  }, [filteredData, table, manualPagination]);
+
+  const totalPages =
+    manualPagination && pageCount != null
+      ? pageCount
+      : manualPagination && rowCount != null
+        ? Math.ceil(rowCount / pagination.pageSize)
+        : Math.ceil((table.getFilteredRowModel().rows.length || 0) / pagination.pageSize);
+
+  // ---- Actions ----
+
+  const actions = {
+    setGlobalFilter: filtering.setGlobalFilter,
+    setFilters: filtering.setFilters,
+    addFilter: filtering.addFilter,
+    removeFilter: filtering.removeFilter,
+    clearFilters: filtering.clearFilters,
+    setPagination,
+    setSorting: sortingHook.setSorting,
+    toggleColumnVisibility: (columnId: string) => {
+      setColumnVisibility((prev) => ({
+        ...prev,
+        [columnId]: !prev[columnId],
+      }));
+    },
+    setColumnOrder,
+    setColumnSizing,
+    saveView,
+    loadView,
+    resetToDefault: () => {
+      setPagination(defaultTableState.pagination!);
+      sortingHook.setSorting(defaultTableState.sorting! as any);
+      filtering.setColumnFilters(defaultTableState.columnFilters! as any);
+      filtering.setGlobalFilter(defaultTableState.globalFilter!);
+      setColumnVisibility(defaultTableState.columnVisibility!);
+      setColumnOrder(defaultTableState.columnOrder!);
+      setColumnSizing(defaultTableState.columnSizing!);
+      filtering.setFilters(defaultTableState.filters! as any);
+      viewsHook.setActiveViewId(defaultTableState.activeViewId);
+      if (enableRowExpansion) setExpanded({});
+      if (enableColumnPinning) setColumnPinning({ left: [], right: [] });
+      if (enableGrouping) setGrouping([]);
+    },
+    ...(enableRowExpansion ? { setExpanded } : {}),
+    ...(enableGrouping ? { grouping, setGrouping } : {}),
+  };
+
+  const computed = {
+    filteredData,
+    paginatedData,
+    totalPages,
+    hasActiveFilters: filtering.hasActiveFilters,
+    activeFilterCount: filtering.activeFilterCount,
+  };
+
+  // ---- State Change Callback ----
+
+  const resolvedTotalCount =
+    manualPagination && rowCount != null ? rowCount : table.getFilteredRowModel().rows.length;
+
+  const currentState: DataTableState = {
+    data,
+    columns: columns as any,
+    pagination: {
+      ...pagination,
+      totalCount: resolvedTotalCount,
+      totalPages,
+      hasNextPage: table.getCanNextPage(),
+      hasPreviousPage: table.getCanPreviousPage(),
+    },
+    sorting: sortingHook.sorting,
+    filters: filtering.advancedFilters,
+    columnFilters: filtering.columnFilters,
+    globalFilter: filtering.globalFilter,
+    columnVisibility,
+    columnOrder,
+    columnSizing,
+    views: viewsHook.views,
+    activeViewId: viewsHook.activeViewId,
+  };
+
+  useEffect(() => {
+    onStateChange?.(currentState);
+  }, [currentState, onStateChange]);
+
+  return {
+    table,
+    state: currentState,
+    actions,
+    computed,
+  };
+}

package/src/hooks/useDataTableKeyboard.ts

@@ -0,0 +1,134 @@
+import type { Row, Table } from "@tanstack/react-table";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+const rowHeightPx = 40;
+
+export interface UseDataTableKeyboardOptions<TData> {
+  table: Table<TData>;
+  enabled: boolean;
+  /** Height of visible viewport for PageUp/PageDown (default 400) */
+  viewportHeight?: number;
+  /** When virtualization is enabled, callback to scroll to row index */
+  onScrollToRow?: (rowIndex: number) => void;
+  /** Callback when Enter/Space activates a row (e.g. expand) */
+  onRowActivate?: (row: Row<TData>) => void;
+}
+
+export interface UseDataTableKeyboardReturn {
+  focusedRowIndex: number;
+  setFocusedRowIndex: (index: number) => void;
+  isNavigating: boolean;
+  handleKeyDown: (event: React.KeyboardEvent) => void;
+  handleContainerClick: () => void;
+  handleContainerBlur: () => void;
+  containerRef: React.RefObject<HTMLDivElement | null>;
+}
+
+export function useDataTableKeyboard<TData>({
+  table,
+  enabled,
+  viewportHeight = 400,
+  onScrollToRow,
+  onRowActivate,
+}: UseDataTableKeyboardOptions<TData>): UseDataTableKeyboardReturn {
+  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 "ArrowLeft":
+          // Cell-level nav could be added later; for now we focus row
+          event.preventDefault();
+          break;
+        case "ArrowRight":
+          event.preventDefault();
+          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);
+  }, []);
+
+  // Scroll to focused row when it changes (for virtualization)
+  useEffect(() => {
+    if (focusedRowIndex >= 0 && focusedRowIndex < rowCount && onScrollToRow) {
+      onScrollToRow(focusedRowIndex);
+    }
+  }, [focusedRowIndex, rowCount, onScrollToRow]);
+
+  return {
+    focusedRowIndex,
+    setFocusedRowIndex,
+    isNavigating,
+    handleKeyDown,
+    handleContainerClick,
+    handleContainerBlur,
+    containerRef,
+  };
+}