@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/dropdown/DropdownMenu.test.tsx

@@ -1,211 +0,0 @@
-import { DropdownMenu, type DropdownMenuItem, type DrowndownMenuButton } from './DropdownMenu';
-import { render, screen, userEvent, waitFor } from '../../test/renderers';
-
-type Item = { label: string };
-
-const ITEMS: Item[] = [{ label: 'A' }, { label: 'B' }, { label: 'C' }, { label: 'D' }];
-
-const CustomButton = ({ ...props }: DrowndownMenuButton) => {
-  return <button {...props}>Some Custom Text</button>;
-};
-
-const CustomItem = ({ label, ...props }: DropdownMenuItem<Item>) => {
-  return (
-    <a {...props} role="link">
-      {label}
-    </a>
-  );
-};
-
-describe('DropdownMenu Component', () => {
-  it('should render with no menu when unopened', () => {
-    render(<DropdownMenu items={ITEMS}></DropdownMenu>);
-
-    expect(screen.getByRole('button', { name: /menu/i })).toBeInTheDocument();
-    expect(() => screen.getByRole('menu')).toThrow();
-  });
-
-  it('should render with menu when opened', async () => {
-    render(<DropdownMenu items={ITEMS}></DropdownMenu>);
-
-    const user = userEvent.setup();
-
-    await user.click(screen.getByRole('button', { name: /menu/i }));
-
-    for (const item of ITEMS) {
-      expect(await screen.findByRole('menuitem', { name: item.label })).toBeInTheDocument();
-    }
-  });
-
-  it('should render with a custom item component', async () => {
-    render(<DropdownMenu items={ITEMS} itemRenderer={CustomItem}></DropdownMenu>);
-
-    const user = userEvent.setup();
-
-    await user.click(screen.getByRole('button', { name: /menu/i }));
-
-    for (const item of ITEMS) {
-      expect(await screen.findByRole('link', { name: item.label })).toBeInTheDocument();
-    }
-  });
-
-  it('should render with a custom button component', () => {
-    render(<DropdownMenu items={ITEMS} buttonRenderer={CustomButton}></DropdownMenu>);
-
-    expect(screen.getByRole('button', { name: /some custom text/i })).toBeInTheDocument();
-  });
-
-  it('should open the menu when button is clicked', async () => {
-    render(<DropdownMenu items={ITEMS} />);
-
-    const user = userEvent.setup();
-
-    const button = screen.getByRole('button', { name: /menu/i });
-
-    await user.click(button);
-
-    expect(await screen.findByRole('menu')).toBeInTheDocument();
-  });
-
-  it('should open the menu when Space or Enter is pressed', async () => {
-    render(<DropdownMenu items={ITEMS} />);
-
-    const user = userEvent.setup();
-
-    const button = screen.getByRole('button', { name: /menu/i });
-
-    button.focus();
-
-    await user.keyboard(' ');
-
-    expect(await screen.findByRole('menu')).toBeInTheDocument();
-
-    // pressing another key will close the menu but assuming the menu wasnt open already this would open it anyway
-    await user.keyboard('{Enter}');
-
-    await waitFor(() => expect(screen.queryByRole('menu')).not.toBeInTheDocument());
-  });
-
-  it('should close when Escape is pressed', async () => {
-    render(<DropdownMenu items={ITEMS} />);
-
-    const user = userEvent.setup();
-
-    const button = screen.getByRole('button', { name: /menu/i });
-
-    await user.click(button);
-
-    expect(await screen.findByRole('menu')).toBeInTheDocument();
-
-    await user.keyboard('{Escape}');
-
-    await waitFor(() => expect(screen.queryByRole('menu')).not.toBeInTheDocument());
-  });
-
-  it('should close when clicking outside', async () => {
-    render(
-      <>
-        <DropdownMenu items={ITEMS} />
-
-        <button>Outside</button>
-      </>,
-    );
-
-    const user = userEvent.setup();
-
-    const button = screen.getByRole('button', { name: /menu/i });
-
-    await user.click(button);
-
-    expect(await screen.findByRole('menu')).toBeInTheDocument();
-
-    // click away to another element, which should close the menu
-    await user.click(screen.getByRole('button', { name: /outside/i }));
-
-    await waitFor(() => expect(screen.queryByRole('menu')).not.toBeInTheDocument());
-  });
-
-  it('should close when focus moves outside (blur)', async () => {
-    render(
-      <>
-        <DropdownMenu items={ITEMS} />
-
-        <button>Outside</button>
-      </>,
-    );
-
-    const user = userEvent.setup();
-
-    const button = screen.getByRole('button', { name: /menu/i });
-
-    await user.click(button);
-
-    expect(await screen.findByRole('menu')).toBeInTheDocument();
-
-    // move focus away from the menu, which should close it
-    await user.tab();
-
-    await waitFor(() => expect(screen.queryByRole('menu')).not.toBeInTheDocument());
-  });
-
-  it('should navigate items with ArrowUp/ArrowDown', async () => {
-    render(<DropdownMenu items={ITEMS} />);
-
-    const user = userEvent.setup();
-
-    const button = screen.getByRole('button', { name: /menu/i });
-
-    await user.click(button);
-
-    const items = screen.getAllByRole('menuitem');
-
-    // first element is focussed when the menu is open
-    expect(items[0]).toHaveFocus();
-
-    await user.keyboard('{ArrowDown}');
-    expect(items[1]).toHaveFocus();
-
-    await user.keyboard('{ArrowUp}');
-    expect(items[0]).toHaveFocus();
-  });
-
-  it('should select an item with Enter or Space', async () => {
-    render(<DropdownMenu items={ITEMS} />);
-
-    const user = userEvent.setup();
-
-    const button = screen.getByRole('button', { name: /menu/i });
-
-    await user.click(button);
-    const items = screen.getAllByRole('menuitem');
-
-    await user.keyboard('{ArrowDown}');
-    await user.keyboard('{Enter}');
-
-    await waitFor(() => expect(screen.queryByRole('menu')).not.toBeInTheDocument());
-
-    await user.click(button);
-
-    expect(items[0]).toHaveFocus();
-  });
-
-  it('should move focus away when pressing Tab', async () => {
-    render(
-      <>
-        <DropdownMenu items={ITEMS} />
-
-        <button>Other Button</button>
-      </>,
-    );
-
-    const user = userEvent.setup();
-
-    const button = screen.getByRole('button', { name: /menu/i });
-
-    await user.click(button);
-
-    await user.tab();
-
-    await waitFor(() => expect(screen.queryByRole('menu')).not.toBeInTheDocument());
-  });
-});

package/src/components/dropdown/DropdownMenu.tsx

@@ -1,108 +0,0 @@
-'use client';
-
-import type { ComponentType, HTMLAttributes } from 'react';
-
-import { LuChevronDown } from 'react-icons/lu';
-
-import {
-  type ButtonRendererProps,
-  type ItemRendererProps,
-  useDropdownMenu,
-} from './useDropdownMenu';
-import { cn } from '../../utils';
-
-export type DropdownMenuItem<ItemProps extends object> = ItemRendererProps & {
-  label: string;
-} & ItemProps;
-
-export type DrowndownMenuButton = ButtonRendererProps;
-
-type DropdownMenuProps<ItemProps extends object> = HTMLAttributes<HTMLDivElement> & {
-  items: DropdownMenuItem<ItemProps>[];
-  containerClassName?: string;
-  menuContainerClassName?: string;
-  buttonRenderer?: ComponentType<ButtonRendererProps>;
-  buttonClassName?: string;
-  itemRenderer?: ComponentType<DropdownMenuItem<ItemProps>>;
-  itemClassName?: string;
-};
-
-const DefaultButton = ({ state: { isOpen }, ...props }: ButtonRendererProps) => {
-  return (
-    <button
-      {...props}
-      aria-label="Open Menu"
-      className={cn(
-        `text-black flex gap-2 items-center justify-center border rounded-md border-gray-300
-        bg-white px-2 py-1 text-sm shadow-sm focus:border-brand focus:outline-none focus:ring-1
-        focus:ring-brand`,
-        props.className,
-      )}
-    >
-      <span className="text-base pointer-events-none">Menu</span>
-
-      <LuChevronDown className={`pointer-events-none ${isOpen ? 'rotate-180' : ''}`} />
-    </button>
-  );
-};
-
-const DefaultItem = <Item extends object>({ label, ...props }: DropdownMenuItem<Item>) => {
-  return (
-    <div
-      {...props}
-      aria-label={label}
-      className={cn(
-        `text-black cursor-pointer hover:bg-slate-200 focus:bg-slate-200 active:bg-slate-300 px-2
-        py-1`,
-        props.className,
-      )}
-    >
-      {label}
-    </div>
-  );
-};
-
-export const DropdownMenu = <Item extends object>({
-  items,
-  containerClassName,
-  menuContainerClassName,
-  buttonRenderer = DefaultButton,
-  buttonClassName,
-  itemRenderer = DefaultItem,
-  itemClassName,
-  className,
-  ...props
-}: DropdownMenuProps<Item>) => {
-  // rebind to avoid linting errors
-  const ButtonRenderer = buttonRenderer;
-  const ItemRenderer = itemRenderer;
-
-  const { isOpen, buttonProps, itemProps } = useDropdownMenu(items.length);
-
-  return (
-    <div className={cn('relative', containerClassName, className)} {...props}>
-      <ButtonRenderer {...buttonProps} className={buttonClassName} />
-
-      <div
-        style={{ display: isOpen ? 'flex' : 'none' }}
-        aria-hidden={!isOpen}
-        className={cn(
-          `absolute right-0 mt-1 bg-white border shadow-md rounded-md min-w-full flex-col gap-0
-          z-[999] divide-y divide-slate-400`,
-          menuContainerClassName,
-        )}
-        role="menu"
-      >
-        {items.map((item, i) => (
-          <ItemRenderer
-            {...item}
-            {...itemProps[i]}
-            key={i}
-            label={item.label}
-            className={itemClassName}
-          />
-        ))}
-      </div>
-    </div>
-  );
-};

package/src/components/dropdown/useDropdownMenu.ts

@@ -1,249 +0,0 @@
-'use client';
-
-import {
-  useState,
-  useRef,
-  useId,
-  useEffect,
-  useMemo,
-  type HTMLAttributes,
-  useCallback,
-} from 'react';
-
-import type { ExtendProps } from '../../types/utils';
-import { KeyboardKeys } from '../../utils';
-
-/**
- * The current state of the menu
- */
-export type DropdownMenuState = { state: { isOpen: boolean } };
-
-// use a data attribute with a unique value to tell us which elements belong to the current menu
-type DropdownMenuAttribute = { 'data-menu': string };
-
-/**
- * The props that are passed into the button that is used to open/close the menu.
- */
-export type ButtonRendererProps = ExtendProps<'button', DropdownMenuState>;
-
-// can't use `ExtendProps` here since we just want the most base level of HTML attributes.
-// a number of elements use only these props, like `abbr`, but that implies the menu
-// item is an `<abbr>` which isn't strictly true, and so qualifying it ourselves is better
-/**
- * The props passed into each child item of the menu.
- */
-export type ItemRendererProps = HTMLAttributes<HTMLElement>;
-
-export type DropdownMenuHook = {
-  isOpen: boolean;
-  buttonProps: ButtonRendererProps & DropdownMenuAttribute;
-  itemProps: (ItemRendererProps & DropdownMenuAttribute)[];
-  selectedItemIndex: number;
-};
-
-/**
- * This hook handles the behaviour and accessibility concerns when creating a dropdown menu (*not* a select menu).
- * while leaving all the styling and design up to the user.
- *
- * The hook returns an object with 4 keys:
- * - `isOpen`: Whether the dropdown is open or not.
- * - `buttonProps`: These props are generated by the hook and need to be passed down (via spreading) into the `button` element
- * that the user can click to open/close the menu. Other attributes can be applied to the button along side these, but at minimum
- * these MUST be added.
- * - `itemProps`: These props are also generated by the hook, but they should be passed down to each item displayed in the menu.
- * Since the style and design is up to the user, when you create the menu children from some data, you can use the index to get
- * the props for each item and spread them in. For example:
- *   ```tsx
- *     data.map((_, i) => <div {...itemProps[i]}></div>)
- *   ```
- * - `selectedItemIndex`: This represents which item was last selected by the user.
- *
- * ### NOTES:
- * This hook makes use of `refs`. For that reason, the menu items **must not** be unmounted from the DOM via a conditional statement with `isOpen`.
- * Instead, you can show/hide the menu item container using its `display` or `visibility`  style and set it to a different value depending on
- * if the menu is open or not. This does not affect accessibility.
- *
- * Keyboard interactivity sources:
- * https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/
- *
- * @param itemCount The number of items to show in the menu.
- * @returns
- */
-export const useDropdownMenu = (itemCount: number): DropdownMenuHook => {
-  const [isOpen, setIsOpen] = useState(false);
-  const [selectedItem, setSelectedItem] = useState(0);
-
-  const currentFocusIndex = useRef<number | null>(null);
-
-  const menuId = useId();
-
-  // track the refs of each child so they can be focussed for accessibility
-  // this is memoified so it only updates when the number of items changes
-  const itemRefs: { current: Record<number, HTMLElement | null> } = useMemo(
-    () => ({ current: {} }),
-    [],
-  );
-
-  // use the unique id to determive if a given element is part of the menu
-  const isMenuItem = useCallback(
-    (element: Element | null): boolean => {
-      return (
-        element?.getAttribute('data-menu') === menuId ||
-        // get the closest element with that id, essentially checking if we are a child somewhere down the line
-        element?.closest(`[data-menu="${menuId}"]`) !== null
-      );
-    },
-    [menuId],
-  );
-
-  const focusItem = useCallback(
-    (index: number) => {
-      currentFocusIndex.current = index;
-      itemRefs.current[index]?.focus();
-    },
-    [itemRefs],
-  );
-
-  const selectItem = (index: number) => {
-    setSelectedItem(index);
-    setIsOpen(false);
-  };
-
-  useEffect(() => {
-    if (isOpen) {
-      focusItem(0);
-    }
-  }, [focusItem, isOpen]);
-
-  useEffect(() => {
-    // handles exiting the menu when the `Escape` key is pressed
-    const escapeExitMenuHandler = (event: KeyboardEvent) => {
-      if (
-        event.key === KeyboardKeys.Escape &&
-        document.activeElement &&
-        isMenuItem(document.activeElement)
-      ) {
-        event.preventDefault();
-
-        setIsOpen(false);
-      }
-    };
-
-    // handles exiting the menu when focus moved to another element
-    const blurExitMenuHandler = () => {
-      if (!isMenuItem(document.activeElement)) {
-        setIsOpen(false);
-      }
-    };
-
-    // handles exiting the menu when the user clicks/touches outside the menu
-    const clickExitMenuHandler = (event: PointerEvent) => {
-      if (event.button === 0 && !isMenuItem(event.target as Element)) {
-        setIsOpen(false);
-      }
-    };
-
-    window.addEventListener('keydown', escapeExitMenuHandler);
-    // `passive` events just mean we dont call `preventDefault` and it allows the browser to be a bit smarter about the events
-    // `capture` is a bit more complicated but from what I understand it essentially makes it so this event handler fires BEFORE
-    // the element gets the event, whereas without it it would trigger AFTER the element recieved the event
-    document.addEventListener('focus', blurExitMenuHandler, { capture: true, passive: true });
-    //  make use of pointer events instead of click events to support touch devices.
-    document.addEventListener('pointerup', clickExitMenuHandler, { passive: true });
-
-    return () => {
-      window.removeEventListener('keydown', escapeExitMenuHandler);
-      document.removeEventListener('focus', blurExitMenuHandler);
-      document.removeEventListener('pointerup', clickExitMenuHandler);
-    };
-  }, [isMenuItem]);
-
-  return {
-    isOpen,
-    selectedItemIndex: selectedItem,
-
-    buttonProps: {
-      state: { isOpen },
-      'data-menu': menuId,
-      'aria-haspopup': 'menu',
-      'aria-expanded': isOpen,
-
-      onPointerUp: () => setIsOpen(!isOpen),
-      onKeyDown: (event) => {
-        //  space and enter act more like clicking and can toggle the menu open/closed
-        if (event.key === KeyboardKeys.Space || event.key === KeyboardKeys.Enter) {
-          event.preventDefault();
-
-          setIsOpen(!isOpen);
-        }
-
-        // the down arrow should open the menu
-        if (event.key === KeyboardKeys.ArrowDown) {
-          event.preventDefault();
-
-          if (!isOpen) {
-            setIsOpen(true);
-          } else {
-            focusItem(0);
-          }
-        }
-      },
-    },
-
-    itemProps: Array.from({ length: itemCount }, (_, itemIndex) => ({
-      key: itemIndex,
-
-      role: 'menuitem',
-      // the items in the menu should not be focussable. using `Tab` should move the focus away from the menu entirely.
-      // only arrow keys should navigate each item
-      tabIndex: -1,
-      'data-menu': menuId,
-
-      ref: (el: HTMLElement) => {
-        itemRefs.current[itemIndex] = el;
-      },
-
-      // by using a 0 second `setTimeout` the event handler is moved to the bottom of the stack
-      // this is important because it means our handler is fired AFTER the default behaviour
-      // without the setTimeout things like links might not work properly because the menu
-      // would hide BEFORE the browsers own default click handler could redirect you
-      onPointerUp: () => setTimeout(() => selectItem(itemIndex), 0),
-      onKeyDown: (event) => {
-        let focusIndex = currentFocusIndex.current;
-
-        // close the menu if you "select" an item
-        if (event.key === KeyboardKeys.Space || event.key === KeyboardKeys.Enter) {
-          event.preventDefault();
-
-          // we just called `preventDefault` so we need to manually click it otherwise nothing will happen
-          // the reason we must call `preventDefault` is to avoid other behaviour like spacebar scrolling the page
-          itemRefs.current[itemIndex]?.click();
-
-          selectItem(itemIndex);
-        }
-
-        if (focusIndex !== null) {
-          // arrow keys should cycle through each item in the menu
-          if (event.key === KeyboardKeys.ArrowDown) {
-            event.preventDefault();
-
-            focusIndex += 1;
-          } else if (event.key === KeyboardKeys.ArrowUp) {
-            event.preventDefault();
-
-            focusIndex -= 1;
-          }
-
-          // allow wrapping of focus
-          if (focusIndex > itemCount - 1) {
-            focusIndex = 0;
-          } else if (focusIndex < 0) {
-            focusIndex = itemCount - 1;
-          }
-
-          focusItem(focusIndex);
-        }
-      },
-    })),
-  };
-};