@databiosphere/findable-ui 51.1.0 → 52.1.0

package/lib/common/filters/adapters/tanstack/typeGuards.d.ts

@@ -0,0 +1,7 @@
+import type { ColumnFilter } from "@tanstack/react-table";
+/**
+ * Returns true if the value is a valid TanStack ColumnFilter shape.
+ * @param value - Value to check.
+ * @returns true if the value has the expected shape.
+ */
+export declare function isColumnFilter(value: unknown): value is ColumnFilter;

package/lib/common/filters/adapters/tanstack/typeGuards.js

@@ -0,0 +1,11 @@
+/**
+ * Returns true if the value is a valid TanStack ColumnFilter shape.
+ * @param value - Value to check.
+ * @returns true if the value has the expected shape.
+ */
+export function isColumnFilter(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const filter = value;
+    return typeof filter.id === "string" && "value" in filter;
+}

package/lib/common/filters/hooks/UseValidateFilterKeys/hook.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Validates the filter query parameter shape only (no key validation).
+ * Throws a DataExplorerError during render if the filter param is present
+ * but contains malformed JSON or an invalid entry shape.
+ * @param queryParamKey - URL query parameter key to read (e.g. "filter").
+ * @param validKeys - Must be undefined to use this overload.
+ * @param entryValidator - Type guard that validates each parsed entry's shape.
+ * @returns void; throws DataExplorerError on invalid input.
+ */
+export declare function useValidateFilterKeys(queryParamKey: string, validKeys: undefined, entryValidator: (value: unknown) => boolean): void;
+/**
+ * Validates the filter query parameter shape and keys against a valid set.
+ * Throws a DataExplorerError during render if the filter param is present
+ * but contains malformed JSON, an invalid entry shape, or a key that
+ * is not in the valid set.
+ * @param queryParamKey - URL query parameter key to read (e.g. "filter").
+ * @param validKeys - Set of valid keys.
+ * @param entryValidator - Type guard that validates each parsed entry's shape.
+ * @param keyExtractor - Extracts the key string from a validated entry.
+ * @returns void; throws DataExplorerError on invalid input.
+ */
+export declare function useValidateFilterKeys(queryParamKey: string, validKeys: Set<string>, entryValidator: (value: unknown) => boolean, keyExtractor: (entry: unknown) => string): void;
+/**
+ * Validates the filter query parameter shape and, when validKeys is defined,
+ * keys against the valid set. Use when validKeys is dynamically determined.
+ * @param queryParamKey - URL query parameter key to read (e.g. "filter").
+ * @param validKeys - Set of valid keys, or undefined to skip key validation.
+ * @param entryValidator - Type guard that validates each parsed entry's shape.
+ * @param keyExtractor - Extracts the key string from a validated entry.
+ * @returns void; throws DataExplorerError on invalid input.
+ */
+export declare function useValidateFilterKeys(queryParamKey: string, validKeys: Set<string> | undefined, entryValidator: (value: unknown) => boolean, keyExtractor: (entry: unknown) => string): void;

package/lib/common/filters/hooks/UseValidateFilterKeys/hook.js

@@ -0,0 +1,16 @@
+import { useRouter } from "next/router";
+import { useMemo } from "react";
+import { validateFilterParam } from "./utils";
+export function useValidateFilterKeys(queryParamKey, validKeys, entryValidator, keyExtractor) {
+    const { query } = useRouter();
+    const filterParam = query[queryParamKey];
+    const validationError = useMemo(() => {
+        if (validKeys && keyExtractor) {
+            return validateFilterParam(filterParam, validKeys, entryValidator, keyExtractor);
+        }
+        return validateFilterParam(filterParam, undefined, entryValidator);
+    }, [entryValidator, filterParam, keyExtractor, validKeys]);
+    if (validationError) {
+        throw validationError;
+    }
+}

package/lib/common/filters/hooks/UseValidateFilterKeys/utils.d.ts

@@ -0,0 +1,18 @@
+import { DataExplorerError } from "../../../../types/error";
+/**
+ * Validates a filter query parameter value (shape only, no key validation).
+ * @param filterParam - Raw URL query param value.
+ * @param validKeys - Must be undefined to use this overload.
+ * @param entryValidator - Type guard that validates each parsed entry's shape.
+ * @returns DataExplorerError if invalid, undefined if valid.
+ */
+export declare function validateFilterParam(filterParam: string | string[] | undefined, validKeys: undefined, entryValidator: (value: unknown) => boolean): DataExplorerError | undefined;
+/**
+ * Validates a filter query parameter value against a set of valid keys.
+ * @param filterParam - Raw URL query param value.
+ * @param validKeys - Set of valid keys.
+ * @param entryValidator - Type guard that validates each parsed entry's shape.
+ * @param keyExtractor - Extracts the key string from a validated entry.
+ * @returns DataExplorerError if invalid, undefined if valid.
+ */
+export declare function validateFilterParam(filterParam: string | string[] | undefined, validKeys: Set<string>, entryValidator: (value: unknown) => boolean, keyExtractor: (entry: unknown) => string): DataExplorerError | undefined;

package/lib/common/filters/hooks/UseValidateFilterKeys/utils.js

@@ -0,0 +1,47 @@
+import { DataExplorerError } from "../../../../types/error";
+const INVALID_FILTER_PARAM = "Invalid filter parameter in URL";
+const INVALID_FILTER_SHAPE = "Invalid filter entry shape in URL";
+const UNKNOWN_FILTER_KEY = "Unknown filter key in URL";
+export function validateFilterParam(filterParam, validKeys, entryValidator, keyExtractor) {
+    if (filterParam === undefined)
+        return undefined;
+    if (typeof filterParam !== "string") {
+        return new DataExplorerError({ message: INVALID_FILTER_PARAM });
+    }
+    // Try JSON.parse directly first (Next.js router.query already decodes),
+    // then fall back to decodeURIComponent + JSON.parse for encoded values.
+    let parsed;
+    try {
+        parsed = JSON.parse(filterParam);
+    }
+    catch {
+        try {
+            parsed = JSON.parse(decodeURIComponent(filterParam));
+        }
+        catch {
+            return new DataExplorerError({ message: INVALID_FILTER_PARAM });
+        }
+    }
+    if (!Array.isArray(parsed)) {
+        return new DataExplorerError({ message: INVALID_FILTER_PARAM });
+    }
+    // An empty array (e.g. "[]") is valid — it means no filters selected.
+    if (parsed.length === 0)
+        return undefined;
+    // Validate shape: every entry must match the expected shape.
+    if (!parsed.every(entryValidator)) {
+        return new DataExplorerError({ message: INVALID_FILTER_SHAPE });
+    }
+    // Validate keys: every extracted key must be in the valid set.
+    if (validKeys && keyExtractor) {
+        const invalidKey = parsed
+            .map(keyExtractor)
+            .find((key) => !validKeys.has(key));
+        if (invalidKey !== undefined) {
+            return new DataExplorerError({
+                message: `${UNKNOWN_FILTER_KEY}: ${invalidKey}`,
+            });
+        }
+    }
+    return undefined;
+}

package/lib/common/filters/typeGuards.d.ts

@@ -1,4 +1,4 @@
-import { SelectedFilter } from "../entities";
+import type { SelectedFilter } from "../entities";
 /**
  * Returns true if the value is a valid SelectedFilter.
  * @param value - Value to check.

package/lib/components/DataDictionary/dataDictionary.js

@@ -1,8 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fade } from "@mui/material";
+import { useMemo } from "react";
+import { isColumnFilter } from "../../common/filters/adapters/tanstack/typeGuards";
+import { useValidateFilterKeys } from "../../common/filters/hooks/UseValidateFilterKeys/hook";
 import { PROPERTY } from "../../hooks/useHtmlStyle/constants";
 import { useHtmlStyle } from "../../hooks/useHtmlStyle/hook";
 import { useLayoutSpacing } from "../../hooks/UseLayoutSpacing/hook";
+import { DATA_DICTIONARY_URL_PARAMS } from "../../providers/dataDictionaryState/dictionaries/constants";
 import { Description } from "./components/Description/description";
 import { Entities } from "./components/Entities/entities";
 import { ColumnFilterTags } from "./components/Filters/components/ColumnFilterTags/columnFilterTags";
@@ -18,6 +22,7 @@ import { Title as DefaultTitle } from "./components/Title/title";
 import { View } from "./dataDictionary.styles";
 import { useDataDictionaryConfig } from "./hooks/UseDataDictionaryConfig/hook";
 import { useMeasureFilters } from "./hooks/UseMeasureFilters/hook";
+import { extractColumnId, getValidColumnIds } from "./utils";
 export const DataDictionary = ({ className, dictionary, EntitiesLayout = DefaultEntitiesLayout, FiltersLayout = DefaultFiltersLayout, Outline = DefaultOutline, OutlineLayout = DefaultOutlineLayout, Title = DefaultTitle, TitleLayout = DefaultTitleLayout, }) => {
     // Get dictionary configuration.
     const { classes, description, tableOptions, title } = useDataDictionaryConfig(dictionary);
@@ -30,6 +35,9 @@ export const DataDictionary = ({ className, dictionary, EntitiesLayout = Default
     const entitiesSpacing = { ...spacing, top: dimensions.height };
     // Table instance.
     const table = useTable(dictionary, classes, tableOptions);
+    // Validate filter URL param keys against the table's column IDs.
+    const validColumnIds = useMemo(() => getValidColumnIds(table), [table]);
+    useValidateFilterKeys(DATA_DICTIONARY_URL_PARAMS.COLUMN_FILTERS, validColumnIds, isColumnFilter, extractColumnId);
     // Dictionary outline.
     const outline = buildClassesOutline(table);
     // Update scroll-padding-top on the HTML element.

package/lib/components/DataDictionary/utils.d.ts

@@ -0,0 +1,13 @@
+import type { RowData, Table } from "@tanstack/react-table";
+/**
+ * Extracts the column ID from a validated ColumnFilter entry.
+ * @param entry - Validated entry.
+ * @returns column ID.
+ */
+export declare function extractColumnId(entry: unknown): string;
+/**
+ * Returns the set of valid column IDs from a TanStack table instance.
+ * @param table - TanStack table instance.
+ * @returns set of valid column IDs.
+ */
+export declare function getValidColumnIds<T extends RowData>(table: Table<T>): Set<string>;

package/lib/components/DataDictionary/utils.js

@@ -0,0 +1,16 @@
+/**
+ * Extracts the column ID from a validated ColumnFilter entry.
+ * @param entry - Validated entry.
+ * @returns column ID.
+ */
+export function extractColumnId(entry) {
+    return entry.id;
+}
+/**
+ * Returns the set of valid column IDs from a TanStack table instance.
+ * @param table - TanStack table instance.
+ * @returns set of valid column IDs.
+ */
+export function getValidColumnIds(table) {
+    return new Set(table.getAllColumns().map((column) => column.id));
+}

package/lib/config/entities.d.ts

@@ -219,7 +219,11 @@ export interface ListViewConfig {
     rowPreviewView?: ComponentsConfig;
     rowSelectionView?: ComponentsConfig;
 }
-export interface OAuthProvider<P = any> {
+export declare enum OAUTH_FLOW {
+    AUTHORIZATION_CODE = "AUTHORIZATION_CODE",
+    IMPLICIT = "IMPLICIT"
+}
+interface OAuthProviderBase<P = any> {
     authorization: {
         params: {
             scope: string;
@@ -232,6 +236,14 @@ export interface OAuthProvider<P = any> {
     profile: (profile: P) => UserProfile;
     userinfo: string;
 }
+export interface ImplicitFlowProvider<P = any> extends OAuthProviderBase<P> {
+    flow: OAUTH_FLOW.IMPLICIT;
+}
+export interface AuthorizationCodeFlowProvider<P = any> extends OAuthProviderBase<P> {
+    authorize: string;
+    flow: OAUTH_FLOW.AUTHORIZATION_CODE;
+}
+export type OAuthProvider<P = any> = ImplicitFlowProvider<P> | AuthorizationCodeFlowProvider<P>;
 /**
  * Option Method.
  */

package/lib/config/entities.js

@@ -1,3 +1,8 @@
+export var OAUTH_FLOW;
+(function (OAUTH_FLOW) {
+    OAUTH_FLOW["AUTHORIZATION_CODE"] = "AUTHORIZATION_CODE";
+    OAUTH_FLOW["IMPLICIT"] = "IMPLICIT";
+})(OAUTH_FLOW || (OAUTH_FLOW = {}));
 /**
  * Sort direction.
  */

package/lib/google/service.d.ts

@@ -1,15 +1,17 @@
-import { OAuthProvider } from "../config/entities";
-import { SessionDispatch } from "./types";
+import { type OAuthProvider } from "../config/entities";
+import { type LoginDispatch } from "./services/common";
+import type { SessionDispatch } from "./types";
 /**
  * Google Sign-In service.
  */
 export declare const service: {
     /**
      * Login with Google OAuth.
+     * Dispatches to the configured flow based on `provider.flow`.
      * @param provider - OAuth provider configuration.
      * @param dispatch - Dispatch functions for auth state.
      */
-    login: (provider: OAuthProvider, dispatch: Pick<SessionDispatch, "authDispatch" | "authenticationDispatch" | "tokenDispatch">) => void;
+    login: (provider: OAuthProvider, dispatch: LoginDispatch) => void;
     /**
      * Logout and clear all auth state.
      * @param dispatch - Dispatch functions for auth state.

package/lib/google/service.js

@@ -1,54 +1,30 @@
-import { requestAuth, resetAuthState } from "../auth/dispatch/auth";
-import { requestAuthentication, resetAuthenticationState, updateAuthentication, } from "../auth/dispatch/authentication";
-import { resetCredentialsState } from "../auth/dispatch/credentials";
-import { resetTokenState, updateToken } from "../auth/dispatch/token";
-import { AUTHENTICATION_STATUS } from "../auth/types/authentication";
-import { fetchProfile, getAuthenticationRequestOptions } from "./utils/auth";
+import { OAUTH_FLOW } from "../config/entities";
+import { login as authorizationCodeFlowLogin } from "./services/authorizationCodeFlow";
+import { logout } from "./services/common";
+import { login as implicitFlowLogin } from "./services/implicitFlow";
 /**
  * Google Sign-In service.
  */
 export const service = {
     /**
      * Login with Google OAuth.
+     * Dispatches to the configured flow based on `provider.flow`.
      * @param provider - OAuth provider configuration.
      * @param dispatch - Dispatch functions for auth state.
      */
     login: (provider, dispatch) => {
-        const client = google.accounts.oauth2.initTokenClient({
-            callback: (response) => {
-                const { id, profile, userinfo } = provider;
-                const { access_token: token } = response;
-                dispatch.authDispatch?.(requestAuth());
-                dispatch.authenticationDispatch?.(requestAuthentication());
-                dispatch.tokenDispatch?.(updateToken({ providerId: id, token }));
-                fetchProfile(userinfo, getAuthenticationRequestOptions(token), {
-                    onError: () => {
-                        dispatch.authDispatch?.(resetAuthState());
-                        dispatch.authenticationDispatch?.(updateAuthentication({
-                            profile: undefined,
-                            status: AUTHENTICATION_STATUS.SETTLED,
-                        }));
-                        dispatch.tokenDispatch?.(resetTokenState());
-                    },
-                    onSuccess: (r) => dispatch.authenticationDispatch?.(updateAuthentication({
-                        profile: profile(r),
-                        status: AUTHENTICATION_STATUS.PENDING, // Authentication is pending until session controller is resolved.
-                    })),
-                });
-            },
-            client_id: provider.clientId,
-            scope: provider.authorization.params.scope,
-        });
-        client.requestAccessToken();
+        if (provider.flow === OAUTH_FLOW.AUTHORIZATION_CODE) {
+            authorizationCodeFlowLogin(provider, dispatch);
+        }
+        else {
+            implicitFlowLogin(provider, dispatch);
+        }
     },
     /**
      * Logout and clear all auth state.
      * @param dispatch - Dispatch functions for auth state.
      */
     logout: (dispatch) => {
-        dispatch.authDispatch?.(resetAuthState());
-        dispatch.authenticationDispatch?.(resetAuthenticationState());
-        dispatch.credentialsDispatch?.(resetCredentialsState());
-        dispatch.tokenDispatch?.(resetTokenState());
+        logout(dispatch);
     },
 };

package/lib/google/services/authorizationCodeFlow.d.ts

@@ -0,0 +1,10 @@
+import type { AuthorizationCodeFlowProvider } from "../../config/entities";
+import { type LoginDispatch } from "./common";
+/**
+ * Login using the OAuth 2.0 authorization code flow.
+ * Uses Google's initCodeClient to request an authorization code,
+ * then exchanges it for an access token via the configured authorize endpoint.
+ * @param provider - OAuth provider configuration.
+ * @param dispatch - Dispatch functions for auth state.
+ */
+export declare function login(provider: AuthorizationCodeFlowProvider, dispatch: LoginDispatch): void;

package/lib/google/services/authorizationCodeFlow.js

@@ -0,0 +1,38 @@
+import { createOnAccessToken, createResetSession, } from "./common";
+/**
+ * Login using the OAuth 2.0 authorization code flow.
+ * Uses Google's initCodeClient to request an authorization code,
+ * then exchanges it for an access token via the configured authorize endpoint.
+ * @param provider - OAuth provider configuration.
+ * @param dispatch - Dispatch functions for auth state.
+ */
+export function login(provider, dispatch) {
+    const { authorize } = provider;
+    const resetSession = createResetSession(dispatch);
+    const onAccessToken = createOnAccessToken(provider, dispatch, resetSession);
+    const client = google.accounts.oauth2.initCodeClient({
+        callback: (response) => {
+            fetch(authorize, {
+                body: JSON.stringify(response),
+                headers: { "Content-Type": "application/json" },
+                method: "POST",
+            })
+                .then((r) => {
+                if (!r.ok) {
+                    throw new Error(`authorize request failed (${r.status})`);
+                }
+                return r.json();
+            })
+                .then((tokens) => {
+                if (!tokens?.access_token) {
+                    throw new Error("authorize response missing access_token");
+                }
+                onAccessToken(tokens.access_token);
+            })
+                .catch(resetSession);
+        },
+        client_id: provider.clientId,
+        scope: provider.authorization.params.scope,
+    });
+    client.requestCode();
+}

package/lib/google/services/common.d.ts

@@ -0,0 +1,23 @@
+import type { OAuthProvider } from "../../config/entities";
+import type { SessionDispatch } from "../types";
+export type LoginDispatch = Pick<SessionDispatch, "authDispatch" | "authenticationDispatch" | "tokenDispatch">;
+/**
+ * Creates a function that resets the session state on auth failure.
+ * @param dispatch - Dispatch functions for auth state.
+ * @returns reset session function.
+ */
+export declare function createResetSession(dispatch: LoginDispatch): () => void;
+/**
+ * Creates a function that handles a successful access token.
+ * Dispatches auth state updates and fetches the user profile.
+ * @param provider - OAuth provider configuration.
+ * @param dispatch - Dispatch functions for auth state.
+ * @param resetSession - Reset session function.
+ * @returns on access token function.
+ */
+export declare function createOnAccessToken(provider: OAuthProvider, dispatch: LoginDispatch, resetSession: () => void): (token: string) => void;
+/**
+ * Logout and clear all auth state.
+ * @param dispatch - Dispatch functions for auth state.
+ */
+export declare function logout(dispatch: SessionDispatch): void;

package/lib/google/services/common.js

@@ -0,0 +1,54 @@
+import { requestAuth, resetAuthState } from "../../auth/dispatch/auth";
+import { requestAuthentication, resetAuthenticationState, updateAuthentication, } from "../../auth/dispatch/authentication";
+import { resetCredentialsState } from "../../auth/dispatch/credentials";
+import { resetTokenState, updateToken } from "../../auth/dispatch/token";
+import { AUTHENTICATION_STATUS } from "../../auth/types/authentication";
+import { fetchProfile, getAuthenticationRequestOptions } from "../utils/auth";
+/**
+ * Creates a function that resets the session state on auth failure.
+ * @param dispatch - Dispatch functions for auth state.
+ * @returns reset session function.
+ */
+export function createResetSession(dispatch) {
+    return () => {
+        dispatch.authDispatch?.(resetAuthState());
+        dispatch.authenticationDispatch?.(updateAuthentication({
+            profile: undefined,
+            status: AUTHENTICATION_STATUS.SETTLED,
+        }));
+        dispatch.tokenDispatch?.(resetTokenState());
+    };
+}
+/**
+ * Creates a function that handles a successful access token.
+ * Dispatches auth state updates and fetches the user profile.
+ * @param provider - OAuth provider configuration.
+ * @param dispatch - Dispatch functions for auth state.
+ * @param resetSession - Reset session function.
+ * @returns on access token function.
+ */
+export function createOnAccessToken(provider, dispatch, resetSession) {
+    const { id, profile, userinfo } = provider;
+    return (token) => {
+        dispatch.authDispatch?.(requestAuth());
+        dispatch.authenticationDispatch?.(requestAuthentication());
+        dispatch.tokenDispatch?.(updateToken({ providerId: id, token }));
+        fetchProfile(userinfo, getAuthenticationRequestOptions(token), {
+            onError: resetSession,
+            onSuccess: (r) => dispatch.authenticationDispatch?.(updateAuthentication({
+                profile: profile(r),
+                status: AUTHENTICATION_STATUS.PENDING,
+            })),
+        });
+    };
+}
+/**
+ * Logout and clear all auth state.
+ * @param dispatch - Dispatch functions for auth state.
+ */
+export function logout(dispatch) {
+    dispatch.authDispatch?.(resetAuthState());
+    dispatch.authenticationDispatch?.(resetAuthenticationState());
+    dispatch.credentialsDispatch?.(resetCredentialsState());
+    dispatch.tokenDispatch?.(resetTokenState());
+}

package/lib/google/services/implicitFlow.d.ts

@@ -0,0 +1,9 @@
+import type { ImplicitFlowProvider } from "../../config/entities";
+import { type LoginDispatch } from "./common";
+/**
+ * Login using the OAuth 2.0 implicit flow.
+ * Uses Google's initTokenClient to request an access token directly.
+ * @param provider - OAuth provider configuration.
+ * @param dispatch - Dispatch functions for auth state.
+ */
+export declare function login(provider: ImplicitFlowProvider, dispatch: LoginDispatch): void;

package/lib/google/services/implicitFlow.js

@@ -0,0 +1,17 @@
+import { createOnAccessToken, createResetSession, } from "./common";
+/**
+ * Login using the OAuth 2.0 implicit flow.
+ * Uses Google's initTokenClient to request an access token directly.
+ * @param provider - OAuth provider configuration.
+ * @param dispatch - Dispatch functions for auth state.
+ */
+export function login(provider, dispatch) {
+    const resetSession = createResetSession(dispatch);
+    const onAccessToken = createOnAccessToken(provider, dispatch, resetSession);
+    const client = google.accounts.oauth2.initTokenClient({
+        callback: (response) => onAccessToken(response.access_token),
+        client_id: provider.clientId,
+        scope: provider.authorization.params.scope,
+    });
+    client.requestAccessToken();
+}

package/lib/google/types.d.ts

@@ -3,6 +3,17 @@ import { AuthAction, AuthContextProps } from "../auth/types/auth";
 import { AuthenticationAction, AuthenticationContextProps } from "../auth/types/authentication";
 import { CredentialsAction, CredentialsContextProps } from "../auth/types/credentials";
 import { TokenAction, TokenContextProps, TokenState } from "../auth/types/token";
+/**
+ * Authorization code response from Google OAuth.
+ */
+export interface CodeResponse {
+    code?: string;
+    error?: string;
+    error_description?: string;
+    error_uri?: string;
+    scope?: string;
+    state?: string;
+}
 /**
  * Google Sign-In authentication provider props.
  */

package/lib/providers/exploreState/initializer/utils.d.ts

@@ -1,5 +1,12 @@
-import { SiteConfig } from "../../../config/entities";
+import { CategoryGroupConfig, EntityConfig, SiteConfig } from "../../../config/entities";
 import { ExploreState } from "../../exploreState";
+/**
+ * Returns entity related configured category group config where entity config takes precedence over site config.
+ * @param siteConfig - Site config.
+ * @param entityConfig - Entity config.
+ * @returns entity related category group config.
+ */
+export declare function getEntityCategoryGroupConfig(siteConfig: SiteConfig, entityConfig: EntityConfig): CategoryGroupConfig | undefined;
 /**
  * Returns the explore state reducer initial arguments.
  * @param config - Site config.

package/lib/providers/exploreState/initializer/utils.js

@@ -80,7 +80,7 @@ function columnFiltersToSelectedFilters(columnFilters) {
  * @param entityConfig - Entity config.
  * @returns entity related category group config.
  */
-function getEntityCategoryGroupConfig(siteConfig, entityConfig) {
+export function getEntityCategoryGroupConfig(siteConfig, entityConfig) {
     const siteCategoryGroupConfig = siteConfig.categoryGroupConfig;
     const entityCategoryGroupConfig = entityConfig.categoryGroupConfig;
     return entityCategoryGroupConfig ?? siteCategoryGroupConfig;

package/lib/views/DataDictionaryView/dataDictionaryView.js

@@ -1,14 +1,20 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { isColumnFilter } from "../../common/filters/adapters/tanstack/typeGuards";
+import { useValidateFilterKeys } from "../../common/filters/hooks/UseValidateFilterKeys/hook";
 import { DataDictionary } from "../../components/DataDictionary/dataDictionary";
 import { useStateSyncManager } from "../../hooks/stateSyncManager/hook";
 import { DataDictionaryContext } from "../../providers/dataDictionary/context";
 import { clearMeta } from "../../providers/dataDictionaryState/actions/clearMeta/dispatch";
 import { stateToUrl } from "../../providers/dataDictionaryState/actions/stateToUrl/dispatch";
 import { urlToState } from "../../providers/dataDictionaryState/actions/urlToState/dispatch";
+import { DATA_DICTIONARY_URL_PARAMS } from "../../providers/dataDictionaryState/dictionaries/constants";
 import { useDataDictionaryState } from "../../providers/dataDictionaryState/hooks/UseDataDictionaryState/hook";
 import { buildStateSyncManagerContext } from "./utils";
 export const DataDictionaryView = ({ className, dictionary, }) => {
     const { dataDictionaryDispatch, dataDictionaryState } = useDataDictionaryState();
+    // Shape-only validation (no key check) — must run before useStateSyncManager
+    // to prevent malformed entries from being dispatched into state.
+    useValidateFilterKeys(DATA_DICTIONARY_URL_PARAMS.COLUMN_FILTERS, undefined, isColumnFilter);
     useStateSyncManager({
         actions: { clearMeta, stateToUrl, urlToState },
         dispatch: dataDictionaryDispatch,

package/lib/views/ExploreView/hooks/UseValidateFilterParam/hook.d.ts

@@ -1,8 +1,9 @@
 /**
- * Validates the filter query parameter from the URL.
+ * Validates the filter query parameter from the URL for the ExploreView.
  * Throws a DataExplorerError during render if the filter param is present
- * but contains malformed JSON or an invalid filter shape, allowing the
+ * but contains malformed JSON, an invalid filter shape, or a categoryKey
+ * that does not exist in the configured categories, allowing the
  * ErrorBoundary to catch and display the error page.
- * @returns Nothing; this hook performs validation and throws on invalid input.
+ * @returns void; throws DataExplorerError on invalid input.
  */
 export declare function useValidateFilterParam(): void;

package/lib/views/ExploreView/hooks/UseValidateFilterParam/hook.js

@@ -1,54 +1,19 @@
-import { useRouter } from "next/router";
 import { useMemo } from "react";
-import { parseFilterParam } from "../../../../common/filters/typeGuards";
+import { useValidateFilterKeys } from "../../../../common/filters/hooks/UseValidateFilterKeys/hook";
+import { isSelectedFilter } from "../../../../common/filters/typeGuards";
+import { useConfig } from "../../../../hooks/useConfig";
 import { EXPLORE_URL_PARAMS } from "../../../../providers/exploreState/constants";
-import { DataExplorerError } from "../../../../types/error";
-const INVALID_FILTER_PARAM_ERROR = "Invalid filter parameter in URL";
+import { extractCategoryKey, getValidCategoryKeys } from "./utils";
 /**
- * Validates the filter query parameter from the URL.
+ * Validates the filter query parameter from the URL for the ExploreView.
  * Throws a DataExplorerError during render if the filter param is present
- * but contains malformed JSON or an invalid filter shape, allowing the
+ * but contains malformed JSON, an invalid filter shape, or a categoryKey
+ * that does not exist in the configured categories, allowing the
  * ErrorBoundary to catch and display the error page.
- * @returns Nothing; this hook performs validation and throws on invalid input.
+ * @returns void; throws DataExplorerError on invalid input.
  */
 export function useValidateFilterParam() {
-    const { query } = useRouter();
-    const filterParam = query[EXPLORE_URL_PARAMS.FILTER];
-    const validationError = useMemo(() => {
-        if (filterParam === undefined)
-            return undefined;
-        if (typeof filterParam !== "string") {
-            return new DataExplorerError({ message: INVALID_FILTER_PARAM_ERROR });
-        }
-        let decoded;
-        try {
-            decoded = decodeURIComponent(filterParam);
-        }
-        catch {
-            return new DataExplorerError({ message: INVALID_FILTER_PARAM_ERROR });
-        }
-        // Parse and validate the filter param.
-        // An empty array (e.g. "[]") is valid — it means no filters selected.
-        // A non-empty array with no valid entries is invalid.
-        let parsed;
-        try {
-            parsed = JSON.parse(decoded);
-        }
-        catch {
-            return new DataExplorerError({ message: INVALID_FILTER_PARAM_ERROR });
-        }
-        if (!Array.isArray(parsed)) {
-            return new DataExplorerError({ message: INVALID_FILTER_PARAM_ERROR });
-        }
-        if (parsed.length === 0)
-            return undefined;
-        const filters = parseFilterParam(decoded);
-        if (filters.length === 0) {
-            return new DataExplorerError({ message: INVALID_FILTER_PARAM_ERROR });
-        }
-        return undefined;
-    }, [filterParam]);
-    if (validationError) {
-        throw validationError;
-    }
+    const { config, entityConfig } = useConfig();
+    const validKeys = useMemo(() => getValidCategoryKeys(config, entityConfig), [config, entityConfig]);
+    useValidateFilterKeys(EXPLORE_URL_PARAMS.FILTER, validKeys, isSelectedFilter, extractCategoryKey);
 }

package/lib/views/ExploreView/hooks/UseValidateFilterParam/utils.d.ts

@@ -0,0 +1,16 @@
+import type { EntityConfig, SiteConfig } from "../../../../config/entities";
+/**
+ * Extracts the categoryKey from a validated SelectedFilter entry.
+ * @param entry - Validated entry.
+ * @returns category key.
+ */
+export declare function extractCategoryKey(entry: unknown): string;
+/**
+ * Returns the set of valid category keys for the given entity, derived from
+ * the entity's category group config. Returns undefined if no category group
+ * config is available (skipping key validation).
+ * @param config - Site config.
+ * @param entityConfig - Entity config.
+ * @returns set of valid category keys, or undefined.
+ */
+export declare function getValidCategoryKeys(config: SiteConfig, entityConfig: EntityConfig): Set<string> | undefined;

package/lib/views/ExploreView/hooks/UseValidateFilterParam/utils.js

@@ -0,0 +1,29 @@
+import { getEntityCategoryGroupConfig } from "../../../../providers/exploreState/initializer/utils";
+/**
+ * Extracts the categoryKey from a validated SelectedFilter entry.
+ * @param entry - Validated entry.
+ * @returns category key.
+ */
+export function extractCategoryKey(entry) {
+    return entry.categoryKey;
+}
+/**
+ * Returns the set of valid category keys for the given entity, derived from
+ * the entity's category group config. Returns undefined if no category group
+ * config is available (skipping key validation).
+ * @param config - Site config.
+ * @param entityConfig - Entity config.
+ * @returns set of valid category keys, or undefined.
+ */
+export function getValidCategoryKeys(config, entityConfig) {
+    const categoryGroupConfig = getEntityCategoryGroupConfig(config, entityConfig);
+    if (!categoryGroupConfig)
+        return undefined;
+    const keys = new Set();
+    for (const group of categoryGroupConfig.categoryGroups) {
+        for (const categoryConfig of group.categoryConfigs) {
+            keys.add(categoryConfig.key);
+        }
+    }
+    return keys;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databiosphere/findable-ui",
-  "version": "51.1.0",
+  "version": "52.1.0",
   "description": "",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
@@ -44,7 +44,6 @@
     "@types/jest": "^29.5.14",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
-    "@types/react-gtm-module": "^2.0.1",
     "@types/react-window": "^1.8.5",
     "@typescript-eslint/eslint-plugin": "^8.50.0",
     "eslint": "^8.57.1",
@@ -88,7 +87,6 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "react-dropzone": "^14.3.8",
-    "react-gtm-module": "^2.0.11",
     "react-idle-timer": "^5.7.2",
     "react-window": "^1.8.11",
     "rehype-raw": "^7.0.0",