@kaizen/components 1.68.13 → 1.69.1

package/src/{__future__ → __rc__}/Icon/_docs/Icon.stickersheet.stories.tsx

@@ -1,16 +1,16 @@
 import React from 'react'
-import { Meta } from '@storybook/react'
+import { type Meta } from '@storybook/react'
+import { Button } from '~components/Button'
 import { CheckboxField } from '~components/Checkbox'
 import { Label } from '~components/Label'
 import { Text } from '~components/Text'
-import { Button as ButtonV2 } from '~components/__actions__/v2'
-import { Button as ButtonV3 } from '~components/__actions__/v3'
-import { StickerSheet, StickerSheetStory } from '~storybook/components/StickerSheet'
+import { Button as ButtonRC } from '~components/__rc__/Button'
+import { StickerSheet, type StickerSheetStory } from '~storybook/components/StickerSheet'
 import { handledRtlIcons, iconDefaultSet } from '../constants'
-import { Icon, IconProps } from '../index'
+import { Icon, type IconProps } from '../index'
 
 export default {
-  title: 'Illustrations/Icon/Icon (Future)',
+  title: 'Components/Icon/Icon (Future)',
   parameters: {
     chromatic: { disable: false },
     controls: { disable: true },
@@ -87,12 +87,12 @@ const StickerSheetTemplate: StickerSheetStory = {
             />
           </StickerSheet.Row>
           <StickerSheet.Row header="Button (v2)">
-            <ButtonV2 label="Button label" icon={<Icon {...defaultProps} />} />
+            <Button label="Button label" icon={<Icon {...defaultProps} />} />
           </StickerSheet.Row>
           <StickerSheet.Row header="Button (v3)">
-            <ButtonV3>
+            <ButtonRC>
               <Icon {...defaultProps} /> Button label
-            </ButtonV3>
+            </ButtonRC>
           </StickerSheet.Row>
         </StickerSheet>
       </>

package/src/{__future__ → __rc__}/Icon/types.ts

@@ -1,4 +1,4 @@
-import iconsMetadata from './material-symbols-metadata.json'
+import type iconsMetadata from './material-symbols-metadata.json'
 
 // Icon names are from https://github.com/marella/material-symbols/blob/main/metadata/versions.json
 // Update `material-symbols-metadata.json` for new icons.

package/src/{__actions__/Menu/v3 → __rc__/Menu}/Menu.tsx

@@ -1,5 +1,5 @@
 import React, { forwardRef } from 'react'
-import { Menu as RACMenu, MenuProps as RACMenuProps } from 'react-aria-components'
+import { Menu as RACMenu, type MenuProps as RACMenuProps } from 'react-aria-components'
 import { mergeClassNames } from '~components/utils/mergeClassNames'
 import styles from './Menu.module.css'
 

package/src/__rc__/Menu/MenuHeader.tsx

@@ -0,0 +1,12 @@
+import React, { forwardRef, type ReactNode } from 'react'
+import { Header } from 'react-aria-components'
+
+export type MenuHeaderProps = { children: ReactNode }
+
+/**
+ * A <header> element, used to title a MenuSection
+ */
+export const MenuHeader = forwardRef<HTMLDivElement, MenuHeaderProps>(
+  (props, ref): JSX.Element => <Header ref={ref} {...props} />,
+)
+MenuHeader.displayName = 'MenuHeader'

package/src/{__actions__/Menu/v3 → __rc__/Menu}/MenuItem.tsx

@@ -1,5 +1,8 @@
-import React, { forwardRef, ReactNode } from 'react'
-import { MenuItem as RACMenuItem, MenuItemProps as RACMenuItemProps } from 'react-aria-components'
+import React, { forwardRef, type ReactNode } from 'react'
+import {
+  MenuItem as RACMenuItem,
+  type MenuItemProps as RACMenuItemProps,
+} from 'react-aria-components'
 import { mergeClassNames } from '~components/utils/mergeClassNames'
 import styles from './MenuItem.module.css'
 

package/src/__rc__/Menu/MenuPopover.tsx

@@ -0,0 +1,12 @@
+import React, { forwardRef } from 'react'
+import { Popover, type PopoverProps } from 'react-aria-components'
+
+export type MenuPopoverProps = PopoverProps
+
+/**
+ * Overlay element for holding a <Menu>
+ */
+export const MenuPopover = forwardRef<HTMLDivElement, MenuPopoverProps>(
+  (props, ref): JSX.Element => <Popover ref={ref} {...props} />,
+)
+MenuPopover.displayName = 'MenuPopover'

package/src/__rc__/Menu/MenuSection.tsx

@@ -0,0 +1,15 @@
+import React, { forwardRef } from 'react'
+import {
+  MenuSection as RACMenuSection,
+  type MenuSectionProps as RACMenuSectionProps,
+} from 'react-aria-components'
+
+export type MenuSectionProps = RACMenuSectionProps<HTMLDivElement>
+
+/**
+ * A <section> element used to separate <MenuItem>s
+ */
+export const MenuSection = forwardRef<HTMLDivElement, MenuSectionProps>(
+  (props, ref): JSX.Element => <RACMenuSection ref={ref} {...props} />,
+)
+MenuSection.displayName = 'MenuSection'

package/src/{__actions__/Menu/v3 → __rc__/Menu}/MenuTrigger.tsx

@@ -1,12 +1,12 @@
 import React from 'react'
 import {
   MenuTrigger as RACMenuTrigger,
-  MenuTriggerProps as RACMenuTriggerProps,
+  type 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)
+ * A MenuTrigger adds open/close functionality when wrapping a Button and a Popover (with a Menu inside of the MenuPopover)
  */
 export const MenuTrigger = (props: MenuTriggerProps): JSX.Element => <RACMenuTrigger {...props} />

package/src/{__actions__/Menu/v3 → __rc__/Menu}/SubmenuTrigger.tsx

@@ -1,7 +1,7 @@
 import React, { createContext } from 'react'
 import {
   SubmenuTrigger as RACSubmenuTrigger,
-  SubmenuTriggerProps as RACSubmenuTriggerProps,
+  type SubmenuTriggerProps as RACSubmenuTriggerProps,
 } from 'react-aria-components'
 
 export type SubmenuTriggerProps = RACSubmenuTriggerProps

package/src/{__actions__/Menu/v3 → __rc__/Menu}/_docs/ApiSpecification.mdx

@@ -1,16 +1,13 @@
 import { Canvas, Controls, Meta, Source } from '@storybook/blocks'
-import { KAIOInstallation, ResourceLinks, SbContent } from '~storybook/components'
+import { KAIOInstallation, ResourceLinks } from '~storybook/components'
 import * as docsStories from './Menu.docs.stories'
 import * as exampleStories from './Menu.stories'
 
-<Meta title="Actions/Menu/v3/API Specification" />
+<Meta title="Components/Menu/Menu (v3)/API Specification" />
 
-<SbContent>
-  # Menu API Specification (v3)
+# Menu API Specification (v3)
 
-Updated July 4, 2024
-
-</SbContent>
+Updated December 16, 2024
 
 <ResourceLinks
   sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__actions__/Menu"
@@ -19,34 +16,20 @@ Updated July 4, 2024
   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" />
+<KAIOInstallation
+  exportNames={['Menu', 'MenuTrigger', 'MenuItem', 'MenuPopover', 'MenuSection', 'MenuHeader']}
+  family="actions"
+  version="3"
+/>
 
-{' '}
+## Compatibility
 
-<Source
-  code={'import { Popover, Section, Header } from "@kaizen/components/v3/react-aria-components"'}
-  language="tsx"
-/>
+The `Menu` `v3` component is not backwards compatible with Kaizen `Button` `v1` and `v2`. This will only work when used with the `Button` `v3` component.
 
 ## Overview
 
 A menu displays a list of actions in a popover, toggled opened with a button.
 
-</SbContent>
-
 <Canvas
   className="mb-64"
   of={exampleStories.Basic}
@@ -54,30 +37,17 @@ A menu displays a list of actions in a popover, toggled opened with a button.
     code: `
 <MenuTrigger>
   <Button><Icon name="more_horiz" alt="Actions" /></Button>
-  <Popover>
+  <MenuPopover>
     <Menu>
       <MenuItem href="#">Menu Item</MenuItem>
       <MenuItem onAction={handleAction}>Menu Item</MenuItem>
     </Menu>
-  </Popover>
+  </MenuPopover>
 </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
@@ -99,7 +69,7 @@ If you're passing `ReactNode` into `MenuItem` `children`, you'll need to specify
 
 ## Sections
 
-Sections can be added with the `Section` and `Header` component from `react-aria-components`.
+Sections can be added with the `MenuSection` and `MenuHeader` components.
 
 <Canvas className="mb-24" of={exampleStories.WithSections} />
 

package/src/{__actions__/Menu/v3 → __rc__/Menu}/_docs/Menu.docs.stories.tsx

@@ -1,19 +1,21 @@
-import React, { FunctionComponent, ReactNode } from 'react'
-import { Meta, StoryObj } from '@storybook/react'
+import React, { type FunctionComponent, type ReactNode } from 'react'
+import { type Meta, type StoryObj } from '@storybook/react'
 import isChromatic from 'chromatic'
-import { Popover } from 'react-aria-components'
-import { Button } from '~components/__actions__/v3'
-import { Icon } from '~components/__future__/Icon'
-import { Menu, MenuItem, MenuTrigger } from '../index'
+import { Button } from '~components/__rc__/Button'
+import { Icon } from '~components/__rc__/Icon'
+import { Menu, MenuHeader, MenuItem, MenuPopover, MenuSection, MenuTrigger } from '../index'
 
 const meta = {
-  title: 'Actions/Menu/v3/Docs Assets',
+  title: 'Components/Menu/Menu (v3)/Docs Assets',
   component: MenuTrigger,
   args: {
     defaultOpen: isChromatic(),
     children: <></>,
   },
-  subcomponents: { Menu, MenuItem } as Record<string, FunctionComponent<any>>,
+  subcomponents: { Menu, MenuItem, MenuPopover, MenuSection, MenuHeader } as Record<
+    string,
+    FunctionComponent<any>
+  >,
 } satisfies Meta<typeof MenuTrigger>
 
 export default meta
@@ -41,12 +43,12 @@ export const Actions: Story = {
       >
         Additional actions
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu>
           <MenuItem href="https://cultureamp.com">Action that navigates</MenuItem>
           <MenuItem onAction={() => null}>Non-navigation action</MenuItem>
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -62,11 +64,11 @@ export const ItemsDo: Story = {
       >
         Additional actions
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu>
           <DefaultMenuItems />
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -82,11 +84,11 @@ export const ItemsDont: Story = {
       >
         Additional actions
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu>
           <MenuItem icon={<Icon name="delete" isPresentational isFilled />}>Delete</MenuItem>
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -98,12 +100,12 @@ export const SelectionDont: Story = {
         Sort by
         <Icon name="keyboard_arrow_down" isPresentational />
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu>
           <MenuItem icon={<Icon name="check" isPresentational />}>Recommended</MenuItem>
           <MenuItem>Most recent</MenuItem>
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -115,11 +117,11 @@ export const LabelChevronDo: Story = {
         Edit item
         <Icon name="keyboard_arrow_down" isPresentational />
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu>
           <DefaultMenuItems />
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -128,11 +130,11 @@ export const LabelChevronDont: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen} {...args}>
       <Button variant="secondary">Edit item</Button>
-      <Popover>
+      <MenuPopover>
         <Menu>
           <DefaultMenuItems />
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -144,11 +146,11 @@ export const LabelDo: Story = {
         Actions [visually hidden], conversation with Harper[/visually hidden]
         <Icon name="keyboard_arrow_down" isPresentational />
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu {...args}>
           <DefaultMenuItems />
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -160,11 +162,11 @@ export const LabelDont: Story = {
         Open menu
         <Icon name="keyboard_arrow_down" isPresentational />
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu {...args}>
           <DefaultMenuItems />
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -180,7 +182,7 @@ export const IconsDont: Story = {
       >
         Additional actions
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu {...args}>
           <MenuItem icon={<Icon name="edit" isPresentational isFilled />}>
             Edit &lsquo;Strengths&rsquo;
@@ -191,7 +193,7 @@ export const IconsDont: Story = {
           <MenuItem>Export PDF</MenuItem>
           <MenuItem>Export Powerpoint</MenuItem>
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -207,13 +209,13 @@ export const MenuItemLabelsDont: Story = {
       >
         Additional actions
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu {...args}>
           <MenuItem>Save comment</MenuItem>
           <MenuItem>Edit comment</MenuItem>
           <MenuItem>Delete comment</MenuItem>
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -229,13 +231,13 @@ export const SentenceCaseDo: Story = {
       >
         Additional actions
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu {...args}>
           <MenuItem>Quick export</MenuItem>
           <MenuItem>Open a copy</MenuItem>
           <MenuItem>Share a link</MenuItem>
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -251,13 +253,13 @@ export const SentenceCaseDont: Story = {
       >
         Additional actions
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu {...args}>
           <MenuItem>Quick Export</MenuItem>
           <MenuItem>Open A Copy</MenuItem>
           <MenuItem>Share A Link</MenuItem>
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -273,13 +275,13 @@ export const ElipsesDo: Story = {
       >
         Additional actions
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu {...args}>
           <MenuItem>Quick export</MenuItem>
           <MenuItem>Open a copy</MenuItem>
           <MenuItem>Share a link</MenuItem>
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }
@@ -295,13 +297,13 @@ export const ElipsesDont: Story = {
       >
         Additional actions
       </Button>
-      <Popover>
+      <MenuPopover>
         <Menu {...args}>
           <MenuItem>Quick export…</MenuItem>
           <MenuItem>Open a copy…</MenuItem>
           <MenuItem>Share a link…</MenuItem>
         </Menu>
-      </Popover>
+      </MenuPopover>
     </MenuTrigger>
   ),
 }

package/src/__rc__/Menu/_docs/Menu.mdx

@@ -0,0 +1,152 @@
+import { Canvas, Meta, Controls } from '@storybook/blocks'
+import { ResourceLinks, Installation, DosAndDonts, DoOrDont } from '~storybook/components'
+import * as MenuDocsStories from './Menu.docs.stories'
+import * as MenuStories from './Menu.stories'
+
+<Meta title="Components/Menu/Menu (v3)/Usage Guidelines" />
+
+# Menu (v3)
+
+Updated July 6, 2024
+
+<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"
+  ariaComponentPage="https://react-spectrum.adobe.com/react-aria/Menu.html"
+  apiSpecification="/?path=/docs/actions-menu-v3-api-specification--docs"
+/>
+
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { MenuTrigger, Menu, MenuItem, MenuPopover, MenuSection, MenuHeader } from "@kaizen/components/v3/actions"'
+/>
+
+## Overview
+
+A menu displays a list of actions in a popover, toggled opened with a button.
+
+<Canvas
+  of={MenuStories.Playground}
+  source={{
+    code: `
+<MenuTrigger>
+  <Button>
+    <Icon name="more_horiz" alt="Additional actions" />
+  </Button>
+  <MenuPopover>
+    <Menu>
+      <MenuItem>Save</MenuItem>
+      <MenuItem>Edit</MenuItem>
+      <MenuItem>Delete</MenuItem>
+    </Menu>
+  </MenuPopover>
+</MenuTrigger>
+  `,
+  }}
+/>
+<Controls of={MenuStories.Playground} include={['placement', 'isOpen']} className="mb-64" />
+
+### Anatomy
+
+- A Menu is made up of:
+  - A trigger button
+  - A popover
+  - A list of menu items
+- Menu items may be organised into sections, with a heading for each section.
+- The menu trigger button, which may be any variation of a button.
+
+  ### When to use
+
+- When you have a group of related actions for a page or item on the page.
+- The actions either: - Cause an action on the page (e.g. delete), or - Navigate somewhere
+
+  ### When not to use
+
+- When you want to persist a user selection.
+  - Use a Select/Multi-Select or Combobox/Multi-Combobox component instead.
+- When you want additional elements beyond a list of menu items (e.g. a search input)
+  - Use a Modal, or construct your own pattern with a Popover.
+  - It's recommended that you avoid this because of the complexity it adds for accessibility.
+- Inside a navigation bar - Different DOM elements and behaviour is required for a dropdown menu in a navigation bar.
+
+#### Do use a menu for an overflow of actions
+
+Menus work well as an overflow for a list of actions on a page or section. Try to avoid using menus for a single action, favouring an inline button/link instead.
+
+<DosAndDonts>
+  <DoOrDont story={MenuDocsStories.ItemsDo} />
+  <DoOrDont story={MenuDocsStories.ItemsDont} isDont />
+</DosAndDonts>
+
+#### Don't use Menus to persist a user selection
+
+Menus are not intended for a list of options where a user selection persists. Use a Select/Multi-Select or Combobox/Multi-Combobox component instead.
+
+<DosAndDonts>
+  <DoOrDont story={MenuDocsStories.SelectionDont} isDont />
+</DosAndDonts>
+
+#### Do use a chevron icon when using a text label
+
+Providing this icon is an important part of visually communicating that the button triggers a menu.
+
+<DosAndDonts>
+  <DoOrDont story={MenuDocsStories.LabelChevronDo} />
+  <DoOrDont story={MenuDocsStories.LabelChevronDont} isDont />
+</DosAndDonts>
+
+#### Do give the trigger button a concise and unique label
+
+The label of the trigger button will be important for screen reader users to understand the purpose of the menu.
+
+Menu button labels are often too generic and need context added. E.g. a label of &ldquo;Actions&rdquo; is too generic if you have multiple menus on a single page.
+
+Avoid using the words &ldquo;Open/close&rdquo; or &ldquo;Menu&rdquo; in the label, both of these things are communicated to screen reader users already with ARIA properties.
+
+The following examples show you the verbose labels. In practice you will either want to use visually hidden text (when using a text-based trigger button), or an aria-label (when using an icon-based trigger button) to create the label.
+
+<DosAndDonts>
+  <DoOrDont story={MenuDocsStories.LabelDo} />
+  <DoOrDont story={MenuDocsStories.LabelDont} isDont />
+</DosAndDonts>
+
+#### Do use icons in menu items for common actions
+
+Icons beside items make sense for common actions (pencil for edit, trash can for delete, etc).
+
+Avoid using icons when:
+
+- The action is unique and doesn't have a commonly known icon associated.
+- Not all menu items will have an icon
+- You will have duplicates of icons in the list
+
+<DosAndDonts>
+  <DoOrDont story={MenuDocsStories.ItemsDo} />
+  <DoOrDont story={MenuDocsStories.IconsDont} isDont />
+</DosAndDonts>
+
+#### Don't repeat the same word in the menu item labels
+
+Context may be useful in some cases, but avoid adding context if it will be repeated in every menu item label.
+
+<DosAndDonts>
+  <DoOrDont story={MenuDocsStories.MenuItemLabelsDont} isDont />
+</DosAndDonts>
+
+#### Do use sentence case for menu items
+
+Write menu items in sentence case unless they contain words that are branded terms.
+
+<DosAndDonts>
+  <DoOrDont story={MenuDocsStories.SentenceCaseDo} />
+  <DoOrDont story={MenuDocsStories.SentenceCaseDont} isDont />
+</DosAndDonts>
+
+#### Don't use elipses in menu items
+
+Avoid using ellipses (…) in menu item names within products whenever possible. An ellipsis often implies that the action for a menu item will open in a new view, or that a user will be taken elsewhere.
+
+<DosAndDonts>
+  <DoOrDont story={MenuDocsStories.ElipsesDo} />
+  <DoOrDont story={MenuDocsStories.ElipsesDont} isDont />
+</DosAndDonts>