@bspk/ui 1.0.0

package/hooks/useFloatingMenu.d.ts

@@ -0,0 +1,35 @@
+import { AriaAttributes } from 'react';
+import { CommonProps } from '..';
+import { Placement } from './useFloating';
+export type UseFloatingMenuProps = {
+    placement: Placement;
+    triggerProps?: CommonProps<'disabled' | 'invalid' | 'readOnly'>;
+};
+export type UseFloatingMenuReturn = {
+    menuProps: {
+        activeIndex: number;
+        'data-placement': Placement | undefined;
+        id: string;
+        innerRef: (node: HTMLElement | null) => void;
+        role: 'listbox';
+        style: React.CSSProperties;
+        tabIndex: number;
+    };
+    triggerProps: {
+        'aria-activedescendant': string | undefined;
+        'aria-controls': string;
+        'aria-expanded': boolean;
+        'aria-haspopup': AriaAttributes['aria-haspopup'];
+        'aria-invalid': boolean | undefined;
+        'aria-owns': string;
+        'aria-readonly': boolean | undefined;
+        role: 'combobox';
+        tabIndex: number;
+        ref: (node: HTMLElement | null) => void;
+        onClick: (event: React.MouseEvent) => void;
+        onKeyDownCapture: (event: React.KeyboardEvent) => boolean;
+    };
+    closeMenu: () => void;
+};
+export declare function useFloatingMenu({ placement, triggerProps }: UseFloatingMenuProps): UseFloatingMenuReturn;
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/hooks/useFloatingMenu.js

@@ -0,0 +1,71 @@
+import { useId, useState } from 'react';
+import { EVENT_KEY } from '../utils/keyboard.js';
+import { useFloating } from './useFloating.js';
+import { useKeyboardNavigation } from './useKeyboardNavigation.js';
+import { useOutsideClick } from './useOutsideClick.js';
+
+function useFloatingMenu({ placement, triggerProps }) {
+    const menuId = useId();
+    const [show, setShow] = useState(false);
+    const closeMenu = () => setShow(false);
+    const openMenu = () => setShow(true);
+    const { floatingStyles, middlewareData, elements } = useFloating({
+        placement,
+        strategy: 'fixed',
+        offsetOptions: 4,
+        refWidth: true,
+        hide: !show,
+    });
+    const { handleKeyNavigation, selectedIndex: activeIndex, selectedId } = useKeyboardNavigation(elements.floating);
+    useOutsideClick([elements.floating, elements.trigger], (event) => {
+        event?.stopPropagation();
+        if (!show)
+            return;
+        closeMenu();
+    });
+    return {
+        menuProps: {
+            activeIndex,
+            'data-placement': middlewareData?.offset?.placement,
+            id: menuId,
+            innerRef: (node) => {
+                elements.setFloating(node);
+            },
+            role: 'listbox',
+            style: floatingStyles,
+            tabIndex: -1,
+        },
+        triggerProps: {
+            'aria-activedescendant': selectedId || undefined,
+            'aria-controls': menuId,
+            'aria-expanded': show,
+            'aria-haspopup': 'listbox',
+            'aria-invalid': triggerProps?.invalid || undefined,
+            'aria-owns': menuId,
+            'aria-readonly': triggerProps?.readOnly || undefined,
+            role: 'combobox',
+            tabIndex: 0,
+            ref: (node) => elements.setTrigger(node),
+            onClick: () => {
+                setShow((prev) => !prev);
+            },
+            /**
+             * @param {React.KeyboardEvent} event
+             * @returns {boolean} True if event was handled internally
+             */
+            onKeyDownCapture: (event) => {
+                if (event.key === EVENT_KEY.Tab || event.key === EVENT_KEY.Escape) {
+                    closeMenu();
+                    return true;
+                }
+                openMenu();
+                return handleKeyNavigation?.(event.nativeEvent);
+            },
+        },
+        closeMenu,
+    };
+}
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */
+
+export { useFloatingMenu };
+//# sourceMappingURL=useFloatingMenu.js.map

package/hooks/useFloatingMenu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFloatingMenu.js","sources":["../src/hooks/useFloatingMenu.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;SAyCgB,eAAe,CAAC,EAAE,SAAS,EAAE,YAAY,EAAwB,EAAA;AAC7E,IAAA,MAAM,MAAM,GAAG,KAAK,EAAE,CAAC;IAEvB,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,WAAW,CAAC;QAC7D,SAAS;AACT,QAAA,QAAQ,EAAE,OAAO;AACjB,QAAA,aAAa,EAAE,CAAC;AAChB,QAAA,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,CAAC,IAAI;AACd,KAAA,CAAC,CAAC;AAEH,IAAA,MAAM,EAAE,mBAAmB,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,qBAAqB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAEjH,IAAA,eAAe,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,KAAI;QAC7D,KAAK,EAAE,eAAe,EAAE,CAAC;AACzB,QAAA,IAAI,CAAC,IAAI;YAAE,OAAO;AAClB,QAAA,SAAS,EAAE,CAAC;AAChB,KAAC,CAAC,CAAC;IAEH,OAAO;AACH,QAAA,SAAS,EAAE;YACP,WAAW;AACX,YAAA,gBAAgB,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS;AACnD,YAAA,EAAE,EAAE,MAAM;AACV,YAAA,QAAQ,EAAE,CAAC,IAAwB,KAAI;AACnC,gBAAA,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;aAC9B;AACD,YAAA,IAAI,EAAE,SAAS;AACf,YAAA,KAAK,EAAE,cAAc;YACrB,QAAQ,EAAE,CAAC,CAAC;AACf,SAAA;AACD,QAAA,YAAY,EAAE;YACV,uBAAuB,EAAE,UAAU,IAAI,SAAS;AAChD,YAAA,eAAe,EAAE,MAAM;AACvB,YAAA,eAAe,EAAE,IAAI;AACrB,YAAA,eAAe,EAAE,SAA4C;AAC7D,YAAA,cAAc,EAAE,YAAY,EAAE,OAAO,IAAI,SAAS;AAClD,YAAA,WAAW,EAAE,MAAM;AACnB,YAAA,eAAe,EAAE,YAAY,EAAE,QAAQ,IAAI,SAAS;AACpD,YAAA,IAAI,EAAE,UAAU;AAChB,YAAA,QAAQ,EAAE,CAAC;YACX,GAAG,EAAE,CAAC,IAAwB,KAAK,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC;YAC5D,OAAO,EAAE,MAAK;gBACV,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC;aAC5B;AACD;;;AAGG;AACH,YAAA,gBAAgB,EAAE,CAAC,KAA0B,KAAa;AACtD,gBAAA,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,MAAM,EAAE;AAC/D,oBAAA,SAAS,EAAE,CAAC;AACZ,oBAAA,OAAO,IAAI,CAAC;iBACf;AAED,gBAAA,QAAQ,EAAE,CAAC;AAEX,gBAAA,OAAO,mBAAmB,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;aACnD;AACJ,SAAA;QACD,SAAS;KACZ,CAAC;AACN,CAAC;AAED;;;;"}

package/hooks/useId.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A utility hook that generates a unique id for an element. If a default id is provided, it will use that instead.
+ *
+ * @param {string | undefined | null} defaultId
+ * @returns {string}
+ */
+export declare function useId(defaultId?: string | null): string;
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/hooks/useId.js

@@ -0,0 +1,16 @@
+import { useId as useId$1 } from 'react';
+
+/**
+ * A utility hook that generates a unique id for an element. If a default id is provided, it will use that instead.
+ *
+ * @param {string | undefined | null} defaultId
+ * @returns {string}
+ */
+function useId(defaultId) {
+    const generatedId = useId$1();
+    return defaultId || generatedId;
+}
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */
+
+export { useId };
+//# sourceMappingURL=useId.js.map

package/hooks/useId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useId.js","sources":["../src/hooks/useId.ts"],"sourcesContent":[null],"names":["useIdReact"],"mappings":";;AAEA;;;;;AAKG;AACG,SAAU,KAAK,CAAC,SAAyB,EAAA;AAC3C,IAAA,MAAM,WAAW,GAAGA,OAAU,EAAE,CAAC;IACjC,OAAO,SAAS,IAAI,WAAW,CAAC;AACpC,CAAC;AAED;;;;"}

package/hooks/useKeyboardNavigation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * This hook provides keyboard navigation for a list of elements. Used inside the Dropdown component.
+ *
+ * @example
+ *     import { useRef } from 'react';
+ *     import { useKeyboardNavigation } from '@bspk/ui/hooks/useKeyboardNavigation';
+ *
+ *     export function Example() {
+ *     const containerRef = useRef<HTMLDivElement>(null);
+ *     const { selectedIndex, setSelectedIndex, handleKeyNavigation } = useKeyboardNavigation(containerRef.current, () => true);
+ *
+ *     return (
+ *     <div ref={containerRef} onKeyDown={handleKeyNavigation} tabIndex={0}>
+ *     {items.map((item, index) => (
+ *     <div key={index} data-selected={selectedIndex === index}>
+ *     {item}
+ *     </div>
+ *     ))}
+ *     </div>
+ *     );
+ *     }
+ *
+ * @param containerElement - The container element that holds the list of elements.
+ * @param onNavigate - Fires when the user navigates through the list with Arrow keys. If the function returns false,
+ *   the navigation will be prevented. For example, this is useful when you want to prevent navigation when a dropdown
+ *   is closed.
+ * @returns An object containing the selectedIndex, setSelectedIndex, and handleKeyNavigation function.
+ */
+export declare function useKeyboardNavigation(containerElement?: HTMLElement | null): {
+    handleKeyNavigation: (event: KeyboardEvent) => boolean;
+    selectedIndex: number;
+    selectedId: string | undefined;
+    setSelectedIndex: (index: number) => void;
+};
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/hooks/useKeyboardNavigation.js

@@ -0,0 +1,79 @@
+import { useState } from 'react';
+import { EVENT_KEY } from '../utils/keyboard.js';
+import { scrollElementIntoView } from '../utils/scrollElementIntoView.js';
+
+/**
+ * This hook provides keyboard navigation for a list of elements. Used inside the Dropdown component.
+ *
+ * @example
+ *     import { useRef } from 'react';
+ *     import { useKeyboardNavigation } from '@bspk/ui/hooks/useKeyboardNavigation';
+ *
+ *     export function Example() {
+ *     const containerRef = useRef<HTMLDivElement>(null);
+ *     const { selectedIndex, setSelectedIndex, handleKeyNavigation } = useKeyboardNavigation(containerRef.current, () => true);
+ *
+ *     return (
+ *     <div ref={containerRef} onKeyDown={handleKeyNavigation} tabIndex={0}>
+ *     {items.map((item, index) => (
+ *     <div key={index} data-selected={selectedIndex === index}>
+ *     {item}
+ *     </div>
+ *     ))}
+ *     </div>
+ *     );
+ *     }
+ *
+ * @param containerElement - The container element that holds the list of elements.
+ * @param onNavigate - Fires when the user navigates through the list with Arrow keys. If the function returns false,
+ *   the navigation will be prevented. For example, this is useful when you want to prevent navigation when a dropdown
+ *   is closed.
+ * @returns An object containing the selectedIndex, setSelectedIndex, and handleKeyNavigation function.
+ */
+function useKeyboardNavigation(containerElement) {
+    const [selectedIndex, setSelectedIndex] = useState(-1);
+    if (!containerElement)
+        return {
+            handleKeyNavigation: () => false,
+            selectedIndex,
+            setSelectedIndex: () => { },
+            selectedId: undefined,
+        };
+    const handleArrowKeyNavigation = (event) => {
+        if (event.key !== EVENT_KEY.Enter && !event.key.startsWith('Arrow'))
+            return false;
+        event.preventDefault();
+        if (!containerElement || !containerElement.children.length)
+            return false;
+        const itemElements = Array.from(containerElement?.children);
+        if (event.key === EVENT_KEY.Enter && selectedIndex !== -1) {
+            itemElements[selectedIndex].click();
+            return true;
+        }
+        let next = 0;
+        if (event.key === EVENT_KEY.ArrowUp || event.key === EVENT_KEY.ArrowLeft)
+            next = selectedIndex - 1;
+        if (event.key === EVENT_KEY.ArrowDown || event.key === EVENT_KEY.ArrowRight)
+            next = selectedIndex + 1;
+        if (next < 0)
+            next = itemElements.length - 1;
+        if (next >= itemElements.length)
+            next = 0;
+        itemElements.forEach((el, index) => {
+            el.dataset.selected = index === next ? 'true' : undefined;
+        });
+        scrollElementIntoView(itemElements[next], containerElement);
+        setSelectedIndex(next);
+        return true;
+    };
+    return {
+        handleKeyNavigation: handleArrowKeyNavigation,
+        selectedIndex,
+        selectedId: selectedIndex === -1 ? undefined : containerElement.children[selectedIndex].id,
+        setSelectedIndex: setSelectedIndex,
+    };
+}
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */
+
+export { useKeyboardNavigation };
+//# sourceMappingURL=useKeyboardNavigation.js.map

package/hooks/useKeyboardNavigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyboardNavigation.js","sources":["../src/hooks/useKeyboardNavigation.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACG,SAAU,qBAAqB,CACjC,gBAAqC,EAAA;IAerC,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvD,IAAA,IAAI,CAAC,gBAAgB;QACjB,OAAO;AACH,YAAA,mBAAmB,EAAE,MAAM,KAAK;YAChC,aAAa;AACb,YAAA,gBAAgB,EAAE,MAAK,GAAG;AAC1B,YAAA,UAAU,EAAE,SAAS;SACxB,CAAC;AAEN,IAAA,MAAM,wBAAwB,GAAG,CAAC,KAAoB,KAAa;AAC/D,QAAA,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;AAAE,YAAA,OAAO,KAAK,CAAC;QAElF,KAAK,CAAC,cAAc,EAAE,CAAC;QAEvB,IAAI,CAAC,gBAAgB,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,MAAM;AAAE,YAAA,OAAO,KAAK,CAAC;QAEzE,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAkB,CAAC;AAE7E,QAAA,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,KAAK,IAAI,aAAa,KAAK,CAAC,CAAC,EAAE;AACvD,YAAA,YAAY,CAAC,aAAa,CAAC,CAAC,KAAK,EAAE,CAAC;AACpC,YAAA,OAAO,IAAI,CAAC;SACf;QAED,IAAI,IAAI,GAAG,CAAC,CAAC;AACb,QAAA,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,OAAO,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,SAAS;AAAE,YAAA,IAAI,GAAG,aAAa,GAAG,CAAC,CAAC;AACnG,QAAA,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,SAAS,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,UAAU;AAAE,YAAA,IAAI,GAAG,aAAa,GAAG,CAAC,CAAC;QAEtG,IAAI,IAAI,GAAG,CAAC;AAAE,YAAA,IAAI,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;AAC7C,QAAA,IAAI,IAAI,IAAI,YAAY,CAAC,MAAM;YAAE,IAAI,GAAG,CAAC,CAAC;QAE1C,YAAY,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,KAAK,KAAI;AAC/B,YAAA,EAAE,CAAC,OAAO,CAAC,QAAQ,GAAG,KAAK,KAAK,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;AAC9D,SAAC,CAAC,CAAC;QAEH,qBAAqB,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC,CAAC;QAC5D,gBAAgB,CAAC,IAAI,CAAC,CAAC;AACvB,QAAA,OAAO,IAAI,CAAC;AAChB,KAAC,CAAC;IAEF,OAAO;AACH,QAAA,mBAAmB,EAAE,wBAAwB;QAC7C,aAAa;AACb,QAAA,UAAU,EAAE,aAAa,KAAK,CAAC,CAAC,GAAG,SAAS,GAAG,gBAAgB,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,EAAE;AAC1F,QAAA,gBAAgB,EAAE,gBAAgB;KACrC,CAAC;AACN,CAAC;AAED;;;;"}

package/hooks/useLongPress.d.ts

@@ -0,0 +1,11 @@
+export declare function useLongPress(callback: (pressCount: number) => void, ms?: number, isDisabled?: boolean): {
+    start: () => void;
+    stop: () => void;
+    buttonProps: import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>;
+    timeout: {
+        clear: () => void;
+        set: (callback: () => void, durationMs: number) => void;
+        ref: import("react").MutableRefObject<NodeJS.Timeout | null>;
+    };
+};
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/hooks/useLongPress.js

@@ -0,0 +1,49 @@
+import { useRef } from 'react';
+import { useTimeout } from './useTimeout.js';
+
+function useLongPress(callback, ms = 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));
+    };
+    const buttonProps = {
+        onMouseDown: (event) => {
+            event.preventDefault();
+            if (isDisabled)
+                return;
+            callback(longPressCount.current);
+            start();
+        },
+        onMouseMove: (event) => {
+            event.preventDefault();
+            if (event.movementX > 100 || event.movementY > 100)
+                stop();
+        },
+        onMouseLeave: () => stop(),
+        onMouseUp: () => stop(),
+    };
+    return {
+        start,
+        stop,
+        buttonProps,
+        timeout: longPressTimeout,
+    };
+}
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */
+
+export { useLongPress };
+//# sourceMappingURL=useLongPress.js.map

package/hooks/useLongPress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLongPress.js","sources":["../src/hooks/useLongPress.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIM,SAAU,YAAY,CAAC,QAAsC,EAAE,KAAa,IAAI,EAAE,UAAU,GAAG,KAAK,EAAA;AACtG,IAAA,MAAM,gBAAgB,GAAG,UAAU,EAAE,CAAC;AACtC,IAAA,MAAM,cAAc,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;AACjC,IAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;IAE5B,MAAM,IAAI,GAAG,MAAK;AACd,QAAA,cAAc,CAAC,OAAO,GAAG,CAAC,CAAC;AAC3B,QAAA,QAAQ,CAAC,OAAO,GAAG,EAAE,CAAC;QACtB,gBAAgB,CAAC,KAAK,EAAE,CAAC;AAC7B,KAAC,CAAC;IAEF,MAAM,KAAK,GAAG,MAAK;AACf,QAAA,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AACtB,QAAA,gBAAgB,CAAC,GAAG,CAChB,MAAK;AACD,YAAA,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AACjC,YAAA,cAAc,CAAC,OAAO,IAAI,CAAC,CAAC;AAC5B,YAAA,KAAK,EAAE,CAAC;SACX;;QAED,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAClC,CAAC;AACN,KAAC,CAAC;AAEF,IAAA,MAAM,WAAW,GAA6B;AAC1C,QAAA,WAAW,EAAE,CAAC,KAAK,KAAI;YACnB,KAAK,CAAC,cAAc,EAAE,CAAC;AACvB,YAAA,IAAI,UAAU;gBAAE,OAAO;AAEvB,YAAA,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AACjC,YAAA,KAAK,EAAE,CAAC;SACX;AACD,QAAA,WAAW,EAAE,CAAC,KAAK,KAAI;YACnB,KAAK,CAAC,cAAc,EAAE,CAAC;YACvB,IAAI,KAAK,CAAC,SAAS,GAAG,GAAG,IAAI,KAAK,CAAC,SAAS,GAAG,GAAG;AAAE,gBAAA,IAAI,EAAE,CAAC;SAC9D;AACD,QAAA,YAAY,EAAE,MAAM,IAAI,EAAE;AAC1B,QAAA,SAAS,EAAE,MAAM,IAAI,EAAE;KAC1B,CAAC;IAEF,OAAO;QACH,KAAK;QACL,IAAI;QACJ,WAAW;AACX,QAAA,OAAO,EAAE,gBAAgB;KAC5B,CAAC;AACN,CAAC;AAED;;;;"}

package/hooks/useModalState.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A hook to manage the state of a modal.
+ *
+ * @example
+ *     import { Modal } from '@bspk/ui/Modal';
+ *     import { useModalState } from '@bspk/ui/hooks/useModalState';
+ *
+ *     export function Example() {
+ *     const modalProps = useModalState(false);
+ *     return <Modal  {...modalProps}>...</Modal>
+ *     }
+ *
+ * @param parentValue - The value of the parent state.
+ * @param setParentState - A function to set the parent state.
+ * @returns An object with the open state and the `onClose` and `onOpen` callbacks.
+ */
+export declare function useModalState(parentValue?: boolean, setParentState?: (next: boolean) => void): {
+    open: boolean;
+    onClose: () => void;
+    onOpen: () => void;
+};
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/hooks/useModalState.js

@@ -0,0 +1,37 @@
+import { useState, useEffect } from 'react';
+
+/**
+ * A hook to manage the state of a modal.
+ *
+ * @example
+ *     import { Modal } from '@bspk/ui/Modal';
+ *     import { useModalState } from '@bspk/ui/hooks/useModalState';
+ *
+ *     export function Example() {
+ *     const modalProps = useModalState(false);
+ *     return <Modal  {...modalProps}>...</Modal>
+ *     }
+ *
+ * @param parentValue - The value of the parent state.
+ * @param setParentState - A function to set the parent state.
+ * @returns An object with the open state and the `onClose` and `onOpen` callbacks.
+ */
+function useModalState(parentValue = false, setParentState) {
+    const [open, setOpen] = useState(parentValue);
+    useEffect(() => setOpen(parentValue), [parentValue]);
+    return {
+        open,
+        onClose: () => {
+            setOpen(false);
+            setParentState?.(false);
+        },
+        onOpen: () => {
+            setOpen(true);
+            setParentState?.(true);
+        },
+    };
+}
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */
+
+export { useModalState };
+//# sourceMappingURL=useModalState.js.map

package/hooks/useModalState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useModalState.js","sources":["../src/hooks/useModalState.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;AAeG;SACa,aAAa,CAAC,WAAuB,GAAA,KAAK,EAAE,cAAwC,EAAA;IAChG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;AAE9C,IAAA,SAAS,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAErD,OAAO;QACH,IAAI;QACJ,OAAO,EAAE,MAAK;YACV,OAAO,CAAC,KAAK,CAAC,CAAC;AACf,YAAA,cAAc,GAAG,KAAK,CAAC,CAAC;SAC3B;QACD,MAAM,EAAE,MAAK;YACT,OAAO,CAAC,IAAI,CAAC,CAAC;AACd,YAAA,cAAc,GAAG,IAAI,CAAC,CAAC;SAC1B;KACJ,CAAC;AACN,CAAC;AAED;;;;"}

package/hooks/useNavOptions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A utility hook used within navigation components. Returns options ready for use in a navigation component. Validates
+ * the icons and sets the icon and iconActive properties.
+ *
+ * @param options [NavOption[]] The options to display. Each option has a label and an optional leading icon.
+ * @returns {undefined} NavOption[] The options with the validated icon and iconActive properties set.
+ */
+export declare function useNavOptions<T extends NavOption>(options: T[] | undefined): T[];
+export type NavOption = {
+    /**
+     * The label of the option. This is the text that will be displayed on the option.
+     *
+     * @required
+     */
+    label: string;
+    /**
+     * Determines if the element is [disabled](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled).
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /** The value of the option. If not provided, the label will be used as the value. */
+    value?: string;
+    /** The the icon to display before the label. */
+    icon?: React.ReactNode;
+    iconActive?: React.ReactNode;
+};
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/hooks/useNavOptions.js

@@ -0,0 +1,46 @@
+import { useMemo } from 'react';
+import { isValidIcon, getChildTypeName } from '../utils/children.js';
+import { useErrorLogger } from '../utils/errors.js';
+
+/**
+ * A utility hook used within navigation components. Returns options ready for use in a navigation component. Validates
+ * the icons and sets the icon and iconActive properties.
+ *
+ * @param options [NavOption[]] The options to display. Each option has a label and an optional leading icon.
+ * @returns {undefined} NavOption[] The options with the validated icon and iconActive properties set.
+ */
+function useNavOptions(options) {
+    const { logError } = useErrorLogger();
+    return useMemo(() => {
+        if (!options)
+            return [];
+        const iconsInvalid = options.some((o) => o.icon) ? !options.every((option) => isValidIcon(option.icon)) : null;
+        logError(iconsInvalid === true, 'useNavOptions - Every option either must have a valid icon or none at all. All icons removed.');
+        return options
+            .map((option) => {
+            let { icon, iconActive } = option;
+            if (iconsInvalid) {
+                icon = undefined;
+                iconActive = undefined;
+            }
+            if (iconActive &&
+                // If the iconActive is not a valid icon or the iconActive is not a fill version of the icon, remove the iconActive
+                (!icon ||
+                    !isValidIcon(iconActive) ||
+                    getChildTypeName(iconActive) !== `${getChildTypeName(icon)}Fill`)) {
+                iconActive = undefined;
+            }
+            return {
+                ...option,
+                value: option.value || option.label,
+                icon,
+                iconActive,
+            };
+        })
+            .map((tab, _, arr) => ({ ...tab, icon: arr.every((t) => t.icon) ? tab.icon : undefined }));
+    }, [logError, options]);
+}
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */
+
+export { useNavOptions };
+//# sourceMappingURL=useNavOptions.js.map

package/hooks/useNavOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNavOptions.js","sources":["../src/hooks/useNavOptions.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAKA;;;;;;AAMG;AACG,SAAU,aAAa,CAAsB,OAAwB,EAAA;AACvE,IAAA,MAAM,EAAE,QAAQ,EAAE,GAAG,cAAc,EAAE,CAAC;IAEtC,OAAO,OAAO,CAAC,MAAK;AAChB,QAAA,IAAI,CAAC,OAAO;AAAE,YAAA,OAAO,EAAE,CAAC;AAExB,QAAA,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;AAE/G,QAAA,QAAQ,CACJ,YAAY,KAAK,IAAI,EACrB,+FAA+F,CAClG,CAAC;AAEF,QAAA,OAAO,OAAO;AACT,aAAA,GAAG,CAAC,CAAC,MAAM,KAAI;AACZ,YAAA,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;YAElC,IAAI,YAAY,EAAE;gBACd,IAAI,GAAG,SAAS,CAAC;gBACjB,UAAU,GAAG,SAAS,CAAC;aAC1B;AAED,YAAA,IACI,UAAU;;AAEV,iBAAC,CAAC,IAAI;oBACF,CAAC,WAAW,CAAC,UAAU,CAAC;AACxB,oBAAA,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAG,EAAA,gBAAgB,CAAC,IAAI,CAAC,CAAA,IAAA,CAAM,CAAC,EACvE;gBACE,UAAU,GAAG,SAAS,CAAC;aAC1B;YAED,OAAO;AACH,gBAAA,GAAG,MAAM;AACT,gBAAA,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;gBACnC,IAAI;gBACJ,UAAU;aACb,CAAC;AACN,SAAC,CAAC;AACD,aAAA,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC,CAAC,CAAC;AACnG,KAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAC5B,CAAC;AAsBD;;;;"}

package/hooks/useOutsideClick.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A hook which calls a method when a click occurs outside of the provided ref. Used inside the Dropdown and Modal
+ * components.
+ *
+ * @example
+ *     import { useOutsideClick } from '@bspk/ui/hooks/useOutsideClick';
+ *     import React, { useRef, useState } from 'react';
+ *
+ *     export function Dropdown() {
+ *     const [isOpen, setIsOpen] = useState(false);
+ *     const containerRef = useRef<HTMLDivElement>(null);
+ *
+ *     useOutsideClick([containerRef.current], () => setIsOpen(false));
+ *
+ *     return (
+ *     <>
+ *     {isOpen && (
+ *     <div className="custom-popup" ref={containerRef}>
+ *     Content
+ *     </div>
+ *     )}
+ *     </>
+ *     );
+ *     }
+ *
+ * @param elements - The elements to check if the click occurred outside of.
+ * @param callback - The callback to call when a click occurs outside of the ref.
+ * @param disabled - Whether the hook should be disabled. Defaults to false.
+ */
+export declare function useOutsideClick(elements: (HTMLElement | null)[], callback: (event?: MouseEvent) => void, disabled?: boolean): void;
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/hooks/useOutsideClick.js

@@ -0,0 +1,50 @@
+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.
+ *
+ * @example
+ *     import { useOutsideClick } from '@bspk/ui/hooks/useOutsideClick';
+ *     import React, { useRef, useState } from 'react';
+ *
+ *     export function Dropdown() {
+ *     const [isOpen, setIsOpen] = useState(false);
+ *     const containerRef = useRef<HTMLDivElement>(null);
+ *
+ *     useOutsideClick([containerRef.current], () => setIsOpen(false));
+ *
+ *     return (
+ *     <>
+ *     {isOpen && (
+ *     <div className="custom-popup" ref={containerRef}>
+ *     Content
+ *     </div>
+ *     )}
+ *     </>
+ *     );
+ *     }
+ *
+ * @param elements - The elements to check if the click occurred outside of.
+ * @param callback - The callback to call when a click occurs outside of the ref.
+ * @param disabled - Whether the hook should be disabled. Defaults to false.
+ */
+function useOutsideClick(elements, callback, disabled) {
+    useEffect(() => {
+        if (!elements.length || disabled)
+            return;
+        const handleClickOutside = (event) => {
+            if (disabled || elements?.some?.((element) => element?.contains?.(event.target)))
+                return;
+            callback(event);
+        };
+        document.addEventListener('mousedown', handleClickOutside);
+        return () => {
+            document.removeEventListener('mousedown', handleClickOutside);
+        };
+    }, [callback, disabled, elements]);
+}
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */
+
+export { useOutsideClick };
+//# sourceMappingURL=useOutsideClick.js.map

package/hooks/useOutsideClick.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOutsideClick.js","sources":["../src/hooks/useOutsideClick.ts"],"sourcesContent":[null],"names":[],"mappings":";;AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BG;SACa,eAAe,CAC3B,QAAgC,EAChC,QAAsC,EACtC,QAAkB,EAAA;IAElB,SAAS,CAAC,MAAK;AACX,QAAA,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ;YAAE,OAAO;AAEzC,QAAA,MAAM,kBAAkB,GAAG,CAAC,KAAiB,KAAI;YAC7C,IAAI,QAAQ,IAAI,QAAQ,EAAE,IAAI,GAAG,CAAC,OAAO,KAAK,OAAO,EAAE,QAAQ,GAAG,KAAK,CAAC,MAAc,CAAC,CAAC;gBAAE,OAAO;YACjG,QAAQ,CAAC,KAAK,CAAC,CAAC;AACpB,SAAC,CAAC;AAEF,QAAA,QAAQ,CAAC,gBAAgB,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC;AAC3D,QAAA,OAAO,MAAK;AACR,YAAA,QAAQ,CAAC,mBAAmB,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC;AAClE,SAAC,CAAC;KACL,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;"}

package/hooks/useRadioState.d.ts

@@ -0,0 +1,23 @@
+import { RadioProps } from '../Radio';
+/**
+ * A hook to manage the state of a single radio. Used alongside the Radio component.
+ *
+ * @example
+ *     import { Radio } from '@bspk/ui/Radio';
+ *     import { useRadioState } from '@bspk/ui/hooks/useRadioState';
+ *
+ *     export function Example() {
+ *     const { radioProps } = useRadioState('fruits');
+ *     return <Radio aria-label="cherry" {...radioProps('cherry')} />;
+ *     }
+ *
+ * @param name - The name of the radio.
+ * @param externalState - The externally managed state of the radio.
+ * @returns Properties to pass to the radio and the state of the radio.
+ */
+export declare function useRadioState(name: string, externalState?: [value: string | undefined, onChange: (next: string) => void]): {
+    radioProps: (radioValue: string) => Pick<RadioProps, "checked" | "name" | "onChange" | "value">;
+    value: string | undefined;
+    setValue: (next: string) => void;
+};
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/hooks/useRadioState.js

@@ -0,0 +1,38 @@
+import { useState } from 'react';
+
+/**
+ * A hook to manage the state of a single radio. Used alongside the Radio component.
+ *
+ * @example
+ *     import { Radio } from '@bspk/ui/Radio';
+ *     import { useRadioState } from '@bspk/ui/hooks/useRadioState';
+ *
+ *     export function Example() {
+ *     const { radioProps } = useRadioState('fruits');
+ *     return <Radio aria-label="cherry" {...radioProps('cherry')} />;
+ *     }
+ *
+ * @param name - The name of the radio.
+ * @param externalState - The externally managed state of the radio.
+ * @returns Properties to pass to the radio and the state of the radio.
+ */
+function useRadioState(name, externalState) {
+    const localState = useState();
+    const [value, setValue] = externalState || localState;
+    const radioProps = (radioValue) => {
+        return {
+            name,
+            checked: value === radioValue,
+            value: radioValue,
+            onChange: (checked) => {
+                if (checked)
+                    setValue(radioValue);
+            },
+        };
+    };
+    return { radioProps, value, setValue };
+}
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */
+
+export { useRadioState };
+//# sourceMappingURL=useRadioState.js.map

package/hooks/useRadioState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRadioState.js","sources":["../src/hooks/useRadioState.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAIA;;;;;;;;;;;;;;;AAeG;AACa,SAAA,aAAa,CACzB,IAAY,EACZ,aAA6E,EAAA;AAE7E,IAAA,MAAM,UAAU,GAAG,QAAQ,EAAU,CAAC;IACtC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,aAAa,IAAI,UAAU,CAAC;AAEtD,IAAA,MAAM,UAAU,GAAG,CAAC,UAAkB,KAAiE;QACnG,OAAO;YACH,IAAI;YACJ,OAAO,EAAE,KAAK,KAAK,UAAU;AAC7B,YAAA,KAAK,EAAE,UAAU;AACjB,YAAA,QAAQ,EAAE,CAAC,OAAO,KAAI;AAClB,gBAAA,IAAI,OAAO;oBAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;aACrC;SACJ,CAAC;AACN,KAAC,CAAC;AAEF,IAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC3C,CAAC;AAED;;;;"}