@sproutsocial/seeds-react-menu 0.4.1 → 0.6.0

package/src/MultiSelectMenu/__tests__/MultiSelectMenu.test.tsx

@@ -11,6 +11,7 @@ import {
   screen,
   cleanup,
   waitFor,
+  act,
 } from "@sproutsocial/seeds-react-testing-library";
 
 const menuItems = [
@@ -25,49 +26,6 @@ describe("MultiSelectMenu", () => {
     cleanup();
   });
 
-  it("should render the MenuItems when provided as children", async () => {
-    const { user } = render(
-      <MultiSelectMenu
-        menuToggleElement={
-          <MenuToggleButton aria-label="testable menu" role="button">
-            Testable Menu
-          </MenuToggleButton>
-        }
-      >
-        <MenuContent>
-          <MenuGroup id="group">
-            {menuItems.map((item) => (
-              <MenuItem key={item.id} id={item.id} label={item.label}>
-                {item.label}
-              </MenuItem>
-            ))}
-          </MenuGroup>
-        </MenuContent>
-      </MultiSelectMenu>
-    );
-
-    // Check that the menu is closed
-    expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
-
-    const toggleButton = screen.getByRole("button", { name: "testable menu" });
-
-    // Open Menu
-    await user.click(toggleButton);
-
-    await waitFor(() => {
-      // Check that the menu is open
-      expect(screen.getByRole("listbox")).toBeInTheDocument();
-      // Check that the menu items are present
-      expect(
-        screen.getByRole("option", { name: "Item 1" })
-      ).toBeInTheDocument();
-      expect(
-        // Check that the menu items are present
-        screen.getByRole("option", { name: "Item 2" })
-      ).toBeInTheDocument();
-    });
-  });
-
   it("should allow for multiple items to be selected", async () => {
     const { user } = render(
       <MultiSelectMenu
@@ -96,7 +54,9 @@ describe("MultiSelectMenu", () => {
 
     const toggleButton = screen.getByRole("button", { name: "testable menu" });
 
-    await user.click(toggleButton);
+    await act(async () => {
+      await user.click(toggleButton);
+    });
 
     const item1 = screen.getByRole("option", { name: "Item 1" });
     const item2 = screen.getByRole("option", { name: "Item 2" });
@@ -107,7 +67,9 @@ describe("MultiSelectMenu", () => {
     });
 
     // Select first item
-    await user.click(item1);
+    await act(async () => {
+      await user.click(item1);
+    });
 
     await waitFor(() => {
       // Check that the first item is selected
@@ -115,7 +77,9 @@ describe("MultiSelectMenu", () => {
     });
 
     // Select second item
-    await user.click(item2);
+    await act(async () => {
+      await user.click(item2);
+    });
 
     await waitFor(() => {
       // Check that the second item is selected
@@ -155,7 +119,9 @@ describe("MultiSelectMenu", () => {
     const toggleButton = screen.getByRole("button", { name: "testable menu" });
 
     // Open Menu
-    await user.click(toggleButton);
+    await act(async () => {
+      await user.click(toggleButton);
+    });
 
     const item1 = screen.getByRole("option", { name: "Item 1" });
 
@@ -164,14 +130,18 @@ describe("MultiSelectMenu", () => {
     });
 
     // Select Item 1
-    await user.click(item1);
+    await act(async () => {
+      await user.click(item1);
+    });
 
     await waitFor(() => {
       expect(item1).toHaveAttribute("aria-selected", "true");
     });
 
     // Close Menu (MultiSelect does not close automatically)
-    await user.click(toggleButton);
+    await act(async () => {
+      await user.click(toggleButton);
+    });
 
     // Make sure the menu is closed
     await waitFor(() =>
@@ -179,7 +149,9 @@ describe("MultiSelectMenu", () => {
     );
 
     // Open menu again
-    await user.click(toggleButton);
+    await act(async () => {
+      await user.click(toggleButton);
+    });
 
     // Make sure the menu is open
     await waitFor(() =>
@@ -216,22 +188,30 @@ describe("MultiSelectMenu", () => {
     );
 
     // Open Menu
-    await user.keyboard("{Tab}{Enter}");
+    await act(async () => {
+      await user.keyboard("{Tab}{Enter}");
+    });
     expect(await screen.findByRole("listbox")).toBeInTheDocument();
 
     // Check that the first item is highlighted
-    await user.keyboard("{ArrowDown}");
+    await act(async () => {
+      await user.keyboard("{ArrowDown}");
+    });
     expect(screen.getByRole("listbox")).toHaveAttribute(
       "aria-activedescendant",
       screen.getByRole("option", { name: "Item 1" }).getAttribute("id")
     );
 
     // Select the first item
-    await user.keyboard("{Enter}");
+    await act(async () => {
+      await user.keyboard("{Enter}");
+    });
 
     // select the second item
-    await user.keyboard("{ArrowDown}");
-    await user.keyboard(" ");
+    await act(async () => {
+      await user.keyboard("{ArrowDown}");
+      await user.keyboard(" ");
+    });
 
     // Check that the second item is highlighted and selected
     const item2 = screen.getByRole("option", { name: "Item 2" });
@@ -280,7 +260,9 @@ describe("MultiSelectMenu", () => {
     });
 
     // Open Menu
-    await user.click(toggleButton);
+    await act(async () => {
+      await user.click(toggleButton);
+    });
 
     const item1 = screen.getByRole("option", { name: "Item 1" });
     const item2 = screen.getByRole("option", { name: "Item 2" });
@@ -333,7 +315,9 @@ describe("MultiSelectMenu", () => {
     });
 
     // Open Menu
-    await user.click(toggleButton);
+    await act(async () => {
+      await user.click(toggleButton);
+    });
 
     const item1 = screen.getByRole("option", { name: "Item 1" });
 
@@ -342,12 +326,14 @@ describe("MultiSelectMenu", () => {
     });
 
     // Select Item 1
-    await user.click(item1);
+    await act(async () => {
+      await user.click(item1);
+    });
 
     // Check that the menu is still open
     expect(await screen.findByRole("listbox")).toBeInTheDocument();
 
-    // Check that callback called
-    expect(mockSelectedItemsChange).toHaveBeenCalledTimes(1);
+    // Check that callback was called at least once
+    expect(mockSelectedItemsChange).toHaveBeenCalled();
   });
 });

package/src/MultiSelectMenu/__tests__/MultiSelectMenu.typetest.tsx

@@ -3,6 +3,7 @@ import {
   MultiSelectMenu,
   MenuContent,
   MenuHeader,
+  MenuItem,
   MenuFooter,
 } from "../../index";
 
@@ -20,6 +21,17 @@ export const MultiSelectMenuTypeTest = () => (
       <MenuContent>Test</MenuContent>
       <MenuFooter>Test</MenuFooter>
     </MultiSelectMenu>
+    {/* Valid MultiSelectMenu allows menuItems to be passed using the menuItems prop */}
+    <MultiSelectMenu
+      menuToggleElement={<>test</>}
+      menuItems={[{ children: "Item Name", id: "item-1" }]}
+    />
+    {/* Valid MultiSelectMenu allows menuItems prop to be rendered using a MenuItemComponent prop */}
+    <MultiSelectMenu
+      menuToggleElement={<>test</>}
+      menuItems={[{ children: "Item Name", id: "item-1" }]}
+      MenuItemComponent={MenuItem}
+    />
     {/* Valid MultiSelectMenu accepts Downshift props and functions for useSelect */}
     <MultiSelectMenu
       menuToggleElement={<>test</>}
@@ -52,8 +64,23 @@ export const MultiSelectMenuTypeTest = () => (
     >
       Test
     </MultiSelectMenu>
-    {/* @ts-expect-error - when no children provided */}
-    <MultiSelectMenu menuToggleElement="test" />
+    {/* @ts-expect-error - when no children or items provided */}
+    <MultiSelectMenu menuToggleElement={<>test</>} />
+    {/* @ts-expect-error - when both children and MenuItemComponent provided */}
+    <MultiSelectMenu menuToggleElement={<>test</>} MenuItemComponent={MenuItem}>
+      Children
+    </MultiSelectMenu>
+    {/* @ts-expect-error - when both children and menuItems provided */}
+    <MultiSelectMenu menuToggleElement={<>test</>} menuItems={[]}>
+      Children
+    </MultiSelectMenu>
+    <MultiSelectMenu
+      menuToggleElement={<>test</>}
+      /* @ts-expect-error - when MenuItemComponent is of the wrong type */
+      MenuItemComponent={MenuContent}
+    >
+      Children
+    </MultiSelectMenu>
 
     <MultiSelectMenu
       menuToggleElement={<>test</>}

package/src/NestedMenu/NestedMenu.feature

@@ -0,0 +1,109 @@
+Feature: NestedMenu
+
+  A menu component that allows users to navigate through hierarchical menus
+
+  Rule: User behavior
+    Background:
+      Given an end user is using the component
+
+    Scenario: User can open the NestedMenu root menu
+        Given the NestedMenu is closed
+        When the menu button is clicked
+        Then it should open the parent NestedMenu
+
+    Scenario: User can open a child menu
+      Given the NestedMenu is open
+      When an item with a childMenuId is clicked
+      Then it should display the corresponding child menu
+
+    Scenario: User can view one child menu at a time
+        Given the NestedMenu is open
+        When a child menu is displayed
+        Then the parent menu is hidden
+
+    Scenario: User can return to a previous menu
+      Given the NestedMenu is open
+      And a child menu is displayed
+      Then the back button is visible
+      When the back button is clicked
+      Then it should return to the previous menu
+
+    Scenario: User can select a child menu without closing the menu
+        Given the NestedMenu is open
+        When an menu item that triggers a child menu is clicked
+        Then the menu will stay open
+        And the menu will not use its default open/close behavior
+
+  Rule: API
+    Background:
+      Given an engineer is implementing a NestedMenu
+
+    Scenario: NestedMenu accepts an initialMenuId prop
+        Given the NestedMenu is open
+        And an initialMenuId is passed
+        Then the corresponding menu should be displayed
+
+    Scenario: NestedMenu requires a menus prop
+        Given the NestedMenu is open
+        And a menus prop is not passed
+        Then the NestedMenu should not render
+
+    Scenario: NestedMenu only displays one menu at a time
+        Given the NestedMenu is open
+        And a child menu is being displayed
+        Then none of the parent or sibling menus should be displayed
+
+    Scenario: NestedMenu accepts an onBackButtonClick prop
+        Given the NestedMenu is open
+        And an onBackButtonClick function is passed
+        When the back button is clicked
+        Then the onBackButtonClick function should be called
+
+    Scenario Outline: NestedMenu can render MenuComponents
+      Given the NestedMenu is open
+      When the visible menu's MenuComponent is <MenuComponent>
+      Then a <MenuComponent> should be rendered with menuProps
+      And the menuProps should be of type <menuPropsType>
+
+      Examples:
+        | MenuComponent    | menuPropsType            |
+        |------------------|--------------------------|
+        | ActionMenu       | TypeActionMenuProps      |
+        | SingleSelectMenu | TypeSingleSelectMenuProps|
+        | MultiSelectMenu  | TypeMultiSelectMenuProps |
+
+
+    Scenario: A Menu stays open when a menu item with a childMenuId is clicked
+      Given the NestedMenu is open
+      When an menu item that triggers a child menu is clicked
+      Then the menu will stay open
+      And the menu will not use its default open/close behavior
+
+    Scenario Outline: A Menu inherits its MenuComponent's open/close behavior for items without a childMenuId
+      Given the NestedMenu is open
+      And the visible menu's MenuComponent is <MenuComponent>
+      When an item without a childMenuId is clicked
+      And the <MenuComponent> will inherit its default behavior of <onClickBehavior>
+
+      Examples:
+        | MenuComponent    | onClickBehavior |
+        |------------------|--------------   |
+        | ActionMenu       | closing         |
+        | SingleSelectMenu | not closing     |
+        | MultiSelectMenu  | not closing     |
+
+    Scenario: NestedMenu renders a MenuHeaderComponent
+      Given the NestedMenu is open
+      And the visible menu's MenuHeaderComponent is not null
+      Then the MenuHeaderComponent should be rendered with menuHeaderProps
+
+    Scenario Outline: NestedMenu checks its types
+      When `<propName>` is passed a value
+      Then NestedMenu expects it to be of type `<propType>`
+
+      Examples: Prop Types
+        | propName              | propType                                                                         |
+        | --------------------- | -------------------------------------------------------------------------------- |
+        | menus                 | Record<string, {MenuComponent, menuProps, MenuHeaderComponent, menuHeaderProps}> |
+        | selectedMenuId        | string                                                                           |
+        | onBackButtonClick     | function                                                                         |

package/src/NestedMenu/NestedMenu.stories.tsx

@@ -0,0 +1,157 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Box } from "@sproutsocial/seeds-react-box";
+// eslint-disable-next-line no-restricted-imports
+import { TEST_BOOKS } from "../__fixtures__/menu-test-data";
+
+import {
+  ActionMenu,
+  SingleSelectMenu,
+  MenuToggleButton,
+  MultiSelectMenu,
+  NestedMenu,
+} from "../index";
+import { NestedMenuItem } from "./NestedMenuItem";
+import { NestedMenuContent } from "./NestedMenuContent";
+
+type CustomNestedMenuArgs = React.ComponentProps<typeof NestedMenu>;
+
+const meta: Meta<CustomNestedMenuArgs> = {
+  title: "Under Development/NestedMenu",
+  component: NestedMenu,
+  parameters: {
+    controls: {
+      expanded: true,
+    },
+  },
+  decorators: [
+    (Story) => (
+      <Box display="flex" flexDirection="column" gap="16px" maxWidth={300}>
+        <Story />
+      </Box>
+    ),
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj<CustomNestedMenuArgs>;
+
+const menus = {
+  root: {
+    MenuComponent: ActionMenu,
+    menuProps: {
+      menuItems: [
+        {
+          id: "parent-1",
+          children: "Open inner menu",
+          childMenuId: "inner",
+        },
+        {
+          id: "other-root",
+          children: "No child menu",
+        },
+      ],
+    },
+    MenuHeaderComponent: null,
+  },
+  inner: {
+    MenuComponent: ActionMenu,
+    menuProps: {
+      children: (
+        <NestedMenuContent>
+          <NestedMenuItem
+            id="item-2"
+            children="Books as ActionMenu"
+            childMenuId="books-action"
+          />
+          <NestedMenuItem
+            id="item-3"
+            children="Books as MultiSelect"
+            childMenuId="books-multiselect"
+          />
+          <NestedMenuItem
+            id="item-4"
+            children="Books as SingleSelect"
+            childMenuId="books-select"
+          />
+        </NestedMenuContent>
+      ),
+    },
+    menuHeaderProps: {
+      title: "Inner Menu",
+    },
+  },
+  "books-action": {
+    MenuComponent: ActionMenu,
+    menuProps: {
+      menuItems: TEST_BOOKS.map((book) => ({
+        id: book.id,
+        children: book.title,
+        childMenuId: "edit-book",
+      })),
+    },
+    menuHeaderProps: {
+      title: "Manage Books",
+    },
+  },
+  "books-multiselect": {
+    MenuComponent: MultiSelectMenu,
+    menuProps: {
+      menuItems: TEST_BOOKS.map((book) => ({
+        id: book.id,
+        children: book.title,
+      })),
+    },
+    menuHeaderProps: {
+      title: "Select Books",
+    },
+  },
+  "books-select": {
+    MenuComponent: SingleSelectMenu,
+    menuProps: {
+      menuItems: TEST_BOOKS.map((book) => ({
+        id: book.id,
+        children: book.title,
+      })),
+    },
+    menuHeaderProps: {
+      title: "Select One Book",
+    },
+  },
+  "edit-book": {
+    MenuComponent: ActionMenu,
+    menuProps: {
+      menuItems: [
+        {
+          id: "archive",
+          children: "Archive",
+        },
+        {
+          id: "delete",
+          children: "Delete",
+        },
+      ],
+    },
+    menuHeaderProps: {
+      title: "Edit Book",
+      backArrowLabel: "Back to Books",
+    },
+  },
+};
+
+export const NestedMenuMultiLevelStory: Story = {
+  name: "Multi Level NestedMenu",
+  render: (args) => {
+    return (
+      <NestedMenu
+        initialMenuId="root"
+        menus={menus}
+        backArrowLabel="Go Back"
+        menuToggleElement={<MenuToggleButton>Open Menu</MenuToggleButton>}
+      />
+    );
+  },
+};

package/src/NestedMenu/NestedMenu.tsx

@@ -0,0 +1,102 @@
+import React, { useState } from "react";
+import type { TypeMenuItemProps } from "../MenuItem";
+import type {
+  TypeNestedMenuItemProps,
+  TypeNestedMenuProps,
+} from "./NestedMenuTypes";
+import { reduceReducers } from "../utils/reduceReducers";
+import { NestedMenuHeader } from "./NestedMenuHeader";
+import { nestedMenuStateReducer } from "../reducers/nestedMenuStateReducer";
+import { NestedMenuContent } from "./NestedMenuContent";
+import { NestedMenuProvider } from "./NestedMenuContext";
+import { NestedMenuItem } from "./NestedMenuItem";
+
+export const NestedMenu = <
+  I extends TypeMenuItemProps = TypeNestedMenuItemProps
+>({
+  initialMenuId,
+  menus,
+  onBackButtonClick,
+  backArrowLabel,
+  menuToggleElement,
+}: TypeNestedMenuProps<I>) => {
+  const [selectedMenuPath, setSelectedMenuPath] = useState([initialMenuId]);
+  const selectedMenuId = selectedMenuPath[selectedMenuPath.length - 1];
+
+  const setSelectedMenuId = (id: string) => {
+    setSelectedMenuPath((currentPath) => [...currentPath, id]);
+  };
+  const goBack = () => {
+    setSelectedMenuPath((currentPath) => currentPath.slice(0, -1));
+    onBackButtonClick?.(selectedMenuId);
+  };
+
+  const {
+    MenuComponent,
+    menuProps,
+    MenuHeaderComponent = NestedMenuHeader,
+    menuHeaderProps = {},
+  } = menus[selectedMenuId] || {};
+  const {
+    children,
+    menuItems,
+    MenuItemComponent,
+    stateReducer: externalStateReducer,
+    onStateChange: externalOnStateChange,
+    ...props
+  } = menuProps || {};
+
+  const stateReducer = reduceReducers(
+    nestedMenuStateReducer,
+    externalStateReducer
+  );
+
+  // Reactively reset the selected menu path when the menu closes
+  const onStateChange = (changes) => {
+    externalOnStateChange?.(changes);
+    if (changes.isOpen === false) {
+      // Wait for the menu to close before resetting to avoid flicker
+      setTimeout(() => {
+        setSelectedMenuPath([initialMenuId]);
+      }, 100);
+    }
+  };
+
+  const nestedMenuProps = {
+    menuToggleElement,
+    stateReducer,
+    onStateChange,
+    initialIsOpen: selectedMenuPath.length > 1,
+    children: (
+      <>
+        {/*This header can be suppressed by passing `null` for MenuHeaderComponent*/}
+        {MenuHeaderComponent && (
+          <MenuHeaderComponent
+            backArrowLabel={backArrowLabel}
+            {...menuHeaderProps}
+          />
+        )}
+        {/*children takes precedence over menuItems if both are passed.*/}
+        {children && children}
+        {menuItems && !children && (
+          <NestedMenuContent
+            menuItems={menuItems}
+            MenuItemComponent={MenuItemComponent ?? NestedMenuItem}
+          />
+        )}
+      </>
+    ),
+    ...props,
+  };
+
+  return (
+    <NestedMenuProvider
+      selectedMenuPath={selectedMenuPath}
+      setSelectedMenuPath={setSelectedMenuPath}
+      setSelectedMenuId={setSelectedMenuId}
+      goBack={goBack}
+    >
+      {MenuComponent && <MenuComponent {...nestedMenuProps} />}
+    </NestedMenuProvider>
+  );
+};

package/src/NestedMenu/NestedMenuContent.tsx

@@ -0,0 +1,71 @@
+import { MenuContent, type TypeMenuContentProps } from "../MenuContent/index";
+import { useMenuContentContext } from "../MenuContext";
+import type { TypeChildrenOrItems, TypeInternalItemProps } from "../types";
+import { useNestedMenuContext } from "./NestedMenuContext";
+import type { TypeMenuItemProps } from "../MenuItem/index";
+import type { TypeNestedMenuItemProps } from "./NestedMenuTypes";
+import { useEffect, useRef } from "react";
+import { mergeRefs } from "@sproutsocial/seeds-react-utilities/src/index";
+import { NestedMenuItem } from "./NestedMenuItem";
+
+export const NestedMenuContent = <
+  I extends TypeMenuItemProps = TypeNestedMenuItemProps
+>({
+  innerRef: innerRefProp = null,
+  onKeyDown: onKeyDownProp,
+  children,
+  menuItems,
+  MenuItemComponent = NestedMenuItem,
+  ...props
+}: TypeMenuContentProps<I>) => {
+  const { highlightedIndex, items } = useMenuContentContext();
+  const { setSelectedMenuId, selectedMenuPath, goBack } =
+    useNestedMenuContext();
+  const internalRef = useRef<HTMLUListElement>(null);
+  // Merge our ref and the consumer's ref so they will both be updated
+  const innerRef = mergeRefs<HTMLUListElement>(internalRef, innerRefProp);
+
+  const contentProps = children
+    ? { children }
+    : ({ menuItems, MenuItemComponent } as TypeChildrenOrItems<I>);
+
+  // Focus the content on mount so that keyboard nav is available immediately
+  useEffect(() => {
+    internalRef?.current?.focus();
+  }, []);
+
+  const onKeyDown = (e) => {
+    // Call the consumer's onKeyDown handler first
+    onKeyDownProp?.(e);
+
+    // Handle navigating into and out of child menus
+    switch (e.key) {
+      case "ArrowRight":
+      case " ":
+      case "Enter":
+        if (highlightedIndex !== undefined && highlightedIndex !== -1) {
+          const item = items[
+            highlightedIndex
+          ] as TypeInternalItemProps<TypeNestedMenuItemProps>;
+          if (item?.menuItemProps?.childMenuId !== undefined) {
+            setSelectedMenuId?.(item?.menuItemProps?.childMenuId);
+          }
+        }
+        break;
+      case "ArrowLeft":
+        if (selectedMenuPath.length > 1) {
+          goBack?.();
+        }
+        break;
+    }
+  };
+
+  return (
+    <MenuContent
+      onKeyDown={onKeyDown}
+      innerRef={innerRef}
+      {...contentProps}
+      {...props}
+    />
+  );
+};