@multiplatform.one/table 6.0.0

package/src/hooks/useDragScroll.ts

@@ -0,0 +1,80 @@
+/**
+ * useDragScroll - enables drag-to-scroll on a scrollable element.
+ *
+ * Web-only hook. On native, this is a no-op.
+ * Uses a 5px threshold before activating drag mode.
+ * Ignores interactive elements (button, input, select, textarea,
+ * [role="button"]).
+ */
+
+import { useEffect } from "react";
+import { isWeb } from "tamagui";
+
+export function useDragScroll(ref: React.RefObject<HTMLElement | null>, enabled: boolean = true) {
+  useEffect(() => {
+    if (!isWeb) return;
+    const el = ref.current;
+    if (!el || !enabled) return;
+
+    let isDown = false;
+    let startX = 0;
+    let startY = 0;
+    let scrollLeft = 0;
+    let scrollTop = 0;
+
+    const handleMouseDown = (e: MouseEvent) => {
+      if (e.button !== 0) return;
+      const target = e.target as HTMLElement;
+      if (target.closest('button, input, select, textarea, [role="button"]')) return;
+
+      isDown = true;
+      startX = e.clientX;
+      startY = e.clientY;
+      scrollLeft = el.scrollLeft;
+      scrollTop = el.scrollTop;
+      el.style.cursor = "grab";
+    };
+
+    const handleMouseUp = () => {
+      isDown = false;
+      el.style.cursor = "";
+    };
+
+    const handleMouseMove = (e: MouseEvent) => {
+      if (!isDown) return;
+
+      const x = e.clientX;
+      const y = e.clientY;
+      const diffX = Math.abs(x - startX);
+      const diffY = Math.abs(y - startY);
+
+      if (diffX > 5 || diffY > 5) {
+        el.style.cursor = "grabbing";
+        e.preventDefault();
+        el.scrollLeft = scrollLeft - (x - startX);
+        el.scrollTop = scrollTop - (y - startY);
+      }
+    };
+
+    const handleMouseLeave = () => {
+      if (isDown) {
+        isDown = false;
+        el.style.cursor = "";
+      }
+    };
+
+    el.addEventListener("mousedown", handleMouseDown);
+    el.addEventListener("mouseup", handleMouseUp);
+    el.addEventListener("mousemove", handleMouseMove);
+    el.addEventListener("mouseleave", handleMouseLeave);
+    document.addEventListener("mouseup", handleMouseUp);
+
+    return () => {
+      el.removeEventListener("mousedown", handleMouseDown);
+      el.removeEventListener("mouseup", handleMouseUp);
+      el.removeEventListener("mousemove", handleMouseMove);
+      el.removeEventListener("mouseleave", handleMouseLeave);
+      document.removeEventListener("mouseup", handleMouseUp);
+    };
+  }, [ref, enabled]);
+}

package/src/hooks/useSavedFilters.spec.ts

@@ -0,0 +1,232 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useSavedFilters } from "./useSavedFilters";
+import type { SavedFilter, SavedFiltersStorage } from "./useSavedFilters";
+
+describe("useSavedFilters", () => {
+  describe("in-memory mode (no storage)", () => {
+    it("starts with empty filters when no initialFilters provided", () => {
+      const { result } = renderHook(() => useSavedFilters());
+
+      expect(result.current.filters).toEqual([]);
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    it("initializes with provided initialFilters", () => {
+      const initial: SavedFilter[] = [
+        {
+          name: "f1",
+          filter_name: "Active Users",
+          for_user: "user@example.com",
+          filters: JSON.stringify([["status", "is", "active"]]),
+        },
+        {
+          name: "f2",
+          filter_name: "Global Filter",
+          for_user: "",
+          filters: JSON.stringify([["priority", "is", "high"]]),
+        },
+      ];
+
+      const { result } = renderHook(() => useSavedFilters({ initialFilters: initial }));
+
+      expect(result.current.filters).toHaveLength(2);
+      expect(result.current.filters[0].filter_name).toBe("Active Users");
+      expect(result.current.filters[0].isGlobal).toBe(false);
+      expect(result.current.filters[1].filter_name).toBe("Global Filter");
+      expect(result.current.filters[1].isGlobal).toBe(true);
+    });
+
+    it("saves a filter in memory", async () => {
+      const { result } = renderHook(() => useSavedFilters({ userId: "user@test.com" }));
+
+      await act(async () => {
+        await result.current.saveFilter("My Filter", [["name", "contains", "test"]], false);
+      });
+
+      expect(result.current.filters).toHaveLength(1);
+      expect(result.current.filters[0].filter_name).toBe("My Filter");
+      expect(result.current.filters[0].for_user).toBe("user@test.com");
+      expect(result.current.filters[0].isGlobal).toBe(false);
+      expect(result.current.filters[0].filters).toEqual([["name", "contains", "test"]]);
+    });
+
+    it("saves a global filter in memory", async () => {
+      const { result } = renderHook(() => useSavedFilters({ userId: "user@test.com" }));
+
+      await act(async () => {
+        await result.current.saveFilter("Global Filter", [["status", "is", "active"]], true);
+      });
+
+      expect(result.current.filters).toHaveLength(1);
+      expect(result.current.filters[0].for_user).toBe("");
+      expect(result.current.filters[0].isGlobal).toBe(true);
+    });
+
+    it("deletes a filter from memory", async () => {
+      const initial: SavedFilter[] = [
+        {
+          name: "f1",
+          filter_name: "Filter One",
+          for_user: "",
+          filters: JSON.stringify([["a", "is", "b"]]),
+        },
+        {
+          name: "f2",
+          filter_name: "Filter Two",
+          for_user: "",
+          filters: JSON.stringify([["c", "is", "d"]]),
+        },
+      ];
+
+      const { result } = renderHook(() => useSavedFilters({ initialFilters: initial }));
+
+      expect(result.current.filters).toHaveLength(2);
+
+      await act(async () => {
+        await result.current.deleteFilter("f1");
+      });
+
+      expect(result.current.filters).toHaveLength(1);
+      expect(result.current.filters[0].name).toBe("f2");
+    });
+
+    it("retrieves a filter by name", () => {
+      const initial: SavedFilter[] = [
+        {
+          name: "f1",
+          filter_name: "First",
+          for_user: "",
+          filters: JSON.stringify([["x", "is", "y"]]),
+        },
+      ];
+
+      const { result } = renderHook(() => useSavedFilters({ initialFilters: initial }));
+
+      expect(result.current.getFilterByName("f1")).toBeDefined();
+      expect(result.current.getFilterByName("f1")?.filter_name).toBe("First");
+      expect(result.current.getFilterByName("nonexistent")).toBeUndefined();
+    });
+
+    it("handles malformed filter JSON gracefully", () => {
+      const initial: SavedFilter[] = [
+        {
+          name: "bad",
+          filter_name: "Bad Filter",
+          for_user: "",
+          filters: "not valid json{{{",
+        },
+        {
+          name: "good",
+          filter_name: "Good Filter",
+          for_user: "",
+          filters: JSON.stringify([["a", "is", "b"]]),
+        },
+      ];
+
+      const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+      const { result } = renderHook(() => useSavedFilters({ initialFilters: initial }));
+
+      // Should skip the malformed filter and include the valid one
+      expect(result.current.filters).toHaveLength(1);
+      expect(result.current.filters[0].name).toBe("good");
+      consoleError.mockRestore();
+    });
+  });
+
+  describe("with storage adapter", () => {
+    it("loads filters from storage on mount", async () => {
+      const storedFilters: SavedFilter[] = [
+        {
+          name: "stored-1",
+          filter_name: "From Storage",
+          for_user: "",
+          filters: JSON.stringify([["field", "is", "value"]]),
+        },
+      ];
+
+      const storage: SavedFiltersStorage = {
+        load: vi.fn().mockResolvedValue(storedFilters),
+        save: vi.fn(),
+        remove: vi.fn(),
+      };
+
+      const { result } = renderHook(() => useSavedFilters({ storage }));
+
+      // Initially loading
+      expect(result.current.isLoading).toBe(true);
+
+      await waitFor(() => {
+        expect(result.current.isLoading).toBe(false);
+      });
+
+      expect(result.current.filters).toHaveLength(1);
+      expect(result.current.filters[0].filter_name).toBe("From Storage");
+      expect(storage.load).toHaveBeenCalledTimes(1);
+    });
+
+    it("saves and reloads via storage adapter", async () => {
+      const stored: SavedFilter[] = [];
+      const storage: SavedFiltersStorage = {
+        load: vi.fn().mockImplementation(() => Promise.resolve([...stored])),
+        save: vi.fn().mockImplementation((filter: SavedFilter) => {
+          stored.push(filter);
+          return Promise.resolve();
+        }),
+        remove: vi.fn(),
+      };
+
+      const { result } = renderHook(() => useSavedFilters({ storage, userId: "me" }));
+
+      await waitFor(() => {
+        expect(result.current.isLoading).toBe(false);
+      });
+
+      await act(async () => {
+        await result.current.saveFilter("New", [["a", "is", "b"]]);
+      });
+
+      expect(storage.save).toHaveBeenCalledTimes(1);
+      // load is called on mount + after save
+      expect(storage.load).toHaveBeenCalledTimes(2);
+    });
+
+    it("deletes via storage adapter", async () => {
+      const stored: SavedFilter[] = [
+        {
+          name: "to-delete",
+          filter_name: "Delete Me",
+          for_user: "",
+          filters: JSON.stringify([["a", "is", "b"]]),
+        },
+      ];
+
+      const storage: SavedFiltersStorage = {
+        load: vi.fn().mockImplementation(() => {
+          return Promise.resolve([...stored]);
+        }),
+        save: vi.fn(),
+        remove: vi.fn().mockImplementation((name: string) => {
+          const idx = stored.findIndex((f) => f.name === name);
+          if (idx >= 0) stored.splice(idx, 1);
+          return Promise.resolve();
+        }),
+      };
+
+      const { result } = renderHook(() => useSavedFilters({ storage }));
+
+      await waitFor(() => {
+        expect(result.current.isLoading).toBe(false);
+      });
+
+      expect(result.current.filters).toHaveLength(1);
+
+      await act(async () => {
+        await result.current.deleteFilter("to-delete");
+      });
+
+      expect(storage.remove).toHaveBeenCalledWith("to-delete");
+      expect(storage.load).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/src/hooks/useSavedFilters.ts

@@ -0,0 +1,189 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+/**
+ * A raw saved filter record as stored in persistence.
+ */
+export interface SavedFilter {
+  name: string;
+  filter_name?: string;
+  for_user?: string;
+  filters?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * A parsed, ready-to-use saved filter.
+ */
+export interface ParsedFilter {
+  name: string;
+  filter_name: string;
+  for_user: string;
+  filters: Array<[string, string, unknown]>;
+  isGlobal: boolean;
+}
+
+/**
+ * Generic storage adapter for saved filters.
+ * Implement this interface to connect to any persistence backend
+ * (REST API, localStorage, IndexedDB, Frappe, etc.).
+ */
+export interface SavedFiltersStorage {
+  /** Load all saved filters for a given context */
+  load: () => Promise<SavedFilter[]> | SavedFilter[];
+  /** Persist a new saved filter */
+  save: (filter: SavedFilter) => Promise<void> | void;
+  /** Remove a saved filter by name/id */
+  remove: (name: string) => Promise<void> | void;
+}
+
+export interface UseSavedFiltersOptions {
+  /** Storage adapter for persistence. If omitted, filters are kept in memory only. */
+  storage?: SavedFiltersStorage;
+  /** Pre-populated filters (useful for testing or SSR) */
+  initialFilters?: SavedFilter[];
+  /** Current user ID (used to determine isGlobal) */
+  userId?: string;
+}
+
+export interface SavedFiltersHook {
+  filters: ParsedFilter[];
+  isLoading: boolean;
+  saveFilter: (
+    filterName: string,
+    filterArray: Array<[string, string, unknown]>,
+    isGlobal?: boolean,
+  ) => Promise<void>;
+  deleteFilter: (name: string) => Promise<void>;
+  getFilterByName: (name: string) => ParsedFilter | undefined;
+}
+
+function parseRawFilter(filter: SavedFilter): ParsedFilter | null {
+  try {
+    const filtersStr = String(filter.filters || "[]");
+    const filterArray = JSON.parse(filtersStr);
+    return {
+      name: filter.name || "",
+      filter_name: String(filter.filter_name || ""),
+      for_user: String(filter.for_user || ""),
+      filters: Array.isArray(filterArray) ? filterArray : [],
+      isGlobal: !filter.for_user || filter.for_user === "",
+    };
+  } catch (e) {
+    console.error("Failed to parse filter:", filter, e);
+    return null;
+  }
+}
+
+/**
+ * Generic hook for managing saved filters with optional persistence.
+ *
+ * This hook is storage-agnostic — provide a `SavedFiltersStorage` adapter
+ * to connect to any backend, or omit it for in-memory-only operation.
+ *
+ * @example
+ * ```tsx
+ * // In-memory only
+ * const { filters, saveFilter } = useSavedFilters();
+ *
+ * // With localStorage persistence
+ * const { filters, saveFilter } = useSavedFilters({
+ *   storage: {
+ *     load: () => JSON.parse(localStorage.getItem('filters') || '[]'),
+ *     save: (f) => {
+ *       const all = JSON.parse(localStorage.getItem('filters') || '[]');
+ *       all.push(f);
+ *       localStorage.setItem('filters', JSON.stringify(all));
+ *     },
+ *     remove: (name) => {
+ *       const all = JSON.parse(localStorage.getItem('filters') || '[]');
+ *       localStorage.setItem('filters', JSON.stringify(all.filter(f => f.name !== name)));
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function useSavedFilters(options: UseSavedFiltersOptions = {}): SavedFiltersHook {
+  const { storage, initialFilters, userId } = options;
+  const [rawFilters, setRawFilters] = useState<SavedFilter[]>(initialFilters ?? []);
+  const [isLoading, setIsLoading] = useState(!!storage);
+
+  useEffect(() => {
+    if (!storage) return;
+    let cancelled = false;
+
+    const loadFilters = async () => {
+      setIsLoading(true);
+      try {
+        const loaded = await storage.load();
+        if (!cancelled) {
+          setRawFilters(loaded);
+        }
+      } catch (e) {
+        console.error("Failed to load saved filters:", e);
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    };
+
+    loadFilters();
+    return () => {
+      cancelled = true;
+    };
+  }, [storage]);
+
+  const parsedFilters = useMemo<ParsedFilter[]>(() => {
+    if (!rawFilters || rawFilters.length === 0) return [];
+    return rawFilters.map(parseRawFilter).filter((f): f is ParsedFilter => f !== null);
+  }, [rawFilters]);
+
+  const saveFilter = useCallback(
+    async (filterName: string, filterArray: Array<[string, string, unknown]>, isGlobal = false) => {
+      const newFilter: SavedFilter = {
+        name: `filter-${Date.now()}`,
+        filter_name: filterName,
+        for_user: isGlobal ? "" : (userId ?? ""),
+        filters: JSON.stringify(filterArray),
+      };
+
+      if (storage) {
+        await storage.save(newFilter);
+        // Reload from storage to stay in sync
+        const loaded = await storage.load();
+        setRawFilters(loaded);
+      } else {
+        setRawFilters((prev) => [...prev, newFilter]);
+      }
+    },
+    [storage, userId],
+  );
+
+  const deleteFilter = useCallback(
+    async (name: string) => {
+      if (storage) {
+        await storage.remove(name);
+        const loaded = await storage.load();
+        setRawFilters(loaded);
+      } else {
+        setRawFilters((prev) => prev.filter((f) => f.name !== name));
+      }
+    },
+    [storage],
+  );
+
+  const getFilterByName = useCallback(
+    (name: string) => {
+      return parsedFilters.find((f) => f.name === name);
+    },
+    [parsedFilters],
+  );
+
+  return {
+    filters: parsedFilters,
+    isLoading,
+    saveFilter,
+    deleteFilter,
+    getFilterByName,
+  };
+}

package/src/hooks/useTableColumnPinning.ts

@@ -0,0 +1,49 @@
+import type { ColumnPinningState } from "@tanstack/react-table";
+import { useCallback, useState } from "react";
+
+export interface UseTableColumnPinningOptions {
+  initialPinning?: ColumnPinningState;
+}
+
+export interface UseTableColumnPinningReturn {
+  columnPinning: ColumnPinningState;
+  setColumnPinning: React.Dispatch<React.SetStateAction<ColumnPinningState>>;
+  pinColumn: (columnId: string, position: "left" | "right") => void;
+  unpinColumn: (columnId: string) => void;
+}
+
+export function useTableColumnPinning({
+  initialPinning = { left: [], right: [] },
+}: UseTableColumnPinningOptions = {}): UseTableColumnPinningReturn {
+  const [columnPinning, setColumnPinning] = useState<ColumnPinningState>(initialPinning);
+
+  const pinColumn = useCallback((columnId: string, position: "left" | "right") => {
+    setColumnPinning((prev) => {
+      const newState = { ...prev };
+      newState.left = (prev.left || []).filter((id) => id !== columnId);
+      newState.right = (prev.right || []).filter((id) => id !== columnId);
+
+      if (position === "left") {
+        newState.left = [...newState.left, columnId];
+      } else {
+        newState.right = [...newState.right, columnId];
+      }
+
+      return newState;
+    });
+  }, []);
+
+  const unpinColumn = useCallback((columnId: string) => {
+    setColumnPinning((prev) => ({
+      left: (prev.left || []).filter((id) => id !== columnId),
+      right: (prev.right || []).filter((id) => id !== columnId),
+    }));
+  }, []);
+
+  return {
+    columnPinning,
+    setColumnPinning,
+    pinColumn,
+    unpinColumn,
+  };
+}

package/src/hooks/useTableFiltering.ts

@@ -0,0 +1,86 @@
+import type { ColumnFiltersState } from "@tanstack/react-table";
+import { useCallback, useState } from "react";
+import type { TableFilter } from "../types";
+import { generateFilterId } from "../utils/filterUtils";
+
+export interface UseTableFilteringOptions {
+  enableFiltering?: boolean;
+  manualFiltering?: boolean;
+  initialFilters?: TableFilter[];
+  initialColumnFilters?: ColumnFiltersState;
+  initialGlobalFilter?: string;
+}
+
+export interface UseTableFilteringReturn {
+  columnFilters: ColumnFiltersState;
+  setColumnFilters: React.Dispatch<React.SetStateAction<ColumnFiltersState>>;
+  globalFilter: string;
+  setGlobalFilter: (value: string) => void;
+  advancedFilters: TableFilter[];
+  setFilters: React.Dispatch<React.SetStateAction<TableFilter[]>>;
+  addFilter: (filter: Omit<TableFilter, "id">) => void;
+  removeFilter: (filterId: string) => void;
+  clearFilters: () => void;
+  hasActiveFilters: boolean;
+  activeFilterCount: number;
+}
+
+export function useTableFiltering({
+  initialFilters = [],
+  initialColumnFilters = [],
+  initialGlobalFilter = "",
+}: UseTableFilteringOptions = {}): UseTableFilteringReturn {
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>(initialColumnFilters);
+  const [globalFilter, setGlobalFilter] = useState<string>(initialGlobalFilter);
+  const [advancedFilters, setAdvancedFilters] = useState<TableFilter[]>(initialFilters);
+
+  const addFilter = useCallback((filter: Omit<TableFilter, "id">) => {
+    const newFilter: TableFilter = {
+      ...filter,
+      id: generateFilterId(),
+    };
+    setAdvancedFilters((prev) => [...prev, newFilter]);
+
+    if (filter.columnId) {
+      const columnFilter = {
+        id: filter.columnId,
+        value: filter.value,
+      };
+      setColumnFilters((prev) => [...prev, columnFilter]);
+    }
+  }, []);
+
+  const removeFilter = useCallback((filterId: string) => {
+    setAdvancedFilters((prev) => {
+      const filter = prev.find((f) => f.id === filterId);
+      if (filter?.columnId) {
+        setColumnFilters((prevCf) => prevCf.filter((cf) => cf.id !== filter.columnId));
+      }
+      return prev.filter((f) => f.id !== filterId);
+    });
+  }, []);
+
+  const clearFilters = useCallback(() => {
+    setAdvancedFilters([]);
+    setColumnFilters([]);
+    setGlobalFilter("");
+  }, []);
+
+  const hasActiveFilters = advancedFilters.length > 0 || columnFilters.length > 0 || !!globalFilter;
+
+  const activeFilterCount = advancedFilters.length + columnFilters.length + (globalFilter ? 1 : 0);
+
+  return {
+    columnFilters,
+    setColumnFilters,
+    globalFilter,
+    setGlobalFilter,
+    advancedFilters,
+    setFilters: setAdvancedFilters,
+    addFilter,
+    removeFilter,
+    clearFilters,
+    hasActiveFilters,
+    activeFilterCount,
+  };
+}