@bspk/ui 1.2.0 → 1.3.1

package/src/components/Truncated/Truncated.rtl.test.tsx

@@ -0,0 +1,15 @@
+import { Truncated } from './Truncated';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <Truncated>Example content</Truncated>;
+
+describe('Truncated (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example content')).toBeInTheDocument();
+    });
+});

package/src/components/Truncated/Truncated.tsx

@@ -1,5 +1,5 @@
+import './truncated.scss';
 import { ElementType } from 'react';
-
 import { Tooltip, TooltipTriggerProps } from '-/components/Tooltip';
 import { useTruncatedText } from '-/hooks/useTruncatedText';
 import { ElementConstructorProps } from '-/types/common';
@@ -47,15 +47,8 @@ export function Truncated<As extends ElementType = 'span'>({
             {...props}
             data-bspk-utility="truncated"
             ref={(node) => setElement(node)}
-            style={{
-                maxWidth: '100%',
-                ...props.style,
-                display: 'inline-block',
-                overflow: 'hidden',
-                textOverflow: 'ellipsis',
-                whiteSpace: 'nowrap',
-            }}
             {...triggerProps}
+            role={isTruncated ? 'note' : props.role}
         >
             {children}
         </span>

package/src/components/Truncated/truncated.scss

@@ -0,0 +1,8 @@
+[data-bspk-utility='truncated'] {
+    max-width: 100%;
+    display: inline-block;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    background-color: transparent;
+}

package/src/components/Txt/Txt.rtl.test.tsx

@@ -0,0 +1,15 @@
+import { Txt } from './Txt';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <Txt>Example content</Txt>;
+
+describe('Txt (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example content')).toBeInTheDocument();
+    });
+});

package/src/components/UIProvider/AriaLiveMessageHandler.tsx

@@ -0,0 +1,44 @@
+import { useState } from 'react';
+import { useEventListener } from '-/hooks/useAddEventListener';
+import { useTimeout } from '-/hooks/useTimeout';
+import { AriaLiveMessage } from '-/utils/uiContext';
+
+export function sendAriaLiveMessage(message: string, live: 'assertive' | 'polite' = 'polite') {
+    document.dispatchEvent(new CustomEvent('aria-live', { detail: { message, live } }));
+}
+
+/**
+ * AriaLiveMessageHandler is a single use component that listens for aria-live messages and displays them to the user.
+ *
+ * We use a custom event to communicate between components and this handler.
+ *
+ * We don't store the message in context to avoid unnecessary re-renders of all components that consume the context. :)
+ *
+ * We queue messages to ensure that they are read by screen readers.
+ *
+ * After the message is read, we clear it after a short delay to allow for subsequent messages to be read.
+ */
+export function AriaLiveMessageHandler() {
+    const [ariaLiveMessage, setAriaLiveMessage] = useState<AriaLiveMessage | undefined>(undefined);
+
+    const timeout = useTimeout();
+
+    useEventListener(
+        'aria-live',
+        (event: CustomEvent) => {
+            const { message, live } = event.detail;
+            // Clear any existing message to ensure that screen readers read the new message
+            setAriaLiveMessage(undefined);
+            timeout.set(() => setAriaLiveMessage({ message, live: live || 'polite' }), 10);
+        },
+        document,
+    );
+
+    return (
+        ariaLiveMessage && (
+            <div aria-live={ariaLiveMessage?.live || 'polite'} data-sr-only role="alert">
+                {ariaLiveMessage?.message}
+            </div>
+        )
+    );
+}

package/src/components/UIProvider/UIProvider.tsx

@@ -1,21 +1,33 @@
 import { useState, ReactNode } from 'react';
-
+import { AriaLiveMessageHandler, sendAriaLiveMessage } from './AriaLiveMessageHandler';
 import { useEventListener } from '-/hooks/useAddEventListener';
 import { useDebounceState } from '-/hooks/useDebounceState';
 import { useIsomorphicEffect } from '-/hooks/useIsomorphicEffect';
 import { UIContext, ColorTheme } from '-/utils/uiContext';
 
 export type UIProviderProps = {
+    /**
+     * The children elements that will have access to the UI context.
+     *
+     * @required
+     */
     children: ReactNode;
 };
 
 /**
- * UIProvider is a React context provider that manages the UI state, including theme and responsive state.
+ * UIProvider is a React context provider that manages the UI state.
+ *
+ * UI state includes, theme, setTheme, responsive state, aria live messages
+ *
+ * This provider should wrap the root of your application to ensure that all components have access to the UI context.
  *
  * @name UIProvider
+ *
+ * @phase Utility
  */
 export function UIProvider({ children }: UIProviderProps) {
     const [theme, setTheme] = useState<ColorTheme>('light');
+    // Keep track of device width to determine if we are in mobile, tablet, or desktop mode
 
     const [deviceWidth, setDeviceWidth] = useDebounceState(() => {
         return typeof window !== 'undefined' ? window.innerWidth : 0;
@@ -40,9 +52,11 @@ export function UIProvider({ children }: UIProviderProps) {
                 isMobile: deviceWidth < 640,
                 isTablet: deviceWidth > 640 && deviceWidth < 1024,
                 isDesktop: deviceWidth >= 1024,
+                sendAriaLiveMessage,
             }}
         >
             {children}
+            <AriaLiveMessageHandler />
         </UIContext.Provider>
     );
 }

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/phases.ts

@@ -4,7 +4,6 @@ import { ColorVariant } from '-/utils/colorVariants';
 export const COMPONENT_PHASE_COLORS: Record<ComponentPhase, ColorVariant> = {
     Backlog: 'grey',
     Dev: 'blue',
-    QA: 'yellow',
     UXReview: 'purple',
     Stable: 'green',
     Utility: 'magenta',

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,17 +65,17 @@ export type UseFloatingProps = {
     /**
      * When set to true, the width of the floating element will match the width of the reference element.
      *
-     * @default true
+     * @default false
      */
     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;
 };
 
@@ -85,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,
@@ -112,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);
 
@@ -123,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;
 
@@ -130,7 +133,6 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
             if (floatingElement?.style.top)
                 setFloatingStyles((prev) => ({
                     ...prev,
-                    display: undefined,
                     opacity: 0,
                     pointerEvents: 'none',
                 }));
@@ -138,7 +140,6 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
             transitionDelay.set(() => {
                 setFloatingStyles((prev) => ({
                     ...prev,
-                    display: 'none',
                 }));
             }, TRANSITION_DELAY);
             return;
@@ -157,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) {
-                                if (refWidth)
-                                    Object.assign(elements.floating.style, {
-                                        width: `${rects.reference.width}px`,
-                                    });
-                            },
-                        }),
+                    size({
+                        apply({ rects, elements }: MiddlewareState) {
+                            Object.assign(elements.floating.style, {
+                                width: refWidth ? `${rects.reference.width}px` : undefined,
+                            });
+                        },
+                    }),
                 ],
             }).then((value: ComputePositionReturn) => {
                 setFloatingStyles(() => ({
@@ -204,6 +203,7 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
 
     useEffect(() => {
         compute();
+
         return () => {
             computeDebounce.clear();
             transitionDelay.clear();
@@ -229,6 +229,7 @@ export function useFloating<ReferenceElementType extends HTMLElement = HTMLEleme
         },
         floatingStyles,
         middlewareData,
+        currentPlacement: middlewareData?.offset?.placement,
     };
 }
 

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/rtl/hasNoBasicA11yIssues.tsx

@@ -0,0 +1,27 @@
+import { axe } from 'jest-axe';
+import { ReactElement } from 'react';
+import { render, waitFor } from '-/rtl/util';
+
+/**
+ * A utility function to test for basic accessibility issues using jest-axe.
+ *
+ * @example
+ *     import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+ *     import { MyComponent } from './MyComponent';
+ *
+ *     const TestBed = () => <MyComponent />;
+ *
+ *     describe('MyComponent', () => {
+ *         it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+ *     });
+ *
+ * @param TestBed - A React element representing the component to be tested.
+ * @returns An async function that performs the accessibility test.
+ */
+export const hasNoBasicA11yIssues = (TestBed: ReactElement) => {
+    return async () => {
+        const { container } = render(TestBed);
+        await waitFor(() => expect(container).toBeInTheDocument());
+        expect(await axe(container)).toHaveNoViolations();
+    };
+};