@rio-cloud/rio-uikit 1.10.1 → 1.12.0

package/src/hooks/useOnlineStatus.js

@@ -0,0 +1,15 @@
+// Inspired by https://github.com/WebDevSimplified/useful-custom-react-hooks/blob/main/src/26-useOnlineStatus/useOnlineStatus.js
+import { useState } from 'react';
+import useEvent from './useEvent';
+/**
+ * Custom hook to track online/offline status of the browser.
+ *
+ * @returns Returns true if the browser is online, otherwise false.
+ */
+const useOnlineStatus = () => {
+    const [online, setOnline] = useState(navigator.onLine);
+    useEvent('online', () => setOnline(navigator.onLine), false, window);
+    useEvent('offline', () => setOnline(navigator.onLine), false, window);
+    return online;
+};
+export default useOnlineStatus;

package/src/hooks/usePopperDropdown.d.ts

@@ -0,0 +1,16 @@
+import { type CSSProperties } from 'react';
+type UsePopperDropdownResult = {
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    referenceRef: any;
+    popperElementRef: (el: HTMLElement | null) => void;
+    popperStyles: CSSProperties;
+    popperAttributes: Record<string, any>;
+};
+type UsePopperDropdownParams = {
+    placement?: 'bottom-start' | 'bottom-end';
+};
+declare const usePopperDropdown: ({ placement }?: UsePopperDropdownParams) => UsePopperDropdownResult;
+export default usePopperDropdown;

package/src/hooks/usePopperDropdown.js

@@ -0,0 +1,24 @@
+import { useRef, useState } from 'react';
+import { usePopper } from 'react-popper';
+const usePopperDropdown = ({ placement = 'bottom-start' } = {}) => {
+    const referenceRef = useRef(null);
+    const [popperElement, setPopperElement] = useState(null);
+    const [isOpen, setIsOpen] = useState(false);
+    const popper = usePopper(referenceRef.current, popperElement, {
+        placement,
+    });
+    const open = () => setIsOpen(true);
+    const close = () => setIsOpen(false);
+    const toggle = () => setIsOpen(prev => !prev);
+    return {
+        isOpen,
+        open,
+        close,
+        toggle,
+        referenceRef,
+        popperElementRef: setPopperElement,
+        popperStyles: popper.styles.popper,
+        popperAttributes: popper.attributes.popper,
+    };
+};
+export default usePopperDropdown;

package/src/hooks/usePostMessage.d.ts

@@ -0,0 +1,32 @@
+export type RemoteAction = {
+    /**
+     * The RemoteAction is inspired by a plain redux action where the type is the
+     * action identifier.
+     *
+     * @example
+     *
+     * ```json
+     * {
+     *      "type": "EVENT_SET_VISIBLE_WIDGETS",
+     *      "payload": ["foo", "bar"],
+     * }
+     * ```
+     */
+    type: string;
+    /**
+     * The action payload itself.
+     */
+    payload: any;
+};
+/**
+ * A custom hook to ease the exchange of postMessage events between iframes and the parent window.
+ *
+ * @param messagePrefix a custom prefix to limit the event listener for these events
+ * @param onReceiveMessage a callback function triggered when a message is received
+ * @returns
+ */
+declare const usePostMessage: (messagePrefix: string, onReceiveMessage?: (eventData: any) => void) => {
+    sendMessageToParent: (message: RemoteAction) => void;
+    sendMessageToWidget: (message: RemoteAction, targetFrames: HTMLIFrameElement | HTMLIFrameElement[]) => void;
+};
+export default usePostMessage;

package/src/hooks/usePostMessage.js

@@ -0,0 +1,50 @@
+import { useEffect } from 'react';
+import noop from 'lodash/fp/noop';
+import isEmpty from 'lodash/fp/isEmpty';
+import isArray from 'lodash/fp/isArray';
+/**
+ * A custom hook to ease the exchange of postMessage events between iframes and the parent window.
+ *
+ * @param messagePrefix a custom prefix to limit the event listener for these events
+ * @param onReceiveMessage a callback function triggered when a message is received
+ * @returns
+ */
+const usePostMessage = (messagePrefix, onReceiveMessage) => {
+    const sendMessageToParent = (message) => {
+        const referrer = document.referrer;
+        if (referrer) {
+            window.parent.postMessage(message, referrer);
+        }
+    };
+    const sendMessageToWidget = (message, targetFrames) => {
+        if (!targetFrames || isEmpty(targetFrames)) {
+            return;
+        }
+        const frames = isArray(targetFrames) ? [...targetFrames] : [targetFrames];
+        [...frames].forEach(target => {
+            const contentWindow = target.contentWindow;
+            if (contentWindow) {
+                contentWindow.postMessage(message, '*');
+            }
+        });
+    };
+    const receiveMessage = (event, callback) => {
+        const actionType = event.data.type;
+        if (!actionType) {
+            return;
+        }
+        if (actionType.startsWith(messagePrefix)) {
+            callback(event.data);
+        }
+    };
+    useEffect(() => {
+        const listenerCallback = (event) => receiveMessage(event, onReceiveMessage || noop);
+        window.addEventListener('message', listenerCallback, false);
+        return () => window.removeEventListener('message', listenerCallback, false);
+    }, []);
+    return {
+        sendMessageToParent,
+        sendMessageToWidget,
+    };
+};
+export default usePostMessage;

package/src/hooks/usePrevious.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The usePrevious hook allows to easily access state from previous component render.
+ * Instead of using a *React.ref* or a *useEffect*, this hook uses a *useState* internally to keep track of the
+ * previous state value.
+ *
+ * Quoting from the React documentation:
+ *
+ * *In most cases, you don’t need this:*
+ *
+ * - *If the value you need can be computed entirely from the current props or other state, remove*
+ * *that redundant state altogether. If you’re worried about recomputing too often, the useMemo Hook can help.*
+ * - *If you want to reset the entire component tree’s state, pass a different key to your component.*
+ * - *If you can, update all the relevant state in the event handlers.*
+ *
+ * @link https://react.dev/reference/react/useState#storing-information-from-previous-renders
+ *
+ * @param state The value of the current state to keep track of.
+ * @returns
+ */
+declare const usePrevious: <T>(state: T, isEqualFunc?: ((value: T | null | undefined, current: T | null | undefined) => any) | undefined) => T;
+export default usePrevious;

package/src/hooks/usePrevious.js

@@ -0,0 +1,33 @@
+import { useRef } from 'react';
+import isEqual from 'lodash/fp/isEqual';
+// Based on the react beta docs, we avoid using an effect here but
+// use another state to store the previous value to compare to.
+// See: https://react.dev/reference/react/useState#storing-information-from-previous-renders
+/**
+ * The usePrevious hook allows to easily access state from previous component render.
+ * Instead of using a *React.ref* or a *useEffect*, this hook uses a *useState* internally to keep track of the
+ * previous state value.
+ *
+ * Quoting from the React documentation:
+ *
+ * *In most cases, you don’t need this:*
+ *
+ * - *If the value you need can be computed entirely from the current props or other state, remove*
+ * *that redundant state altogether. If you’re worried about recomputing too often, the useMemo Hook can help.*
+ * - *If you want to reset the entire component tree’s state, pass a different key to your component.*
+ * - *If you can, update all the relevant state in the event handlers.*
+ *
+ * @link https://react.dev/reference/react/useState#storing-information-from-previous-renders
+ *
+ * @param state The value of the current state to keep track of.
+ * @returns
+ */
+const usePrevious = (state, isEqualFunc) => {
+    const ref = useRef({ target: state, previous: state });
+    if (isEqualFunc ? !isEqualFunc(state, ref.current.target) : !isEqual(state, ref.current.target)) {
+        ref.current.previous = ref.current.target;
+        ref.current.target = state;
+    }
+    return ref.current.previous;
+};
+export default usePrevious;

package/src/hooks/useRenderCount.d.ts

@@ -0,0 +1,2 @@
+declare const useRenderCount: () => number;
+export default useRenderCount;

package/src/hooks/useRenderCount.js

@@ -0,0 +1,10 @@
+// Inspired by https://github.com/WebDevSimplified/useful-custom-react-hooks/blob/main/src/27-useRenderCount/useRenderCount.js
+import { useEffect, useRef } from 'react';
+const useRenderCount = () => {
+    const count = useRef(1);
+    useEffect(() => {
+        count.current++;
+    });
+    return count.current;
+};
+export default useRenderCount;

package/src/hooks/useResizeObserver.d.ts

@@ -0,0 +1,10 @@
+import { type MutableRefObject } from 'react';
+/**
+ * Custom hook for observing element resize.
+ * @returns
+ */
+declare const useResizeObserver: <T extends HTMLElement = HTMLDivElement>() => [MutableRefObject<T | null>, ResizeObserverEntry | null, {
+    blockSize: number | undefined;
+    inlineSize: number | undefined;
+}];
+export default useResizeObserver;

package/src/hooks/useResizeObserver.js

@@ -0,0 +1,31 @@
+// inspired from https://tobbelindstrom.com/blog/resize-observer-hook/
+import { useRef, useLayoutEffect, useState, useCallback } from 'react';
+/**
+ * Custom hook for observing element resize.
+ * @returns
+ */
+const useResizeObserver = () => {
+    const [observerEntry, setObserverEntry] = useState(null);
+    const nodeRef = useRef(null);
+    const observer = useRef(null);
+    const disconnect = useCallback(() => observer.current?.disconnect(), []);
+    const observe = useCallback(() => {
+        observer.current = new ResizeObserver(([entry]) => setObserverEntry(entry));
+        if (nodeRef.current) {
+            observer.current.observe(nodeRef.current);
+        }
+    }, [nodeRef]);
+    useLayoutEffect(() => {
+        observe();
+        return () => disconnect();
+    }, [disconnect, observe]);
+    return [
+        nodeRef,
+        observerEntry,
+        {
+            blockSize: observerEntry?.borderBoxSize?.at(0)?.blockSize,
+            inlineSize: observerEntry?.borderBoxSize?.at(0)?.inlineSize,
+        },
+    ];
+};
+export default useResizeObserver;

package/src/hooks/useScrollPosition.d.ts

@@ -0,0 +1,10 @@
+import { RefObject } from 'react';
+export type TargetType = Window | Document | HTMLBodyElement | HTMLElement | Element | React.ReactElement | RefObject<HTMLElement>;
+/**
+ * A custom hook that tracks the scroll position of a target element.
+ *
+ * @param target The target element for scroll position tracking.
+ * @returns The current scroll position of the target element.
+ */
+declare const useScrollPosition: (target?: TargetType) => number;
+export default useScrollPosition;

package/src/hooks/useScrollPosition.js

@@ -0,0 +1,65 @@
+import { useState, useEffect } from 'react';
+const getModuleContent = () => document.querySelector('.module-content > .scrollbar-view');
+// "target" can be "window", "document.body", a "ref" or undefined
+// where in later case the module-content is taken as default
+/**
+ * A custom hook that tracks the scroll position of a target element.
+ *
+ * @param target The target element for scroll position tracking.
+ * @returns The current scroll position of the target element.
+ */
+const useScrollPosition = (target) => {
+    const [targetElement, setTargetElement] = useState(null);
+    const [scrollPosition, setScrollPosition] = useState(0);
+    useEffect(() => {
+        let checkForModuleContent = null;
+        // In case the target is undefined it might be that the module-content is
+        // not rendered yet, hence check periodically for the existence in the DOM
+        if (!target) {
+            checkForModuleContent = setInterval(() => {
+                const element = getModuleContent();
+                if (element) {
+                    setTargetElement(element);
+                }
+            }, 300);
+        }
+        else if (target && checkForModuleContent) {
+            clearInterval(checkForModuleContent);
+        }
+        // In case the target is a "ref" - set the targetElement when current is defined
+        else if (target instanceof Object && 'current' in target && target.current) {
+            setTargetElement(target.current);
+        }
+        // In case it's "window" or "document.body"
+        else {
+            setTargetElement(target);
+        }
+        return () => {
+            if (checkForModuleContent) {
+                clearInterval(checkForModuleContent);
+            }
+        };
+    }, [target]);
+    const handleScroll = () => {
+        requestAnimationFrame(() => {
+            if (targetElement === window) {
+                setScrollPosition(window.scrollY);
+            }
+            else {
+                setScrollPosition(targetElement.scrollTop);
+            }
+        });
+    };
+    useEffect(() => {
+        if (targetElement instanceof EventTarget) {
+            targetElement.addEventListener('scroll', handleScroll);
+        }
+        return () => {
+            if (targetElement instanceof EventTarget) {
+                targetElement.removeEventListener('scroll', handleScroll);
+            }
+        };
+    }, [targetElement]);
+    return scrollPosition;
+};
+export default useScrollPosition;

package/src/hooks/useSearch.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Options for configuring the `useSearch` hook.
+ */
+type UseSearchOptions<T> = {
+    /**
+     * List of object fields to search within. Dot notation (e.g. `'address.city'`) is supported for nested properties.
+     * If omitted, all top-level string and number fields will be used.
+     */
+    fields?: (keyof T | string)[];
+    /**
+     * Optional custom filtering function.
+     * If provided, this takes precedence over field-based filtering.
+     *
+     * @param item - The current item in the list.
+     * @param query - The current search query string.
+     * @returns `true` if the item should be included in the filtered list.
+     */
+    customFilter?: (item: T, query: string) => boolean;
+    /**
+     * Number of milliseconds to debounce the search input.
+     * If omitted, debounce is disabled.
+     */
+    debounceMs?: number;
+    /**
+     * Whether to perform a case-sensitive match.
+     * Default is `false` (case-insensitive).
+     *
+     * @default false
+     */
+    caseSensitive?: boolean;
+};
+/**
+ * A hook to filter a list of objects by a search value.
+ * Supports field-based filtering, custom filtering logic, debounce, and case sensitivity.
+ *
+ * @template T - The type of items in the list (must be an object).
+ *
+ * @param list - The array of objects to search through.
+ * @param options - Configuration options for the search behavior.
+ * @param options.fields - Fields to search through. If omitted, all top-level string/number fields are used.
+ * @param options.customFilter - Optional custom filter function overriding field-based filtering.
+ * @param options.debounceMs - Debounce time in milliseconds.
+ * @param options.caseSensitive - Whether the search should be case-sensitive.
+ *
+ * @returns An object containing:
+ * - `searchValue`: The current search input string.
+ * - `setSearchValue`: A setter function to update the search query.
+ * - `filteredList`: The list of items matching the current search query.
+ *
+ * @example
+ * ```ts
+ * const { searchValue, setSearchValue, filteredList } = useSearch(users, {
+ *   fields: ['name', 'email'],
+ *   debounceMs: 300,
+ * });
+ * ```
+ */
+declare const useSearch: <T extends object>(list: T[], options?: UseSearchOptions<T>) => {
+    searchValue: string;
+    setSearchValue: import("react").Dispatch<import("react").SetStateAction<string>> | import("lodash").DebouncedFunc<(q: string) => void>;
+    filteredList: T[];
+};
+export default useSearch;

package/src/hooks/useSearch.js

@@ -0,0 +1,73 @@
+import { useMemo, useState, useCallback } from 'react';
+import { debounce } from 'lodash/fp';
+/**
+ * Gets the value of a nested field from an object using dot notation.
+ *
+ * @param obj - The object to traverse.
+ * @param path - The dot-notated path string.
+ * @returns The value at the specified path, or undefined.
+ */
+const getNestedValue = (obj, path) => path.split('.').reduce((val, key) => (val ? val[key] : undefined), obj);
+const inferSearchableFields = (item) => Object.keys(item).filter(key => {
+    const value = item[key];
+    return typeof value === 'string' || typeof value === 'number';
+});
+/**
+ * A hook to filter a list of objects by a search value.
+ * Supports field-based filtering, custom filtering logic, debounce, and case sensitivity.
+ *
+ * @template T - The type of items in the list (must be an object).
+ *
+ * @param list - The array of objects to search through.
+ * @param options - Configuration options for the search behavior.
+ * @param options.fields - Fields to search through. If omitted, all top-level string/number fields are used.
+ * @param options.customFilter - Optional custom filter function overriding field-based filtering.
+ * @param options.debounceMs - Debounce time in milliseconds.
+ * @param options.caseSensitive - Whether the search should be case-sensitive.
+ *
+ * @returns An object containing:
+ * - `searchValue`: The current search input string.
+ * - `setSearchValue`: A setter function to update the search query.
+ * - `filteredList`: The list of items matching the current search query.
+ *
+ * @example
+ * ```ts
+ * const { searchValue, setSearchValue, filteredList } = useSearch(users, {
+ *   fields: ['name', 'email'],
+ *   debounceMs: 300,
+ * });
+ * ```
+ */
+const useSearch = (list, options = {}) => {
+    const [searchValue, _setSearchValue] = useState('');
+    // Debounced setter
+    const setSearchValue = useCallback(options.debounceMs ? debounce(options.debounceMs, (q) => _setSearchValue(q)) : _setSearchValue, [options.debounceMs]);
+    const filteredList = useMemo(() => {
+        if (!searchValue) {
+            return list;
+        }
+        if (list.length === 0) {
+            return [];
+        }
+        const isCaseSensitive = options.caseSensitive ?? false;
+        const query = isCaseSensitive ? searchValue : searchValue.toLowerCase();
+        // Custom filter takes precedence
+        if (options.customFilter) {
+            return list.filter(item => options.customFilter?.(item, searchValue));
+        }
+        const fields = options.fields ?? inferSearchableFields(list[0]);
+        return list.filter(item => fields.some(field => {
+            const value = getNestedValue(item, field.toString());
+            if (typeof value === 'string') {
+                const target = isCaseSensitive ? value : value.toLowerCase();
+                return target.includes(query);
+            }
+            if (typeof value === 'number') {
+                return value.toString().includes(query);
+            }
+            return false;
+        }));
+    }, [list, options, searchValue]);
+    return { searchValue, setSearchValue, filteredList };
+};
+export default useSearch;

package/src/hooks/useSorting.d.ts

@@ -0,0 +1,35 @@
+import { type SortDirectionType } from '../utils/SortUtils';
+type SortKey<T> = keyof T | [keyof T, keyof T];
+type UseSortingResult<T> = {
+    /**
+     * The sorted data
+     */
+    sortedItems: T[];
+    /**
+     * The key(s) to sort the data for
+     */
+    sortKey: SortKey<T>;
+    /**
+     * The current direction that the data is sorted
+     */
+    sortDirection: SortDirectionType;
+    /**
+     * Function to change the sorting key(s) afterwards
+     * @param newKey the new sorting key(s)
+     * @returns
+     */
+    setSortKey: (newKey: SortKey<T>) => void;
+    /**
+     * Function to change the sorting order afterwards
+     * @param newKey the new sorting key(s)
+     * @returns
+     */
+    setSortDirection: (newSortDirection: SortDirectionType) => void;
+    /**
+     * Function to toggle the sorting between ascending and descending order
+     * @returns
+     */
+    toggleDirection: () => void;
+};
+declare const useSorting: <T>(items: T[], initialKey: SortKey<T>, initialDirection?: SortDirectionType, enableNaturalSort?: boolean, isCaseSensitive?: boolean) => UseSortingResult<T>;
+export default useSorting;

package/src/hooks/useSorting.js

@@ -0,0 +1,44 @@
+import { useState, useMemo } from 'react';
+import { naturalSortByProperty, SortDirection } from '../utils/SortUtils';
+const useSorting = (items, initialKey, initialDirection = SortDirection.ASCENDING, enableNaturalSort = true, isCaseSensitive = false) => {
+    const [sortKey, setSortKey] = useState(initialKey);
+    const [sortDirection, setSortDirection] = useState(initialDirection);
+    const sortedItems = useMemo(() => {
+        const sortByKey = (arr, key) => {
+            return enableNaturalSort
+                ? naturalSortByProperty(arr, key, sortDirection, isCaseSensitive)
+                : arr.sort((a, b) => {
+                    const aVal = a[key];
+                    const bVal = b[key];
+                    if (aVal < bVal) {
+                        return sortDirection === SortDirection.ASCENDING ? -1 : 1;
+                    }
+                    if (aVal > bVal) {
+                        return sortDirection === SortDirection.ASCENDING ? 1 : -1;
+                    }
+                    return 0;
+                });
+        };
+        if (Array.isArray(sortKey)) {
+            const [primaryKey, secondaryKey] = sortKey;
+            const primarySorted = sortByKey(items, primaryKey);
+            // Group items with the same primary key value
+            const groups = primarySorted.reduce((acc, item) => {
+                const key = String(item[primaryKey]);
+                if (!acc[key]) {
+                    acc[key] = [];
+                }
+                acc[key].push(item);
+                return acc;
+            }, {});
+            // Sort each group by the secondary key and flatten the result
+            return Object.values(groups).flatMap(group => sortByKey(group, secondaryKey));
+        }
+        return sortByKey(items, sortKey);
+    }, [items, sortKey, sortDirection, enableNaturalSort, isCaseSensitive]);
+    const toggleDirection = () => {
+        setSortDirection(prev => prev === SortDirection.ASCENDING ? SortDirection.DESCENDING : SortDirection.ASCENDING);
+    };
+    return { sortedItems, sortKey, sortDirection, setSortKey, setSortDirection, toggleDirection };
+};
+export default useSorting;

package/src/hooks/useStateWithValidation.d.ts

@@ -0,0 +1,12 @@
+export type ValidationFunction<T> = (value: T) => boolean;
+/**
+ * A custom hook that provides a state with validation.
+ *
+ * @param validationFn The function used to validate the state value.
+ * @param initialValue The initial value of the state.
+ *
+ * @returns A tuple containing the state value, a function to update the state
+ *          with validation, and a boolean indicating whether the current state value is valid.
+ */
+declare const useStateWithValidation: <T>(validationFn: ValidationFunction<T>, initialValue: T) => readonly [T, (nextState: T | ((prevState: T) => T)) => void, boolean];
+export default useStateWithValidation;

package/src/hooks/useStateWithValidation.js

@@ -0,0 +1,25 @@
+import { useCallback, useState } from 'react';
+/**
+ * A custom hook that provides a state with validation.
+ *
+ * @param validationFn The function used to validate the state value.
+ * @param initialValue The initial value of the state.
+ *
+ * @returns A tuple containing the state value, a function to update the state
+ *          with validation, and a boolean indicating whether the current state value is valid.
+ */
+const useStateWithValidation = (validationFn, initialValue) => {
+    const [state, setState] = useState(initialValue);
+    const [isValid, setIsValid] = useState(() => validationFn(state));
+    // Callback function to update the state with validation
+    const onChange = useCallback((nextState) => {
+        // Get the next value based on the provided nextState argument
+        const value = typeof nextState === 'function' ? nextState(state) : nextState;
+        // Update the state with the next value
+        setState(value);
+        // Update the isValid state based on the validation function
+        setIsValid(validationFn(value));
+    }, [validationFn, state]);
+    return [state, onChange, isValid];
+};
+export default useStateWithValidation;

package/src/hooks/useStorage.d.ts

@@ -0,0 +1,21 @@
+export type StorageType = 'localStorage' | 'sessionStorage';
+/**
+ * A custom hook for managing state stored in localStorage.
+ *
+ * @param key The key under which the state will be stored in localStorage.
+ * @param defaultValue The initial value for the state, or a function that returns the initial value.
+ *
+ * @returns A tuple containing the state value, a function to update the state, and a function
+ *          to remove the value from localStorage.
+ */
+export declare const useLocalStorage: <T>(key: string, defaultValue: T | (() => T)) => [T | undefined, React.Dispatch<React.SetStateAction<T | undefined>>, () => void];
+/**
+ * A custom hook for managing state stored in sessionStorage.
+ *
+ * @param key The key under which the state will be stored in sessionStorage.
+ * @param defaultValue The initial value for the state, or a function that returns the initial value.
+ *
+ * @returns A tuple containing the state value, a function to update the state,
+ *          and a function to remove the value from sessionStorage.
+ */
+export declare const useSessionStorage: <T>(key: string, defaultValue: T | (() => T)) => [T | undefined, React.Dispatch<React.SetStateAction<T | undefined>>, () => void];