@rio-cloud/rio-uikit 1.11.0 → 1.12.0

package/lib/es/src/hooks/useLocationSuggestions.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const react_1 = require("react");
+const debounce_1 = tslib_1.__importDefault(require("lodash/fp/debounce"));
+const DEFAULT_URL = 'https://autocomplete.search.hereapi.com/v1/autocomplete';
+const fetchLocationSuggestions = async (query, signal, options = {}) => {
+    const { apiKey, fetchUrl = DEFAULT_URL, limit = 5, ...restOptions } = options;
+    if (!query || !apiKey) {
+        return [];
+    }
+    const params = new URLSearchParams({
+        q: query,
+        apiKey,
+        limit: String(limit),
+        // Add any additional options dynamically
+        ...restOptions,
+    });
+    const response = await fetch(`${fetchUrl}?${params.toString()}`, { signal });
+    if (!response.ok) {
+        // Throw an error for bad responses (4xx, 5xx)
+        // This allows the hook's catch block to handle API errors
+        throw new Error(`API request failed with status ${response.status}`);
+    }
+    const data = await response.json();
+    // Ensure data.items exists and is an array before mapping
+    return Array.isArray(data?.items)
+        ? data.items.map((item) => ({
+            id: item.id,
+            label: item.title,
+        }))
+        : [];
+};
+const FETCH_DEBOUNCE_IN_MS = 300;
+/**
+ * Custom React hook for fetching location suggestions using HERE Maps Autocomplete API.
+ *
+ * @param query - The user input string to search for location suggestions.
+ * @param options - Optional configuration:
+ *   - apiKey: Your HERE Maps API key (default is 'YOUR_API_KEY').
+ *   - fetchUrl: Optional override for the autocomplete endpoint URL.
+ * @returns An object containing:
+ *   - suggestions: Array of location suggestions with `id` and `label`.
+ *   - loading: Boolean indicating whether the fetch is in progress.
+ *   - error: Any error that occurred during fetching.
+ */
+const useLocationSuggestions = (query, options = {}) => {
+    const [suggestions, setSuggestions] = (0, react_1.useState)([]);
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const abortRef = (0, react_1.useRef)(null);
+    // React re-renders the component every time state or props change. If we define the debounce() call
+    // directly inside the component without useRef, we'll create a new debounced function on every render,
+    // which defeats the purpose of debouncing.
+    // By wrapping it in useRef, we ensure the debounced function is created only once and persists between renders
+    const debouncedFetch = (0, react_1.useRef)((0, debounce_1.default)(FETCH_DEBOUNCE_IN_MS, async (currentQuery, currentOptions) => {
+        // Abort any ongoing request from previous calls
+        abortRef.current?.abort();
+        const controller = new AbortController();
+        abortRef.current = controller;
+        // Reset error before a new fetch attempt
+        setError(null);
+        try {
+            const results = await fetchLocationSuggestions(currentQuery, controller.signal, currentOptions);
+            setSuggestions(results);
+        }
+        catch (fetchError) {
+            if (fetchError.name !== 'AbortError') {
+                setError(fetchError);
+            }
+            setSuggestions([]);
+        }
+        finally {
+            setLoading(false);
+        }
+    })).current;
+    // biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
+    (0, react_1.useEffect)(() => {
+        if (!query || !options.apiKey) {
+            setSuggestions([]);
+            setLoading(false);
+            // Abort if there was an ongoing request
+            abortRef.current?.abort();
+            return;
+        }
+        setLoading(true);
+        debouncedFetch(query, options);
+    }, [query, debouncedFetch, options.apiKey, options.fetchUrl]); // `debouncedFetch` is stable due to useRef
+    // Cleanup on unmount
+    (0, react_1.useEffect)(() => {
+        return () => {
+            abortRef.current?.abort();
+        };
+    }, []);
+    return { suggestions, loading, error };
+};
+exports.default = useLocationSuggestions;

package/lib/es/src/hooks/useMax.d.ts

@@ -0,0 +1,18 @@
+export type UseMaxOptions = {
+    /**
+     * The locale used to parse localized number formats (e.g. "de-DE", "en-GB").
+     * @default "en-GB".
+     */
+    locale?: string;
+};
+/**
+ * Finds the maximum numeric value from a list of objects.
+ * Values are extracted using a dot-separated path and parsed with locale awareness.
+ *
+ * @param items - The list of objects to evaluate.
+ * @param path - Dot-separated path to the value in each object.
+ * @param options - Optional configuration (e.g. locale for number parsing).
+ * @returns The largest of all valid values, or 0 if none are valid.
+ */
+declare const useMax: (items: unknown[], path: string, options?: UseMaxOptions) => number;
+export default useMax;

package/lib/es/src/hooks/useMax.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = require("react");
+const formatUtils_1 = require("../utils/formatUtils");
+/**
+ * Finds the maximum numeric value from a list of objects.
+ * Values are extracted using a dot-separated path and parsed with locale awareness.
+ *
+ * @param items - The list of objects to evaluate.
+ * @param path - Dot-separated path to the value in each object.
+ * @param options - Optional configuration (e.g. locale for number parsing).
+ * @returns The largest of all valid values, or 0 if none are valid.
+ */
+const useMax = (items, path, options = {}) => {
+    const { locale = 'en-GB' } = options;
+    return (0, react_1.useMemo)(() => {
+        const values = items
+            .map(item => {
+            const valueFromPath = (0, formatUtils_1.getValueByPath)(item, path);
+            return (0, formatUtils_1.parseNumberFromValue)(valueFromPath, locale);
+        })
+            .filter(num => !Number.isNaN(num));
+        return values.length > 0 ? Math.max(...values) : 0;
+    }, [items, path, locale]);
+};
+exports.default = useMax;

package/lib/es/src/hooks/useMergeRefs.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+export type ReactRef<T> = React.RefCallback<T> | React.MutableRefObject<T>;
+/**
+ * Custom hook to merge multiple React references into a single callback ref.
+ *
+ * @param refs - The React references to merge.
+ * @returns A memoized callback function to assign the merged references to a node.
+ */
+declare const useMergeRefs: <T>(...refs: (ReactRef<T> | null | undefined)[]) => (node: T | null) => void;
+export default useMergeRefs;

package/lib/es/src/hooks/useMergeRefs.js

@@ -0,0 +1,48 @@
+"use strict";
+// forked from https://github.com/chakra-ui/chakra-ui/blob/main/packages/hooks/use-merge-refs/src/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = require("react");
+/**
+ * Assigns a value to a React reference.
+ *
+ * @param ref - The React reference to assign the value to.
+ * @param value - The value to assign to the reference.
+ */
+const assignRef = (ref, value) => {
+    if (ref == null) {
+        return;
+    }
+    if (typeof ref === 'function') {
+        ref(value);
+        return;
+    }
+    try {
+        ref.current = value;
+    }
+    catch (error) {
+        throw new Error(`Cannot assign value '${value}' to ref '${ref}'`);
+    }
+};
+/**
+ * Merges multiple React references into a single callback ref.
+ *
+ * @param refs - The React references to merge.
+ * @returns A callback function to assign the merged references to a node.
+ */
+const mergeRefs = (...refs) => {
+    return (node) => {
+        refs.forEach(ref => {
+            assignRef(ref, node);
+        });
+    };
+};
+/**
+ * Custom hook to merge multiple React references into a single callback ref.
+ *
+ * @param refs - The React references to merge.
+ * @returns A memoized callback function to assign the merged references to a node.
+ */
+const useMergeRefs = (...refs) => {
+    return (0, react_1.useMemo)(() => mergeRefs(...refs), refs);
+};
+exports.default = useMergeRefs;

package/lib/es/src/hooks/useMin.d.ts

@@ -0,0 +1,18 @@
+export type UseMinOptions = {
+    /**
+     * The locale used to parse localized number formats (e.g. "de-DE", "en-GB").
+     * @default "en-GB".
+     */
+    locale?: string;
+};
+/**
+ * Finds the minimum numeric value from a list of objects.
+ * Values are extracted using a dot-separated path and parsed with locale awareness.
+ *
+ * @param items - The list of objects to evaluate.
+ * @param path - Dot-separated path to the value in each object.
+ * @param options - Optional configuration (e.g. locale for number parsing).
+ * @returns The smallest of all valid values, or 0 if none are valid.
+ */
+declare const useMin: (items: unknown[], path: string, options?: UseMinOptions) => number;
+export default useMin;

package/lib/es/src/hooks/useMin.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = require("react");
+const formatUtils_1 = require("../utils/formatUtils");
+/**
+ * Finds the minimum numeric value from a list of objects.
+ * Values are extracted using a dot-separated path and parsed with locale awareness.
+ *
+ * @param items - The list of objects to evaluate.
+ * @param path - Dot-separated path to the value in each object.
+ * @param options - Optional configuration (e.g. locale for number parsing).
+ * @returns The smallest of all valid values, or 0 if none are valid.
+ */
+const useMin = (items, path, options = {}) => {
+    const { locale = 'en-GB' } = options;
+    return (0, react_1.useMemo)(() => {
+        const values = items
+            .map(item => {
+            const valueFromPath = (0, formatUtils_1.getValueByPath)(item, path);
+            return (0, formatUtils_1.parseNumberFromValue)(valueFromPath, locale);
+        })
+            .filter(num => !Number.isNaN(num));
+        return values.length > 0 ? Math.min(...values) : 0;
+    }, [items, path, locale]);
+};
+exports.default = useMin;

package/lib/es/src/hooks/useMutationObserver.d.ts

@@ -0,0 +1,22 @@
+import { type MutableRefObject } from 'react';
+export type Options = {
+    attributes?: boolean;
+    childList?: boolean;
+    subtree?: boolean;
+};
+/**
+ * Custom hook to observe mutations on a target element.
+ *
+ * @param {HTMLElement | MutableRefObject<HTMLElement | null> | null} target - The element or ref to observe.
+ * @param {MutationCallback | undefined} callback - The callback function to execute when mutations occur.
+ * @param {object} options - Options to configure the MutationObserver.
+ * @param {boolean} options.attributes - Set to true if attribute mutations should be observed.
+ * @param {boolean} options.childList - Set to true if mutations to target's children should be observed.
+ * @param {boolean} options.subtree - Set to true if mutations to target's descendants should be observed.
+ */
+declare const useMutationObserver: (target: HTMLElement | MutableRefObject<HTMLElement | null> | null, callback?: MutationCallback | undefined, options?: {
+    attributes?: boolean;
+    childList?: boolean;
+    subtree?: boolean;
+}) => void;
+export default useMutationObserver;

package/lib/es/src/hooks/useMutationObserver.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const react_1 = require("react");
+const noop_1 = tslib_1.__importDefault(require("lodash/fp/noop"));
+// Options for the observer (which mutations to observe)
+const DEFAULT_OPTIONS = {
+    attributes: true,
+    childList: false,
+    subtree: false,
+};
+// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+const isRef = (obj) => obj !== null && typeof obj === 'object' && Object.prototype.hasOwnProperty.call(obj, 'current');
+const unRef = (target) => isRef(target) ? target.current : target;
+/**
+ * Custom hook to observe mutations on a target element.
+ *
+ * @param {HTMLElement | MutableRefObject<HTMLElement | null> | null} target - The element or ref to observe.
+ * @param {MutationCallback | undefined} callback - The callback function to execute when mutations occur.
+ * @param {object} options - Options to configure the MutationObserver.
+ * @param {boolean} options.attributes - Set to true if attribute mutations should be observed.
+ * @param {boolean} options.childList - Set to true if mutations to target's children should be observed.
+ * @param {boolean} options.subtree - Set to true if mutations to target's descendants should be observed.
+ */
+const useMutationObserver = (target, callback = noop_1.default, options = DEFAULT_OPTIONS) => {
+    const observer = (0, react_1.useRef)(null);
+    const disconnect = (0, react_1.useCallback)(() => observer.current?.disconnect(), []);
+    const observe = (0, react_1.useCallback)(() => {
+        const targetElement = unRef(target);
+        if (targetElement) {
+            observer.current = new MutationObserver(callback);
+            observer.current.observe(targetElement, options);
+        }
+    }, [callback, options, target]);
+    (0, react_1.useLayoutEffect)(() => {
+        observe();
+        return () => disconnect();
+    }, [disconnect, observe]);
+};
+exports.default = useMutationObserver;

package/lib/es/src/hooks/useOnMount.d.ts

@@ -0,0 +1,9 @@
+import { type DependencyList } from 'react';
+/**
+ * Custom hook to execute a callback function only on component mount.
+ *
+ * @param callback - The callback function to be executed on mount.
+ * @param deps - The dependencies array for the useEffect hook.
+ */
+declare const useOnMount: (callback: () => void, deps: DependencyList) => void;
+export default useOnMount;

package/lib/es/src/hooks/useOnMount.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = require("react");
+/**
+ * Custom hook to execute a callback function only on component mount.
+ *
+ * @param callback - The callback function to be executed on mount.
+ * @param deps - The dependencies array for the useEffect hook.
+ */
+const useOnMount = (callback, deps) => {
+    const componentJustMountedRef = (0, react_1.useRef)(true);
+    (0, react_1.useEffect)(() => {
+        if (componentJustMountedRef.current) {
+            componentJustMountedRef.current = false;
+            return callback();
+        }
+    }, deps);
+};
+exports.default = useOnMount;

package/lib/es/src/hooks/useOnScreen.d.ts

@@ -0,0 +1,18 @@
+import { type RefObject } from 'react';
+export type UseOnScreen = (ref: RefObject<HTMLElement>, options?: {
+    rootMargin?: string;
+    threshold?: number | number[];
+}) => boolean;
+/**
+ * Custom React hook to detect whether an element is within the viewport.
+ *
+ * @param {RefObject<HTMLElement>} ref - Reference object for the target element to observe.
+ * @param {object} [options] - Options for configuring the IntersectionObserver.
+ * @param {string} [options.rootMargin='0px'] - Margin around the root (viewport) to track intersections.
+ * @param {number | number[]} [options.threshold] - A single threshold value or an array of threshold values
+ *        which indicate the percentage of the target element's visibility needed to trigger the callback.
+ *
+ * @returns {boolean} - Boolean value indicating whether the target element is currently visible in the viewport.
+ */
+declare const useOnScreen: UseOnScreen;
+export default useOnScreen;

package/lib/es/src/hooks/useOnScreen.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Inspired by https://github.com/WebDevSimplified/useful-custom-react-hooks/blob/main/src/14-useOnScreen/useOnScreen.js
+const react_1 = require("react");
+/**
+ * Custom React hook to detect whether an element is within the viewport.
+ *
+ * @param {RefObject<HTMLElement>} ref - Reference object for the target element to observe.
+ * @param {object} [options] - Options for configuring the IntersectionObserver.
+ * @param {string} [options.rootMargin='0px'] - Margin around the root (viewport) to track intersections.
+ * @param {number | number[]} [options.threshold] - A single threshold value or an array of threshold values
+ *        which indicate the percentage of the target element's visibility needed to trigger the callback.
+ *
+ * @returns {boolean} - Boolean value indicating whether the target element is currently visible in the viewport.
+ */
+const useOnScreen = (ref, options = { rootMargin: '0px' }) => {
+    const [isVisible, setIsVisible] = (0, react_1.useState)(false);
+    (0, react_1.useEffect)(() => {
+        if (!ref.current) {
+            return;
+        }
+        /**
+         * Callback function for IntersectionObserver.
+         *
+         * @param {IntersectionObserverEntry[]} entries - An array of IntersectionObserverEntry objects describing
+         * the intersection between the target element and its root container at a specific moment of transition.
+         */
+        const callback = ([entry]) => setIsVisible(entry.isIntersecting);
+        // Create a new IntersectionObserver instance
+        const observer = new IntersectionObserver(callback, options);
+        // Start observing the target element
+        observer.observe(ref.current);
+        // Cleanup function to stop observing the target element when the component unmounts
+        return () => {
+            if (!ref.current) {
+                return;
+            }
+            observer.unobserve(ref.current);
+        };
+    }, [ref, options]);
+    return isVisible;
+};
+exports.default = useOnScreen;