@bspk/ui 1.1.34 → 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,34 +1,13 @@
-import { ReactNode, useMemo } from 'react';
-
-import { CommonProps, ElementProps, SetRef } from '-';
-import { Portal } from '-/components/Portal';
-import { Scrim } from '-/components/Scrim';
-import { useId } from '-/hooks/useId';
-import { cssWithVars } from '-/utils/cwv';
 import './menu.scss';
+import { ElementType, ReactNode } from 'react';
+import { useId } from '-/hooks/useId';
+import { CommonProps, ElementProps, SetRef } from '-/types/common';
 
 export function menuItemId(menuId: string, index: number) {
     return `menu-${menuId}-item-${index}`;
 }
 
-export const MIN_ITEM_COUNT = 3;
-export const MAX_ITEM_COUNT = 10;
-
-// returns the item count to display based on the items and the itemDisplayCount bounded by the MIN_ITEM_COUNT and MAX_ITEM_COUNT
-function boundCount(itemLength = 0, itemDisplayCount = 0) {
-    const minItemCount = Math.max(MIN_ITEM_COUNT, itemLength);
-    const maxItemCount = Math.min(MAX_ITEM_COUNT, itemLength);
-    return (
-        // Ensure we don't display less than the minimum item count
-        Math.min(
-            minItemCount,
-            // Ensure we don't display more items than available
-            Math.min(maxItemCount, itemDisplayCount),
-        )
-    );
-}
-
-export type MenuProps = CommonProps<'data-bspk-owner' | 'id'> & {
+export type MenuProps<As extends ElementType = ElementType> = CommonProps<'id' | 'owner' | 'role'> & {
     /** A ref to the inner div element. */
     innerRef?: SetRef<HTMLDivElement>;
     /**
@@ -38,37 +17,18 @@ export type MenuProps = CommonProps<'data-bspk-owner' | 'id'> & {
      */
     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.
+     * A label for the menu for screen readers.
      *
-     * - If set to `false`, the menu will not have a maximum height and will grow to fit its content.
-     * - If set to a number, the menu will display that many items before scrolling.
-     * - If not set or set to `undefined`, the menu will default to showing a minimum of 3 items and a maximum of 10
-     *   items.
+     * This is required if the role is set to "menu" or "listbox".
      */
-    itemDisplayCount?: number | false;
+    label?: string;
     /**
-     * The number of items in the menu.
+     * The element type to render as.
      *
-     * This is used to determine the maximum height of the menu when `itemDisplayCount` is set to a number.
-     *
-     * @required
-     */
-    itemCount?: number;
-    /**
-     * Whether the menu is rendered as a floating element.
-     *
-     * @default true
+     * @default div
+     * @type ElementType
      */
-    floating?: boolean;
-    /** A function that is called when the user clicks outside of the menu. */
-    onOutsideClick?: () => void;
+    as?: As;
 };
 
 /**
@@ -83,61 +43,32 @@ export type MenuProps = CommonProps<'data-bspk-owner' | 'id'> & {
  *         return (
  *             <Menu>
  *                 <ListItem label="List Item" />
+ *                 <ListItem label="List Item" />
+ *                 <ListItem label="List Item" />
  *             </Menu>
  *         );
  *     }
  *
  * @name Menu
- * @phase DesignReview
+ * @phase UXReview
  */
-function Menu({
-    //
-    innerRef,
-    id: idProp,
-    children,
-    portal = true,
-    itemDisplayCount: itemDisplayCountProp,
-    itemCount,
-    floating = true,
-    onOutsideClick,
-    ...props
-}: ElementProps<MenuProps, 'div'>) {
+export function Menu({ as, innerRef, id: idProp, children, owner, label, ...props }: ElementProps<MenuProps, 'div'>) {
     const menuId = useId(idProp);
 
-    const itemDisplayCount = useMemo(() => {
-        return itemDisplayCountProp && boundCount(itemCount, itemDisplayCountProp);
-    }, [itemCount, itemDisplayCountProp]);
+    const As = as || 'div';
 
-    const menu = (
-        <>
-            {floating && <Scrim data-bspk-owner="menu" onClick={() => onOutsideClick?.()} variant="dropdown" />}
-            <div
-                role="listbox"
-                {...props}
-                data-bspk="menu"
-                data-floating={floating || undefined}
-                id={menuId}
-                ref={innerRef}
-                style={cssWithVars({
-                    ...props.style,
-                    '--overflow-y':
-                        itemCount && itemDisplayCount && itemCount > itemDisplayCount ? 'scroll' : undefined,
-                    maxHeight:
-                        itemDisplayCount === false
-                            ? 'auto'
-                            : `calc(calc(${itemDisplayCount} * var(--list-item-height)) + 2px /* borders */)`,
-                })}
-            >
-                {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>{menu}</Portal> : menu;
 }
 
-Menu.bspkName = 'Menu';
-
-export { Menu };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Menu/MenuExample.tsx

@@ -7,28 +7,19 @@ import { SvgLogout } from '@bspk/icons/Logout';
 import { SvgMenuBook } from '@bspk/icons/MenuBook';
 import { SvgSettings } from '@bspk/icons/Settings';
 
+import { MenuProps } from '.';
 import { Avatar } from '-/components/Avatar';
 import { Divider } from '-/components/Divider';
 import { ListItem } from '-/components/ListItem';
 import { Switch } from '-/components/Switch';
 import { ComponentExampleFn } from '-/utils/demo';
 
-import { ElementProps } from '../..';
-
-import { MenuProps } from '.';
-
-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}
-                aria-label="Settings Menu"
-                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" />}
@@ -38,9 +29,9 @@ export const MenuExample: ComponentExampleFn<ElementProps<MenuProps, 'div'> & {
                 <ListItem href="#/my-profile" label="My profile" leading={<SvgAccountCircle />} />
                 <ListItem href="#/settings" label="Settings" leading={<SvgSettings />} />
                 <ListItem
+                    as="label"
                     label="Dark mode"
                     leading={props['data-dark-mode'] ? <SvgDarkModeFill /> : <SvgDarkMode />}
-                    role="checkbox"
                     trailing={
                         <Switch
                             aria-label="Toggle dark mode"
@@ -64,9 +55,10 @@ export const MenuExample: ComponentExampleFn<ElementProps<MenuProps, 'div'> & {
                     onClick={() => {
                         action('Log out clicked');
                     }}
+                    role="button"
                 />
             </Component>
         );
     },
-    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;
@@ -6,20 +6,12 @@
     border: 1px solid var(--stroke-neutral-low);
     background-color: var(--surface-neutral-t1-base);
     box-shadow: var(--drop-shadow-float);
-    border-radius: var(--radius-large);
+    border-radius: var(--radius-lg);
     display: flex;
     flex-direction: column;
-    overflow: hidden var(--overflow-y);
-
-    &[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,8 +1,7 @@
+import './menu-button.scss';
 import { SvgMenu } from '@bspk/icons/Menu';
-
-import { ElementProps } from '-';
 import { ButtonProps } from '-/components/Button';
-import './menu-button.scss';
+import { ElementProps } from '-/types/common';
 
 export type MenuButtonProps = Pick<ButtonProps, 'as' | 'onClick'>;
 
@@ -19,7 +18,7 @@ export type MenuButtonProps = Pick<ButtonProps, 'as' | 'onClick'>;
  * @name MenuButton
  * @phase Utility
  */
-function MenuButton(props: ElementProps<MenuButtonProps, 'button'>) {
+export function MenuButton(props: ElementProps<MenuButtonProps, 'button'>) {
     return (
         <button data-bspk="menu-button" {...props}>
             <SvgMenu />
@@ -27,8 +26,4 @@ function MenuButton(props: ElementProps<MenuButtonProps, 'button'>) {
     );
 }
 
-MenuButton.bspkName = 'MenuButton';
-
-export { MenuButton };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */