@trackunit/filters-filter-bar 1.3.89 → 1.3.92

package/index.cjs.js

@@ -11,6 +11,7 @@ var reactCoreContextsApi = require('@trackunit/react-core-contexts-api');
 var reactFormComponents = require('@trackunit/react-form-components');
 var reactDateAndTimeComponents = require('@trackunit/react-date-and-time-components');
 var sharedUtils = require('@trackunit/shared-utils');
+var cssClassVarianceUtilities = require('@trackunit/css-class-variance-utilities');
 var tailwindMerge = require('tailwind-merge');
 var dequal = require('dequal');
 var isEqual = require('lodash/isEqual');
@@ -628,6 +629,231 @@ const DefaultRadioFilter = ({ filterDefinition, filterBarActions, options, loadi
                     }, value: selectedRadioId?.key || "", children: jsxRuntime.jsx(DynamicFilterList, { checked: index => filterBarActions.objectIncludesValue(filterDefinition.filterKey, res[index]?.key || ""), count: index => res[index]?.count, keyMapper: index => res[index]?.key || "", labelMapper: index => res[index]?.label || "", rowCount: res.length, showRequestMoreUseSearch: showRequestMoreUseSearch, type: "Radio" }) })) })] }));
 };
 
+/**
+ * Recursively gets all descendant keys for a given hierarchical option, including the option itself.
+ *
+ * @param option The starting hierarchical filter option.
+ * @returns An array of string keys representing the option and all its descendants.
+ */
+const getAllDescendantKeys = (option) => {
+    let keys = [option.key];
+    if (option.children) {
+        option.children.forEach(child => {
+            keys = keys.concat(getAllDescendantKeys(child));
+        });
+    }
+    return keys;
+};
+/**
+ * Recursively filters hierarchical options based on a search term.
+ * Keeps an option if its label matches or if any descendant matches.
+ */
+const filterHierarchicalOptions = (options, searchTerm, parentMatches = false // Track if the parent already matched
+) => {
+    if (!searchTerm) {
+        return options; // Return all options if search term is empty
+    }
+    const lowerCaseSearchTerm = searchTerm.toLowerCase();
+    return options.reduce((acc, option) => {
+        const labelMatches = option.label.toLowerCase().includes(lowerCaseSearchTerm);
+        const matches = labelMatches || parentMatches;
+        let filteredChildren = [];
+        if (option.children && option.children.length > 0) {
+            // Pass `matches` as `parentMatches` for children
+            filteredChildren = filterHierarchicalOptions(option.children, searchTerm, matches);
+        }
+        // Include the option if:
+        // 1. Its label matches OR
+        // 2. Its parent matched (meaning it's part of a matched branch) OR
+        // 3. It has children that matched
+        if (matches || filteredChildren.length > 0) {
+            acc.push({
+                ...option,
+                // Only include children if they (or their descendants) matched
+                children: filteredChildren.length > 0 ? filteredChildren : undefined,
+            });
+        }
+        return acc;
+    }, []);
+};
+
+/**
+ * Custom hook to manage the state and interactions of a single hierarchical option.
+ * Calculates checked/indeterminate state and provides a handler for value changes,
+ * including cascading logic.
+ */
+const useHierarchicalOptionState = ({ options, option, selectedValues, cascadeSelection, optionsMap, setValue, filterDefinition, logEvent, }) => {
+    const allDescendantKeys = react.useMemo(() => (cascadeSelection ? getAllDescendantKeys(option) : [option.key]), [option, cascadeSelection]);
+    const hasChildren = react.useMemo(() => (option.children ?? []).length > 0, [option.children]);
+    const parentMap = react.useMemo(() => {
+        const map = new Map();
+        const traverse = (opts, parentKey) => {
+            opts.forEach(opt => {
+                if (parentKey) {
+                    map.set(opt.key, parentKey);
+                }
+                if (opt.children && Array.isArray(opt.children) && opt.children.length > 0) {
+                    traverse(opt.children, opt.key);
+                }
+            });
+        };
+        traverse(options);
+        return map;
+    }, [options]);
+    const { isChecked, isIndeterminate } = react.useMemo(() => {
+        if (!cascadeSelection || !hasChildren) {
+            const selfChecked = selectedValues.some(v => v.value === option.key);
+            return { isChecked: selfChecked, isIndeterminate: false };
+        }
+        const selectedKeySet = new Set(selectedValues.map(v => v.value));
+        let allChildrenChecked = true;
+        let someChildrenChecked = false;
+        const descendantKeysOnly = allDescendantKeys.filter(k => k !== option.key);
+        if (descendantKeysOnly.length === 0) {
+            return { isChecked: selectedKeySet.has(option.key), isIndeterminate: false };
+        }
+        for (const key of descendantKeysOnly) {
+            if (selectedKeySet.has(key)) {
+                someChildrenChecked = true;
+            }
+            else {
+                allChildrenChecked = false;
+            }
+        }
+        const checked = allChildrenChecked;
+        const indeterminate = someChildrenChecked && !allChildrenChecked;
+        return { isChecked: checked, isIndeterminate: indeterminate };
+    }, [selectedValues, option.key, allDescendantKeys, cascadeSelection, hasChildren]);
+    const handleSelect = react.useCallback(() => {
+        logEvent("Filters Applied - V2", {
+            type: `${stringTs.capitalize(filterDefinition.filterKey)}Filter`,
+            value: option.key,
+        });
+        setValue(prev => {
+            let currentSelectedValues = prev ? [...prev] : [];
+            const selectedKeySet = new Set(currentSelectedValues.map(v => v.value));
+            if (!cascadeSelection) {
+                // Non-cascading: Toggle only the current option
+                if (selectedKeySet.has(option.key)) {
+                    currentSelectedValues = currentSelectedValues.filter(f => f.value !== option.key);
+                }
+                else {
+                    currentSelectedValues.push({ name: option.label, value: option.key });
+                }
+            }
+            else {
+                const keysToToggle = getAllDescendantKeys(option);
+                const shouldBeChecked = !isChecked;
+                if (!shouldBeChecked) {
+                    const keysToRemove = new Set(getAllDescendantKeys(option));
+                    let currentParentKey = parentMap.get(option.key);
+                    while (currentParentKey) {
+                        keysToRemove.add(currentParentKey);
+                        currentParentKey = parentMap.get(currentParentKey);
+                    }
+                    currentSelectedValues = currentSelectedValues.filter(f => !keysToRemove.has(f.value));
+                }
+                else {
+                    // Add the option and all descendants if they are not already selected
+                    const itemsToAdd = [];
+                    keysToToggle.forEach(key => {
+                        if (!selectedKeySet.has(key)) {
+                            const optionDetails = optionsMap.get(key);
+                            // Ensure we have details before adding, fallback to key if not found (shouldn't happen ideally)
+                            itemsToAdd.push({ name: optionDetails?.label ?? key, value: key });
+                        }
+                    });
+                    currentSelectedValues.push(...itemsToAdd);
+                }
+            }
+            return currentSelectedValues;
+        });
+    }, [cascadeSelection, filterDefinition.filterKey, logEvent, setValue, isChecked, option, optionsMap, parentMap]);
+    return {
+        isChecked,
+        isIndeterminate,
+        handleSelect,
+    };
+};
+
+/**
+ * Renders a single option and its children recursively.
+ * Uses the `useHierarchicalOptionState` hook for state management and interaction logic.
+ */
+const RenderHierarchicalOption = ({ option, filterDefinition, filterBarActions, setValue, logEvent, selectedValues, cascadeSelection, optionsMap, }) => {
+    const level = option.level ?? 0;
+    const { isChecked, isIndeterminate, handleSelect } = useHierarchicalOptionState({
+        option,
+        selectedValues,
+        cascadeSelection,
+        optionsMap,
+        setValue,
+        options: Array.from(optionsMap.values()),
+        filterDefinition,
+        logEvent,
+    });
+    return (jsxRuntime.jsxs(react.Fragment, { children: [jsxRuntime.jsx("div", { className: cvaOptionItem({ indentationLevel: level > 6 ? 6 : level }), children: jsxRuntime.jsx(reactFilterComponents.CheckBoxFilterItem, { checked: isChecked, className: "rounded-none", dataTestId: `hierarchical-filter-check-box-${option.key}`, indeterminate: isIndeterminate, itemCount: option.count, label: option.label, name: `hierarchical-filter-check-box-${option.key}`, onChange: handleSelect }) }), option.children?.map(child => (jsxRuntime.jsx(RenderHierarchicalOption, { cascadeSelection: cascadeSelection, filterBarActions: filterBarActions, filterDefinition: filterDefinition, logEvent: logEvent, option: child, optionsMap: optionsMap, selectedValues: selectedValues, setValue: setValue }, child.key)))] }, option.key));
+};
+const cvaOptionItem = cssClassVarianceUtilities.cvaMerge(["m-1"], {
+    variants: {
+        indentationLevel: {
+            0: ["pl-0"],
+            1: ["pl-6"],
+            2: ["pl-12"],
+            3: ["pl-18"],
+            4: ["pl-24"],
+            5: ["pl-30"],
+            6: ["pl-36"],
+        },
+    },
+    defaultVariants: {
+        indentationLevel: 0,
+    },
+});
+
+/**
+ * `HierarchicalCheckboxFilter` is a React component for handling hierarchical checkbox filters.
+ * It expects options to be pre-processed into a hierarchical structure.
+ *
+ * Supports optional cascading selection behavior via the `cascadeSelection` prop.
+ */
+const HierarchicalCheckboxFilter = ({ filterDefinition, filterBarActions, options, loading, setValue, value, cascadeSelection = false, customSearch, }) => {
+    const { logEvent } = reactCoreHooks.useAnalytics(FilterEvents);
+    const selectedValues = value ?? [];
+    // Local state for client-side search (used if customSearch is not provided)
+    const [localSearchText, setLocalSearchText] = react.useState("");
+    // Determine if we are using server-side search (customSearch) or client-side search
+    const isServerSearch = !!customSearch;
+    const currentSearchText = isServerSearch ? customSearch.value : localSearchText;
+    const currentSetSearchText = isServerSearch ? customSearch.onChange : setLocalSearchText;
+    const searchHeaderProps = {
+        searchEnabled: true,
+        searchProps: { value: currentSearchText, onChange: currentSetSearchText },
+    };
+    const optionsMap = react.useMemo(() => {
+        const map = new Map();
+        const traverse = (opts) => {
+            opts.forEach(opt => {
+                map.set(opt.key, opt);
+                if (opt.children) {
+                    traverse(opt.children);
+                }
+            });
+        };
+        traverse(options);
+        return map;
+    }, [options]);
+    // Filter options based on search term, preserving hierarchy
+    const filteredOptions = react.useMemo(() => {
+        // Only apply client-side filtering if not doing server-side search
+        if (isServerSearch) {
+            return options; // Assume server provides filtered options
+        }
+        return filterHierarchicalOptions(options, localSearchText);
+    }, [options, isServerSearch, localSearchText]);
+    return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx(FilterHeader, { ...filterDefinition, ...filterBarActions, filterHasChanges: filterBarActions.appliedFilterKeys().includes(filterDefinition.filterKey), loading: loading, ...searchHeaderProps }), jsxRuntime.jsx("div", { className: "max-h-60 overflow-y-auto", children: jsxRuntime.jsx(FilterResults, { loading: loading, results: filteredOptions, children: results => (jsxRuntime.jsx(jsxRuntime.Fragment, { children: results.map(option => (jsxRuntime.jsx(RenderHierarchicalOption, { cascadeSelection: cascadeSelection, filterBarActions: filterBarActions, filterDefinition: filterDefinition, logEvent: logEvent, option: option, optionsMap: optionsMap, selectedValues: selectedValues, setValue: setValue }, option.key))) })) }) })] }));
+};
+
 /**
  * Custom React hook for grouping and filtering a list of filters.
  *
@@ -1709,6 +1935,7 @@ exports.FilterBar = FilterBar;
 exports.FilterEvents = FilterEvents;
 exports.FilterHeader = FilterHeader;
 exports.FilterResults = FilterResults;
+exports.HierarchicalCheckboxFilter = HierarchicalCheckboxFilter;
 exports.StarredFilters = StarredFilters;
 exports.areaFilterGeoJsonGeometrySchema = areaFilterGeoJsonGeometrySchema;
 exports.isAreaFilterValue = isAreaFilterValue;

package/index.esm.js

@@ -3,12 +3,13 @@ import { registerTranslations, useNamespaceTranslation } from '@trackunit/i18n-l
 import { VirtualizedList, Text, Button, Popover, PopoverTrigger, PopoverContent, MenuList, cvaInteractableItem, useViewportBreakpoints, Tooltip, Icon, IconButton, Card, CardBody, CardFooter } from '@trackunit/react-components';
 import { useAnalytics, useTextSearch, useCurrentUser } from '@trackunit/react-core-hooks';
 import { FilterBody, RadioFilterItem, CheckBoxFilterItem, FilterHeader as FilterHeader$1, FilterFooter, Filter as Filter$1 } from '@trackunit/react-filter-components';
-import { useRef, useMemo, useState, useEffect, useCallback } from 'react';
+import { useRef, useMemo, useState, useEffect, useCallback, Fragment as Fragment$1 } from 'react';
 import { capitalize } from 'string-ts';
 import { createEvent } from '@trackunit/react-core-contexts-api';
 import { Search, NumberField, RadioGroup, ToggleSwitchOption } from '@trackunit/react-form-components';
 import { DayRangePicker } from '@trackunit/react-date-and-time-components';
 import { nonNullable, capitalize as capitalize$1, objectValues, truthy, objectKeys } from '@trackunit/shared-utils';
+import { cvaMerge } from '@trackunit/css-class-variance-utilities';
 import { twMerge } from 'tailwind-merge';
 import { dequal } from 'dequal';
 import isEqual from 'lodash/isEqual';
@@ -626,6 +627,231 @@ const DefaultRadioFilter = ({ filterDefinition, filterBarActions, options, loadi
                     }, value: selectedRadioId?.key || "", children: jsx(DynamicFilterList, { checked: index => filterBarActions.objectIncludesValue(filterDefinition.filterKey, res[index]?.key || ""), count: index => res[index]?.count, keyMapper: index => res[index]?.key || "", labelMapper: index => res[index]?.label || "", rowCount: res.length, showRequestMoreUseSearch: showRequestMoreUseSearch, type: "Radio" }) })) })] }));
 };
 
+/**
+ * Recursively gets all descendant keys for a given hierarchical option, including the option itself.
+ *
+ * @param option The starting hierarchical filter option.
+ * @returns An array of string keys representing the option and all its descendants.
+ */
+const getAllDescendantKeys = (option) => {
+    let keys = [option.key];
+    if (option.children) {
+        option.children.forEach(child => {
+            keys = keys.concat(getAllDescendantKeys(child));
+        });
+    }
+    return keys;
+};
+/**
+ * Recursively filters hierarchical options based on a search term.
+ * Keeps an option if its label matches or if any descendant matches.
+ */
+const filterHierarchicalOptions = (options, searchTerm, parentMatches = false // Track if the parent already matched
+) => {
+    if (!searchTerm) {
+        return options; // Return all options if search term is empty
+    }
+    const lowerCaseSearchTerm = searchTerm.toLowerCase();
+    return options.reduce((acc, option) => {
+        const labelMatches = option.label.toLowerCase().includes(lowerCaseSearchTerm);
+        const matches = labelMatches || parentMatches;
+        let filteredChildren = [];
+        if (option.children && option.children.length > 0) {
+            // Pass `matches` as `parentMatches` for children
+            filteredChildren = filterHierarchicalOptions(option.children, searchTerm, matches);
+        }
+        // Include the option if:
+        // 1. Its label matches OR
+        // 2. Its parent matched (meaning it's part of a matched branch) OR
+        // 3. It has children that matched
+        if (matches || filteredChildren.length > 0) {
+            acc.push({
+                ...option,
+                // Only include children if they (or their descendants) matched
+                children: filteredChildren.length > 0 ? filteredChildren : undefined,
+            });
+        }
+        return acc;
+    }, []);
+};
+
+/**
+ * Custom hook to manage the state and interactions of a single hierarchical option.
+ * Calculates checked/indeterminate state and provides a handler for value changes,
+ * including cascading logic.
+ */
+const useHierarchicalOptionState = ({ options, option, selectedValues, cascadeSelection, optionsMap, setValue, filterDefinition, logEvent, }) => {
+    const allDescendantKeys = useMemo(() => (cascadeSelection ? getAllDescendantKeys(option) : [option.key]), [option, cascadeSelection]);
+    const hasChildren = useMemo(() => (option.children ?? []).length > 0, [option.children]);
+    const parentMap = useMemo(() => {
+        const map = new Map();
+        const traverse = (opts, parentKey) => {
+            opts.forEach(opt => {
+                if (parentKey) {
+                    map.set(opt.key, parentKey);
+                }
+                if (opt.children && Array.isArray(opt.children) && opt.children.length > 0) {
+                    traverse(opt.children, opt.key);
+                }
+            });
+        };
+        traverse(options);
+        return map;
+    }, [options]);
+    const { isChecked, isIndeterminate } = useMemo(() => {
+        if (!cascadeSelection || !hasChildren) {
+            const selfChecked = selectedValues.some(v => v.value === option.key);
+            return { isChecked: selfChecked, isIndeterminate: false };
+        }
+        const selectedKeySet = new Set(selectedValues.map(v => v.value));
+        let allChildrenChecked = true;
+        let someChildrenChecked = false;
+        const descendantKeysOnly = allDescendantKeys.filter(k => k !== option.key);
+        if (descendantKeysOnly.length === 0) {
+            return { isChecked: selectedKeySet.has(option.key), isIndeterminate: false };
+        }
+        for (const key of descendantKeysOnly) {
+            if (selectedKeySet.has(key)) {
+                someChildrenChecked = true;
+            }
+            else {
+                allChildrenChecked = false;
+            }
+        }
+        const checked = allChildrenChecked;
+        const indeterminate = someChildrenChecked && !allChildrenChecked;
+        return { isChecked: checked, isIndeterminate: indeterminate };
+    }, [selectedValues, option.key, allDescendantKeys, cascadeSelection, hasChildren]);
+    const handleSelect = useCallback(() => {
+        logEvent("Filters Applied - V2", {
+            type: `${capitalize(filterDefinition.filterKey)}Filter`,
+            value: option.key,
+        });
+        setValue(prev => {
+            let currentSelectedValues = prev ? [...prev] : [];
+            const selectedKeySet = new Set(currentSelectedValues.map(v => v.value));
+            if (!cascadeSelection) {
+                // Non-cascading: Toggle only the current option
+                if (selectedKeySet.has(option.key)) {
+                    currentSelectedValues = currentSelectedValues.filter(f => f.value !== option.key);
+                }
+                else {
+                    currentSelectedValues.push({ name: option.label, value: option.key });
+                }
+            }
+            else {
+                const keysToToggle = getAllDescendantKeys(option);
+                const shouldBeChecked = !isChecked;
+                if (!shouldBeChecked) {
+                    const keysToRemove = new Set(getAllDescendantKeys(option));
+                    let currentParentKey = parentMap.get(option.key);
+                    while (currentParentKey) {
+                        keysToRemove.add(currentParentKey);
+                        currentParentKey = parentMap.get(currentParentKey);
+                    }
+                    currentSelectedValues = currentSelectedValues.filter(f => !keysToRemove.has(f.value));
+                }
+                else {
+                    // Add the option and all descendants if they are not already selected
+                    const itemsToAdd = [];
+                    keysToToggle.forEach(key => {
+                        if (!selectedKeySet.has(key)) {
+                            const optionDetails = optionsMap.get(key);
+                            // Ensure we have details before adding, fallback to key if not found (shouldn't happen ideally)
+                            itemsToAdd.push({ name: optionDetails?.label ?? key, value: key });
+                        }
+                    });
+                    currentSelectedValues.push(...itemsToAdd);
+                }
+            }
+            return currentSelectedValues;
+        });
+    }, [cascadeSelection, filterDefinition.filterKey, logEvent, setValue, isChecked, option, optionsMap, parentMap]);
+    return {
+        isChecked,
+        isIndeterminate,
+        handleSelect,
+    };
+};
+
+/**
+ * Renders a single option and its children recursively.
+ * Uses the `useHierarchicalOptionState` hook for state management and interaction logic.
+ */
+const RenderHierarchicalOption = ({ option, filterDefinition, filterBarActions, setValue, logEvent, selectedValues, cascadeSelection, optionsMap, }) => {
+    const level = option.level ?? 0;
+    const { isChecked, isIndeterminate, handleSelect } = useHierarchicalOptionState({
+        option,
+        selectedValues,
+        cascadeSelection,
+        optionsMap,
+        setValue,
+        options: Array.from(optionsMap.values()),
+        filterDefinition,
+        logEvent,
+    });
+    return (jsxs(Fragment$1, { children: [jsx("div", { className: cvaOptionItem({ indentationLevel: level > 6 ? 6 : level }), children: jsx(CheckBoxFilterItem, { checked: isChecked, className: "rounded-none", dataTestId: `hierarchical-filter-check-box-${option.key}`, indeterminate: isIndeterminate, itemCount: option.count, label: option.label, name: `hierarchical-filter-check-box-${option.key}`, onChange: handleSelect }) }), option.children?.map(child => (jsx(RenderHierarchicalOption, { cascadeSelection: cascadeSelection, filterBarActions: filterBarActions, filterDefinition: filterDefinition, logEvent: logEvent, option: child, optionsMap: optionsMap, selectedValues: selectedValues, setValue: setValue }, child.key)))] }, option.key));
+};
+const cvaOptionItem = cvaMerge(["m-1"], {
+    variants: {
+        indentationLevel: {
+            0: ["pl-0"],
+            1: ["pl-6"],
+            2: ["pl-12"],
+            3: ["pl-18"],
+            4: ["pl-24"],
+            5: ["pl-30"],
+            6: ["pl-36"],
+        },
+    },
+    defaultVariants: {
+        indentationLevel: 0,
+    },
+});
+
+/**
+ * `HierarchicalCheckboxFilter` is a React component for handling hierarchical checkbox filters.
+ * It expects options to be pre-processed into a hierarchical structure.
+ *
+ * Supports optional cascading selection behavior via the `cascadeSelection` prop.
+ */
+const HierarchicalCheckboxFilter = ({ filterDefinition, filterBarActions, options, loading, setValue, value, cascadeSelection = false, customSearch, }) => {
+    const { logEvent } = useAnalytics(FilterEvents);
+    const selectedValues = value ?? [];
+    // Local state for client-side search (used if customSearch is not provided)
+    const [localSearchText, setLocalSearchText] = useState("");
+    // Determine if we are using server-side search (customSearch) or client-side search
+    const isServerSearch = !!customSearch;
+    const currentSearchText = isServerSearch ? customSearch.value : localSearchText;
+    const currentSetSearchText = isServerSearch ? customSearch.onChange : setLocalSearchText;
+    const searchHeaderProps = {
+        searchEnabled: true,
+        searchProps: { value: currentSearchText, onChange: currentSetSearchText },
+    };
+    const optionsMap = useMemo(() => {
+        const map = new Map();
+        const traverse = (opts) => {
+            opts.forEach(opt => {
+                map.set(opt.key, opt);
+                if (opt.children) {
+                    traverse(opt.children);
+                }
+            });
+        };
+        traverse(options);
+        return map;
+    }, [options]);
+    // Filter options based on search term, preserving hierarchy
+    const filteredOptions = useMemo(() => {
+        // Only apply client-side filtering if not doing server-side search
+        if (isServerSearch) {
+            return options; // Assume server provides filtered options
+        }
+        return filterHierarchicalOptions(options, localSearchText);
+    }, [options, isServerSearch, localSearchText]);
+    return (jsxs(Fragment, { children: [jsx(FilterHeader, { ...filterDefinition, ...filterBarActions, filterHasChanges: filterBarActions.appliedFilterKeys().includes(filterDefinition.filterKey), loading: loading, ...searchHeaderProps }), jsx("div", { className: "max-h-60 overflow-y-auto", children: jsx(FilterResults, { loading: loading, results: filteredOptions, children: results => (jsx(Fragment, { children: results.map(option => (jsx(RenderHierarchicalOption, { cascadeSelection: cascadeSelection, filterBarActions: filterBarActions, filterDefinition: filterDefinition, logEvent: logEvent, option: option, optionsMap: optionsMap, selectedValues: selectedValues, setValue: setValue }, option.key))) })) }) })] }));
+};
+
 /**
  * Custom React hook for grouping and filtering a list of filters.
  *
@@ -1698,4 +1924,4 @@ const mergeFilters = (filterBarDefinition, extraFilters) => {
  */
 setupLibraryTranslations();
 
-export { DefaultCheckboxFilter, DefaultDateRangeFilter, DefaultMinMaxFilter, DefaultRadioFilter, DynamicFilterList, FilterBar, FilterEvents, FilterHeader, FilterResults, StarredFilters, areaFilterGeoJsonGeometrySchema, isAreaFilterValue, isArrayFilterValue, isBooleanValue, isDateRangeValue, isMinMaxFilterValue, isStringArrayFilterValue, isValueName, isValueNameArray, mergeFilters, mockFilterBar, toggleFilterValue, useFilterBar, useFilterBarAsync, useSearchParamAsFilter, validateFilter };
+export { DefaultCheckboxFilter, DefaultDateRangeFilter, DefaultMinMaxFilter, DefaultRadioFilter, DynamicFilterList, FilterBar, FilterEvents, FilterHeader, FilterResults, HierarchicalCheckboxFilter, StarredFilters, areaFilterGeoJsonGeometrySchema, isAreaFilterValue, isArrayFilterValue, isBooleanValue, isDateRangeValue, isMinMaxFilterValue, isStringArrayFilterValue, isValueName, isValueNameArray, mergeFilters, mockFilterBar, toggleFilterValue, useFilterBar, useFilterBarAsync, useSearchParamAsFilter, validateFilter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/filters-filter-bar",
-  "version": "1.3.89",
+  "version": "1.3.92",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -14,15 +14,16 @@
     "tailwind-merge": "^2.0.0",
     "string-ts": "^2.0.0",
     "zod": "3.22.4",
-    "@trackunit/react-components": "1.4.64",
-    "@trackunit/react-core-hooks": "1.3.54",
-    "@trackunit/react-filter-components": "1.3.74",
-    "@trackunit/react-date-and-time-components": "1.3.72",
-    "@trackunit/shared-utils": "1.5.51",
-    "@trackunit/react-form-components": "1.3.74",
-    "@trackunit/react-core-contexts-api": "1.4.52",
-    "@trackunit/geo-json-utils": "1.3.52",
-    "@trackunit/i18n-library-translation": "1.3.56"
+    "@trackunit/react-components": "1.4.66",
+    "@trackunit/react-core-hooks": "1.3.56",
+    "@trackunit/react-filter-components": "1.3.76",
+    "@trackunit/react-date-and-time-components": "1.3.74",
+    "@trackunit/shared-utils": "1.5.53",
+    "@trackunit/react-form-components": "1.3.76",
+    "@trackunit/react-core-contexts-api": "1.4.54",
+    "@trackunit/geo-json-utils": "1.3.54",
+    "@trackunit/i18n-library-translation": "1.3.58",
+    "@trackunit/css-class-variance-utilities": "1.3.53"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/lib/components/DefaultFilterTypes.d.ts

@@ -18,6 +18,20 @@ export interface FilterOption {
      */
     prefix?: ReactNode;
 }
+/**
+ * Represents a filter option within a hierarchical structure.
+ */
+export interface HierarchicalFilterOption extends FilterOption {
+    /**
+     * Child options for this node in the hierarchy.
+     */
+    children?: HierarchicalFilterOption[];
+    /**
+     * The nesting level of this option (0 for root).
+     * Added during hierarchy processing.
+     */
+    level?: number;
+}
 export interface DefaultFilterProps<TReturnType> extends FilterViewProps<TReturnType> {
     /**
      * An array of filter options to be displayed.

package/src/lib/components/HierarchicalCheckboxFilter/HierarchicalCheckboxFilter.d.ts

@@ -0,0 +1,58 @@
+import { FilterDefinition, FilterStateSetterCallback, ValueName } from "../../types/FilterTypes";
+import { DefaultFilterProps, HierarchicalFilterOption } from "../DefaultFilterTypes";
+/**
+ * Props for the HierarchicalCheckboxFilter component.
+ * Extends base filter props but requires hierarchical options and ValueName[] type.
+ */
+export interface HierarchicalFilterProps extends Omit<DefaultFilterProps<ValueName[]>, "options" | "customSearch" | "showRequestMoreUseSearch" | "showUndefinedOptionWithCountAtBottom" | "totalRecords"> {
+    /**
+     * An array of hierarchical filter options to be displayed.
+     * The structure (parent-child relationships and levels) should be pre-processed.
+     */
+    options: HierarchicalFilterOption[];
+    /**
+     * The filter definition, constrained to the 'valueNameArray' type for this component.
+     */
+    filterDefinition: FilterDefinition & {
+        type: "valueNameArray";
+    };
+    /**
+     * Callback function to update the filter's value state.
+     */
+    setValue: FilterStateSetterCallback<ValueName[]>;
+    /**
+     * Enable cascading selection behavior.
+     * - Checking/unchecking a parent affects all descendants.
+     * - Parent shows indeterminate state if only some children are checked.
+     *
+     * @default false
+     */
+    cascadeSelection?: boolean;
+    /**
+     * Optional prop to enable server-side searching.
+     * - If provided, the component assumes filtering is handled externally (server-side).
+     *   It will use the provided `value` for the search input and call `onChange` when it changes.
+     *   Client-side filtering using `filterHierarchicalOptions` will be skipped.
+     * - If not provided, the component will handle filtering client-side using internal state
+     *   and the `filterHierarchicalOptions` function.
+     */
+    customSearch?: {
+        /**
+         * Current search string
+         */
+        value: string;
+        /**
+         * Callback when search string changed
+         *
+         * @param value Updated search string
+         */
+        onChange: (value: string) => void;
+    };
+}
+/**
+ * `HierarchicalCheckboxFilter` is a React component for handling hierarchical checkbox filters.
+ * It expects options to be pre-processed into a hierarchical structure.
+ *
+ * Supports optional cascading selection behavior via the `cascadeSelection` prop.
+ */
+export declare const HierarchicalCheckboxFilter: ({ filterDefinition, filterBarActions, options, loading, setValue, value, cascadeSelection, customSearch, }: HierarchicalFilterProps) => import("react/jsx-runtime").JSX.Element;

package/src/lib/components/HierarchicalCheckboxFilter/HierarchicalCheckboxFilter.utils.d.ts

@@ -0,0 +1,13 @@
+import { HierarchicalFilterOption } from "../DefaultFilterTypes";
+/**
+ * Recursively gets all descendant keys for a given hierarchical option, including the option itself.
+ *
+ * @param option The starting hierarchical filter option.
+ * @returns An array of string keys representing the option and all its descendants.
+ */
+export declare const getAllDescendantKeys: (option: HierarchicalFilterOption) => string[];
+/**
+ * Recursively filters hierarchical options based on a search term.
+ * Keeps an option if its label matches or if any descendant matches.
+ */
+export declare const filterHierarchicalOptions: (options: HierarchicalFilterOption[], searchTerm: string, parentMatches?: boolean) => HierarchicalFilterOption[];

package/src/lib/components/HierarchicalCheckboxFilter/RenderHierarchicalOption.d.ts

@@ -0,0 +1,20 @@
+import { useAnalytics } from "@trackunit/react-core-hooks";
+import { ValueName } from "../../types/FilterTypes";
+import { HierarchicalFilterOption } from "../DefaultFilterTypes";
+import { HierarchicalFilterProps } from "./HierarchicalCheckboxFilter";
+interface RenderHierarchicalOptionProps {
+    option: HierarchicalFilterOption;
+    filterDefinition: HierarchicalFilterProps["filterDefinition"];
+    filterBarActions: HierarchicalFilterProps["filterBarActions"];
+    setValue: HierarchicalFilterProps["setValue"];
+    logEvent: ReturnType<typeof useAnalytics>["logEvent"];
+    selectedValues: ValueName[];
+    cascadeSelection: boolean;
+    optionsMap: Map<string, HierarchicalFilterOption>;
+}
+/**
+ * Renders a single option and its children recursively.
+ * Uses the `useHierarchicalOptionState` hook for state management and interaction logic.
+ */
+export declare const RenderHierarchicalOption: ({ option, filterDefinition, filterBarActions, setValue, logEvent, selectedValues, cascadeSelection, optionsMap, }: RenderHierarchicalOptionProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/lib/components/HierarchicalCheckboxFilter/useHierarchicalOptionState.d.ts

@@ -0,0 +1,25 @@
+import { useAnalytics } from "@trackunit/react-core-hooks";
+import { ValueName } from "../../types/FilterTypes";
+import { HierarchicalFilterOption } from "../DefaultFilterTypes";
+import { HierarchicalFilterProps } from "./HierarchicalCheckboxFilter";
+interface UseHierarchicalOptionStateProps {
+    options: HierarchicalFilterOption[];
+    option: HierarchicalFilterOption;
+    selectedValues: ValueName[];
+    cascadeSelection: boolean;
+    optionsMap: Map<string, HierarchicalFilterOption>;
+    setValue: HierarchicalFilterProps["setValue"];
+    filterDefinition: HierarchicalFilterProps["filterDefinition"];
+    logEvent: ReturnType<typeof useAnalytics>["logEvent"];
+}
+/**
+ * Custom hook to manage the state and interactions of a single hierarchical option.
+ * Calculates checked/indeterminate state and provides a handler for value changes,
+ * including cascading logic.
+ */
+export declare const useHierarchicalOptionState: ({ options, option, selectedValues, cascadeSelection, optionsMap, setValue, filterDefinition, logEvent, }: UseHierarchicalOptionStateProps) => {
+    isChecked: boolean;
+    isIndeterminate: boolean;
+    handleSelect: () => void;
+};
+export {};

package/src/lib/components/index.d.ts

@@ -6,4 +6,5 @@ export * from "./DefaultRadioFilter";
 export * from "./DynamicFilterList";
 export * from "./FilterHeader";
 export * from "./FilterResults";
+export * from "./HierarchicalCheckboxFilter/HierarchicalCheckboxFilter";
 export * from "./StarredFilters";