@databiosphere/findable-ui 51.0.2 → 51.1.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/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": "51.1.0",
   "description": "",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",