Migration from DeprecatedMenu/Menu in preview-react to Menu in main

[josh-bagwell]

This will be a migration guide to help the migration from the DeprecatedMenu/Menu component that is a part of the preview-react to the Menu compound component that is in main. Please see the Menu documentation
here.

If you would like to see the differences between DeprecatedMenu and the Menu compound component,
see this codesandbox example.

See below for how these components will migrate:

<DeprecatedMenu/> -> <Menu/>
(This will be the parent container that wraps those)

<DeprecatedMenuItem/> -> <Menu.Item/>

<Popup/>
Not needed to wrap

<Popup.Popper/> -> <Menu.Popper/>
The "Popper" of a menu. The popper will appear around the Menu.Target. It renders a div element that is portalled to the document.body which is controlled by the PopupStack. The PopupStack is not part of React. This means no extra props given to this component will be forwarded to the div element, but the ref will be forwarded.

<Popup.Target/> -> <Menu.Target/>

hasDivider -> <Menu.Divider/>
This will need to be moved from a prop to a sub-component. This is a divider for the

<Menu.Card/>
The menu card is a non-semantic element used to give the dropdown menu its distinct visual cue that the dropdown menu is floating above other content. A menu card usually contains a menu list, but can also contain other elements like a header or footer.

<Menu.List/>
The menu list follows the Collections API. A list can either contain static items or a render prop and items to the model.

Below are some basic examples of DeprecatedMenu and the Menu component from main.

DeprecatedMenu and DeprecatedMenuItem:

import React from 'react';
import {DeprecatedMenu, DeprecatedMenuItem} from '@workday/canvas-kit-preview-react/menu';
import {SecondaryButton} from '@workday/canvas-kit-react/button';
import {
  Popup,
  usePopupModel,
  useAlwaysCloseOnOutsideClick,
  useReturnFocus,
  useCloseOnEscape,
} from '@workday/canvas-kit-react/popup';

const menuId = 'basic-menu';

export const Basic = () => {
  const model = usePopupModel();

  useAlwaysCloseOnOutsideClick(model);
  useCloseOnEscape(model);
  useReturnFocus(model);

  const isOpen = model.state.visibility !== 'hidden';

  const handleButtonKeyDown = (event: React.KeyboardEvent) => {
    let isShortcut = false;
    if (event.key === `Spacebar` || event.key === ` ` || event.key === `Enter`) {
      isShortcut = true;
      if (isOpen) {
        model.events.hide();
      } else {
        model.events.show();
      }
    } else if (event.key === `ArrowDown` || event.key === `ArrowUp`) {
      isShortcut = true;
      model.events.show();
    }

    if (isShortcut) {
      // Prevent ArrowDown and ArrowUp keys from scrolling the entire page
      event.preventDefault();
    }
  };

  return (
    <Popup model={model}>
      <Popup.Target
        as={SecondaryButton}
        onKeyDown={handleButtonKeyDown}
        aria-expanded={isOpen}
        aria-haspopup={true}
        aria-controls={isOpen ? menuId : undefined}
      >
        Open Menu
      </Popup.Target>
      <Popup.Popper placement="bottom-start">
        {/*
          isOpen must be set for focus to be properly assigned to the DeprecatedMenu;
          onClose must be set in order to the DeprecatedMenu to close properly after
          selecting a DeprecatedMenuItem
        */}
        <DeprecatedMenu id={menuId} isOpen={isOpen} onClose={model.events.hide}>
          <DeprecatedMenuItem>First Item</DeprecatedMenuItem>
          <DeprecatedMenuItem>
            Second Item (with a really really really long label)
          </DeprecatedMenuItem>
          <DeprecatedMenuItem isDisabled>Third Item (disabled)</DeprecatedMenuItem>
          <DeprecatedMenuItem>
            Fourth Item (<b>with markup</b>)
          </DeprecatedMenuItem>
          <DeprecatedMenuItem hasDivider>Fifth Item (with divider)</DeprecatedMenuItem>
        </DeprecatedMenu>
      </Popup.Popper>
    </Popup>
  );
};

Menu:

import React from 'react';
import {Menu} from '@workday/canvas-kit-react/menu';
import {BodyText} from '@workday/canvas-kit-react/text';

export const Basic = () => {
  const [selected, setSelected] = React.useState('');
  return (
    <Menu onSelect={data => setSelected(data.id)}>
      <Menu.Target>Open Menu</Menu.Target>
      <Menu.Popper>
        <Menu.Card>
          <Menu.List>
            <Menu.Item>First Item</Menu.Item>
            <Menu.Item>Second Item</Menu.Item>
            <Menu.Divider />
            <Menu.Item>Third Item (with a really, really, really long label)</Menu.Item>
            <Menu.Item>Fourth Item</Menu.Item>
          </Menu.List>
        </Menu.Card>
      </Menu.Popper>
      <BodyText size="small" marginTop="s">
        Selected: <span data-testid="output">{selected}</span>
      </BodyText>
    </Menu>
  );
};