@databiosphere/findable-ui 32.0.0 → 32.1.0

package/lib/providers/exploreState.d.ts

@@ -4,9 +4,11 @@ import { CategoryView } from "../common/categories/views/types";
 import { SelectedFilter } from "../common/entities";
 import { RowPreviewState } from "../components/Table/features/RowPreview/entities";
 import { CategoryGroup, SiteConfig } from "../config/entities";
+import { ClearMetaAction } from "./exploreState/actions/clearMeta/types";
+import { SyncStateFromUrlAction } from "./exploreState/actions/syncStateFromUrl/types";
 import { UpdateGroupingAction } from "./exploreState/actions/updateGrouping/types";
 import { UpdateColumnVisibilityAction } from "./exploreState/actions/updateVisibility/types";
-import { EntityPageStateMapper, EntityStateByCategoryGroupConfigKey, ListItem } from "./exploreState/entities";
+import { EntityPageStateMapper, EntityStateByCategoryGroupConfigKey, ListItem, Meta } from "./exploreState/entities";
 import { ApplySavedFilterPayload, PaginateTablePayload, PatchExploreResponsePayload, ProcessExploreResponsePayload, ResetExploreResponsePayload, UpdateEntityFiltersPayload, UpdateEntityViewAccessPayload, UpdateFilterPayload, UpdateRowPreviewPayload, UpdateRowSelectionPayload, UpdateSortingPayload } from "./exploreState/payloads/entities";
 export type CatalogState = string | undefined;
 /**
@@ -30,6 +32,7 @@ export type ExploreState = {
     filterState: SelectedFilter[];
     listItems: ListItems;
     loading: boolean;
+    meta: Meta | null;
     paginationState: PaginationState;
     rowPreview: RowPreviewState;
     tabValue: string;
@@ -96,12 +99,14 @@ export declare function ExploreStateProvider({ children, entityListType, }: {
 export declare enum ExploreActionKind {
     ApplySavedFilter = "APPLY_SAVED_FILTER",
     ClearFilters = "CLEAR_FILTERS",
+    ClearMeta = "CLEAR_META",
     PaginateTable = "PAGINATE_TABLE",
     PatchExploreResponse = "PATCH_EXPLORE_RESPONSE",
     ProcessExploreResponse = "PROCESS_EXPLORE_RESPONSE",
     ResetExploreResponse = "RESET_EXPLORE_RESPONSE",
     ResetState = "RESET_STATE",
     SelectEntityType = "SELECT_ENTITY_TYPE",
+    SyncStateFromUrl = "SYNC_STATE_FROM_URL",
     UpdateColumnVisibility = "UPDATE_COLUMN_VISIBILITY",
     UpdateEntityFilters = "UPDATE_ENTITY_FILTERS",
     UpdateEntityViewAccess = "UPDATE_ENTITY_VIEW_ACCESS",
@@ -114,7 +119,7 @@ export declare enum ExploreActionKind {
 /**
  * Explore action.
  */
-export type ExploreAction = ApplySavedFilterAction | ClearFiltersAction | PaginateTableAction | PatchExploreResponseAction | ProcessExploreResponseAction | ResetExploreResponseAction | ResetStateAction | SelectEntityTypeAction | UpdateColumnVisibilityAction | UpdateEntityFiltersAction | UpdateEntityViewAccessAction | UpdateFilterAction | UpdateGroupingAction | UpdateRowPreviewAction | UpdateRowSelectionAction | UpdateSortingAction;
+export type ExploreAction = ApplySavedFilterAction | ClearFiltersAction | ClearMetaAction | PaginateTableAction | PatchExploreResponseAction | ProcessExploreResponseAction | ResetExploreResponseAction | ResetStateAction | SelectEntityTypeAction | SyncStateFromUrlAction | UpdateColumnVisibilityAction | UpdateEntityFiltersAction | UpdateEntityViewAccessAction | UpdateFilterAction | UpdateGroupingAction | UpdateRowPreviewAction | UpdateRowSelectionAction | UpdateSortingAction;
 /**
  * Apply saved filter action.
  */

package/lib/providers/exploreState.js

@@ -3,8 +3,13 @@ import { useToken } from "../hooks/authentication/token/useToken";
 import { buildCategoryViews, buildNextFilterState, } from "../hooks/useCategoryFilter";
 import { useConfig } from "../hooks/useConfig";
 import { useURLFilterParams } from "../hooks/useURLFilterParams";
+import { clearMetaAction } from "./exploreState/actions/clearMeta/action";
+import { syncStateFromUrlAction } from "./exploreState/actions/syncStateFromUrl/action";
 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";
@@ -51,6 +56,10 @@ 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));
 }
 /**
@@ -60,12 +69,14 @@ export var ExploreActionKind;
 (function (ExploreActionKind) {
     ExploreActionKind["ApplySavedFilter"] = "APPLY_SAVED_FILTER";
     ExploreActionKind["ClearFilters"] = "CLEAR_FILTERS";
+    ExploreActionKind["ClearMeta"] = "CLEAR_META";
     ExploreActionKind["PaginateTable"] = "PAGINATE_TABLE";
     ExploreActionKind["PatchExploreResponse"] = "PATCH_EXPLORE_RESPONSE";
     ExploreActionKind["ProcessExploreResponse"] = "PROCESS_EXPLORE_RESPONSE";
     ExploreActionKind["ResetExploreResponse"] = "RESET_EXPLORE_RESPONSE";
     ExploreActionKind["ResetState"] = "RESET_STATE";
     ExploreActionKind["SelectEntityType"] = "SELECT_ENTITY_TYPE";
+    ExploreActionKind["SyncStateFromUrl"] = "SYNC_STATE_FROM_URL";
     ExploreActionKind["UpdateColumnVisibility"] = "UPDATE_COLUMN_VISIBILITY";
     ExploreActionKind["UpdateEntityFilters"] = "UPDATE_ENTITY_FILTERS";
     ExploreActionKind["UpdateEntityViewAccess"] = "UPDATE_ENTITY_VIEW_ACCESS";
@@ -107,6 +118,7 @@ function exploreReducer(state, action, exploreContext) {
                 entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(state, { grouping, rowPreview, rowSelection, sorting }),
                 filterCount: getFilterCount(filterState),
                 filterState,
+                meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
                 paginationState: resetPage(state.paginationState),
                 rowPreview,
             };
@@ -129,10 +141,17 @@ function exploreReducer(state, action, exploreContext) {
                 entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(state, { rowPreview, rowSelection }),
                 filterCount,
                 filterState,
+                meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
                 paginationState: resetPage(state.paginationState),
                 rowPreview,
             };
         }
+        /**
+         * Clear meta
+         */
+        case ExploreActionKind.ClearMeta: {
+            return clearMetaAction(state, payload);
+        }
         /**
          * Paginate table
          **/
@@ -214,7 +233,8 @@ function exploreReducer(state, action, exploreContext) {
          **/
         case ExploreActionKind.SelectEntityType: {
             if (payload === state.tabValue) {
-                return state;
+                // 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 } };
             }
             const entityState = getEntityState(state, getEntityCategoryGroupConfigKey(payload, state.entityPageState));
             const rowPreview = closeRowPreview(state.rowPreview); // Close row preview, without updating the entity page state row preview.
@@ -226,11 +246,18 @@ function exploreReducer(state, action, exploreContext) {
                 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.
+         */
+        case ExploreActionKind.SyncStateFromUrl: {
+            return syncStateFromUrlAction(state, payload);
+        }
         /**
          * Update column visibility
          **/
@@ -262,6 +289,13 @@ function exploreReducer(state, action, exploreContext) {
                 ...state,
                 entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(state, { grouping, rowPreview, rowSelection, sorting }, categoryGroupConfigKey),
                 rowPreview: closeRowPreview(state.rowPreview),
+                ...(payload.entityListType === state.tabValue
+                    ? {
+                        filterCount: getFilterCount(filterState),
+                        filterState,
+                        paginationState: { ...resetPage(state.paginationState), rows: 0 },
+                    }
+                    : {}),
             };
         }
         /**
@@ -290,6 +324,7 @@ function exploreReducer(state, action, exploreContext) {
                 entityPageState: updateEntityPageStateWithCommonCategoryGroupConfigKey(state, { rowPreview, rowSelection }),
                 filterCount: getFilterCount(filterState),
                 filterState,
+                meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
                 paginationState: resetPage(state.paginationState),
                 rowPreview,
             };

package/package.json

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

package/src/components/Index/index.tsx

@@ -25,7 +25,7 @@ export const Index = ({
 }: IndexProps): JSX.Element => {
   const { onChange, viewMode, viewStatus } = useEntitiesView();
   const { dimensions } = useLayoutDimensions();
-  const { table } = useTable();
+  const { table } = useTable({ entityListType });
   return (
     <IndexLayout className={className} marginTop={dimensions.header.height}>
       <Hero SideBarButton={SideBarButton} Summaries={Summaries} title={title} />

package/src/components/Index/table/hook.ts

@@ -40,10 +40,12 @@ import { RowPreviewState } from "../../Table/features/RowPreview/entities";
 import { buildBaseColumnDef } from "../../TableCreator/common/utils";
 import { useTableOptions } from "../../TableCreator/options/hook";
 import { createCell } from "./coreOptions/columns/cellFactory";
-import { UseTable } from "./types";
+import { UseTable, UseTableProps } from "./types";
 
-// eslint-disable-next-line sonarjs/cognitive-complexity -- TODO fix component length / complexity
-export const useTable = <T extends RowData>(): UseTable<T> => {
+export const useTable = <T extends RowData>({
+  entityListType,
+}: // eslint-disable-next-line sonarjs/cognitive-complexity -- TODO fix complexity
+UseTableProps): UseTable<T> => {
   const { entityConfig } = useConfig();
   const exploreMode = useExploreMode();
   const { exploreDispatch, exploreState } = useExploreState();
@@ -209,6 +211,7 @@ export const useTable = <T extends RowData>(): UseTable<T> => {
 
   // Process explore response - client-side filtering only.
   useEffect(() => {
+    if (entityListType !== tabValue) return;
     if (!listItems || listItems.length === 0) return;
     if (clientFiltering) {
       exploreDispatch({
@@ -229,9 +232,11 @@ export const useTable = <T extends RowData>(): UseTable<T> => {
     allColumns,
     clientFiltering,
     columnFilters,
+    entityListType,
     exploreDispatch,
     listItems,
     rows,
+    tabValue,
   ]);
 
   return { table };

package/src/components/Index/table/types.ts

@@ -3,3 +3,7 @@ import { RowData, Table } from "@tanstack/react-table";
 export interface UseTable<T extends RowData> {
   table: Table<T>;
 }
+
+export interface UseTableProps {
+  entityListType: string;
+}

package/src/hooks/useEntityList.ts

@@ -20,7 +20,6 @@ import { useEntityService } from "./useEntityService";
 import { EXPLORE_MODE, ExploreMode } from "./useExploreMode/types";
 import { useExploreMode } from "./useExploreMode/useExploreMode";
 import { useExploreState } from "./useExploreState";
-import { useURLFilterParams } from "./useURLFilterParams";
 
 /**
  * Hook handling the load and transformation of the values used by index pages. If the current entity loaded statically,
@@ -45,15 +44,8 @@ export const useEntityList = (
   } = useEntityService();
   const { exploreDispatch, exploreState } = useExploreState();
   const { data, isIdle, isLoading, run } = useAsync<AzulEntitiesResponse>();
-  const {
-    catalogState,
-    entityPageState,
-    featureFlagState,
-    filterState,
-    tabValue,
-  } = exploreState;
+  const { entityPageState, filterState, tabValue } = exploreState;
   const { pagination, termFacets } = data || {};
-  const { updateFilterQueryString } = useURLFilterParams();
   const { sorting } = entityPageState[tabValue];
   const entities = getEntities(staticData, data);
   const shouldDispatchResponse = isDispatchable(
@@ -63,11 +55,6 @@ export const useEntityList = (
   );
   const isFetching = isIdle || isLoading;
 
-  // Update the filter query string when the filter state changes.
-  useEffect(() => {
-    updateFilterQueryString(catalogState, featureFlagState, filterState);
-  }, [catalogState, featureFlagState, filterState, updateFilterQueryString]);
-
   // Fetch entities - on change of filter state - server-side fetching and server-side filtering.
   useEffect(() => {
     if (exploreMode === EXPLORE_MODE.SS_FETCH_SS_FILTERING) {

package/src/hooks/useURLFilterParams.ts

@@ -18,6 +18,7 @@ interface UseURLFilterParamsResult {
 /**
  * useURLFilterParams hook is used to keep track of the url search params, and update them,
  * if needed
+ * @deprecated - Avoid using this hook if possible; we intend on using ExploreState actions to manage URL state.
  * @returns an object containing a update function and the current filter
  */
 export const useURLFilterParams = (): UseURLFilterParamsResult => {

package/src/hooks/useUpdateURLSearchParams.ts

@@ -4,6 +4,7 @@ import { useURLFilterParams } from "./useURLFilterParams";
 
 /**
  * Updates URL search params when the filter state changes.
+ * @deprecated - Avoid using this hook if possible; we intend on using ExploreState actions to manage URL state.
  */
 export const useUpdateURLSearchParams = (): void => {
   const { exploreState } = useExploreState();

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

@@ -0,0 +1,18 @@
+import { ExploreState } from "../../../exploreState";
+import { ClearMetaPayload } from "./types";
+
+/**
+ * Reducer function to handle the "clear meta" action.
+ * @param state - Explore State.
+ * @param payload - Payload.
+ * @returns explore state.
+ */
+export function clearMetaAction(
+  state: ExploreState,
+  payload: ClearMetaPayload
+): ExploreState {
+  return {
+    ...state,
+    meta: payload,
+  };
+}

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

@@ -0,0 +1,13 @@
+import { ExploreActionKind } from "../../../exploreState";
+import { ClearMetaAction } from "./types";
+
+/**
+ * Action creator for clearing meta in the state.
+ * @returns Action with payload and action type.
+ */
+export function clearMeta(): ClearMetaAction {
+  return {
+    payload: null,
+    type: ExploreActionKind.ClearMeta,
+  };
+}

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

@@ -0,0 +1,8 @@
+import { ExploreActionKind } from "../../../exploreState";
+
+export type ClearMetaAction = {
+  payload: ClearMetaPayload;
+  type: ExploreActionKind.ClearMeta;
+};
+
+export type ClearMetaPayload = null;

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

@@ -0,0 +1,44 @@
+import { ExploreState } from "../../../exploreState";
+import {
+  getEntityCategoryGroupConfigKey,
+  updateEntityStateByCategoryGroupConfigKey,
+} from "../../utils";
+import { SyncStateFromUrlPayload } from "./types";
+import { buildNextState } from "./utils";
+
+/**
+ * Reducer function to handle the "sync state from URL" action.
+ * Updates the catalog state, feature flag state, and the payload entity's filter state.
+ * @param state - Explore State.
+ * @param payload - Payload.
+ * @returns explore state.
+ */
+export function syncStateFromUrlAction(
+  state: ExploreState,
+  payload: SyncStateFromUrlPayload
+): ExploreState {
+  // Build the next state.
+  const nextState = buildNextState(state, payload);
+
+  // Grab the category group config key for the payload entityListType.
+  const categoryGroupConfigKey = getEntityCategoryGroupConfigKey(
+    payload.entityListType,
+    state.entityPageState
+  );
+
+  // Update the entity state by category group config key.
+  updateEntityStateByCategoryGroupConfigKey(
+    state,
+    {
+      filterState: payload.filterState,
+      savedFilterState: [],
+    },
+    categoryGroupConfigKey
+  );
+
+  // Return the updated state.
+  return {
+    ...state,
+    ...nextState,
+  };
+}

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

@@ -0,0 +1,16 @@
+import { ExploreActionKind } from "../../../exploreState";
+import { SyncStateFromUrlAction, SyncStateFromUrlPayload } from "./types";
+
+/**
+ * Action creator for syncing state from URL.
+ * @param payload - Payload.
+ * @returns Action with payload and action type.
+ */
+export function syncStateFromUrl(
+  payload: SyncStateFromUrlPayload
+): SyncStateFromUrlAction {
+  return {
+    payload,
+    type: ExploreActionKind.SyncStateFromUrl,
+  };
+}

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

@@ -0,0 +1,13 @@
+import { ExploreActionKind, ExploreState } from "../../../exploreState";
+
+export type SyncStateFromUrlAction = {
+  payload: SyncStateFromUrlPayload;
+  type: ExploreActionKind.SyncStateFromUrl;
+};
+
+export type SyncStateFromUrlPayload = Pick<
+  ExploreState,
+  "catalogState" | "featureFlagState" | "filterState"
+> & {
+  entityListType: string;
+};

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

@@ -0,0 +1,31 @@
+import { ExploreState } from "../../../exploreState";
+import { getFilterCount } from "../../../exploreState/utils";
+import { SyncStateFromUrlPayload } from "./types";
+
+/**
+ * Builds the next state, syncing the catalog state, feature flag state, and filter state.
+ * @param state - Explore state.
+ * @param payload - Payload.
+ * @returns state.
+ */
+export function buildNextState(
+  state: ExploreState,
+  payload: SyncStateFromUrlPayload
+): Partial<ExploreState> {
+  // Initialize filter count and filter state from current state.
+  let filterCount = state.filterCount;
+  let filterState = state.filterState;
+
+  // Only update filter count and filter state if the payload entityListType matches the current tab value.
+  if (payload.entityListType === state.tabValue) {
+    filterCount = getFilterCount(payload.filterState);
+    filterState = payload.filterState;
+  }
+
+  return {
+    catalogState: payload.catalogState,
+    featureFlagState: payload.featureFlagState,
+    filterCount,
+    filterState,
+  };
+}

package/src/providers/exploreState/constants.ts

@@ -1,3 +1,9 @@
+export const EXPLORE_URL_PARAMS = {
+  CATALOG: "catalog",
+  FEATURE_FLAG: "ff",
+  FILTER: "filter",
+} as const;
+
 export const SELECT_CATEGORY_KEY = {
   SAVED_FILTERS: "savedFilters",
 };

package/src/providers/exploreState/entities.ts

@@ -18,6 +18,7 @@ import {
   EntityPath,
   SavedFilter,
 } from "../../config/entities";
+import { META_COMMAND } from "./hooks/UseMetaCommands/types";
 
 export interface EntityPageState {
   categoryGroupConfigKey: CategoryGroupConfigKey;
@@ -55,6 +56,10 @@ 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;
 
+export interface Meta {
+  command: META_COMMAND;
+}
+
 export type SavedFilterByCategoryValueKey = Map<
   CategoryValueKey,
   EntityStateSavedFilter

package/src/providers/exploreState/hooks/UseBeforePopState/useBeforePopState.ts

@@ -0,0 +1,46 @@
+import { useRouter } from "next/router";
+import { useEffect } from "react";
+import { ExploreStateContextProps } from "../../../exploreState";
+import { syncStateFromUrl } from "../../../exploreState/actions/syncStateFromUrl/dispatch";
+import { getSyncStateFromUrl } from "./utils";
+
+/**
+ * useBeforePopState
+ *
+ * Keeps ExploreState, URL, and page props aligned when the user clicks
+ * the browser Back / Forward buttons.
+ *
+ * This hook runs inside `ExploreStateProvider` (mounted once in `_app`).
+ * It adds a single `router.beforePopState` handler that:
+ * - Parses the destination URL.
+ * - Dispatches `syncStateFromUrl` so filters, catalogue, and feature-flags in context match the URL.
+ * - Calls `router.replace(...{ shallow: false })` to trigger a full page transition, ensuring Next.js
+ *   re-executes data-fetching methods that shallow routing would otherwise skip.
+ *
+ * The provider never unmounts, and a second call to `router.beforePopState` simply overwrites the handler.
+ * Cleaning up here would wipe out any handler registered later by other code.
+ */
+
+export const useBeforePopState = ({
+  exploreDispatch,
+}: ExploreStateContextProps): void => {
+  const router = useRouter();
+  useEffect(() => {
+    router.beforePopState(({ as, options, url }) => {
+      // Grab the expected state from URL.
+      const payload = getSyncStateFromUrl(url, as);
+      // Only dispatch if the url contains the dynamic segment `[entityListType]`.
+      if (payload.entityListType) {
+        // Sync state from URL.
+        exploreDispatch(syncStateFromUrl(payload));
+        // Force a full route transition to ensure page props are refreshed.
+        router.replace(url, as, { ...options, shallow: false });
+        return false;
+      }
+      // Return true to allow the popstate event to continue.
+      return true;
+    });
+    // No cleanup handler: see the JSDoc above for why we do not reset beforePopState here.
+    // Resetting would remove any handler registered by other parts of the app after this hook mounted.
+  }, [exploreDispatch, router]);
+};

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

@@ -0,0 +1,93 @@
+import { SelectedFilter } from "common/entities";
+import { SyncStateFromUrlPayload } from "providers/exploreState/actions/syncStateFromUrl/types";
+import { EXPLORE_URL_PARAMS } from "../../../exploreState/constants";
+
+/**
+ * Returns the filters from the resolved URL.
+ * @param paramValue - The filter parameter value.
+ * @returns The filters or an empty array.
+ */
+export function decodeFiltersParamValue(
+  paramValue: string | undefined
+): SelectedFilter[] {
+  return JSON.parse(decodeURIComponent(paramValue || "[]"));
+}
+
+/**
+ * Returns the dynamic segment from the resolved URL.
+ * @param pattern - The pattern URL.
+ * @param resolved - The resolved URL.
+ * @param dynamicSegment - The dynamic segment to extract.
+ * @returns The dynamic segment or an empty string.
+ */
+function getDynamicSegment(
+  pattern: string,
+  resolved: string,
+  dynamicSegment = "[entityListType]"
+): string {
+  // Remove query strings.
+  const patternPath = pattern.split("?")[0];
+  const resolvedPath = resolved.split("?")[0];
+
+  // Check if the pattern ends with the dynamic segment e.g. /data/[entityListType].
+  // We are not interested in a pattern the suggests we are on an entity page e.g. /data/[entityListType]/[entityId].
+  if (!patternPath.endsWith(`/${dynamicSegment}`)) return "";
+
+  // Split into segments.
+  const patternSegments = patternPath.split("/");
+  const resolvedSegments = resolvedPath.split("/");
+
+  // Find the dynamic segment.
+  const idx = patternSegments.findIndex((seg) => seg === dynamicSegment);
+
+  if (idx === -1) return "";
+
+  return resolvedSegments[idx] || "";
+}
+
+/**
+ * Returns a parameter from the resolved URL.
+ * @param resolved - The resolved URL.
+ * @param param - The parameter to extract.
+ * @returns The parameter value or undefined.
+ */
+export function getParamValue(
+  resolved: string,
+  param: string
+): string | undefined {
+  // Grab the params from the resolved URL.
+  const params = new URLSearchParams(resolved.split("?")[1]);
+  const paramValue = params.get(param);
+
+  // Return the parameter value or undefined.
+  if (!paramValue) return;
+
+  return paramValue;
+}
+
+/**
+ * Returns the entity list type, filters, and feature flag state from the URL.
+ * A dynamic segment that is not exactly `[entityListType]` is not supported will return entityListType as an empty string.
+ * @param url - The URL to extract from.
+ * @param as - The resolved URL.
+ * @returns An object containing the entity list type, filters, and feature flag state.
+ */
+export function getSyncStateFromUrl(
+  url: string,
+  as: string
+): SyncStateFromUrlPayload {
+  // Get the entity list type from the url.
+  const entityListType = getDynamicSegment(url, as);
+
+  // Get the param values for each param.
+  const [catalogState, featureFlagState, filter] = [
+    EXPLORE_URL_PARAMS.CATALOG,
+    EXPLORE_URL_PARAMS.FEATURE_FLAG,
+    EXPLORE_URL_PARAMS.FILTER,
+  ].map((param) => getParamValue(as, param));
+
+  // Decode the filter param value to selected filters.
+  const filterState = decodeFiltersParamValue(filter);
+
+  return { catalogState, entityListType, featureFlagState, filterState };
+}

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

@@ -0,0 +1,29 @@
+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

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