@kaizen/components 1.66.1 → 1.67.0

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

@@ -2,17 +2,8 @@ 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 { Icon } from "~components/__future__/Icon"
 import { Menu, MenuItem, MenuTrigger } from "../index"
 
 const meta = {
@@ -31,19 +22,27 @@ 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>
+    <MenuItem icon={<Icon name="bookmark" isPresentational />}>Save</MenuItem>
+    <MenuItem icon={<Icon name="edit" isPresentational isFilled />}>
+      Edit
+    </MenuItem>
+    <MenuItem icon={<Icon name="arrow_upward" isPresentational />}>
+      Move up
+    </MenuItem>
+    <MenuItem icon={<Icon name="arrow_downward" isPresentational />}>
+      Move down
+    </MenuItem>
+    <MenuItem icon={<Icon name="delete" isPresentational isFilled />}>
+      Delete
+    </MenuItem>
   </>
 )
 
 export const Actions: Story = {
   render: ({ defaultOpen: _, ...args }) => (
     <MenuTrigger {...args}>
-      <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+      <Button className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu>
@@ -60,8 +59,8 @@ export const Actions: Story = {
 export const ItemsDo: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen} {...args}>
-      <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+      <Button className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu>
@@ -75,12 +74,14 @@ export const ItemsDo: Story = {
 export const ItemsDont: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen} {...args}>
-      <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+      <Button className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu>
-          <MenuItem icon={<TrashIcon role="presentation" />}>Delete</MenuItem>
+          <MenuItem icon={<Icon name="delete" isPresentational isFilled />}>
+            Delete
+          </MenuItem>
         </Menu>
       </Popover>
     </MenuTrigger>
@@ -90,13 +91,13 @@ export const ItemsDont: Story = {
 export const SelectionDont: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen} {...args}>
-      <Button>
+      <Button className="[--icon-size:24]">
         Sort by
-        <ChevronDownIcon role="presentation" />
+        <Icon name="keyboard_arrow_down" isPresentational />
       </Button>
       <Popover>
         <Menu>
-          <MenuItem icon={<CheckIcon role="presentation" />}>
+          <MenuItem icon={<Icon name="check" isPresentational />}>
             Recommended
           </MenuItem>
           <MenuItem>Most recent</MenuItem>
@@ -110,9 +111,9 @@ export const LabelChevronDo: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen} {...args}>
       {/* Replace with Kaizen Button once we have v3 or backwards compatibility */}
-      <Button>
+      <Button className="[--icon-size:24]">
         Edit item
-        <ChevronDownIcon role="presentation" />
+        <Icon name="keyboard_arrow_down" isPresentational />
       </Button>
       <Popover>
         <Menu>
@@ -139,9 +140,9 @@ export const LabelChevronDont: Story = {
 export const LabelDo: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen}>
-      <Button>
+      <Button className="[--icon-size:24]">
         Actions [visually hidden], conversation with Harper[/visually hidden]
-        <ChevronDownIcon role="presentation" />
+        <Icon name="keyboard_arrow_down" isPresentational />
       </Button>
       <Popover>
         <Menu {...args}>
@@ -155,9 +156,9 @@ export const LabelDo: Story = {
 export const LabelDont: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen}>
-      <Button>
+      <Button className="[--icon-size:24]">
         Open menu
-        <ChevronDownIcon role="presentation" />
+        <Icon name="keyboard_arrow_down" isPresentational />
       </Button>
       <Popover>
         <Menu {...args}>
@@ -171,15 +172,15 @@ export const LabelDont: Story = {
 export const IconsDont: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen}>
-      <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+      <Button className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu {...args}>
-          <MenuItem icon={<EditIcon role="presentation" />}>
+          <MenuItem icon={<Icon name="edit" isPresentational isFilled />}>
             Edit &lsquo;Strengths&rsquo;
           </MenuItem>
-          <MenuItem icon={<EditIcon role="presentation" />}>
+          <MenuItem icon={<Icon name="edit" isPresentational isFilled />}>
             Edit &lsquo;Weaknesses&rsquo;
           </MenuItem>
           <MenuItem>Export PDF</MenuItem>
@@ -193,8 +194,8 @@ export const IconsDont: Story = {
 export const MenuItemLabelsDont: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen}>
-      <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+      <Button className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu {...args}>
@@ -211,8 +212,8 @@ 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 className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu {...args}>
@@ -229,8 +230,8 @@ 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 className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu {...args}>
@@ -247,8 +248,8 @@ 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 className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu {...args}>
@@ -265,8 +266,8 @@ 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 className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu {...args}>

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

@@ -34,7 +34,7 @@ import * as MenuStories from "./Menu.stories"
   source={{code: `
 <TooltipTrigger>
   <Button>
-    <MeatballsIcon role="img" aria-label="Additional actions" />
+    <Icon name="more_horiz" alt="Additional actions" />
   </Button>
   <Popover>
     <Menu>

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

@@ -3,17 +3,8 @@ import { Meta, StoryObj } from "@storybook/react"
 import { expect, userEvent, waitFor, within, fn } from "@storybook/test"
 import isChromatic from "chromatic"
 import { Popover, Header, Section } from "react-aria-components"
-import {
-  ArrowDownIcon,
-  ArrowUpIcon,
-  BookmarkOffIcon,
-  CautionIcon,
-  EditIcon,
-  ExternalLinkIcon,
-  MeatballsIcon,
-  TrashIcon,
-} from "~components/Icon"
 import { Button } from "~components/__actions__/v3"
+import { Icon } from "~components/__future__/Icon"
 import { Menu, MenuItem, MenuTrigger } from "../index"
 
 const meta = {
@@ -46,31 +37,38 @@ export const KitchenSink: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen} {...args}>
       <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu>
           <Section>
             <Header>Section One</Header>
             <MenuItem
-              icon={<BookmarkOffIcon role="presentation" />}
+              icon={<Icon name="bookmark" isPresentational />}
               href="https://cultureamp.com"
             >
               Save
             </MenuItem>
-            <MenuItem icon={<EditIcon role="presentation" />}>Edit</MenuItem>
+            <MenuItem icon={<Icon name="edit" isPresentational isFilled />}>
+              Edit
+            </MenuItem>
           </Section>
           <Section>
-            <MenuItem icon={<ArrowUpIcon role="presentation" />}>
+            <MenuItem icon={<Icon name="arrow_upward" isPresentational />}>
               Move Up
             </MenuItem>
-            <MenuItem icon={<ArrowDownIcon role="presentation" />}>
+            <MenuItem icon={<Icon name="arrow_downward" isPresentational />}>
               Menu item with a longer label
             </MenuItem>
           </Section>
           <Section>
-            <MenuItem icon={<TrashIcon role="presentation" />}>Delete</MenuItem>
-            <MenuItem icon={<TrashIcon role="presentation" />} isDisabled>
+            <MenuItem icon={<Icon name="delete" isPresentational isFilled />}>
+              Delete
+            </MenuItem>
+            <MenuItem
+              icon={<Icon name="delete" isPresentational isFilled />}
+              isDisabled
+            >
               Delete but disabled
             </MenuItem>
             <MenuItem>Other action</MenuItem>
@@ -87,18 +85,18 @@ export const Basic: Story = {
   render: ({ defaultOpen, ...args }) => (
     <MenuTrigger defaultOpen={defaultOpen} {...args}>
       <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu>
           <MenuItem
-            icon={<CautionIcon role="presentation" />}
+            icon={<Icon name="warning" isPresentational isFilled />}
             onAction={() => alert("Menu item pressed")}
           >
             Trigger an alert
           </MenuItem>
           <MenuItem
-            icon={<ExternalLinkIcon role="presentation" />}
+            icon={<Icon name="open_in_new" isPresentational />}
             href="https://cultureamp.com"
             target="_blank"
           >
@@ -168,7 +166,7 @@ export const DisabledItems: Story = {
   render: () => (
     <MenuTrigger>
       <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu>
@@ -208,7 +206,7 @@ export const WithSections: Story = {
   render: () => (
     <MenuTrigger>
       <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu>
@@ -240,7 +238,7 @@ export const Controlled: Story = {
         </button>
         <MenuTrigger isOpen={isOpen} onOpenChange={setOpen}>
           <Button>
-            <MeatballsIcon role="img" aria-label="Additional actions" />
+            <Icon name="more_horiz" alt="Additional actions" />
           </Button>
           <Popover>
             <Menu>

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

@@ -2,15 +2,8 @@ import React, { FunctionComponent } from "react"
 import { Meta, StoryObj } from "@storybook/react"
 import isChromatic from "chromatic"
 import { Popover } from "react-aria-components"
-import {
-  ArrowDownIcon,
-  ArrowUpIcon,
-  BookmarkOffIcon,
-  EditIcon,
-  MeatballsIcon,
-  TrashIcon,
-} from "~components/Icon"
 import { Button } from "~components/__actions__/v3"
+import { Icon } from "~components/__future__/Icon"
 import { Menu, MenuTrigger, MenuItem } from "../index"
 import * as testStories from "./Menu.spec.stories"
 
@@ -32,22 +25,26 @@ export const Playground: Story = {
   render: ({ defaultOpen: _, ...args }) => (
     <MenuTrigger {...args}>
       {/* Replace with Kaizen Button once we have v3 or backwards compatibility */}
-      <Button>
-        <MeatballsIcon role="img" aria-label="Additional actions" />
+      <Button className="[--icon-size:24]">
+        <Icon name="more_horiz" alt="Additional actions" />
       </Button>
       <Popover>
         <Menu>
-          <MenuItem icon={<BookmarkOffIcon role="presentation" />}>
+          <MenuItem icon={<Icon name="bookmark" isPresentational />}>
             Save
           </MenuItem>
-          <MenuItem icon={<EditIcon role="presentation" />}>Edit</MenuItem>
-          <MenuItem icon={<ArrowUpIcon role="presentation" />}>
+          <MenuItem icon={<Icon name="edit" isPresentational isFilled />}>
+            Edit
+          </MenuItem>
+          <MenuItem icon={<Icon name="arrow_upward" isPresentational />}>
             Move up
           </MenuItem>
-          <MenuItem icon={<ArrowDownIcon role="presentation" />}>
+          <MenuItem icon={<Icon name="arrow_downward" isPresentational />}>
             Move down
           </MenuItem>
-          <MenuItem icon={<TrashIcon role="presentation" />}>Delete</MenuItem>
+          <MenuItem icon={<Icon name="delete" isPresentational isFilled />}>
+            Delete
+          </MenuItem>
         </Menu>
       </Popover>
     </MenuTrigger>

package/src/__future__/Icon/Icon.module.css

@@ -0,0 +1,35 @@
+.icon {
+  font-size: calc(1px * var(--icon-size, 20));
+  font-weight: var(--icon-font-weight, 400);
+  vertical-align: var(--icon-vertical-align);
+
+  /* Must use vars otherwise whole attribute must be set again */
+  font-variation-settings:
+    "FILL" var(--icon-fill, 0),
+    "GRAD" var(--icon-grade, 0),
+    "opsz" var(--icon-optical-size, var(--icon-size, 20));
+}
+
+.filled {
+  --icon-fill: 1;
+}
+
+.shouldMirrorInRTL {
+  [dir="rtl"] & {
+    transform: scale(-1, 1);
+  }
+}
+
+.iconLTR {
+  [dir="rtl"] & {
+    display: none;
+  }
+}
+
+.iconRTL {
+  display: none;
+
+  [dir="rtl"] & {
+    display: inherit;
+  }
+}

package/src/__future__/Icon/Icon.spec.tsx

@@ -0,0 +1,36 @@
+import React from "react"
+import { render, screen } from "@testing-library/react"
+import { Icon } from "./Icon"
+
+describe("<Icon />", () => {
+  it("sets required attributes for a presentational icon", () => {
+    render(<Icon data-testid="test__icon" name="star" isPresentational />)
+    const icon = screen.getByTestId("test__icon")
+
+    expect(icon).toHaveAttribute("aria-hidden", "true")
+    expect(icon).not.toHaveAttribute("role")
+    expect(icon).not.toHaveAttribute("aria-label")
+  })
+
+  it("sets required attributes for a meaningful icon", () => {
+    render(<Icon data-testid="test__icon" name="star" alt="Favourite" />)
+    const icon = screen.getByTestId("test__icon")
+
+    expect(icon).not.toHaveAttribute("aria-hidden")
+    expect(icon).toHaveAttribute("role", "img")
+    expect(icon).toHaveAttribute("aria-label", "Favourite")
+  })
+
+  describe("shouldMirrorInRTL", () => {
+    it("does not show icon name in accessible name for switched icons", () => {
+      render(
+        <button type="button">
+          <Icon name="format_list_numbered" shouldMirrorInRTL alt="Pancakes" />
+        </button>
+      )
+      const button = screen.getByRole("button")
+
+      expect(button).toHaveAccessibleName("Pancakes")
+    })
+  })
+})

package/src/__future__/Icon/Icon.tsx

@@ -0,0 +1,85 @@
+import React, { HTMLAttributes } from "react"
+import classNames from "classnames"
+import { StringSuggestions } from "~components/types/StringSuggestions"
+import { handledRtlIcons } from "./constants"
+import { IconNames } from "./types"
+import styles from "./Icon.module.css"
+
+type PresentationalIcon = {
+  isPresentational: true
+  alt?: never
+}
+
+type MeaningfulIcon = {
+  isPresentational?: false
+  alt: string
+}
+
+type BaseIconProps = {
+  isFilled?: boolean
+} & HTMLAttributes<HTMLSpanElement> &
+  (PresentationalIcon | MeaningfulIcon)
+
+type MaterialIconProps = BaseIconProps & {
+  children: React.ReactNode
+}
+
+const MaterialIcon = ({
+  children,
+  isFilled,
+  isPresentational,
+  alt,
+  className,
+  ...restProps
+}: MaterialIconProps): JSX.Element => (
+  <span
+    className={classNames(
+      "material-symbols-outlined",
+      styles.icon,
+      isFilled && styles.filled,
+      className
+    )}
+    aria-hidden={isPresentational}
+    role={isPresentational ? undefined : "img"}
+    aria-label={alt}
+    {...restProps}
+  >
+    {children}
+  </span>
+)
+
+export type IconProps = BaseIconProps & {
+  /** Options available at https://fonts.google.com/icons */
+  name: StringSuggestions<IconNames>
+  shouldMirrorInRTL?: boolean
+}
+
+export const Icon = ({
+  name,
+  shouldMirrorInRTL,
+  ...restProps
+}: IconProps): JSX.Element => {
+  if (!shouldMirrorInRTL) {
+    return <MaterialIcon {...restProps}>{name}</MaterialIcon>
+  }
+
+  if (Object.keys(handledRtlIcons).includes(name)) {
+    return (
+      <MaterialIcon {...restProps}>
+        <span className={styles.iconLTR}>{name}</span>
+        <span className={styles.iconRTL}>
+          {handledRtlIcons[name as keyof typeof handledRtlIcons]}
+        </span>
+      </MaterialIcon>
+    )
+  }
+
+  return (
+    <MaterialIcon
+      {...restProps}
+      className={classNames(styles.shouldMirrorInRTL, restProps.className)}
+    >
+      {name}
+    </MaterialIcon>
+  )
+}

package/src/__future__/Icon/_docs/Icon--api-specification.mdx

@@ -0,0 +1,98 @@
+import { Canvas, Meta, Controls, Story } from "@storybook/blocks"
+import { ResourceLinks, KAIOInstallation } from "~storybook/components"
+import * as IconStories from "./Icon.docs.stories"
+
+<Meta title="Illustrations/Icon/Icon (Future)/API Specification" />
+
+# Icon API Specification (Future)
+
+Updated September 4, 2024
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__v2__/Icon"
+  designGuidelines="/?path=/docs/illustrations-icon-v2-usage-guidelines--docs"
+/>
+
+<KAIOInstallation exportNames="Icon" isFuture />
+
+### Set up
+
+Add the following (CDN for the variable icon font) to your Storybook `preview-head.html` and to the `<head>` of your apps.
+
+```html
+<link rel="preconnect" href="https://fonts.gstatic.com/" crossorigin>
+<link rel="preload" as="style" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,400,0..1,0" />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,400,0..1,0" />
+```
+
+## Overview
+
+Icon extends [Material Symbols](https://fonts.google.com/icons), utilising the CDN.
+
+<Canvas of={IconStories.Playground} />
+<Controls of={IconStories.Playground} />
+
+## API
+
+### Name
+
+See [Material Symbols](https://fonts.google.com/icons) for all valid options.
+
+### Filled
+
+<Canvas of={IconStories.Filled} />
+
+### Mirror in RTL
+
+The `shouldMirrorInRTL` prop mirrors the Icon in `dir="rtl"`.
+
+Use this for directional icons based on your usage context (eg. forwards in LTR will point right, whilst in RTL will point left).
+
+Read more about bidirectionality from [Material Design](https://m2.material.io/design/usability/bidirectionality.html#mirroring-elements).
+
+<Canvas of={IconStories.MirrorInRTL} />
+
+### Accessibility
+
+#### Meaningful icon
+
+Icons without accompanying text need to convey their intent to the screen reader.
+Add `alt` text for these use cases.
+
+<Canvas of={IconStories.MeaningfulIcon} />
+
+#### Presentational icon
+
+For icons which are purely presentational, add `isPresentational` to hide it from the screen reader.
+
+<Canvas of={IconStories.PresentationalIcon} />
+
+### Customisation
+
+#### Color
+
+The Icon component inherits the color from its parent by default. You may also change the color using `className`.
+
+<Canvas of={IconStories.Color} />
+
+#### Size
+
+There are two ways to change the size of the icon:
+
+1. (Recommended) Change the value of the `--icon-size` CSS variable (eg. in Tailwind - `[--icon-size:48]`).
+This option will also scale the [optical size](https://m3.material.io/styles/icons/applying-icons#b41cbc01-9b49-4a44-a525-d153d1ea1425) of the icon.
+Note that the value must be a whole number value without units.
+
+2. Override the `font-size` CSS attribute (eg. in Tailwind - `text-[1em]`).
+This option will not scale the optical size of the icon for you, so you will need to combine it with also
+overriding the `--icon-optical-size` CSS variable (eg. in Tailwind - `[--icon-optical-size:48]`).
+
+<Canvas of={IconStories.Size} />
+
+## Default icon set
+
+Whilst you have access to all Material Symbols, the following icons match the default set we have in Figma.
+
+Tip: Click on the icon you want for a quick copy!
+
+<Story of={IconStories.DefaultIconSet} />