@sproutsocial/seeds-react-menu 0.5.0 → 1.0.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 = [
@@ -53,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" });
@@ -64,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
@@ -72,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
@@ -112,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" });
 
@@ -121,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(() =>
@@ -136,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(() =>
@@ -173,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" });
@@ -237,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" });
@@ -290,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" });
 
@@ -299,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

@@ -21,15 +21,15 @@ export const MultiSelectMenuTypeTest = () => (
       <MenuContent>Test</MenuContent>
       <MenuFooter>Test</MenuFooter>
     </MultiSelectMenu>
-    {/* Valid MultiSelectMenu allows items to be passed using the items prop */}
+    {/* Valid MultiSelectMenu allows menuItems to be passed using the menuItems prop */}
     <MultiSelectMenu
       menuToggleElement={<>test</>}
-      items={[{ children: "Item Name", id: "item-1" }]}
+      menuItems={[{ children: "Item Name", id: "item-1" }]}
     />
-    {/* Valid MultiSelectMenu allows items prop to be rendered using a MenuItemComponent prop */}
+    {/* Valid MultiSelectMenu allows menuItems prop to be rendered using a MenuItemComponent prop */}
     <MultiSelectMenu
       menuToggleElement={<>test</>}
-      items={[{ children: "Item Name", id: "item-1" }]}
+      menuItems={[{ children: "Item Name", id: "item-1" }]}
       MenuItemComponent={MenuItem}
     />
     {/* Valid MultiSelectMenu accepts Downshift props and functions for useSelect */}
@@ -70,8 +70,8 @@ export const MultiSelectMenuTypeTest = () => (
     <MultiSelectMenu menuToggleElement={<>test</>} MenuItemComponent={MenuItem}>
       Children
     </MultiSelectMenu>
-    {/* @ts-expect-error - when both children and items provided */}
-    <MultiSelectMenu menuToggleElement={<>test</>} items={[]}>
+    {/* @ts-expect-error - when both children and menuItems provided */}
+    <MultiSelectMenu menuToggleElement={<>test</>} menuItems={[]}>
       Children
     </MultiSelectMenu>
     <MultiSelectMenu

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,75 @@
+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";
+
+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}
+    />
+  );
+};
+
+NestedMenuContent.__MENU_PRIMITIVE_TYPE = "MenuContent";
+
+export { NestedMenuContent };

package/src/NestedMenu/NestedMenuContext.tsx

@@ -0,0 +1,56 @@
+import React, { createContext, useContext } from "react";
+import type { TypeNotEmptyChildren } from "../types";
+
+export interface TypeNestedMenuContext {
+  selectedMenuPath: string[];
+  setSelectedMenuId?: (id: string) => void;
+  setSelectedMenuPath?: (path: string[]) => void;
+  goBack?: () => void;
+}
+
+const defaultNestedMenuContext: TypeNestedMenuContext = {
+  selectedMenuPath: [],
+  setSelectedMenuId: () => {},
+  setSelectedMenuPath: () => {},
+  goBack: () => {},
+};
+
+export interface TypeNestedMenuProviderProps extends TypeNestedMenuContext {
+  children: TypeNotEmptyChildren;
+}
+
+/**
+ * NestedMenuContext factory, sets the type and the initial object
+ */
+export const NestedMenuContext = createContext<TypeNestedMenuContext>(
+  defaultNestedMenuContext
+);
+
+/**
+ * Provider Component sets the context values in the provider
+ */
+export const NestedMenuProvider = ({
+  children,
+  ...nestedMenuProps
+}: TypeNestedMenuProviderProps) => {
+  return (
+    <NestedMenuContext.Provider value={nestedMenuProps}>
+      {children}
+    </NestedMenuContext.Provider>
+  );
+};
+
+/**
+ * Utility hook for consuming NestedMenuContext
+ */
+export const useNestedMenuContext = (): TypeNestedMenuContext => {
+  const nestedMenuContextValue = useContext(NestedMenuContext);
+
+  if (nestedMenuContextValue === null) {
+    throw new Error(
+      "useNestedMenuContext must be used within a <NestedMenuContext.Provider />"
+    );
+  }
+
+  return nestedMenuContextValue;
+};