@databiosphere/findable-ui 34.1.0 → 35.0.2

package/lib/providers/services/wasPop/provider.js

@@ -0,0 +1,30 @@
+import React, { useCallback, useRef } from "react";
+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, }) {
+    const popRef = useRef();
+    // Pop callback.
+    const onBeforePopState = useCallback((state) => {
+        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 (React.createElement(WasPopContext.Provider, { value: { onClearPopRef, popRef } }, children));
+}

package/lib/providers/services/wasPop/types.d.ts

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

package/lib/providers/services/wasPop/types.js

@@ -0,0 +1 @@
+export {};

package/lib/services/beforePopState/popStateBus.d.ts

@@ -0,0 +1,20 @@
+import { BeforePopStateCallback } from "./types";
+/**
+ * Register a callback to be invoked immediately before any Next.js pop navigation.
+ * Return `false` from your callback to prevent the pop; otherwise return `true`.
+ * @param cb - The callback function to register.
+ */
+export declare function registerBeforePopCallback(cb: BeforePopStateCallback): void;
+/**
+ * Unregister a previously registered “before pop” callback.
+ * @param cb - The callback function to unregister.
+ */
+export declare function unregisterBeforePopCallback(cb: BeforePopStateCallback): void;
+/**
+ * Install the global “before pop” interceptor into Next.js’s router.
+ * Subsequent calls to this function will be no‐ops.
+ *
+ * This method must be called once (e.g. in your app’s top‐level code)
+ * to enable the pop‐state bus.
+ */
+export declare function registerPopStateHandler(): void;

package/lib/services/beforePopState/popStateBus.js

@@ -0,0 +1,58 @@
+import Router from "next/router";
+/**
+ * Pop‐State Event Bus
+ *
+ * Provides a centralized mechanism for components to intercept
+ * and optionally prevent Back/Forward navigation (Next.js beforePopState).
+ */
+/**
+ * A set of callback functions that will run before Next.js performs a pop.
+ * Each callback returns `true` to allow navigation or `false` to block.
+ */
+const beforePopCallbacks = new Set();
+/**
+ * Register a callback to be invoked immediately before any Next.js pop navigation.
+ * Return `false` from your callback to prevent the pop; otherwise return `true`.
+ * @param cb - The callback function to register.
+ */
+export function registerBeforePopCallback(cb) {
+    beforePopCallbacks.add(cb);
+}
+/**
+ * Unregister a previously registered “before pop” callback.
+ * @param cb - The callback function to unregister.
+ */
+export function unregisterBeforePopCallback(cb) {
+    beforePopCallbacks.delete(cb);
+}
+/**
+ * Ensures that we only hook into Next.js once. After install, any pop event
+ * will first invoke all registered callbacks and only proceed if all return true.
+ */
+let hasInstalledInterceptor = false;
+/**
+ * Install the global “before pop” interceptor into Next.js’s router.
+ * Subsequent calls to this function will be no‐ops.
+ *
+ * This method must be called once (e.g. in your app’s top‐level code)
+ * to enable the pop‐state bus.
+ */
+export function registerPopStateHandler() {
+    if (hasInstalledInterceptor)
+        return;
+    hasInstalledInterceptor = true;
+    Router.beforePopState((state) => {
+        // Iteratively call every callback. If any returns false, block navigation.
+        let allAllow = true;
+        beforePopCallbacks.forEach((cb) => {
+            try {
+                if (cb(state) === false)
+                    allAllow = false;
+            }
+            catch (e) {
+                console.error("Pop listener failed:", e);
+            }
+        });
+        return allAllow;
+    });
+}

package/lib/services/beforePopState/types.d.ts

@@ -0,0 +1,11 @@
+import Router from "next/router";
+/**
+ * Type representing the callback function passed to beforePopState.
+ * Extracted from the Next.js Router.beforePopState API.
+ */
+export type BeforePopStateCallback = Parameters<typeof Router.beforePopState>[0];
+/**
+ * Type representing the state passed to beforePopState.
+ * Extracted from the Next.js Router.beforePopState API.
+ */
+export type NextHistoryState = Parameters<BeforePopStateCallback>[0];

package/lib/services/beforePopState/types.js

@@ -0,0 +1 @@
+export {};

package/lib/services/beforePopState/useOnPopState.d.ts

@@ -0,0 +1,2 @@
+import { BeforePopStateCallback } from "./types";
+export declare const useOnPopState: (cb: BeforePopStateCallback) => void;

package/lib/services/beforePopState/useOnPopState.js

@@ -0,0 +1,10 @@
+import { useEffect } from "react";
+import { registerBeforePopCallback, unregisterBeforePopCallback, } from "./popStateBus";
+export const useOnPopState = (cb) => {
+    useEffect(() => {
+        registerBeforePopCallback(cb);
+        return () => {
+            unregisterBeforePopCallback(cb);
+        };
+    }, [cb]);
+};

package/lib/services/beforePopState/usePopStateBus.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Registers the single global `router.beforePopState` handler that
+ * fans out to all feature listeners.
+ * Safe to call multiple times - only the first invocation does the real install.
+ */
+export declare const usePopStateBus: () => void;

package/lib/services/beforePopState/usePopStateBus.js

@@ -0,0 +1,12 @@
+import { useEffect } from "react";
+import { registerPopStateHandler } from "./popStateBus";
+/**
+ * Registers the single global `router.beforePopState` handler that
+ * fans out to all feature listeners.
+ * Safe to call multiple times - only the first invocation does the real install.
+ */
+export const usePopStateBus = () => {
+    useEffect(() => {
+        registerPopStateHandler();
+    }, []);
+};

package/lib/styles/common/mixins/shadows.d.ts

@@ -0,0 +1,3 @@
+import { ThemeProps } from "../../../theme/theme";
+export declare const shadows01: ({ theme }: ThemeProps) => string;
+export declare const shadows02: ({ theme }: ThemeProps) => string;

package/lib/styles/common/mixins/shadows.js

@@ -0,0 +1,4 @@
+// Elevation 01
+export const shadows01 = ({ theme }) => theme.shadows[1];
+// Elevation 02
+export const shadows02 = ({ theme }) => theme.shadows[2];

package/lib/styles/common/mui/palette.d.ts

@@ -0,0 +1,47 @@
+export declare const PALETTE: {
+    readonly ALERT_LIGHT: "var(--mui-palette-alert-light)";
+    readonly ALERT_LIGHTEST: "var(--mui-palette-alert-lightest)";
+    readonly ALERT_MAIN: "var(--mui-palette-alert-main)";
+    readonly BACKGROUND_DEFAULT: "var(--mui-palette-background-default)";
+    readonly BACKGROUND_PAPER: "var(--mui-palette-background-paper)";
+    readonly COMMON_BACKGROUND: "var(--mui-palette-common-background)";
+    readonly COMMON_BLACK: "var(--mui-palette-common-black)";
+    readonly COMMON_WHITE: "var(--mui-palette-common-white)";
+    readonly ERROR_CONTRAST_TEXT: "var(--mui-palette-error-contrastText)";
+    readonly ERROR_DARK: "var(--mui-palette-error-dark)";
+    readonly ERROR_LIGHT: "var(--mui-palette-error-light)";
+    readonly ERROR_MAIN: "var(--mui-palette-error-main)";
+    readonly INFO_CONTRAST_TEXT: "var(--mui-palette-info-contrastText)";
+    readonly INFO_DARK: "var(--mui-palette-info-dark)";
+    readonly INFO_LIGHT: "var(--mui-palette-info-light)";
+    readonly INFO_LIGHTEST: "var(--mui-palette-info-lightest)";
+    readonly INFO_MAIN: "var(--mui-palette-info-main)";
+    readonly INK_LIGHT: "var(--mui-palette-ink-light)";
+    readonly INK_MAIN: "var(--mui-palette-ink-main)";
+    readonly PRIMARY_CONTRAST_TEXT: "var(--mui-palette-primary-contrastText)";
+    readonly PRIMARY_DARK: "var(--mui-palette-primary-dark)";
+    readonly PRIMARY_LIGHT: "var(--mui-palette-primary-light)";
+    readonly PRIMARY_LIGHTEST: "var(--mui-palette-primary-lightest)";
+    readonly PRIMARY_MAIN: "var(--mui-palette-primary-main)";
+    readonly SECONDARY_CONTRAST_TEXT: "var(--mui-palette-secondary-contrastText)";
+    readonly SECONDARY_DARK: "var(--mui-palette-secondary-dark)";
+    readonly SECONDARY_LIGHT: "var(--mui-palette-secondary-light)";
+    readonly SECONDARY_MAIN: "var(--mui-palette-secondary-main)";
+    readonly SMOKE_DARK: "var(--mui-palette-smoke-dark)";
+    readonly SMOKE_LIGHT: "var(--mui-palette-smoke-light)";
+    readonly SMOKE_LIGHTEST: "var(--mui-palette-smoke-lightest)";
+    readonly SMOKE_MAIN: "var(--mui-palette-smoke-main)";
+    readonly SUCCESS_CONTRAST_TEXT: "var(--mui-palette-success-contrastText)";
+    readonly SUCCESS_DARK: "var(--mui-palette-success-dark)";
+    readonly SUCCESS_LIGHT: "var(--mui-palette-success-light)";
+    readonly SUCCESS_LIGHTEST: "var(--mui-palette-success-lightest)";
+    readonly SUCCESS_MAIN: "var(--mui-palette-success-main)";
+    readonly TEXT_DISABLED: "var(--mui-palette-text-disabled)";
+    readonly TEXT_PRIMARY: "var(--mui-palette-text-primary)";
+    readonly TEXT_SECONDARY: "var(--mui-palette-text-secondary)";
+    readonly WARNING_CONTRAST_TEXT: "var(--mui-palette-warning-contrastText)";
+    readonly WARNING_DARK: "var(--mui-palette-warning-dark)";
+    readonly WARNING_LIGHT: "var(--mui-palette-warning-light)";
+    readonly WARNING_LIGHTEST: "var(--mui-palette-warning-lightest)";
+    readonly WARNING_MAIN: "var(--mui-palette-warning-main)";
+};

package/lib/styles/common/mui/palette.js

@@ -0,0 +1,47 @@
+export const PALETTE = {
+    ALERT_LIGHT: `var(--mui-palette-alert-light)`,
+    ALERT_LIGHTEST: `var(--mui-palette-alert-lightest)`,
+    ALERT_MAIN: `var(--mui-palette-alert-main)`,
+    BACKGROUND_DEFAULT: `var(--mui-palette-background-default)`,
+    BACKGROUND_PAPER: `var(--mui-palette-background-paper)`,
+    COMMON_BACKGROUND: `var(--mui-palette-common-background)`,
+    COMMON_BLACK: `var(--mui-palette-common-black)`,
+    COMMON_WHITE: `var(--mui-palette-common-white)`,
+    ERROR_CONTRAST_TEXT: `var(--mui-palette-error-contrastText)`,
+    ERROR_DARK: `var(--mui-palette-error-dark)`,
+    ERROR_LIGHT: `var(--mui-palette-error-light)`,
+    ERROR_MAIN: `var(--mui-palette-error-main)`,
+    INFO_CONTRAST_TEXT: `var(--mui-palette-info-contrastText)`,
+    INFO_DARK: `var(--mui-palette-info-dark)`,
+    INFO_LIGHT: `var(--mui-palette-info-light)`,
+    INFO_LIGHTEST: `var(--mui-palette-info-lightest)`,
+    INFO_MAIN: `var(--mui-palette-info-main)`,
+    INK_LIGHT: `var(--mui-palette-ink-light)`,
+    INK_MAIN: `var(--mui-palette-ink-main)`,
+    PRIMARY_CONTRAST_TEXT: `var(--mui-palette-primary-contrastText)`,
+    PRIMARY_DARK: `var(--mui-palette-primary-dark)`,
+    PRIMARY_LIGHT: `var(--mui-palette-primary-light)`,
+    PRIMARY_LIGHTEST: `var(--mui-palette-primary-lightest)`,
+    PRIMARY_MAIN: `var(--mui-palette-primary-main)`,
+    SECONDARY_CONTRAST_TEXT: `var(--mui-palette-secondary-contrastText)`,
+    SECONDARY_DARK: `var(--mui-palette-secondary-dark)`,
+    SECONDARY_LIGHT: `var(--mui-palette-secondary-light)`,
+    SECONDARY_MAIN: `var(--mui-palette-secondary-main)`,
+    SMOKE_DARK: `var(--mui-palette-smoke-dark)`,
+    SMOKE_LIGHT: `var(--mui-palette-smoke-light)`,
+    SMOKE_LIGHTEST: `var(--mui-palette-smoke-lightest)`,
+    SMOKE_MAIN: `var(--mui-palette-smoke-main)`,
+    SUCCESS_CONTRAST_TEXT: `var(--mui-palette-success-contrastText)`,
+    SUCCESS_DARK: `var(--mui-palette-success-dark)`,
+    SUCCESS_LIGHT: `var(--mui-palette-success-light)`,
+    SUCCESS_LIGHTEST: `var(--mui-palette-success-lightest)`,
+    SUCCESS_MAIN: `var(--mui-palette-success-main)`,
+    TEXT_DISABLED: `var(--mui-palette-text-disabled)`,
+    TEXT_PRIMARY: `var(--mui-palette-text-primary)`,
+    TEXT_SECONDARY: `var(--mui-palette-text-secondary)`,
+    WARNING_CONTRAST_TEXT: `var(--mui-palette-warning-contrastText)`,
+    WARNING_DARK: `var(--mui-palette-warning-dark)`,
+    WARNING_LIGHT: `var(--mui-palette-warning-light)`,
+    WARNING_LIGHTEST: `var(--mui-palette-warning-lightest)`,
+    WARNING_MAIN: `var(--mui-palette-warning-main)`,
+};

package/lib/theme/common/entities.d.ts

@@ -0,0 +1,6 @@
+export interface BaseComponentProps {
+    className?: string;
+}
+export interface TrackingComponentProps {
+    trackingId?: string;
+}

package/lib/theme/common/entities.js

@@ -0,0 +1 @@
+export {};

package/lib/views/ExploreView/exploreView.js

@@ -11,16 +11,20 @@ import { SidebarButton } from "../../components/Layout/components/Sidebar/compon
 import { SidebarLabel } from "../../components/Layout/components/Sidebar/components/SidebarLabel/sidebarLabel";
 import { SidebarTools } from "../../components/Layout/components/Sidebar/components/SidebarTools/sidebarTools.styles";
 import { Sidebar } from "../../components/Layout/components/Sidebar/sidebar";
+import { useStateSyncManager } from "../../hooks/stateSyncManager/hook";
 import { BREAKPOINT_FN_NAME, useBreakpointHelper, } from "../../hooks/useBreakpointHelper";
 import { useConfig } from "../../hooks/useConfig";
 import { useEntityList } from "../../hooks/useEntityList";
 import { useExploreState } from "../../hooks/useExploreState";
 import { useSummary } from "../../hooks/useSummary";
 import { ExploreActionKind } from "../../providers/exploreState";
+import { clearMeta } from "../../providers/exploreState/actions/clearMeta/dispatch";
+import { stateToUrl } from "../../providers/exploreState/actions/stateToUrl/dispatch";
+import { urlToState } from "../../providers/exploreState/actions/urlToState/dispatch";
 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";
+import { buildStateSyncManagerContext } from "./utils";
 export const ExploreView = (props) => {
     const [isDrawerOpen, setIsDrawerOpen] = useState(false);
     const tabletDown = useBreakpointHelper(BREAKPOINT_FN_NAME.DOWN, DESKTOP_SM);
@@ -34,6 +38,15 @@ export const ExploreView = (props) => {
     useEntityList(props); // Fetch entities.
     const { entityListType } = props;
     const categoryFilters = useMemo(() => buildCategoryFilters(categoryViews, categoryGroups), [categoryGroups, categoryViews]);
+    /**
+     * State sync manager.
+     * Handles state synchronization between the explore state and the URL.
+     */
+    useStateSyncManager({
+        actions: { clearMeta, stateToUrl, urlToState },
+        dispatch: exploreDispatch,
+        state: buildStateSyncManagerContext(exploreState, props),
+    });
     /**
      * Closes filter drawer.
      */
@@ -99,7 +112,7 @@ export const ExploreView = (props) => {
             });
         }
     }, [entityListType, exploreDispatch]);
-    return (React.createElement(ExploreStateSyncProvider, null,
+    return (React.createElement(React.Fragment, 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/lib/views/ExploreView/utils.d.ts

@@ -0,0 +1,14 @@
+import { ComponentProps } from "react";
+import { StateSyncManagerContext } from "../../hooks/stateSyncManager/types";
+import { ExploreState } from "../../providers/exploreState";
+import { ExploreView } from "./exploreView";
+/**
+ *Builds the state sync manager context object for URL-state synchronization.
+ * - Command: The meta command that signals a URL update operation is needed e.g. "STATE_TO_URL_PUSH" or "STATE_TO_URL_REPLACE".
+ * - ParamKeys: Expected list of URL parameter keys that should be synchronized with state e.g. "filter", "catalog".
+ * - Query: Entity related query object from state that should be synchronized with the URL.
+ * @param exploreState - Explore state.
+ * @param pageProps - Page props.
+ * @returns The state sync manager context.
+ */
+export declare function buildStateSyncManagerContext(exploreState: ExploreState, pageProps: ComponentProps<typeof ExploreView>): StateSyncManagerContext;

package/lib/views/ExploreView/utils.js

@@ -0,0 +1,17 @@
+import { EXPLORE_URL_PARAMS } from "../../providers/exploreState/constants";
+/**
+ *Builds the state sync manager context object for URL-state synchronization.
+ * - Command: The meta command that signals a URL update operation is needed e.g. "STATE_TO_URL_PUSH" or "STATE_TO_URL_REPLACE".
+ * - ParamKeys: Expected list of URL parameter keys that should be synchronized with state e.g. "filter", "catalog".
+ * - Query: Entity related query object from state that should be synchronized with the URL.
+ * @param exploreState - Explore state.
+ * @param pageProps - Page props.
+ * @returns The state sync manager context.
+ */
+export function buildStateSyncManagerContext(exploreState, pageProps) {
+    return {
+        command: exploreState.meta?.command,
+        paramKeys: Object.values(EXPLORE_URL_PARAMS),
+        query: exploreState.entities[pageProps.entityListType].query,
+    };
+}

package/package.json

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

package/src/hooks/stateSyncManager/hook.ts

@@ -0,0 +1,47 @@
+import { useState } from "react";
+import { useBeforePopState } from "./hooks/UseBeforePopState/hook";
+import { useMetaCommands } from "./hooks/UseMetaCommands/hook";
+import { useStateSync } from "./hooks/UseStateSync/hook";
+import { StateSyncManagerActions, UseStateSyncManagerProps } from "./types";
+
+/**
+ * Synchronizes state (e.g. explore state, data dictionary state) with browser URL query parameters.
+ *
+ * Keeps state and URL in sync by:
+ * - Updating URL when state changes (push/replace).
+ * - Updating state when URL changes (navigation).
+ * - Handling browser history events (back/forward buttons).
+ *
+ * Internal components:
+ * 1. Pop-State Manager - Manages browser navigation events.
+ * 2. Meta-Command Handler - Processes URL update commands from state.
+ * 3. State-URL Sync - Coordinates bidirectional synchronization.
+ *
+ * Required setup:
+ * - Action creators for state/URL operations.
+ * - State containing command flags, URL parameters, and sync configuration.
+ */
+
+export const useStateSyncManager = <Action>({
+  actions: actionCreators,
+  dispatch,
+  state,
+}: UseStateSyncManagerProps<Action>): void => {
+  /**
+   * Store action creators in state to maintain referential stability across renders.
+   * This prevents unnecessary re-renders in hooks that depend on these actions
+   * and ensures effect dependencies remain stable.
+   */
+  const [actions] = useState<StateSyncManagerActions<Action>>(
+    () => actionCreators
+  );
+
+  // Register pop state related side effects.
+  useBeforePopState();
+
+  // Set up Meta-commands related side effects.
+  useMetaCommands({ actions, dispatch, state });
+
+  // Dispatch state <-> URL sync side effects.
+  useStateSync({ actions, dispatch, state });
+};

package/src/hooks/stateSyncManager/hooks/UseBeforePopState/hook.ts

@@ -0,0 +1,30 @@
+import Router from "next/router";
+import { useCallback } from "react";
+import {
+  BeforePopStateCallback,
+  NextHistoryState,
+} from "../../../../services/beforePopState/types";
+import { useOnPopState } from "../../../../services/beforePopState/useOnPopState";
+
+export const useBeforePopState = (): void => {
+  // Callback to handle beforePopState.
+  const onBeforePopState = useCallback<BeforePopStateCallback>(
+    (state: NextHistoryState) => {
+      const basePath = Router.basePath ?? "";
+      // Use regex to remove the base path from the beginning of the URL.
+      const as = basePath
+        ? state.as.replace(new RegExp(`^${basePath}`), "") || "/"
+        : state.as;
+      // Force a full route transition to ensure page props are refreshed.
+      Router.replace(as, undefined, {
+        ...state.options,
+        shallow: false,
+      });
+      return false;
+    },
+    []
+  );
+
+  // Pop state related side effects.
+  useOnPopState(onBeforePopState);
+};

package/src/hooks/stateSyncManager/hooks/UseMetaCommands/hook.ts

@@ -0,0 +1,30 @@
+import Router, { useRouter } from "next/router";
+import { useEffect } from "react";
+import { UseStateSyncManagerProps } from "../../types";
+import { META_COMMAND } from "./types";
+
+export const useMetaCommands = <Action>({
+  actions,
+  dispatch,
+  state,
+}: UseStateSyncManagerProps<Action>): void => {
+  const { isReady } = useRouter();
+
+  useEffect(() => {
+    if (!isReady) return;
+    const { command, query } = state;
+
+    switch (command) {
+      case META_COMMAND.STATE_TO_URL_PUSH:
+        Router.push({ query }, undefined, { shallow: true });
+        dispatch(actions.clearMeta());
+        break;
+      case META_COMMAND.STATE_TO_URL_REPLACE:
+        Router.replace({ query }, undefined, { shallow: true });
+        dispatch(actions.clearMeta());
+        break;
+      default:
+        break;
+    }
+  }, [actions, dispatch, isReady, state]);
+};

package/src/hooks/stateSyncManager/hooks/UseMetaCommands/types.ts

@@ -0,0 +1,4 @@
+export enum META_COMMAND {
+  STATE_TO_URL_PUSH = "STATE_TO_URL_PUSH",
+  STATE_TO_URL_REPLACE = "STATE_TO_URL_REPLACE",
+}

package/src/hooks/stateSyncManager/hooks/UseStateSync/hook.ts

@@ -0,0 +1,52 @@
+import { NextRouter, useRouter } from "next/router";
+import { useEffect } from "react";
+import { ROUTER_METHOD } from "../../../../providers/exploreState/actions/stateToUrl/types";
+import { useWasPop } from "../../../../providers/services/wasPop/hook";
+import { UseStateSyncManagerProps } from "../../types";
+import { hasParams, isSynced, wasPop } from "./utils";
+
+export const useStateSync = <Action>({
+  actions,
+  dispatch,
+  state,
+}: UseStateSyncManagerProps<Action>): void => {
+  const { basePath, isReady, pathname, query } = useRouter();
+  const { onClearPopRef, popRef } = useWasPop();
+
+  // Extract the query from the state.
+  const stateQuery = state.query as NextRouter["query"];
+
+  // Extract the param keys from the state.
+  const paramKeys = state.paramKeys;
+
+  // Dispatch action to sync state <-> URL.
+  useEffect(() => {
+    // Do nothing if the router is not ready.
+    if (!isReady) return;
+
+    // Do nothing; URL and state are in sync.
+    if (isSynced(stateQuery, query)) {
+      onClearPopRef();
+      return;
+    }
+
+    // Dispatch action sync URL >> state.
+    if (wasPop(basePath, pathname, popRef.current)) {
+      // When the user navigates with the back/forward buttons.
+      dispatch(actions.urlToState({ query }));
+      onClearPopRef();
+      return;
+    }
+
+    // Dispatch action sync URL >> state.
+    if (hasParams(query, paramKeys)) {
+      // When the URL has parameters.
+      dispatch(actions.urlToState({ query }));
+      return;
+    }
+
+    // Otherwise, dispatch action sync URL << state.
+    dispatch(actions.stateToUrl({ method: ROUTER_METHOD.REPLACE }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- deliberate omission of `state.query`, `state.paramKeys`, `actions` and `dispatch` from dependencies, hook is only expected to run when the Next.js router changes.
+  }, [basePath, isReady, pathname, query]);
+};

package/src/hooks/stateSyncManager/hooks/UseStateSync/utils.ts

@@ -0,0 +1,58 @@
+import { NextRouter } from "next/router";
+import { NextHistoryState } from "../../../../services/beforePopState/types";
+
+/**
+ * Returns true if the query object has any of the specified keys.
+ * @param query - Query object.
+ * @param paramKeys - Array of parameter keys to check.
+ * @returns True if the query object has any of the specified keys.
+ */
+export function hasParams(
+  query: NextRouter["query"],
+  paramKeys: string[]
+): boolean {
+  return paramKeys.some((key) => query[key] !== undefined);
+}
+
+/**
+ * Returns true if the two query objects are equal.
+ * @param queryA - Query object.
+ * @param queryB - Query object.
+ * @returns True if the two query objects are equal.
+ */
+export function isSynced(
+  queryA: NextRouter["query"],
+  queryB: NextRouter["query"]
+): boolean {
+  return stringifyQuery(queryA) === stringifyQuery(queryB);
+}
+
+/**
+ * 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] }), {})
+  );
+}
+
+/**
+ * Returns true if the URL was navigated to using the back/forward buttons.
+ * @param basePath - Base path.
+ * @param pathname - Pathname.
+ * @param nextHistoryState - Next history state.
+ * @returns True if the URL was navigated to using the back/forward buttons.
+ */
+export function wasPop(
+  basePath = "",
+  pathname: string,
+  nextHistoryState: NextHistoryState | undefined
+): boolean {
+  if (!nextHistoryState) return false;
+  const [path] = nextHistoryState.url.split("?");
+  return path === `${basePath}${pathname}`;
+}

package/src/hooks/stateSyncManager/types.ts

@@ -0,0 +1,34 @@
+import { NextRouter } from "next/router";
+import { Dispatch } from "react";
+import { ROUTER_METHOD } from "../../providers/exploreState/actions/stateToUrl/types";
+import { META_COMMAND } from "./hooks/UseMetaCommands/types";
+
+export type ActionCreator<P, DispatchType> = [P] extends [void]
+  ? () => DispatchType
+  : (payload: P) => DispatchType;
+
+export interface StateToUrlPayload {
+  method: ROUTER_METHOD;
+}
+
+export interface UrlToStatePayload {
+  query: NextRouter["query"];
+}
+
+export interface StateSyncManagerActions<Action> {
+  clearMeta: ActionCreator<void, Action>;
+  stateToUrl: ActionCreator<StateToUrlPayload, Action>;
+  urlToState: ActionCreator<UrlToStatePayload, Action>;
+}
+
+export interface StateSyncManagerContext {
+  command: META_COMMAND | undefined;
+  paramKeys: string[];
+  query: NextRouter["query"];
+}
+
+export interface UseStateSyncManagerProps<Action> {
+  actions: StateSyncManagerActions<Action>;
+  dispatch: Dispatch<Action>;
+  state: StateSyncManagerContext;
+}