@databiosphere/findable-ui 35.2.0 → 36.0.0

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

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

package/src/providers/dataDictionaryState/context.ts

@@ -0,0 +1,9 @@
+import { createContext } from "react";
+import { INITIAL_DATA_DICTIONARY_STATE } from "./initializer/constants";
+import { DataDictionaryStateContextProps } from "./types";
+
+export const DataDictionaryStateContext =
+  createContext<DataDictionaryStateContextProps>({
+    dataDictionaryDispatch: null,
+    dataDictionaryState: INITIAL_DATA_DICTIONARY_STATE,
+  });

package/src/providers/dataDictionaryState/dictionaries/constants.ts

@@ -0,0 +1,4 @@
+export const DATA_DICTIONARY_URL_PARAMS = {
+  COLUMN_FILTERS: "filter",
+  GLOBAL_FILTER: "search",
+} as const;

package/src/providers/dataDictionaryState/dictionaries/state.ts

@@ -0,0 +1,45 @@
+import { TableState } from "@tanstack/react-table";
+import { stateToUrlQuery } from "../../../utils/stateToUrlQuery";
+import { DataDictionaryState } from "../types";
+import { DictionariesContext } from "./types";
+import { extractDictionaryUrlState as extractUrlState } from "./utils";
+
+/**
+ * Builds the next dictionaries context.
+ * @param state - State.
+ * @param dictionaryKey - Dictionary key.
+ * @param nextDictionaryState - Next dictionary state.
+ * @returns Next dictionaries context.
+ */
+export function buildNextDictionaries(
+  state: DataDictionaryState,
+  dictionaryKey: string,
+  nextDictionaryState: Partial<TableState>
+): DictionariesContext {
+  // Clone the dictionaries.
+  const dictionaries: DictionariesContext = { ...state.dictionaries };
+
+  for (const [key, dictionary] of Object.entries(dictionaries)) {
+    // Clone the dictionary context.
+    const dictionaryContext = { ...dictionary };
+
+    // If the dictionary key is a match, update the dictionary context.
+    if (key === dictionaryKey) {
+      // Update the dictionary state.
+      dictionaryContext.state = { ...dictionary.state, ...nextDictionaryState };
+
+      // Grab param values from the updated dictionary state.
+      const { columnFilters, globalFilter } = dictionaryContext.state;
+
+      // Update the dictionary query.
+      dictionaryContext.query = stateToUrlQuery(
+        extractUrlState(key, { columnFilters, globalFilter })
+      );
+    }
+
+    // Update the dictionary context.
+    dictionaries[key] = dictionaryContext;
+  }
+
+  return dictionaries;
+}

package/src/providers/dataDictionaryState/dictionaries/types.ts

@@ -0,0 +1,11 @@
+import { TableState } from "@tanstack/react-table";
+import { NextRouter } from "next/router";
+
+export interface DictionariesContext {
+  [key: string]: DictionaryContext;
+}
+
+export interface DictionaryContext {
+  query: NextRouter["query"];
+  state: Partial<TableState>;
+}

package/src/providers/dataDictionaryState/dictionaries/utils.ts

@@ -0,0 +1,25 @@
+import { ColumnFiltersState, TableState } from "@tanstack/react-table";
+import { DATA_DICTIONARY_URL_PARAMS } from "./constants";
+
+/**
+ * Extracts dictionary state properties that should be synchronized with URL parameters.
+ * This function maps specific properties from the dictionary state to a format
+ * that can be used to generate URL query parameters.
+ * The extracted properties are:
+ * - dictionary: Dictionary key (string).
+ * - filter: Applied column filters (ColumnFiltersState).
+ * - search: Applied global filter (GlobalFilterTableState) - typed as string or undefined.
+ * @param dictionary - Dictionary key.
+ * @param state - Dictionary table state.
+ * @returns Object with properties ready for URL query serialization.
+ */
+export function extractDictionaryUrlState(
+  dictionary: string,
+  state: Partial<TableState>
+): Record<string, string | ColumnFiltersState | undefined> {
+  return {
+    dictionary,
+    [DATA_DICTIONARY_URL_PARAMS.COLUMN_FILTERS]: state.columnFilters || [],
+    [DATA_DICTIONARY_URL_PARAMS.GLOBAL_FILTER]: state.globalFilter,
+  };
+}

package/src/providers/dataDictionaryState/hooks/UseDataDictionaryInitialArgs/hook.ts

@@ -0,0 +1,14 @@
+import { DataDictionaryConfig } from "../../../../common/entities";
+import { useConfig } from "../../../../hooks/useConfig";
+import { UseDataDictionaryInitialArgs } from "./types";
+
+export const useDataDictionaryInitialArgs =
+  (): UseDataDictionaryInitialArgs => {
+    const { config } = useConfig();
+
+    const dataDictionaries = config.dataDictionaries as
+      | DataDictionaryConfig[]
+      | undefined;
+
+    return { dataDictionaries };
+  };

package/src/providers/dataDictionaryState/hooks/UseDataDictionaryInitialArgs/types.ts

@@ -0,0 +1,5 @@
+import { DataDictionaryConfig } from "../../../../common/entities";
+
+export interface UseDataDictionaryInitialArgs {
+  dataDictionaries?: DataDictionaryConfig[];
+}

package/src/providers/dataDictionaryState/hooks/UseDataDictionaryReducer/hook.ts

@@ -0,0 +1,17 @@
+import { useReducer } from "react";
+import { initializer } from "../../initializer/initializer";
+import { dataDictionaryReducer } from "../../reducer";
+import { DataDictionaryStateContextProps } from "../../types";
+import { useDataDictionaryInitialArgs } from "../UseDataDictionaryInitialArgs/hook";
+
+export const useDataDictionaryReducer = (): DataDictionaryStateContextProps => {
+  const initialArgs = useDataDictionaryInitialArgs();
+
+  const [dataDictionaryState, dataDictionaryDispatch] = useReducer(
+    dataDictionaryReducer,
+    initialArgs,
+    initializer
+  );
+
+  return { dataDictionaryDispatch, dataDictionaryState };
+};

package/src/providers/dataDictionaryState/hooks/UseDataDictionaryState/hook.ts

@@ -0,0 +1,11 @@
+import { useContext } from "react";
+import { DataDictionaryStateContext } from "../../context";
+import { DataDictionaryStateContextProps } from "../../types";
+
+/**
+ * Returns data dictionary state context.
+ * @returns data dictionary state context.
+ */
+export const useDataDictionaryState = (): DataDictionaryStateContextProps => {
+  return useContext(DataDictionaryStateContext);
+};

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

@@ -0,0 +1,6 @@
+import { DataDictionaryState } from "../types";
+
+export const INITIAL_DATA_DICTIONARY_STATE: DataDictionaryState = {
+  dictionaries: {},
+  meta: null,
+};

package/src/providers/dataDictionaryState/initializer/initializer.ts

@@ -0,0 +1,22 @@
+import { UseDataDictionaryInitialArgs } from "../hooks/UseDataDictionaryInitialArgs/types";
+import { DataDictionaryState } from "../types";
+import { INITIAL_DATA_DICTIONARY_STATE } from "./constants";
+import { initDictionaries } from "./utils";
+
+/**
+ * Initializer function for the data dictionary reducer, returning initial state.
+ * @param initialArgs - Initial arguments.
+ * @param initialArgs.dataDictionaries - Data dictionary configs.
+ * @returns The initialized data dictionary state.
+ */
+export function initializer({
+  dataDictionaries,
+}: UseDataDictionaryInitialArgs): DataDictionaryState {
+  // If no data dictionary configs are provided, return default initial state.
+  if (!dataDictionaries) return INITIAL_DATA_DICTIONARY_STATE;
+
+  return {
+    dictionaries: initDictionaries(dataDictionaries),
+    meta: null,
+  };
+}

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

@@ -0,0 +1,39 @@
+import { TableState } from "@tanstack/react-table";
+import { DataDictionaryConfig } from "../../../common/entities";
+import { initPaginationState } from "../../../components/Table/coreOptions/state/pagination/utils";
+import { DictionariesContext } from "../dictionaries/types";
+
+/**
+ * Initializes the dictionaries context.
+ * @param dataDictionaries - The data dictionary configs.
+ * @returns The initialized dictionaries context.
+ */
+export function initDictionaries(
+  dataDictionaries: DataDictionaryConfig[]
+): DictionariesContext {
+  return dataDictionaries.reduce((acc, { path, tableOptions }) => {
+    acc[path] = {
+      query: { dictionary: path },
+      state: initState(tableOptions),
+    };
+    return acc;
+  }, {} as DictionariesContext);
+}
+
+/**
+ * Initializes the dictionary state (TanStack Table state).
+ * @param tableOptions - The table options.
+ * @returns The initialized dictionary state.
+ */
+function initState(
+  tableOptions: DataDictionaryConfig["tableOptions"]
+): Partial<TableState> {
+  const { initialState } = tableOptions;
+
+  return {
+    columnFilters: [],
+    globalFilter: undefined,
+    ...initialState,
+    ...initPaginationState(initialState),
+  };
+}

package/src/providers/dataDictionaryState/provider.tsx

@@ -0,0 +1,16 @@
+import React, { ReactNode } from "react";
+import { DataDictionaryStateContext } from "./context";
+import { useDataDictionaryReducer } from "./hooks/UseDataDictionaryReducer/hook";
+
+export function DataDictionaryStateProvider({
+  children,
+}: {
+  children: ReactNode | ReactNode[];
+}): JSX.Element {
+  const reducer = useDataDictionaryReducer();
+  return (
+    <DataDictionaryStateContext.Provider value={reducer}>
+      {children}
+    </DataDictionaryStateContext.Provider>
+  );
+}

package/src/providers/dataDictionaryState/reducer.ts

@@ -0,0 +1,42 @@
+import { clearMetaAction } from "./actions/clearMeta/action";
+import { stateToUrlAction } from "./actions/stateToUrl/action";
+import {
+  DataDictionaryAction,
+  DataDictionaryActionKind,
+} from "./actions/types";
+import { updateColumnFiltersAction } from "./actions/updateColumnFilters/action";
+import { updateGlobalFilterAction } from "./actions/updateGlobalFilter/action";
+import { urlToStateAction } from "./actions/urlToState/action";
+import { DataDictionaryState } from "./types";
+
+/**
+ * Reducer for data dictionary.
+ * @param state - State.
+ * @param action - Action.
+ * @returns state.
+ */
+export function dataDictionaryReducer(
+  state: DataDictionaryState,
+  action: DataDictionaryAction
+): DataDictionaryState {
+  const { payload, type } = action;
+  switch (type) {
+    case DataDictionaryActionKind.ClearMeta: {
+      return clearMetaAction(state, payload);
+    }
+    case DataDictionaryActionKind.StateToUrl: {
+      return stateToUrlAction(state, payload);
+    }
+    case DataDictionaryActionKind.UpdateColumnFilters: {
+      return updateColumnFiltersAction(state, payload);
+    }
+    case DataDictionaryActionKind.UpdateGlobalFilter: {
+      return updateGlobalFilterAction(state, payload);
+    }
+    case DataDictionaryActionKind.UrlToState: {
+      return urlToStateAction(state, payload);
+    }
+    default:
+      return state;
+  }
+}

package/src/providers/dataDictionaryState/types.ts

@@ -0,0 +1,18 @@
+import { Dispatch } from "react";
+import { META_COMMAND } from "../../hooks/stateSyncManager/hooks/UseMetaCommands/types";
+import { DataDictionaryAction } from "./actions/types";
+import { DictionariesContext } from "./dictionaries/types";
+
+export interface DataDictionaryState {
+  dictionaries: DictionariesContext;
+  meta: Meta | null;
+}
+
+export interface DataDictionaryStateContextProps {
+  dataDictionaryDispatch: Dispatch<DataDictionaryAction> | null;
+  dataDictionaryState: DataDictionaryState;
+}
+
+export interface Meta {
+  command: META_COMMAND;
+}

package/src/styles/common/mui/iconButton.ts

@@ -0,0 +1,40 @@
+import { IconButtonProps } from "@mui/material";
+
+type IconButtonPropsOptions = {
+  COLOR: typeof COLOR;
+  EDGE: typeof EDGE;
+  SIZE: typeof SIZE;
+};
+
+const COLOR: Record<string, IconButtonProps["color"]> = {
+  DEFAULT: "default",
+  ERROR: "error",
+  INFO: "info",
+  INHERIT: "inherit",
+  INK: "ink",
+  INK_LIGHT: "inkLight",
+  PRIMARY: "primary",
+  SECONDARY: "secondary",
+  SUCCESS: "success",
+  WARNING: "warning",
+};
+
+const EDGE: Record<string, IconButtonProps["edge"]> = {
+  END: "end",
+  START: "start",
+};
+
+const SIZE: Record<string, IconButtonProps["size"]> = {
+  LARGE: "large",
+  MEDIUM: "medium",
+  SMALL: "small",
+  XLARGE: "xlarge",
+  XSMALL: "xsmall",
+  XXSMALL: "xxsmall",
+};
+
+export const ICON_BUTTON_PROPS: IconButtonPropsOptions = {
+  COLOR,
+  EDGE,
+  SIZE,
+};

package/src/styles/common/mui/inputAdornment.ts

@@ -0,0 +1,22 @@
+import { InputAdornmentProps } from "@mui/material";
+
+type InputAdornmentPropsOptions = {
+  POSITION: typeof POSITION;
+  VARIANT: typeof VARIANT;
+};
+
+const POSITION: Record<string, InputAdornmentProps["position"]> = {
+  END: "end",
+  START: "start",
+};
+
+const VARIANT: Record<string, InputAdornmentProps["variant"]> = {
+  FILLED: "filled",
+  OUTLINED: "outlined",
+  STANDARD: "standard",
+};
+
+export const INPUT_ADORNMENT_PROPS: InputAdornmentPropsOptions = {
+  POSITION,
+  VARIANT,
+};

package/src/styles/common/mui/outlinedInput.ts

@@ -0,0 +1,14 @@
+import { OutlinedInputProps } from "@mui/material";
+
+type OutlinedInputPropsOptions = {
+  COLOR: typeof COLOR;
+};
+
+const COLOR: Record<string, OutlinedInputProps["color"]> = {
+  PRIMARY: "primary",
+  SECONDARY: "secondary",
+};
+
+export const OUTLINED_INPUT_PROPS: OutlinedInputPropsOptions = {
+  COLOR,
+};

package/src/theme/common/components.ts

@@ -5,6 +5,7 @@ import { PALETTE } from "../../styles/common/constants/palette";
 import { SHADOWS } from "../../styles/common/constants/shadows";
 import { BUTTON_PROPS } from "../../styles/common/mui/button";
 import { CHIP_PROPS } from "../../styles/common/mui/chip";
+import { OUTLINED_INPUT_PROPS } from "../../styles/common/mui/outlinedInput";
 import { desktopUp, mobileUp, tabletUp } from "./breakpoints";
 import {
   TEXT_BODY_400,
@@ -256,11 +257,25 @@ export const MuiButton = (theme: Theme): Components["MuiButton"] => {
         minWidth: 0,
         padding: 0,
       },
-      textPrimary: {
-        color: theme.palette.primary.main,
-      },
     },
     variants: [
+      {
+        props: {
+          color: BUTTON_PROPS.COLOR.PRIMARY,
+          variant: BUTTON_PROPS.VARIANT.TEXT,
+        },
+        style: {
+          color: PALETTE.PRIMARY_MAIN,
+          // eslint-disable-next-line sort-keys -- disabling key order for readability
+          "&:hover": {
+            backgroundColor: "transparent",
+            textDecoration: "underline",
+            textDecorationColor: "currentColor",
+            textDecorationSkipInk: "none",
+            textUnderlinePosition: "from-font",
+          },
+        },
+      },
       {
         props: {
           variant: "activeNav", // associated with "nav" variant.
@@ -439,6 +454,16 @@ export const MuiChip = (theme: Theme): Components["MuiChip"] => {
           color: theme.palette.info.main,
         },
       },
+      {
+        props: {
+          color: CHIP_PROPS.COLOR.PRIMARY,
+          variant: CHIP_PROPS.VARIANT.FILLED,
+        },
+        style: {
+          backgroundColor: PALETTE.PRIMARY_MAIN,
+          color: PALETTE.COMMON_WHITE,
+        },
+      },
       {
         props: { color: "success" },
         style: {
@@ -866,9 +891,6 @@ export const MuiIconButton = (theme: Theme): Components["MuiIconButton"] => {
 export const MuiInputBase = (theme: Theme): Components["MuiInputBase"] => {
   return {
     styleOverrides: {
-      adornedStart: {
-        gap: 8,
-      },
       multiline: {
         height: "unset",
       },
@@ -881,6 +903,17 @@ export const MuiInputBase = (theme: Theme): Components["MuiInputBase"] => {
         [tabletUp]: {
           fontSize: theme.typography[TEXT_BODY_400].fontSize,
         },
+        variants: [
+          /* PRIMARY */ /* TODO: remove `adornedStart` when all input components are refactored to color: secondary */
+          {
+            props: { color: "primary" },
+            style: {
+              adornedStart: {
+                gap: 8,
+              },
+            },
+          },
+        ],
       },
     },
   };
@@ -1012,11 +1045,8 @@ export const MuiOutlinedInput = (
       root: {
         backgroundColor: PALETTE.COMMON_WHITE,
         boxShadow: `inset 0 2px 0 0 ${COLOR_MIXES.COMMON_BLACK_04}`,
-        paddingLeft: 12,
+        paddingLeft: 12, // TODO: remove when all input components are refactored to color: secondary.
         // eslint-disable-next-line sort-keys -- disabling key order for readability
-        "& .MuiSvgIcon-root": {
-          color: theme.palette.ink.light, // Adornment e.g. "SearchIcon".
-        },
         "&:hover": {
           "& .MuiOutlinedInput-notchedOutline": {
             borderColor: theme.palette.smoke.dark,
@@ -1028,9 +1058,6 @@ export const MuiOutlinedInput = (
             borderColor: theme.palette.ink.main,
             borderWidth: 1,
           },
-          "& .MuiSvgIcon-root": {
-            color: theme.palette.ink.main, // Adornment e.g. "SearchIcon".
-          },
         },
         // eslint-disable-next-line sort-keys -- disabling key order for specificity
         "&.Mui-disabled": {
@@ -1038,9 +1065,6 @@ export const MuiOutlinedInput = (
             borderColor: theme.palette.smoke.dark,
             borderWidth: 1,
           },
-          "& .MuiSvgIcon-root": {
-            color: theme.palette.ink.light,
-          },
         },
         "&.Mui-error": {
           backgroundColor: theme.palette.alert.lightest,
@@ -1050,6 +1074,88 @@ export const MuiOutlinedInput = (
             borderWidth: 1,
           },
         },
+        variants: [
+          /* PRIMARY */
+          {
+            props: { color: OUTLINED_INPUT_PROPS.COLOR.PRIMARY },
+            style: {
+              "& .MuiSvgIcon-root": {
+                color: theme.palette.ink.light, // Adornment e.g. "SearchIcon". TODO: remove when all input components are refactored to color: secondary.
+              },
+              // eslint-disable-next-line sort-keys -- disabling key order for specificity
+              "&.Mui-focused": {
+                "& .MuiSvgIcon-root": {
+                  color: theme.palette.ink.main, // Adornment e.g. "SearchIcon". TODO: remove when all input components are refactored to color: secondary.
+                },
+              },
+              // eslint-disable-next-line sort-keys -- disabling key order for specificity
+              "&.Mui-disabled": {
+                "& .MuiSvgIcon-root": {
+                  color: theme.palette.ink.light, // TODO: remove when all input components are refactored to color: secondary.
+                },
+              },
+            },
+          },
+          /* SECONDARY */
+          {
+            props: { color: OUTLINED_INPUT_PROPS.COLOR.SECONDARY },
+            style: {
+              backgroundColor: PALETTE.COMMON_WHITE,
+              boxShadow: `inset 0 2px 0 0 ${COLOR_MIXES.COMMON_BLACK_04}`,
+              color: PALETTE.INK_LIGHT,
+              padding: "0 12px",
+              // eslint-disable-next-line sort-keys -- disabling key order for specificity
+              ".MuiOutlinedInput-input": {
+                color: "inherit",
+                height: 20,
+                padding: "10px 0",
+                // eslint-disable-next-line sort-keys -- disabling key order for specificity
+                "&::placeholder": {
+                  color: "inherit",
+                  opacity: 0.8,
+                },
+              },
+              ".MuiOutlinedInput-notchedOutline": {
+                borderColor: PALETTE.SMOKE_DARK,
+                borderWidth: 1,
+              },
+              // eslint-disable-next-line sort-keys -- disabling key order for specificity
+              "&.Mui-focused": {
+                color: PALETTE.INK_MAIN,
+                // eslint-disable-next-line sort-keys -- disabling key order for specificity
+                ".MuiOutlinedInput-input": {
+                  "&::placeholder": {
+                    opacity: 0,
+                  },
+                },
+                // eslint-disable-next-line sort-keys -- disabling key order for specificity
+                ".MuiOutlinedInput-notchedOutline": {
+                  borderColor: PALETTE.INK_MAIN,
+                  borderWidth: 1,
+                },
+              },
+              // eslint-disable-next-line sort-keys -- disabling key order for specificity
+              "&.Mui-disabled": {
+                backgroundColor: PALETTE.SMOKE_LIGHT,
+                color: PALETTE.INK_LIGHT,
+                // eslint-disable-next-line sort-keys -- disabling key order for specificity
+                ".MuiOutlinedInput-input": {
+                  WebkitTextFillColor: "unset",
+                  // eslint-disable-next-line sort-keys -- disabling key order for specificity
+                  "&::placeholder": {
+                    color: "inherit",
+                    opacity: 1,
+                  },
+                },
+                // eslint-disable-next-line sort-keys -- disabling key order for specificity
+                ".MuiOutlinedInput-notchedOutline": {
+                  borderColor: PALETTE.SMOKE_DARK,
+                  borderWidth: 1,
+                },
+              },
+            },
+          },
+        ],
       },
     },
   };

package/src/theme/components/muiButtonGroup.ts

@@ -59,6 +59,10 @@ export const MuiButtonGroup: Components["MuiButtonGroup"] = {
                 backgroundColor: PALETTE.SMOKE_LIGHTEST,
                 boxShadow: `inset 0 0 0 1px ${PALETTE.SMOKE_DARK}`,
               },
+              // eslint-disable-next-line sort-keys -- disabling key order for readability
+              "&.Mui-focusVisible": {
+                boxShadow: `inset 0 0 0 1px ${PALETTE.SMOKE_DARK}, 0 1px 0 0 ${COLOR_MIXES.COMMON_BLACK_08}`,
+              },
             },
           },
         },

package/src/theme/components/muiTableCell.ts

@@ -1,4 +1,5 @@
 import { Components, Theme } from "@mui/material";
+import { PALETTE } from "../../styles/common/constants/palette";
 import { TABLE_CELL_PROPS } from "../../styles/common/mui/tableCell";
 import { TEXT_BODY_400, TEXT_BODY_SMALL_500 } from "../common/typography";
 
@@ -34,6 +35,11 @@ export const MuiTableCell = (theme: Theme): Components["MuiTableCell"] => {
             props: { variant: TABLE_CELL_PROPS.VARIANT.BODY },
             style: {
               ...typography[TEXT_BODY_400],
+              "& mark": {
+                backgroundColor: PALETTE.WARNING_LIGHT,
+                color: "inherit",
+                padding: "2px 0",
+              },
             },
           },
           {

package/src/utils/parseJsonQueryParam.ts

@@ -0,0 +1,27 @@
+/**
+ * Parses a JSON-encoded value from a URL query parameter.
+ *
+ * This function is specifically designed for query parameters that contain
+ * serialized complex data (arrays or objects), not for simple string values.
+ *
+ * It handles Next.js query parameters which can be string, string[] or undefined.
+ * Repeated parameters (`string[]`) are not supported.
+ *
+ * @param param - URL query parameter value.
+ * @param defaultValue - Default value.
+ * @returns Parsed complex data structure or default value.
+ */
+export function parseJsonQueryParam<T = unknown>(
+  param: string | string[] | undefined,
+  defaultValue?: T
+): T | undefined {
+  // Handle non-string parameters.
+  if (typeof param !== "string") return defaultValue;
+
+  try {
+    return JSON.parse(decodeURIComponent(param));
+  } catch (error) {
+    console.warn("Failed to parse query param JSON:", error);
+    return defaultValue;
+  }
+}