@bspk/ui 1.1.34 → 1.3.0

package/src/components/UIProvider/UIProviderExample.tsx

@@ -0,0 +1,146 @@
+import { UIProviderProps } from '.';
+import { Button } from '-/components/Button';
+import { useUIContext } from '-/hooks/useUIContext';
+import { ComponentExample, Preset } from '-/utils/demo';
+
+export const presets: Preset<UIProviderProps>[] = [];
+
+export const UIProviderExample: ComponentExample<UIProviderProps> = {
+    containerStyle: { width: '100%' },
+    defaultState: {},
+    disableProps: [],
+    presets,
+    sections: [
+        {
+            title: 'Theme Switching',
+            content: ({ Syntax }) => (
+                <div style={{}}>
+                    <Syntax
+                        code={`// Example usage of theme switching
+import { useContext } from 'react';
+import { useUIContext } from '-/hooks/useUIContext';
+
+export function ThemeSwitcher() {
+    const {theme, setTheme} = useUIContext();
+
+    return (
+        <div>
+            <p>Current theme: {theme}</p>
+            <button onClick={() => setTheme('light')}>Light Theme</button>
+            <button onClick={() => setTheme('dark')}>Dark Theme</button>
+        </div>
+    );
+}`}
+                        language="typescript"
+                    />
+                </div>
+            ),
+        },
+        {
+            title: 'Responsive Helpers',
+            content: ({ Syntax }) => (
+                <div style={{}}>
+                    <Syntax
+                        code={`// Example usage of isMobile, isTablet, and isDesktop
+import { useContext } from 'react';
+import { useUIContext } from '-/hooks/useUIContext';
+
+export function ResponsiveComponent() {
+    const {isMobile, isTablet, isDesktop} = useUIContext();
+
+    return (
+        <div>
+            {isMobile && <p>This is a mobile device.</p>}
+            {isTablet && <p>This is a tablet device.</p>}
+            {isDesktop && <p>This is a desktop device.</p>}
+        </div>
+    );
+}`}
+                        language="typescript"
+                    />
+                </div>
+            ),
+        },
+        {
+            title: 'ARIA Live Messages',
+            content: ({ Syntax }) => (
+                <div style={{}}>
+                    <p>
+                        Example usage of sending ARIA live messages. This allows for dynamic updates to assistive
+                        technologies, such as screen readers.
+                    </p>
+                    <AriaLiveExample />
+                    <Syntax
+                        code={`// Example usage of sending ARIA live messages
+import { useContext } from 'react';
+import { useUIContext } from '-/hooks/useUIContext';
+
+export function AriaLiveExample() {
+    const {sendAriaLiveMessage} = useUIContext();
+
+    const handleClick = () => {
+        sendAriaLiveMessage('Action completed successfully', 'polite');
+    };
+
+    return (
+        <div>
+            <button onClick={handleClick}>Perform Action</button>
+        </div>
+    );
+}`}
+                        language="typescript"
+                    />
+                </div>
+            ),
+        },
+    ],
+    variants: {},
+};
+
+export function AriaLiveExample() {
+    const { sendAriaLiveMessage } = useUIContext();
+
+    return (
+        <p>
+            <Button
+                data-bspk="link"
+                label="Send a polite ARIA Live Message "
+                onClick={() => {
+                    sendAriaLiveMessage?.(
+                        `Action completed successfully at ${new Date().toLocaleTimeString()}`,
+                        'polite',
+                    );
+                }}
+                style={{
+                    padding: 0,
+                    margin: 0,
+                    border: 'none',
+                    background: 'none',
+                    color: 'inherit',
+                    cursor: 'pointer',
+                }}
+                variant="tertiary"
+            />
+
+            <Button
+                data-bspk="link"
+                label="Send an assertive ARIA Live Message "
+                onClick={() => {
+                    sendAriaLiveMessage?.(
+                        `Critical update occurred at ${new Date().toLocaleTimeString()}`,
+                        'assertive',
+                    );
+                }}
+                style={{
+                    padding: 0,
+                    margin: 0,
+                    border: 'none',
+                    background: 'none',
+                    color: 'inherit',
+                    cursor: 'pointer',
+                }}
+                variant="tertiary"
+            />
+        </p>
+    );
+}

package/src/constants/brands.ts

@@ -0,0 +1,45 @@
+import { Brand } from '-/types/common';
+
+export const BRANDS: {
+    /** The title of the brand. */
+    title: string;
+    /** The slug of the brand, used in URLs and identifiers. */
+    slug: Brand;
+}[] = [
+    {
+        title: 'Anywhere',
+        slug: 'anywhere',
+    },
+    {
+        title: 'Better Homes & Gardens',
+        slug: 'better-homes-gardens',
+    },
+    {
+        title: 'Cartus',
+        slug: 'cartus',
+    },
+    {
+        title: 'Century 21',
+        slug: 'century-21',
+    },
+    {
+        title: 'Coldwell Banker',
+        slug: 'coldwell-banker',
+    },
+    {
+        title: 'Corcoran',
+        slug: 'corcoran',
+    },
+    {
+        title: 'Denali Boss',
+        slug: 'denali-boss',
+    },
+    {
+        title: 'ERA',
+        slug: 'era',
+    },
+    {
+        title: "Sotheby's",
+        slug: 'sothebys',
+    },
+] as const;

package/src/constants/phases.ts

@@ -0,0 +1,10 @@
+import { ComponentPhase } from '-/types/meta';
+import { ColorVariant } from '-/utils/colorVariants';
+
+export const COMPONENT_PHASE_COLORS: Record<ComponentPhase, ColorVariant> = {
+    Backlog: 'grey',
+    Dev: 'blue',
+    UXReview: 'purple',
+    Stable: 'green',
+    Utility: 'magenta',
+};

package/src/global.d.ts

@@ -0,0 +1,3 @@
+declare module '*.css';
+
+declare module '*.scss';

package/src/hooks/useAddEventListener.ts

@@ -2,13 +2,15 @@ import { useRef } from 'react';
 
 import { useIsomorphicEffect } from './useIsomorphicEffect';
 
+export type CustomEventName = 'aria-live';
+
 export function useEventListener<
     KW extends keyof WindowEventMap,
     KH extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
     KM extends keyof MediaQueryListEventMap,
     T extends Document | HTMLElement | MediaQueryList | SVGAElement | Window = HTMLElement,
 >(
-    eventName: KH | KM | KW,
+    eventName: CustomEventName | KH | KM | KW,
     handler: (
         event:
             | Event

package/src/hooks/useArrowNavigation.ts

@@ -0,0 +1,107 @@
+import { useState, KeyboardEvent } from 'react';
+import { getElementById } from '-/utils/dom';
+import { KeysCallback } from '-/utils/handleKeyDown';
+import { KeyboardEventCode } from '-/utils/keyboard';
+
+type ArrowKeyNames = Extract<KeyboardEventCode, `Arrow${string}`>;
+
+const ARROW_KEYS: ArrowKeyNames[] = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'];
+
+export type ArrowKeyNavigationCallbackParams = {
+    key: ArrowKeyNames;
+    event: KeyboardEvent;
+    activeElementId: string | null;
+    increment: number;
+};
+
+type UseArrowNavigationProps = {
+    /**
+     * An array of string IDs representing the navigable elements. These IDs should correspond to the `id` attributes of
+     * the elements in the DOM. Ensure the elements are not disabled.
+     */
+    ids: string[];
+    /**
+     * An optional callback function that is invoked when an arrow key is pressed. This function receives the key name,
+     * the keyboard event, and the next active element ID. If the function returns `true`, the default navigation
+     * behavior is prevented; if it returns `false` or is not provided, the default behavior proceeds.
+     */
+    callback?: (params: ArrowKeyNavigationCallbackParams) => boolean;
+    /** Optional configuration to set navigation direction increments. */
+    increments?: Record<ArrowKeyNames, number>;
+    /**
+     * The ID of the element that should be active by default. If not provided, the first ID in the `ids` array will be
+     * used.
+     */
+    defaultActiveId?: string | null;
+};
+
+/**
+ * A hook to manage arrow key navigation for a list of elements.
+ *
+ * @example
+ *     ```tsx
+ *     const { activeElementId, setActiveElementId, arrowKeyCallbacks } = useArrowNavigation(['id1', 'id2', 'id3']);
+ *     ```;
+ *
+ * @returns An object containing:
+ *
+ *   - `activeElementId`: The ID of the currently active element.
+ *   - `setActiveElementId`: A function to manually set the active element ID.
+ *   - `arrowKeyCallbacks`: An object with callback functions for arrow key navigation.
+ */
+export function useArrowNavigation({
+    ids = [],
+    callback,
+    increments = {
+        ArrowLeft: -1,
+        ArrowRight: 1,
+        ArrowUp: -1,
+        ArrowDown: 1,
+    },
+    defaultActiveId,
+}: UseArrowNavigationProps): {
+    activeElementId: string | null;
+    setActiveElementId: (id: string | null) => void;
+    arrowKeyCallbacks: KeysCallback;
+} {
+    const [activeElementId, setActiveElementIdBase] = useState<string | null>(defaultActiveId || null);
+
+    const setActiveElementId = (id: string | null) => {
+        setActiveElementIdBase(id);
+        getElementById(id)?.scrollIntoView({
+            block: 'nearest',
+            behavior: 'smooth',
+            inline: 'nearest',
+        });
+    };
+
+    return {
+        activeElementId,
+        setActiveElementId,
+        arrowKeyCallbacks: Object.fromEntries(
+            ARROW_KEYS.map((key) => [
+                key,
+                (event: KeyboardEvent) => {
+                    let nextIndex = 0;
+                    let currentIndex = 0;
+                    let nextId = ids[nextIndex];
+                    const increment = increments[key];
+
+                    if (activeElementId) {
+                        currentIndex = ids.indexOf(activeElementId);
+                        nextIndex = (currentIndex + increment + ids.length) % ids.length;
+                        nextId = ids[nextIndex];
+                    }
+
+                    if (
+                        typeof callback === 'function' &&
+                        callback({ key, event, activeElementId: nextId, increment }) === false
+                    )
+                        return;
+                    event.preventDefault();
+                    setActiveElementId(nextId);
+                },
+            ]),
+        ) as KeysCallback,
+    };
+}

package/src/hooks/useContainerWidth.tsx

@@ -0,0 +1,37 @@
+import { useState, useLayoutEffect } from 'react';
+/**
+ * A hook to get the width of a container element.
+ *
+ * @example
+ *     import { useRef } from 'react';
+ *     import { useContainerWidth } from '@bspk/ui/hooks/useContainerWidth';
+ *     export function Example() {
+ *         const containerRef = useRef<HTMLDivElement>(null);
+ *         const width = useContainerWidth(containerRef);
+ *         return <div ref={containerRef}>Width: {width}px</div>;
+ *     }
+ *
+ * @param ref - A ref to a container element.
+ * @returns The width of the container element.
+ */
+export function useContainerWidth(ref: React.RefObject<HTMLDivElement>) {
+    const [width, setWidth] = useState(0);
+
+    useLayoutEffect(() => {
+        if (!ref.current) return;
+        setWidth(ref.current.offsetWidth);
+
+        const observer = new window.ResizeObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.target === ref.current) {
+                    setWidth(entry.contentRect.width);
+                }
+            }
+        });
+        observer.observe(ref.current);
+
+        return () => observer.disconnect();
+    }, [ref]);
+
+    return width;
+}

package/src/hooks/useFloating.ts

@@ -65,19 +65,17 @@ export type UseFloatingProps = {
     /**
      * When set to true, the width of the floating element will match the width of the reference element.
      *
-     * When set to an HTMLElement, the width of the floating element will match the width of that HTMLElement.
-     *
-     * @default true
+     * @default false
      */
-    refWidth?: HTMLElement | boolean;
+    refWidth?: boolean;
     /** Whether to hide the floating element. */
     hide?: boolean;
 };
 
-export type UseFloatingElements<ReferenceElementType extends HTMLElement = HTMLElement> = {
-    reference: ReferenceElementType | null;
+export type UseFloatingElements = {
+    reference: HTMLElement | null;
     floating: HTMLElement | null;
-    setReference: (element: ReferenceElementType | null) => void;
+    setReference: (element: HTMLElement | null) => void;
     setFloating: (element: HTMLElement | null) => void;
 };
 
@@ -87,17 +85,18 @@ export type UseFloatingElements<ReferenceElementType extends HTMLElement = HTMLE
  * @param param0
  * @returns
  */
-export function useFloating<ReferenceElementType extends HTMLElement = HTMLElement>({
+export function useFloating({
     placement = 'bottom-start',
     arrowRef,
     strategy = 'fixed',
     offsetOptions = 0,
-    refWidth = true,
+    refWidth = false,
     hide = false,
 }: UseFloatingProps): {
-    elements: UseFloatingElements<ReferenceElementType>;
+    elements: UseFloatingElements;
     floatingStyles: React.CSSProperties;
     middlewareData: MiddlewareData;
+    currentPlacement: Placement | undefined;
 } {
     const [floatingStyles, setFloatingStylesState] = useState<React.CSSProperties>({
         opacity: 0,
@@ -114,7 +113,7 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
 
     const [middlewareData, setMiddlewareData] = useState<MiddlewareData>({});
 
-    const [referenceElement, setReferenceElement] = useState<ReferenceElementType | null>(null);
+    const [referenceElement, setReferenceElement] = useState<HTMLElement | null>(null);
 
     const [floatingElement, setFloatingElement] = useState<HTMLElement | null>(null);
 
@@ -125,6 +124,8 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
         computeDebounce.clear();
         transitionDelay.clear();
 
+        // console.log('compute', { referenceElement, floatingElement });
+
         // check if the reference or floating element is null
         if (referenceElement === null || floatingElement === null) return;
 
@@ -132,7 +133,6 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
             if (floatingElement?.style.top)
                 setFloatingStyles((prev) => ({
                     ...prev,
-                    display: undefined,
                     opacity: 0,
                     pointerEvents: 'none',
                 }));
@@ -140,7 +140,6 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
             transitionDelay.set(() => {
                 setFloatingStyles((prev) => ({
                     ...prev,
-                    display: 'none',
                 }));
             }, TRANSITION_DELAY);
             return;
@@ -159,15 +158,13 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
                     arrowRef?.current && arrow({ element: arrowRef.current, padding: 8 }),
                     offset(offsetOptions),
                     flip(),
-                    refWidth &&
-                        size({
-                            apply({ rects, elements }: MiddlewareState) {
-                                Object.assign(elements.floating.style, {
-                                    width:
-                                        refWidth === true ? `${rects.reference.width}px` : `${refWidth.offsetWidth}px`,
-                                });
-                            },
-                        }),
+                    size({
+                        apply({ rects, elements }: MiddlewareState) {
+                            Object.assign(elements.floating.style, {
+                                width: refWidth ? `${rects.reference.width}px` : undefined,
+                            });
+                        },
+                    }),
                 ],
             }).then((value: ComputePositionReturn) => {
                 setFloatingStyles(() => ({
@@ -206,6 +203,7 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
 
     useEffect(() => {
         compute();
+
         return () => {
             computeDebounce.clear();
             transitionDelay.clear();
@@ -231,6 +229,7 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
         },
         floatingStyles,
         middlewareData,
+        currentPlacement: middlewareData?.offset?.placement,
     };
 }
 

package/src/hooks/useId.ts

@@ -1,4 +1,5 @@
-import { useId as useIdReact } from 'react';
+import { useMemo } from 'react';
+import { randomString } from '-/utils/random';
 
 /**
  * A utility hook that generates a unique id for an element. If a default id is provided, it will use that instead.
@@ -7,8 +8,9 @@ import { useId as useIdReact } from 'react';
  * @returns {string}
  */
 export function useId(defaultId?: string | null): string {
-    const generatedId = useIdReact();
-    return defaultId || generatedId;
+    return useMemo(() => {
+        return defaultId || randomString(8);
+    }, [defaultId]);
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useLongPress.ts

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react';
+import { useRef, useState, MouseEvent } from 'react';
 
 import { useTimeout } from './useTimeout';
 
@@ -38,7 +38,8 @@ export function useLongPress(callback: () => void, disabled: boolean) {
     };
 
     return {
-        onMouseDown: () => {
+        onMouseDown: (event: MouseEvent) => {
+            event.preventDefault();
             intervalRef.current = INITIAL_INTERVAL;
             callback();
             timeout.set(run, intervalRef.current);

package/src/hooks/useOutsideClick.ts

@@ -29,11 +29,15 @@ import { useEffect } from 'react';
  * @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)[] | null,
-    callback: (event?: MouseEvent) => void,
-    disabled?: boolean,
-) {
+export function useOutsideClick({
+    elements,
+    callback,
+    disabled,
+}: {
+    elements: (HTMLElement | null)[] | null;
+    callback: (event?: MouseEvent) => void;
+    disabled?: boolean;
+}) {
     useEffect(() => {
         if (!elements?.length || disabled) return;
 

package/src/hooks/usePaginationState.tsx

@@ -0,0 +1,24 @@
+import { useState } from 'react';
+
+/*
+    * A hook to manage the state of pagination.
+
+    * @param numPages - The total number of pages.
+    * @param initialPage - The initial page to start on (default is 1).
+    * @returns An object containing the current page and a function to set the current page.
+    */
+export const usePaginationState = (numPages: number, initialPage?: number) => {
+    const [currentPage, setCurrentPage] = useState(initialPage || 1);
+
+    const setPage = (page: number) => {
+        if (page < 1 || page > numPages) {
+            return;
+        }
+        setCurrentPage(page);
+    };
+
+    return {
+        currentPage,
+        setCurrentPage: setPage,
+    };
+};

package/src/hooks/useSnackbarContext.ts

@@ -0,0 +1,18 @@
+/* eslint-disable no-console */
+import { useContext } from 'react';
+import { SnackbarContext } from '-/utils/snackbarContext';
+
+export const useSnackbarContext = () => {
+    const context = useContext(SnackbarContext);
+    if (!context) {
+        console.error('useSnackbarContext must be used within a SnackbarProvider!');
+    }
+    return (
+        context ?? {
+            snackbars: [],
+            sendSnackbar: () => console.error('sendSnackbar must be used within a SnackbarProvider!'),
+            clearSnackbar: () => console.error('clearSnackbar must be used within a SnackbarProvider!'),
+            clearAll: () => console.error('clearAll must be used within a SnackbarProvider!'),
+        }
+    );
+};

package/src/hooks/useSwipe.ts

@@ -0,0 +1,32 @@
+import { TouchEventHandler, useRef } from 'react';
+
+const MIN_SWIPE_DISTANCE = 50; // Minimum distance for a swipe to be recognized
+
+export function useSwipe(onSwipeLeft: () => void, onSwipeRight: () => void) {
+    const touchStart = useRef<number | null>(null);
+    const touchEnd = useRef<number | null>(null);
+
+    const onTouchStart: TouchEventHandler = (e) => {
+        touchEnd.current = null;
+        touchStart.current = e.targetTouches[0].clientX;
+    };
+
+    const onTouchMove: TouchEventHandler = (e) => {
+        touchEnd.current = e.targetTouches[0].clientX;
+    };
+
+    const onTouchEnd: TouchEventHandler = () => {
+        if (!touchStart.current || !touchEnd.current) return;
+        const distance = touchStart.current - touchEnd.current;
+        const isLeftSwipe = distance > MIN_SWIPE_DISTANCE;
+        const isRightSwipe = distance < -MIN_SWIPE_DISTANCE;
+
+        if (isLeftSwipe) {
+            onSwipeLeft();
+        } else if (isRightSwipe) {
+            onSwipeRight();
+        }
+    };
+
+    return { onTouchStart, onTouchMove, onTouchEnd };
+}

package/src/hooks/useTimeout.ts

@@ -1,5 +1,11 @@
 import { useRef, useEffect, useMemo } from 'react';
 
+type TimeoutHook = {
+    clear: () => void;
+    set: (callback: () => void, ms?: number) => void;
+    ref: React.MutableRefObject<ReturnType<typeof setTimeout> | null>;
+};
+
 /**
  * A hook that creates a timeout that is automatically cleared when the component is unmounted.
  *
@@ -19,11 +25,15 @@ import { useRef, useEffect, useMemo } from 'react';
  *
  * @returns A ref object that can be used to store a timeout id.
  */
-export function useTimeout() {
+export function useTimeout(): TimeoutHook;
+export function useTimeout(initialCallback: () => void, durationMs: number): TimeoutHook;
+export function useTimeout(initialCallback?: () => void, durationMs = 1000): TimeoutHook {
     const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
     useEffect(() => {
         if (timeoutRef.current) clearTimeout(timeoutRef.current);
+        if (initialCallback) timeoutRef.current = setTimeout(initialCallback, durationMs);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- only run at mount
     }, []);
 
     return useMemo(
@@ -31,13 +41,13 @@ export function useTimeout() {
             clear: () => {
                 if (timeoutRef.current) clearTimeout(timeoutRef.current);
             },
-            set: (callback: () => void, durationMs: number) => {
+            set: (callback: () => void, ms = durationMs) => {
                 if (timeoutRef.current) clearTimeout(timeoutRef.current);
-                timeoutRef.current = setTimeout(callback, durationMs);
+                timeoutRef.current = setTimeout(callback, ms);
             },
             ref: timeoutRef,
         }),
-        [],
+        [durationMs],
     );
 }