@sproutsocial/seeds-react-menu 0.5.0 → 1.0.0

package/src/SubmenuItem/SubmenuItem.feature

@@ -0,0 +1,82 @@
+Scenario: SubmenuItem is expandable via click
+  Given a SubmenuItem is not disabled
+  When the SubmenuItem is clicked
+  Then the submenu should be displayed
+
+Scenario Outline: SubmenuItem can be expanded via keyboard
+  Given a SubmenuItem is focused
+  And the SubmenuItem is not disabled
+  When the SubmenuItem is triggered via <interaction>
+  Then the submenu should be displayed
+
+  Examples:
+    | interaction            |
+    | pressing the Enter key |
+    | pressing the Space key |
+    | pressing the Right Arrow key |
+
+Scenario Outline: SubmenuItem is disabled
+  Given a SubmenuItem is disabled
+  When the SubmenuItem is triggered via <interaction>
+  Then no events should fire
+  And the submenu should not be displayed
+
+  Examples:
+    | interaction                         |
+    | clicking                            |
+    | focusing and pressing the Enter key |
+    | focusing and pressing the Space key |
+    | focusing and pressing the Right Arrow key |
+
+Scenario: SubmenuItem displays an arrow indicator
+  Given a SubmenuItem is rendered
+  Then it should display an arrow icon indicating a submenu
+
+Scenario: SubmenuItem can be collapsed via keyboard
+  Given a SubmenuItem is expanded
+  And the submenu is displayed
+  When the Left Arrow key is pressed
+  Then the submenu should be hidden
+
+  Rule: API
+    Background:
+      Given an engineer is developing using the component
+
+  Scenario Outline: SubmenuItem accepts children
+  When <child component(s)> provided
+  Then the SubmenuItem should render the <component(s)>
+
+  Examples: child components
+    | child component(s)       | component(s)    |
+    | a Link is                | Link            |
+    | a Text is                | Text            |
+    | an Icon is               | Icon            |
+    | a Text then an Icon are  | Text and Icon   |
+    | an Icon and Text are     | Icon and Text   |
+
+Scenario Outline: A SubmenuItem accepts system props
+  When a system prop from the category <systemPropCategory> is passed a value
+  Then the SubmenuItem will have <systemPropName> styling
+
+  Examples: System Props
+    | systemPropCategory   | systemPropName |
+    | color                | bg             |
+    | border               | borderColor    |
+    | layout               | display        |
+    | position             | zIndex         |
+    | flexbox              | flex           |
+    | grid                 | gridGap        |
+    | space                | p              |
+
+Scenario Outline: SubmenuItem validates prop types
+  When any <propName> is passed to the SubmenuItem
+  Then the SubmenuItem should check that each <propName> is of the expected <propType>
+
+  Examples: Prop Types
+    | propName  | propType                   |
+    | children  | ReactNode                  |
+    | disabled  | boolean                    |
+    | elevation | low, medium, or high       |
+    | href      | string                     |
+    | onClick   | React.MouseEventHandler    |
+    | role      | string                     |

package/src/SubmenuItem/SubmenuItem.stories.tsx

@@ -0,0 +1,163 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { action } from "@storybook/addon-actions";
+import { Box } from "@sproutsocial/seeds-react-box";
+import {
+  MenuItem,
+  MenuToggleButton,
+  MenuContent,
+  ActionMenu,
+  MenuGroup,
+  SubmenuItem,
+  type TypeMenuItemProps,
+} from "../index";
+
+type SubmenuItemStoryArgs = TypeMenuItemProps & {
+  text?: string;
+};
+
+type Story = StoryObj<SubmenuItemStoryArgs>;
+
+const meta: Meta<SubmenuItemStoryArgs> = {
+  title: "Under Development/Submenu",
+  decorators: [(Story) => <Story />],
+};
+
+export default meta;
+
+const StoryMenuToggleButton = ({ appearance, triggerText }) => {
+  return (
+    <MenuToggleButton appearance={appearance} alignSelf="flex-start">
+      {triggerText}
+    </MenuToggleButton>
+  );
+};
+
+const handleOnClick = (e: React.MouseEvent<HTMLElement>, itemName: string) => {
+  action(`${itemName}`)(e);
+};
+
+const submenuItems: TypeMenuItemProps[] = [
+  { id: "item1", children: "Option 1" },
+  { id: "item2", children: "Option 2" },
+  { id: "item3", children: "Option 3" },
+];
+
+export const SubmenuItemStory: Story = {
+  name: "Simple Action Menu",
+  render: (args) => {
+    return (
+      <ActionMenu
+        {...args}
+        menuToggleElement={
+          <StoryMenuToggleButton
+            appearance={args["Trigger Appearance"]}
+            triggerText={"Button"}
+          />
+        }
+        onStateChange={(changes) => action("onStateChange")(changes)}
+      >
+        <MenuContent>
+          <MenuGroup id="actions">
+            <MenuItem onClick={(e) => handleOnClick(e, "Compose")} id="Compose">
+              Compose
+            </MenuItem>
+            <SubmenuItem
+              id="sj"
+              MenuComponent={ActionMenu}
+              menuProps={{
+                menuItems: submenuItems,
+                onStateChange: (changes) =>
+                  action("submenu onStateChange")(changes),
+              }}
+            >
+              Basic Item
+            </SubmenuItem>
+            <MenuItem
+              onClick={(e) => handleOnClick(e, "View Messages")}
+              id="View Messages"
+            >
+              View Messages
+            </MenuItem>
+            <MenuItem
+              onClick={(e) => handleOnClick(e, "Analyze post")}
+              id="Analyze post"
+            >
+              Analyze post
+            </MenuItem>
+            <MenuItem
+              href="https://sproutsocial.com"
+              target="_blank"
+              id="settings"
+            >
+              This Opens a Link
+            </MenuItem>
+          </MenuGroup>
+        </MenuContent>
+      </ActionMenu>
+    );
+  },
+};
+
+const children = (
+  <MenuContent>
+    <MenuItem id="sub-menu-item-1">Item 1</MenuItem>
+    <SubmenuItem
+      id="subsub"
+      MenuComponent={ActionMenu}
+      menuProps={{ menuItems: submenuItems }}
+    >
+      Another one
+    </SubmenuItem>
+  </MenuContent>
+);
+
+export const NestedSubmenuItemStory: Story = {
+  name: "Nested Submenus",
+  render: (args) => {
+    return (
+      <ActionMenu
+        {...args}
+        menuToggleElement={
+          <StoryMenuToggleButton
+            appearance={args["Trigger Appearance"]}
+            triggerText={"Button"}
+          />
+        }
+      >
+        <MenuContent>
+          <MenuGroup id="actions">
+            <MenuItem onClick={(e) => handleOnClick(e, "Compose")} id="Compose">
+              Compose
+            </MenuItem>
+            <SubmenuItem
+              id="sj"
+              MenuComponent={ActionMenu}
+              menuProps={{ children }}
+            >
+              Basic Item
+            </SubmenuItem>
+            <MenuItem
+              onClick={(e) => handleOnClick(e, "View Messages")}
+              id="View Messages"
+            >
+              View Messages
+            </MenuItem>
+            <MenuItem
+              onClick={(e) => handleOnClick(e, "Analyze post")}
+              id="Analyze post"
+            >
+              Analyze post
+            </MenuItem>
+            <MenuItem
+              href="https://sproutsocial.com"
+              target="_blank"
+              id="settings"
+            >
+              This Opens a Link
+            </MenuItem>
+          </MenuGroup>
+        </MenuContent>
+      </ActionMenu>
+    );
+  },
+};

package/src/SubmenuItem/SubmenuItem.tsx

@@ -0,0 +1,258 @@
+import React from "react";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import { Box } from "@sproutsocial/seeds-react-box";
+import { mergeRefs } from "@sproutsocial/seeds-react-utilities";
+import type { TypeInternalItemProps } from "../types";
+import { getChildrenFromMenuItems } from "../hooks/useMenuChildren";
+import { useMenuContentContext, useMenuToggleContext } from "../MenuContext";
+import {
+  MenuItem,
+  MenuItemActionRight,
+  type TypeMenuItemProps,
+} from "../MenuItem";
+import type {
+  TypeSubmenuItemProps,
+  TypeSubmenuValidMenuComponentProps,
+} from "./SubmenuItemTypes";
+
+const SubmenuItemTrigger = ({
+  id,
+  children,
+  innerRef,
+  ...rest
+}: TypeMenuItemProps) => {
+  const { getToggleButtonProps, getDropdownProps, ref, ariaProps } =
+    useMenuToggleContext();
+  const toggleRef =
+    ref && innerRef
+      ? mergeRefs([ref, innerRef].filter(Boolean))
+      : ref || innerRef;
+  return (
+    <MenuItem
+      {...rest}
+      {...getToggleButtonProps?.(
+        {
+          ...(getDropdownProps?.({
+            ref: toggleRef,
+            preventKeyAction: true,
+          }) || { ref: toggleRef }),
+          refKey: "innerRef",
+          role: "menuitem",
+          ...ariaProps,
+        },
+        { suppressRefError: true }
+      )}
+      id={id}
+    >
+      <Box display="flex" justifyContent="space-between">
+        {children}
+        <MenuItemActionRight>
+          <Icon name="chevron-right-outline" />
+        </MenuItemActionRight>
+      </Box>
+    </MenuItem>
+  );
+};
+
+const doesRefContainEventTarget = (
+  ref: React.RefObject<HTMLElement | undefined>,
+  event: MouseEvent
+) => {
+  return (
+    ref.current &&
+    event.target instanceof Node &&
+    ref.current.contains(event.target)
+  );
+};
+
+const SubmenuItem = <
+  I extends TypeMenuItemProps,
+  P extends TypeSubmenuValidMenuComponentProps<I>
+>({
+  MenuComponent,
+  menuProps: {
+    children: menuChildren,
+    menuItems,
+    MenuItemComponent,
+    popoutProps: { popperProps, ...popoutProps } = {},
+    onStateChange,
+    ...menuProps
+  },
+  // isOpen,
+  // onToggleSubmenu,
+  id,
+  children,
+  ...rest
+}: TypeSubmenuItemProps<I, P>) => {
+  const {
+    highlightedIndex,
+    setHighlightedIndex,
+    itemsMap,
+    isOpen: parentIsOpen,
+  } = useMenuContentContext();
+  const [submenuIsFocused, setSubmenuIsFocused] = React.useState(false);
+  const [submenuIsOpen, setSubmenuIsOpen] = React.useState(false);
+  const [submenuIsActive, setSubmenuIsActive] = React.useState(false);
+  const submenuItemRef = React.useRef<HTMLElement>(null);
+  const submenuRef = React.useRef<HTMLDivElement>(null);
+
+  // get children for both use cases so it can be wrapped in a submenu div
+  const menuContent = menuItems
+    ? getChildrenFromMenuItems({ menuItems, MenuItemComponent })
+    : menuChildren;
+
+  const item = (itemsMap[id] || {
+    index: 0,
+    id,
+  }) as TypeInternalItemProps;
+
+  // React.useEffect(() => {
+  //   debugger;
+  //   // reset isOpen on render
+  //   setSubmenuIsOpen(false);
+  //   setSubmenuIsActive(false);
+  // }, []);
+
+  React.useEffect(() => {
+    if (highlightedIndex === item.index) {
+      // Open submenu when item becomes highlighted
+      !submenuIsOpen && setSubmenuIsOpen(true);
+    } else if (submenuIsOpen && highlightedIndex !== -1) {
+      // Close submenu when another item is highlighted
+      setSubmenuIsOpen(false);
+      setSubmenuIsActive(false);
+    }
+  }, [highlightedIndex, item.index, submenuIsOpen, setSubmenuIsOpen]);
+
+  const onSubmenuStateChange = React.useCallback(
+    (state) => {
+      if (state.isOpen !== undefined) {
+        // Ensures the menu opens and closes when the state changes
+        setSubmenuIsOpen(state.isOpen);
+        if (!state.isOpen) {
+          // Reset the submenu focus and highlighted index when the submenu closes
+          setSubmenuIsFocused(false);
+          setHighlightedIndex?.(-1);
+        }
+      }
+      onStateChange?.(state);
+    },
+    [onStateChange, setSubmenuIsOpen]
+  );
+
+  // Callback for navigating the submenu wit harrow keys
+  const onSubmenuKeydown = (e: KeyboardEvent): void => {
+    switch (e.key) {
+      case "ArrowRight":
+      case " ":
+      case "Enter":
+        // Focus the submenu if item highlighted and right arrow key is pressed
+        if (!submenuIsFocused && submenuIsOpen) {
+          // stop propagation to avoid interacting with other components
+          e.stopPropagation();
+          setSubmenuIsFocused(true);
+        }
+        break;
+      case "ArrowLeft":
+        // Return focus to the parent menu if submenu is focused and left arrow key is pressed
+        if (submenuIsFocused) {
+          // stop propagation to avoid interacting with other components
+          e.stopPropagation();
+          setSubmenuIsFocused(false);
+        }
+        break;
+      default:
+        break;
+    }
+  };
+
+  const onMenuItemClick = () => {
+    const newIsActive = !submenuIsActive;
+    // Lock the submenu in an active open state when clicked
+    // or close the menu and unlock if it is open
+    setSubmenuIsActive(newIsActive);
+    setSubmenuIsOpen(newIsActive);
+  };
+
+  const onBodyClick = (e: MouseEvent): void => {
+    // Prevent closing the parent menu when clicking on the submenu item
+    if (doesRefContainEventTarget(submenuItemRef, e)) {
+      e.stopPropagation();
+      onMenuItemClick();
+    }
+    // Prevent closing other popouts when clicking on inside the submenu
+    // This doesn't work because it's overridden by the logic in Popout the closes when clicked outside
+    // if (doesRefContainEventTarget(submenuRef, e)) {
+    //   e.stopPropagation();
+    // }
+  };
+
+  React.useEffect(() => {
+    if (document && document.body) {
+      document.body.addEventListener("click", onBodyClick, {
+        capture: true,
+      });
+      document.body.addEventListener("keydown", onSubmenuKeydown, {
+        capture: true,
+      });
+      return () => {
+        document.body.removeEventListener("click", onBodyClick, {
+          capture: true,
+        });
+        document.body.removeEventListener("keydown", onSubmenuKeydown, {
+          capture: true,
+        });
+      };
+    }
+  }, [document, onSubmenuKeydown]);
+
+  const subMenuContent = (
+    <div
+      ref={submenuRef}
+      onKeyDown={(e) => {
+        // prevent keydown on submenu triggering the parent menu
+        e.stopPropagation();
+      }}
+      tabIndex={-1}
+    >
+      {menuContent}
+    </div>
+  );
+
+  return (
+    <MenuComponent
+      {...({
+        ...menuProps,
+        children: subMenuContent,
+        menuToggleElement: (
+          <SubmenuItemTrigger
+            innerRef={submenuItemRef}
+            id={id}
+            children={children}
+            active={submenuIsActive}
+            {...rest}
+          />
+        ),
+        isOpen: submenuIsOpen,
+        onStateChange: onSubmenuStateChange,
+        popoutProps: {
+          placement: "right",
+          popperProps: {
+            modifiers: {
+              offset: {
+                offset: "0,18",
+              },
+            },
+            ...popperProps,
+          },
+          focusOnContent: submenuIsFocused,
+          ...popoutProps,
+        },
+      } as P)}
+    />
+  );
+};
+
+SubmenuItem.__MENU_PRIMITIVE_TYPE = "MenuItem";
+
+export { SubmenuItem };

package/src/SubmenuItem/SubmenuItemTypes.ts

@@ -0,0 +1,24 @@
+import type { TypeActionMenuProps } from "../ActionMenu";
+import type { TypeSingleSelectMenuProps } from "../SingleSelectMenu";
+import type { TypeMultiSelectMenuProps } from "../MultiSelectMenu";
+import type { TypeMenuItemProps } from "../MenuItem";
+import type { TypeMenuRootProps } from "../MenuRoot";
+import type { TypeChildrenOrItems } from "../types";
+
+export type TypeSubmenuValidMenuComponentProps<I extends TypeMenuItemProps> =
+  TypeChildrenOrItems<I> &
+    (
+      | TypeActionMenuProps<I>
+      | TypeSingleSelectMenuProps<I>
+      | TypeMultiSelectMenuProps<I>
+    );
+
+export interface TypeSubmenuItemProps<
+  I extends TypeMenuItemProps,
+  P extends TypeSubmenuValidMenuComponentProps<I>
+> extends TypeMenuItemProps {
+  isOpen?: boolean;
+  onToggleSubmenu?: (isOpen: boolean) => void;
+  MenuComponent: React.ComponentType<P>;
+  menuProps: Omit<P, "menuToggleElement">;
+}

package/src/SubmenuItem/__tests__/SubmenuItem.test.tsx

@@ -0,0 +1,3 @@
+describe("SubmenuItem", () => {
+  xit("placeholder", () => {});
+});

package/src/SubmenuItem/__tests__/SubmenuItem.typetest.tsx

@@ -0,0 +1,112 @@
+import { SubmenuItem } from "../SubmenuItem";
+import { ActionMenu } from "../../index";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function SubmenuItemTypetest() {
+  return (
+    <>
+      {/* Valid SubmenuItem with minimal required props */}
+      <SubmenuItem id="test" MenuComponent={ActionMenu} menuProps={{}}>
+        Test
+      </SubmenuItem>
+      {/* Valid SubmenuItem allows href */}
+      <SubmenuItem
+        id="test"
+        href="test.com"
+        MenuComponent={ActionMenu}
+        menuProps={{}}
+      >
+        Test
+      </SubmenuItem>
+      {/* Valid SubmenuItem allows active prop */}
+      <SubmenuItem id="test" active MenuComponent={ActionMenu} menuProps={{}}>
+        Test
+      </SubmenuItem>
+      {/* Valid SubmenuItem allows active prop false */}
+      <SubmenuItem
+        id="test"
+        active={false}
+        MenuComponent={ActionMenu}
+        menuProps={{}}
+      >
+        Test
+      </SubmenuItem>
+      {/* Valid SubmenuItem allows inputType prop to be checkbox */}
+      <SubmenuItem
+        id="test"
+        inputType="checkbox"
+        MenuComponent={ActionMenu}
+        menuProps={{}}
+      >
+        Test
+      </SubmenuItem>
+      {/* Valid SubmenuItem allows inputType prop to be radio */}
+      <SubmenuItem
+        id="test"
+        inputType="radio"
+        MenuComponent={ActionMenu}
+        menuProps={{}}
+      >
+        Test
+      </SubmenuItem>
+      {/* Valid SubmenuItem allows inputType prop to be switch */}
+      <SubmenuItem
+        id="test"
+        inputType="switch"
+        MenuComponent={ActionMenu}
+        menuProps={{}}
+      >
+        Test
+      </SubmenuItem>
+      {/* Valid SubmenuItem allows inputType prop to be icon */}
+      <SubmenuItem
+        id="test"
+        inputType="icon"
+        MenuComponent={ActionMenu}
+        menuProps={{}}
+      >
+        Test
+      </SubmenuItem>
+      {/* Valid SubmenuItem allows inputLabelId prop as a string */}
+      <SubmenuItem
+        id="test"
+        inputLabelId="Test Label"
+        MenuComponent={ActionMenu}
+        menuProps={{}}
+      >
+        Test
+      </SubmenuItem>
+
+      {/* @ts-expect-error - no children is invalid */}
+      <SubmenuItem id="foo" MenuComponent={ActionMenu} menuProps={{}} />
+      {/* @ts-expect-error - missing id is invalid */}
+      <SubmenuItem MenuComponent={ActionMenu} menuProps={{}}>
+        Test
+      </SubmenuItem>
+      {/* @ts-expect-error - missing MenuComponent is invalid */}
+      <SubmenuItem id="foo" menuProps={{}}>
+        Test
+      </SubmenuItem>
+      {/* @ts-expect-error - missing menuProps is invalid */}
+      <SubmenuItem id="foo" MenuComponent={ActionMenu}>
+        Test
+      </SubmenuItem>
+      <SubmenuItem
+        /* @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 - inputLabelId may not be a number */
+        inputLabelId={0}
+        /* @ts-expect-error - non-Menu component is invalid for MenuComponent */
+        MenuComponent={SubmenuItem}
+        /* @ts-expect-error - menuProps must be an object */
+        menuProps={false}
+      >
+        Test
+      </SubmenuItem>
+    </>
+  );
+}

package/src/SubmenuItem/index.ts

@@ -0,0 +1,2 @@
+export * from "./SubmenuItem";
+export * from "./SubmenuItemTypes";