@sproutsocial/seeds-react-menu 0.1.0

package/src/MenuHeader/MenuHeader.feature

@@ -0,0 +1,59 @@
+Feature: Menu Header
+
+  The top area of a Menu.
+
+  Rule: API
+    Background:
+      Given an engineer is implementing a MenuHeader
+
+      Scenario: Display MenuHeader with a title
+        When the "title" prop is provided
+        And the title is a String
+        Then the MenuHeader should display the title
+
+      Scenario: Display MenuHeader with an empty or non-string title
+        When an empty or non-string title is provided
+        Then the MenuHeader should not display the title
+
+      Scenario Outline: MenuHeader supports children
+        When <child component(s)> provided
+        Then the MenuHeader should render the <component(s)>
+
+        Examples: Child Components
+          | child component(s)       | component(s)     |
+          | Text is                  | Text             |
+          | a Banner is              | Banner           |
+          | a MenuHeaderInput is     | MenuHeaderInput  |
+          | Text and a Banner are    | Text and Banner  |
+
+      Scenario Outline: Actions can be triggered from the MenuHeader
+        Given that actionable elements are provided to the MenuHeader
+        When a <action> is clicked
+        Then the corresponding onClick should be executed
+
+        Examples: Action Types
+          | action                     |
+          | back button                |
+          | link button                |
+
+      Scenario Outline: Actions can appear on the left or right of the MenuHeader title
+        When an action is provided <action position>
+        Then the action(s) should be rendered
+
+        Examples: action position
+          | before the header title                |
+          | after the header title                 |
+          | before and after the header title      |
+
+      Scenario: MenuHeader extends Box
+        When Box features are used
+        Then the MenuHeader responds as a Box would
+
+      Scenario Outline: MenuHeader checks its types
+        When <propName> is passed a value
+        Then MenuHeader expects it to be of type <propType>
+
+        Examples: Prop Types
+          | propName    | propType   |
+          | title       | String     |
+          | children    | ReactNode  |

package/src/MenuHeader/MenuHeader.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import {
+  MenuHeaderContainer,
+  MenuTitleText,
+  MenuChildrenContainer,
+} from "./styles";
+import type { TypeMenuHeaderProps } from "./MenuHeaderTypes";
+
+const MenuHeader = ({
+  children,
+  title,
+  leftAction,
+  rightAction,
+  ...rest
+}: TypeMenuHeaderProps) => {
+  return (
+    <>
+      <MenuHeaderContainer $leftAction={!!leftAction} {...rest}>
+        {leftAction && leftAction}
+        {title && (
+          <MenuTitleText $leftAction={!!leftAction}>{title}</MenuTitleText>
+        )}
+        {rightAction && rightAction}
+        {children && <MenuChildrenContainer>{children}</MenuChildrenContainer>}
+      </MenuHeaderContainer>
+    </>
+  );
+};
+
+export { MenuHeader };

package/src/MenuHeader/MenuHeaderTypes.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+import type {
+  TypeBorderSystemProps,
+  TypeColorSystemProps,
+  TypeFlexboxSystemProps,
+  TypeGridSystemProps,
+  TypeLayoutSystemProps,
+  TypePositionSystemProps,
+  TypeSpaceSystemProps,
+  TypeStyledComponentsCommonProps,
+} from "@sproutsocial/seeds-react-system-props";
+
+export interface TypeMenuHeaderProps
+  extends Omit<React.ComponentPropsWithoutRef<"div">, "color">,
+    TypeStyledComponentsCommonProps,
+    TypeBorderSystemProps,
+    TypeColorSystemProps,
+    TypeFlexboxSystemProps,
+    TypeGridSystemProps,
+    TypeLayoutSystemProps,
+    TypeSpaceSystemProps,
+    TypePositionSystemProps {
+  title?: string;
+  leftAction?: React.ReactNode;
+  rightAction?: React.ReactNode;
+}

package/src/MenuHeader/__tests__/MenuHeader.test.tsx

@@ -0,0 +1,67 @@
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import { MenuHeader } from "../MenuHeader";
+import Button from "@sproutsocial/seeds-react-button";
+
+describe("MenuHeader API", () => {
+  it("renders a title when title prop is passed a string", () => {
+    render(<MenuHeader title="Menu Header" />);
+
+    expect(screen.getByText("Menu Header")).toBeInTheDocument();
+  });
+
+  it("doesn't render a title when title prop is empty", () => {
+    render(<MenuHeader />);
+    const menuHeader = screen.queryByRole("heading");
+
+    expect(menuHeader).not.toBeInTheDocument();
+  });
+
+  it("supports children", () => {
+    render(<MenuHeader>Hello World</MenuHeader>);
+
+    expect(screen.getByText("Hello World")).toBeInTheDocument();
+  });
+
+  it("supports clickable actions", async () => {
+    const handleTestClick = jest.fn();
+
+    const { user } = render(
+      <MenuHeader
+        leftAction={<Button onClick={handleTestClick}>Left Action</Button>}
+        rightAction={<Button onClick={handleTestClick}>Right Action</Button>}
+      >
+        Hello World
+      </MenuHeader>
+    );
+
+    const leftAction = screen.getByText("Left Action");
+    const rightAction = screen.getByText("Right Action");
+
+    await user.click(leftAction);
+
+    expect(handleTestClick).toHaveBeenCalledTimes(1);
+
+    await user.click(rightAction);
+
+    expect(handleTestClick).toHaveBeenCalledTimes(2);
+  });
+
+  it("can render actions on the left or right of the title", () => {
+    render(
+      <MenuHeader
+        leftAction={<Button onClick={() => {}}>Left Action</Button>}
+        rightAction={<Button onClick={() => {}}>Right Action</Button>}
+        title="Menu Header"
+      >
+        Hello World
+      </MenuHeader>
+    );
+
+    const menuHeader = screen.getByText("Menu Header");
+    const leftAction = screen.getByText("Left Action");
+    const rightAction = screen.getByText("Right Action");
+
+    expect(menuHeader.compareDocumentPosition(leftAction)).toBe(2);
+    expect(menuHeader.compareDocumentPosition(rightAction)).toBe(4);
+  });
+});

package/src/MenuHeader/__tests__/MenuHeader.typetest.tsx

@@ -0,0 +1,27 @@
+import { MenuHeader } from "../MenuHeader";
+
+export const MenuHeaderTypeTest = () => (
+  <>
+    <MenuHeader
+      title="Menu Header"
+      leftAction={<div>left action</div>}
+      rightAction={<div>right action</div>}
+      children={<div>children</div>}
+    />
+    {/* left and right action accept strings */}
+    <MenuHeader leftAction="left" rightAction="right" />
+    {/* left and right action accept booleans */}
+    <MenuHeader leftAction={false} rightAction={true} />
+    {/* left and right action accept undefined */}
+    <MenuHeader leftAction={undefined} rightAction={undefined} />
+    {/* left and right action accept numbers */}
+    <MenuHeader leftAction={123} rightAction={123} />
+    {/* left and right action accept null */}
+    <MenuHeader leftAction={null} rightAction={null} />
+
+    {/* @ts-expect-error - title should error with boolean */}
+    <MenuHeader title={true} />
+    {/* @ts-expect-error - title should error with numbers */}
+    <MenuHeader title={123123} />
+  </>
+);

package/src/MenuHeader/index.ts

@@ -0,0 +1,2 @@
+export { MenuHeader } from "./MenuHeader";
+export type { TypeMenuHeaderProps } from "./MenuHeaderTypes";

package/src/MenuHeader/styles.tsx

@@ -0,0 +1,75 @@
+import styled from "styled-components";
+import {
+  border,
+  color,
+  flexbox,
+  grid,
+  layout,
+  position,
+  space,
+} from "styled-system";
+import type { TypeMenuHeaderProps } from "./MenuHeaderTypes";
+
+interface TypeMenuHeaderContainerProps extends TypeMenuHeaderProps {
+  $leftAction?: boolean;
+}
+
+export const MenuHeaderContainer = styled.div<TypeMenuHeaderContainerProps>`
+  border-color: ${({ theme }) => theme.colors.container.border.base};
+  border-bottom-width: 1px;
+  border-bottom-style: solid;
+  box-sizing: border-box;
+  width: 100%;
+  font-size: ${({ theme }) => theme.typography[200].fontSize};
+  display: flex;
+  padding: ${({ theme }) => theme.space[350]} ${({ theme }) => theme.space[400]};
+
+  > a {
+    white-space: nowrap;
+  }
+
+  &:first-child {
+    flex-grow: 1;
+    justify-self: start;
+  }
+
+  &:last-child {
+    flex-grow: 1;
+    justify-self: end;
+  }
+
+  ${({ $leftAction, theme }) =>
+    $leftAction &&
+    `
+			padding-left: ${theme.space[350]};
+	`}
+
+  ${border}
+  ${color}
+  ${flexbox}
+  ${grid}
+  ${layout}
+  ${space}
+  ${position}
+`;
+
+export const MenuTitleText = styled.h3<TypeMenuHeaderContainerProps>`
+  color: ${({ theme }) => theme.colors.text.headline};
+  font-weight: ${({ theme }) => theme.fontWeights.bold};
+  margin: 0px;
+  flex-grow: 2;
+  justify-self: start;
+
+  ${({ $leftAction, theme }) =>
+    $leftAction &&
+    `
+			padding-left: ${theme.space[350]};
+	`}
+
+  ${({ theme }) => theme.typography[200]}
+`;
+
+export const MenuChildrenContainer = styled.div`
+  grid-column: 1 / -1;
+  margin-top: ${({ theme }) => theme.space[300]};
+`;

package/src/MenuItem/MenuItem.feature

@@ -0,0 +1,88 @@
+Feature: MenuItem
+
+  A configurable and interactive item for inclusion in a `Menu` component.
+
+  Rule: User Behavior
+    Background:
+      Given an end user is using the component
+
+    Scenario: MenuItem is clickable
+      Given a MenuItem is not disabled
+      When the MenuItem is clicked
+      Then the MenuItem's onClick event should fire
+
+    Scenario Outline: MenuItem is disabled
+      Given a MenuItem is disabled
+      When the MenuItem is triggered via <interaction>
+      Then no events should fire
+
+      Examples:
+        | interaction                         |
+        | clicking                            |
+        | focusing and pressing the Enter key |
+        | focusing and pressing the Space key |
+
+    Scenario Outline: MenuItem can be triggered via keyboard
+      Given a MenuItem is focused
+      And the MenuItem is not disabled
+      When the MenuItem is triggered via <interaction>
+      Then the MenuItem's onClick event should fire
+
+      Examples:
+        | interaction            |
+        | pressing the Enter key |
+        | pressing the Space key |
+      
+  Rule: API
+    Background:
+      Given an engineer is developing using the component
+
+    Scenario Outline: MenuItem accepts children
+      When <child component(s)> provided
+      Then the MenuFooter should render the <component(s)>
+
+      Examples: child components
+        | child component(s)       | component(s)    |
+        | a Link is                | Link            |
+        | a Text is                | Text            |
+        | a Icon is                | Icon            |
+        | a Text then Icon are     | Text and Icon   |
+        | a Icon and Text are      | Icon and Text   |
+
+    Scenario Outline: A MenuItem accepts system props
+      When a system prop from the category <systemPropCategory> is passed a value
+      Then the MenuItem 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: MenuItem validates prop types
+      When any <prop> is passed to the MenuItem
+      Then the MenuItem should check that each prop is of the expected <propType>
+
+      Examples: Prop Types
+        | prop       | propType |
+        | children   | node     |
+        | onClick    | func     |
+        | disabled   | bool     |
+        | className  | string   |
+
+    Scenario Outline: Screen readers should read MenuItem states
+      Given a MenuItem is <state>
+      Then screen readers should read the MenuItem as <state>
+
+      Examples: MenuItem States
+        | state    |
+        | enabled  |
+        | disabled |
+        | hovered  |
+        | focused  |
+        | active   |
+        | pressed  |

package/src/MenuItem/MenuItem.tsx

@@ -0,0 +1,44 @@
+import React, { useContext } from "react";
+import { MenuContext } from "../MenuContext";
+import { MENU_ITEM_ROLES } from "../constants";
+import type { TypeDefaultItemProps } from "../types";
+import { MenuItemContainer } from "./styles";
+import type { TypeMenuItemProps } from "./MenuItemTypes";
+
+export const MenuItem = ({
+  id,
+  children,
+  role = "menuitem",
+  label,
+  onClick,
+  onKeyDown,
+  disabled = false,
+  ref,
+  color,
+  ...props
+}: TypeMenuItemProps) => {
+  const { getItemProps, itemsMap, highlightedIndex, isListbox } =
+    useContext(MenuContext);
+  const item = (itemsMap[id] || { index: 0, id }) as TypeDefaultItemProps;
+  const highlighted = highlightedIndex === item?.index;
+
+  return (
+    <MenuItemContainer
+      id={id}
+      tabIndex={role !== MENU_ITEM_ROLES.LISTITEM && !disabled ? -1 : undefined}
+      $highlighted={highlighted}
+      {...getItemProps?.({
+        ...(isListbox ? {} : { role: "menuitem" }),
+        item,
+        index: item.index,
+        // This prop no longer supported in downshift
+        // disabled,
+        onClick,
+        onKeyDown,
+      })}
+      {...props}
+    >
+      {children}
+    </MenuItemContainer>
+  );
+};

package/src/MenuItem/MenuItemTypes.ts

@@ -0,0 +1,37 @@
+import type { GetItemPropsOptions } from "downshift";
+import type { TypeMenuItemRoles } from "../constants";
+import type { TypeDefaultItemProps } from "../types";
+import type {
+  TypeBorderSystemProps,
+  TypeColorSystemProps,
+  TypeFlexboxSystemProps,
+  TypeGridSystemProps,
+  TypeLayoutSystemProps,
+  TypePositionSystemProps,
+  TypeSpaceSystemProps,
+  TypeTypographySystemProps,
+} from "@sproutsocial/seeds-react-system-props";
+
+export interface TypeMenuItemStyledProps
+  extends TypeBorderSystemProps,
+    TypeColorSystemProps,
+    TypeFlexboxSystemProps,
+    TypeGridSystemProps,
+    TypeLayoutSystemProps,
+    TypePositionSystemProps,
+    TypeSpaceSystemProps,
+    TypeTypographySystemProps {}
+
+export interface TypeMenuItemProps
+  extends TypeMenuItemStyledProps,
+    Omit<
+      GetItemPropsOptions<TypeDefaultItemProps>,
+      "as" | "item" | keyof TypeMenuItemStyledProps | keyof TypeDefaultItemProps
+    >,
+    Omit<TypeDefaultItemProps, "index"> {
+  label?: string;
+  children: React.ReactNode;
+  disabled?: boolean;
+  role?: TypeMenuItemRoles;
+  $highlighted?: boolean;
+}

package/src/MenuItem/__tests__/MenuItem.test.tsx

@@ -0,0 +1,228 @@
+/* eslint-disable testing-library/no-unnecessary-act */
+import {
+  screen,
+  render,
+  waitFor,
+} from "@sproutsocial/seeds-react-testing-library";
+import { PointerEventsCheckLevel } from "@testing-library/user-event";
+import { theme } from "@sproutsocial/seeds-react-theme";
+import {
+  MenuItem,
+  MenuToggleButton,
+  MenuContent,
+  ActionMenu,
+} from "../../index";
+import { TestWithMenuRoot } from "../../menuTestingUtils";
+
+const menuItemProps = {
+  key: "book123",
+  id: "book-id",
+  children: "Book Title",
+};
+const testMenuContext = {
+  isOpen: true,
+  closeMenu: jest.fn(),
+  openMenu: jest.fn(),
+  getMenuProps: jest.fn((props) => props),
+  getToggleButtonProps: jest.fn((props) => ({
+    onKeyDown: jest.fn(),
+    ...props,
+  })),
+  getItemProps: jest.fn((props) => ({ ...props })),
+  isListbox: false,
+};
+const testTriggerElement = <MenuToggleButton>Open</MenuToggleButton>;
+
+describe("MenuItem User Behavior", () => {
+  describe("MenuItem is clickable", () => {
+    it("fires onClick event when clicked and not disabled", async () => {
+      const handleClick = jest.fn();
+      const { user } = render(
+        <TestWithMenuRoot
+          triggerElement={testTriggerElement}
+          {...testMenuContext}
+        >
+          <MenuContent>
+            <MenuItem {...menuItemProps} onClick={handleClick} />
+          </MenuContent>
+        </TestWithMenuRoot>
+      );
+
+      await user
+        .setup({
+          pointerEventsCheck: PointerEventsCheckLevel.Never,
+        })
+        .click(screen.getByRole("menuitem"));
+
+      await waitFor(() => expect(handleClick).toHaveBeenCalledTimes(1));
+    });
+  });
+
+  describe("MenuItem can be triggered via keyboard", () => {
+    it(`fires onClick event when enter and not disabled`, async () => {
+      const handleClick = jest.fn();
+      const handleStateChange = jest.fn();
+
+      const { user } = render(
+        <ActionMenu
+          triggerElement={testTriggerElement}
+          isOpen
+          onStateChange={handleStateChange}
+        >
+          <MenuContent>
+            <MenuItem
+              {...menuItemProps}
+              data-testid="menu-test"
+              key={0}
+              onKeyDown={handleClick}
+              tabIndex={0}
+            />
+          </MenuContent>
+        </ActionMenu>
+      );
+      const targetElem = screen.getByTestId("menu-test");
+
+      await user.tab();
+      expect(targetElem).toHaveFocus();
+
+      await user.keyboard("{enter}");
+
+      await waitFor(() =>
+        expect(handleStateChange).toHaveBeenCalledWith({
+          isOpen: false,
+          type: "__togglebutton_keydown_enter__",
+        })
+      );
+      expect(handleClick).toHaveBeenCalled();
+    });
+    it(`fires onClick event when space and not disabled`, async () => {
+      const handleClick = jest.fn();
+      const handleStateChange = jest.fn();
+
+      const { user } = render(
+        <ActionMenu
+          triggerElement={testTriggerElement}
+          isOpen
+          onStateChange={handleStateChange}
+        >
+          <MenuContent>
+            <MenuItem
+              {...menuItemProps}
+              data-testid="menu-test"
+              key={0}
+              onKeyDown={handleClick}
+              tabIndex={0}
+            />
+          </MenuContent>
+        </ActionMenu>
+      );
+      const targetElem = screen.getByTestId("menu-test");
+
+      await user.tab();
+      expect(targetElem).toHaveFocus();
+
+      await user.keyboard(" ");
+
+      await waitFor(() =>
+        expect(handleStateChange).toHaveBeenCalledWith({
+          isOpen: false,
+          type: "__togglebutton_keydown_space_button__",
+        })
+      );
+
+      expect(handleClick).toHaveBeenCalled();
+    });
+
+    it(`does not fire onClick event when disabled`, async () => {
+      const handleClick = jest.fn();
+      const handleStateChange = jest.fn();
+
+      const books = [
+        {
+          index: 0,
+          id: "book-1",
+          author: "Harper Lee",
+          title: "To Kill a Mockingbird",
+        },
+        {
+          index: 1,
+          id: "book-2",
+          author: "Lev Tolstoy",
+          title: "War and Peace",
+        },
+      ];
+
+      const testItem = books[0];
+
+      const { user } = render(
+        <TestWithMenuRoot
+          triggerElement={<MenuToggleButton>Open</MenuToggleButton>}
+          {...{
+            ...testMenuContext,
+            items: books,
+            selectedItem: testItem,
+          }}
+        >
+          <MenuItem
+            id={testItem.id}
+            disabled={true}
+            onClick={handleStateChange}
+          >
+            {testItem.title}
+          </MenuItem>
+        </TestWithMenuRoot>
+      );
+      await user
+        .setup({
+          pointerEventsCheck: PointerEventsCheckLevel.Never,
+        })
+        .click(screen.getByRole("menuitem"));
+
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe("MenuItem API", () => {
+  it("accepts children", () => {
+    render(
+      <ActionMenu
+        id="test-menu-item-selectable"
+        triggerElement={testTriggerElement}
+        isOpen
+      >
+        <MenuContent>
+          <MenuItem onClick={() => {}} id="test">
+            Hello world!
+            <span>testing</span>
+          </MenuItem>
+        </MenuContent>
+      </ActionMenu>
+    );
+
+    const menuItem = screen.getByText("Hello world!");
+    const span = screen.getByText("testing");
+    expect(menuItem).toContainElement(span);
+  });
+
+  it("accepts box & system Props", () => {
+    render(
+      <ActionMenu
+        id="test-menu-item-selectable"
+        triggerElement={testTriggerElement}
+        isOpen
+      >
+        <MenuContent>
+          <MenuItem display="flex" p={300} onClick={() => {}} id="test">
+            Hello world!
+            <span>testing</span>
+          </MenuItem>
+        </MenuContent>
+      </ActionMenu>
+    );
+
+    const menuItem = screen.getByRole("menuitem");
+    expect(menuItem).toHaveStyle(`padding: ${theme.space[300]}`);
+    expect(menuItem).toHaveStyle(`display: flex`);
+  });
+});