@trackunit/react-core-hooks 0.2.262 → 0.2.264

package/index.cjs.js

@@ -25,7 +25,7 @@ function _interopNamespaceDefault(e) {
 var React__namespace = /*#__PURE__*/_interopNamespaceDefault(React);
 
 const AnalyticsContext = React.createContext(null);
-const AnalyticsContextProvider = AnalyticsContext.Provider;
+const AnalyticsContextProvider = AnalyticsContext.Provider; // easy import
 /**
  * Hook to get the analytics context.
  *
@@ -157,7 +157,7 @@ const useEnvironment = () => {
 };
 
 const ErrorHandlingContext = React.createContext(null);
-const ErrorHandlingContextProvider = ErrorHandlingContext.Provider;
+const ErrorHandlingContextProvider = ErrorHandlingContext.Provider; // easy import
 /**
  * Hook to get the error handling context.
  *
@@ -882,6 +882,154 @@ const useCurrentUser = () => {
     return context;
 };
 
+/**
+ * Validates the state object using a Zod schema.
+ *
+ * @template TState - The type of the state.
+ * @param {ValidateStateOptions<TState>} params - The parameters for the validateState function.
+ */
+const validateState = ({ state, schema, onValidationFailed, onValidationSuccessful, defaultState, }) => {
+    try {
+        const parsedState = schema.parse(state);
+        onValidationSuccessful === null || onValidationSuccessful === void 0 ? void 0 : onValidationSuccessful(parsedState);
+        return parsedState;
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error("Failed to parse and validate the state from local storage.", error);
+        onValidationFailed === null || onValidationFailed === void 0 ? void 0 : onValidationFailed(error);
+        return defaultState;
+    }
+};
+
+/**
+ * Initializes the state from local storage, parsing and validating it if a Zod schema is provided.
+ *
+ * @template TState - The type of the state stored in local storage.
+ * @param {Omit<LocalStorageParams<TState>, "state">} params - The parameters for initializing the local storage state.
+ * @returns {TState} - The initialized state.
+ */
+const initLocalStorageState = ({ key, defaultState, schema, }) => {
+    const localStorageItem = localStorage.getItem(key);
+    if (!localStorageItem) {
+        return defaultState;
+    }
+    const localStorageItemJSON = JSON.parse(localStorageItem);
+    if (!schema) {
+        return localStorageItemJSON;
+    }
+    return validateState({ state: localStorageItemJSON, defaultState, schema });
+};
+
+/**
+ * The usePrevious hook is a useful tool for tracking the previous value of a variable in a functional component. This can be particularly handy in scenarios where it is necessary to compare the current value with the previous one, such as triggering actions or rendering based on changes.
+ *
+ * @example
+ * const [color, setColor] = React.useState(getRandomColor());
+  const previousColor = usePrevious(color);
+ */
+const usePrevious = (value) => {
+    const ref = React.useRef();
+    React.useEffect(() => {
+        ref.current = value;
+    }, [value]);
+    return ref.current;
+};
+
+/**
+ * Sets a value in the local storage with the specified key.
+ * Thin wrapper around localStorage.setItem() that is slightly more type safe
+ * Stringifies value automatically.
+ * Useful if you for some reason can't use the useLocalStorage hook for React lifecycle reasons
+ *
+ * @template TValue - The type of value to be stored.
+ * @param {string} key - The key under which to store the value.
+ * @param {TValue} value - The value to store in the local storage.
+ */
+const setLocalStorage = (key, value) => {
+    localStorage.setItem(key, JSON.stringify(value));
+};
+
+/**
+ * Custom hook for synchronizing a state variable with local storage,
+ * with optional schema validation and callbacks.
+ *
+ * @template TState - The type of the state variable.
+ * @param {LocalStorageParams<TState> & LocalStorageCallbacks & { state: TState }} params - The parameters for the useLocalStorageEffect hook.
+ */
+const useLocalStorageEffect = ({ key, state, defaultState, schema, onValidationFailed, onValidationSuccessful, }) => {
+    const prevState = usePrevious(state);
+    React.useEffect(() => {
+        if (JSON.stringify(prevState) === JSON.stringify(state)) {
+            return;
+        }
+        if (schema) {
+            validateState({
+                state,
+                schema,
+                defaultState,
+                onValidationFailed: error => {
+                    // eslint-disable-next-line no-console
+                    console.error(`State validation failed. Resetting local storage to default state: ${defaultState}.`, error);
+                    localStorage.removeItem(key);
+                    onValidationFailed === null || onValidationFailed === void 0 ? void 0 : onValidationFailed(error);
+                },
+                onValidationSuccessful: data => {
+                    setLocalStorage(key, data);
+                    onValidationSuccessful === null || onValidationSuccessful === void 0 ? void 0 : onValidationSuccessful(data);
+                },
+            });
+        }
+        else {
+            const stringifiedState = JSON.stringify(state);
+            localStorage.setItem(key, stringifiedState);
+        }
+    }, [state, key, schema, defaultState, prevState, onValidationFailed, onValidationSuccessful]);
+};
+
+/**
+ * Works like a normal useState, but saves to local storage and has optional schema validation.
+ *
+ * @template TState - The type of the value stored in local storage.
+ * @param {Omit<LocalStorageParams<TState>, "state"> & LocalStorageCallbacks} options - The options for useLocalStorage.
+ * @returns {[TState, Dispatch<SetStateAction<TState>>, () => void]} - A tuple containing the current value, a function to update the value, and a function to remove the value from local storage.
+ */
+const useLocalStorage = ({ key, defaultState, schema, onValidationFailed, onValidationSuccessful, }) => {
+    if (!key) {
+        throw new Error("useLocalStorage key may not be falsy");
+    }
+    const [state, setState] = React.useState(initLocalStorageState({ key, defaultState, schema }));
+    useLocalStorageEffect({
+        key,
+        state,
+        defaultState,
+        schema,
+        onValidationFailed,
+        onValidationSuccessful,
+    });
+    const reset = () => {
+        setState(defaultState);
+    };
+    return [state, setState, reset];
+};
+
+/**
+ * Works like a normal useReducer, but saves to local storage and has optional schema validation.
+ *
+ * @template TState - The type of the state.
+ * @template TAction - The type of the action.
+ * @param {LocalStorageParams<TState> & LocalStorageCallbacks} params - The parameters for the useLocalStorageReducer function.
+ * @returns {[TState, Dispatch<TAction>]} - A tuple containing the state and the dispatch function.
+ */
+const useLocalStorageReducer = ({ key, defaultState, reducer, schema, onValidationFailed, onValidationSuccessful, }) => {
+    if (!key) {
+        throw new Error("useLocalStorage key may not be falsy");
+    }
+    const [state, dispatch] = React.useReducer(reducer, defaultState, () => initLocalStorageState({ key, defaultState, schema }));
+    useLocalStorageEffect({ key, state, defaultState, schema, onValidationFailed, onValidationSuccessful });
+    return [state, dispatch];
+};
+
 exports.AnalyticsContext = AnalyticsContext;
 exports.AnalyticsContextProvider = AnalyticsContextProvider;
 exports.AssetSortingProvider = AssetSortingProvider;
@@ -918,9 +1066,12 @@ exports.useImageUploader = useImageUploader;
 exports.useIrisAppId = useIrisAppId;
 exports.useIrisAppImage = useIrisAppImage;
 exports.useIrisAppName = useIrisAppName;
+exports.useLocalStorage = useLocalStorage;
+exports.useLocalStorageReducer = useLocalStorageReducer;
 exports.useModalDialogContext = useModalDialogContext;
 exports.useNavigateInHost = useNavigateInHost;
 exports.useOemBrandingContext = useOemBrandingContext;
+exports.usePrevious = usePrevious;
 exports.useSiteRuntime = useSiteRuntime;
 exports.useTextSearch = useTextSearch;
 exports.useToast = useToast;

package/index.esm.js

@@ -1,11 +1,11 @@
 import * as React from 'react';
-import { createContext, useContext, useMemo, useState, useCallback, useEffect } from 'react';
+import { createContext, useContext, useMemo, useState, useCallback, useEffect, useRef, useReducer } from 'react';
 import { jsx } from 'react/jsx-runtime';
 import { AssetRuntime, CustomerRuntime, EventRuntime, ParamsRuntime, SiteRuntime } from '@trackunit/iris-app-runtime-core';
 import { filterByMultiple } from '@trackunit/shared-utils';
 
 const AnalyticsContext = createContext(null);
-const AnalyticsContextProvider = AnalyticsContext.Provider;
+const AnalyticsContextProvider = AnalyticsContext.Provider; // easy import
 /**
  * Hook to get the analytics context.
  *
@@ -137,7 +137,7 @@ const useEnvironment = () => {
 };
 
 const ErrorHandlingContext = createContext(null);
-const ErrorHandlingContextProvider = ErrorHandlingContext.Provider;
+const ErrorHandlingContextProvider = ErrorHandlingContext.Provider; // easy import
 /**
  * Hook to get the error handling context.
  *
@@ -862,4 +862,152 @@ const useCurrentUser = () => {
     return context;
 };
 
-export { AnalyticsContext, AnalyticsContextProvider, AssetSortingProvider, ConfirmationDialogProvider, CurrentUserPreferenceProvider, CurrentUserProvider, EnvironmentContextProvider, ErrorHandlingContext, ErrorHandlingContextProvider, FilterBarProvider, ModalDialogContextProvider, NavigationContextProvider, OemBrandingContextProvider, ToastProvider, TokenProvider, UserSubscriptionProvider, fetchAssetBlobUrl, useAnalytics, useAssetRuntime, useAssetSorting, useConfirmationDialog, useCurrentUser, useCurrentUserLanguage, useCurrentUserSystemOfMeasurement, useCurrentUserTimeZonePreference, useCustomerRuntime, useEnvironment, useErrorHandler, useEventRuntime, useFeatureBranchQueryString, useFilterBarContext, useHasAccessTo, useImageUploader, useIrisAppId, useIrisAppImage, useIrisAppName, useModalDialogContext, useNavigateInHost, useOemBrandingContext, useSiteRuntime, useTextSearch, useToast, useToken, useUserSubscription };
+/**
+ * Validates the state object using a Zod schema.
+ *
+ * @template TState - The type of the state.
+ * @param {ValidateStateOptions<TState>} params - The parameters for the validateState function.
+ */
+const validateState = ({ state, schema, onValidationFailed, onValidationSuccessful, defaultState, }) => {
+    try {
+        const parsedState = schema.parse(state);
+        onValidationSuccessful === null || onValidationSuccessful === void 0 ? void 0 : onValidationSuccessful(parsedState);
+        return parsedState;
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error("Failed to parse and validate the state from local storage.", error);
+        onValidationFailed === null || onValidationFailed === void 0 ? void 0 : onValidationFailed(error);
+        return defaultState;
+    }
+};
+
+/**
+ * Initializes the state from local storage, parsing and validating it if a Zod schema is provided.
+ *
+ * @template TState - The type of the state stored in local storage.
+ * @param {Omit<LocalStorageParams<TState>, "state">} params - The parameters for initializing the local storage state.
+ * @returns {TState} - The initialized state.
+ */
+const initLocalStorageState = ({ key, defaultState, schema, }) => {
+    const localStorageItem = localStorage.getItem(key);
+    if (!localStorageItem) {
+        return defaultState;
+    }
+    const localStorageItemJSON = JSON.parse(localStorageItem);
+    if (!schema) {
+        return localStorageItemJSON;
+    }
+    return validateState({ state: localStorageItemJSON, defaultState, schema });
+};
+
+/**
+ * The usePrevious hook is a useful tool for tracking the previous value of a variable in a functional component. This can be particularly handy in scenarios where it is necessary to compare the current value with the previous one, such as triggering actions or rendering based on changes.
+ *
+ * @example
+ * const [color, setColor] = React.useState(getRandomColor());
+  const previousColor = usePrevious(color);
+ */
+const usePrevious = (value) => {
+    const ref = useRef();
+    useEffect(() => {
+        ref.current = value;
+    }, [value]);
+    return ref.current;
+};
+
+/**
+ * Sets a value in the local storage with the specified key.
+ * Thin wrapper around localStorage.setItem() that is slightly more type safe
+ * Stringifies value automatically.
+ * Useful if you for some reason can't use the useLocalStorage hook for React lifecycle reasons
+ *
+ * @template TValue - The type of value to be stored.
+ * @param {string} key - The key under which to store the value.
+ * @param {TValue} value - The value to store in the local storage.
+ */
+const setLocalStorage = (key, value) => {
+    localStorage.setItem(key, JSON.stringify(value));
+};
+
+/**
+ * Custom hook for synchronizing a state variable with local storage,
+ * with optional schema validation and callbacks.
+ *
+ * @template TState - The type of the state variable.
+ * @param {LocalStorageParams<TState> & LocalStorageCallbacks & { state: TState }} params - The parameters for the useLocalStorageEffect hook.
+ */
+const useLocalStorageEffect = ({ key, state, defaultState, schema, onValidationFailed, onValidationSuccessful, }) => {
+    const prevState = usePrevious(state);
+    useEffect(() => {
+        if (JSON.stringify(prevState) === JSON.stringify(state)) {
+            return;
+        }
+        if (schema) {
+            validateState({
+                state,
+                schema,
+                defaultState,
+                onValidationFailed: error => {
+                    // eslint-disable-next-line no-console
+                    console.error(`State validation failed. Resetting local storage to default state: ${defaultState}.`, error);
+                    localStorage.removeItem(key);
+                    onValidationFailed === null || onValidationFailed === void 0 ? void 0 : onValidationFailed(error);
+                },
+                onValidationSuccessful: data => {
+                    setLocalStorage(key, data);
+                    onValidationSuccessful === null || onValidationSuccessful === void 0 ? void 0 : onValidationSuccessful(data);
+                },
+            });
+        }
+        else {
+            const stringifiedState = JSON.stringify(state);
+            localStorage.setItem(key, stringifiedState);
+        }
+    }, [state, key, schema, defaultState, prevState, onValidationFailed, onValidationSuccessful]);
+};
+
+/**
+ * Works like a normal useState, but saves to local storage and has optional schema validation.
+ *
+ * @template TState - The type of the value stored in local storage.
+ * @param {Omit<LocalStorageParams<TState>, "state"> & LocalStorageCallbacks} options - The options for useLocalStorage.
+ * @returns {[TState, Dispatch<SetStateAction<TState>>, () => void]} - A tuple containing the current value, a function to update the value, and a function to remove the value from local storage.
+ */
+const useLocalStorage = ({ key, defaultState, schema, onValidationFailed, onValidationSuccessful, }) => {
+    if (!key) {
+        throw new Error("useLocalStorage key may not be falsy");
+    }
+    const [state, setState] = useState(initLocalStorageState({ key, defaultState, schema }));
+    useLocalStorageEffect({
+        key,
+        state,
+        defaultState,
+        schema,
+        onValidationFailed,
+        onValidationSuccessful,
+    });
+    const reset = () => {
+        setState(defaultState);
+    };
+    return [state, setState, reset];
+};
+
+/**
+ * Works like a normal useReducer, but saves to local storage and has optional schema validation.
+ *
+ * @template TState - The type of the state.
+ * @template TAction - The type of the action.
+ * @param {LocalStorageParams<TState> & LocalStorageCallbacks} params - The parameters for the useLocalStorageReducer function.
+ * @returns {[TState, Dispatch<TAction>]} - A tuple containing the state and the dispatch function.
+ */
+const useLocalStorageReducer = ({ key, defaultState, reducer, schema, onValidationFailed, onValidationSuccessful, }) => {
+    if (!key) {
+        throw new Error("useLocalStorage key may not be falsy");
+    }
+    const [state, dispatch] = useReducer(reducer, defaultState, () => initLocalStorageState({ key, defaultState, schema }));
+    useLocalStorageEffect({ key, state, defaultState, schema, onValidationFailed, onValidationSuccessful });
+    return [state, dispatch];
+};
+
+export { AnalyticsContext, AnalyticsContextProvider, AssetSortingProvider, ConfirmationDialogProvider, CurrentUserPreferenceProvider, CurrentUserProvider, EnvironmentContextProvider, ErrorHandlingContext, ErrorHandlingContextProvider, FilterBarProvider, ModalDialogContextProvider, NavigationContextProvider, OemBrandingContextProvider, ToastProvider, TokenProvider, UserSubscriptionProvider, fetchAssetBlobUrl, useAnalytics, useAssetRuntime, useAssetSorting, useConfirmationDialog, useCurrentUser, useCurrentUserLanguage, useCurrentUserSystemOfMeasurement, useCurrentUserTimeZonePreference, useCustomerRuntime, useEnvironment, useErrorHandler, useEventRuntime, useFeatureBranchQueryString, useFilterBarContext, useHasAccessTo, useImageUploader, useIrisAppId, useIrisAppImage, useIrisAppName, useLocalStorage, useLocalStorageReducer, useModalDialogContext, useNavigateInHost, useOemBrandingContext, usePrevious, useSiteRuntime, useTextSearch, useToast, useToken, useUserSubscription };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-core-hooks",
-  "version": "0.2.262",
+  "version": "0.2.264",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -11,7 +11,8 @@
     "react": "18.3.1",
     "@trackunit/iris-app-runtime-core": "*",
     "jest-fetch-mock": "^3.0.3",
-    "@trackunit/shared-utils": "*"
+    "@trackunit/shared-utils": "*",
+    "zod": "3.22.4"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/index.d.ts

@@ -22,3 +22,6 @@ export * from "./useFeatureBranchQueryString";
 export * from "./useTextSearch";
 export * from "./user/CurrentUserPreferenceProvider";
 export * from "./user/CurrentUserProvider";
+export * from "./localStorage/useLocalStorage";
+export * from "./localStorage/useLocalStorageReducer";
+export * from "./usePrevious";

package/src/localStorage/initLocalStorageState.d.ts

@@ -0,0 +1,9 @@
+import { LocalStorageParams } from "./types";
+/**
+ * Initializes the state from local storage, parsing and validating it if a Zod schema is provided.
+ *
+ * @template TState - The type of the state stored in local storage.
+ * @param {Omit<LocalStorageParams<TState>, "state">} params - The parameters for initializing the local storage state.
+ * @returns {TState} - The initialized state.
+ */
+export declare const initLocalStorageState: <TState>({ key, defaultState, schema, }: Omit<LocalStorageParams<TState>, "state">) => any;

package/src/localStorage/setLocalStorage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sets a value in the local storage with the specified key.
+ * Thin wrapper around localStorage.setItem() that is slightly more type safe
+ * Stringifies value automatically.
+ * Useful if you for some reason can't use the useLocalStorage hook for React lifecycle reasons
+ *
+ * @template TValue - The type of value to be stored.
+ * @param {string} key - The key under which to store the value.
+ * @param {TValue} value - The value to store in the local storage.
+ */
+export declare const setLocalStorage: <TValue>(key: string, value: TValue) => void;

package/src/localStorage/types.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export interface LocalStorageParams<TState> {
+    /**
+     * The key used to store the value in local storage.
+     */
+    key: string;
+    /**
+     * The default state value.
+     */
+    defaultState: TState;
+    /**
+     * Optional schema for validating the state.
+     */
+    schema?: z.Schema<TState>;
+}
+export interface LocalStorageCallbacks<TState> {
+    /**
+     * Optional callback function called when validation fails.
+     *
+     * @param error - The validation error object.
+     */
+    onValidationFailed?: (error: unknown) => void;
+    /**
+     * Optional callback function called when validation succeeds.
+     */
+    onValidationSuccessful?: (data: TState) => void;
+}

package/src/localStorage/useLocalStorage.d.ts

@@ -0,0 +1,10 @@
+import { Dispatch, SetStateAction } from "react";
+import { LocalStorageCallbacks, LocalStorageParams } from "./types";
+/**
+ * Works like a normal useState, but saves to local storage and has optional schema validation.
+ *
+ * @template TState - The type of the value stored in local storage.
+ * @param {Omit<LocalStorageParams<TState>, "state"> & LocalStorageCallbacks} options - The options for useLocalStorage.
+ * @returns {[TState, Dispatch<SetStateAction<TState>>, () => void]} - A tuple containing the current value, a function to update the value, and a function to remove the value from local storage.
+ */
+export declare const useLocalStorage: <TState>({ key, defaultState, schema, onValidationFailed, onValidationSuccessful, }: LocalStorageParams<TState> & LocalStorageCallbacks<TState>) => readonly [TState, Dispatch<SetStateAction<TState>>, () => void];

package/src/localStorage/useLocalStorageEffect.d.ts

@@ -0,0 +1,11 @@
+import { LocalStorageCallbacks, LocalStorageParams } from "./types";
+/**
+ * Custom hook for synchronizing a state variable with local storage,
+ * with optional schema validation and callbacks.
+ *
+ * @template TState - The type of the state variable.
+ * @param {LocalStorageParams<TState> & LocalStorageCallbacks & { state: TState }} params - The parameters for the useLocalStorageEffect hook.
+ */
+export declare const useLocalStorageEffect: <TState>({ key, state, defaultState, schema, onValidationFailed, onValidationSuccessful, }: LocalStorageParams<TState> & LocalStorageCallbacks<TState> & {
+    state: TState;
+}) => void;

package/src/localStorage/useLocalStorageReducer.d.ts

@@ -0,0 +1,13 @@
+import { Dispatch } from "react";
+import { LocalStorageCallbacks, LocalStorageParams } from "./types";
+/**
+ * Works like a normal useReducer, but saves to local storage and has optional schema validation.
+ *
+ * @template TState - The type of the state.
+ * @template TAction - The type of the action.
+ * @param {LocalStorageParams<TState> & LocalStorageCallbacks} params - The parameters for the useLocalStorageReducer function.
+ * @returns {[TState, Dispatch<TAction>]} - A tuple containing the state and the dispatch function.
+ */
+export declare const useLocalStorageReducer: <TState, TAction>({ key, defaultState, reducer, schema, onValidationFailed, onValidationSuccessful, }: {
+    reducer: (state: TState, action: TAction) => TState;
+} & LocalStorageParams<TState> & LocalStorageCallbacks<TState>) => readonly [TState, Dispatch<TAction>];

package/src/localStorage/validateState.d.ts

@@ -0,0 +1,13 @@
+import { LocalStorageCallbacks, LocalStorageParams } from "./types";
+type ValidateStateOptions<TState> = Required<Pick<LocalStorageParams<TState>, "schema">> & {
+    state: TState;
+    defaultState: TState;
+} & LocalStorageCallbacks<TState>;
+/**
+ * Validates the state object using a Zod schema.
+ *
+ * @template TState - The type of the state.
+ * @param {ValidateStateOptions<TState>} params - The parameters for the validateState function.
+ */
+export declare const validateState: <TState>({ state, schema, onValidationFailed, onValidationSuccessful, defaultState, }: ValidateStateOptions<TState>) => TState;
+export {};

package/src/usePrevious.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The usePrevious hook is a useful tool for tracking the previous value of a variable in a functional component. This can be particularly handy in scenarios where it is necessary to compare the current value with the previous one, such as triggering actions or rendering based on changes.
+ *
+ * @example
+ * const [color, setColor] = React.useState(getRandomColor());
+  const previousColor = usePrevious(color);
+ */
+export declare const usePrevious: <TValue>(value: TValue) => TValue | undefined;