Strongly Typed Filters and Sorting Rule (#62)

Co-authored-by: Tobias Merki <103021062+neotob@users.noreply.github.com>

Author: manni497

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- the `reset icon` will now reset the table to the initialState if provided, otherwise to the first value of the state
+- :boom: the `sorting` accepts now a strongly typed object instead of a list
+- :boom: the `columnFilters` can be used only defining a `filter type` to datatable hooks
+
+### Removed
+
+- :boom: utilities `getColumnFilterFromModel` and `getModelFromColumnFilter` are not exposed anymore
+
 ## [4.2.0] - 2024-03-22
 
 ### Added

src/index.ts

@@ -5,5 +5,3 @@ export * from "./lib/ReactDataTable/ReactDataTable";
 export * from "./lib/utils/getStronglyTypedColumnFilter";
 export * from "./lib/useFullyControlledReactDataTable/useFullyControlledReactDataTable";
 export * from "./lib/utils/createReactDataTableColumnHelper";
-export * from "./lib/utils/getModelFromColumnFilter";
-export * from "./lib/utils/getColumnFilterFromModel";

src/lib/ReactDataTable/ReactDataTable.tsx

@@ -6,6 +6,8 @@ import { Table, flexRender } from "@tanstack/react-table";
 import { Table as ReactStrapTable, Input } from "reactstrap";
 import { reactDataTableTranslations } from "../translations/translations";
 import { ReactDataTableProps } from "./ReactDataTableProps";
+import { FilterModel } from "../types/TableState";
+import { getModelFromColumnFilter } from "../utils/getModelFromColumnFilter";
 import { CSSProperties, Fragment } from "react";
 import { DndContext, KeyboardSensor, MouseSensor, TouchSensor, closestCenter, useSensor, useSensors } from "@dnd-kit/core";
 import { restrictToVerticalAxis } from "@dnd-kit/modifiers";
@@ -18,11 +20,11 @@ interface TableBodyProps<TData> {
   rowStyle?: (row: TData) => CSSProperties;
 }
 
-/**
+/**b
  * The table renderer for the react data table
  * @param props according to {@link ReactDataTableProps}
  */
-const ReactDataTable = <TData,>(props: ReactDataTableProps<TData>) => {
+const ReactDataTable = <TData, TFilter extends FilterModel = Record<string, never>>(props: ReactDataTableProps<TData, TFilter>) => {
   const {
     isLoading,
     isFetching,
@@ -147,7 +149,7 @@ const ReactDataTable = <TData,>(props: ReactDataTableProps<TData>) => {
                                   <FontAwesomeIcon
                                     style={{ cursor: "pointer", marginBottom: "4px", marginRight: "5px" }}
                                     icon={faSearch}
-                                    onClick={() => onEnter(table.getState().columnFilters)}
+                                    onClick={() => onEnter(getModelFromColumnFilter(table.getState().columnFilters))}
                                   />
                                 )}
 
@@ -156,15 +158,14 @@ const ReactDataTable = <TData,>(props: ReactDataTableProps<TData>) => {
                                   icon={faTimes}
                                   onClick={() => {
                                     if (onEnter) {
-                                      onEnter([]);
+                                      onEnter(getModelFromColumnFilter(table.initialState.columnFilters));
                                     }
 
-                                    table.resetColumnFilters(true);
+                                    table.setColumnFilters(table.initialState.columnFilters);
                                   }}
                                 />
                               </>
                             )}
-
                             {header.column.getCanFilter() && (
                               <>
                                 {meta?.customFilter ? (
@@ -181,7 +182,7 @@ const ReactDataTable = <TData,>(props: ReactDataTableProps<TData>) => {
                                     }}
                                     onKeyUp={({ key }) => {
                                       if (key === "Enter" && onEnter) {
-                                        onEnter(table.getState().columnFilters);
+                                        onEnter(getModelFromColumnFilter(table.getState().columnFilters));
                                       }
                                     }}
                                     bsSize="sm"
@@ -201,7 +202,7 @@ const ReactDataTable = <TData,>(props: ReactDataTableProps<TData>) => {
                                     }}
                                     onKeyUp={({ key }) => {
                                       if (key === "Enter" && onEnter) {
-                                        onEnter(table.getState().columnFilters);
+                                        onEnter(getModelFromColumnFilter(table.getState().columnFilters));
                                       }
                                     }}
                                     bsSize="sm"

src/lib/ReactDataTable/ReactDataTableProps.ts

@@ -1,11 +1,12 @@
-import { ColumnFiltersState, Table } from "@tanstack/react-table";
+import { Table } from "@tanstack/react-table";
 import { CSSProperties } from "react";
+import { FilterModel } from "../types/TableState";
 import { DragAndDropOptions } from "./DragAndDropOptions";
 
 /**
  * The props for the ReactDataTable component
  */
-export interface ReactDataTableProps<TData> {
+export interface ReactDataTableProps<TData, TFilter extends FilterModel> {
   /**
    * the table instance returned from useReactDataTable or useReactTable
    */
@@ -65,7 +66,7 @@ export interface ReactDataTableProps<TData> {
   /**
    * callback that gets trigger by pressing enter or clicking the search icon
    */
-  onEnter?: (columnFilters: ColumnFiltersState) => void;
+  onEnter?: (columnFilters: TFilter) => void;
 
   /**
    * To draw the table without headers (titles + filters)

src/lib/types/ColumnFilterState.ts

@@ -0,0 +1,6 @@
+import { AllNullable } from "./NullableTypes";
+
+/**
+ * Type making the object possibly undefined if all properties are nullable
+ */
+export type ColumnFilterState<TFilter> = TFilter extends AllNullable<TFilter> ? TFilter | undefined : TFilter;

src/lib/types/NullableTypes.ts

@@ -0,0 +1,31 @@
+/**
+ * Type taking all nullable props from object T
+ */
+type PickNullable<T> = {
+  [P in keyof T as undefined extends T[P] ? P : never]: T[P];
+};
+
+/**
+ * Type taking all not nullable props from object T
+ */
+type PickNotNullable<T> = {
+  [P in keyof T as undefined extends T[P] ? never : P]: T[P];
+};
+
+/**
+ * Type defining an object with all nullable props as optional
+ */
+type OptionalNullable<T> = {
+  [K in keyof PickNullable<T>]?: Exclude<T[K], undefined>;
+} & {
+  [K in keyof PickNotNullable<T>]: T[K];
+};
+
+/**
+ * Object type in which all props are nullable
+ */
+type AllNullable<T> = {
+  [K in keyof T]: undefined extends T[K] ? T[K] : never;
+};
+
+export { OptionalNullable, AllNullable };

src/lib/types/SortingState.ts

@@ -0,0 +1,14 @@
+/**
+ * The type sorting state
+ */
+export interface SortingState<TData> {
+  /**
+   * the id of the sortable row
+   */
+  id: keyof TData;
+
+  /**
+   * the descending
+   */
+  desc: boolean;
+}

src/lib/types/TableState.ts

@@ -0,0 +1,24 @@
+import { CoreOptions } from "@tanstack/react-table";
+import { SortingState } from "./SortingState";
+
+/**
+ * Object type implementation
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type FilterModel = { [k: string]: any };
+
+/**
+ * The table sorting state
+ */
+interface TableState<TData, TFilter extends FilterModel> extends Pick<CoreOptions<TData>["state"], "pagination"> {
+  /**
+   * The column filters state
+   */
+  columnFilters: TFilter;
+  /**
+   * The sorting state
+   */
+  sorting: SortingState<TData> | undefined;
+}
+
+export { TableState, FilterModel };

src/lib/useFullyControlledReactDataTable/useFullyControlledReactDataTable.tsx

@@ -1,26 +1,28 @@
-import { TableState } from "@tanstack/react-table";
-import { useReactDataTable } from "../useReactDataTable/useReactDataTable";
+import { useReactDataTable } from "../useReactDataTable/useReactDataTable";
 import { useReactDataTableProps } from "../useReactDataTable/useReactDataTableProps";
 import { useReactDataTableResult } from "../useReactDataTable/useReactDataTableResult";
+import { FilterModel, TableState } from "../types/TableState";
 
 type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
 
-interface useFullyControlledReactDataTableProps<TData>
+interface useFullyControlledReactDataTableProps<TData, TFilter extends FilterModel>
   extends WithRequired<
-    Omit<useReactDataTableProps<TData>, "manualFiltering" | "manualPagination" | "manualSorting">,
+    Omit<useReactDataTableProps<TData, TFilter>, "manualFiltering" | "manualPagination" | "manualSorting">,
     "onColumnFiltersChange" | "onPaginationChange" | "onSortingChange"
   > {
   state: {
-    columnFilters: TableState["columnFilters"];
-    pagination: TableState["pagination"];
-    sorting: TableState["sorting"];
+    columnFilters: TableState<TData, TFilter>["columnFilters"];
+    pagination: TableState<TData, TFilter>["pagination"];
+    sorting: TableState<TData, TFilter>["sorting"];
   };
 }
 
 /**
  * A helper hook to use the useReactDataTable hook which is fully controlled. Usefull for server side filtering, sorting and pagination.
  */
-const useFullyControlledReactDataTable = <TData,>(props: useFullyControlledReactDataTableProps<TData>): useReactDataTableResult<TData> =>
-  useReactDataTable<TData>({ manualFiltering: true, manualPagination: true, manualSorting: true, ...props });
+const useFullyControlledReactDataTable = <TData, TFilter extends FilterModel>(
+  props: useFullyControlledReactDataTableProps<TData, TFilter>,
+): useReactDataTableResult<TData, TFilter> =>
+  useReactDataTable<TData, TFilter>({ manualFiltering: true, manualPagination: true, manualSorting: true, ...props });
 
 export { useFullyControlledReactDataTable };

src/lib/useReactDataTable/useReactDataTable.tsx

@@ -1,13 +1,21 @@
 import { getCoreRowModel, getFilteredRowModel, getPaginationRowModel, getSortedRowModel, useReactTable } from "@tanstack/react-table";
-import { useReactDataTableState } from "../useReactDataTableState/useReactDataTableState";
+import { useReactDataTableState, useReactDataTableStateProps } from "../useReactDataTableState/useReactDataTableState";
 import Skeleton from "react-loading-skeleton";
 import { useReactDataTableProps } from "./useReactDataTableProps";
 import { useReactDataTableResult } from "./useReactDataTableResult";
+import { getColumnFilterFromModel } from "../utils/getColumnFilterFromModel";
+import { FilterModel } from "../types/TableState";
+import { getModelFromColumnFilter } from "../utils/getModelFromColumnFilter";
+import { getSortingStateFromModel } from "../utils/getSortingStateFromModel";
+import { getModelFromSortingState } from "../utils/getModelFromSortingState";
+import { OptionalNullable } from "../types/NullableTypes";
 
 /**
  * A react hook that returns a react table instance and the state of the table
  */
-const useReactDataTable = <TData,>(props: useReactDataTableProps<TData>): useReactDataTableResult<TData> => {
+const useReactDataTable = <TData, TFilter extends FilterModel = Record<string, never>>(
+  props: useReactDataTableProps<TData, TFilter>,
+): useReactDataTableResult<TData, TFilter> => {
   const {
     data = [],
     columns,
@@ -32,11 +40,11 @@ const useReactDataTable = <TData,>(props: useReactDataTableProps<TData>): useRea
     setColumnFilters: setColumnFiltersInternal,
     setPagination: setPaginationInternal,
     setSorting: setSortingInternal,
-  } = useReactDataTableState({
-    initialColumnFilters: columnFiltersInitial,
+  } = useReactDataTableState<TData, TFilter>({
+    initialColumnFilters: columnFiltersInitial as TFilter,
     initialPagination: paginationInitial,
     initialSorting: sortingInitial,
-  });
+  } as unknown as OptionalNullable<useReactDataTableStateProps<TData, TFilter>>);
 
   const effectiveColumnFilters = columnFiltersExternal ?? columnFiltersInternal;
   const effectivePagination = paginationExternal ?? paginationInternal;
@@ -45,7 +53,7 @@ const useReactDataTable = <TData,>(props: useReactDataTableProps<TData>): useRea
   const effectiveOnPaginationChange = onPaginationChange ?? setPaginationInternal;
   const effectiveOnSortingChange = onSortingChange ?? setSortingInternal;
 
-  // If we active the manual filtering, we have to unset the filterfunction, else it still does automatic filtering
+  // If we active the manual filtering, we have to unset the filter function, else it still does automatic filtering
   if (manualFiltering) columns.forEach((x) => (x.filterFn = undefined));
 
   const internalColumns = columns.filter((x) => x.meta?.isHidden !== true);
@@ -60,22 +68,32 @@ const useReactDataTable = <TData,>(props: useReactDataTableProps<TData>): useRea
     columns: isLoading ? skeletonColumns : internalColumns,
 
     onColumnFiltersChange: (filtersOrUpdaterFn) => {
-      const newFilter = typeof filtersOrUpdaterFn !== "function" ? filtersOrUpdaterFn : filtersOrUpdaterFn(effectiveColumnFilters);
-      return effectiveOnColumnFiltersChange(newFilter);
+      const newFilter =
+        typeof filtersOrUpdaterFn !== "function"
+          ? filtersOrUpdaterFn
+          : filtersOrUpdaterFn(getColumnFilterFromModel(effectiveColumnFilters));
+      return effectiveOnColumnFiltersChange(getModelFromColumnFilter(newFilter));
     },
     onPaginationChange: (paginationOrUpdaterFn) => {
       const newFilter = typeof paginationOrUpdaterFn !== "function" ? paginationOrUpdaterFn : paginationOrUpdaterFn(effectivePagination);
       return effectiveOnPaginationChange(newFilter);
     },
     onSortingChange: (sortingOrUpdaterFn) => {
-      const newFilter = typeof sortingOrUpdaterFn !== "function" ? sortingOrUpdaterFn : sortingOrUpdaterFn(effectiveSorting);
-      return effectiveOnSortingChange(newFilter);
+      const newFilter =
+        typeof sortingOrUpdaterFn !== "function" ? sortingOrUpdaterFn : sortingOrUpdaterFn(getSortingStateFromModel(effectiveSorting));
+      return effectiveOnSortingChange(getModelFromSortingState(newFilter));
     },
 
     state: {
-      columnFilters: effectiveColumnFilters,
+      columnFilters: getColumnFilterFromModel(effectiveColumnFilters),
       pagination: effectivePagination,
-      sorting: effectiveSorting,
+      sorting: getSortingStateFromModel(effectiveSorting),
+    },
+
+    initialState: {
+      columnFilters: getColumnFilterFromModel(columnFiltersInitial ?? columnFiltersExternal ?? {}),
+      pagination: paginationInitial ?? paginationExternal,
+      sorting: getSortingStateFromModel(sortingInitial ?? sortingExternal),
     },
 
     getCoreRowModel: getCoreRowModel(),
@@ -99,7 +117,7 @@ const useReactDataTable = <TData,>(props: useReactDataTableProps<TData>): useRea
 
   return {
     table,
-    columnFilters: effectiveColumnFilters,
+    columnFilters: effectiveColumnFilters as TFilter,
     pagination: effectivePagination,
     sorting: effectiveSorting,
     setColumnFilters: effectiveOnColumnFiltersChange,