@trackunit/filters-filter-bar 1.7.87 → 1.7.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/filters-filter-bar",
-  "version": "1.7.87",
+  "version": "1.7.90",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -9,23 +9,23 @@
   "dependencies": {
     "react": "19.0.0",
     "dequal": "^2.0.3",
-    "lodash": "4.17.21",
     "jest-fetch-mock": "^3.0.3",
     "tailwind-merge": "^2.0.0",
     "string-ts": "^2.0.0",
     "zod": "^3.23.8",
-    "@trackunit/iris-app-api": "1.6.53",
-    "@trackunit/react-core-hooks": "1.6.57",
-    "@trackunit/react-filter-components": "1.6.80",
-    "@trackunit/react-date-and-time-components": "1.9.80",
-    "@trackunit/shared-utils": "1.8.54",
-    "@trackunit/react-form-components": "1.7.45",
-    "@trackunit/react-core-contexts-api": "1.7.55",
-    "@trackunit/geo-json-utils": "1.6.53",
-    "@trackunit/i18n-library-translation": "1.6.58",
-    "@trackunit/css-class-variance-utilities": "1.6.53",
-    "@trackunit/react-components": "1.8.29",
-    "@trackunit/react-test-setup": "1.3.53"
+    "@trackunit/iris-app-api": "1.6.56",
+    "@trackunit/react-core-hooks": "1.6.60",
+    "@trackunit/react-filter-components": "1.6.83",
+    "@trackunit/react-date-and-time-components": "1.9.83",
+    "@trackunit/shared-utils": "1.8.57",
+    "@trackunit/react-form-components": "1.7.48",
+    "@trackunit/react-core-contexts-api": "1.7.58",
+    "@trackunit/geo-json-utils": "1.6.56",
+    "@trackunit/i18n-library-translation": "1.6.61",
+    "@trackunit/css-class-variance-utilities": "1.6.56",
+    "@trackunit/react-components": "1.8.32",
+    "@trackunit/react-test-setup": "1.3.56",
+    "@tanstack/react-router": "1.114.29"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/lib/hooks/types.d.ts

@@ -8,6 +8,10 @@ export type FilterPersistenceConfig<TFilterBarDefinition extends FilterBarDefini
      * An optional callback function that gets called when filter values change. This overrides the default behavior of saving filter values to local storage.
      */
     saveData?: (data: FilterStateValues<TFilterBarDefinition> | null) => void;
+    /**
+     * An optional callback function that gets called when filter values change. This overrides the default behavior of refreshing filter values.
+     */
+    refreshData?: () => void;
 };
 export interface FilterBarProps<TFilterBarDefinition extends FilterBarDefinition> extends FilterPersistenceConfig<TFilterBarDefinition> {
     /**

package/src/lib/hooks/useSearchParamAsFilter.d.ts

@@ -1,7 +1,6 @@
 import { ErrorHandlingContextValue } from "@trackunit/react-core-contexts-api";
 import { ZodTypeAny } from "zod";
 interface SearchParamAsFilterProps<TZodSchema> {
-    searchParamName: string;
     filterName: string;
     search: Record<PropertyKey, unknown>;
     zodSchema: TZodSchema;
@@ -12,12 +11,11 @@ interface SearchParamAsFilterProps<TZodSchema> {
  * The parameter is validated using the provided Zod schema.
  *
  * @template T - A Zod schema used for validation.
- * @param {string} searchParamName - The name of the search parameter in the URL.
  * @param {string} filterName - The name of the filter.
  * @param {object} search - The current search state, provided by `useSearch` from @tanstack/react-router.
  * @param {T} zodSchema - The Zod schema for validating the filter data.
  * @param {ErrorHandlingContextValue} errorHandler - Error handling context for capturing and reporting exceptions.
  * @returns {any} The parsed filter data if validation succeeds, otherwise `null`.
  */
-export declare const useSearchParamAsFilter: <TZodSchema extends ZodTypeAny>({ searchParamName, filterName, search, zodSchema, errorHandler, }: SearchParamAsFilterProps<TZodSchema>) => any;
+export declare const useSearchParamAsFilter: <TZodSchema extends ZodTypeAny>({ filterName, search, zodSchema, errorHandler, }: SearchParamAsFilterProps<TZodSchema>) => any;
 export {};

package/src/lib/hooks/utils/useFilterBarActions.d.ts

@@ -9,7 +9,7 @@ import { FilterBarConfig, FilterBarDefinition, FilterBarInferredValue, FilterMap
 declare const useFilterBarActions: <TFilterBarDefinition extends FilterBarDefinition>({ name, filterBarConfig, filterBarDefinition, setFilterBarConfig, setValue, initialState, }: {
     name: string;
     filterBarConfig: FilterBarConfig<TFilterBarDefinition>;
-    filterBarDefinition: FilterBarDefinition;
+    filterBarDefinition: TFilterBarDefinition;
     setFilterBarConfig: Dispatch<SetStateAction<FilterBarConfig<TFilterBarDefinition>>>;
     setValue: (key: string, callback: (prev: FilterBarInferredValue<TFilterBarDefinition, never> | undefined) => FilterBarInferredValue<TFilterBarDefinition, never> | undefined) => void;
     initialState?: InitialState<TFilterBarDefinition>;

package/src/lib/hooks/utils/useFilterBarPersistence.d.ts

@@ -1,9 +1,14 @@
-import { FilterBarConfig, FilterBarDefinition, FilterBarInferredValue } from "../../types/FilterTypes";
+import { FilterBarConfig, FilterBarDefinition, FilterBarInferredValue, FilterDefinition, FilterStateValues, FilterValueType } from "../../types/FilterTypes";
 import { FilterPersistenceConfig } from "../types";
 interface FilterBarPersistenceProps<TFilterBarDefinition extends FilterBarDefinition> extends FilterPersistenceConfig<TFilterBarDefinition> {
     name: string;
     setValue: (key: string, callback: (prev: FilterBarInferredValue<TFilterBarDefinition, never> | undefined) => FilterBarInferredValue<TFilterBarDefinition, never> | undefined) => void;
+    /**
+     * An optional callback function that gets called to check if a filter value is the default value.
+     */
+    isDefaultValue: (key: string, value: FilterValueType) => boolean;
 }
+export declare const MAX_URL_LENGTH = 5000;
 /**
  * Get the persistence key for the filter bar.
  *
@@ -15,12 +20,51 @@ export declare const getPersistenceKey: (name: string, clientSideUserId?: string
 /**
  * Custom hook for managing the persistence of filter bar configurations.
  *
+ * This hook provides a complete state management solution for filter bars with automatic
+ * URL synchronization and localStorage persistence. It maintains the following state:
+ *
+ * ## State Management Flow:
+ *
+ * 1. **Initial Load**:
+ *    - Loads from localStorage (if no custom loadData or saveData function is provided)
+ *    - Updates with state from URL search parameters
+ *    - Ensures URL is updated with the final state after load
+ *
+ * 2. **Save Operations**:
+ *    - Updates localStorage with new filter values
+ *    - Updates URL search parameters to reflect current state
+ *    - Maintains synchronization between localStorage and URL
+ *
+ * 3. **URL Change Detection**:
+ *    - Listens for changes in URL search parameters
+ *    - Compares URL state with last known state to detect external changes
+ *    - Triggers refreshData callback when external URL changes are detected
+ *    - Only updates URL when no custom loadData or saveData function provided
+ *
+ * ## Behavior Modes:
+ *
+ * **Default Mode** (no custom functions):
+ * - Uses localStorage for persistence
+ * - Automatically syncs with URL search parameters
+ * - Handles URL updates and change detection
+ *
+ * **Custom Mode** (with loadData/saveData functions):
+ * - Does NOT sync with URL or use localStorage
+ * - Relies entirely on provided functions for persistence
+ * - Does not provide URL change detection via refreshData callback
+ *
+ * The hook prevents infinite loops by:
+ * - Tracking what state was last sent to the URL
+ * - Only updating URL when state actually changes
+ * - Distinguishing between internal state changes and external URL changes
+ *
  * @template TFilterBarDefinition - The type of the filter bar definition.
  * @param {FilterBarPersistenceProps<TFilterBarDefinition>} props - The props for the filter bar persistence.
  * @returns { object } An object containing the loadData and saveData functions.
  */
-export declare const useFilterBarPersistence: <TFilterBarDefinition extends FilterBarDefinition>({ name, setValue, loadData: inputLoadData, saveData: inputSaveData, }: FilterBarPersistenceProps<TFilterBarDefinition>) => {
+export declare const useFilterBarPersistence: <TFilterBarDefinition extends FilterBarDefinition>({ name, setValue, refreshData, isDefaultValue, loadData: inputLoadData, saveData: inputSaveData, }: FilterBarPersistenceProps<TFilterBarDefinition>) => {
     loadData: <TFilterBarDefinitionExtended extends TFilterBarDefinition>(updatedFilterDefinitionsValues: Array<TFilterBarDefinitionExtended[keyof TFilterBarDefinitionExtended]>) => FilterBarConfig<TFilterBarDefinition>;
     saveData: (filterBarConfig: Partial<FilterBarConfig<TFilterBarDefinition>>, filterBarDefinitions: TFilterBarDefinition) => void;
+    getFilterValuesToUrl: (values: FilterStateValues<FilterBarDefinition> | null, definitions: Array<FilterDefinition>, setEmptyAndDefaultValues: boolean, isDefaultValue: (key: string, value: FilterValueType) => boolean) => Record<string, unknown>;
 };
 export {};

package/src/lib/hooks/utils/useFilterUrlSync.d.ts

@@ -0,0 +1,10 @@
+import { FilterBarDefinition, FilterDefinition, FilterStateValues, FilterValueType } from "../../types/FilterTypes";
+/**
+ * Hook to sync filter values with URL
+ *
+ * @returns {object} Object containing loadFromUrl and saveToUrl functions
+ */
+export declare const useFilterUrlSync: () => {
+    getFilterValuesFromUrl: <TFilterBarDefinition extends FilterBarDefinition>(definitions: Array<FilterDefinition>, search: Record<PropertyKey, unknown>) => FilterStateValues<TFilterBarDefinition>;
+    getFilterValuesToUrl: (values: FilterStateValues<FilterBarDefinition> | null, definitions: Array<FilterDefinition>, setEmptyAndDefaultValues: boolean, isDefaultValue: (key: string, value: FilterValueType) => boolean) => Record<string, unknown>;
+};

package/src/lib/hooks/utils/useIsDefaultValue.d.ts

@@ -0,0 +1,10 @@
+import { FilterBarDefinition, FilterValueType, InitialState } from "../../types/FilterTypes";
+/**
+ * Generic hook for setting the value of a filter bar.
+ *
+ * @template TFilterBarDefinition - The type of the filter bar definition.
+ * @returns {object} An object containing the setValue function.
+ */
+export declare const useIsDefaultValue: <TFilterBarDefinition extends FilterBarDefinition>() => {
+    isDefaultValue: (key: string, filterValue: FilterValueType, filterBarDefinition: TFilterBarDefinition, initialState?: InitialState<TFilterBarDefinition>) => boolean;
+};

package/src/lib/hooks/utils/useSearchUtils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This hook provides functionality to:
+ * - Get the length of the search parameters excluding a specific key
+ */
+export declare const useSearchUtils: () => {
+    getSearchParamsLengthExcluding: (excludeKey: string, searchParams: Record<PropertyKey, unknown>) => number;
+    getUrlLengthWithSearchParam: (key: string, value: string, prev: Record<PropertyKey, unknown>) => number;
+};

package/src/lib/types/FilterTypes.d.ts

@@ -1,5 +1,6 @@
 import { ReactNode } from "react";
-import { AreaFilterGeoJsonGeometry } from "./FilterZodTypes";
+import z, { ZodTypeAny } from "zod";
+import { AreaFilterGeoJsonGeometry, areaFilterGeoJsonGeometrySchema, booleanSchema, dateRangeSchema, minMaxFilterSchema, numberSchema, stringArraySchema, stringSchema, valueNameArraySchema, valueNameSchema } from "./FilterZodTypes";
 export type ValueName = {
     value: string;
     name: string;
@@ -14,7 +15,7 @@ export type MinMaxFilterValue = {
     min?: number;
     max?: number;
 };
-export type FilterValueType = Array<string> | Array<ValueName> | ValueName | MinMaxFilterValue | AreaFilterGeoJsonGeometry | string | number | BooleanValue | undefined;
+export type FilterValueType = Array<string> | Array<ValueName> | ValueName | DateRangeValue | MinMaxFilterValue | AreaFilterGeoJsonGeometry | string | number | BooleanValue | undefined;
 export declare type FilterTypes = "boolean" | "string" | "number" | "dateRange" | "area" | "valueNameArray" | "valueName" | "stringArray" | "minMax";
 export type FilterMapActions = {
     toggleArrayValue: (key: string, value: string) => void;
@@ -62,48 +63,63 @@ export interface AbstractFilterDefinition {
     showInFilterBar?: () => boolean;
     showDirectly?: boolean;
     isHidden?: boolean;
+    zodSchema?: ZodTypeAny;
 }
 export interface BooleanFilterDefinition extends AbstractFilterDefinition {
     type: "boolean";
     defaultValue?: BooleanValue;
     valueAsText?: (value: BooleanValue) => string;
     component: (filterComponentProps: FilterViewProps<BooleanValue>) => ReactNode;
+    zodSchema?: typeof booleanSchema;
 }
 export interface StringFilterDefinition extends AbstractFilterDefinition {
     type: "string";
     defaultValue?: string;
     valueAsText?: (value: string) => string;
     component: (filterComponentProps: FilterViewProps<string>) => ReactNode;
+    zodSchema?: typeof stringSchema;
 }
 export interface NumberFilterDefinition extends AbstractFilterDefinition {
     type: "number";
     defaultValue?: number;
     valueAsText?: (value: number) => string;
     component: (filterComponentProps: FilterViewProps<number>) => ReactNode;
+    zodSchema?: typeof numberSchema;
 }
 export interface AreaFilterDefinition extends AbstractFilterDefinition {
     type: "area";
     defaultValue?: AreaFilterGeoJsonGeometry;
     valueAsText?: (value: AreaFilterGeoJsonGeometry) => string;
     component: (filterComponentProps: FilterViewProps<AreaFilterGeoJsonGeometry>) => ReactNode;
+    zodSchema?: typeof areaFilterGeoJsonGeometrySchema;
 }
 export interface ValueNameArrayFilterDefinition extends AbstractFilterDefinition {
     type: "valueNameArray";
     defaultValue?: Array<ValueName>;
     valueAsText?: (value: Array<ValueName>) => Array<string>;
     component: (filterComponentProps: FilterViewProps<Array<ValueName>>) => ReactNode;
+    zodSchema?: typeof valueNameArraySchema;
 }
 export interface ValueNameFilterDefinition extends AbstractFilterDefinition {
     type: "valueName";
     defaultValue?: ValueName;
     valueAsText?: (value: ValueName) => string;
     component: (filterComponentProps: FilterViewProps<ValueName>) => ReactNode;
+    zodSchema?: typeof valueNameSchema;
 }
 export interface StringArrayFilterDefinition extends AbstractFilterDefinition {
     type: "stringArray";
     defaultValue?: Array<string>;
     valueAsText?: (value: Array<string>) => Array<string>;
     component: (filterComponentProps: FilterViewProps<Array<string>>) => ReactNode;
+    zodSchema?: typeof stringArraySchema;
+}
+export interface ArrayFilterDefinition<TZodType extends ZodTypeAny> extends AbstractFilterDefinition {
+    type: "stringArray";
+    defaultValue?: z.infer<TZodType>;
+    valueAsText?: (value: z.infer<TZodType>) => Array<string>;
+    component: (filterComponentProps: FilterViewProps<z.infer<TZodType>>) => ReactNode;
+    zodSchema: TZodType;
 }
 export interface MinMaxFilterDefinition extends AbstractFilterDefinition {
     type: "minMax";
@@ -118,6 +134,7 @@ export interface MinMaxFilterDefinition extends AbstractFilterDefinition {
     maximumNumber?: number | undefined;
     valueAsText?: (value: MinMaxFilterValue) => string;
     component: (filterComponentProps: FilterViewProps<MinMaxFilterValue>) => ReactNode;
+    zodSchema?: typeof minMaxFilterSchema;
 }
 export type DateRangeValue = {
     from: string | undefined;
@@ -136,8 +153,9 @@ export interface DateRangeFilterDefinition extends AbstractFilterDefinition {
     to?: string | undefined;
     valueAsText?: (value: DateRangeValue) => string;
     component: (filterComponentProps: FilterViewProps<DateRangeValue>) => ReactNode;
+    zodSchema?: typeof dateRangeSchema;
 }
-export type FilterDefinition = BooleanFilterDefinition | MinMaxFilterDefinition | StringFilterDefinition | NumberFilterDefinition | DateRangeFilterDefinition | AreaFilterDefinition | ValueNameFilterDefinition | ValueNameArrayFilterDefinition | StringArrayFilterDefinition;
+export type FilterDefinition = BooleanFilterDefinition | MinMaxFilterDefinition | StringFilterDefinition | NumberFilterDefinition | DateRangeFilterDefinition | AreaFilterDefinition | ValueNameFilterDefinition | ValueNameArrayFilterDefinition | ArrayFilterDefinition<any> | StringArrayFilterDefinition;
 export type FilterDefinitionValue = NonNullable<FilterDefinition["defaultValue"]>;
 export interface FilterViewProps<TReturnType> {
     filterDefinition: FilterDefinition;

package/src/lib/types/FilterZodTypes.d.ts

@@ -22,3 +22,47 @@ export declare const areaFilterGeoJsonGeometrySchema: z.ZodUnion<[z.ZodObject<{
     coordinates: [number, number][][][];
 }>]>;
 export type AreaFilterGeoJsonGeometry = z.infer<typeof areaFilterGeoJsonGeometrySchema>;
+export declare const stringSchema: z.ZodString;
+export declare const stringArraySchema: z.ZodArray<z.ZodString, "many">;
+export declare const numberSchema: z.ZodNumber;
+export declare const booleanSchema: z.ZodBoolean;
+export declare const valueNameSchema: z.ZodObject<{
+    value: z.ZodString;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    name: string;
+}, {
+    value: string;
+    name: string;
+}>;
+export declare const minMaxFilterSchema: z.ZodObject<{
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    min?: number | undefined;
+    max?: number | undefined;
+}, {
+    min?: number | undefined;
+    max?: number | undefined;
+}>;
+export declare const dateRangeSchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    from?: string | undefined;
+    to?: string | undefined;
+}, {
+    from?: string | undefined;
+    to?: string | undefined;
+}>;
+export declare const valueNameArraySchema: z.ZodArray<z.ZodObject<{
+    value: z.ZodString;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    name: string;
+}, {
+    value: string;
+    name: string;
+}>, "many">;