@databiosphere/findable-ui 34.0.0 → 34.1.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "34.0.0"
+  ".": "34.1.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [34.1.0](https://github.com/DataBiosphere/findable-ui/compare/v34.0.0...v34.1.0) (2025-05-29)
+
+
+### Features
+
+* entity lists do not load when page refreshes ([#506](https://github.com/DataBiosphere/findable-ui/issues/506)) ([#507](https://github.com/DataBiosphere/findable-ui/issues/507)) ([05ba8a1](https://github.com/DataBiosphere/findable-ui/commit/05ba8a17d5c94b35e35056a51d06066f337a276a))
+
 ## [34.0.0](https://github.com/DataBiosphere/findable-ui/compare/v33.0.0...v34.0.0) (2025-05-27)
 
 

package/lib/providers/exploreState/entities.d.ts

@@ -4,7 +4,7 @@ import { CategoryView } from "../../common/categories/views/types";
 import { CategoryValueKey, SelectCategory, SelectedFilter } from "../../common/entities";
 import { RowPreviewState } from "../../components/Table/features/RowPreview/entities";
 import { CategoryGroup, CategoryGroupConfig, EntityPath, SavedFilter } from "../../config/entities";
-import { META_COMMAND } from "./hooks/UseMetaCommands/types";
+import { META_COMMAND } from "../exploreStateSync/hooks/UseMetaCommands/types";
 export interface EntityPageState {
     categoryGroupConfigKey: CategoryGroupConfigKey;
     columnVisibility: VisibilityState;

package/lib/providers/exploreState.js

@@ -8,11 +8,10 @@ import { syncStateFromUrlAction } from "./exploreState/actions/syncStateFromUrl/
 import { updateGroupingAction } from "./exploreState/actions/updateGrouping/action";
 import { updateColumnVisibilityAction } from "./exploreState/actions/updateVisibility/action";
 import { useBeforePopState } from "./exploreState/hooks/UseBeforePopState/useBeforePopState";
-import { META_COMMAND } from "./exploreState/hooks/UseMetaCommands/types";
-import { useMetaCommands } from "./exploreState/hooks/UseMetaCommands/useMetaCommands";
 import { DEFAULT_PAGINATION_STATE, INITIAL_STATE, } from "./exploreState/initializer/constants";
 import { initReducerArguments } from "./exploreState/initializer/utils";
 import { buildEntityStateSavedFilterState, buildNextSavedFilterState, closeRowPreview, getEntityCategoryGroupConfigKey, getEntityState, getEntityStateSavedProperty, getFilterCount, patchEntityListItems, resetPage, updateEntityPageState, updateEntityPageStateWithCommonCategoryGroupConfigKey, updateEntityStateByCategoryGroupConfigKey, updateSelectColumnVisibility, } from "./exploreState/utils";
+import { META_COMMAND } from "./exploreStateSync/hooks/UseMetaCommands/types";
 /**
  * Explore state context for storing and using filter-related and explore state.
  */
@@ -56,8 +55,6 @@ export function ExploreStateProvider({ children, entityListType, }) {
             type: ExploreActionKind.ResetExploreResponse,
         });
     }, [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 (React.createElement(ExploreStateContext.Provider, { value: exploreContextValue }, children));
@@ -118,7 +115,7 @@ function exploreReducer(state, action, exploreContext) {
                 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,
             };
@@ -141,7 +138,7 @@ function exploreReducer(state, action, exploreContext) {
                 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,
             };
@@ -233,8 +230,11 @@ function exploreReducer(state, action, exploreContext) {
          **/
         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 } };
+                // Update meta to match command "STATE_TO_URL_REPLACE" - facilitates navigation to filters on return back to entity from elsewhere.
+                return {
+                    ...state,
+                    meta: { command: META_COMMAND.STATE_TO_URL_REPLACE },
+                };
             }
             const entityState = getEntityState(state, getEntityCategoryGroupConfigKey(payload, state.entityPageState));
             const rowPreview = closeRowPreview(state.rowPreview); // Close row preview, without updating the entity page state row preview.
@@ -246,7 +246,7 @@ function exploreReducer(state, action, exploreContext) {
                 filterState: entityState.filterState,
                 listItems: [],
                 loading: true,
-                meta: { command: META_COMMAND.REPLACE_TO_FILTERS },
+                meta: { command: META_COMMAND.STATE_TO_URL_REPLACE },
                 paginationState: { ...resetPage(state.paginationState), rows: 0 },
                 rowPreview,
                 tabValue: payload,
@@ -324,7 +324,7 @@ function exploreReducer(state, action, exploreContext) {
                 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,
             };

package/lib/providers/exploreStateSync/hooks/UseMetaCommands/handlers.d.ts

@@ -0,0 +1,10 @@
+import { NextRouter } from "next/router";
+import { ExploreQueryState } from "./types";
+/**
+ * Updates the URL query parameters based on state.
+ * Pushes or replaces the query to the router.
+ * @param state - State -- partial explore state.
+ * @param currentQuery - Query -- current.
+ * @param method - "push" or "replace".
+ */
+export declare function updateUrlFromState(state: ExploreQueryState, currentQuery: NextRouter["query"], method?: "push" | "replace"): void;

package/lib/providers/exploreStateSync/hooks/UseMetaCommands/handlers.js

@@ -0,0 +1,18 @@
+import Router from "next/router";
+import { buildQuery, stringifyQuery } from "./utils";
+/**
+ * Updates the URL query parameters based on state.
+ * Pushes or replaces the query to the router.
+ * @param state - State -- partial explore state.
+ * @param currentQuery - Query -- current.
+ * @param method - "push" or "replace".
+ */
+export function updateUrlFromState(state, currentQuery, method = "push") {
+    // Build the next query.
+    const query = buildQuery(state);
+    // Do nothing if the next query is the same as the current query.
+    if (stringifyQuery(query) === stringifyQuery(currentQuery))
+        return;
+    // Push or replace the query to the router.
+    Router[method]({ query }, undefined, { shallow: true });
+}

package/lib/providers/exploreStateSync/hooks/UseMetaCommands/hook.d.ts

@@ -0,0 +1 @@
+export declare const useMetaCommands: () => void;

package/lib/providers/exploreStateSync/hooks/UseMetaCommands/hook.js

@@ -0,0 +1,33 @@
+import { useRouter } from "next/router";
+import { useEffect, useMemo } from "react";
+import { useExploreState } from "../../../../hooks/useExploreState";
+import { clearMeta } from "../../../exploreState/actions/clearMeta/dispatch";
+import { updateUrlFromState } from "./handlers";
+import { META_COMMAND } from "./types";
+import { getQueryState } from "./utils";
+export const useMetaCommands = () => {
+    const { exploreDispatch, exploreState } = useExploreState();
+    // Router must be ready before executing any meta-command side effects.
+    const { isReady, query } = useRouter();
+    // Command.
+    const command = exploreState.meta?.command;
+    // Extract relevant state to update URL.
+    const state = useMemo(() => getQueryState(exploreState), [exploreState]);
+    useEffect(() => {
+        // Do nothing if the router is not ready.
+        if (!isReady)
+            return;
+        switch (command) {
+            case META_COMMAND.STATE_TO_URL_PUSH:
+                updateUrlFromState(state, query);
+                exploreDispatch(clearMeta());
+                break;
+            case META_COMMAND.STATE_TO_URL_REPLACE:
+                updateUrlFromState(state, query, "replace");
+                exploreDispatch(clearMeta());
+                break;
+            default:
+                break;
+        }
+    }, [command, exploreDispatch, isReady, query, state]);
+};

package/lib/providers/exploreStateSync/hooks/UseMetaCommands/types.d.ts

@@ -0,0 +1,11 @@
+import { ExploreState } from "../../../exploreState";
+export interface ExploreQueryState {
+    catalog: ExploreState["catalogState"];
+    entityListType: ExploreState["tabValue"];
+    ff: ExploreState["featureFlagState"];
+    filter: ExploreState["filterState"];
+}
+export declare enum META_COMMAND {
+    STATE_TO_URL_PUSH = "STATE_TO_URL_PUSH",
+    STATE_TO_URL_REPLACE = "STATE_TO_URL_REPLACE"
+}

package/lib/providers/exploreStateSync/hooks/UseMetaCommands/types.js

@@ -0,0 +1,5 @@
+export var META_COMMAND;
+(function (META_COMMAND) {
+    META_COMMAND["STATE_TO_URL_PUSH"] = "STATE_TO_URL_PUSH";
+    META_COMMAND["STATE_TO_URL_REPLACE"] = "STATE_TO_URL_REPLACE";
+})(META_COMMAND || (META_COMMAND = {}));

package/lib/providers/exploreStateSync/hooks/UseMetaCommands/utils.d.ts

@@ -0,0 +1,34 @@
+import { NextRouter } from "next/router";
+import { ExploreState } from "../../../exploreState";
+import { ExploreQueryState } from "./types";
+/**
+ * Builds a query object from state.
+ * State values are expected to be undefined, string, or an array.
+ * Undefined values and empty arrays are not included in the query.
+ * @param state - State -- partial explore state.
+ * @returns A query object.
+ */
+export declare function buildQuery(state: ExploreQueryState): NextRouter["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: Current active tab value (string)
+ * - ff: Feature flag state (string | undefined)
+ * - filter: Applied filters (SelectedFilter[])
+ *
+ * @param exploreState - Explore state.
+ * @returns Subset of state used for URL query parameters.
+ */
+export declare function getQueryState(exploreState: ExploreState): ExploreQueryState;
+/**
+ * Returns a sorted string representation of a query object.
+ * @param query - Query object.
+ * @returns Sorted string representation of the query object.
+ */
+export declare function stringifyQuery(query: NextRouter["query"]): string;

package/lib/providers/exploreStateSync/hooks/UseMetaCommands/utils.js

@@ -0,0 +1,59 @@
+/**
+ * Builds a query object from state.
+ * State values are expected to be undefined, string, or an array.
+ * Undefined values and empty arrays are not included in the query.
+ * @param state - State -- partial explore state.
+ * @returns A query object.
+ */
+export function buildQuery(state) {
+    const query = {};
+    for (const [key, value] of Object.entries(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: Current active tab value (string)
+ * - ff: Feature flag state (string | undefined)
+ * - filter: Applied filters (SelectedFilter[])
+ *
+ * @param exploreState - Explore state.
+ * @returns Subset of state used for URL query parameters.
+ */
+export function getQueryState(exploreState) {
+    return {
+        catalog: exploreState.catalogState,
+        entityListType: exploreState.tabValue,
+        ff: exploreState.featureFlagState,
+        filter: exploreState.filterState,
+    };
+}
+/**
+ * Returns a sorted string representation of a query object.
+ * @param query - Query object.
+ * @returns Sorted string representation of the query object.
+ */
+export function stringifyQuery(query) {
+    return JSON.stringify(Object.keys(query)
+        .sort()
+        .reduce((acc, key) => ({ ...acc, [key]: query[key] }), {}));
+}

package/lib/providers/exploreStateSync/provider.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from "react";
+/**
+ * Synchronizes the ExploreView component's state with the Next.js URL.
+ *
+ * Listens for reducer meta-commands (`STATE_TO_URL_PUSH`/`STATE_TO_URL_REPLACE`)
+ * and updates the URL accordingly using router methods.
+ *
+ * Usage:
+ * ```tsx
+ * <ExploreStateProvider>
+ *   <ExploreStateSyncProvider>
+ *     <ExploreView />
+ *   </ExploreStateSyncProvider>
+ * </ExploreStateProvider>
+ * ```
+ */
+export declare function ExploreStateSyncProvider({ children, }: {
+    children: ReactNode;
+}): JSX.Element;

package/lib/providers/exploreStateSync/provider.js

@@ -0,0 +1,22 @@
+import React from "react";
+import { useMetaCommands } from "./hooks/UseMetaCommands/hook";
+/**
+ * Synchronizes the ExploreView component's state with the Next.js URL.
+ *
+ * Listens for reducer meta-commands (`STATE_TO_URL_PUSH`/`STATE_TO_URL_REPLACE`)
+ * and updates the URL accordingly using router methods.
+ *
+ * Usage:
+ * ```tsx
+ * <ExploreStateProvider>
+ *   <ExploreStateSyncProvider>
+ *     <ExploreView />
+ *   </ExploreStateSyncProvider>
+ * </ExploreStateProvider>
+ * ```
+ */
+export function ExploreStateSyncProvider({ children, }) {
+    // Meta-command related side effects.
+    useMetaCommands();
+    return React.createElement(React.Fragment, null, children);
+}

package/lib/views/ExploreView/exploreView.js

@@ -18,6 +18,7 @@ import { useExploreState } from "../../hooks/useExploreState";
 import { useSummary } from "../../hooks/useSummary";
 import { ExploreActionKind } from "../../providers/exploreState";
 import { SELECT_CATEGORY_KEY } from "../../providers/exploreState/constants";
+import { ExploreStateSyncProvider } from "../../providers/exploreStateSync/provider";
 import { TEST_IDS } from "../../tests/testIds";
 import { DESKTOP_SM } from "../../theme/common/breakpoints";
 export const ExploreView = (props) => {
@@ -98,7 +99,7 @@ export const ExploreView = (props) => {
             });
         }
     }, [entityListType, exploreDispatch]);
-    return (React.createElement(React.Fragment, null,
+    return (React.createElement(ExploreStateSyncProvider, null,
         categoryViews && !!categoryViews.length && (React.createElement(Sidebar, { drawerOpen: isDrawerOpen, onDrawerClose: onCloseDrawer },
             React.createElement(SidebarTools, { "data-testid": TEST_IDS.FILTER_CONTROLS },
                 React.createElement(SidebarLabel, { label: "Filters" }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databiosphere/findable-ui",
-  "version": "34.0.0",
+  "version": "34.1.0",
   "description": "",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",

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 "../exploreStateSync/hooks/UseMetaCommands/types";
 
 export interface EntityPageState {
   categoryGroupConfigKey: CategoryGroupConfigKey;

package/src/providers/exploreState.tsx

@@ -35,8 +35,6 @@ import {
   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 {
   DEFAULT_PAGINATION_STATE,
   INITIAL_STATE,
@@ -70,6 +68,7 @@ import {
   updateEntityStateByCategoryGroupConfigKey,
   updateSelectColumnVisibility,
 } from "./exploreState/utils";
+import { META_COMMAND } from "./exploreStateSync/hooks/UseMetaCommands/types";
 
 export type CatalogState = string | undefined;
 
@@ -215,9 +214,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 });
 
@@ -445,7 +441,7 @@ function exploreReducer(
         ),
         filterCount: getFilterCount(filterState),
         filterState,
-        meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_PUSH },
         paginationState: resetPage(state.paginationState),
         rowPreview,
       };
@@ -471,7 +467,7 @@ function exploreReducer(
         ),
         filterCount,
         filterState,
-        meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_PUSH },
         paginationState: resetPage(state.paginationState),
         rowPreview,
       };
@@ -578,8 +574,11 @@ 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 } };
+        // Update meta to match command "STATE_TO_URL_REPLACE" - facilitates navigation to filters on return back to entity from elsewhere.
+        return {
+          ...state,
+          meta: { command: META_COMMAND.STATE_TO_URL_REPLACE },
+        };
       }
       const entityState = getEntityState(
         state,
@@ -594,7 +593,7 @@ function exploreReducer(
         filterState: entityState.filterState,
         listItems: [],
         loading: true,
-        meta: { command: META_COMMAND.REPLACE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_REPLACE },
         paginationState: { ...resetPage(state.paginationState), rows: 0 },
         rowPreview,
         tabValue: payload,
@@ -699,7 +698,7 @@ function exploreReducer(
         ),
         filterCount: getFilterCount(filterState),
         filterState,
-        meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_PUSH },
         paginationState: resetPage(state.paginationState),
         rowPreview,
       };

package/src/providers/exploreStateSync/hooks/UseMetaCommands/handlers.ts

@@ -0,0 +1,25 @@
+import Router, { NextRouter } from "next/router";
+import { ExploreQueryState } from "./types";
+import { buildQuery, stringifyQuery } from "./utils";
+
+/**
+ * Updates the URL query parameters based on state.
+ * Pushes or replaces the query to the router.
+ * @param state - State -- partial explore state.
+ * @param currentQuery - Query -- current.
+ * @param method - "push" or "replace".
+ */
+export function updateUrlFromState(
+  state: ExploreQueryState,
+  currentQuery: NextRouter["query"],
+  method: "push" | "replace" = "push"
+): void {
+  // Build the next query.
+  const query = buildQuery(state);
+
+  // Do nothing if the next query is the same as the current query.
+  if (stringifyQuery(query) === stringifyQuery(currentQuery)) return;
+
+  // Push or replace the query to the router.
+  Router[method]({ query }, undefined, { shallow: true });
+}

package/src/providers/exploreStateSync/hooks/UseMetaCommands/hook.ts

@@ -0,0 +1,38 @@
+import { useRouter } from "next/router";
+import { useEffect, useMemo } from "react";
+import { useExploreState } from "../../../../hooks/useExploreState";
+import { clearMeta } from "../../../exploreState/actions/clearMeta/dispatch";
+import { updateUrlFromState } from "./handlers";
+import { META_COMMAND } from "./types";
+import { getQueryState } from "./utils";
+
+export const useMetaCommands = (): void => {
+  const { exploreDispatch, exploreState } = useExploreState();
+
+  // Router must be ready before executing any meta-command side effects.
+  const { isReady, query } = useRouter();
+
+  // Command.
+  const command = exploreState.meta?.command;
+
+  // Extract relevant state to update URL.
+  const state = useMemo(() => getQueryState(exploreState), [exploreState]);
+
+  useEffect(() => {
+    // Do nothing if the router is not ready.
+    if (!isReady) return;
+
+    switch (command) {
+      case META_COMMAND.STATE_TO_URL_PUSH:
+        updateUrlFromState(state, query);
+        exploreDispatch(clearMeta());
+        break;
+      case META_COMMAND.STATE_TO_URL_REPLACE:
+        updateUrlFromState(state, query, "replace");
+        exploreDispatch(clearMeta());
+        break;
+      default:
+        break;
+    }
+  }, [command, exploreDispatch, isReady, query, state]);
+};

package/src/providers/exploreStateSync/hooks/UseMetaCommands/types.ts

@@ -0,0 +1,13 @@
+import { ExploreState } from "../../../exploreState";
+
+export interface ExploreQueryState {
+  catalog: ExploreState["catalogState"];
+  entityListType: ExploreState["tabValue"];
+  ff: ExploreState["featureFlagState"];
+  filter: ExploreState["filterState"];
+}
+
+export enum META_COMMAND {
+  STATE_TO_URL_PUSH = "STATE_TO_URL_PUSH",
+  STATE_TO_URL_REPLACE = "STATE_TO_URL_REPLACE",
+}

package/src/providers/exploreStateSync/hooks/UseMetaCommands/utils.ts

@@ -0,0 +1,69 @@
+import { NextRouter } from "next/router";
+import { ExploreState } from "../../../exploreState";
+import { ExploreQueryState } from "./types";
+
+/**
+ * Builds a query object from state.
+ * State values are expected to be undefined, string, or an array.
+ * Undefined values and empty arrays are not included in the query.
+ * @param state - State -- partial explore state.
+ * @returns A query object.
+ */
+export function buildQuery(state: ExploreQueryState): NextRouter["query"] {
+  const query: NextRouter["query"] = {};
+
+  for (const [key, value] of Object.entries(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: Current active tab value (string)
+ * - ff: Feature flag state (string | undefined)
+ * - filter: Applied filters (SelectedFilter[])
+ *
+ * @param exploreState - Explore state.
+ * @returns Subset of state used for URL query parameters.
+ */
+export function getQueryState(exploreState: ExploreState): ExploreQueryState {
+  return {
+    catalog: exploreState.catalogState,
+    entityListType: exploreState.tabValue,
+    ff: exploreState.featureFlagState,
+    filter: exploreState.filterState,
+  };
+}
+
+/**
+ * Returns a sorted string representation of a query object.
+ * @param query - Query object.
+ * @returns Sorted string representation of the query object.
+ */
+export function stringifyQuery(query: NextRouter["query"]): string {
+  return JSON.stringify(
+    Object.keys(query)
+      .sort()
+      .reduce((acc, key) => ({ ...acc, [key]: query[key] }), {})
+  );
+}

package/src/providers/exploreStateSync/provider.tsx

@@ -0,0 +1,29 @@
+import React, { ReactNode } from "react";
+import { useMetaCommands } from "./hooks/UseMetaCommands/hook";
+
+/**
+ * Synchronizes the ExploreView component's state with the Next.js URL.
+ *
+ * Listens for reducer meta-commands (`STATE_TO_URL_PUSH`/`STATE_TO_URL_REPLACE`)
+ * and updates the URL accordingly using router methods.
+ *
+ * Usage:
+ * ```tsx
+ * <ExploreStateProvider>
+ *   <ExploreStateSyncProvider>
+ *     <ExploreView />
+ *   </ExploreStateSyncProvider>
+ * </ExploreStateProvider>
+ * ```
+ */
+
+export function ExploreStateSyncProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  // Meta-command related side effects.
+  useMetaCommands();
+
+  return <>{children}</>;
+}

package/src/views/ExploreView/exploreView.tsx

@@ -35,6 +35,7 @@ import { useExploreState } from "../../hooks/useExploreState";
 import { useSummary } from "../../hooks/useSummary";
 import { ExploreActionKind } from "../../providers/exploreState";
 import { SELECT_CATEGORY_KEY } from "../../providers/exploreState/constants";
+import { ExploreStateSyncProvider } from "../../providers/exploreStateSync/provider";
 import { TEST_IDS } from "../../tests/testIds";
 import { DESKTOP_SM } from "../../theme/common/breakpoints";
 
@@ -141,7 +142,7 @@ export const ExploreView = (props: ExploreViewProps): JSX.Element => {
   }, [entityListType, exploreDispatch]);
 
   return (
-    <>
+    <ExploreStateSyncProvider>
       {categoryViews && !!categoryViews.length && (
         <Sidebar drawerOpen={isDrawerOpen} onDrawerClose={onCloseDrawer}>
           <SidebarTools data-testid={TEST_IDS.FILTER_CONTROLS}>
@@ -182,7 +183,7 @@ export const ExploreView = (props: ExploreViewProps): JSX.Element => {
         Tabs={<Tabs />}
         title={entityConfig.explorerTitle || explorerTitle}
       />
-    </>
+    </ExploreStateSyncProvider>
   );
 };
 

package/lib/providers/exploreState/hooks/UseMetaCommands/actions.d.ts

@@ -1,13 +0,0 @@
-import { ExploreState } from "../../../exploreState";
-/**
- * Updates the URL query parameters for the entity list page based on the current explore state.
- * Pushes the query to the router.
- * @param exploreState - The current explore state.
- */
-export declare function navigateToFilters(exploreState: ExploreState): void;
-/**
- * Updates the URL query parameters for the entity list page based on the current explore state.
- * Replaces the query to the router.
- * @param exploreState - The current explore state.
- */
-export declare function replaceToFilters(exploreState: ExploreState): void;

package/lib/providers/exploreState/hooks/UseMetaCommands/actions.js

@@ -1,24 +0,0 @@
-import Router from "next/router";
-import { buildQuery } from "./utils";
-/**
- * Updates the URL query parameters for the entity list page based on the current explore state.
- * Pushes the query to the router.
- * @param exploreState - The current explore state.
- */
-export function navigateToFilters(exploreState) {
-    // Build the query object.
-    const query = buildQuery(exploreState);
-    // Push the query to the router.
-    Router.push({ query }, undefined, { shallow: true });
-}
-/**
- * Updates the URL query parameters for the entity list page based on the current explore state.
- * Replaces the query to the router.
- * @param exploreState - The current explore state.
- */
-export function replaceToFilters(exploreState) {
-    // Build the query object.
-    const query = buildQuery(exploreState);
-    // Replace the query to the router.
-    Router.replace({ query }, undefined, { shallow: true });
-}

package/lib/providers/exploreState/hooks/UseMetaCommands/types.d.ts

@@ -1,4 +0,0 @@
-export declare enum META_COMMAND {
-    NAVIGATE_TO_FILTERS = "NAVIGATE_TO_FILTERS",
-    REPLACE_TO_FILTERS = "REPLACE_TO_FILTERS"
-}

package/lib/providers/exploreState/hooks/UseMetaCommands/types.js

@@ -1,5 +0,0 @@
-export var META_COMMAND;
-(function (META_COMMAND) {
-    META_COMMAND["NAVIGATE_TO_FILTERS"] = "NAVIGATE_TO_FILTERS";
-    META_COMMAND["REPLACE_TO_FILTERS"] = "REPLACE_TO_FILTERS";
-})(META_COMMAND || (META_COMMAND = {}));

package/lib/providers/exploreState/hooks/UseMetaCommands/useMetaCommands.d.ts

@@ -1,2 +0,0 @@
-import { ExploreStateContextProps } from "../../../exploreState";
-export declare const useMetaCommands: ({ exploreDispatch, exploreState, }: ExploreStateContextProps) => void;

package/lib/providers/exploreState/hooks/UseMetaCommands/useMetaCommands.js

@@ -1,21 +0,0 @@
-import { useEffect } from "react";
-import { clearMeta } from "../../actions/clearMeta/dispatch";
-import { navigateToFilters, replaceToFilters } from "./actions";
-import { META_COMMAND } from "./types";
-export const useMetaCommands = ({ exploreDispatch, exploreState, }) => {
-    useEffect(() => {
-        const command = exploreState.meta?.command;
-        switch (command) {
-            case META_COMMAND.NAVIGATE_TO_FILTERS:
-                navigateToFilters(exploreState);
-                exploreDispatch(clearMeta());
-                break;
-            case META_COMMAND.REPLACE_TO_FILTERS:
-                replaceToFilters(exploreState);
-                exploreDispatch(clearMeta());
-                break;
-            default:
-                break;
-        }
-    }, [exploreDispatch, exploreState]);
-};

package/lib/providers/exploreState/hooks/UseMetaCommands/utils.d.ts

@@ -1,9 +0,0 @@
-import { UrlObject } from "url";
-import { ExploreState } from "../../../exploreState";
-/**
- * Builds a query object from the current explore state.
- * Contains catalog, feature flag, filter, and entity list type.
- * @param exploreState - The current explore state.
- * @returns A query object.
- */
-export declare function buildQuery(exploreState: ExploreState): UrlObject["query"];

package/lib/providers/exploreState/hooks/UseMetaCommands/utils.js

@@ -1,25 +0,0 @@
-import { EXPLORE_URL_PARAMS } from "../../../exploreState/constants";
-/**
- * Builds a query object from the current explore state.
- * Contains catalog, feature flag, filter, and entity list type.
- * @param exploreState - The current explore state.
- * @returns A query object.
- */
-export function buildQuery(exploreState) {
-    const query = {};
-    // Entity list type.
-    query["entityListType"] = exploreState.tabValue;
-    // Filter state.
-    if (exploreState.filterState.length > 0) {
-        query[EXPLORE_URL_PARAMS.FILTER] = JSON.stringify(exploreState.filterState);
-    }
-    // Catalog state.
-    if (exploreState.catalogState) {
-        query[EXPLORE_URL_PARAMS.CATALOG] = exploreState.catalogState;
-    }
-    // Feature flag state.
-    if (exploreState.featureFlagState) {
-        query[EXPLORE_URL_PARAMS.FEATURE_FLAG] = exploreState.featureFlagState;
-    }
-    return query;
-}

package/src/providers/exploreState/hooks/UseMetaCommands/actions.ts

@@ -1,29 +0,0 @@
-import Router from "next/router";
-import { ExploreState } from "../../../exploreState";
-import { buildQuery } from "./utils";
-
-/**
- * Updates the URL query parameters for the entity list page based on the current explore state.
- * Pushes the query to the router.
- * @param exploreState - The current explore state.
- */
-export function navigateToFilters(exploreState: ExploreState): void {
-  // Build the query object.
-  const query = buildQuery(exploreState);
-
-  // Push the query to the router.
-  Router.push({ query }, undefined, { shallow: true });
-}
-
-/**
- * Updates the URL query parameters for the entity list page based on the current explore state.
- * Replaces the query to the router.
- * @param exploreState - The current explore state.
- */
-export function replaceToFilters(exploreState: ExploreState): void {
-  // Build the query object.
-  const query = buildQuery(exploreState);
-
-  // Replace the query to the router.
-  Router.replace({ query }, undefined, { shallow: true });
-}

package/src/providers/exploreState/hooks/UseMetaCommands/types.ts

@@ -1,4 +0,0 @@
-export enum META_COMMAND {
-  NAVIGATE_TO_FILTERS = "NAVIGATE_TO_FILTERS",
-  REPLACE_TO_FILTERS = "REPLACE_TO_FILTERS",
-}

package/src/providers/exploreState/hooks/UseMetaCommands/useMetaCommands.ts

@@ -1,27 +0,0 @@
-import { useEffect } from "react";
-import { ExploreStateContextProps } from "../../../exploreState";
-import { clearMeta } from "../../actions/clearMeta/dispatch";
-import { navigateToFilters, replaceToFilters } from "./actions";
-import { META_COMMAND } from "./types";
-
-export const useMetaCommands = ({
-  exploreDispatch,
-  exploreState,
-}: ExploreStateContextProps): void => {
-  useEffect(() => {
-    const command = exploreState.meta?.command;
-
-    switch (command) {
-      case META_COMMAND.NAVIGATE_TO_FILTERS:
-        navigateToFilters(exploreState);
-        exploreDispatch(clearMeta());
-        break;
-      case META_COMMAND.REPLACE_TO_FILTERS:
-        replaceToFilters(exploreState);
-        exploreDispatch(clearMeta());
-        break;
-      default:
-        break;
-    }
-  }, [exploreDispatch, exploreState]);
-};

package/src/providers/exploreState/hooks/UseMetaCommands/utils.ts

@@ -1,33 +0,0 @@
-import { UrlObject } from "url";
-import { ExploreState } from "../../../exploreState";
-import { EXPLORE_URL_PARAMS } from "../../../exploreState/constants";
-
-/**
- * Builds a query object from the current explore state.
- * Contains catalog, feature flag, filter, and entity list type.
- * @param exploreState - The current explore state.
- * @returns A query object.
- */
-export function buildQuery(exploreState: ExploreState): UrlObject["query"] {
-  const query: UrlObject["query"] = {};
-
-  // Entity list type.
-  query["entityListType"] = exploreState.tabValue;
-
-  // Filter state.
-  if (exploreState.filterState.length > 0) {
-    query[EXPLORE_URL_PARAMS.FILTER] = JSON.stringify(exploreState.filterState);
-  }
-
-  // Catalog state.
-  if (exploreState.catalogState) {
-    query[EXPLORE_URL_PARAMS.CATALOG] = exploreState.catalogState;
-  }
-
-  // Feature flag state.
-  if (exploreState.featureFlagState) {
-    query[EXPLORE_URL_PARAMS.FEATURE_FLAG] = exploreState.featureFlagState;
-  }
-
-  return query;
-}