@react-fabric/data 1.0.0-beta.5 → 1.0.0-beta.52

package/src/table/Table.tsx

@@ -21,12 +21,25 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { EmptyContent, Loading, useDebounce } from "@react-fabric/core";
+import {
+  CoreIcons,
+  EmptyContent,
+  Icon,
+  Loading,
+  useDebounce,
+} from "@react-fabric/core";
+import { debounce } from "@react-fabric/utilities";
 import classNames from "classnames";
-import { useImperativeHandle, useMemo, useRef } from "react";
+import {
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from "react";
 import { useTranslation } from "react-i18next";
 import { AddColumn } from "./AddColumn";
-import { BodyCell } from "./BodyCell";
+import { BodyRow } from "./BodyRow";
 import { CheckboxCell } from "./CheckboxCell";
 import { TableProvider } from "./Context";
 import { EmptyCell } from "./EmptyCell";
@@ -35,16 +48,38 @@ import { type TableProps } from "./types";
 import { useTableColumns } from "./useTableColumns";
 import { useVirtualTable } from "./useVirtualTable";
 
+/**
+ * Table component for displaying data in a tabular format with features like sorting, filtering, and virtual scrolling.
+ * It supports expandable rows, checkable rows, and customizable columns.
+ * The component is designed to handle large datasets efficiently by rendering only the visible rows.
+ * It also provides a way to manage column visibility and allows for custom rendering of group headers.
+ * Uses TanStack's `useVirtual` for virtualization and React's `useMemo` for performance optimization.
+ *
+ * @param {TableProps<T>} props - The properties for the Table component.
+ * @returns {JSX.Element} The rendered Table component.
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/data-table--table}
+ * @see {@link https://tanstack.com/table/v8/docs/api/virtual}
+ */
 export const Table = <T extends KeyValue = KeyValue>({
   ref,
   data,
   columns,
-  keyProperty,
+  keyProperty = "id",
+  groupProperty,
   checkableRows,
+  initialScroll,
   hideableColumns,
   sort,
   loading,
+  checked,
+  emptyDisplay,
+  groupRenderer,
+  canExpand,
+  children,
   onSort,
+  onFilter,
+  onScroll,
   onRowClick,
   onCheckedChanged,
 }: TableProps<T>) => {
@@ -58,13 +93,24 @@ export const Table = <T extends KeyValue = KeyValue>({
   const {
     scrollerRef,
     items,
+    top,
     checkState,
+    virtualizer,
+    hasActiveSticky,
+    toggleExpand,
     toggleChecked,
     toggleAllChecked,
+    toggleGroupExpand,
     getData,
     totalSize,
+    isActiveSticky,
     measureElement,
-  } = useVirtualTable(data, keyProperty, fireCheckChanged);
+  } = useVirtualTable(data, {
+    checked,
+    keyProperty,
+    groupProperty,
+    onCheckChanged: fireCheckChanged,
+  });
   const refBody = useRef<HTMLDivElement>(null);
 
   const wrapperStart = useMemo(
@@ -76,32 +122,51 @@ export const Table = <T extends KeyValue = KeyValue>({
     [],
   );
 
+  useLayoutEffect(() => {
+    setTimeout(() => {
+      initialScroll &&
+        virtualizer.scrollToIndex(initialScroll, { align: "start" });
+    }, 100);
+  }, []);
+
   useImperativeHandle(
     ref,
     () => ({
-      hilight: (row: number) => {
-        refBody.current
-          ?.querySelectorAll<HTMLElement>(`.datatable-row[data-hilight="true"]`)
-          .forEach((el) => el && (el.dataset.hilight = undefined));
-        const el = refBody.current?.querySelector<HTMLElement>(
-          `[data-row="${row}"]`,
-        );
-        el?.scrollIntoView({ behavior: "smooth", block: "center" });
-        el && (el.dataset.hilight = "true");
+      scrollTo: (row: number) => {
+        virtualizer.scrollToIndex(row, { align: "start" });
       },
-      unhilight: () => {
-        refBody.current
-          ?.querySelectorAll<HTMLElement>(`.datatable-row[data-hilight="true"]`)
-          .forEach((el) => el && (el.dataset.hilight = undefined));
+      hilight(row) {
+        scrollerRef.current
+          ?.querySelector(".hilight")
+          ?.classList.remove("hilight", "ring-1");
+        virtualizer.scrollToIndex(Math.floor(row), {
+          align: "start",
+        });
+        setTimeout(() => {
+          scrollerRef.current
+            ?.querySelector(`[data-index="${row}"]`)
+            ?.classList.add("hilight", "ring-1");
+        }, 100);
       },
-      scrollTo: (row: number) => {
-        const el = refBody.current?.querySelector(`[data-row="${row}"]`);
-        el?.scrollIntoView({ behavior: "smooth" });
+      unhilight() {
+        scrollerRef.current
+          ?.querySelector(".hilight")
+          ?.classList.remove("hilight", "ring-1");
       },
     }),
     [],
   );
 
+  useEffect(() => {
+    const handle = debounce((top: number) => {
+      onScroll?.(top ?? 0);
+    });
+    handle(top);
+    return () => {
+      handle.cancel();
+    };
+  }, [top]);
+
   return (
     <TableProvider>
       <div
@@ -109,10 +174,15 @@ export const Table = <T extends KeyValue = KeyValue>({
         style={{
           gridTemplate: `"head" auto "loader" auto "content" 1fr "foot" auto/1fr`,
         }}
+        data-ref="tableScroller"
         ref={scrollerRef}
       >
-        <div className="bg-base font-medium sticky top-0 area-head border-b select-none flex flex-nowrap z-2">
+        <div
+          data-ref="tableHeader"
+          className="bg-base font-medium sticky top-0 h-8 area-head border-b select-none flex flex-nowrap z-2"
+        >
           <div className={wrapperStart}>
+            {canExpand && <div className="w-6" />}
             {checkableRows && (
               <CheckboxCell
                 state={checkState.allChecked}
@@ -120,15 +190,33 @@ export const Table = <T extends KeyValue = KeyValue>({
               />
             )}
             {state.start?.map((col, idx) => (
-              <HeaderCell key={idx} {...col} sort={sort} onSort={onSort} />
+              <HeaderCell
+                key={idx}
+                {...col}
+                sort={sort}
+                onSort={onSort}
+                onFilter={onFilter}
+              />
             ))}
           </div>
           {state.cols?.map((col, idx) => (
-            <HeaderCell key={idx} {...col} sort={sort} onSort={onSort} />
+            <HeaderCell
+              key={idx}
+              {...col}
+              sort={sort}
+              onSort={onSort}
+              onFilter={onFilter}
+            />
           ))}
           <div className={wrapperEnd}>
             {state.end?.map((col, idx) => (
-              <HeaderCell key={idx} {...col} sort={sort} onSort={onSort} />
+              <HeaderCell
+                key={idx}
+                {...col}
+                sort={sort}
+                onSort={onSort}
+                onFilter={onFilter}
+              />
             ))}
 
             {hideableColumns && (
@@ -142,66 +230,76 @@ export const Table = <T extends KeyValue = KeyValue>({
         {loading && <Loading />}
         {data.length > 0 && (
           <div
-            className="area-content flex flex-col flex-nowrap"
+            className="area-content flex flex-col flex-nowrap min-h-full"
             style={{ height: totalSize() }}
             ref={refBody}
           >
-            <div style={{ height: items[0]?.start }} />
+            <div
+              style={{
+                height: items[hasActiveSticky ? 1 : 0]?.start,
+              }}
+            />
             {items.map(({ index, key }) => {
               const data = getData(index);
-              return (
+              return "__GROUP__" in data ? (
                 <div
                   key={key}
-                  role="none"
-                  data-row={index}
+                  ref={measureElement}
+                  data-index={index}
                   className={classNames(
-                    "flex flex-nowrap datatable-row data-[hilight]:outline-1 -outline-offset-1 outline-primary-500",
-                    index % 2 ? "bg-even" : "bg-odd",
-                    onRowClick && "hover:bg-primary-50 active:bg-primary-100",
+                    "px-2 py-1 text-md bg-base border-y border-tint-100 cursor-pointer flex items-center gap-1 z-1",
+                    isActiveSticky(index) && "sticky top-8",
                   )}
-                  onClick={() =>
-                    checkableRows && keyProperty && !onRowClick
-                      ? toggleChecked(data[keyProperty])
-                      : onRowClick?.(data)
-                  }
-                  data-index={index}
-                  ref={measureElement}
+                  role="none"
+                  onClick={() => toggleGroupExpand(data.key)}
                 >
-                  <div className={wrapperStart}>
-                    {checkableRows && keyProperty && (
-                      <CheckboxCell
-                        onClick={() => toggleChecked(data[keyProperty])}
-                        state={
-                          checkState.checked.includes(data[keyProperty]) ? 1 : 0
-                        }
-                      />
-                    )}
-                    {state.start?.map((col, ids) => (
-                      <BodyCell
-                        key={`${key}:${ids}`}
-                        column={col}
-                        item={data}
-                      />
-                    ))}
-                  </div>
-                  {state.cols?.map((col, idc) => (
-                    <BodyCell key={`${key}:${idc}`} column={col} item={data} />
-                  ))}
-                  <div className={wrapperEnd}>
-                    {state.end?.map((col, ide) => (
-                      <BodyCell
-                        key={`${key}:${ide}`}
-                        column={col}
-                        item={data}
-                      />
-                    ))}
-                    {hideableColumns && <div className="w-6" />}
-                  </div>
+                  <Icon
+                    rtlFlip
+                    icon={
+                      data.open ? CoreIcons.chevronDown : CoreIcons.chevronRight
+                    }
+                  />
+                  {groupRenderer?.(data) ?? (
+                    <div className="flex gap-1 items-center">
+                      <span>{data.key}</span>
+                      <span className="text-sm">({data.itemCount})</span>
+                    </div>
+                  )}
                 </div>
+              ) : (
+                <BodyRow
+                  rowKey={key.toString()}
+                  index={index}
+                  checkableRows={checkableRows}
+                  checked={
+                    keyProperty &&
+                    checkState.checked.includes(data[keyProperty])
+                      ? 1
+                      : 0
+                  }
+                  expanded={
+                    !!keyProperty &&
+                    checkState.expanded.includes(data[keyProperty])
+                  }
+                  data={data}
+                  hideableColumns={hideableColumns}
+                  keyProperty={keyProperty}
+                  measureElement={measureElement}
+                  onRowClick={onRowClick}
+                  state={state}
+                  canExpand={canExpand}
+                  toggleExpand={toggleExpand}
+                  expandRow={children}
+                  toggleChecked={toggleChecked}
+                  wrapperEnd={wrapperEnd}
+                  wrapperStart={wrapperStart}
+                  key={key}
+                />
               );
             })}
             <div className="flex-1 flex flex-nowrap">
               <div className={wrapperStart}>
+                {canExpand && <div className="w-6" />}
                 {checkableRows && <div className="w-6" />}
                 {state.start?.map((col) => (
                   <EmptyCell key={String(col.id)} {...col} />
@@ -220,13 +318,15 @@ export const Table = <T extends KeyValue = KeyValue>({
             </div>
           </div>
         )}
-        {!loading && data.length === 0 && (
-          <EmptyContent
-            size="sm"
-            className="bg-dimmed"
-            message={t("datagrid.empty")}
-          />
-        )}
+        {!loading &&
+          data.length === 0 &&
+          (emptyDisplay ?? (
+            <EmptyContent
+              size="sm"
+              className="bg-dimmed"
+              message={t("datagrid.empty")}
+            />
+          ))}
       </div>
     </TableProvider>
   );

package/src/table/types.ts

@@ -23,6 +23,7 @@
 
 import {
   type CssProp,
+  type Elements,
   type IconProps,
   type RefProp,
   type TestProps,
@@ -33,21 +34,52 @@ export const COL_MIN_WIDTH = "3rem";
 export const COL_MAX_WIDTH = "64rem";
 export const COL_DEFAULT_WIDTH = "12rem";
 
-export interface ColumnType<T = KeyValue>
+/**
+ * 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,
     IconProps,
     TestProps {
   id: keyof T | string;
   label?: string;
-  actions?: ReactElement;
+  tooltip?: string;
+  actions?: ReactElement[];
   align?: "start" | "center" | "end";
   locked?: "start" | "end";
   hidden?: boolean;
+  truncate?: boolean;
   hideable?: boolean;
   resizable?: boolean;
   sortable?: boolean;
   filterable?: boolean;
-  filterList?: AnyObject[];
+  filter?: AnyObject;
+  filterOptions?: AnyObject[];
   width?: string | number;
   minWidth?: string | number;
   maxWidth?: string | number;
@@ -60,7 +92,8 @@ export interface ColumnType<T = KeyValue>
     | "time"
     | "unknown";
   format?: string;
-  renderer?: (value: AnyObject, data: T) => void;
+  valueMap?: KeyValue;
+  renderer?: (value: AnyObject, data: T, index: number) => Elements<AnyObject>;
 }
 
 export interface TableRef {
@@ -70,14 +103,19 @@ export interface TableRef {
 }
 
 export interface TableProps<T = KeyValue> extends RefProp<TableRef> {
-  columns: Array<ColumnType<T>>;
+  columns: Array<TableColumn<T>>;
   data: T[];
   keyProperty?: keyof T;
+  groupProperty?: keyof T;
+  groupRenderer?: (key: AnyObject) => ReactElement;
+  emptyDisplay?: ReactElement;
+
   /**
    * checkable rows
    */
+  checked?: AnyObject[];
   checkableRows?: boolean;
-  onCheckedChanged?: (rows: Array<keyof T>) => void;
+  onCheckedChanged?: (rows: AnyObject[]) => void;
   /**
    * sorting
    */
@@ -88,4 +126,12 @@ export interface TableProps<T = KeyValue> extends RefProp<TableRef> {
   hideableColumns?: boolean;
 
   onRowClick?: (data: T) => void;
+
+  initialScroll?: number;
+  onScroll?: (firstItem: number) => void;
+
+  canExpand?: (record: T) => boolean;
+  children?: (record: T) => Elements<AnyObject>;
+
+  onFilter?: (id: keyof T | string, value?: AnyObject) => void;
 }

package/src/table/useResizer.ts

@@ -47,13 +47,15 @@ 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`;

package/src/table/useTableColumns.ts

@@ -23,20 +23,20 @@
 
 import { groupBy } from "@react-fabric/utilities";
 import { useEffect, useReducer } from "react";
-import { type ColumnType } from "./types";
+import { type TableColumn } from "./types";
 
 interface ColumnState {
-  columns: ColumnType[];
-  start: ColumnType[];
-  end: ColumnType[];
-  cols: ColumnType[];
+  columns: TableColumn[];
+  start: TableColumn[];
+  end: TableColumn[];
+  cols: TableColumn[];
 }
 
 type ColumnActions =
-  | { type: "columns"; columns: ColumnType[] }
+  | { type: "columns"; columns: TableColumn[] }
   | { type: "hide"; id: string };
 
-export const useTableColumns = (columns: ColumnType[]) => {
+export const useTableColumns = (columns: TableColumn[]) => {
   const [state, dispatch] = useReducer(
     (state: ColumnState, action: ColumnActions) => {
       if (action.type === "columns") {