@databiosphere/findable-ui 18.0.0 → 19.0.0

package/src/config/entities.ts

@@ -1,8 +1,10 @@
 import { TabProps as MTabProps, Theme, ThemeOptions } from "@mui/material";
 import {
   CellContext,
+  ColumnDef,
   ColumnMeta,
   ColumnSort,
+  GroupingState,
   RowData,
   Table,
   TableOptions,
@@ -87,24 +89,24 @@ export interface CategoryConfig {
 
 /**
  * Column configuration.
+ * TanStack ColumnDef properties not currently supported include:
+ * - `enableMultiSort` - Note, table multi-sort is managed via table options.
  */
-export interface ColumnConfig<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- This config model is part of a generic array
-  T = any,
+export type ColumnConfig<
+  T extends RowData,
+  TValue = unknown,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- This config model is part of a generic array
   C extends keyof JSX.IntrinsicElements | JSXElementConstructor<any> = any
-> {
+> = Omit<ColumnDef<T, TValue>, "enableMultiSort"> & {
   columnPinned?: boolean; // Column is pinned to the top when table rows are collapsable.
   columnVisible?: boolean; // Column is visible. Default is "true".
   componentConfig: ComponentConfig<C, T>;
   disableHiding?: boolean; // Disables hiding of column. Column is unavailable for "Edit Columns" functionality when "true".
-  disableSorting?: boolean; // Disables sorting for the column.
   header: string;
   id: string; // The unique identifier for the column.
   meta?: ColumnMeta<T, unknown>;
-  tooltip?: string; // TODO review need to define `tooltip` field - it is currently not in use.
   width: GridTrackSize;
-}
+};
 
 /**
  * Interface used to define the configuration of a component.
@@ -256,7 +258,6 @@ export type GridTrackSize =
 /**
  * List configuration.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- This config model can receive any model as type
 export interface ListConfig<T extends RowData> {
   columns: ColumnConfig<T>[];
   defaultSort?: ColumnSort; // Establishes initial table state "sorting" state.
@@ -270,7 +271,6 @@ export interface ListViewConfig {
   disablePagination?: boolean;
   enableDownload?: boolean;
   enableRowPreview?: boolean;
-  enableRowSelection?: boolean;
   enableTab?: boolean;
   listHero?: ComponentsConfig;
   rowPreviewView?: ComponentsConfig; // Row preview view is expected to be a modal or drawer or similar.
@@ -312,6 +312,7 @@ export interface Override {
 
 export interface SavedFilter {
   filters: SelectedFilter[];
+  grouping?: GroupingState;
   sorting?: ColumnSort[];
   title: string;
 }

package/src/config/utils.ts

@@ -1,4 +1,3 @@
-import { ColumnSort } from "@tanstack/react-table";
 import { EXPLORE_MODE } from "../hooks/useExploreMode";
 import { getConfig } from "./config";
 import { EntityConfig, SiteConfig } from "./entities";
@@ -51,19 +50,6 @@ export function getDefaultEntityConfig(): EntityConfig {
   };
 }
 
-/**
- * Returns the initial table sorting state for the specified entity list configuration.
- * @param entityConfig - Entity configuration.
- * @returns initial sorting state.
- */
-export function getDefaultSorting(entityConfig: EntityConfig): ColumnSort[] {
-  const columnSort = entityConfig.list.defaultSort;
-  if (!columnSort) {
-    return [];
-  }
-  return [columnSort];
-}
-
 /**
  * Returns the entity config for the given entity list type.
  * @param entities - Entities config.

package/src/providers/exploreState/actions/updateGrouping/action.ts

@@ -0,0 +1,26 @@
+import { ExploreState } from "../../../exploreState";
+import { updateEntityPageState } from "../../utils";
+import { UpdateGroupingPayload } from "./types";
+import { buildNextGrouping } from "./utils";
+
+/**
+ * Reducer function to handle the "update grouping" action.
+ * Updates the grouping in the state for the current entity.
+ * @param state - Explore State.
+ * @param payload - Payload.
+ * @returns explore state.
+ */
+export function updateGroupingAction(
+  state: ExploreState,
+  payload: UpdateGroupingPayload
+): ExploreState {
+  const grouping = buildNextGrouping(state, payload.updaterOrValue);
+  return {
+    ...state,
+    entityPageState: updateEntityPageState(
+      state.tabValue,
+      state.entityPageState,
+      { grouping }
+    ),
+  };
+}

package/src/providers/exploreState/actions/updateGrouping/dispatch.ts

@@ -0,0 +1,16 @@
+import { ExploreActionKind } from "../../../exploreState";
+import { UpdateGroupingAction, UpdateGroupingPayload } from "./types";
+
+/**
+ * Action creator for updating grouping in the state.
+ * @param payload - Payload.
+ * @returns Action with payload and action type.
+ */
+export function updateGrouping(
+  payload: UpdateGroupingPayload
+): UpdateGroupingAction {
+  return {
+    payload,
+    type: ExploreActionKind.UpdateGrouping,
+  };
+}

package/src/providers/exploreState/actions/updateGrouping/types.ts

@@ -0,0 +1,11 @@
+import { GroupingState, Updater } from "@tanstack/react-table";
+import { ExploreActionKind } from "../../../exploreState";
+
+export type UpdateGroupingAction = {
+  payload: UpdateGroupingPayload;
+  type: ExploreActionKind.UpdateGrouping;
+};
+
+export type UpdateGroupingPayload = {
+  updaterOrValue: Updater<GroupingState>;
+};

package/src/providers/exploreState/actions/updateGrouping/utils.ts

@@ -0,0 +1,33 @@
+import { GroupingState, Updater } from "@tanstack/react-table";
+import { resolveUpdater } from "../../../../components/Table/options/updater";
+import { ExploreState } from "../../../exploreState";
+
+/**
+ * Builds the next grouping state for the current entity type.
+ * Uses TanStack updater to update the grouping state.
+ * @param state - Explore state.
+ * @param updaterOrValue - Updater or value to update the grouping state.
+ * @returns grouping state.
+ */
+export function buildNextGrouping(
+  state: ExploreState,
+  updaterOrValue: Updater<GroupingState>
+): GroupingState {
+  const grouping = resolveUpdater(updaterOrValue, getOldGrouping(state));
+  if (grouping.length > 1) {
+    // Explore state only supports single-column grouping.
+    return grouping.slice(-1);
+  }
+  return grouping;
+}
+
+/**
+ * Retrieves the current "old" grouping state from the explore state, for the current entity type.
+ * @param state - Explore state.
+ * @returns old grouping state.
+ */
+function getOldGrouping(state: ExploreState): GroupingState {
+  const { entityPageState, tabValue } = state;
+  const { grouping = [] } = entityPageState[tabValue];
+  return grouping;
+}

package/src/providers/exploreState/entities.ts

@@ -1,5 +1,6 @@
 import {
   ColumnSort,
+  GroupingState,
   RowSelectionState,
   VisibilityState,
 } from "@tanstack/react-table";
@@ -22,6 +23,7 @@ export interface EntityPageState {
   categoryGroupConfigKey: CategoryGroupConfigKey;
   columnsVisibility: VisibilityState;
   enableRowSelection: boolean;
+  grouping: GroupingState;
   rowPreview: RowPreviewState;
   rowSelection: RowSelectionState;
   sorting: ColumnSort[];
@@ -48,9 +50,7 @@ export type EntityStateByCategoryGroupConfigKey = Map<
 
 export type CategoryGroupConfigKey = CategoryGroupConfig["key"];
 
-export interface EntityStateSavedFilter extends Omit<SavedFilter, "sort"> {
-  sorting?: ColumnSort[];
-}
+export type EntityStateSavedFilter = SavedFilter;
 
 // eslint-disable-next-line  @typescript-eslint/no-explicit-any -- TODO revisit when adding react query or similar
 export type ListItem = any;

package/src/providers/exploreState/initializer/utils.ts

@@ -1,4 +1,8 @@
-import { VisibilityState } from "@tanstack/react-table";
+import {
+  ColumnSort,
+  GroupingState,
+  VisibilityState,
+} from "@tanstack/react-table";
 import { SelectCategory, SelectedFilter } from "../../../common/entities";
 import { getInitialTableColumnVisibility } from "../../../components/Table/common/utils";
 import { ACCESSOR_KEYS } from "../../../components/TableCreator/common/constants";
@@ -10,7 +14,6 @@ import {
   SavedFilter,
   SiteConfig,
 } from "../../../config/entities";
-import { getDefaultSorting } from "../../../config/utils";
 import { ExploreState } from "../../exploreState";
 import { SELECT_CATEGORY_KEY } from "../constants";
 import {
@@ -73,8 +76,13 @@ function buildSavedFilterByCategoryValueKey(
   if (!savedFilters) return;
   const savedFilterByCategoryValueKey: SavedFilterByCategoryValueKey =
     new Map();
-  for (const { filters, sorting, title } of savedFilters) {
-    savedFilterByCategoryValueKey.set(title, { filters, sorting, title });
+  for (const { filters, grouping, sorting, title } of savedFilters) {
+    savedFilterByCategoryValueKey.set(title, {
+      filters,
+      grouping,
+      sorting,
+      title,
+    });
   }
   return savedFilterByCategoryValueKey;
 }
@@ -145,18 +153,29 @@ function initColumnVisibility(entityConfig: EntityConfig): VisibilityState {
   const {
     list: {
       columns,
-      tableOptions: { initialState: { columnVisibility = {} } = {} } = {},
+      tableOptions: {
+        enableRowSelection,
+        initialState: { columnVisibility = {} } = {},
+      } = {},
     },
-    listView: { enableRowSelection = false } = {},
   } = entityConfig;
   return {
-    [ACCESSOR_KEYS.ROW_POSITION]: false, // Explicitly setting row position to false; required - currently `columnVisibilty` is initialized from columns configuration.
-    [ACCESSOR_KEYS.SELECT]: enableRowSelection,
+    [ACCESSOR_KEYS.ROW_POSITION]: false, // Explicitly setting row position to false; required - currently `columnVisibility` is initialized from columns configuration.
+    [ACCESSOR_KEYS.SELECT]: Boolean(enableRowSelection),
     ...getInitialTableColumnVisibility(columns),
     ...columnVisibility, // `columnVisibility` is managed by ExploreState; use table options to override this setting.
   };
 }
 
+/**
+ * Returns the initial `enableRowSelection` option for the specified entity list configuration.
+ * @param entityConfig - Entity configuration.
+ * @returns initial `enableRowSelection` option.
+ */
+function initEnableRowSelection(entityConfig: EntityConfig): boolean {
+  return Boolean(entityConfig.list.tableOptions?.enableRowSelection);
+}
+
 /**
  * Initializes entity page state.
  * @param config - Site config.
@@ -169,10 +188,11 @@ function initEntityPageState(config: SiteConfig): EntityPageStateMapper {
       [entity.route]: {
         categoryGroupConfigKey: initCategoryGroupConfigKey(config, entity),
         columnsVisibility: initColumnVisibility(entity),
-        enableRowSelection: Boolean(entity.listView?.enableRowSelection),
+        enableRowSelection: initEnableRowSelection(entity),
+        grouping: initGrouping(entity),
         rowPreview: undefined,
         rowSelection: {},
-        sorting: getDefaultSorting(entity),
+        sorting: initSorting(entity),
       },
     };
   }, {} as EntityPageStateMapper);
@@ -230,6 +250,34 @@ function initFilterState(decodedFilterParam: string): SelectedFilter[] {
   return filterState;
 }
 
+/**
+ * Returns the initial table grouping state for the specified entity list configuration.
+ * @param entityConfig - Entity configuration.
+ * @returns initial grouping state.
+ */
+function initGrouping(entityConfig: EntityConfig): GroupingState {
+  const {
+    list: { tableOptions: { initialState: { grouping = [] } = {} } = {} },
+  } = entityConfig;
+  return grouping;
+}
+
+/**
+ * Returns the initial table sorting state for the specified entity list configuration.
+ * @param entityConfig - Entity configuration.
+ * @returns initial sorting state.
+ */
+function initSorting(entityConfig: EntityConfig): ColumnSort[] {
+  const {
+    list: {
+      defaultSort,
+      tableOptions: { initialState: { sorting = [] } = {} } = {},
+    },
+  } = entityConfig;
+  if (defaultSort) return [defaultSort];
+  return sorting;
+}
+
 /**
  * Returns the explore state reducer initial arguments.
  * @param config - Site config.

package/src/providers/exploreState/payloads/entities.ts

@@ -1,5 +1,6 @@
 import {
   ColumnSort,
+  GroupingState,
   RowSelectionState,
   VisibilityState,
 } from "@tanstack/react-table";
@@ -62,6 +63,7 @@ export type UpdateColumnVisibilityPayload = VisibilityState;
 export interface UpdateEntityFiltersPayload {
   entityListType: string;
   filters: SelectedFilter[];
+  grouping?: GroupingState;
   sorting?: ColumnSort[];
 }
 /**

package/src/providers/exploreState/utils.ts

@@ -1,4 +1,3 @@
-import { ColumnSort } from "@tanstack/react-table";
 import {
   CategoryKey,
   CategoryValueKey,
@@ -109,20 +108,24 @@ export function getEntityStateSavedFilter(
 }
 
 /**
- * Returns entity state "saved filter" sorting for the given category value key.
+ * Retrieves a specified property from the "saved filter" for the given category value key.
+ * This function fetches a property (e.g., "sorting" or "grouping") from the saved filter
+ * associated with a given `selectedValue`.
  * @param state - Explore state.
  * @param selectedValue - Key of category value that has been de/selected.
  * @param selected - True if value is selected, false if de-selected.
- * @returns sorting.
+ * @param propertyName - The name of the property to retrieve from the saved filter. Should be one of the predefined keys: "sorting" or "grouping".
+ * @returns value of the specified property from the saved filter, or undefined if `selected` is false.
  */
-export function getEntityStateSavedSorting(
+export function getEntityStateSavedProperty<K extends "sorting" | "grouping">(
   state: ExploreState,
   selectedValue: CategoryValueKey,
-  selected: boolean
-): ColumnSort[] | undefined {
+  selected: boolean,
+  propertyName: K
+): EntityStateSavedFilter[K] | undefined {
   if (!selected) return;
   const savedFilter = getEntityStateSavedFilter(state, selectedValue);
-  return savedFilter?.sorting;
+  return savedFilter?.[propertyName];
 }
 
 /**

package/src/providers/exploreState.tsx

@@ -19,6 +19,8 @@ import {
 } from "../hooks/useCategoryFilter";
 import { useConfig } from "../hooks/useConfig";
 import { useURLFilterParams } from "../hooks/useURLFilterParams";
+import { updateGroupingAction } from "./exploreState/actions/updateGrouping/action";
+import { UpdateGroupingAction } from "./exploreState/actions/updateGrouping/types";
 import {
   EntityPageStateMapper,
   EntityStateByCategoryGroupConfigKey,
@@ -49,7 +51,7 @@ import {
   closeRowPreview,
   getEntityCategoryGroupConfigKey,
   getEntityState,
-  getEntityStateSavedSorting,
+  getEntityStateSavedProperty,
   getFilterCount,
   patchEntityListItems,
   resetPage,
@@ -226,6 +228,7 @@ export enum ExploreActionKind {
   UpdateEntityFilters = "UPDATE_ENTITY_FILTERS",
   UpdateEntityViewAccess = "UPDATE_ENTITY_VIEW_ACCESS",
   UpdateFilter = "UPDATE_FILTER",
+  UpdateGrouping = "UPDATE_GROUPING",
   UpdateRowPreview = "UPDATE_ROW_PREVIEW",
   UpdateRowSelection = "UPDATE_ROW_SELECTION",
   UpdateSorting = "UPDATE_SORTING",
@@ -247,6 +250,7 @@ export type ExploreAction =
   | UpdateEntityFiltersAction
   | UpdateEntityViewAccessAction
   | UpdateFilterAction
+  | UpdateGroupingAction
   | UpdateRowPreviewAction
   | UpdateRowSelectionAction
   | UpdateSortingAction;
@@ -403,11 +407,19 @@ function exploreReducer(
         payload.selectedValue,
         payload.selected
       );
-      const savedSorting = getEntityStateSavedSorting(
+      const savedGrouping = getEntityStateSavedProperty(
         state,
         payload.selectedValue,
-        payload.selected
+        payload.selected,
+        "grouping"
+      );
+      const savedSorting = getEntityStateSavedProperty(
+        state,
+        payload.selectedValue,
+        payload.selected,
+        "sorting"
       );
+      const grouping = savedGrouping || []; // Reset grouping to default if saved grouping is not available.
       const sorting = savedSorting || []; // Reset sorting to default if saved sorting is not available.
       updateEntityStateByCategoryGroupConfigKey(state, {
         filterState,
@@ -417,7 +429,7 @@ function exploreReducer(
         ...state,
         entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(
           state,
-          { rowPreview, rowSelection, sorting }
+          { grouping, rowPreview, rowSelection, sorting }
         ),
         filterCount: getFilterCount(filterState),
         filterState,
@@ -592,7 +604,12 @@ function exploreReducer(
      * - closes row preview, without updating the entity page state row preview.
      */
     case ExploreActionKind.UpdateEntityFilters: {
-      const { entityListType, filters: filterState, sorting } = payload;
+      const {
+        entityListType,
+        filters: filterState,
+        grouping = [],
+        sorting = [],
+      } = payload;
       const categoryGroupConfigKey = getEntityCategoryGroupConfigKey(
         entityListType,
         state.entityPageState
@@ -614,7 +631,7 @@ function exploreReducer(
         ...state,
         entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(
           state,
-          { rowPreview, rowSelection, sorting },
+          { grouping, rowPreview, rowSelection, sorting },
           categoryGroupConfigKey
         ),
         rowPreview: closeRowPreview(state.rowPreview),
@@ -658,6 +675,12 @@ function exploreReducer(
         rowPreview,
       };
     }
+    /**
+     * Update grouping
+     **/
+    case ExploreActionKind.UpdateGrouping: {
+      return updateGroupingAction(state, payload);
+    }
     /**
      * Update row preview
      */

package/src/views/ExploreView/exploreView.tsx

@@ -248,7 +248,7 @@ function renderList(
 ): JSX.Element {
   const { listItems, loading, tabValue } = exploreState;
   const { getId: getRowId, list, listView } = entityConfig;
-  const { columns: columnsConfig, defaultSort, tableOptions } = list;
+  const { columns: columnsConfig } = list;
 
   if (!exploreState || !tabValue) {
     return <></>; //TODO: return the loading UI component
@@ -263,12 +263,10 @@ function renderList(
   return (
     <TableCreator
       columns={columnsConfig}
-      defaultSort={defaultSort}
       getRowId={getRowId}
       items={listItems ?? []}
       listView={listView}
       loading={loading}
-      tableOptions={tableOptions}
     />
   );
 }

package/types/data-explorer-ui.d.ts

@@ -269,7 +269,6 @@ declare module "@tanstack/react-table" {
   interface ColumnMeta<TData extends RowData, TValue> {
     align?: TableCellProps["align"];
     columnPinned?: boolean;
-    enableSortingInteraction?: boolean; // Flag to enable sorting interaction UI (e.g. sort icon) button; defaults to true.
     header?: string;
     width?: GridTrackSize;
   }
@@ -277,6 +276,14 @@ declare module "@tanstack/react-table" {
   interface InitialTableState extends CustomFeatureInitialTableState {}
   // eslint-disable-next-line @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars -- empty interface is needed for extending, TData is an unused variable.
   interface Row<TData extends RowData> extends CustomFeatureRow {}
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- TData is an unused variables.
+  interface SortingOptions<TData extends RowData> {
+    /**
+     * When false, sorting can still be applied programmatically (e.g., `getSortedRowModel`),
+     * but user interactions or showing sort icons are disabled.
+     */
+    enableSortingInteraction?: boolean;
+  }
   // eslint-disable-next-line @typescript-eslint/no-empty-interface -- empty interface is needed for extending.
   interface Table<TData extends RowData> extends CustomFeatureInstance<TData> {}
   // eslint-disable-next-line @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars -- empty interface is needed for extending, TData is an unused variable.

package/lib/components/TableCreator/common/entities.d.ts

@@ -1,5 +0,0 @@
-import { ColumnMeta } from "@tanstack/react-table";
-import { ColumnConfig } from "../../../config/entities";
-export interface BaseColumnConfig<T, TValue> extends ColumnConfig<T> {
-    meta?: ColumnMeta<T, TValue>;
-}

package/src/components/TableCreator/common/entities.ts

@@ -1,6 +0,0 @@
-import { ColumnMeta } from "@tanstack/react-table";
-import { ColumnConfig } from "../../../config/entities";
-
-export interface BaseColumnConfig<T, TValue> extends ColumnConfig<T> {
-  meta?: ColumnMeta<T, TValue>;
-}