@databiosphere/findable-ui 52.0.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/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": "52.0.0",
+  "version": "52.1.0",
   "description": "",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",