@databiosphere/findable-ui 34.0.0 → 35.0.1

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

@@ -0,0 +1,14 @@
+import { ExploreActionKind } from "../../../exploreState";
+import { StateToUrlAction, StateToUrlPayload } from "./types";
+
+/**
+ * Action creator for state >> URL sync.
+ * @param payload - Payload.
+ * @returns Action with payload and action type.
+ */
+export function stateToUrl(payload: StateToUrlPayload): StateToUrlAction {
+  return {
+    payload,
+    type: ExploreActionKind.StateToUrl,
+  };
+}

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

@@ -0,0 +1,15 @@
+import { ExploreActionKind } from "../../../exploreState";
+
+export enum ROUTER_METHOD {
+  PUSH = "push",
+  REPLACE = "replace",
+}
+
+export type StateToUrlAction = {
+  payload: StateToUrlPayload;
+  type: ExploreActionKind.StateToUrl;
+};
+
+export type StateToUrlPayload = {
+  method: ROUTER_METHOD;
+};

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

@@ -0,0 +1,74 @@
+import {
+  CatalogState,
+  ExploreState,
+  FeatureFlagState,
+} from "../../../exploreState";
+import { EXPLORE_URL_PARAMS } from "../../../exploreState/constants";
+import { buildNextEntities } from "../../entities/state";
+import {
+  getEntityCategoryGroupConfigKey,
+  getFilterCount,
+  updateEntityStateByCategoryGroupConfigKey,
+} from "../../utils";
+import { UrlToStatePayload } from "./types";
+import { decodeFilterParamValue } from "./utils";
+
+/**
+ * Reducer function to handle the "URL >> state sync" action.
+ * @param state - State.
+ * @param payload - Payload.
+ * @returns state.
+ */
+export function urlToStateAction(
+  state: ExploreState,
+  payload: UrlToStatePayload
+): ExploreState {
+  const { query } = payload;
+
+  // Get the entity list type from the query.
+  const { entityListType } = query;
+
+  // If the entityListType is not a string, return the current state.
+  if (typeof entityListType !== "string") return state;
+
+  // Decode the catalog param value to catalog state.
+  const catalogState = query[EXPLORE_URL_PARAMS.CATALOG] as CatalogState;
+
+  // Decode the filter param value to selected filters.
+  const filterState = decodeFilterParamValue(query[EXPLORE_URL_PARAMS.FILTER]);
+
+  // Decode the feature flag param value to feature flag state.
+  const featureFlagState = query[
+    EXPLORE_URL_PARAMS.FEATURE_FLAG
+  ] as FeatureFlagState;
+
+  // Grab the category group config key for the entityListType.
+  const categoryGroupConfigKey = getEntityCategoryGroupConfigKey(
+    entityListType,
+    state.entityPageState
+  );
+
+  // Update the entity state by category group config key.
+  updateEntityStateByCategoryGroupConfigKey(
+    state,
+    { filterState, savedFilterState: [] },
+    categoryGroupConfigKey
+  );
+
+  return {
+    ...state,
+    catalogState,
+    entities: buildNextEntities(
+      { ...state, catalogState, featureFlagState },
+      entityListType,
+      { filterState }
+    ),
+    featureFlagState,
+    filterCount:
+      entityListType === state.tabValue
+        ? getFilterCount(filterState)
+        : state.filterCount,
+    filterState:
+      entityListType === state.tabValue ? filterState : state.filterState,
+  };
+}

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

@@ -0,0 +1,14 @@
+import { ExploreActionKind } from "../../../exploreState";
+import { UrlToStateAction, UrlToStatePayload } from "./types";
+
+/**
+ * Action creator for URL >> state sync.
+ * @param payload - Payload.
+ * @returns Action with payload and action type.
+ */
+export function urlToState(payload: UrlToStatePayload): UrlToStateAction {
+  return {
+    payload,
+    type: ExploreActionKind.UrlToState,
+  };
+}

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

@@ -0,0 +1,11 @@
+import { NextRouter } from "next/router";
+import { ExploreActionKind } from "../../../exploreState";
+
+export type UrlToStateAction = {
+  payload: UrlToStatePayload;
+  type: ExploreActionKind.UrlToState;
+};
+
+export type UrlToStatePayload = {
+  query: NextRouter["query"];
+};

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

@@ -0,0 +1,18 @@
+import { SelectedFilter } from "../../../../common/entities";
+
+/**
+ * Returns the selected filters from the filter parameter value.
+ * @param paramValue - The filter parameter value.
+ * @returns The selected filters or an empty array.
+ */
+export function decodeFilterParamValue(
+  paramValue: string | string[] | undefined
+): SelectedFilter[] {
+  if (typeof paramValue === "string") {
+    // Return decoded filter param value if it is a string.
+    return JSON.parse(decodeURIComponent(paramValue));
+  }
+
+  // Default to an empty array.
+  return [];
+}

package/src/providers/exploreState/entities/query/buildQuery.ts

@@ -0,0 +1,66 @@
+import { NextRouter } from "next/router";
+import { SelectedFilter } from "../../../../common/entities";
+import { EntityState } from "../types";
+
+/**
+ * Builds a query object from entity related state.
+ * State values are expected to be undefined, string, or an array.
+ * Undefined values and empty arrays are not included in the query.
+ * @param entityListType - Entity list type.
+ * @param state - Entity related state.
+ * @returns A query object.
+ */
+export function buildQuery(
+  entityListType: string,
+  state: EntityState
+): NextRouter["query"] {
+  const query: NextRouter["query"] = {};
+
+  for (const [key, value] of Object.entries(
+    getQueryState(entityListType, state)
+  )) {
+    // Handle the undefined case.
+    if (value === undefined) continue;
+
+    // Handle the string case.
+    if (typeof value === "string") {
+      query[key] = value;
+      continue;
+    }
+
+    // Handle the array case.
+    if (value.length === 0) continue;
+    query[key] = JSON.stringify(value);
+  }
+
+  return query;
+}
+
+/**
+ * Extracts URL-relevant values from the ExploreState for query parameter synchronization.
+ *
+ * This function maps specific properties from the full ExploreState to the
+ * ExploreQueryState interface, which contains only the subset of state that
+ * should be synchronized with the URL.
+ *
+ * The extracted properties are:
+ * - catalog: Current catalog selection (string | undefined)
+ * - entityListType: Entity list type (string)
+ * - ff: Feature flag state (string | undefined)
+ * - filter: Applied filters (SelectedFilter[])
+ *
+ * @param entityListType - Entity list type.
+ * @param state - Entity related state.
+ * @returns Subset of state used for URL query parameters.
+ */
+export function getQueryState(
+  entityListType: string,
+  state: EntityState
+): Record<string, string | SelectedFilter[] | undefined> {
+  return {
+    catalog: state.catalogState,
+    entityListType,
+    ff: state.featureFlagState,
+    filter: state.filterState,
+  };
+}

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

@@ -0,0 +1,50 @@
+import { ExploreState } from "../../exploreState";
+import { buildQuery } from "./query/buildQuery";
+import { EntitiesContext, EntityState } from "./types";
+
+/**
+ * Builds the next entities context.
+ * @param state - State.
+ * @param entityListType - Entity list type.
+ * @param nextEntityState - Next entity state.
+ * @returns Next entities context.
+ */
+export function buildNextEntities(
+  state: ExploreState,
+  entityListType: string,
+  nextEntityState: Pick<EntityState, "filterState">
+): EntitiesContext {
+  // Get the entity key for the current entity.
+  // Other entities may share the same key and therefore filter state.
+  const key = state.entities[entityListType].entityKey;
+
+  const entities: EntitiesContext = {};
+
+  for (const [entityPath, entity] of Object.entries(state.entities)) {
+    // Grab the entity key for the entity.
+    const entityKey = entity.entityKey;
+
+    if (entityKey !== key) {
+      // For entities that do not share the same key, leave the context unchanged.
+      entities[entityPath] = entity;
+      continue;
+    }
+
+    // Clone the entity context.
+    const entityContext = { ...entity };
+
+    // Update entity context with "shared" context (e.g. filterState).
+    entityContext.query = buildQuery(entityPath, {
+      ...nextEntityState,
+      catalogState: state.catalogState,
+      featureFlagState: state.featureFlagState,
+    });
+
+    // At some point, we may need to update the entity context with additional properties that
+    // are not "shared" (e.g. column grouping).
+    // For now, this is not needed and so we update entities with the updated entity context and continue.
+    entities[entityPath] = entityContext;
+  }
+
+  return entities;
+}

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

@@ -0,0 +1,19 @@
+import { NextRouter } from "next/router";
+import { SelectedFilter } from "../../../common/entities";
+import { EntityPath } from "../../../config/entities";
+import { CatalogState, FeatureFlagState } from "../../exploreState";
+
+export interface EntitiesContext {
+  [key: EntityPath]: EntityContext;
+}
+
+export interface EntityContext {
+  entityKey: string;
+  query: NextRouter["query"];
+}
+
+export interface EntityState {
+  catalogState: CatalogState;
+  featureFlagState: FeatureFlagState;
+  filterState: SelectedFilter[];
+}

package/src/providers/exploreState/entities.ts

@@ -18,7 +18,7 @@ import {
   EntityPath,
   SavedFilter,
 } from "../../config/entities";
-import { META_COMMAND } from "./hooks/UseMetaCommands/types";
+import { META_COMMAND } from "../../hooks/stateSyncManager/hooks/UseMetaCommands/types";
 
 export interface EntityPageState {
   categoryGroupConfigKey: CategoryGroupConfigKey;

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

@@ -29,6 +29,7 @@ export const DEFAULT_PAGINATION_STATE: PaginationState = {
 export const INITIAL_STATE: ExploreState = {
   catalogState: undefined,
   categoryViews: [],
+  entities: {},
   entityPageState: {},
   entityStateByCategoryGroupConfigKey: new Map(),
   featureFlagState: undefined,

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

@@ -21,6 +21,8 @@ import {
   EntityStateByCategoryGroupConfigKey,
   SavedFilterByCategoryValueKey,
 } from "../entities";
+import { buildNextEntities } from "../entities/state";
+import { EntitiesContext } from "../entities/types";
 import { getEntityCategoryGroupConfigKey, getFilterCount } from "../utils";
 import {
   DEFAULT_CATEGORY_GROUP_SAVED_FILTERS,
@@ -186,6 +188,23 @@ function initEntityPageState(config: SiteConfig): EntityPageStateMapper {
   }, {} as EntityPageStateMapper);
 }
 
+/**
+ * Initializes entities context.
+ * @param entityPageState - Entity page state.
+ * @returns Entities context.
+ */
+function initEntities(entityPageState: EntityPageStateMapper): EntitiesContext {
+  return Object.keys(entityPageState).reduce((acc, entityPath) => {
+    return {
+      ...acc,
+      [entityPath]: {
+        entityKey: entityPageState[entityPath].categoryGroupConfigKey,
+        query: {},
+      },
+    };
+  }, {} as EntitiesContext);
+}
+
 /**
  * Initializes entity state by category group config key.
  * @param config - Site config.
@@ -294,10 +313,14 @@ export function initReducerArguments(
     entityStateByCategoryGroupConfigKey,
     categoryGroupConfigKey
   );
-  return {
+  const entities = initEntities(entityPageState);
+
+  // Initialize state.
+  const state = {
     ...INITIAL_STATE,
     catalogState: decodedCatalogParam,
     categoryGroups,
+    entities,
     entityPageState,
     entityStateByCategoryGroupConfigKey,
     featureFlagState: decodedFeatureFlagParam,
@@ -305,4 +328,10 @@ export function initReducerArguments(
     filterState,
     tabValue: entityListType,
   };
+
+  // Return state with entities (updated by initial state).
+  return {
+    ...state,
+    entities: buildNextEntities(state, entityListType, { filterState }),
+  };
 }

package/src/providers/exploreState.tsx

@@ -14,6 +14,7 @@ import { SelectedFilter } from "../common/entities";
 import { RowPreviewState } from "../components/Table/features/RowPreview/entities";
 import { CategoryGroup, SiteConfig } from "../config/entities";
 import { useToken } from "../hooks/authentication/token/useToken";
+import { META_COMMAND } from "../hooks/stateSyncManager/hooks/UseMetaCommands/types";
 import {
   buildCategoryViews,
   buildNextFilterState,
@@ -22,21 +23,22 @@ import { useConfig } from "../hooks/useConfig";
 import { useURLFilterParams } from "../hooks/useURLFilterParams";
 import { clearMetaAction } from "./exploreState/actions/clearMeta/action";
 import { ClearMetaAction } from "./exploreState/actions/clearMeta/types";
-import { syncStateFromUrlAction } from "./exploreState/actions/syncStateFromUrl/action";
-import { SyncStateFromUrlAction } from "./exploreState/actions/syncStateFromUrl/types";
+import { stateToUrlAction } from "./exploreState/actions/stateToUrl/action";
+import { StateToUrlAction } from "./exploreState/actions/stateToUrl/types";
 import { updateGroupingAction } from "./exploreState/actions/updateGrouping/action";
 import { UpdateGroupingAction } from "./exploreState/actions/updateGrouping/types";
 import { updateColumnVisibilityAction } from "./exploreState/actions/updateVisibility/action";
 import { UpdateColumnVisibilityAction } from "./exploreState/actions/updateVisibility/types";
+import { urlToStateAction } from "./exploreState/actions/urlToState/action";
+import { UrlToStateAction } from "./exploreState/actions/urlToState/types";
 import {
   EntityPageStateMapper,
   EntityStateByCategoryGroupConfigKey,
   ListItem,
   Meta,
 } from "./exploreState/entities";
-import { useBeforePopState } from "./exploreState/hooks/UseBeforePopState/useBeforePopState";
-import { META_COMMAND } from "./exploreState/hooks/UseMetaCommands/types";
-import { useMetaCommands } from "./exploreState/hooks/UseMetaCommands/useMetaCommands";
+import { buildNextEntities } from "./exploreState/entities/state";
+import { EntitiesContext } from "./exploreState/entities/types";
 import {
   DEFAULT_PAGINATION_STATE,
   INITIAL_STATE,
@@ -88,6 +90,7 @@ export type ExploreState = {
   catalogState: CatalogState;
   categoryGroups?: CategoryGroup[];
   categoryViews: CategoryView[];
+  entities: EntitiesContext;
   entityPageState: EntityPageStateMapper;
   entityStateByCategoryGroupConfigKey: EntityStateByCategoryGroupConfigKey;
   featureFlagState: FeatureFlagState;
@@ -215,12 +218,6 @@ export function ExploreStateProvider({
     });
   }, [exploreDispatch, token]);
 
-  // Meta-command related side effects.
-  useMetaCommands({ exploreDispatch, exploreState });
-
-  // Before pop state related side effects (forward / backward navigation by browser buttons).
-  useBeforePopState({ exploreDispatch, exploreState });
-
   return (
     <ExploreStateContext.Provider value={exploreContextValue}>
       {children}
@@ -241,7 +238,7 @@ export enum ExploreActionKind {
   ResetExploreResponse = "RESET_EXPLORE_RESPONSE",
   ResetState = "RESET_STATE",
   SelectEntityType = "SELECT_ENTITY_TYPE",
-  SyncStateFromUrl = "SYNC_STATE_FROM_URL",
+  StateToUrl = "STATE_TO_URL",
   UpdateColumnVisibility = "UPDATE_COLUMN_VISIBILITY",
   UpdateEntityFilters = "UPDATE_ENTITY_FILTERS",
   UpdateEntityViewAccess = "UPDATE_ENTITY_VIEW_ACCESS",
@@ -250,6 +247,7 @@ export enum ExploreActionKind {
   UpdateRowPreview = "UPDATE_ROW_PREVIEW",
   UpdateRowSelection = "UPDATE_ROW_SELECTION",
   UpdateSorting = "UPDATE_SORTING",
+  UrlToState = "URL_TO_STATE",
 }
 
 /**
@@ -265,7 +263,7 @@ export type ExploreAction =
   | ResetExploreResponseAction
   | ResetStateAction
   | SelectEntityTypeAction
-  | SyncStateFromUrlAction
+  | StateToUrlAction
   | UpdateColumnVisibilityAction
   | UpdateEntityFiltersAction
   | UpdateEntityViewAccessAction
@@ -273,7 +271,8 @@ export type ExploreAction =
   | UpdateGroupingAction
   | UpdateRowPreviewAction
   | UpdateRowSelectionAction
-  | UpdateSortingAction;
+  | UpdateSortingAction
+  | UrlToStateAction;
 
 /**
  * Apply saved filter action.
@@ -439,13 +438,14 @@ function exploreReducer(
       });
       return {
         ...state,
+        entities: buildNextEntities(state, state.tabValue, { filterState }),
         entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(
           state,
           { grouping, rowPreview, rowSelection, sorting }
         ),
         filterCount: getFilterCount(filterState),
         filterState,
-        meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_PUSH },
         paginationState: resetPage(state.paginationState),
         rowPreview,
       };
@@ -465,13 +465,14 @@ function exploreReducer(
       });
       return {
         ...state,
+        entities: buildNextEntities(state, state.tabValue, { filterState }),
         entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(
           state,
           { rowPreview, rowSelection }
         ),
         filterCount,
         filterState,
-        meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_PUSH },
         paginationState: resetPage(state.paginationState),
         rowPreview,
       };
@@ -578,8 +579,7 @@ function exploreReducer(
      **/
     case ExploreActionKind.SelectEntityType: {
       if (payload === state.tabValue) {
-        // Update meta to match command "REPLACE_TO_FILTERS" - facilitates navigation to filters on return back to entity from elsewhere.
-        return { ...state, meta: { command: META_COMMAND.REPLACE_TO_FILTERS } };
+        return state;
       }
       const entityState = getEntityState(
         state,
@@ -594,17 +594,16 @@ function exploreReducer(
         filterState: entityState.filterState,
         listItems: [],
         loading: true,
-        meta: { command: META_COMMAND.REPLACE_TO_FILTERS },
         paginationState: { ...resetPage(state.paginationState), rows: 0 },
         rowPreview,
         tabValue: payload,
       };
     }
     /**
-     * Sync state from URL.
+     * State >> URL sync
      */
-    case ExploreActionKind.SyncStateFromUrl: {
-      return syncStateFromUrlAction(state, payload);
+    case ExploreActionKind.StateToUrl: {
+      return stateToUrlAction(state, payload);
     }
     /**
      * Update column visibility
@@ -649,6 +648,7 @@ function exploreReducer(
       );
       return {
         ...state,
+        entities: buildNextEntities(state, entityListType, { filterState }),
         entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(
           state,
           { grouping, rowPreview, rowSelection, sorting },
@@ -693,13 +693,14 @@ function exploreReducer(
       });
       return {
         ...state,
+        entities: buildNextEntities(state, state.tabValue, { filterState }),
         entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(
           state,
           { rowPreview, rowSelection }
         ),
         filterCount: getFilterCount(filterState),
         filterState,
-        meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_PUSH },
         paginationState: resetPage(state.paginationState),
         rowPreview,
       };
@@ -756,7 +757,12 @@ function exploreReducer(
         rowPreview,
       };
     }
-
+    /**
+     * URL >> state sync.
+     */
+    case ExploreActionKind.UrlToState: {
+      return urlToStateAction(state, payload);
+    }
     default:
       return state;
   }

package/src/providers/services/provider.tsx

@@ -0,0 +1,25 @@
+import React, { ReactNode } from "react";
+import { usePopStateBus } from "../../services/beforePopState/usePopStateBus";
+import { WasPopProvider } from "./wasPop/provider";
+
+/**
+ * ServicesProvider is a component that initializes and provides access to various service-related
+ * functionality throughout the application.
+ *
+ * This provider:
+ * 1. Registers the pop state bus to handle browser navigation events.
+ * 2. Provides the WasPopProvider context to track browser back/forward navigation
+ *
+ * This provider should be placed at the _app root level to ensure all components have access to these services.
+ */
+
+export function ServicesProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  // Register the pop state bus.
+  usePopStateBus();
+
+  return <WasPopProvider>{children}</WasPopProvider>;
+}

package/src/providers/services/wasPop/context.ts

@@ -0,0 +1,7 @@
+import { createContext } from "react";
+import { WasPopContextProps } from "./types";
+
+export const WasPopContext = createContext<WasPopContextProps>({
+  onClearPopRef: () => {},
+  popRef: { current: undefined },
+});

package/src/providers/services/wasPop/hook.ts

@@ -0,0 +1,7 @@
+import { useContext } from "react";
+import { WasPopContext } from "./context";
+import { WasPopContextProps } from "./types";
+
+export const useWasPop = (): WasPopContextProps => {
+  return useContext(WasPopContext);
+};

package/src/providers/services/wasPop/provider.tsx

@@ -0,0 +1,45 @@
+import React, { ReactNode, useCallback, useRef } from "react";
+import { NextHistoryState } from "../../../services/beforePopState/types";
+import { useOnPopState } from "../../../services/beforePopState/useOnPopState";
+import { WasPopContext } from "./context";
+
+/**
+ * WasPopProvider tracks browser navigation events to determine if the current route change
+ * was triggered by a popstate event (browser back/forward navigation).
+ *
+ * This provider:
+ * 1. Registers callbacks for route change events.
+ * 2. Tracks when navigation occurs via browser back/forward buttons
+ * 3. Provides this state via context to child components
+ *
+ * This allows components to respond differently to user-initiated navigation versus
+ * browser history navigation.
+ */
+
+export function WasPopProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const popRef = useRef<NextHistoryState | undefined>();
+
+  // Pop callback.
+  const onBeforePopState = useCallback((state: NextHistoryState) => {
+    popRef.current = state;
+    return true;
+  }, []);
+
+  // Clear pop ref.
+  const onClearPopRef = useCallback(() => {
+    popRef.current = undefined;
+  }, []);
+
+  // Register the callback to be invoked before pop.
+  useOnPopState(onBeforePopState);
+
+  return (
+    <WasPopContext.Provider value={{ onClearPopRef, popRef }}>
+      {children}
+    </WasPopContext.Provider>
+  );
+}

package/src/providers/services/wasPop/types.ts

@@ -0,0 +1,7 @@
+import { MutableRefObject } from "react";
+import { NextHistoryState } from "../../../services/beforePopState/types";
+
+export interface WasPopContextProps {
+  onClearPopRef: () => void;
+  popRef: MutableRefObject<NextHistoryState | undefined>;
+}