@react-fabric/data 1.0.0-beta.8 → 1.0.1

package/src/table/context.ts

@@ -0,0 +1,33 @@
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * The MIT License (MIT)
+ * Copyright (c) 2026 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ * and associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+import { createContext, use } from "react";
+
+interface Context {
+  widths: Map<string, number>;
+  startResize: (col: HTMLElement) => void;
+}
+
+export const TableContext = createContext<Context>({} as Context);
+
+export const useTableContext = () => use(TableContext);

package/src/table/types.ts

@@ -21,49 +21,66 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import {
-  type CssProp,
-  type Elements,
-  type IconProps,
-  type RefProp,
-  type TestProps,
-} from "@react-fabric/core/dist/types/types";
+import { type IconProps } from "@react-fabric/core/dist/types/components/icon/Icon";
+import { type CssProp, type NestedKeys, type RefProp, type TestProps } from "@react-fabric/core/dist/types/types";
 import { type ReactElement } from "react";
 
 export const COL_MIN_WIDTH = "3rem";
 export const COL_MAX_WIDTH = "64rem";
 export const COL_DEFAULT_WIDTH = "12rem";
 
-export interface TableColumn<T = KeyValue>
-  extends CssProp,
-    IconProps,
-    TestProps {
-  id: keyof T | string;
+/**
+ * TableColumn interface defines the structure of a column in a table.
+ * It includes properties for column identification, display options, alignment,
+ * visibility, resizing, sorting, filtering, and rendering.
+ *
+ * @template T - The type of data the column will represent, defaulting to KeyValue.
+ * @property {keyof T | string} id - Unique identifier for the column.
+ * @property {"string" | "number" | "boolean" | "datetime" | "date" | "time" | "unknown"} [dataType] - Data type of the column values.
+ * @property {string} [label] - Display label for the column header.
+ * @property {string} [tooltip] - Tooltip text for the column header.
+ * @property {string} [format] - Format string for displaying the column values.
+ * @property {"start" | "center" | "end"} [align] - Text alignment within the column.
+ * @property {"start" | "end"} [locked] - Indicates if the column is locked at the start or end.
+ * @property {boolean} [hidden] - Whether the column is hidden.
+ * @property {boolean} [truncate] - Whether to truncate the text in the column.
+ * @property {boolean} [hideable] - Whether the column can be hidden by the user.
+ * @property {boolean} [resizable] - Whether the column can be resized by the user.
+ * @property {boolean} [sortable] - Whether the column can be sorted.
+ * @property {boolean} [filterable] - Whether the column can be filtered.
+ * @property {AnyObject} [filter] - Filter criteria for the column.
+ * @property {ReactElement[]} [actions] - Array of action elements to be displayed in the column.
+ * @property {AnyObject[]} [filterOptions] - Options for filtering the column.
+ * @property {string | number} [width] - Width of the column.
+ * @property {string | number} [minWidth] - Minimum width of the column.
+ * @property {string | number} [maxWidth] - Maximum width of the column.
+ * @property {KeyValue} [valueMap] - Mapping of values for the column.
+ * @property {(value: AnyObject, data: T, index: number) => Elements<AnyObject>} [renderer] - Custom renderer function for the column values.
+ */
+export interface TableColumn<T = KeyValue> extends CssProp, TestProps {
+  id: NestedKeys<T>;
+  field?: string;
   label?: string;
   tooltip?: string;
-  actions?: ReactElement;
+  icon?: IconProps;
+  actions?: ReactElement[];
   align?: "start" | "center" | "end";
   locked?: "start" | "end";
   hidden?: boolean;
+  truncate?: boolean;
   hideable?: boolean;
   resizable?: boolean;
   sortable?: boolean;
   filterable?: boolean;
-  filterList?: AnyObject[];
+  filter?: string | string[];
+  filterOptions?: Array<string | { id: string; label: string }>;
   width?: string | number;
   minWidth?: string | number;
   maxWidth?: string | number;
-  dataType?:
-    | "string"
-    | "number"
-    | "boolean"
-    | "datetime"
-    | "date"
-    | "time"
-    | "unknown";
+  dataType?: "string" | "number" | "boolean" | "datetime" | "date" | "time" | "unknown";
   format?: string;
-  valueMap?: KeyValue;
-  renderer?: (value: AnyObject, data: T, index: number) => Elements<AnyObject>;
+  valueMap?: KeyValue<string>;
+  renderer?: (value: AnyObject, data: T, index: number) => React.ReactElement<unknown>;
 }
 
 export interface TableRef {
@@ -75,13 +92,17 @@ export interface TableRef {
 export interface TableProps<T = KeyValue> extends RefProp<TableRef> {
   columns: Array<TableColumn<T>>;
   data: T[];
-  keyProperty?: keyof T;
+  keyProperty?: NestedKeys<T>;
+  groupProperty?: NestedKeys<T>;
+  groupRenderer?: (key: AnyObject) => ReactElement;
   emptyDisplay?: ReactElement;
+
   /**
    * checkable rows
    */
+  checked?: AnyObject[];
   checkableRows?: boolean;
-  onCheckedChanged?: (rows: Array<keyof T>) => void;
+  onCheckedChanged?: (rows: AnyObject[]) => void;
   /**
    * sorting
    */
@@ -97,5 +118,10 @@ export interface TableProps<T = KeyValue> extends RefProp<TableRef> {
   onScroll?: (firstItem: number) => void;
 
   canExpand?: (record: T) => boolean;
-  children?: (record: T) => Elements<AnyObject>;
+  children?: (record: T) => React.ReactElement<unknown>;
+
+  onFilter?: (id: NestedKeys<T> | string, value?: AnyObject) => void;
+
+  total?: number;
+  onLoadMore?: (lastIndex?: number) => void;
 }

package/src/table/useResizer.ts

@@ -21,11 +21,7 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-export const useResizer = (
-  colEl: HTMLElement,
-  ghostEl: HTMLElement,
-  callback: (width: number) => void,
-) => {
+export function startResizer(colEl: HTMLElement, ghostEl: HTMLElement, callback: (width: number) => void) {
   const placeholder = ghostEl.firstElementChild as HTMLElement;
   const isRtl = getComputedStyle(colEl).direction === "rtl";
 
@@ -47,13 +43,13 @@ export const useResizer = (
   /** ***************** attach handlers *******************/
   const box = colEl.getBoundingClientRect();
   if (colEl.parentElement != null) {
-    const parentBox = colEl.parentElement?.getBoundingClientRect();
+    const parentBox = colEl.closest("[data-ref='tableScroller']")?.getBoundingClientRect() as unknown as DOMRect;
     if (isRtl) {
       placeholder.style.left = "unset";
-      placeholder.style.right = `${box.right - parentBox.right}px`;
+      placeholder.style.right = `${parentBox.width - box.right}px`;
     } else {
       placeholder.style.right = "unset";
-      placeholder.style.left = `${box.left - parentBox.left}px`;
+      placeholder.style.left = `${box.left}px`;
     }
   }
   placeholder.style.width = `${colEl.offsetWidth}px`;
@@ -63,4 +59,4 @@ export const useResizer = (
 
   document.addEventListener("mousemove", onResize);
   document.addEventListener("mouseup", onResizeEnd);
-};
+}

package/src/table/useTableColumns.ts

@@ -32,11 +32,9 @@ interface ColumnState {
   cols: TableColumn[];
 }
 
-type ColumnActions =
-  | { type: "columns"; columns: TableColumn[] }
-  | { type: "hide"; id: string };
+type ColumnActions = { type: "columns"; columns: TableColumn[] } | { type: "hide"; id: string };
 
-export const useTableColumns = (columns: TableColumn[]) => {
+export function useTableColumns(columns: TableColumn[]) {
   const [state, dispatch] = useReducer(
     (state: ColumnState, action: ColumnActions) => {
       if (action.type === "columns") {
@@ -44,7 +42,7 @@ export const useTableColumns = (columns: TableColumn[]) => {
       }
       if (action.type === "hide") {
         const col = state.columns.find((col) => col.id === action.id);
-        col &&
+        if (col)
           state.columns.splice(state.columns.indexOf(col), 1, {
             ...col,
             hidden: col.hidden !== true,
@@ -82,4 +80,4 @@ export const useTableColumns = (columns: TableColumn[]) => {
     state,
     onHide: (id: string) => dispatch({ type: "hide", id }),
   };
-};
+}

package/src/table/useVirtualTable.ts

@@ -21,93 +21,192 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { useVirtualizer } from "@tanstack/react-virtual";
-import { useCallback, useReducer, useRef } from "react";
+import { compareValues, debounce, groupBy } from "@react-fabric/utilities";
+import { defaultRangeExtractor, type Range, useVirtualizer } from "@tanstack/react-virtual";
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
 
-interface DataState {
+interface DataGroup {
+  __GROUP__: true;
+  key: Key;
+  open: boolean;
+  itemCount: number;
+}
+
+interface DataState<T = KeyValue> {
+  data: T[];
+  items: Array<T | DataGroup>;
+  grouped: KeyValue<T[]>;
+  groups: DataGroup[];
   expanded: Key[];
   checked: Key[];
-  allChecked: 0 | 1 | 2;
+  allChecked: number;
 }
 
-type DataAction =
+type DataAction<T = KeyValue> =
+  | { type: "updateState"; checked: Key[] }
+  | { type: "groupExpand"; key: keyof T }
+  | { type: "reset"; key?: keyof T; data: T[] }
   | { type: "expand"; key: Key }
   | { type: "check"; key: Key }
   | { type: "checkall" };
 
-export const useVirtualTable = (
-  data: KeyValue[],
-  keyProperty?: Key,
-  onCheckChanged?: (checked: Key[]) => void,
-) => {
+export function useVirtualTable<T extends KeyValue = KeyValue>(
+  data: T[],
+  options: {
+    checked?: Key[];
+    keyProperty: keyof T;
+    groupProperty?: keyof T;
+    loading?: boolean;
+    total: number;
+    onLoadMore?: (startIndex: number) => void;
+    onCheckChanged?: (checked: AnyObject[]) => void;
+  },
+) {
   // TODO: refactor data into item list, apply grouping if groupColumn provided
   // TODO: when grouping maintain map of group with children, {___GROUP___:true, label, items, open}
-
-  const scrollerRef = useRef<HTMLDivElement>(null);
-  const virtualizer = useVirtualizer({
-    count: data.length,
-    getScrollElement: () => scrollerRef.current,
-    estimateSize: () => 24,
-  });
-
   const [state, dispatch] = useReducer(
-    (state: DataState, action: DataAction) => {
+    (state: DataState<T>, action: DataAction<T>) => {
+      if (action.type === "updateState") {
+        state.checked = action.checked;
+      }
       if (action.type === "expand") {
-        if (state.expanded.includes(action.key))
-          state.expanded.splice(state.expanded.indexOf(action.key), 1);
+        if (state.expanded.includes(action.key)) state.expanded.splice(state.expanded.indexOf(action.key), 1);
         else state.expanded.push(action.key);
       }
       if (action.type === "check") {
-        if (state.checked.includes(action.key))
-          state.checked.splice(state.checked.indexOf(action.key), 1);
+        if (state.checked.includes(action.key)) state.checked.splice(state.checked.indexOf(action.key), 1);
         else state.checked.push(action.key);
-        onCheckChanged?.(state.checked);
+        options.onCheckChanged?.(state.checked);
       }
       if (action.type === "checkall") {
         if (state.allChecked !== 0) {
           state.checked = [];
-        } else if (keyProperty) {
-          state.checked = data.map((item) => item[keyProperty]);
+        } else if (options.keyProperty) {
+          state.checked = state.data.map((item) => item[options.keyProperty]);
+        }
+        options.onCheckChanged?.(state.checked);
+      }
+      const checkList = state.data.filter((hit) => state.checked.includes(hit[options.keyProperty]));
+      if (action.type === "groupExpand") {
+        const group = state.groups.find((group) => group.key === action.key);
+        if (group) {
+          group.open = !group.open;
+          state.groups = state.groups.slice();
+          state.items = state.groups
+            .map((group) => [group, group.open ? state.grouped[group.key] : undefined])
+            .flat(2)
+            .filter(Boolean) as never;
+        }
+      }
+      if (action.type === "reset") {
+        state.data = action.data;
+        if (action.key) {
+          state.grouped = groupBy<T>(state.data, action.key);
+          state.groups = Object.keys(state.grouped)
+            .sort(compareValues("asc"))
+            .map((group) => ({
+              __GROUP__: true,
+              open: true,
+              key: group,
+              itemCount: state.grouped[group].length,
+            }));
+          state.items = state.groups.map((group) => [group, ...state.grouped[group.key]]).flat();
+        } else {
+          state.items = state.data;
         }
-        onCheckChanged?.(state.checked);
       }
       return {
         ...state,
-        allChecked:
-          state.checked.length === data.length
-            ? 1
-            : state.checked.length
-              ? 2
-              : 0,
-      } as DataState;
+        allChecked: checkList.length === state.data.length ? 1 : state.checked.length ? 2 : 0,
+      };
     },
     {
+      data,
+      items: [],
+      grouped: {},
+      groups: [],
       checked: [],
       expanded: [],
       allChecked: 0,
     },
   );
 
+  const activeStickyIndexRef = useRef(0);
+  const stickyIndexes = useMemo<number[]>(
+    () => state.items.map((hit, idx) => ("__GROUP__" in hit ? idx : undefined)).filter(Boolean) as number[],
+    [state.items],
+  );
+  const isActiveSticky = (index: number) => activeStickyIndexRef.current === index;
+
+  const [hasActiveSticky, setHasActiveSticky] = useState(false);
+  const scrollerRef = useRef<HTMLDivElement>(null);
+  const virtualizer = useVirtualizer({
+    count: state.items.length,
+    getScrollElement: () => scrollerRef.current,
+    estimateSize: () => 32,
+    rangeExtractor: useCallback(
+      (range: Range) => {
+        activeStickyIndexRef.current = [...stickyIndexes].reverse().find((index) => range.startIndex > index) ?? 0;
+
+        setHasActiveSticky(range.startIndex !== activeStickyIndexRef.current);
+
+        const next = new Set([activeStickyIndexRef.current, ...defaultRangeExtractor(range)]);
+
+        return [...next];
+      },
+      [stickyIndexes],
+    ),
+  });
+
   const virtualItems = virtualizer.getVirtualItems();
 
   const getData = useCallback(
     (index: number) => {
-      return data[index];
+      return state.items[index];
     },
-    [data],
+    [state.items],
   );
 
+  useEffect(() => {
+    dispatch({ type: "reset", key: options.groupProperty, data });
+  }, [data, options.groupProperty]);
+
+  useEffect(() => {
+    dispatch({ type: "updateState", checked: options.checked ?? [] });
+  }, [options.checked]);
+
+  useEffect(() => {
+    if (options.onLoadMore) {
+      const firstItem = virtualItems[0]?.index;
+      const lastItem = virtualItems?.slice(-1).pop()?.index;
+      const canLoadPrevPage = firstItem !== undefined && state.items[firstItem] === null;
+      const canLoadNextPage =
+        lastItem !== undefined && lastItem === state.items.length - 1 && state.items.length < options.total;
+      const db = debounce(options.onLoadMore);
+      if (canLoadPrevPage) {
+        db(firstItem);
+      } else if (!options.loading && canLoadNextPage) {
+        db(lastItem + 1);
+      }
+      return () => db.cancel();
+    }
+    // eslint-disable-next-line @eslint-react/exhaustive-deps
+  }, [options.onLoadMore, virtualItems]);
+
   return {
     scrollerRef,
     items: virtualItems,
     checkState: state,
     getData,
     virtualizer,
+    hasActiveSticky,
+    isActiveSticky,
     top: virtualizer.range?.startIndex,
     totalSize: virtualizer.getTotalSize,
     measureElement: virtualizer.measureElement,
+    toggleGroupExpand: (key: Key) => dispatch({ type: "groupExpand", key }),
     toggleExpand: (key: Key) => dispatch({ type: "expand", key }),
     toggleChecked: (key: Key) => dispatch({ type: "check", key }),
     toggleAllChecked: () => dispatch({ type: "checkall" }),
   };
-};
+}