@rio-cloud/rio-uikit 1.7.1 → 1.9.0

package/hooks/useIsFocusWithin.js

@@ -0,0 +1,55 @@
+import { useEffect, useRef, useState } from 'react';
+/**
+ * React hook that tracks whether focus is currently within a given element or its children.
+ * Provides a boolean state and a ref to attach to the tracked element.
+ *
+ * @param options Hook configuration including external ref, callbacks, and optional delay.
+ * @returns An object containing the ref and whether focus is currently within the element.
+ */
+const useIsFocusWithin = ({ ref: externalRef, onFocusWithin = () => { }, onBlurWithin = () => { }, delay = 0, } = {}) => {
+    const internalRef = useRef(null);
+    const targetRef = externalRef ?? internalRef;
+    const [isFocusedWithin, setIsFocusedWithin] = useState(false);
+    const timeoutId = useRef(null);
+    const clearTimeoutIfAny = () => {
+        if (timeoutId.current !== null) {
+            window.clearTimeout(timeoutId.current);
+            timeoutId.current = null;
+        }
+    };
+    useEffect(() => {
+        const node = targetRef.current;
+        if (!node) {
+            return;
+        }
+        const handleFocusIn = () => {
+            clearTimeoutIfAny();
+            if (!isFocusedWithin) {
+                setIsFocusedWithin(true);
+                onFocusWithin();
+            }
+        };
+        const handleFocusOut = (e) => {
+            clearTimeoutIfAny();
+            timeoutId.current = window.setTimeout(() => {
+                if (!node.contains(e.relatedTarget)) {
+                    setIsFocusedWithin(false);
+                    onBlurWithin();
+                }
+                timeoutId.current = null;
+            }, delay);
+        };
+        node.addEventListener('focusin', handleFocusIn);
+        node.addEventListener('focusout', handleFocusOut);
+        return () => {
+            node.removeEventListener('focusin', handleFocusIn);
+            node.removeEventListener('focusout', handleFocusOut);
+            clearTimeoutIfAny();
+        };
+    }, [targetRef, delay, onFocusWithin, onBlurWithin, isFocusedWithin]);
+    return {
+        ref: targetRef,
+        isFocusedWithin,
+    };
+};
+export default useIsFocusWithin;

package/hooks/useLocationSuggestions.d.ts

@@ -0,0 +1,27 @@
+export type LocationSuggestion = {
+    id: string;
+    label: string;
+};
+export type LocationFetchOptions = Record<string, unknown> & {
+    apiKey?: string;
+    fetchUrl?: string;
+    limit?: number;
+};
+/**
+ * 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.
+ */
+declare const useLocationSuggestions: (query: string, options?: LocationFetchOptions) => {
+    suggestions: LocationSuggestion[];
+    loading: boolean;
+    error: Error | null;
+};
+export default useLocationSuggestions;

package/hooks/useLocationSuggestions.js

@@ -0,0 +1,94 @@
+import { useEffect, useRef, useState } from 'react';
+import debounce from '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] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const abortRef = 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 = useRef(debounce(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>
+    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
+    useEffect(() => {
+        return () => {
+            abortRef.current?.abort();
+        };
+    }, []);
+    return { suggestions, loading, error };
+};
+export default useLocationSuggestions;

package/hooks/useOnboarding.d.ts

@@ -1,8 +1,8 @@
-import { type PopoverDOM as DriverPopoverDOM, type State as DriverState, type AllowedButtons } from 'driver.js';
+import { type PopoverDOM as DriverPopoverDOM, type State as DriverState, type AllowedButtons, type DriveStep } from 'driver.js';
 import 'driver.js/dist/driver.css';
 export type PopoverDOM = DriverPopoverDOM;
 export type OnboardingState = DriverState;
-export type OnboardingStep = {
+export type OnboardingStep = DriveStep & {
     element?: string | Element;
     onHighlightStarted?: (element: Element | undefined, step: OnboardingStep, opts: any) => void;
     onHighlighted?: (element: Element | undefined, step: OnboardingStep, opts: any) => void;
@@ -14,6 +14,7 @@ export type OnboardingStep = {
         align?: 'start' | 'center' | 'end';
         showButtons?: ('next' | 'previous' | 'close')[];
         disableButtons?: ('next' | 'previous' | 'close')[];
+        disableActiveInteraction?: boolean;
         popoverClass?: string;
         doneBtnText?: string;
         nextBtnText?: string;
@@ -78,6 +79,13 @@ type OnboardingOptions = {
      * Array of buttons to disable. This is useful when you want to show some of the buttons, but disable some of them.
      */
     disableButtons?: AllowedButtons[];
+    /**
+     * Whether to disable interaction with the highlighted element.
+     * Can be configured at the step level as well.
+     *
+     * @default false
+     */
+    disableActiveInteraction?: boolean;
     /**
      * Option to disable the backdrop. Note, the backdrop element is still there but with 100% opacity
      * and the close on the backdrop is disabled.
@@ -97,18 +105,22 @@ type OnboardingOptions = {
      * @returns
      */
     onPopoverRender?: (popover: PopoverDOM, state: OnboardingState) => void;
+    /**
+     * Callback triggered when the onboarding tour is destroyed
+     */
+    onDestroyed?: () => void;
 };
 export declare const useOnboardingTour: (params: OnboardingOptions) => {
     run: () => void;
     destroy: () => void;
-    onboardingState: () => DriverState;
+    onboardingState: () => any;
     refresh: () => void;
     isActive: () => boolean;
     moveNext: () => void;
     movePrevious: () => void;
     moveTo: (stepNumber: number) => void;
-    hasNextStep: () => false | import("driver.js").DriveStep;
-    hasPreviousStep: () => false | import("driver.js").DriveStep;
+    hasNextStep: () => boolean;
+    hasPreviousStep: () => boolean;
     isFirstStep: () => boolean;
     isLastStep: () => boolean;
     getActiveIndex: () => number | undefined;

package/hooks/useOnboarding.js

@@ -1,10 +1,14 @@
 import { driver, } from 'driver.js';
 import 'driver.js/dist/driver.css';
 export const useOnboardingTour = (params) => {
-    const { steps, prevBtnText = 'Previous', nextBtnText = 'Next', doneBtnText = 'Done', showProgress = true, allowClose = false, stagePadding = 10, stageRadius = 5, allowKeyboardControl = true, showButtons, disableButtons, popoverClass, noBackdrop = false, onPopoverRender = () => { }, } = params;
+    console.log({ params });
+    const { steps, prevBtnText = 'Previous', nextBtnText = 'Next', doneBtnText = 'Done', showProgress = true, allowClose = false, stagePadding = 10, stageRadius = 5, allowKeyboardControl = true, showButtons, disableButtons, popoverClass, noBackdrop = false, onPopoverRender = () => { }, onDestroyed = () => { }, ...driverProps } = params;
     const handlePopoverRender = (popover, options) => {
         onPopoverRender(popover, options.state);
     };
+    const handleDestroyed = () => {
+        onDestroyed();
+    };
     const isSingleStep = !steps || steps.length === 1;
     // This configuration is applied to all steps.
     // Driver.js allows also for individual customization for single steps too.
@@ -25,6 +29,8 @@ export const useOnboardingTour = (params) => {
         allowKeyboardControl,
         popoverClass,
         onPopoverRender: handlePopoverRender,
+        onDestroyed: handleDestroyed,
+        ...driverProps,
     });
     return {
         // Use for onboarding tours. Pass in all steps as "steps" parameter for initial configuration.

package/hooks/usePostMessage.js

@@ -33,7 +33,6 @@ const usePostMessage = (messagePrefix, onReceiveMessage) => {
         if (!actionType) {
             return;
         }
-        console.log(event);
         if (actionType.startsWith(messagePrefix)) {
             callback(event.data);
         }

package/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/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/hooks/useSorting.d.ts

@@ -19,6 +19,12 @@ type UseSortingResult<T> = {
      * @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

package/hooks/useSorting.js

@@ -10,10 +10,12 @@ const useSorting = (items, initialKey, initialDirection = SortDirection.ASCENDIN
                 : arr.sort((a, b) => {
                     const aVal = a[key];
                     const bVal = b[key];
-                    if (aVal < bVal)
+                    if (aVal < bVal) {
                         return sortDirection === SortDirection.ASCENDING ? -1 : 1;
-                    if (aVal > bVal)
+                    }
+                    if (aVal > bVal) {
                         return sortDirection === SortDirection.ASCENDING ? 1 : -1;
+                    }
                     return 0;
                 });
         };
@@ -23,8 +25,9 @@ const useSorting = (items, initialKey, initialDirection = SortDirection.ASCENDIN
             // Group items with the same primary key value
             const groups = primarySorted.reduce((acc, item) => {
                 const key = String(item[primaryKey]);
-                if (!acc[key])
+                if (!acc[key]) {
                     acc[key] = [];
+                }
                 acc[key].push(item);
                 return acc;
             }, {});
@@ -36,6 +39,6 @@ const useSorting = (items, initialKey, initialDirection = SortDirection.ASCENDIN
     const toggleDirection = () => {
         setSortDirection(prev => prev === SortDirection.ASCENDING ? SortDirection.DESCENDING : SortDirection.ASCENDING);
     };
-    return { sortedItems, sortKey, sortDirection, setSortKey, toggleDirection };
+    return { sortedItems, sortKey, sortDirection, setSortKey, setSortDirection, toggleDirection };
 };
 export default useSorting;

package/hooks/useTableExport.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Options for exporting tabular data to CSV.
+ */
+export type ExportOptions<T extends object> = {
+    /**
+     * Array of data objects to export. Each object represents one row in the table.
+     */
+    data: T[];
+    /**
+     * Optional name for the exported file.
+     * @default "export.csv"
+     */
+    fileName?: string;
+    /**
+     * Optional list of object keys to export as columns.
+     * If omitted, all keys from the first row will be used.
+     */
+    columns?: (keyof T)[];
+    /**
+     * Optional map of column keys to custom header labels.
+     * @example { firstName: 'First Name' }
+     */
+    headers?: Partial<Record<keyof T, string>>;
+    /**
+     * Optional delimiter to use between values in the CSV.
+     * You can use `";"` or `"\t"` for other formats.
+     * @default ","
+     */
+    delimiter?: string;
+    /**
+     * Whether to include UTF-8 BOM (useful for Excel).
+     * @default true
+     */
+    withBom?: boolean;
+};
+/**
+ * React hook for exporting tabular data to a downloadable CSV file.
+ *
+ * @template T Type of each data row object.
+ * @returns An object with a `exportToCSV` function to trigger the export.
+ *
+ * @example
+ * const { exportToCSV } = useTableExport<User>();
+ * exportToCSV({ data: users, fileName: 'users.csv', delimiter: ';' });
+ */
+declare const useTableExport: <T extends object>() => {
+    exportToCSV: ({ data, fileName, columns, headers, delimiter, withBom }: ExportOptions<T>) => void;
+};
+export default useTableExport;

package/hooks/useTableExport.js

@@ -0,0 +1,57 @@
+import { useCallback } from 'react';
+/**
+ * Converts a dataset into CSV format as a string.
+ *
+ * @template T Type of each row object.
+ * @param data The data array to convert.
+ * @param columns Optional keys to include as columns.
+ * @param headers Optional key-to-label mapping for header row.
+ * @param delimiter Delimiter to separate columns. Defaults to `","`.
+ * @returns A string representing the CSV data.
+ */
+const convertToCSV = (data, columns, headers, delimiter = ',') => {
+    if (!data.length) {
+        return '';
+    }
+    const escapeFn = (val) => {
+        if (val === null || val === undefined) {
+            return '';
+        }
+        const str = String(val);
+        const needsQuotes = str.includes(delimiter) || str.includes('"') || str.includes('\n');
+        const escaped = str.replace(/"/g, '""');
+        return needsQuotes ? `"${escaped}"` : escaped;
+    };
+    const headerRow = columns.map(key => escapeFn(headers?.[key] ?? String(key))).join(delimiter);
+    const dataRows = data.map(row => columns.map(key => escapeFn(row[key])).join(delimiter));
+    return [headerRow, ...dataRows].join('\n');
+};
+/**
+ * React hook for exporting tabular data to a downloadable CSV file.
+ *
+ * @template T Type of each data row object.
+ * @returns An object with a `exportToCSV` function to trigger the export.
+ *
+ * @example
+ * const { exportToCSV } = useTableExport<User>();
+ * exportToCSV({ data: users, fileName: 'users.csv', delimiter: ';' });
+ */
+const useTableExport = () => {
+    const exportToCSV = useCallback(({ data, fileName = 'export.csv', columns, headers, delimiter = ',', withBom = true }) => {
+        if (!data.length) {
+            return;
+        }
+        const cols = columns ?? Object.keys(data[0]);
+        const csv = convertToCSV(data, cols, headers, delimiter);
+        const bom = withBom ? '\uFEFF' : '';
+        const blob = new Blob([bom + csv], { type: 'text/csv;charset=utf-8;' });
+        const link = document.createElement('a');
+        link.href = URL.createObjectURL(blob);
+        link.setAttribute('download', fileName);
+        document.body.appendChild(link);
+        link.click();
+        document.body.removeChild(link);
+    }, []);
+    return { exportToCSV };
+};
+export default useTableExport;