@rio-cloud/rio-uikit 1.10.1 → 1.12.0

package/src/hooks/useEventListenerCount.js

@@ -0,0 +1,42 @@
+import { useState, useEffect } from 'react';
+import throttle from 'lodash/fp/throttle';
+const useEventListenerCount = () => {
+    const [listenerCounts, setListenerCounts] = useState({});
+    const [totalCount, setTotalCount] = useState(0);
+    useEffect(() => {
+        console.log('init useEventListener interceptor');
+        const eventListeners = new Set();
+        const originalAddEventListener = EventTarget.prototype.addEventListener;
+        const originalRemoveEventListener = EventTarget.prototype.removeEventListener;
+        const updateListeners = throttle(1000)(() => {
+            const counts = Array.from(eventListeners).reduce((acc, { type }) => {
+                acc[type] = (acc[type] || 0) + 1;
+                return acc;
+            }, {});
+            setListenerCounts(counts);
+            setTotalCount(eventListeners.size);
+        });
+        EventTarget.prototype.addEventListener = function (type, listener, options) {
+            if (listener) {
+                eventListeners.add({ type, listener });
+                updateListeners();
+            }
+            originalAddEventListener.call(this, type, listener, options);
+        };
+        EventTarget.prototype.removeEventListener = function (type, listener, options) {
+            eventListeners.forEach(item => {
+                if (item.type === type && item.listener === listener) {
+                    eventListeners.delete(item);
+                }
+            });
+            updateListeners();
+            originalRemoveEventListener.call(this, type, listener, options);
+        };
+        return () => {
+            EventTarget.prototype.addEventListener = originalAddEventListener;
+            EventTarget.prototype.removeEventListener = originalRemoveEventListener;
+        };
+    }, []);
+    return { counts: listenerCounts, total: totalCount };
+};
+export default useEventListenerCount;

package/src/hooks/useFocusTrap.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+/**
+ * This custom hook allows to keep the focus inside a defined wrapper element.
+ * This might be a dialog or a custom overlay.
+ *
+ * This hook can be used in two ways:
+ * - When you have a external component that will be re-rendered after the overlay opens, you can use
+ *   the built-in ref. This ref will be returned from this hook and can be set on the respective wrapper element.
+ * - When you have an element that does not re-render, use a state setter function to set as the ref.
+ *   This element can then be passed as a parameter to this hook and it will be used instead of the built-in ref.
+ *
+ * @param element Optional parameter to pass in the existing DOM reference. Use this instead of the built-in ref.
+ * @returns
+ */
+declare const useFocusTrap: <T extends HTMLElement>(element?: HTMLDivElement | null) => React.RefObject<HTMLDivElement>;
+export default useFocusTrap;

package/src/hooks/useFocusTrap.js

@@ -0,0 +1,62 @@
+import { useEffect, useRef } from 'react';
+/**
+ * This custom hook allows to keep the focus inside a defined wrapper element.
+ * This might be a dialog or a custom overlay.
+ *
+ * This hook can be used in two ways:
+ * - When you have a external component that will be re-rendered after the overlay opens, you can use
+ *   the built-in ref. This ref will be returned from this hook and can be set on the respective wrapper element.
+ * - When you have an element that does not re-render, use a state setter function to set as the ref.
+ *   This element can then be passed as a parameter to this hook and it will be used instead of the built-in ref.
+ *
+ * @param element Optional parameter to pass in the existing DOM reference. Use this instead of the built-in ref.
+ * @returns
+ */
+const useFocusTrap = (element) => {
+    const ref = useRef(null);
+    const handleFocus = (event) => {
+        const wrapper = element ?? ref.current;
+        const focusableElements = wrapper?.querySelectorAll([
+            'a[href]',
+            'button',
+            'textarea',
+            'input',
+            'input[type="text"]',
+            'input[type="radio"]',
+            'input[type="checkbox"]',
+            'select',
+        ].join(', '));
+        const firstFocusableEl = focusableElements?.[0];
+        const lastFocusableEl = focusableElements?.[focusableElements.length - 1];
+        const isTabPressed = event.key === 'Tab';
+        if (!isTabPressed) {
+            return;
+        }
+        // Handle: shift + tab
+        if (event.shiftKey) {
+            if (document.activeElement === firstFocusableEl) {
+                lastFocusableEl?.focus();
+                event.preventDefault();
+            }
+            return;
+        }
+        // Handle: tab
+        if (document.activeElement === lastFocusableEl) {
+            firstFocusableEl?.focus();
+            event.preventDefault();
+        }
+    };
+    useEffect(() => {
+        const wrapper = element ?? ref.current;
+        if (wrapper) {
+            wrapper.addEventListener('keydown', handleFocus);
+        }
+        return () => {
+            if (wrapper) {
+                wrapper.removeEventListener('keydown', handleFocus);
+            }
+        };
+    }, [ref.current, element]);
+    return ref;
+};
+export default useFocusTrap;

package/src/hooks/useFullscreen.d.ts

@@ -0,0 +1,31 @@
+type EventCallback = (this: Document, event_: Event) => any;
+type OnChangeEventCallback = (this: Document, event_: Event, isOpen: boolean) => any;
+type RequestFullscreenOptions = {
+    navigationUI?: string | 'auto' | 'hide' | 'show';
+};
+type FullScreenOptions = {
+    element?: HTMLElement;
+    onChange?: OnChangeEventCallback;
+    onError?: EventCallback;
+    requestFullscreenOptions?: RequestFullscreenOptions;
+};
+type FullscreenApi = {
+    requestFullscreen: () => void | ((element?: any) => Promise<unknown>);
+    exitFullscreen: () => void | (() => Promise<unknown>);
+    toggleFullscreen: () => void | ((element?: HTMLElement) => Promise<unknown>);
+    isEnabled: boolean;
+    isFullscreen: boolean;
+};
+/**
+ * Custom hook to manage fullscreen functionality.
+ *
+ * @param options - Options for managing fullscreen behavior.
+ */
+declare const useFullscreen: (options?: FullScreenOptions) => FullscreenApi | {
+    requestFullscreen: (newTargetElement: any) => Promise<any>;
+    exitFullscreen: () => Promise<any>;
+    toggleFullscreen: (newTargetElement: any) => void;
+    isFullscreen: boolean;
+    isEnabled: boolean;
+};
+export default useFullscreen;

package/src/hooks/useFullscreen.js

@@ -0,0 +1,136 @@
+// inspired by https://github.com/imbhargav5/rooks/blob/main/src/hooks/useFullscreen.ts
+import { useState, useCallback } from 'react';
+import noop from 'lodash/fp/noop';
+import useEvent from './useEvent';
+const defaultValue = {
+    requestFullscreen: noop,
+    exitFullscreen: noop,
+    toggleFullscreen: noop,
+    isFullscreen: false,
+    isEnabled: false,
+};
+const requestFunctions = [
+    'requestFullscreen',
+    'webkitRequestFullscreen',
+    'webkitRequestFullScreen',
+    'mozRequestFullScreen',
+];
+const exitFunctions = ['exitFullscreen', 'webkitExitFullscreen', 'webkitCancelFullScreen', 'mozCancelFullScreen'];
+const fullscreenElementFunctions = [
+    'fullscreenElement',
+    'webkitFullscreenElement',
+    'webkitCurrentFullScreenElement',
+    'mozFullScreenElement',
+];
+const isFullscreenEnabledFunctions = [
+    'fullscreenElement',
+    'webkitFullscreenEnabled',
+    'webkitCurrentFullScreenElement',
+    'mozFullScreenEnabled',
+];
+const getFnName = (fnMap, targetElement) => fnMap.find(fnName => {
+    if (fnName in targetElement) {
+        return fnName;
+    }
+});
+// Element centered fullscreen functions
+const getRequestFunctionName = (targetElement = document) => getFnName(requestFunctions, targetElement);
+// Document fullscreen functions
+const getExitFunctionName = () => getFnName(exitFunctions, document);
+const getFullscreenElementFunctionName = () => {
+    const fullscreenFunctionName = getFnName(fullscreenElementFunctions, document);
+    const initialFullscreenElement = fullscreenFunctionName
+        ? document[fullscreenFunctionName]
+        : null;
+    return initialFullscreenElement;
+};
+const getIsFullscreenEnabledFunctionName = () => getFnName(isFullscreenEnabledFunctions, document);
+/**
+ * Custom hook to manage fullscreen functionality.
+ *
+ * @param options - Options for managing fullscreen behavior.
+ */
+const useFullscreen = (options = {}) => {
+    if (typeof window === 'undefined') {
+        console.warn('useFullscreen: window is undefined.');
+        return defaultValue;
+    }
+    const { element, onChange, onError, requestFullscreenOptions = {} } = options;
+    // use either a defined target or when document is set, use the html element as in Chrome the
+    // document does not have a request function. It needs to be an element.
+    const defaultFullscreenElement = !element || !(element instanceof HTMLElement) ? document.querySelector('html') : element;
+    const initialFullscreenElement = getFullscreenElementFunctionName();
+    const [isFullscreen, setIsFullscreen] = useState(Boolean(initialFullscreenElement));
+    const [fullscreenElement, setFullscreenElement] = useState(initialFullscreenElement);
+    // Request
+    const requestFullscreen = useCallback(async (newTargetElement) => {
+        // check whether the new target element is a real DOM node or just a function
+        const isHtmlElement = newTargetElement instanceof HTMLElement;
+        try {
+            const target = newTargetElement && isHtmlElement ? newTargetElement : defaultFullscreenElement;
+            const requestFunctionName = getRequestFunctionName(target);
+            if (requestFunctionName) {
+                return await target[requestFunctionName](requestFullscreenOptions);
+            }
+            else {
+                throw new Error('Request function not found');
+            }
+        }
+        catch (error) {
+            console.log(error);
+        }
+    }, []);
+    // Exit
+    const exitFullscreen = useCallback(async () => {
+        try {
+            const exitFunctionName = getExitFunctionName();
+            if (fullscreenElement && exitFunctionName) {
+                return await document[exitFunctionName]();
+            }
+        }
+        catch (error) {
+            console.warn(error);
+        }
+    }, [fullscreenElement]);
+    // Toggle
+    const toggleFullscreen = useCallback((newTargetElement) => {
+        if (fullscreenElement) {
+            exitFullscreen();
+        }
+        else {
+            requestFullscreen(newTargetElement);
+        }
+    }, [fullscreenElement]);
+    const handleChangeEvent = () => {
+        const currentFullscreenElement = getFullscreenElementFunctionName();
+        const isOpen = Boolean(currentFullscreenElement);
+        if (isOpen) {
+            // fullscreen was enabled
+            setIsFullscreen(true);
+            setFullscreenElement(currentFullscreenElement);
+        }
+        else {
+            // fullscreen was disabled
+            setIsFullscreen(false);
+            setFullscreenElement(null);
+        }
+        onChange?.call(document, event || new Event('default'), isOpen);
+    };
+    const handleErrorEvent = () => (event) => onError?.call(document, event);
+    useEvent('fullscreenchange', handleChangeEvent);
+    useEvent('webkitfullscreenchange', handleChangeEvent);
+    useEvent('mozfullscreenchange', handleChangeEvent);
+    useEvent('fullscreenerror', handleErrorEvent);
+    useEvent('webkitfullscreenerror', handleErrorEvent);
+    useEvent('mozfullscreenerror', handleErrorEvent);
+    const enabledFunctionName = getIsFullscreenEnabledFunctionName();
+    const isEnabled = enabledFunctionName ? Boolean(document[enabledFunctionName]) : false;
+    return {
+        requestFullscreen,
+        exitFullscreen,
+        toggleFullscreen,
+        isFullscreen,
+        isEnabled,
+    };
+};
+export default useFullscreen;

package/src/hooks/useHover.d.ts

@@ -0,0 +1,9 @@
+import { type RefObject } from 'react';
+/**
+ * Custom hook to detect hover state for a given HTML element.
+ *
+ * @param elementRef - The reference to the HTML element.
+ * @returns A boolean value representing whether the element is being hovered over or not.
+ */
+declare const useHover: <T extends HTMLElement = HTMLElement>(elementRef: RefObject<T>) => boolean;
+export default useHover;

package/src/hooks/useHover.js

@@ -0,0 +1,34 @@
+import { useEffect, useState } from 'react';
+/**
+ * Custom hook to detect hover state for a given HTML element.
+ *
+ * @param elementRef - The reference to the HTML element.
+ * @returns A boolean value representing whether the element is being hovered over or not.
+ */
+const useHover = (elementRef) => {
+    const [value, setValue] = useState(false);
+    const handleMouseEnter = () => setValue(true);
+    const handleMouseLeave = () => setValue(false);
+    useEffect(() => {
+        if (elementRef.current) {
+            elementRef.current.addEventListener('mouseenter', handleMouseEnter);
+        }
+        return () => {
+            if (elementRef.current) {
+                elementRef.current.removeEventListener('mouseenter', handleMouseEnter);
+            }
+        };
+    }, [elementRef.current]);
+    useEffect(() => {
+        if (elementRef.current) {
+            elementRef.current.addEventListener('mouseleave', handleMouseLeave);
+        }
+        return () => {
+            if (elementRef.current) {
+                elementRef.current.removeEventListener('mouseleave', handleMouseLeave);
+            }
+        };
+    }, [elementRef.current]);
+    return value;
+};
+export default useHover;

package/src/hooks/useInterval.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Custom hook to execute a callback function at specified intervals.
+ *
+ * @param callback - The callback function to be executed.
+ * @param delay - The interval duration in milliseconds. Set to null to stop the interval.
+ *
+ * @returns A mutable ref object that holds the interval ID.
+ */
+declare const useInterval: (callback: () => void, delay: number | null) => React.MutableRefObject<number | null>;
+export default useInterval;

package/src/hooks/useInterval.js

@@ -0,0 +1,26 @@
+import { useEffect, useRef } from 'react';
+// See https://overreacted.io/making-setinterval-declarative-with-react-hooks/
+/**
+ * Custom hook to execute a callback function at specified intervals.
+ *
+ * @param callback - The callback function to be executed.
+ * @param delay - The interval duration in milliseconds. Set to null to stop the interval.
+ *
+ * @returns A mutable ref object that holds the interval ID.
+ */
+const useInterval = (callback, delay) => {
+    const intervalRef = useRef(null);
+    const savedCallback = useRef(callback);
+    useEffect(() => {
+        savedCallback.current = callback;
+    }, [callback]);
+    useEffect(() => {
+        const tick = () => savedCallback.current();
+        if (typeof delay === 'number') {
+            intervalRef.current = window.setInterval(tick, delay);
+            return () => window.clearInterval(intervalRef.current ?? undefined);
+        }
+    }, [delay]);
+    return intervalRef;
+};
+export default useInterval;

package/src/hooks/useIsFirstRender.d.ts

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

package/src/hooks/useIsFirstRender.js

@@ -0,0 +1,10 @@
+import { useRef } from 'react';
+const useIsFirstRender = () => {
+    const renderRef = useRef(true);
+    if (renderRef.current === true) {
+        renderRef.current = false;
+        return true;
+    }
+    return renderRef.current;
+};
+export default useIsFirstRender;

package/src/hooks/useIsFocusWithin.d.ts

@@ -0,0 +1,33 @@
+type UseIsFocusWithinOptions<T extends HTMLElement> = {
+    /**
+     * Optional external ref to the DOM element to track.
+     * If not provided, the hook will return its own internal ref.
+     */
+    ref?: React.RefObject<T>;
+    /**
+     * Optional callback triggered when focus enters the element or its children.
+     */
+    onFocusWithin?: () => void;
+    /**
+     * Optional callback triggered when focus leaves the element and all its children.
+     */
+    onBlurWithin?: () => void;
+    /**
+     * Optional delay (in ms) before calling onBlurWithin.
+     * Useful when focus might quickly shift between internal elements.
+     * @default 0
+     */
+    delay?: number;
+};
+/**
+ * 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.
+ */
+declare const useIsFocusWithin: <T extends HTMLElement>({ ref: externalRef, onFocusWithin, onBlurWithin, delay, }?: UseIsFocusWithinOptions<T>) => {
+    ref: import("react").RefObject<T>;
+    isFocusedWithin: boolean;
+};
+export default useIsFocusWithin;

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

@@ -0,0 +1,13 @@
+type KeyboardEventType = 'keyup' | 'keydown' | 'keypress';
+/**
+ * Custom hook to handle keyboard events.
+ *
+ * @param keyOrCallback - Either a key string (e.g., 'Enter') or a callback function.
+ * @param callbackOrEventTypes - If the first argument is a key, this should be the callback function.
+ *                               If the first argument is a callback, this is an optional array of event types.
+ * @param [eventTypesOrNode=['keydown']] - If the first argument is a key, this should be an array of event types.
+ *                                         If the first argument is a callback, this is the node (defaults to document).
+ * @param [node=document] - Optional DOM node to attach the event listener to (defaults to document).
+ */
+declare const useKey: (keyOrCallback: string | ((event: KeyboardEvent) => void), callbackOrEventTypes?: (event: KeyboardEvent) => void | KeyboardEventType[], eventTypesOrNode?: KeyboardEventType[] | Document, node?: Document | HTMLElement) => void;
+export default useKey;

package/src/hooks/useKey.js

@@ -0,0 +1,49 @@
+import { useEffect, useRef } from 'react';
+/**
+ * Custom hook to handle keyboard events.
+ *
+ * @param keyOrCallback - Either a key string (e.g., 'Enter') or a callback function.
+ * @param callbackOrEventTypes - If the first argument is a key, this should be the callback function.
+ *                               If the first argument is a callback, this is an optional array of event types.
+ * @param [eventTypesOrNode=['keydown']] - If the first argument is a key, this should be an array of event types.
+ *                                         If the first argument is a callback, this is the node (defaults to document).
+ * @param [node=document] - Optional DOM node to attach the event listener to (defaults to document).
+ */
+const useKey = (keyOrCallback, callbackOrEventTypes, eventTypesOrNode = ['keydown'], node = document) => {
+    const callbacksRef = useRef([]);
+    useEffect(() => {
+        const isKeyMode = typeof keyOrCallback === 'string';
+        const callback = isKeyMode
+            ? callbackOrEventTypes
+            : keyOrCallback;
+        const keyHandler = (event) => {
+            if (isKeyMode) {
+                if (event.key === keyOrCallback) {
+                    callback(event);
+                }
+            }
+            else {
+                callback(event);
+            }
+        };
+        // Register the keyHandler
+        callbacksRef.current.push(keyHandler);
+        const genericHandler = (event) => {
+            for (const callBecky of callbacksRef.current) {
+                callBecky(event);
+            }
+        };
+        const eventTypes = Array.isArray(eventTypesOrNode) ? eventTypesOrNode : ['keydown'];
+        for (const eventType of eventTypes) {
+            node.addEventListener(eventType, genericHandler);
+        }
+        return () => {
+            for (const eventType of eventTypes) {
+                node.removeEventListener(eventType, genericHandler);
+            }
+            // Clean up callback reference
+            callbacksRef.current = callbacksRef.current.filter(singleCallback => singleCallback !== keyHandler);
+        };
+    }, [keyOrCallback, callbackOrEventTypes, eventTypesOrNode, node]);
+};
+export default useKey;

package/src/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/src/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;