@databiosphere/findable-ui 51.0.2 → 52.0.0

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

@@ -0,0 +1,19 @@
+import { SelectedFilter } from "../entities";
+/**
+ * Returns true if the value is a valid SelectedFilter.
+ * @param value - Value to check.
+ * @returns true if the value has the expected shape.
+ */
+export declare function isSelectedFilter(value: unknown): value is SelectedFilter;
+/**
+ * Parses a filter parameter string into an array of SelectedFilter.
+ * Filters out invalid entries — a mixed array of valid and invalid
+ * objects returns only the valid ones. Returns an empty array if the
+ * string is not valid JSON or contains no valid entries. This function
+ * must not throw, as it is called from reducers above the ErrorBoundary.
+ * The useValidateFilterParam hook in ExploreView handles surfacing
+ * invalid filter errors to the user from inside the ErrorBoundary.
+ * @param paramValue - URL-decoded filter parameter string.
+ * @returns valid filters from the parsed input, or empty array.
+ */
+export declare function parseFilterParam(paramValue: string): SelectedFilter[];

package/lib/common/filters/typeGuards.js

@@ -0,0 +1,33 @@
+/**
+ * Returns true if the value is a valid SelectedFilter.
+ * @param value - Value to check.
+ * @returns true if the value has the expected shape.
+ */
+export function isSelectedFilter(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const filter = value;
+    return typeof filter.categoryKey === "string" && Array.isArray(filter.value);
+}
+/**
+ * Parses a filter parameter string into an array of SelectedFilter.
+ * Filters out invalid entries — a mixed array of valid and invalid
+ * objects returns only the valid ones. Returns an empty array if the
+ * string is not valid JSON or contains no valid entries. This function
+ * must not throw, as it is called from reducers above the ErrorBoundary.
+ * The useValidateFilterParam hook in ExploreView handles surfacing
+ * invalid filter errors to the user from inside the ErrorBoundary.
+ * @param paramValue - URL-decoded filter parameter string.
+ * @returns valid filters from the parsed input, or empty array.
+ */
+export function parseFilterParam(paramValue) {
+    try {
+        const parsed = JSON.parse(paramValue);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter(isSelectedFilter);
+    }
+    catch {
+        return [];
+    }
+}

package/lib/components/ErrorBoundary/errorBoundary.js

@@ -13,7 +13,7 @@ export class ErrorBoundary extends Component {
     }
     render() {
         if (this.state.error) {
-            const fallbackProps = { error: this.state.error, reset: this.render };
+            const fallbackProps = { error: this.state.error, reset: this.reset };
             return this.props.fallbackRender(fallbackProps);
         }
         return this.props.children;

package/lib/components/Links/components/Link/components/ExploreViewLink/exploreViewLink.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import Link from "next/link";
+import { isSelectedFilter } from "../../../../../../common/filters/typeGuards";
 import { useExploreState } from "../../../../../../hooks/useExploreState";
 import { ExploreActionKind, } from "../../../../../../providers/exploreState";
 import { ANCHOR_TARGET, REL_ATTRIBUTE, } from "../../../../common/entities";
@@ -61,17 +62,6 @@ function getSorting(query) {
     const parsedQuery = JSON.parse(decodedQuery);
     return parsedQuery[PARAM_SORTING];
 }
-/**
- * Returns true if the given value is a SelectedFilter.
- * @param value - Value.
- * @returns true if the given value is a SelectedFilter.
- */
-function isSelectedFilter(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "categoryKey" in value &&
-        "value" in value);
-}
 /**
  * Returns true if the given query string is a valid JSON string.
  * @param query - Query string.

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/hooks/useAsync.js

@@ -23,7 +23,7 @@ export const useAsync = (state = { status: "idle" }) => {
         if (!promise || !promise.then) {
             throw new Error(`The argument passed to useAsync().run must be a promise.`);
         }
-        safeSetState({ status: "pending" });
+        safeSetState({ error: undefined, status: "pending" });
         return promise.then((data) => {
             setData(data);
             return data;

package/lib/providers/exploreState/actions/urlToState/utils.d.ts

@@ -3,5 +3,6 @@ import { SelectedFilter } from "../../../../common/entities";
  * Returns the selected filters from the filter parameter value.
  * @param paramValue - The filter parameter value.
  * @returns The selected filters or an empty array.
+ * @see parseFilterParam for validation details and ErrorBoundary constraints.
  */
 export declare function decodeFilterParamValue(paramValue: string | string[] | undefined): SelectedFilter[];

package/lib/providers/exploreState/actions/urlToState/utils.js

@@ -1,13 +1,18 @@
+import { parseFilterParam } from "../../../../common/filters/typeGuards";
 /**
  * Returns the selected filters from the filter parameter value.
  * @param paramValue - The filter parameter value.
  * @returns The selected filters or an empty array.
+ * @see parseFilterParam for validation details and ErrorBoundary constraints.
  */
 export function decodeFilterParamValue(paramValue) {
     if (typeof paramValue === "string") {
-        // Return decoded filter param value if it is a string.
-        return JSON.parse(decodeURIComponent(paramValue));
+        try {
+            return parseFilterParam(decodeURIComponent(paramValue));
+        }
+        catch {
+            return [];
+        }
     }
-    // Default to an empty array.
     return [];
 }

package/lib/providers/exploreState/entities/state.js

@@ -14,12 +14,15 @@ export function buildNextEntities(state, entityListType, nextEntityState) {
     for (const [entityPath, entity] of Object.entries(state.entities)) {
         // Grab the entity key for the entity.
         const entityKey = entity.entityKey;
+        if (entityKey !== key) {
+            // For entities that do not share the same key, leave the context unchanged.
+            entities[entityPath] = entity;
+            continue;
+        }
         // Clone the entity context.
         const entityContext = { ...entity };
         // Build the params object.
         // All entities share the same catalog and feature flag state.
-        // Filter state is default to an empty array and updated below,
-        // if the entity key matches the current entity key.
         const params = {
             catalogState: state.catalogState,
             featureFlagState: state.featureFlagState,

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

@@ -1,7 +1,8 @@
 import { getFilterSortType } from "../../../common/filters/sort/config/utils";
+import { parseFilterParam } from "../../../common/filters/typeGuards";
 import { getInitialColumnVisibilityState } from "../../../components/TableCreator/options/initialState/columnVisibility";
 import { SELECT_CATEGORY_KEY } from "../constants";
-import { buildNextEntities } from "../entities/state";
+import { buildQuery } from "../entities/query/buildQuery";
 import { getEntityCategoryGroupConfigKey, getFilterCount } from "../utils";
 import { DEFAULT_CATEGORY_GROUP_SAVED_FILTERS, DEFAULT_ENTITY_STATE, INITIAL_STATE, } from "./constants";
 /**
@@ -55,6 +56,24 @@ function buildSavedFilterByCategoryValueKey(savedFilters) {
     }
     return savedFilterByCategoryValueKey;
 }
+/**
+ * Converts TanStack column filters to findable-ui SelectedFilter format.
+ * Throws if a column filter value is not an array, since SelectedFilterValue
+ * expects an array of CategoryValueKey.
+ * @param columnFilters - TanStack column filters.
+ * @returns selected filters.
+ */
+function columnFiltersToSelectedFilters(columnFilters) {
+    return columnFilters.map(({ id, value }) => {
+        if (!Array.isArray(value)) {
+            throw new Error(`columnFilters entry "${id}" has a non-array value. Expected an array e.g. ["value1", "value2"].`);
+        }
+        return {
+            categoryKey: id,
+            value: value,
+        };
+    });
+}
 /**
  * Returns entity related configured category group config where entity config takes precedence over site config.
  * @param siteConfig - Site config.
@@ -103,6 +122,18 @@ function initColumnVisibility(entityConfig) {
     const { list: { tableOptions = {} }, } = entityConfig;
     return getInitialColumnVisibilityState(tableOptions);
 }
+/**
+ * Returns the default filter state for the specified entity list configuration,
+ * converted from TanStack columnFilters format to SelectedFilter format.
+ * @param entityConfig - Entity configuration.
+ * @returns default filter state, or empty array if none configured.
+ */
+function initDefaultFilterState(entityConfig) {
+    if (!entityConfig)
+        return [];
+    const { list: { tableOptions: { initialState: { columnFilters = [] } = {} } = {} }, } = entityConfig;
+    return columnFiltersToSelectedFilters(columnFilters);
+}
 /**
  * Returns the initial `enableRowSelection` option for the specified entity list configuration.
  * @param entityConfig - Entity configuration.
@@ -133,26 +164,38 @@ function initEntityPageState(config) {
     }, {});
 }
 /**
- * Initializes entities context.
+ * Initializes entities context with queries that include default filter state
+ * from each entity's config (tableOptions.initialState.columnFilters).
  * @param entityPageState - Entity page state.
+ * @param entityStateByCategoryGroupConfigKey - Entity state by category group config key.
+ * @param state - Partial explore state for building queries.
  * @returns Entities context.
  */
-function initEntities(entityPageState) {
+function initEntities(entityPageState, entityStateByCategoryGroupConfigKey, state) {
     return Object.keys(entityPageState).reduce((acc, entityPath) => {
+        const entityKey = entityPageState[entityPath].categoryGroupConfigKey;
+        const entityState = entityStateByCategoryGroupConfigKey.get(entityKey);
+        const query = buildQuery(entityPath, {
+            catalogState: state.catalogState,
+            featureFlagState: state.featureFlagState,
+            filterState: entityState?.filterState ?? [],
+        });
         return {
             ...acc,
             [entityPath]: {
-                entityKey: entityPageState[entityPath].categoryGroupConfigKey,
-                query: { entityListType: entityPath },
+                entityKey,
+                query,
             },
         };
     }, {});
 }
 /**
  * Initializes entity state by category group config key.
+ * For the current entity, uses the pre-resolved filter state (URL filters or config defaults).
+ * For other entities, reads default filters from their tableOptions.initialState.columnFilters.
  * @param config - Site config.
- * @param categoryGroupConfigKey - Category group config key.
- * @param filterState - Filter state.
+ * @param categoryGroupConfigKey - Category group config key for the current entity.
+ * @param filterState - Pre-resolved filter state for the current entity.
  * @returns entity state by category group config key.
  */
 function initEntityStateByCategoryGroupConfigKey(config, categoryGroupConfigKey, filterState) {
@@ -167,11 +210,14 @@ function initEntityStateByCategoryGroupConfigKey(config, categoryGroupConfigKey,
         const categoryGroups = buildCategoryGroups(categoryGroupConfig);
         const savedSelectCategories = buildSavedSelectCategories(savedFilters);
         const savedFilterByCategoryValueKey = buildSavedFilterByCategoryValueKey(savedFilters);
+        const entityFilterState = key === categoryGroupConfigKey
+            ? filterState
+            : initDefaultFilterState(entity);
         entityStateByCategoryGroupConfigKey.set(key, {
             ...DEFAULT_ENTITY_STATE,
             categoryConfigs: flattenCategoryGroups(categoryGroups),
             categoryGroups,
-            filterState: key === categoryGroupConfigKey ? filterState : [],
+            filterState: entityFilterState,
             savedFilterByCategoryValueKey,
             savedSelectCategories,
         });
@@ -181,18 +227,11 @@ function initEntityStateByCategoryGroupConfigKey(config, categoryGroupConfigKey,
 /**
  * Initializes filter state from URL "filter" parameter.
  * @param decodedFilterParam - Decoded filter parameter.
- * @returns filter state.
+ * @returns filter state, or empty array if invalid.
+ * @see parseFilterParam for validation details and ErrorBoundary constraints.
  */
 function initFilterState(decodedFilterParam) {
-    // Define filter state, from URL "filter" parameter, if present and valid.
-    let filterState = [];
-    try {
-        filterState = JSON.parse(decodedFilterParam);
-    }
-    catch {
-        // do nothing
-    }
-    return filterState;
+    return parseFilterParam(decodedFilterParam);
 }
 /**
  * Returns the initial table grouping state for the specified entity list configuration.
@@ -222,14 +261,21 @@ function initSorting(entityConfig) {
  * @returns explore state reducer initial arguments.
  */
 export function initReducerArguments(config, entityListType, decodedFilterParam, decodedCatalogParam, decodedFeatureFlagParam) {
-    const filterState = initFilterState(decodedFilterParam);
+    const urlFilterState = initFilterState(decodedFilterParam);
+    const hasUrlFilters = urlFilterState.length > 0;
     const entityPageState = initEntityPageState(config);
     const categoryGroupConfigKey = getEntityCategoryGroupConfigKey(entityListType, entityPageState);
+    // URL filters take precedence over config-defined defaults.
+    const filterState = hasUrlFilters
+        ? urlFilterState
+        : initDefaultFilterState(config.entities.find(({ route }) => route === entityListType));
     const entityStateByCategoryGroupConfigKey = initEntityStateByCategoryGroupConfigKey(config, categoryGroupConfigKey, filterState);
     const categoryGroups = initCategoryGroups(entityStateByCategoryGroupConfigKey, categoryGroupConfigKey);
-    const entities = initEntities(entityPageState);
-    // Initialize state.
-    const state = {
+    const entities = initEntities(entityPageState, entityStateByCategoryGroupConfigKey, {
+        catalogState: decodedCatalogParam,
+        featureFlagState: decodedFeatureFlagParam,
+    });
+    return {
         ...INITIAL_STATE,
         catalogState: decodedCatalogParam,
         categoryGroups,
@@ -242,9 +288,4 @@ export function initReducerArguments(config, entityListType, decodedFilterParam,
         filterState,
         tabValue: entityListType,
     };
-    // Return state with entities (updated by initial state).
-    return {
-        ...state,
-        entities: buildNextEntities(state, entityListType, { filterState }),
-    };
 }

package/lib/views/ExploreView/exploreView.js

@@ -26,6 +26,7 @@ import { TEST_IDS } from "../../tests/testIds";
 import { ToggleButtonGroup } from "./entityList/filters/components/ToggleButtonGroup/toggleButtonGroup";
 import { StyledGrid, StyledStack } from "./entityList/filters/filters.styles";
 import { useUpdateFilterSort } from "./hooks/UseUpdateFilterSort/hook";
+import { useValidateFilterParam } from "./hooks/UseValidateFilterParam/hook";
 import { buildStateSyncManagerContext } from "./utils";
 export const ExploreView = (props) => {
     const { mdDown } = useBreakpoint();
@@ -34,6 +35,7 @@ export const ExploreView = (props) => {
     const { trackingConfig } = config;
     const { label } = entityConfig;
     const { categoryGroups, categoryViews, loading } = exploreState;
+    useValidateFilterParam();
     useEntityList(props); // Fetch entities.
     const { entityListType } = props;
     const categoryFilters = useMemo(() => buildCategoryFilters(categoryViews, categoryGroups), [categoryGroups, categoryViews]);

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

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

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

@@ -0,0 +1,54 @@
+import { useRouter } from "next/router";
+import { useMemo } from "react";
+import { parseFilterParam } from "../../../../common/filters/typeGuards";
+import { EXPLORE_URL_PARAMS } from "../../../../providers/exploreState/constants";
+import { DataExplorerError } from "../../../../types/error";
+const INVALID_FILTER_PARAM_ERROR = "Invalid filter parameter in URL";
+/**
+ * Validates the filter query parameter from the URL.
+ * Throws a DataExplorerError during render if the filter param is present
+ * but contains malformed JSON or an invalid filter shape, allowing the
+ * ErrorBoundary to catch and display the error page.
+ * @returns Nothing; this hook performs validation and throws 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;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databiosphere/findable-ui",
-  "version": "51.0.2",
+  "version": "52.0.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",