@kaizen/components 1.55.2 → 1.56.1

package/src/__actions__/Menu/v3/Menu.tsx

@@ -0,0 +1,28 @@
+import React, { forwardRef } from "react"
+import {
+  Menu as RACMenu,
+  MenuProps as RACMenuProps,
+} from "react-aria-components"
+import { mergeClassNames } from "~utils/mergeClassNames"
+import styles from "./Menu.module.scss"
+
+export type MenuProps = Omit<
+  RACMenuProps<HTMLDivElement>,
+  | "selectionMode"
+  | "disallowEmptySelection"
+  | "selectedKeys"
+  | "defaultSelectedKeys"
+>
+
+/**
+ * A menu displays a list of actions or options that a user can choose.
+ */
+export const Menu = forwardRef<HTMLDivElement, MenuProps>(
+  ({ className, ...props }, ref): JSX.Element => (
+    <RACMenu
+      className={mergeClassNames(styles.menu, className)}
+      ref={ref}
+      {...props}
+    />
+  )
+)

package/src/__actions__/Menu/v3/MenuItem.module.scss

@@ -0,0 +1,34 @@
+.item {
+  font-family: var(--typography-paragraph-body-font-family);
+  font-size: var(--typography-paragraph-body-font-size);
+  letter-spacing: var(--typography-paragraph-body-letter-spacing);
+  font-weight: var(--typography-paragraph-body-font-weight);
+  line-height: var(--typography-paragraph-body-line-height);
+  color: rgba(var(--color-purple-800-rgb), 0.7);
+  padding: var(--spacing-6) var(--spacing-8);
+  border: var(--border-focus-ring-border-width)
+    var(--border-focus-ring-border-style) transparent;
+  border-radius: 4px;
+  display: flex;
+  gap: 0 var(--spacing-8);
+  align-items: center;
+  margin-inline: var(--spacing-6);
+  text-decoration: none;
+}
+
+.iconWrapper {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+}
+
+.item[data-focused] {
+  background-color: var(--color-blue-100);
+  color: var(--color-blue-500);
+  outline: none;
+  border-color: var(--color-blue-500);
+}
+
+.item[data-disabled] {
+  opacity: 0.3;
+}

package/src/__actions__/Menu/v3/MenuItem.tsx

@@ -0,0 +1,32 @@
+import React, { forwardRef, ReactNode } from "react"
+import {
+  MenuItem as RACMenuItem,
+  MenuItemProps as RACMenuItemProps,
+} from "react-aria-components"
+import { mergeClassNames } from "~utils/mergeClassNames"
+import styles from "./MenuItem.module.scss"
+
+export type MenuItemProps = RACMenuItemProps & {
+  /**
+   * Provides positioning for an icon to the left of the menu item content
+   */
+  icon?: ReactNode
+}
+
+/**
+ * A MenuItem represents an individual action in a Menu.
+ */
+export const MenuItem = forwardRef<HTMLDivElement, MenuItemProps>(
+  ({ className, icon, children, ...props }, ref): JSX.Element => (
+    <RACMenuItem
+      ref={ref}
+      className={mergeClassNames(styles.item, className)}
+      {...props}
+    >
+      <>
+        {icon && <span className={styles.iconWrapper}>{icon}</span>}
+        {children}
+      </>
+    </RACMenuItem>
+  )
+)

package/src/__actions__/Menu/v3/MenuTrigger.tsx

@@ -0,0 +1,14 @@
+import React from "react"
+import {
+  MenuTrigger as RACMenuTrigger,
+  MenuTriggerProps as RACMenuTriggerProps,
+} from "react-aria-components"
+
+export type MenuTriggerProps = Omit<RACMenuTriggerProps, "trigger">
+
+/**
+ * A MenuTrigger adds open/close functionality when wrapping a Button and a Popover (with a Menu inside of the Popover)
+ */
+export const MenuTrigger = (props: MenuTriggerProps): JSX.Element => (
+  <RACMenuTrigger {...props} />
+)

package/src/__actions__/Menu/v3/SubmenuTrigger.tsx

@@ -0,0 +1,18 @@
+import React, { createContext } from "react"
+import {
+  SubmenuTrigger as RACSubmenuTrigger,
+  SubmenuTriggerProps as RACSubmenuTriggerProps,
+} from "react-aria-components"
+
+export type SubmenuTriggerProps = RACSubmenuTriggerProps
+
+export const SubmenuTriggerContext = createContext<object | null>(null)
+
+/**
+ * A SubmenuTrigger creates a nested Menu triggered by a MenuItem
+ */
+export const SubmenuTrigger = (props: SubmenuTriggerProps): JSX.Element => (
+  <SubmenuTriggerContext.Provider value={{}}>
+    <RACSubmenuTrigger {...props} />
+  </SubmenuTriggerContext.Provider>
+)

package/src/__actions__/Menu/v3/_docs/ApiSpecification.mdx

@@ -0,0 +1,98 @@
+import { Canvas, Controls, Meta, Source } from "@storybook/blocks"
+import { KAIOInstallation, ResourceLinks,  SbContent } from "~storybook/components"
+import * as docsStories from "./Menu.docs.stories"
+import * as exampleStories from "./Menu.stories"
+
+<Meta title="Actions/Menu/v3/API Specification"/>
+
+<SbContent>
+  # Menu API Specification (v3)
+
+  Updated July 4, 2024
+</SbContent>
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__actions__/Menu"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?m=auto&node-id=6262-0&t=I4H23jCrCJz4O2nf-1"
+  designGuidelines="/?path=/docs/actions-menu-v3-usage-guidelines--docs"
+  ariaComponentPage="https://react-spectrum.adobe.com/react-aria/Menu.html"
+/>
+
+<SbContent className="mb-24">
+  <div className="bg-yellow-100 border-default border-yellow-400 rounded px-24">
+    ### Disclaimer
+
+    The `Menu` `v3` component is not backwards compatible with Kaizen `Button` `v1` and `v2`. For this reason, usage of this component is not recommended until a `Button` `v3` is released.
+  </div>
+</SbContent>
+
+<SbContent className="mb-24">
+
+  <KAIOInstallation exportNames={["Menu", "MenuTrigger", "MenuItem"]} family="actions" version="3" />
+
+  <Source code={"import { Popover, Section, Header } from \"@kaizen/components/v3/react-aria-components\""} language="tsx" />
+
+  ## Overview
+
+  A menu displays a list of actions in a popover, toggled opened with a button.
+</SbContent>
+
+<Canvas
+  className="mb-64"
+  of={exampleStories.Basic}
+  source={{code: `
+<MenuTrigger>
+  <Button><MeatballsIcon aria-label="Actions" /></Button>
+  <Popover>
+    <Menu>
+      <MenuItem href="#">Menu Item</MenuItem>
+      <MenuItem onAction={handleAction}>Menu Item</MenuItem>
+    </Menu>
+  </Popover>
+</MenuTrigger>
+  `}}
+/>
+
+<SbContent className="mb-64">
+  ### React Aria
+
+  This component is built using the `react-aria-components` library and extends the [Menu component](https://react-spectrum.adobe.com/react-aria/Menu.html).
+
+  As this shares the same core [anatomy](https://react-spectrum.adobe.com/react-aria/Menu.html#anatomy), [props types](https://react-spectrum.adobe.com/react-aria/Menu.html#menu-1) and [functionality](https://react-spectrum.adobe.com/react-aria/Menu.html#features), the guidance below is tailored to our implementation and should cover known use cases of the Menu.
+
+  More on the React Aria API and a deep dive into other examples can be found via the [React Aria docs page](https://react-spectrum.adobe.com/react-aria/Menu.html) if not present below.
+</SbContent>
+
+<SbContent className="mb-12">
+  ## API
+</SbContent>
+
+<Controls of={exampleStories.Basic}  />
+
+## Actions and Next.js routing
+
+Use the `href` prop when an action navigates to a new page. Wrapping your app in `FrontendServices` from `@cultureamp/next-services` will automatically turn these into Next.js links.
+
+Otherwise, use the `onAction` prop to trigger an action within the page.
+
+<Canvas className="mb-24" of={docsStories.Actions}  />
+
+## Sections
+
+Sections can be added with the `Section` and `Header` component from `react-aria-components`.
+
+<Canvas className="mb-24" of={exampleStories.WithSections}  />
+
+## Disabling items
+
+Menu items can be disabled with the `isDisabled` prop.
+
+<Canvas className="mb-24" of={exampleStories.DisabledItems}  />
+
+## Controlled
+
+By default, the open/closed state of the menu is handled under the hood. In cases where you need control over the open state, use the `isOpen` and `onOpenChange` props on the `MenuTrigger` component (both props must be used for this to work).
+
+<Canvas className="mb-24" of={exampleStories.Controlled}  />
+
+

package/src/__actions__/Menu/v3/_docs/Menu.docs.stories.tsx

@@ -0,0 +1,280 @@
+import React, { FunctionComponent, ReactNode } from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import isChromatic from "chromatic"
+import { Popover } from "react-aria-components"
+import {
+  ArrowDownIcon,
+  ArrowUpIcon,
+  BookmarkOffIcon,
+  CheckIcon,
+  ChevronDownIcon,
+  EditIcon,
+  MeatballsIcon,
+  TrashIcon,
+} from "~components/Icon"
+import { Button } from "~components/__actions__/v3"
+import { Menu, MenuItem, MenuTrigger } from "../index"
+
+const meta = {
+  title: "Actions/Menu/v3/Docs Assets",
+  component: MenuTrigger,
+  args: {
+    defaultOpen: isChromatic(),
+    children: <></>,
+  },
+  subcomponents: { Menu, MenuItem } as Record<string, FunctionComponent<any>>,
+} satisfies Meta<typeof MenuTrigger>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const DefaultMenuItems = (): ReactNode => (
+  <>
+    <MenuItem icon={<BookmarkOffIcon role="presentation" />}>Save</MenuItem>
+    <MenuItem icon={<EditIcon role="presentation" />}>Edit</MenuItem>
+    <MenuItem icon={<ArrowUpIcon role="presentation" />}>Move up</MenuItem>
+    <MenuItem icon={<ArrowDownIcon role="presentation" />}>Move down</MenuItem>
+    <MenuItem icon={<TrashIcon role="presentation" />}>Delete</MenuItem>
+  </>
+)
+
+export const Actions: Story = {
+  render: ({ defaultOpen: _, ...args }) => (
+    <MenuTrigger {...args}>
+      <Button>
+        <MeatballsIcon role="img" aria-label="Additional actions" />
+      </Button>
+      <Popover>
+        <Menu>
+          <MenuItem href="https://cultureamp.com">
+            Action that navigates
+          </MenuItem>
+          <MenuItem onAction={() => null}>Non-navigation action</MenuItem>
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const ItemsDo: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen} {...args}>
+      <Button>
+        <MeatballsIcon role="img" aria-label="Additional actions" />
+      </Button>
+      <Popover>
+        <Menu>
+          <DefaultMenuItems />
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const ItemsDont: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen} {...args}>
+      <Button>
+        <MeatballsIcon role="img" aria-label="Additional actions" />
+      </Button>
+      <Popover>
+        <Menu>
+          <MenuItem icon={<TrashIcon role="presentation" />}>Delete</MenuItem>
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const SelectionDont: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen} {...args}>
+      <Button>
+        Sort by
+        <ChevronDownIcon role="presentation" />
+      </Button>
+      <Popover>
+        <Menu>
+          <MenuItem icon={<CheckIcon role="presentation" />}>
+            Recommended
+          </MenuItem>
+          <MenuItem>Most recent</MenuItem>
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const LabelChevronDo: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen} {...args}>
+      {/* Replace with Kaizen Button once we have v3 or backwards compatibility */}
+      <Button>
+        Edit item
+        <ChevronDownIcon role="presentation" />
+      </Button>
+      <Popover>
+        <Menu>
+          <DefaultMenuItems />
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const LabelChevronDont: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen} {...args}>
+      <Button>Edit item</Button>
+      <Popover>
+        <Menu>
+          <DefaultMenuItems />
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const LabelDo: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen}>
+      <Button>
+        Actions [visually hidden], conversation with Harper[/visually hidden]
+        <ChevronDownIcon role="presentation" />
+      </Button>
+      <Popover>
+        <Menu {...args}>
+          <DefaultMenuItems />
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const LabelDont: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen}>
+      <Button>
+        Open menu
+        <ChevronDownIcon role="presentation" />
+      </Button>
+      <Popover>
+        <Menu {...args}>
+          <DefaultMenuItems />
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const IconsDont: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen}>
+      <Button>
+        <MeatballsIcon role="img" aria-label="Additional actions" />
+      </Button>
+      <Popover>
+        <Menu {...args}>
+          <MenuItem icon={<EditIcon role="presentation" />}>
+            Edit &lsquo;Strengths&rsquo;
+          </MenuItem>
+          <MenuItem icon={<EditIcon role="presentation" />}>
+            Edit &lsquo;Weaknesses&rsquo;
+          </MenuItem>
+          <MenuItem>Export PDF</MenuItem>
+          <MenuItem>Export Powerpoint</MenuItem>
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const MenuItemLabelsDont: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen}>
+      <Button>
+        <MeatballsIcon role="img" aria-label="Additional actions" />
+      </Button>
+      <Popover>
+        <Menu {...args}>
+          <MenuItem>Save comment</MenuItem>
+          <MenuItem>Edit comment</MenuItem>
+          <MenuItem>Delete comment</MenuItem>
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const SentenceCaseDo: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen}>
+      {/* Replace with Kaizen Button once we have v3 or backwards compatibility */}
+      <Button>
+        <MeatballsIcon role="img" aria-label="Additional actions" />
+      </Button>
+      <Popover>
+        <Menu {...args}>
+          <MenuItem>Quick export</MenuItem>
+          <MenuItem>Open a copy</MenuItem>
+          <MenuItem>Share a link</MenuItem>
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const SentenceCaseDont: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen}>
+      {/* Replace with Kaizen Button once we have v3 or backwards compatibility */}
+      <Button>
+        <MeatballsIcon role="img" aria-label="Additional actions" />
+      </Button>
+      <Popover>
+        <Menu {...args}>
+          <MenuItem>Quick Export</MenuItem>
+          <MenuItem>Open A Copy</MenuItem>
+          <MenuItem>Share A Link</MenuItem>
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const ElipsesDo: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen}>
+      {/* Replace with Kaizen Button once we have v3 or backwards compatibility */}
+      <Button>
+        <MeatballsIcon role="img" aria-label="Additional actions" />
+      </Button>
+      <Popover>
+        <Menu {...args}>
+          <MenuItem>Quick export</MenuItem>
+          <MenuItem>Open a copy</MenuItem>
+          <MenuItem>Share a link</MenuItem>
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}
+
+export const ElipsesDont: Story = {
+  render: ({ defaultOpen, ...args }) => (
+    <MenuTrigger defaultOpen={defaultOpen}>
+      {/* Replace with Kaizen Button once we have v3 or backwards compatibility */}
+      <Button>
+        <MeatballsIcon role="img" aria-label="Additional actions" />
+      </Button>
+      <Popover>
+        <Menu {...args}>
+          <MenuItem>Quick export…</MenuItem>
+          <MenuItem>Open a copy…</MenuItem>
+          <MenuItem>Share a link…</MenuItem>
+        </Menu>
+      </Popover>
+    </MenuTrigger>
+  ),
+}