@sproutsocial/seeds-react-menu 0.1.0

package/src/MenuItemSelectable/__tests__/MenuItemSelectable.typetest.tsx

@@ -0,0 +1,56 @@
+import { MenuItemSelectable } from "../MenuItemSelectable";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function MenuItemSelectableTypeTest() {
+  return (
+    <>
+      {/* Valid MenuItemSelectable with minimal required props */}
+      <MenuItemSelectable id="test">Test</MenuItemSelectable>
+      {/* Valid MenuItemSelectable allows active prop */}
+      <MenuItemSelectable id="test" active>
+        Test
+      </MenuItemSelectable>
+      {/* Valid MenuItemSelectable allows active prop false */}
+      <MenuItemSelectable id="test" active={false}>
+        Test
+      </MenuItemSelectable>
+      {/* Valid MenuItemSelectable allows inputType prop to be checkbox */}
+      <MenuItemSelectable id="test" inputType="checkbox">
+        Test
+      </MenuItemSelectable>
+      {/* Valid MenuItemSelectable allows inputType prop to be radio */}
+      <MenuItemSelectable id="test" inputType="radio">
+        Test
+      </MenuItemSelectable>
+      {/* Valid MenuItemSelectable allows inputType prop to be switch */}
+      <MenuItemSelectable id="test" inputType="switch">
+        Test
+      </MenuItemSelectable>
+      {/* Valid MenuItemSelectable allows inputType prop to be icon */}
+      <MenuItemSelectable id="test" inputType="icon">
+        Test
+      </MenuItemSelectable>
+      {/* Valid MenuItemSelectable allows inputLabel prop as a string */}
+      <MenuItemSelectable id="test" inputLabel="Test Label">
+        Test
+      </MenuItemSelectable>
+
+      {/* @ts-expect-error - no children is invalid */}
+      <MenuItemSelectable id="foo" />
+      {/* @ts-expect-error - missing id is invalid */}
+      <MenuItemSelectable>Test</MenuItemSelectable>
+      <MenuItemSelectable
+        /* @ts-expect-error - id may not be a number */
+        id={0}
+        /* @ts-expect-error - active may not be a string */
+        active="true"
+        /* @ts-expect-error - inputType must be valid */
+        inputType="invalid"
+        /* @ts-expect-error - inputLabel may not be a number */
+        inputLabel={0}
+      >
+        Test
+      </MenuItemSelectable>
+    </>
+  );
+}

package/src/MenuItemSelectable/index.ts

@@ -0,0 +1,5 @@
+export * from "./MenuItemSelectable";
+
+export * from "./MenuItemSelectableTypes";
+
+export * from "./styles";

package/src/MenuItemSelectable/styles.tsx

@@ -0,0 +1,21 @@
+import styled from "styled-components";
+
+export const MenuItemSelectableRow = styled.div`
+  display: flex;
+  align-items: center;
+  pointer-events: none;
+`;
+
+export const MenuItemSelectableAction = styled.div`
+  margin-right: ${({ theme }) => theme.space[300]};
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+`;
+
+export const MenuItemSelectableText = styled.div`
+  word-break: break-word;
+  flex-grow: 1;
+  min-width: 0;
+`;

package/src/MenuLabel.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { Text, type TypeTextProps } from "@sproutsocial/seeds-react-text";
+import { useMenuContext } from "./MenuContext";
+
+export const MenuLabel = ({ children, ...rest }: TypeTextProps) => {
+  const { getLabelProps } = useMenuContext();
+  return (
+    <Text as="label" color="text.body" {...getLabelProps?.()} {...rest}>
+      {children}
+    </Text>
+  );
+};

package/src/MenuRoot/MenuRoot.feature

@@ -0,0 +1,93 @@
+Feature: Menu Root
+
+  The main component responsible for setting up a Menu.
+
+  Rule: User Behavior
+    Background:
+      Given an end user is using the component
+
+    Scenario: MenuRoot closes when esc is pressed
+      Given a menu is open
+      When the esc key is pressed
+      Then the menu closes
+
+    Scenario Outline: MenuRoot focuses the correct element when opened
+      Given a MenuRoot <use case>
+      When the the menu is opened
+      Then <correct element> is in focus
+
+      Examples:
+        | use case                                | the correct element                              |
+        | contains at least one MenuItem          | the first MenuItem                               |
+        | has a custom defaultFocusRef            | the defaultFocusRef element                      |
+        | has no MenuItems and no defaultFocusRef | an error is logged and the first focusable child |
+
+  Rule: API
+    Background:
+      Given an engineer is implementing the component
+
+      Scenario: MenuRoot is using keyboard instructions
+        Given a screen reader is being used
+        When a MenuRoot is provided with the keyboardInstructions prop
+        Then the screen reader will read the instructions
+
+      Scenario: MenuRoot is not using keyboard instructions
+        Given a screen reader is being used
+        When a MenuRoot is not provided with the keyboardInstructions prop
+        Then the screen reader will not read the instructions
+
+      Scenario Outline: MenuRoot contains children
+        When <child component(s)> provided
+        Then the MenuRoot should render the <component(s)>
+
+        Examples: child components
+          | child component(s)             | component(s)               |
+          | a MenuHeader is                | MenuHeader                 |
+          | a MenuFooter is                | MenuFooter                 |
+          | a MenuGroup is                 | MenuGroup                  |
+          | a Banner and MenuGroup are     | Banner and MenuGroup       |
+          | MenuItems wrapped in a Box are | MenuItems wrapped in a Box |
+
+      Scenario: MenuRoot implements MenuContext
+        When MenuContext props are provided
+        Then the MenuRoot passes those props to the MenuContext
+
+      Scenario Outline: MenuRoot implements all Downshift functions, props and utilities
+        When <input prop> from Downshift is provided
+        Then the MenuRoot passes <this prop> to the MenuContext
+
+        Examples: child components
+          | input prop           | this prop            |
+          | items                | items                |
+          | itemToString         | itemToString         |
+          | onSelectedItemChange | onSelectedItemChange |
+          | stateReducer         | stateReducer         |
+          | getToggleButtonProps | getToggleButtonProps |
+          | getItemProps         | getItemProps         |
+          | getLabelProps        | getLabelProps        |
+          | getMenuProps         | getMenuProps         |
+          | reset                | reset                |
+          | isOpen               | isOpen               |
+
+      Scenario: MenuRoot may be implemented without using Downshift
+        Given a developer is not using Downshift
+        When the MenuRoot is built using valid props
+        Then the MenuRoot passes those props to the MenuContext for custom implementation
+
+      Scenario Outline: MenuRoot children can access MenuContext
+        When child <component> accesses <menu context>
+        Then <menu context> is available to use
+
+        Examples: Prop Types
+          | component     | menu context          |
+          | Button        | getToggleButtonProps  |
+          | MenuFooter    | closeMenu             |
+          | Clear Link    | reset                 |
+
+      Scenario Outline: MenuRoot checks its types
+        When <propName> is passed a value
+        Then MenuRoot expects it to be of type <propType>
+
+        Examples: Prop Types
+          | propName    | propType   |
+          | children    | ReactNode  |

package/src/MenuRoot/MenuRoot.tsx

@@ -0,0 +1,70 @@
+import React, { useCallback, useRef } from "react";
+import styled from "styled-components";
+import { Popout, type TypePopoutProps } from "@sproutsocial/seeds-react-popout";
+
+import { MenuProvider, type TypeMenuProviderProps } from "../MenuContext";
+
+export interface TypeMenuRootOwnProps {
+  triggerElement: React.ReactElement<any>;
+  popoutProps?: Partial<
+    Omit<TypePopoutProps, "isOpen" | "setIsOpen" | "content" | "children">
+  >;
+  width?: TypePopoutProps["width"];
+}
+export interface TypeMenuRootProps
+  extends Partial<TypeMenuProviderProps>,
+    TypeMenuRootOwnProps {}
+
+const CustomPopoutContent = styled(Popout.Content)`
+  padding: 0;
+  margin-left: 0;
+  margin-right: 0;
+`;
+export const MenuRoot = ({
+  children,
+  triggerElement,
+  popoutProps,
+  width = "300px",
+  ...contextProps
+}: TypeMenuRootProps) => {
+  const { isListbox, isOpen, openMenu, closeMenu, getMenuProps } = contextProps;
+  const setIsOpen = useCallback(
+    (newIsOpen: boolean) => {
+      newIsOpen ? openMenu?.() : closeMenu?.();
+    },
+    [openMenu, closeMenu]
+  );
+
+  return (
+    <MenuProvider {...contextProps}>
+      <Popout
+        isOpen={!!isOpen}
+        setIsOpen={setIsOpen}
+        content={
+          <CustomPopoutContent width={width}>
+            <div
+              {...getMenuProps?.(
+                {
+                  ...(isListbox ? {} : { role: "menu" }),
+                },
+                // Suppress ref error for now
+                { suppressRefError: true }
+              )}
+            >
+              {children}
+            </div>
+          </CustomPopoutContent>
+        }
+        focusLockProps={{
+          // correct jerking motion when scrolling while the Popout is open
+          // returnFocus: false,
+          crossFrame: false,
+        }}
+        disableWrapperAria
+        {...popoutProps}
+      >
+        {triggerElement}
+      </Popout>
+    </MenuProvider>
+  );
+};

package/src/MenuRoot/__tests__/MenuRoot.test.tsx

@@ -0,0 +1,197 @@
+import React, { useContext, useState } from "react";
+import {
+  fireEvent,
+  render,
+  screen,
+} from "@sproutsocial/seeds-react-testing-library";
+import { Box } from "@sproutsocial/seeds-react-box";
+import { Button } from "@sproutsocial/seeds-react-button";
+import {
+  MenuRoot,
+  MenuToggleButton,
+  MenuItem,
+  MenuContext,
+  MenuFooter,
+  MenuHeader,
+  type TypeMenuContextProps,
+} from "../../index";
+
+jest.mock("@sproutsocial/seeds-react-portal", () => ({ children }) => (
+  <div>{children}</div>
+));
+
+const TestComponent = () => {
+  const { isOpen } = useContext(MenuContext);
+  return <div>{isOpen ? "Is open" : "Is closed"}</div>;
+};
+const TestToggleButton = () => {
+  const { getToggleButtonProps } = useContext(MenuContext);
+  return <Button {...getToggleButtonProps?.()}>Toggle</Button>;
+};
+const TestMenuFooter = () => {
+  const { closeMenu } = useContext(MenuContext);
+  return (
+    <MenuFooter>
+      <Button onClick={() => closeMenu?.()}>Close</Button>
+    </MenuFooter>
+  );
+};
+// const TestClearLink = () => {
+//   const { reset } = useContext(MenuContext);
+//   return <Link onClick={() => reset?.()}>Reset</Link>;
+// };
+
+describe("MenuRoot", () => {
+  // TODO: test this on the Menu components that use downshift?
+  // it("closes when esc is pressed", () => {
+  //   // closes when esc is pressed
+  // });
+
+  // TODO: write these tests when focus logic is implemented
+  // test.each([
+  //   {
+  //     element: "focuses the first MenuItem",
+  //     condition: "contains at least one MenuItem",
+  //   },
+  //   {
+  //     element: "focuses the defaultFocusRef element",
+  //     condition: "has a custom defaultFocusRef",
+  //   },
+  //   {
+  //     element: "an error is logged and focuses the first focusable child",
+  //     condition: "has no MenuItems and no defaultFocusRef",
+  //   },
+  // ])("$element when opened if it $condition", ({}) => {
+  //   // focuses the correct element when opened
+  // });
+
+  // TODO: write tests for keyboard instructions when feature added
+  // it("triggers keyboard instructions", () => {
+  //   // triggers keyboard instructions
+  // });
+
+  // it("has no keyboard instructions by default", () => {
+  //   // has no keyboard instructions by default
+  // });
+
+  // TODO: Add MenuGroup when the component is ready
+  it("renders custom children", () => {
+    render(
+      <MenuRoot
+        triggerElement={<MenuToggleButton>Open Menu</MenuToggleButton>}
+        isOpen
+      >
+        <MenuHeader title="Menu Header" />
+        <div>Custom Banner</div>
+        <Box>
+          <MenuItem id="1">Item 1</MenuItem>
+        </Box>
+        <MenuFooter>Menu Footer</MenuFooter>
+      </MenuRoot>
+    );
+
+    expect(screen.getByText("Menu Header")).toBeInTheDocument();
+    expect(screen.getByText("Custom Banner")).toBeInTheDocument();
+    expect(screen.getByText("Item 1")).toBeInTheDocument();
+    expect(screen.getByText("Menu Footer")).toBeInTheDocument();
+  });
+
+  // TODO: test this using the SingleSelectMenu, MultiSelectMenu, and ComboBox
+  // it("passes downshift props to the MenuContext", () => {
+  //   // passes downshift props to the MenuContext
+  //   // Can be tested by the components that use downshift
+  // });
+
+  it("can be implemented without using Downshift", () => {
+    const randomText = "Some random text";
+    const TestCustomMenu = () => {
+      const [isOpen, setIsOpen] = useState(false);
+      const getToggleButtonProps = (props) => ({
+        onClick: () => setIsOpen(!isOpen),
+        ...props,
+      });
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore - mock contextProps may be imperfect
+      const contextProps: TypeMenuContextProps = {
+        toggleMenu: () => setIsOpen(!isOpen),
+        getToggleButtonProps,
+        isOpen,
+      };
+
+      return (
+        <MenuRoot
+          triggerElement={
+            <MenuToggleButton appearance="secondary">
+              Open Menu (<TestComponent />)
+            </MenuToggleButton>
+          }
+          {...contextProps}
+        >
+          {randomText}
+        </MenuRoot>
+      );
+    };
+    render(<TestCustomMenu />);
+
+    expect(screen.getByText("Is closed")).toBeInTheDocument();
+    expect(screen.queryByText(randomText)).not.toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button"));
+    expect(screen.getByText("Is open")).toBeInTheDocument();
+    expect(screen.getByText(randomText)).toBeInTheDocument();
+  });
+
+  const contextTests: {
+    child: string;
+    TestComponent: React.FC;
+    contextProps: Partial<TypeMenuContextProps>;
+    testBtnText: string;
+    testFn: string;
+  }[] = [
+    {
+      child: "Button",
+      TestComponent: TestToggleButton,
+      contextProps: {
+        // @ts-expect-error - mocked function doesn't match expected type
+        getToggleButtonProps: jest.fn((props) => ({
+          onKeyDown: jest.fn() as React.KeyboardEventHandler,
+          ...props,
+        })),
+      },
+      testBtnText: "Toggle",
+      testFn: "getToggleButtonProps",
+    },
+    {
+      child: "MenuFooter",
+      TestComponent: TestMenuFooter,
+      contextProps: { closeMenu: jest.fn() },
+      testBtnText: "Close",
+      testFn: "closeMenu",
+    },
+    // TODO: Add this back when Link is abstracted
+    // {
+    //   child: "Clear Link",
+    //   TestComponent: TestClearLink,
+    //   contextProps: { reset: jest.fn() },
+    //   testBtnText: "Reset",
+    //   testFn: "reset",
+    // },
+  ];
+  test.each(contextTests)(
+    "$child can access $testFn from the MenuContext",
+    ({ TestComponent, contextProps, testBtnText, testFn }) => {
+      render(
+        <MenuRoot
+          triggerElement={<MenuToggleButton>Open Menu</MenuToggleButton>}
+          isOpen
+          {...contextProps}
+        >
+          <TestComponent />
+        </MenuRoot>
+      );
+
+      const testBtn = screen.getByRole("button", { name: testBtnText });
+      fireEvent.click(testBtn);
+      expect(contextProps[testFn]).toHaveBeenCalled();
+    }
+  );
+});

package/src/MenuRoot/__tests__/MenuRoot.typetest.tsx

@@ -0,0 +1,76 @@
+import * as React from "react";
+import { MenuRoot, MenuContent, MenuHeader, MenuFooter } from "../../index";
+
+export const MenuRootTypeTest = () => (
+  <>
+    {/* Valid MenuRoot with minimal required props */}
+    <MenuRoot triggerElement={<>test</>}>Test</MenuRoot>
+    {/* Valid MenuRoot allows MenuContent by itself as a child */}
+    <MenuRoot triggerElement={<>test</>}>
+      <MenuContent>Test</MenuContent>
+    </MenuRoot>
+    {/* Valid MenuRoot allows multiple children without fragment */}
+    <MenuRoot triggerElement={<>test</>}>
+      <MenuHeader>Test</MenuHeader>
+      <MenuContent>Test</MenuContent>
+      <MenuFooter>Test</MenuFooter>
+    </MenuRoot>
+    {/* Valid MenuRoot accepts Downshift props and functions for useSelect */}
+    <MenuRoot
+      triggerElement={<>test</>}
+      onSelectedItemChange={() => {}}
+      selectItem={() => {}}
+      selectedItem={null}
+      stateReducer={(c) => c}
+      onStateChange={() => {}}
+      getA11yStatusMessage={() => ""}
+      isOpen
+    >
+      Test
+    </MenuRoot>
+    {/* Valid MenuRoot accepts Downshift props and functions for useMultipleSelection */}
+    <MenuRoot
+      triggerElement={<>test</>}
+      onSelectedItemsChange={() => {}}
+      selectedItems={[]}
+      multiSelectStateReducer={(c) => c}
+      onMultiSelectStateChange={() => {}}
+      getA11yMultiStatusMessage={() => ""}
+    >
+      Test
+    </MenuRoot>
+
+    {/* @ts-expect-error - triggerElement is a required prop */}
+    <MenuRoot>Test</MenuRoot>
+    <MenuRoot
+      /* @ts-expect-error - triggerElement must be a valid react element */
+      triggerElement="test"
+    >
+      Test
+    </MenuRoot>
+    {/* @ts-expect-error - when no children provided */}
+    <MenuRoot triggerElement="test" />
+
+    <MenuRoot
+      triggerElement={<>test</>}
+      /* @ts-expect-error - isOpen can't be a string */
+      isOpen="false"
+      /* @ts-expect-error - onSelectedItemChange can't be a string */
+      onSelectedItemChange="test"
+      /* @ts-expect-error - selectItem can't be a string */
+      selectItem="test"
+      /* @ts-expect-error - selectedItem can't be a string */
+      selectedItem="test"
+      /* @ts-expect-error - stateReducer must have a return value */
+      stateReducer={() => {}}
+      /* @ts-expect-error - onMultiSelectStateChange can't be a string */
+      onMultiSelectStateChange="test"
+      /* @ts-expect-error - selectedItems can't be a string */
+      selectedItems="test"
+      /* @ts-expect-error - multiSelectStateReducer must have a return value */
+      multiSelectStateReducer="test"
+    >
+      Test
+    </MenuRoot>
+  </>
+);

package/src/MenuRoot/index.ts

@@ -0,0 +1 @@
+export * from "./MenuRoot";

package/src/MenuToggleButton.tsx

@@ -0,0 +1,29 @@
+import React, { type ReactNode, useContext } from "react";
+import { Button, type TypeButtonProps } from "@sproutsocial/seeds-react-button";
+import { MenuContext } from "./MenuContext";
+
+export interface TypeMenuToggleButtonProps extends Partial<TypeButtonProps> {
+  children: ReactNode;
+}
+
+export const MenuToggleButton = ({
+  children,
+  ...rest
+}: TypeMenuToggleButtonProps) => {
+  const { getToggleButtonProps, isListbox, getDropdownProps } =
+    useContext(MenuContext);
+  return (
+    <Button
+      appearance="secondary"
+      {...getToggleButtonProps?.({
+        // Decide if we want the preventKeyAction stuff. Maybe create a prop to allow for this to be overriden.
+        ...getDropdownProps?.({ preventKeyAction: true }),
+        refKey: "innerRef",
+        ...(isListbox ? {} : { role: "button", "aria-haspopup": "menu" }),
+      })}
+      {...rest}
+    >
+      {children}
+    </Button>
+  );
+};

package/src/MultiSelectMenu/MultiSelectMenu.feature

@@ -0,0 +1,70 @@
+Feature: MultiSelectMenu
+
+    A menu component that allows users to select multiple items from a list.
+
+    Rule: User behavior
+        Background:
+            Given an end user is using the component
+
+        Scenario: User can select multiple items
+            Given the MultiSelectMenu is open
+            When an item is selected
+            Then the items are marked as selected
+            And the menu remains open
+
+        Scenario: Menu retains selection state
+            Given the MultiSelectMenu has items selected
+            When the MultiSelectMenu is opened
+            Then the items appear as selected
+
+        Scenario: Screen reader announces listbox
+            Given a screen reader is being used
+            When the MultiSelect Input is focused
+            Then the screen reader announces it as a "listbox" with multiple selections possible
+
+        Scenario: Multi-select is navigable via keyboard
+            Given the MultiSelectMenu is focused
+            And an item is selected with 'spacebar' or 'enter'
+            Then the onSelectedItemsChange callback triggers
+
+    Rule: API
+        Background:
+            Given an engineer is developing using the component
+
+        Scenario: Component accepts selected items
+            When a list of selected items is passed to the MultiSelectMenu
+            Then the items are displayed as selected
+
+        Scenario: Component handles existing selection state
+            When the MultiSelectMenu is passed a `selectedItems` prop
+            Then the component renders the existing values
+
+        Scenario: Component handles new selection state
+            When the MultiSelectMenu is not passed
+            And a new selection is created
+            Then the 'onSelectedItemsChangee' callback is fired
+
+        Scenario: Menu does not close on selection
+            When an item is selected
+            Then the 'onSelectedItemsChange' callback fires without closing the menu
+
+        Scenario Outline: Actions can be triggered from the MultiSelectMenu
+            When actionable elements are provided to the MultiSelectMenu
+            And an `<action>` is clicked
+            Then the corresponding `onClick` should be executed
+
+            Examples: Action Types
+                | action           |
+                | ---------------- |
+                | select button    |
+                | deselect button  |
+
+        Scenario Outline: MultiSelectMenu checks its types
+            When `<propName>` is passed a value
+            Then MultiSelectMenu expects it to be of type `<propType>`
+
+            Examples: Prop Types
+                | propName              | propType                 |
+                | --------------------- | ------------------------ |
+                | selectedItems         | array                    |
+                | onSelectedItemsChange | function                 |