@sproutsocial/seeds-react-menu 0.5.0 → 0.6.0

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}
+    />
+  );
+};

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;
+};

package/src/NestedMenu/NestedMenuHeader.tsx

@@ -0,0 +1,25 @@
+import { MenuHeader } from "../MenuHeader/index";
+import { useNestedMenuContext } from "./NestedMenuContext";
+import { Button } from "@sproutsocial/seeds-react-button";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import type { TypeNestedMenuHeaderProps } from "./NestedMenuTypes";
+
+export const NestedMenuHeader = ({
+  backArrowLabel,
+  ...props
+}: TypeNestedMenuHeaderProps) => {
+  const { goBack, selectedMenuPath } = useNestedMenuContext();
+  const showBackArrow = selectedMenuPath.length > 1;
+  return (
+    <MenuHeader
+      leftAction={
+        showBackArrow ? (
+          <Button onClick={goBack} ariaLabel={backArrowLabel}>
+            <Icon name="arrow-left" />
+          </Button>
+        ) : undefined
+      }
+      {...props}
+    />
+  );
+};

package/src/NestedMenu/NestedMenuItem.tsx

@@ -0,0 +1,37 @@
+import { MenuItem, MenuItemActionRight } from "../MenuItem/index";
+import { useNestedMenuContext } from "./NestedMenuContext";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import { Box } from "@sproutsocial/seeds-react-box";
+import type { TypeNestedMenuItemProps } from "./NestedMenuTypes";
+
+export const NestedMenuItem = ({
+  children,
+  childMenuId,
+  onClick: onClickProp,
+  ...rest
+}: TypeNestedMenuItemProps) => {
+  const { setSelectedMenuId } = useNestedMenuContext();
+  // This method of passing onClick is necessary because passing undefined for onClick
+  // behaves differently from not passing anything at all.
+  const onClickProps = childMenuId
+    ? {
+        onClick: (e) => {
+          onClickProp?.(e);
+          setSelectedMenuId?.(childMenuId);
+        },
+      }
+    : {};
+
+  return (
+    <MenuItem {...onClickProps} {...rest}>
+      <Box display="flex" justifyContent="space-between">
+        {children}
+        {childMenuId && (
+          <MenuItemActionRight>
+            <Icon name="arrow-right-outline" />
+          </MenuItemActionRight>
+        )}
+      </Box>
+    </MenuItem>
+  );
+};

package/src/NestedMenu/NestedMenuTypes.ts

@@ -0,0 +1,47 @@
+import type { TypeActionMenuProps } from "../ActionMenu";
+import type { TypeMultiSelectMenuProps } from "../MultiSelectMenu";
+import type { TypeSingleSelectMenuProps } from "../SingleSelectMenu";
+import type { TypeMenuItemProps } from "../MenuItem";
+import type { TypeMenuRootProps } from "../MenuRoot";
+import type { TypeMenuHeaderProps } from "../MenuHeader";
+import type { TypeChildrenOrItems } from "../types";
+
+export interface TypeNestedMenuMapProps<
+  P,
+  I extends TypeMenuItemProps = TypeNestedMenuItemProps
+> {
+  MenuComponent: React.ComponentType<P>;
+  menuProps: Omit<P, "menuToggleElement"> & TypeChildrenOrItems<I>;
+  /** Defaults to NestedMenuHeader if not provided.
+   *  This header can be suppressed by passing null.*/
+  MenuHeaderComponent?: React.ComponentType<TypeMenuHeaderProps> | null;
+  menuHeaderProps?: Partial<TypeMenuHeaderProps>;
+}
+
+export interface TypeNestedMenuHeaderProps extends TypeMenuHeaderProps {
+  /** Localized label for the back arrow in this child menu.
+   *  Overrides the default label passed to NestedMenu. */
+  backArrowLabel?: string;
+}
+
+export interface TypeNestedMenuItemProps extends TypeMenuItemProps {
+  childMenuId?: string;
+}
+
+export interface TypeNestedMenuProps<
+  I extends TypeMenuItemProps = TypeNestedMenuItemProps
+> {
+  initialMenuId: string;
+  menuToggleElement: TypeMenuRootProps["menuToggleElement"];
+  onBackButtonClick?: (menuId: string) => void;
+  /** Sets the default localized label for the back arrow in all child menus.
+   *  This label can be overridden by including backArrowLabel in a menu's menuHeaderProps. */
+  backArrowLabel?: string;
+  /** An object of the menus and child menus to be displayed, keyed by id.*/
+  menus: {
+    [id: string]:
+      | TypeNestedMenuMapProps<TypeActionMenuProps<I>, I>
+      | TypeNestedMenuMapProps<TypeSingleSelectMenuProps<I>, I>
+      | TypeNestedMenuMapProps<TypeMultiSelectMenuProps<I>, I>;
+  };
+}

package/src/NestedMenu/__tests__/NestedMenu.test.tsx

@@ -0,0 +1,31 @@
+/* eslint-disable testing-library/no-unnecessary-act */
+import {
+  NestedMenu,
+  MenuContent,
+  MenuToggleButton,
+  MenuItem,
+  MenuGroup,
+} from "../../index";
+import {
+  render,
+  screen,
+  cleanup,
+  waitFor,
+} from "@sproutsocial/seeds-react-testing-library";
+
+const menuItems = [
+  { id: "test-item-1", index: 0, label: "Item 1" },
+  { id: "test-item-2", index: 1, label: "Item 2" },
+  { id: "test-item-3", index: 2, label: "Item 3" },
+  { id: "test-item-4", index: 3, label: "Item 4" },
+];
+
+describe("NestedMenu", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("runs", () => {
+    expect(true).toBe(true);
+  });
+});