@bspk/ui 1.1.31 → 1.1.33

package/src/hooks/useCombobox.ts

@@ -1,15 +1,95 @@
 import { AriaAttributes, useId, useState } from 'react';
 
+import { EVENT_KEY } from '-/utils/keyboard';
+import { scrollElementIntoView } from '-/utils/scrollElementIntoView';
+
 import { CommonProps, InvalidPropsLibrary } from '..';
-import { EVENT_KEY } from '../utils/keyboard';
 
-import { useFloating, UseFloatingProps } from './useFloating';
-import { useKeyboardNavigation } from './useKeyboardNavigation';
-import { useOutsideClick } from './useOutsideClick';
+import { useFloating, UseFloatingElements, UseFloatingProps } from './useFloating';
 
 export type UseComboboxProps = CommonProps<'disabled' | 'readOnly'> &
     InvalidPropsLibrary &
-    Pick<UseFloatingProps, 'offsetOptions' | 'placement' | 'refWidth'>;
+    Pick<UseFloatingProps, 'offsetOptions' | 'placement' | 'refWidth'> & {
+        /**
+         * The element to use for outside click detection.
+         *
+         * If set to true, it will use the floating, and reference elements.
+         *
+         * If set to HTMLElements, it will use those element for outside click detection.
+         *
+         * If set to false, it will not use outside click detection.
+         */
+        refOutsideClick?: HTMLElement[] | boolean;
+    };
+
+export type ComboboxContext = ReturnType<typeof useCombobox>;
+export type ToggleProps = {
+    'aria-errormessage'?: string | undefined;
+    'aria-activedescendant'?: string | undefined;
+    'aria-controls': string;
+    'aria-disabled'?: boolean | undefined;
+    'aria-expanded': boolean;
+    'aria-haspopup': AriaAttributes['aria-haspopup'];
+    'aria-invalid'?: boolean | undefined;
+    'aria-owns': string;
+    'aria-readonly'?: boolean | undefined;
+    role: 'combobox';
+    tabIndex: number;
+    onClick: () => void;
+    onKeyDownCapture: (event: React.KeyboardEvent) => boolean;
+};
+
+function useKeyDownNavigation(containerElement: HTMLElement, setShow: (show: boolean) => void, disabled?: boolean) {
+    const [activeIndex, setActiveIndex] = useState(-1);
+
+    const itemElements = Array.from(containerElement?.children || []) as HTMLElement[];
+    const selectedId = itemElements[activeIndex]?.id;
+
+    const onKeyDownCapture = (event: React.KeyboardEvent): boolean => {
+        if (disabled) return false;
+
+        if (event.key === EVENT_KEY.Tab || event.key === EVENT_KEY.Escape) {
+            setShow(false);
+            return true;
+        }
+
+        if (event.key !== EVENT_KEY.Enter && !event.key.startsWith('Arrow')) return false;
+
+        if (event.key.startsWith('Arrow') && !containerElement) {
+            event.preventDefault();
+            setShow(true);
+            setActiveIndex(0);
+            return true;
+        }
+
+        if (!containerElement?.children.length) return false;
+
+        event.preventDefault();
+
+        if (event.key === EVENT_KEY.Enter && activeIndex !== -1) {
+            itemElements[activeIndex].click();
+            return true;
+        }
+
+        let next = 0;
+        if (event.key === EVENT_KEY.ArrowUp || event.key === EVENT_KEY.ArrowLeft) next = activeIndex - 1;
+        if (event.key === EVENT_KEY.ArrowDown || event.key === EVENT_KEY.ArrowRight) next = activeIndex + 1;
+        if (next < 0) next = itemElements.length - 1;
+        if (next >= itemElements.length) next = 0;
+
+        itemElements.forEach((el, index) => {
+            if (index === next) el.setAttribute('data-selected', 'true');
+            else el.removeAttribute('data-selected');
+        });
+
+        scrollElementIntoView(itemElements[next], containerElement);
+        setActiveIndex(next);
+
+        return true;
+    };
+
+    return { onKeyDownCapture, selectedId, activeIndex };
+}
 
 /**
  * Utility hook to manage a combobox component.
@@ -17,7 +97,7 @@ export type UseComboboxProps = CommonProps<'disabled' | 'readOnly'> &
  * It provides functionality for showing/hiding the menu, handling keyboard navigation, and managing ARIA attributes.
  *
  * @param {UseComboboxProps} props - The properties to configure the combobox.
- * @returns {object} An object containing props for the menu and toggle elements, and a function to close the menu.
+ * @returns An object containing props for the menu and toggle elements, and a function to close the menu.
  */
 export function useCombobox({
     placement = 'bottom',
@@ -27,12 +107,24 @@ export function useCombobox({
     invalid,
     readOnly,
     offsetOptions,
-}: UseComboboxProps) {
+}: UseComboboxProps): {
+    activeIndex: number;
+    menuProps: {
+        'data-placement': string | undefined;
+        id: string;
+        role: 'listbox';
+        style: React.CSSProperties;
+        tabIndex: -1;
+        onOutsideClick: () => void;
+    };
+    toggleProps: ToggleProps;
+    closeMenu: () => void;
+    isOpen: boolean;
+    elements: UseFloatingElements;
+} {
     const menuId = useId();
 
     const [show, setShow] = useState(false);
-    const closeMenu = () => setShow(false);
-    const openMenu = () => setShow(true);
 
     const { floatingStyles, middlewareData, elements } = useFloating({
         placement,
@@ -42,25 +134,21 @@ export function useCombobox({
         hide: !show,
     });
 
-    const { handleKeyNavigation, selectedIndex: activeIndex, selectedId } = useKeyboardNavigation(elements.floating);
-
-    useOutsideClick([elements.floating, elements.trigger], (event) => {
-        event?.stopPropagation();
-        if (!show) return;
-        closeMenu();
-    });
+    const { onKeyDownCapture, activeIndex, selectedId } = useKeyDownNavigation(
+        elements.floating as HTMLElement,
+        setShow,
+        disabled || readOnly,
+    );
 
     return {
+        activeIndex,
         menuProps: {
-            activeIndex,
             'data-placement': middlewareData?.offset?.placement,
             id: menuId,
-            innerRef: (node: HTMLElement | null) => {
-                elements.setFloating(node);
-            },
             role: 'listbox',
             style: floatingStyles,
             tabIndex: -1,
+            onOutsideClick: () => setShow(false),
         },
         toggleProps: {
             'aria-errormessage': errorMessage || undefined,
@@ -74,26 +162,14 @@ export function useCombobox({
             'aria-readonly': readOnly || undefined,
             role: 'combobox',
             tabIndex: 0,
-            ref: (node: HTMLElement | null) => elements.setTrigger(node),
             onClick: () => {
                 setShow((prev) => !prev);
             },
-            /**
-             * @param {React.KeyboardEvent} event
-             * @returns {boolean} True if event was handled internally
-             */
-            onKeyDownCapture: (event: React.KeyboardEvent): boolean => {
-                if (event.key === EVENT_KEY.Tab || event.key === EVENT_KEY.Escape) {
-                    closeMenu();
-                    return true;
-                }
-
-                openMenu();
-
-                return handleKeyNavigation?.(event.nativeEvent);
-            },
+            onKeyDownCapture,
         },
-        closeMenu,
+        closeMenu: () => setShow(false),
+        isOpen: show,
+        elements,
     };
 }
 

package/src/hooks/useDebounceCallback.ts

@@ -0,0 +1,16 @@
+import { useTimeout } from './useTimeout';
+
+type Fn = (...args: unknown[]) => void;
+
+/**
+ * A hook that debounces a function call, ensuring that the function is not called again until a specified delay
+ *
+ * @param fn The original, non debounced function (You can pass any number of args to it)
+ * @param delay [1000] The delay (in ms) for the function to return
+ * @returns The debounced function, which will run only if the debounced function has not been called in the last
+ *   (delay) ms
+ */
+export function useDebounceCallback(fn: Fn, delay = 1000): Fn {
+    const timer = useTimeout();
+    return (...args: unknown[]) => timer.set(() => fn(...args), delay);
+}

package/src/hooks/useDebounceState.ts

@@ -0,0 +1,18 @@
+import { SetStateAction, useState } from 'react';
+
+import { useTimeout } from './useTimeout';
+
+/**
+ * A hook that debounces a state update, ensuring that the function is not called again until a specified delay
+ *
+ * @param defaultValue The initial value of the state
+ * @param delay [1000] The delay (in ms) for the state to update
+ * @returns A tuple containing the current state and a debounced setter function that updates the state after the
+ *   specified delay
+ */
+export function useDebounceState<T>(initialState: T | (() => T), delay = 1000) {
+    const [state, setState] = useState<T>(initialState);
+    const timeout = useTimeout();
+
+    return [state, (nextState: SetStateAction<T>) => timeout.set(() => setState(nextState), delay)] as const;
+}

package/src/hooks/useFloating.ts

@@ -1,6 +1,9 @@
 /**
  * Custom hook to manage the positioning of a floating element relative to a reference element.
  *
+ * This hook uses the Floating UI library to compute the position of the floating element based on the reference
+ * element's position and the specified placement, strategy, and offset options.
+ *
  * @template ReferenceType - The type of the reference element, extending HTMLElement.
  * @param {Object} params - The parameters for the hook.
  * @param {Placement} params.placement - The preferred placement of the floating element.
@@ -38,9 +41,9 @@ export type UseFloatingProps = {
      *
      * This determines where the floating element will be positioned relative to the reference element.
      *
-     * @default bottom
+     * @default bottom-start
      */
-    placement: Placement;
+    placement?: Placement;
     /** A ref object for the arrow element. */
     arrowRef?: React.MutableRefObject<HTMLElement | null>;
     /**
@@ -71,20 +74,31 @@ export type UseFloatingProps = {
     hide?: boolean;
 };
 
+export type UseFloatingElements<ReferenceElementType extends HTMLElement = HTMLElement> = {
+    reference: ReferenceElementType | null;
+    floating: HTMLElement | null;
+    setReference: (element: ReferenceElementType | null) => void;
+    setFloating: (element: HTMLElement | null) => void;
+};
+
 /**
  *
  *
  * @param param0
  * @returns
  */
-export function useFloating<TriggerElementType extends HTMLElement>({
-    placement = 'bottom',
+export function useFloating<ReferenceElementType extends HTMLElement = HTMLElement>({
+    placement = 'bottom-start',
     arrowRef,
     strategy = 'fixed',
     offsetOptions = 0,
     refWidth = true,
     hide = false,
-}: UseFloatingProps) {
+}: UseFloatingProps): {
+    elements: UseFloatingElements<ReferenceElementType>;
+    floatingStyles: React.CSSProperties;
+    middlewareData: MiddlewareData;
+} {
     const [floatingStyles, setFloatingStylesState] = useState<React.CSSProperties>({
         opacity: 0,
         pointerEvents: 'none',
@@ -100,7 +114,7 @@ export function useFloating<TriggerElementType extends HTMLElement>({
 
     const [middlewareData, setMiddlewareData] = useState<MiddlewareData>({});
 
-    const [triggerElement, setTriggerElement] = useState<TriggerElementType | null>(null);
+    const [referenceElement, setReferenceElement] = useState<ReferenceElementType | null>(null);
 
     const [floatingElement, setFloatingElement] = useState<HTMLElement | null>(null);
 
@@ -112,7 +126,7 @@ export function useFloating<TriggerElementType extends HTMLElement>({
         transitionDelay.clear();
 
         // check if the reference or floating element is null
-        if (triggerElement === null || floatingElement === null) return;
+        if (referenceElement === null || floatingElement === null) return;
 
         if (hide) {
             if (floatingElement?.style.top)
@@ -136,9 +150,9 @@ export function useFloating<TriggerElementType extends HTMLElement>({
 
         computeDebounce.set(() => {
             // check again if the reference or floating element is null
-            if (hide || triggerElement === null || floatingElement === null) return;
+            if (hide || referenceElement === null || floatingElement === null) return;
 
-            computePosition(triggerElement, floatingElement, {
+            computePosition(referenceElement, floatingElement, {
                 placement: placement,
                 strategy,
                 middleware: [
@@ -180,7 +194,7 @@ export function useFloating<TriggerElementType extends HTMLElement>({
     }, [
         computeDebounce,
         transitionDelay,
-        triggerElement,
+        referenceElement,
         floatingElement,
         hide,
         placement,
@@ -199,20 +213,20 @@ export function useFloating<TriggerElementType extends HTMLElement>({
     }, [compute, computeDebounce, hide, transitionDelay]);
 
     useEffect(() => {
-        if (hide || triggerElement === null || floatingElement === null) return;
+        if (hide || referenceElement === null || floatingElement === null) return;
 
-        const cleanup = autoUpdate(triggerElement, floatingElement, compute);
+        const cleanup = autoUpdate(referenceElement, floatingElement, compute);
 
         return () => {
             cleanup();
         };
-    }, [compute, hide, floatingElement, triggerElement]);
+    }, [compute, hide, floatingElement, referenceElement]);
 
     return {
         elements: {
-            trigger: triggerElement,
+            reference: referenceElement,
             floating: floatingElement,
-            setTrigger: setTriggerElement,
+            setReference: setReferenceElement,
             setFloating: setFloatingElement,
         },
         floatingStyles,

package/src/hooks/useIsomorphicEffect.ts

@@ -0,0 +1,3 @@
+import { useEffect, useLayoutEffect } from 'react';
+
+export const useIsomorphicEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;

package/src/hooks/useLongPress.ts

@@ -1,52 +1,55 @@
-import { ComponentProps, useRef } from 'react';
+import { useRef, useState } from 'react';
 
 import { useTimeout } from './useTimeout';
 
-export function useLongPress(callback: (pressCount: number) => void, ms: number = 2000, isDisabled = false) {
-    const longPressTimeout = useTimeout();
-    const longPressCount = useRef(1);
-    const duration = useRef(ms);
-
-    const stop = () => {
-        longPressCount.current = 1;
-        duration.current = ms;
-        longPressTimeout.clear();
-    };
-
-    const start = () => {
-        duration.current /= 2;
-        longPressTimeout.set(
-            () => {
-                callback(longPressCount.current);
-                longPressCount.current += 1;
-                start();
-            },
-            //
-            Math.max(duration.current, 100),
-        );
+export const MIN_INTERVAL = 250; // Minimum interval in milliseconds
+export const INTERVAL_DECREASE_FACTOR = 0.75; // Percent by which the interval decreases each time
+export const INITIAL_INTERVAL = 1000; // Initial interval in milliseconds
+
+const isTriggerElementDisabled = (element: HTMLElement | null) =>
+    !element ||
+    (element as HTMLButtonElement).disabled ||
+    element.getAttribute('disabled') === 'true' ||
+    element.getAttribute('aria-disabled') === 'true' ||
+    element.getAttribute('data-disabled') === 'true' ||
+    !element.isConnected ||
+    !element.offsetParent;
+
+export function useLongPress(callback: () => void, disabled: boolean) {
+    const timeout = useTimeout();
+    const intervalRef = useRef(INITIAL_INTERVAL);
+
+    const [triggerElement, setTriggerElement] = useState<HTMLButtonElement | null>(null);
+
+    if (disabled)
+        return {
+            onMouseDown: () => {},
+            onMouseUp: () => {},
+            setTriggerElement: () => {},
+        };
+
+    const run = () => {
+        // If the element is not connected or disabled, clear the timeout, and prevent the callback
+        if (isTriggerElementDisabled(triggerElement)) return;
+        callback();
+        // Decrease the interval for the next call, but not below MIN_INTERVAL
+        if (intervalRef.current > MIN_INTERVAL) intervalRef.current = intervalRef.current * INTERVAL_DECREASE_FACTOR;
+        timeout.set(run, intervalRef.current);
     };
 
-    const buttonProps: ComponentProps<'button'> = {
-        onMouseDown: (event) => {
-            event.preventDefault();
-            if (isDisabled) return;
-
-            callback(longPressCount.current);
-            start();
+    return {
+        onMouseDown: () => {
+            intervalRef.current = INITIAL_INTERVAL;
+            callback();
+            timeout.set(run, intervalRef.current);
         },
-        onMouseMove: (event) => {
-            event.preventDefault();
-            if (event.movementX > 100 || event.movementY > 100) stop();
+        onMouseUp: () => {
+            timeout.clear();
         },
-        onMouseLeave: () => stop(),
-        onMouseUp: () => stop(),
-    };
-
-    return {
-        start,
-        stop,
-        buttonProps,
-        timeout: longPressTimeout,
+        onMouseLeave: () => {
+            timeout.clear();
+        },
+        setTriggerElement,
     };
 }
 

package/src/hooks/useMutationObserver.ts

@@ -0,0 +1,29 @@
+import { useEffect } from 'react';
+
+/**
+ * This hook allows you to observe mutations on a target element using the MutationObserver API.
+ *
+ * @param target {HTMLElement | null} The target element to observe for mutations.
+ * @param callback {MutationCallback} The callback function to execute when mutations are observed.
+ * @param options {MutationObserverInit} The options for the mutation observer.
+ */
+export function useMutationObserver(
+    target: HTMLElement | null,
+    callback: MutationCallback,
+    options: MutationObserverInit = {
+        attributes: true,
+        characterData: true,
+        childList: true,
+        subtree: true,
+    },
+) {
+    useEffect(() => {
+        if (target) {
+            const observer = new MutationObserver(callback);
+            observer.observe(target, options);
+            callback([], observer); // Initial call to set state based on current target state
+            return () => observer.disconnect();
+        }
+        return () => null;
+    }, [callback, options, target]);
+}

package/src/hooks/useOptionIconsInvalid.ts

@@ -1,7 +1,7 @@
 import { useMemo } from 'react';
 
-import { isValidIcon } from '../utils/children';
-import { useErrorLogger } from '../utils/errors';
+import { isValidIcon } from '-/utils/children';
+import { useErrorLogger } from '-/utils/errors';
 
 /**
  * A utility hook used within navigation components. Returns true if the icons are invalid.

package/src/hooks/useOutsideClick.ts

@@ -1,4 +1,5 @@
 import { useEffect } from 'react';
+
 /**
  * A hook which calls a method when a click occurs outside of the provided ref. Used inside the DropDown and Modal
  * components.
@@ -29,12 +30,12 @@ import { useEffect } from 'react';
  * @param disabled - Whether the hook should be disabled. Defaults to false.
  */
 export function useOutsideClick(
-    elements: (HTMLElement | null)[],
+    elements: (HTMLElement | null)[] | null,
     callback: (event?: MouseEvent) => void,
     disabled?: boolean,
 ) {
     useEffect(() => {
-        if (!elements.length || disabled) return;
+        if (!elements?.length || disabled) return;
 
         const handleClickOutside = (event: MouseEvent) => {
             if (disabled || elements?.some?.((element) => element?.contains?.(event.target as Node))) return;

package/src/hooks/useRadioState.ts

@@ -1,6 +1,6 @@
 import { useState } from 'react';
 
-import { RadioProps } from '../Radio';
+import { RadioProps } from '-/components/Radio';
 
 /**
  * A hook to manage the state of a single radio. Used alongside the Radio component.

package/src/hooks/useTimeout.ts

@@ -7,15 +7,14 @@ import { useRef, useEffect, useMemo } from 'react';
  *     import { useTimeout } from '@bspk/ui/hooks/useTimeout';
  *     import { useEffect } from 'react';
  *
- *     function MyComponent() {
- *     const timeoutRef = useTimeout();
+ *     export function MyComponent() {
+ *     const timeout = useTimeout();
  *
- *     useEffect(() => {
- *     timeoutRef.current = setTimeout(() => {
- *     console.log('Timeout triggered');
- *     }, 1000);
- *     }, []);
- *     return <div>Check the console after 1 second</div>;
+ *     const handleClick = () => {
+ *     timeout.set(() => console.log('Timeout triggered'), 1000);
+ *     };
+ *
+ *     return <Button onClick={handleClick}>Click here then check the console.</Button>;
  *     }
  *
  * @returns A ref object that can be used to store a timeout id.

package/src/hooks/useTruncatedText.ts

@@ -0,0 +1,20 @@
+import { useState } from 'react';
+
+import { useMutationObserver } from './useMutationObserver';
+
+/**
+ * Custom hook to determine if a text element is truncated.
+ *
+ * @returns {{ isTruncated: boolean; setElement: (element: HTMLElement | null) => void }} -- An object containing
+ *   `isTruncated` boolean and a function to set the element to observe.
+ */
+export function useTruncatedText(): { isTruncated: boolean; setElement: (element: HTMLElement | null) => void } {
+    const [element, setElement] = useState<HTMLElement | null>(null);
+    const [isTruncated, setIsTruncated] = useState<boolean>(false);
+
+    useMutationObserver(element, () => {
+        setIsTruncated(!!element && element.scrollWidth > element.clientWidth);
+    });
+
+    return { isTruncated, setElement };
+}

package/src/hooks/useUIContext.ts

@@ -0,0 +1,11 @@
+import { useContext } from 'react';
+
+import { UIContext } from '-/utils/uiContext';
+
+export const useUIContext = () => {
+    const context = useContext(UIContext);
+    if (!context) {
+        throw new Error('useUIContext must be used within a UIProvider');
+    }
+    return context;
+};

package/src/hooks/useValidChildren.ts

@@ -1,7 +1,7 @@
 import { ReactNode, useMemo } from 'react';
 
-import { getChildrenElements } from '../utils/children';
-import { useErrorLogger } from '../utils/errors';
+import { getChildrenElements } from '-/utils/children';
+import { useErrorLogger } from '-/utils/errors';
 
 const VALID_CHILDREN = ['Icon', 'string'];