@bspk/ui 1.2.0 → 1.3.0

package/src/components/ListItemMenu/ListItemMenu.tsx

@@ -0,0 +1,358 @@
+import {
+    AriaAttributes,
+    CSSProperties,
+    HTMLAttributes,
+    ReactNode,
+    useState,
+    KeyboardEvent,
+    MouseEvent,
+    Dispatch,
+    SetStateAction,
+    useMemo,
+} from 'react';
+import { ListItem, ListItemProps } from '-/components/ListItem';
+import { Menu, MenuProps } from '-/components/Menu';
+import { ArrowKeyNavigationCallbackParams, useArrowNavigation } from '-/hooks/useArrowNavigation';
+import { useFloating, UseFloatingProps } from '-/hooks/useFloating';
+import { useId } from '-/hooks/useId';
+import { useOutsideClick } from '-/hooks/useOutsideClick';
+import { CommonProps, SetRef } from '-/types/common';
+import { getElementById } from '-/utils/dom';
+import { handleKeyDown } from '-/utils/handleKeyDown';
+
+export type MenuListItem = Omit<ListItemProps, 'id'> & {
+    id: string;
+};
+
+export type ListItemMenuRole = keyof typeof LIST_ITEM_ROLES;
+
+const LIST_ITEM_ROLES = {
+    group: undefined,
+    listbox: 'option',
+    menu: 'menuitem',
+    tree: 'treeitem',
+} as const;
+
+/** Props for the toggle element that opens the ListItemMenu. */
+export type ToggleProps = Pick<
+    AriaAttributes,
+    | 'aria-activedescendant'
+    | 'aria-controls'
+    | 'aria-disabled'
+    | 'aria-errormessage'
+    | 'aria-expanded'
+    | 'aria-haspopup'
+    | 'aria-invalid'
+    | 'aria-owns'
+    | 'aria-readonly'
+> &
+    Pick<HTMLAttributes<HTMLElement>, 'role' | 'tabIndex'> & {
+        /** Event handler for the toggle element that change the menu state. */
+        onClick: (event: MouseEvent<HTMLElement>) => void;
+        /** Event handler for keydown events on the toggle element that change the menu state. */
+        onKeyDownCapture: (event: KeyboardEvent) => void;
+    };
+
+/** Props for internal toggle functionality provided to the children render prop. */
+export type InternalToggleProps = {
+    /**
+     * Sets a ref to the toggle element that opens the ListItemMenu.
+     *
+     * Used in determining the position of the floating menu.
+     *
+     * May also be used to set the menu width if `width="reference"` is provided in the ListItemMenu props.
+     */
+    setRef: SetRef<HTMLElement | null>;
+    /**
+     * Function to toggle the menu open or closed.
+     *
+     * If `force` is provided as a boolean, it will set the menu to that state (true = open, false = closed). If `force`
+     * is not provided, it will toggle the current state.
+     */
+    toggleMenu: (force?: boolean) => void;
+    /** The number of items in the menu. */
+    itemCount: number;
+    /** Whether or not the menu is currently open. */
+    show?: boolean;
+    /** The reference element the menu is anchored to. */
+    reference: HTMLElement | null;
+};
+
+export type ListItemMenuProps = CommonProps<'disabled' | 'readOnly'> &
+    Pick<MenuProps, 'id' | 'label' | 'owner'> &
+    Pick<UseFloatingProps, 'offsetOptions' | 'placement'> & {
+        /**
+         * The children to render inside the menu.
+         *
+         * @required
+         */
+        children: (toggleProps: ToggleProps, internal: InternalToggleProps) => ReactNode;
+        /**
+         * The element that the menu is anchored to.
+         *
+         * @default listbox
+         */
+        role?: ListItemMenuRole;
+        /**
+         * The width of the menu. If 'reference' is provided, the menu will match the width of the useFloating reference
+         * element.
+         *
+         * @default reference
+         */
+        width?: CSSProperties['width'] | 'reference';
+        /**
+         * The items to display in the menu as ListItems.
+         *
+         * If an item does not have an `id` property, one will be generated automatically.
+         *
+         * @required
+         */
+        items: MenuListItem[] | ((params: { show?: boolean }) => MenuListItem[]);
+        /**
+         * Content to display in the floating menu element before the ListItems.
+         *
+         * If provided `scrollLimit` will be ignored.
+         */
+        leading?: ReactNode;
+        /**
+         * Content to display in the floating menu element after the ListItems.
+         *
+         * If provided `scrollLimit` will be ignored.
+         */
+        trailing?: ReactNode;
+        /** The ID of the currently active element. */
+        activeElementId?: string | null;
+        /** Optional callback fired when an item is clicked/selected. */
+        itemOnClick?: (params: {
+            event: MouseEvent;
+            currentId: string;
+            show: boolean;
+            setShow: Dispatch<SetStateAction<boolean>>;
+        }) => void;
+        /**
+         * Optional callback fired when the arrow keys are used for navigation.
+         *
+         * If the callback returns `true`, the change is accepted; if it returns `false`, the change is ignored.
+         */
+        arrowKeyNavigationCallback?: (params: ArrowKeyNavigationCallbackParams) => boolean;
+        /** Optional callback fired when the menu is closed. */
+        onClose?: () => void;
+        /** The maximum number of items to show before scrolling is enabled. */
+        scrollLimit?: number;
+        /** Remove menu from dom when closed for performance and to prevent tabbing to hidden menu items. */
+        hideWhenClosed?: boolean;
+    };
+
+/**
+ * A floating list Item menu for displaying additional actions or options presented as ListItems in a Menu.
+ *
+ * Includes keyboard navigation and accessibility features.
+ *
+ * The menu is anchored to a reference element provided as a children function with params that include the necessary
+ * ARIA attributes and event handlers.
+ *
+ * @example
+ *     import { ListItemMenu } from '@bspk/ui/ListItemMenu';
+ *
+ *     function Example() {
+ *         return (
+ *             <ListItemMenu
+ *                 items={[{ id: '1', label: 'Item 1' }]}
+ *                 label="Example Menu"
+ *                 role="menu"
+ *                 scrollLimit={5}
+ *                 width="200px"
+ *             >
+ *                 {(toggleProps, { setRef, toggleMenu }) => (
+ *                     <button {...toggleProps} onClick={() => toggleMenu()} ref={setRef}>
+ *                         Toggle Menu
+ *                     </button>
+ *                 )}
+ *             </ListItemMenu>
+ *         );
+ *     }
+ *
+ * @name ListItemMenu
+ * @phase Utility
+ */
+export function ListItemMenu({
+    activeElementId: activeElementIdProp = null,
+    children,
+    disabled,
+    id: idProp,
+    items: itemsProp,
+    label,
+    leading: menuLeading,
+    offsetOptions = 4,
+    arrowKeyNavigationCallback,
+    itemOnClick,
+    owner,
+    placement = 'bottom',
+    readOnly,
+    role: containerRole = 'listbox',
+    scrollLimit,
+    trailing: menuTrailing,
+    width: menuWidth = 'reference',
+    onClose,
+    hideWhenClosed = false,
+    ...ariaProps
+}: ListItemMenuProps) {
+    const containerId = useId(idProp);
+
+    const [show, setShowBase] = useState(false);
+
+    const items = useMemo(() => (typeof itemsProp === 'function' ? itemsProp({ show }) : itemsProp), [itemsProp, show]);
+
+    const setShow = (next: boolean | ((prev: boolean) => boolean)) => {
+        if (disabled || readOnly) return;
+
+        setShowBase((prev) => {
+            if (prev && !next) {
+                // closing
+                onClose?.();
+            }
+
+            if (typeof next === 'function') return next(prev);
+            return next;
+        });
+    };
+
+    const { floatingStyles, elements, currentPlacement } = useFloating({
+        hide: !show,
+        offsetOptions,
+        placement,
+        refWidth: menuWidth === 'reference',
+        strategy: 'fixed',
+    });
+
+    useOutsideClick({
+        elements: [elements.floating as HTMLElement, elements.reference as HTMLElement],
+        callback: () => setShow(false),
+        disabled: !show,
+    });
+
+    const { activeElementId, setActiveElementId, arrowKeyCallbacks } = useArrowNavigation({
+        ids: items.flatMap((item) => (item.disabled ? [] : item.id)),
+        callback: (params) => {
+            if (!show) setShow(true);
+
+            if (typeof arrowKeyNavigationCallback === 'function' && arrowKeyNavigationCallback)
+                return arrowKeyNavigationCallback(params);
+            return true;
+        },
+    });
+
+    const tabEscape = () => {
+        setShow(false);
+        setActiveElementId(null);
+    };
+
+    const enterSpace = (event: KeyboardEvent) => {
+        event.preventDefault();
+        if (!show) {
+            setShow(true);
+            return;
+        }
+        getElementById(activeElementId)?.click();
+    };
+
+    return (
+        <>
+            {children(
+                {
+                    'aria-disabled': disabled || undefined,
+                    'aria-expanded': show,
+                    'aria-haspopup': show && containerRole !== 'group' ? containerRole : undefined,
+                    'aria-controls': containerId,
+                    'aria-readonly': readOnly || undefined,
+                    'aria-owns': containerId,
+
+                    'aria-activedescendant': show ? activeElementId || undefined : undefined,
+                    role: 'combobox',
+                    tabIndex: 0,
+                    onClick: (event) => {
+                        const nextShow = !show;
+                        setShow(nextShow);
+                        setActiveElementId(nextShow ? activeElementIdProp || items[0]?.id || null : null);
+                        event.preventDefault();
+                    },
+                    onKeyDownCapture: handleKeyDown({
+                        ...arrowKeyCallbacks,
+                        Enter: enterSpace,
+                        Space: enterSpace,
+                        Tab: tabEscape,
+                        Escape: tabEscape,
+                    }),
+                },
+                {
+                    setRef: elements.setReference,
+                    toggleMenu: () => setShow(true),
+                    itemCount: items.length,
+                    reference: elements.reference as HTMLElement | null,
+                },
+            )}
+            {(!hideWhenClosed || show) && (
+                <Menu
+                    {...ariaProps}
+                    aria-label={label}
+                    as="ul"
+                    data-placement={currentPlacement}
+                    data-scroll={!!scrollLimit && items.length > scrollLimit}
+                    id={containerId}
+                    innerRef={(node) => {
+                        elements.setFloating(node);
+                    }}
+                    owner={owner}
+                    role={containerRole}
+                    style={{
+                        width: menuWidth !== 'reference' ? menuWidth : undefined,
+                        ...floatingStyles,
+                        ...scrollLimitStyle(scrollLimit, items.length),
+                    }}
+                >
+                    {menuLeading}
+                    {items.map((item, index) => {
+                        return (
+                            <ListItem
+                                as="li"
+                                key={index}
+                                {...item}
+                                active={activeElementId === item.id || undefined}
+                                onClick={(event) => {
+                                    elements.reference?.focus();
+                                    setActiveElementId(item.id);
+                                    item?.onClick?.(event);
+                                    itemOnClick?.({ event, currentId: item.id, show, setShow });
+                                }}
+                                role={item.role || LIST_ITEM_ROLES[containerRole] || undefined}
+                                tabIndex={0}
+                            />
+                        );
+                    })}
+                    {menuTrailing}
+                </Menu>
+            )}
+        </>
+    );
+}
+
+const scrollLimitStyle = (scrollLimitProp: unknown, itemCount: unknown): CSSProperties => {
+    const scrollLimit = Number(scrollLimitProp);
+
+    // Check:
+    // 1. scrollLimit is valid
+    // 2. itemCount is a number
+    // 3. scrollLimit is less than itemCount
+    // If any of these fail, return undefined (no scrolling)
+    if (Number.isNaN(scrollLimit) || scrollLimit <= 0 || typeof itemCount !== 'number' || scrollLimit > itemCount)
+        return {};
+
+    return {
+        display: 'flex',
+        flexDirection: 'column',
+        maxHeight: `calc(var(--list-item-height) * ${scrollLimit})`,
+        overflow: 'hidden auto',
+    };
+};
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/ListItemMenu/index.tsx

@@ -0,0 +1 @@
+export * from './ListItemMenu';

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

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

package/src/components/Menu/Menu.tsx

@@ -1,68 +1,35 @@
-// import { ReactNode, useMemo, useRef } from 'react';
-import { ReactNode, useRef } from 'react';
-
-import { Portal, PortalProps } from '-/components/Portal';
+import './menu.scss';
+import { ElementType, ReactNode } from 'react';
 import { useId } from '-/hooks/useId';
-import { useOutsideClick } from '-/hooks/useOutsideClick';
 import { CommonProps, ElementProps, SetRef } from '-/types/common';
-import { cssWithVars } from '-/utils/cwv';
-
-import './menu.scss';
 
 export function menuItemId(menuId: string, index: number) {
     return `menu-${menuId}-item-${index}`;
 }
 
-export type MenuProps = CommonProps<'id' | 'owner'> &
-    Pick<PortalProps, 'container'> & {
-        /** A ref to the inner div element. */
-        innerRef?: SetRef<HTMLDivElement>;
-        /**
-         * The items to display in the menu. These should be ListItem and Divider components.
-         *
-         * @required
-         */
-        children: ReactNode;
-        /**
-         * Should the menu be rendered in a portal? This is useful for menus that need to be rendered outside of the
-         * normal DOM flow, such as dropdowns or modals.
-         *
-         * @default true
-         */
-        portal?: boolean;
-        /**
-         * The number of items to show in the menu. This is used to determine the height of the menu.
-         *
-         * @default 1
-         */
-        itemDisplayCount?: number;
-        /**
-         * The number of items in the menu.
-         *
-         * @default 1
-         */
-        itemCount?: number;
-        /**
-         * Whether the menu is rendered as a floating element.
-         *
-         * @default true
-         */
-        floating?: boolean;
-        /**
-         * A function that is called when the user clicks outside of the menu.
-         *
-         * @required
-         */
-        onOutsideClick: () => void;
-        /**
-         * Whether or not the menu is scrollable.
-         *
-         * Setting to false will override itemDisplayCount.
-         *
-         * @default true
-         */
-        scroll?: boolean;
-    };
+export type MenuProps<As extends ElementType = ElementType> = CommonProps<'id' | 'owner' | 'role'> & {
+    /** A ref to the inner div element. */
+    innerRef?: SetRef<HTMLDivElement>;
+    /**
+     * The items to display in the menu. These should be ListItem and Divider components.
+     *
+     * @required
+     */
+    children: ReactNode;
+    /**
+     * A label for the menu for screen readers.
+     *
+     * This is required if the role is set to "menu" or "listbox".
+     */
+    label?: string;
+    /**
+     * The element type to render as.
+     *
+     * @default div
+     * @type ElementType
+     */
+    as?: As;
+};
 
 /**
  * A container housing a simple list of options presented to the customer to select one option at a time.
@@ -74,7 +41,7 @@ export type MenuProps = CommonProps<'id' | 'owner'> &
  *
  *     export function Example() {
  *         return (
- *             <Menu scroll={false}>
+ *             <Menu>
  *                 <ListItem label="List Item" />
  *                 <ListItem label="List Item" />
  *                 <ListItem label="List Item" />
@@ -85,57 +52,23 @@ export type MenuProps = CommonProps<'id' | 'owner'> &
  * @name Menu
  * @phase UXReview
  */
-export function Menu({
-    //
-    innerRef,
-    id: idProp,
-    children,
-    portal = true,
-    itemDisplayCount = 1,
-    itemCount = 1,
-    floating = true,
-    onOutsideClick,
-    owner,
-    scroll = true,
-    container,
-    ...props
-}: ElementProps<MenuProps, 'div'>) {
+export function Menu({ as, innerRef, id: idProp, children, owner, label, ...props }: ElementProps<MenuProps, 'div'>) {
     const menuId = useId(idProp);
 
-    const menuElement = useRef(null as HTMLDivElement | null);
+    const As = as || 'div';
 
-    const scrollDefault = scroll === true && itemCount > itemDisplayCount;
-
-    useOutsideClick({
-        elements: [menuElement.current],
-        callback: () => onOutsideClick?.(),
-        disabled: !onOutsideClick,
-    });
-
-    const menu = (
-        <>
-            <div
-                {...props}
-                data-bspk="menu"
-                data-bspk-owner={owner || undefined}
-                data-floating={floating || undefined}
-                data-scroll={scroll || scrollDefault || undefined}
-                id={menuId}
-                ref={(node) => {
-                    innerRef?.(node);
-                    menuElement.current = node;
-                }}
-                style={cssWithVars({
-                    ...props.style,
-                    '--item-display-count': itemDisplayCount,
-                })}
-            >
-                {children}
-            </div>
-        </>
+    return (
+        <As
+            {...props}
+            aria-label={label || undefined}
+            data-bspk-owner={owner || undefined}
+            data-bspk-utility="menu"
+            id={menuId}
+            ref={innerRef}
+        >
+            {children}
+        </As>
     );
-
-    return portal ? <Portal container={container}>{menu}</Portal> : menu;
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Menu/MenuExample.tsx

@@ -12,20 +12,14 @@ import { Avatar } from '-/components/Avatar';
 import { Divider } from '-/components/Divider';
 import { ListItem } from '-/components/ListItem';
 import { Switch } from '-/components/Switch';
-import { ElementProps } from '-/types/common';
 import { ComponentExampleFn } from '-/utils/demo';
 
-export const MenuExample: ComponentExampleFn<ElementProps<MenuProps, 'div'> & { 'data-dark-mode': boolean }> = ({
+export const MenuExample: ComponentExampleFn<MenuProps & { style?: unknown; 'data-dark-mode'?: boolean }> = ({
     action,
 }) => ({
     render: ({ props, Component, setState }) => {
         return (
-            <Component
-                {...props}
-                floating={false}
-                portal={false}
-                style={{ padding: 'var(--spacing-sizing-02) var(--spacing-sizing-02)' }}
-            >
+            <Component {...props} style={{ padding: 'var(--spacing-sizing-02) var(--spacing-sizing-02)' }}>
                 <ListItem
                     label="Michael Scott"
                     leading={<Avatar image="/profile2.jpg" name="Michael Scott" />}
@@ -66,29 +60,5 @@ export const MenuExample: ComponentExampleFn<ElementProps<MenuProps, 'div'> & {
             </Component>
         );
     },
-    presets: [
-        {
-            label: 'Scroll = False',
-            propState: {
-                floating: false,
-                portal: false,
-                itemDisplayCount: 5,
-                itemCount: 11,
-                scroll: false,
-            },
-        },
-        {
-            label: 'Item Display Count',
-            propState: {
-                floating: false,
-                portal: false,
-                itemDisplayCount: 5,
-                itemCount: 11,
-                scroll: true,
-            },
-        },
-    ],
-
-    disableProps: ['floating', 'portal'],
     variants: false,
 });

package/src/components/Menu/menu.scss

@@ -1,4 +1,4 @@
-[data-bspk='menu'] {
+[data-bspk-utility='menu'] {
     --overflow-y: hidden;
 
     width: 332px;
@@ -9,21 +9,9 @@
     border-radius: var(--radius-lg);
     display: flex;
     flex-direction: column;
-
-    &[data-scroll='true'] {
-        overflow: hidden scroll;
-        max-height: calc(calc(var(--item-display-count, 1) * var(--list-item-height)) + 2px /* borders */);
-    }
-
-    &[data-floating] {
-        z-index: var(--z-index-dropdown);
-    }
-
-    [data-bspk='list-item'] {
-        &[data-selected] {
-            background-color: var(--surface-brand-primary-highlight);
-        }
-    }
+    overflow: hidden auto;
+    height: fit-content;
+    z-index: var(--z-index-dropdown);
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

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

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

package/src/components/MenuButton/MenuButton.tsx

@@ -1,10 +1,8 @@
+import './menu-button.scss';
 import { SvgMenu } from '@bspk/icons/Menu';
-
 import { ButtonProps } from '-/components/Button';
 import { ElementProps } from '-/types/common';
 
-import './menu-button.scss';
-
 export type MenuButtonProps = Pick<ButtonProps, 'as' | 'onClick'>;
 
 /**

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

@@ -0,0 +1,20 @@
+import { Modal } from './Modal';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <Modal description="Example description" disableFocusTrap header="Example header" onClose={() => {}} open>
+        Example Modal
+        <button type="button">Hello</button>
+    </Modal>
+);
+
+describe('Modal (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example Modal')).toBeInTheDocument();
+    });
+});