@bspk/ui 1.0.0

package/src/hooks/useFloatingMenu.ts

@@ -0,0 +1,110 @@
+import { AriaAttributes, useId, useState } from 'react';
+
+import { CommonProps } from '..';
+import { EVENT_KEY } from '../utils/keyboard';
+
+import { Placement, useFloating } from './useFloating';
+import { useKeyboardNavigation } from './useKeyboardNavigation';
+import { useOutsideClick } from './useOutsideClick';
+
+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 function useFloatingMenu({ placement, triggerProps }: UseFloatingMenuProps): UseFloatingMenuReturn {
+    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: HTMLElement | null) => {
+                elements.setFloating(node);
+            },
+            role: 'listbox',
+            style: floatingStyles,
+            tabIndex: -1,
+        },
+        triggerProps: {
+            'aria-activedescendant': selectedId || undefined,
+            'aria-controls': menuId,
+            'aria-expanded': show,
+            'aria-haspopup': 'listbox' as AriaAttributes['aria-haspopup'],
+            'aria-invalid': triggerProps?.invalid || undefined,
+            'aria-owns': menuId,
+            'aria-readonly': triggerProps?.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);
+            },
+        },
+        closeMenu,
+    };
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useId.ts

@@ -0,0 +1,14 @@
+import { useId as useIdReact } 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}
+ */
+export function useId(defaultId?: string | null): string {
+    const generatedId = useIdReact();
+    return defaultId || generatedId;
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useKeyboardNavigation.ts

@@ -0,0 +1,98 @@
+import { useState } from 'react';
+
+import { EVENT_KEY } from '../utils/keyboard';
+import { scrollElementIntoView } from '../utils/scrollElementIntoView';
+
+/**
+ * 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 function useKeyboardNavigation(
+    containerElement?: HTMLElement | null,
+    // /**
+    //  * Fires when the user navigates through the list with Arrow keys. If the function returns false, the navigation will
+    //  * be prevented. This is useful when you want to prevent navigation when the dropdown is closed.
+    //  *
+    //  * @returns Boolean
+    //  */
+    // selectedIndex: number,
+    // setSelectedIndex: (index: number) => void,
+): {
+    handleKeyNavigation: (event: KeyboardEvent) => boolean;
+    selectedIndex: number;
+    selectedId: string | undefined;
+    setSelectedIndex: (index: number) => void;
+} {
+    const [selectedIndex, setSelectedIndex] = useState(-1);
+
+    if (!containerElement)
+        return {
+            handleKeyNavigation: () => false,
+            selectedIndex,
+            setSelectedIndex: () => {},
+            selectedId: undefined,
+        };
+
+    const handleArrowKeyNavigation = (event: KeyboardEvent): boolean => {
+        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) as HTMLElement[];
+
+        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 */

package/src/hooks/useLongPress.ts

@@ -0,0 +1,53 @@
+import { ComponentProps, useRef } 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),
+        );
+    };
+
+    const buttonProps: ComponentProps<'button'> = {
+        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 */

package/src/hooks/useModalState.ts

@@ -0,0 +1,37 @@
+import { useEffect, useState } 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.
+ */
+export function useModalState(parentValue: boolean = false, setParentState?: (next: boolean) => void) {
+    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 */

package/src/hooks/useNavOptions.ts

@@ -0,0 +1,76 @@
+import { useMemo } from 'react';
+
+import { getChildTypeName, isValidIcon } from '../utils/children';
+import { useErrorLogger } from '../utils/errors';
+
+/**
+ * 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 function useNavOptions<T extends NavOption>(options: T[] | undefined): T[] {
+    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]);
+}
+
+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/src/hooks/useOutsideClick.ts

@@ -0,0 +1,51 @@
+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.
+ */
+export function useOutsideClick(
+    elements: (HTMLElement | null)[],
+    callback: (event?: MouseEvent) => void,
+    disabled?: boolean,
+) {
+    useEffect(() => {
+        if (!elements.length || disabled) return;
+
+        const handleClickOutside = (event: MouseEvent) => {
+            if (disabled || elements?.some?.((element) => element?.contains?.(event.target as Node))) return;
+            callback(event);
+        };
+
+        document.addEventListener('mousedown', handleClickOutside);
+        return () => {
+            document.removeEventListener('mousedown', handleClickOutside);
+        };
+    }, [callback, disabled, elements]);
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useRadioState.ts

@@ -0,0 +1,42 @@
+import { useState } from 'react';
+
+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 function useRadioState(
+    name: string,
+    externalState?: [value: string | undefined, onChange: (next: string) => void],
+) {
+    const localState = useState<string>();
+    const [value, setValue] = externalState || localState;
+
+    const radioProps = (radioValue: string): Pick<RadioProps, 'checked' | 'name' | 'onChange' | 'value'> => {
+        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 */

package/src/hooks/useSwitchGroupState.ts

@@ -0,0 +1,75 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import { SwitchProps } from '../Switch';
+
+/**
+ * A hook to manage the state of a group of switches. Used alongside the SwitchGroup component.
+ *
+ * @example
+ *     import { Switch } from '@bspk/ui/Switch';
+ *     import { useSwitchGroupState } from '@bspk/ui/hooks/useSwitchGroupState';
+ *
+ *     export function Example() {
+ *     const allValues = ['Red', 'Orange', 'Yellow', 'Green'];
+ *
+ *     const { allSwitchProps, switchProps, values } = useSwitchGroupState(allValues, 'fruits');
+ *
+ *     return (
+ *     <>
+ *     <pre>Selected Values: {values.join(', ')}</pre>
+ *     <Switch aria-label="All" {...allSwitchProps} />
+ *     {allValues.map((value) => (
+ *     <Switch key={value} aria-label={value} {...switchProps(value)} />
+ *     ))}
+ *     </>
+ *     );
+ *     }
+ *
+ * @param allValues - The values of the switches.
+ * @param name - The name of the switches.
+ * @param externalState - The externally managed state of the switches.
+ * @returns Properties to pass to the switch, other helper functions, and the state of the switch.
+ */
+export function useSwitchGroupState(
+    allValues: string[],
+    name: string,
+    externalState?: [values: string[], setValues: (next: string[]) => void],
+) {
+    const localState = useState<string[]>([]);
+    const [values, setValues] = externalState || localState;
+
+    const toggleValue = useCallback(
+        (itemValue: string, checked: boolean) => {
+            setValues(
+                allValues.flatMap((value) => {
+                    if (value === itemValue) return checked ? value : [];
+                    return values.includes(value) ? value : [];
+                }),
+            );
+        },
+        [allValues, setValues, values],
+    );
+
+    const switchProps = useCallback(
+        (value: string): Pick<SwitchProps, 'checked' | 'name' | 'onChange' | 'value'> => ({
+            checked: values.includes(value),
+            name,
+            onChange: (checked) => toggleValue(value, checked),
+            value,
+        }),
+        [values, name, toggleValue],
+    );
+
+    const allSwitchProps = useMemo((): Pick<SwitchProps, 'checked' | 'name' | 'onChange' | 'value'> => {
+        return {
+            checked: allValues.length === values.length,
+            name,
+            onChange: () => setValues(allValues.length === values.length ? [] : allValues),
+            value: 'all',
+        };
+    }, [allValues, values.length, name, setValues]);
+
+    return { toggleValue, allSwitchProps, switchProps, values, setValues };
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useTimeout.ts

@@ -0,0 +1,45 @@
+import { useRef, useEffect, useMemo } from 'react';
+
+/**
+ * A hook that creates a timeout that is automatically cleared when the component is unmounted.
+ *
+ * @example
+ *     import { useTimeout } from '@bspk/ui/hooks/useTimeout';
+ *     import { useEffect } from 'react';
+ *
+ *     function MyComponent() {
+ *     const timeoutRef = useTimeout();
+ *
+ *     useEffect(() => {
+ *     timeoutRef.current = setTimeout(() => {
+ *     console.log('Timeout triggered');
+ *     }, 1000);
+ *     }, []);
+ *     return <div>Check the console after 1 second</div>;
+ *     }
+ *
+ * @returns A ref object that can be used to store a timeout id.
+ */
+export function useTimeout() {
+    const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    useEffect(() => {
+        if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    }, []);
+
+    return useMemo(
+        () => ({
+            clear: () => {
+                if (timeoutRef.current) clearTimeout(timeoutRef.current);
+            },
+            set: (callback: () => void, durationMs: number) => {
+                if (timeoutRef.current) clearTimeout(timeoutRef.current);
+                timeoutRef.current = setTimeout(callback, durationMs);
+            },
+            ref: timeoutRef,
+        }),
+        [],
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useValidChildren.ts

@@ -0,0 +1,54 @@
+import { ReactNode, useMemo } from 'react';
+
+import { getChildrenElements } from '../utils/children';
+import { useErrorLogger } from '../utils/errors';
+
+const VALID_CHILDREN = ['Icon', 'string'];
+
+export function useValidChildren(
+    componentNme: string,
+    children: ReactNode,
+    ariaLabel: string | undefined,
+    override?: boolean,
+): {
+    icon?: ReactNode | undefined;
+    label?: ReactNode | undefined;
+} {
+    const { logError } = useErrorLogger();
+
+    return useMemo(() => {
+        if (override) return { icon: undefined, label: undefined };
+
+        let icon: ReactNode | undefined;
+        let label: ReactNode;
+
+        const childrenArray = getChildrenElements(children);
+
+        logError(
+            childrenArray.length > 2,
+            `${componentNme} - component only accepts two children, ${childrenArray.length} were provided`,
+        );
+
+        childrenArray.forEach(({ child, name }) => {
+            const valid = VALID_CHILDREN.includes(name);
+
+            logError(!valid, `${componentNme} -  component only accepts two children, and Icon and string`);
+
+            if (valid) {
+                if (name === 'string') label = child;
+                if (name === 'Icon') icon = child;
+            }
+        });
+
+        logError(!icon && !label, `${componentNme} - component requires at least one child, an icon or a label`);
+
+        logError(
+            !!icon && !label && !ariaLabel,
+            `${componentNme} - component requires the aria-label property when only an icon is provided`,
+        );
+
+        return { icon, label };
+    }, [override, children, logError, componentNme, ariaLabel]);
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */