@kaizen/components 0.0.0-canary-fix-select-futureselect-focus-jumping-20241003232256 → 0.0.0-canary-tsx-codemod-20241029235345

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&display=block" />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,400,0..1,0&display=block" />
+```
+
+## 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} />

package/src/__future__/Icon/_docs/Icon--usage-guidelines.mdx

@@ -0,0 +1,145 @@
+import { Canvas, Meta, Controls, Story } from "@storybook/blocks"
+import { ResourceLinks, KAIOInstallation, DosAndDonts, DoOrDont } from "~storybook/components"
+import * as IconStories from "./Icon.docs.stories"
+
+<Meta title="Illustrations/Icon/Icon (Future)/Usage Guidelines" />
+
+# Icon (Future)
+
+Updated September 13, 2024
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__illustrations__/Icon/v3"
+  apiSpecification="/?path=/docs/illustrations-icon-v3-api-specification--docs"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?node-id=1929-3974"
+/>
+
+<KAIOInstallation exportNames="Icon" isFuture />
+
+## Overview
+
+Icons are simplified visual symbols that represent ideas, objects, or actions. They improve comprehension, guide interactivity, and draw attention to important information.
+
+<Canvas of={IconStories.Playground} />
+<Controls of={IconStories.Playground} include={["name", "isFilled"]} />
+
+### When to use
+
+- To support comprehension of an idea, object, or action.
+- To provide visual cues and improving navigation.
+
+### When not to use
+
+- When the meaning of the icon is not immediately clear or could be misinterpreted.
+- When text is necessary to convey specific or detailed information.
+- When using too many icons could clutter the interface and overwhelm the user.
+- When accessibility is a concern and the icon does not have appropriate alternative text or support.
+- When the icon does not align with the overall design language or style of the application.
+
+### Specs
+
+When you need a new icon, use [Google's Material Symbols set](https://fonts.google.com/icons) via the [Figma plugin](https://www.figma.com/community/plugin/1088610476491668236/material-symbols) to add the relevant icons in:
+- **Outlined**
+- **Weight**: 400
+- **Grade**: Normal (0)
+- **Fill**: On or Off
+
+#### Do use icons consistently
+
+Consistent use of icons helps users quickly recognize and understand their function, improving overall usability.
+Refer to the [default set](#default-icon-set) for icons commonly used across the platform.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.ConsistentDo} />
+</DosAndDonts>
+
+#### Do use the appropriate fill for the icon context and state
+
+Filled icons can indicate an active state or selection. Unfilled icons often represent a default or inactive state. Not all icons change appearance when toggled between filled and unfilled, so use this distinction thoughtfully.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.FilledUnfilledDo} />
+</DosAndDonts>
+
+#### Do use the correct optical size
+
+Scale the optical size to match the size of the icon - do not mix icon sizes with a different optical size.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.OpticalSizeDo} />
+  <DoOrDont story={IconStories.OpticalSizeDont} isDont />
+</DosAndDonts>
+
+#### Do align the icon vertically
+
+Vertically center the icon by shifting down the baseline of symbols to approximately 11.5% of the type size.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.AlignmentDo} />
+  <DoOrDont story={IconStories.AlignmentDont} isDont />
+</DosAndDonts>
+
+#### Do use icon colors that meet 3:1 contrast ratios with their background
+
+Icons should be easily distinguishable and clearly visible against their background to ensure they are accessible to all users, including those with visual impairments.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.ContrastDo} />
+  <DoOrDont story={IconStories.ContrastDont} isDont />
+</DosAndDonts>
+
+#### Do use color purposefully
+
+Where suitable, color can be used to highlight an icon or reinforce its meaning, such as using green for success or red for errors.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.ColorPurposefulDo} />
+</DosAndDonts>
+
+#### Don't rely on color alone
+
+Ensure that icons are distinguishable by varying the icon, fill, or labels. Relying only on color can make the interface less accessible to colorblind users.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.DistinguishDo} />
+  <DoOrDont story={IconStories.DistinguishDont} isDont />
+</DosAndDonts>
+
+#### Don't overload your interface with too many icons
+
+Overusing icons can create visual clutter and overwhelm users. Use them sparingly to highlight important actions or information.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.InterfaceDont} isDont />
+</DosAndDonts>
+
+#### Don't rely on icons alone for conveying important information
+
+Icons should support, not replace, text labels, especially for accessibility. Screen readers and other assistive technologies may not always interpret icons correctly.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.ImportantInformationDo} />
+  <DoOrDont story={IconStories.ImportantInformationDont} isDont />
+</DosAndDonts>
+
+#### Do use appropriate states on interactive icons
+
+If the icon is interactive, it should have a base, hover, and focus state.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.InteractiveStatesDo} />
+</DosAndDonts>
+
+#### Don't rely on tooltips to covey icon meaning
+
+Important information can be hidden if it's only explained in tooltips, leading to poor user experience. Whenever possible, include a text label or other contextual information alongside the icon to clearly convey its meaning.
+
+<DosAndDonts>
+  <DoOrDont story={IconStories.TooltipDont} isDont />
+</DosAndDonts>
+
+## Default icon set
+
+Whilst you have access to all Material Symbols, the following icons match the default set we have in Figma.
+
+<Story of={IconStories.DefaultIconSet} />

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

@@ -0,0 +1,17 @@
+.interactiveIcon {
+  position: relative;
+  background: none;
+  padding: 0;
+  color: var(--color-blue-500);
+
+  &:hover {
+    color: var(--color-blue-400);
+  }
+}
+
+.interactiveIcon:focus::after {
+  position: absolute;
+  content: "";
+  border: var(--border-focus-ring-border-width) solid var(--color-blue-500);
+  inset: -2px;
+}