@multiplatform.one/table 6.1.0 → 6.4.0

package/src/hooks/useInfiniteRows.ts

@@ -0,0 +1,242 @@
+/**
+ * useInfiniteRows - accumulation + prefetch engine for DataTable's
+ * `paginationMode="infinite"`.
+ *
+ * Two data shapes, one contract:
+ *
+ * - Client mode (no `loadPage`): all rows are already in memory; the hook
+ *   only tracks how many page-chunks are revealed (`loadedPages`). "Prefetch"
+ *   is trivial — appending is a synchronous slice.
+ * - Loader mode (`loadPage` provided): the hook owns a small page cache
+ *   keyed by page index. Page N+1 is pre-loaded in the background as soon
+ *   as page N is appended (including page 0 on initial load), so the append
+ *   at the scroll tail resolves instantly from cache.
+ *
+ * Reset semantics: any change to sorting / filters / column filters /
+ * global search / page size invalidates the cache and restarts from page 0
+ * (a generation counter drops stale in-flight responses).
+ *
+ * Framework-agnostic by design: `loadPage` is a plain async callback, so
+ * adapters (e.g. FrappeTable in @multiplatform.one/frappe-ui) supply their
+ * own fetching without this package knowing about them.
+ */
+
+import type { ColumnFiltersState } from "@tanstack/react-table";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { DataTablePageLoader, PageLoadResult, TableFilter, TableSorting } from "../types";
+
+export interface UseInfiniteRowsOptions<TData = any> {
+  /** paginationMode === "infinite" */
+  enabled: boolean;
+  /** Async page loader; when omitted, client mode (in-memory slicing) is used */
+  loadPage?: DataTablePageLoader<TData>;
+  pageSize: number;
+  sorting: TableSorting[];
+  filters: TableFilter[];
+  columnFilters: ColumnFiltersState;
+  globalFilter?: string;
+}
+
+export interface UseInfiniteRowsReturn<TData = any> {
+  /** True when infinite mode drives the loader path (loadPage provided) */
+  isLoaderMode: boolean;
+  /** Accumulated rows from the loader (loader mode only; [] otherwise) */
+  rows: TData[];
+  /** Number of revealed page-chunks (client mode; loader mode mirrors pages loaded) */
+  loadedPages: number;
+  /** Total row count reported by the loader, when known */
+  totalCount?: number;
+  /** Loader mode: no further pages exist */
+  exhausted: boolean;
+  /** Loader mode: page 0 for the current query is still loading */
+  isInitialLoading: boolean;
+  /** Loader mode: a page append is awaiting the loader (cache miss) */
+  isAppending: boolean;
+  /** Append the next page (loader mode) */
+  loadMore: () => void;
+  /** Reveal the next chunk (client mode); maxRowCount clamps exhaustion */
+  loadMoreClient: (maxRowCount: number) => void;
+}
+
+function isLastPage(result: PageLoadResult, pagesLoaded: number, pageSize: number): boolean {
+  if (result.rows.length < pageSize) return true;
+  if (result.totalCount != null && pagesLoaded * pageSize >= result.totalCount) return true;
+  return false;
+}
+
+export function useInfiniteRows<TData = any>({
+  enabled,
+  loadPage,
+  pageSize,
+  sorting,
+  filters,
+  columnFilters,
+  globalFilter,
+}: UseInfiniteRowsOptions<TData>): UseInfiniteRowsReturn<TData> {
+  const isLoaderMode = enabled && loadPage != null;
+
+  // Latest loader without retriggering resets when an inline callback changes identity.
+  const loadPageRef = useRef(loadPage);
+  loadPageRef.current = loadPage;
+
+  // Any query-state change resets accumulation back to page one.
+  const queryKey = useMemo(
+    () => JSON.stringify({ sorting, filters, columnFilters, globalFilter, pageSize }),
+    [sorting, filters, columnFilters, globalFilter, pageSize],
+  );
+  const queryRef = useRef({ sorting, filters, columnFilters, globalFilter, pageSize });
+  queryRef.current = { sorting, filters, columnFilters, globalFilter, pageSize };
+
+  // ---- Client mode ----
+  const [clientPages, setClientPages] = useState(1);
+
+  const loadMoreClient = useCallback(
+    (maxRowCount: number) => {
+      if (!enabled) return;
+      setClientPages((prev) => (prev * pageSize >= maxRowCount ? prev : prev + 1));
+    },
+    [enabled, pageSize],
+  );
+
+  // ---- Loader mode ----
+  const [pages, setPages] = useState<TData[][]>([]);
+  const [totalCount, setTotalCount] = useState<number | undefined>(undefined);
+  const [exhausted, setExhausted] = useState(false);
+  const [isInitialLoading, setIsInitialLoading] = useState(false);
+  const [isAppending, setIsAppending] = useState(false);
+
+  const generationRef = useRef(0);
+  const cacheRef = useRef<Map<number, Promise<PageLoadResult<TData>>>>(new Map());
+  /** Pages whose promise already resolved — appended synchronously (no tail skeleton). */
+  const resolvedRef = useRef<Map<number, PageLoadResult<TData>>>(new Map());
+  const appendPendingRef = useRef(false);
+
+  const ensurePage = useCallback((pageIndex: number): Promise<PageLoadResult<TData>> => {
+    const cached = cacheRef.current.get(pageIndex);
+    if (cached) return cached;
+    const loader = loadPageRef.current;
+    if (!loader) return Promise.resolve({ rows: [] });
+    const q = queryRef.current;
+    const generation = generationRef.current;
+    const promise = loader({
+      pageIndex,
+      pageSize: q.pageSize,
+      sorting: q.sorting,
+      filters: q.filters,
+      columnFilters: q.columnFilters,
+      globalFilter: q.globalFilter,
+    });
+    cacheRef.current.set(pageIndex, promise);
+    promise.then(
+      (result) => {
+        if (generation !== generationRef.current) return;
+        resolvedRef.current.set(pageIndex, result);
+      },
+      // Failed loads are evicted so the next loadMore retries instead of
+      // permanently caching the rejection.
+      () => {
+        if (cacheRef.current.get(pageIndex) === promise) {
+          cacheRef.current.delete(pageIndex);
+        }
+      },
+    );
+    return promise;
+  }, []);
+
+  // Reset + initial load (page 0) + prefetch page 1 as soon as page 0 lands.
+  useEffect(() => {
+    setClientPages(1);
+    if (!enabled || !loadPageRef.current) return;
+    const generation = ++generationRef.current;
+    cacheRef.current = new Map();
+    resolvedRef.current = new Map();
+    appendPendingRef.current = false;
+    setPages([]);
+    setTotalCount(undefined);
+    setExhausted(false);
+    setIsAppending(false);
+    setIsInitialLoading(true);
+    ensurePage(0)
+      .then((result) => {
+        if (generation !== generationRef.current) return;
+        setPages([result.rows]);
+        if (result.totalCount != null) setTotalCount(result.totalCount);
+        const done = isLastPage(result, 1, queryRef.current.pageSize);
+        setExhausted(done);
+        setIsInitialLoading(false);
+        // Prefetch-ahead: page 1 starts loading while the user views page 0.
+        if (!done) void ensurePage(1);
+      })
+      .catch(() => {
+        if (generation !== generationRef.current) return;
+        setIsInitialLoading(false);
+      });
+  }, [enabled, isLoaderMode, queryKey, ensurePage]);
+
+  const rows = useMemo(() => pages.flat(), [pages]);
+  const rowsLoadedRef = useRef(0);
+  rowsLoadedRef.current = rows.length;
+  const pagesLoadedRef = useRef(0);
+  pagesLoadedRef.current = pages.length;
+  const exhaustedRef = useRef(false);
+  exhaustedRef.current = exhausted;
+  const initialLoadingRef = useRef(false);
+  initialLoadingRef.current = isInitialLoading;
+
+  const loadMore = useCallback(() => {
+    if (!enabled || !loadPageRef.current) return;
+    if (exhaustedRef.current || initialLoadingRef.current || appendPendingRef.current) return;
+    const generation = generationRef.current;
+    const nextPage = pagesLoadedRef.current;
+    appendPendingRef.current = true;
+
+    const appendResult = (result: PageLoadResult<TData>) => {
+      appendPendingRef.current = false;
+      setIsAppending(false);
+      setPages((prev) => {
+        if (prev.length !== nextPage) return prev;
+        return [...prev, result.rows];
+      });
+      if (result.totalCount != null) setTotalCount(result.totalCount);
+      const done = isLastPage(result, nextPage + 1, queryRef.current.pageSize);
+      if (done) {
+        setExhausted(true);
+      } else {
+        // Keep one page ahead of the viewport.
+        void ensurePage(nextPage + 1);
+      }
+    };
+
+    // Prefetched and resolved — append synchronously, no tail skeleton.
+    const resolved = resolvedRef.current.get(nextPage);
+    if (resolved) {
+      appendResult(resolved);
+      return;
+    }
+
+    // Cache miss or prefetch still in flight — honest loading affordance.
+    setIsAppending(true);
+    ensurePage(nextPage)
+      .then((result) => {
+        if (generation !== generationRef.current) return;
+        appendResult(result);
+      })
+      .catch(() => {
+        if (generation !== generationRef.current) return;
+        appendPendingRef.current = false;
+        setIsAppending(false);
+      });
+  }, [enabled, ensurePage]);
+
+  return {
+    isLoaderMode,
+    rows,
+    loadedPages: isLoaderMode ? pages.length : clientPages,
+    totalCount,
+    exhausted,
+    isInitialLoading,
+    isAppending,
+    loadMore,
+    loadMoreClient,
+  };
+}

package/src/hooks/useTableFiltering.ts

@@ -18,7 +18,10 @@ export interface UseTableFilteringReturn {
   setGlobalFilter: (value: string) => void;
   advancedFilters: TableFilter[];
   setFilters: React.Dispatch<React.SetStateAction<TableFilter[]>>;
-  addFilter: (filter: Omit<TableFilter, "id">) => void;
+  /** Adds an advanced filter and returns its generated id. */
+  addFilter: (filter: Omit<TableFilter, "id">) => string;
+  /** Updates an existing advanced filter in place (live commit, LC-21). */
+  updateFilter: (filterId: string, updates: Partial<Omit<TableFilter, "id">>) => void;
   removeFilter: (filterId: string) => void;
   clearFilters: () => void;
   hasActiveFilters: boolean;
@@ -34,30 +37,27 @@ export function useTableFiltering({
   const [globalFilter, setGlobalFilter] = useState<string>(initialGlobalFilter);
   const [advancedFilters, setAdvancedFilters] = useState<TableFilter[]>(initialFilters);
 
+  // Advanced filters are their own pipeline (applied via applyFiltersToData
+  // client-side, or mapped to server params under manualFiltering). They are
+  // deliberately NOT mirrored into TanStack columnFilters — mirroring double-
+  // applied them and broke on fields with no matching column.
   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 id = generateFilterId();
+    setAdvancedFilters((prev) => [...prev, { ...filter, id }]);
+    return id;
   }, []);
 
+  const updateFilter = useCallback(
+    (filterId: string, updates: Partial<Omit<TableFilter, "id">>) => {
+      setAdvancedFilters((prev) =>
+        prev.map((f) => (f.id === filterId ? { ...f, ...updates, id: f.id } : f)),
+      );
+    },
+    [],
+  );
+
   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);
-    });
+    setAdvancedFilters((prev) => prev.filter((f) => f.id !== filterId));
   }, []);
 
   const clearFilters = useCallback(() => {
@@ -78,6 +78,7 @@ export function useTableFiltering({
     advancedFilters,
     setFilters: setAdvancedFilters,
     addFilter,
+    updateFilter,
     removeFilter,
     clearFilters,
     hasActiveFilters,

package/src/hooks/useTablePagination.ts

@@ -1,7 +1,6 @@
 import type { PaginationState } from "@tanstack/react-table";
 import { useState } from "react";
-
-const defaultPageSize = 10;
+import { DEFAULT_PAGE_SIZE } from "../utils/paginationDefaults";
 
 export interface UseTablePaginationOptions {
   enablePagination?: boolean;
@@ -28,7 +27,7 @@ export function useTablePagination({
   const [pagination, setPagination] = useState<PaginationState>(
     initialPagination || {
       pageIndex: 0,
-      pageSize: defaultPageSize,
+      pageSize: DEFAULT_PAGE_SIZE,
     },
   );
 

package/src/index.ts

@@ -16,6 +16,8 @@ export { useTableFiltering } from "./hooks/useTableFiltering";
 export type { UseTableFilteringOptions, UseTableFilteringReturn } from "./hooks/useTableFiltering";
 export { useTableSorting } from "./hooks/useTableSorting";
 export type { UseTableSortingOptions, UseTableSortingReturn } from "./hooks/useTableSorting";
+export { useInfiniteRows } from "./hooks/useInfiniteRows";
+export type { UseInfiniteRowsOptions, UseInfiniteRowsReturn } from "./hooks/useInfiniteRows";
 export { useTablePagination } from "./hooks/useTablePagination";
 export type {
   UseTablePaginationOptions,
@@ -48,7 +50,11 @@ export {
   DataTableStateContext,
   useDataTableState,
 } from "./components/DataTable/DataTableStateContext";
-export type { DataTableStateContextValue } from "./components/DataTable/DataTableStateContext";
+export type {
+  DataTableFilterUi,
+  DataTableStateContextValue,
+  FilterEditTarget,
+} from "./components/DataTable/DataTableStateContext";
 export type { DataTableRootProps } from "./components/DataTable/DataTableRoot";
 
 // Export components - SimpleTable (lightweight, zero TanStack Table dependency)
@@ -58,9 +64,16 @@ export type { SimpleTableProps, SimpleTableColumn } from "./components/SimpleTab
 // Export sub-components (for standalone usage)
 export { DataTableToolbar } from "./components/DataTableToolbar";
 export { DataTableFilters } from "./components/DataTableFilters";
+export { DataTableFilterButton } from "./components/DataTableFilterButton";
+export { DataTableFilterChips } from "./components/DataTableFilterChips";
+export {
+  FilterOperatorValueEditor,
+  type FilterOperatorValueEditorProps,
+} from "./components/FilterOperatorValueEditor";
 export { DataTablePagination } from "./components/DataTablePagination";
 export { DataTableViewOptions } from "./components/DataTableViewOptions";
 export { DataTableBulkActions } from "./components/DataTableBulkActions";
+export type { BulkAction, SelectAllScope } from "./types";
 export { DataTableExport, type ExportOptions } from "./components/DataTableExport";
 export {
   DataTableSearch,
@@ -124,7 +137,30 @@ export {
 
 // Export utilities
 export * from "./utils/filterUtils";
+export {
+  applyFiltersToData,
+  defaultOperatorForFilterType,
+  filterOperatorLabel,
+  getFilterChipLabel,
+  getFilterFieldType,
+  isFilterValueShape,
+  mapFieldToFilterType,
+  operatorNeedsNoValue,
+  operatorsForFilterType,
+  resolveFilterFields,
+} from "./utils/filterFields";
 export * from "./utils/urlStateUtils";
+export {
+  getDefaultColumnAlign,
+  alignToFlex,
+  type ColumnAlign,
+  type ColumnAlignInput,
+} from "./utils/columnAlign";
+export {
+  DEFAULT_PAGE_SIZE,
+  DEFAULT_PAGE_SIZE_OPTIONS,
+  type DefaultPageSizeOption,
+} from "./utils/paginationDefaults";
 
 // Re-export TanStack Table types for convenience
 export type {

package/src/shared/t.ts

@@ -0,0 +1,24 @@
+import i18n from "i18next";
+
+type TOptions = Record<string, unknown>;
+
+function interpolate(template: string, options?: TOptions): string {
+  if (!options) return template;
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) =>
+    options[key] != null ? String(options[key]) : `{{${key}}}`,
+  );
+}
+
+/**
+ * Safe catalog lookup for non-component paths (render callbacks, chrome
+ * labels). When i18n is not initialized (unit tests / headless DS), returns
+ * the English key with light `{{var}}` interpolation so callers never get
+ * `undefined`. Same contract as `forms/src/shared/t.ts`.
+ */
+export function t(key: string, options?: TOptions): string {
+  if (i18n?.isInitialized) {
+    const translated: unknown = i18n.t(key, options as never);
+    if (typeof translated === "string" && translated.length > 0) return translated;
+  }
+  return interpolate(key, options);
+}