@kaizen/components 1.51.0 → 1.52.1

package/src/KaizenProvider/subcomponents/OptionalIntlProvider/OptionalIntlProvider.tsx

@@ -1,10 +1,11 @@
-import React, { useContext } from "react"
+import React, { ReactNode, useContext } from "react"
 import { StaticIntlProvider } from "@cultureamp/i18n-react-intl"
+import { I18nProvider } from "react-aria"
 import { IntlContext } from "react-intl"
 
 type Props = {
   locale: string
-  children: React.ReactElement
+  children: ReactNode
 }
 export const OptionalIntlProvider = ({
   locale,
@@ -12,8 +13,17 @@ export const OptionalIntlProvider = ({
 }: Props): JSX.Element => {
   const parent = useContext(IntlContext)
 
-  if (parent) return children
-  return <StaticIntlProvider locale={locale}>{children}</StaticIntlProvider>
+  if (parent) {
+    // we always wrap with react-aria provider as we have no way checking if parent is wrapped (useLocale returns default value if not)
+    // but it's not a big deal as we'll consume the defined locale anyways so no effect on children
+    return <I18nProvider locale={parent.locale}>{children}</I18nProvider>
+  }
+
+  return (
+    <StaticIntlProvider locale={locale}>
+      <I18nProvider locale={locale}>{children}</I18nProvider>
+    </StaticIntlProvider>
+  )
 }
 
 OptionalIntlProvider.displayName = "OptionalIntlProvider"

package/src/MultiSelect/subcomponents/MultiSelectToggle/MultiSelectToggle.tsx

@@ -3,7 +3,7 @@ import classnames from "classnames"
 import { ClearButton } from "~components/ClearButton"
 import { FieldMessageProps } from "~components/FieldMessage"
 import { ChevronDownIcon, ChevronUpIcon } from "~components/Icon"
-import { RemovableTag } from "~components/__future__/Tag"
+import { RemovableTag } from "~components/__future__"
 import { OverrideClassName } from "~types/OverrideClassName"
 import { MultiSelectOption } from "../../types"
 import styles from "./MultiSelectToggle.module.scss"

package/src/Notification/subcomponents/GenericNotification/GenericNotification.tsx

@@ -18,7 +18,7 @@ export type GenericNotificationProps = {
   noBottomMargin?: boolean
   forceMultiline?: boolean
   headingProps?: HeadingProps
-} & OverrideClassName<HTMLAttributes<HTMLDivElement>>
+} & Omit<OverrideClassName<HTMLAttributes<HTMLDivElement>>, "style">
 
 export const GenericNotification = ({
   type,

package/src/RichTextEditor/RichTextEditor/subcomponents/ToggleIconButton/ToggleIconButton.tsx

@@ -1,6 +1,6 @@
 import React from "react"
 import classnames from "classnames"
-import { Tooltip } from "~components/Tooltip"
+import { Tooltip } from "~components/__overlays__/Tooltip/v1"
 import { OverrideClassName } from "~types/OverrideClassName"
 import { ToggleIconButtonMoods } from "./types"
 import styles from "./ToggleIconButton.module.scss"

package/src/Table/Table.tsx

@@ -7,7 +7,7 @@ import {
   SortAscendingIcon,
   SortDescendingIcon,
 } from "~components/Icon"
-import { Tooltip } from "~components/Tooltip"
+import { Tooltip } from "~components/__overlays__/Tooltip/v1"
 import { OverrideClassName } from "~types/OverrideClassName"
 import styles from "./Table.module.scss"
 

package/src/Tabs/_docs/Tabs.stories.tsx

@@ -3,7 +3,7 @@ import { Meta, StoryObj } from "@storybook/react"
 import { Button } from "~components/Button"
 import { Card } from "~components/Card"
 import { Text } from "~components/Text"
-import { Tabs, TabList, Tab, TabPanels, TabPanel } from "../index"
+import { Tab, TabList, TabPanel, TabPanels, Tabs } from "../index"
 
 const meta = {
   title: "Components/Tabs",

package/src/Tabs/subcomponents/Tab.tsx

@@ -1,11 +1,13 @@
 import React, {
   HTMLAttributes,
   ReactNode,
-  useState,
   SyntheticEvent,
+  useRef,
+  useState,
 } from "react"
 import { Tab as ReachTab } from "@reach/tabs"
 import classnames from "classnames"
+import { useFocusable } from "react-aria"
 import { Badge } from "~components/Badge"
 import { OverrideClassName } from "~types/OverrideClassName"
 import styles from "./Tab.module.scss"
@@ -44,34 +46,38 @@ export const Tab = (props: TabProps): JSX.Element => {
     classNameOverride,
     ...restProps
   } = props
+  const ref = useRef<HTMLButtonElement>(null)
   const [isHovered, setIsHovered] = useState<boolean>(false)
   const [isFocused, setIsFocused] = useState<boolean>(false)
   const showActiveBadge = isSelected || isHovered || isFocused
 
-  const onFocus = (event: SyntheticEvent): void => {
-    setIsFocused(true)
-    props.onFocus?.(event)
+  const tabProps = {
+    disabled,
+    className: classnames(
+      styles.tab,
+      classNameOverride,
+      isSelected && styles.selected
+    ),
+    onFocus: (event: SyntheticEvent): void => {
+      setIsFocused(true)
+      props.onFocus?.(event)
+    },
+    onBlur: (event: SyntheticEvent): void => {
+      setIsFocused(false)
+      props.onBlur?.(event)
+    },
+    onMouseEnter: (): void => setIsHovered(true),
+    onMouseLeave: (): void => setIsHovered(false),
+    ...restProps,
   }
 
-  const onBlur = (event: SyntheticEvent): void => {
-    setIsFocused(false)
-    props.onBlur?.(event)
-  }
+  const { focusableProps } = useFocusable(tabProps, ref)
+
+  // Reach is setting and managing tabIndex for us here, so we remove it from the focusableProps (also it needs to be non-defined, undefined is not enough)
+  delete focusableProps.tabIndex
 
   return (
-    <ReachTab
-      disabled={disabled}
-      className={classnames(
-        styles.tab,
-        classNameOverride,
-        isSelected && styles.selected
-      )}
-      onFocus={onFocus}
-      onBlur={onBlur}
-      onMouseEnter={(): void => setIsHovered(true)}
-      onMouseLeave={(): void => setIsHovered(false)}
-      {...restProps}
-    >
+    <ReachTab ref={ref} {...tabProps} {...focusableProps}>
       {children}
       {badge && (
         <span className={styles.badge}>

package/src/__future__/Workflow/subcomponents/Header/Header.tsx

@@ -18,7 +18,7 @@ export const Header = ({
   ...restProps
 }: HeaderProps): JSX.Element => (
   <HeaderRoot {...restProps}>
-    <Branding alt="Cultureamp" />
+    <Branding alt="Culture Amp" />
     <Titles workflowName={workflowName} stepName={stepName} status={status} />
     <Actions headerActions={headerActions} />
   </HeaderRoot>

package/src/__overlays__/Focusable/v3/Focusable.module.scss

@@ -0,0 +1,3 @@
+.focusableWrapper {
+  display: inline-flex;
+}

package/src/__overlays__/Focusable/v3/Focusable.tsx

@@ -0,0 +1,37 @@
+import React, { HTMLAttributes, ReactNode, useRef } from "react"
+import classnames from "classnames"
+import { FocusableOptions, useFocusable } from "react-aria"
+import styles from "./Focusable.module.scss"
+
+export type FocusableProps = {
+  children: ReactNode
+} & FocusableOptions &
+  HTMLAttributes<HTMLDivElement>
+
+export const Focusable = ({
+  children,
+  className,
+  ...props
+}: FocusableProps): JSX.Element => {
+  const ref = useRef<HTMLDivElement>(null)
+  const { focusableProps } = useFocusable(props, ref)
+
+  return (
+    <div
+      ref={ref}
+      className={classnames(styles.focusableWrapper, className)}
+      {...focusableProps}
+      data-inline-hidden-content
+      // We want the div to be focusable for keyboard users,
+      // but screen readers will have the VisuallyHidden content
+      // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+      tabIndex={0}
+      // aria-describedby on div doesn't do anthing so we instead render the content in VisuallyHidden from tooltip
+      // but because RAC adds it as it assumes it's interactive element we remove it here
+      aria-describedby={undefined}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}

package/src/__overlays__/Focusable/v3/_docs/ApiSpecification.mdx

@@ -0,0 +1,38 @@
+import { Canvas, Controls, Meta } from "@storybook/blocks"
+import { KAIOInstallation, ResourceLinks,  SbContent } from "~storybook/components"
+import * as exampleStories from "./Focusable.stories"
+
+<Meta title="Overlays/Focusable/v3/API Specification"/>
+
+<SbContent>
+  # Focusable API Specification (v3)
+
+  Updated June 25, 2024
+</SbContent>
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/__overlays__/Focusable"
+  className="mt-16 !mb-8"
+/>
+
+<SbContent className="mb-24">
+  <KAIOInstallation exportNames={["Focusable"]} family="overlays" version="3" />
+
+  ## Overview
+
+  Focusable is a utility wrapper to allow users to add focus to a non-focusable element.
+
+  The main use case is for non semantic components like `Tag` that need a [Tooltip](/docs/overlays-tooltip-v3-usage-guidelines--docs).
+</SbContent>
+
+<Canvas className="mb-24" of={exampleStories.Playground} />
+
+<SbContent className="mb-64">
+  Be aware that this does not negate the need to meet A11Y standards and best practices. Use this utility wrapper with caution.
+</SbContent>
+
+<SbContent className="mb-12">
+  ## API
+</SbContent>
+
+<Controls of={exampleStories.Playground}  />

package/src/__overlays__/Focusable/v3/_docs/Focusable.stories.tsx

@@ -0,0 +1,24 @@
+import React from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import { Tag } from "~components/__future__/Tag"
+import { Focusable } from "../index"
+
+const meta = {
+  title: "Overlays/Focusable/v3",
+  component: Focusable,
+  parameters: {
+    layout: "centered",
+  },
+} satisfies Meta<typeof Focusable>
+
+export default meta
+
+type Story = StoryObj<typeof Focusable>
+
+export const Playground: Story = {
+  render: args => (
+    <Focusable {...args}>
+      <Tag>Name</Tag>
+    </Focusable>
+  ),
+}

package/src/__overlays__/Focusable/v3/index.ts

@@ -0,0 +1 @@
+export * from "./Focusable"

package/src/{Tooltip → __overlays__/Tooltip/v1}/Tooltip.module.scss

@@ -3,7 +3,7 @@
 @import "~@kaizen/design-tokens/sass/color";
 @import "~@kaizen/design-tokens/sass/animation";
 @import "~@kaizen/design-tokens/sass/typography";
-@import "../../styles/utils/layers";
+@import "../../../../styles/utils/layers";
 @import "./variables";
 
 .tooltip {

package/src/__overlays__/Tooltip/v1/_docs/Tooltip.mdx

@@ -0,0 +1,139 @@
+import { Canvas, Controls, Meta } from "@storybook/blocks"
+import { ResourceLinks, Installation } from "~storybook/components"
+import * as TooltipStories from "./Tooltip.stories"
+
+<Meta of={TooltipStories} />
+
+# Tooltip (v1)
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Tooltip"
+  figma="https://www.figma.com/file/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-UI-Kit%3A-Heart?type=design&node-id=1929%3A32006&mode=design&t=LwTCBZ5E1uRvOA1l-1"
+  designGuidelines="https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3075604978/Tooltip"
+  className="!mb-8"
+/>
+
+<Installation
+  installCommand="pnpm add @kaizen/components"
+  importStatement='import { Tooltip } from "@kaizen/components/v1/overlays"'
+/>
+
+It is recommended that you import from the `v2` entry point.
+
+
+## Overview
+
+Adds a popover that will show on hover or focus of the child element, with simple text content.
+
+<Canvas of={TooltipStories.Playground} />
+<Controls of={TooltipStories.Playground} />
+
+## Accessibility
+
+This component wasn't built with accessibility in mind, as a result it's quite easy to implement a tooltip in a non-accessible way. A rethink and rewrite is likely for the future.
+
+There's two major accessibility concerns here:
+- Keyboard only users
+- Screen reader (or similar assistive tech) users
+
+Failure to meet either of these requirements will result in a critical issue where some people are completely unable to access the information.
+
+### Keyboard accessibility
+
+For keyboard accessibility, you need to make sure the child you are passing is a focusable element. It's best to keep the contents of this component simple. E.g. just a button:
+
+```jsx
+<Tooltip text="Opens in a new tab">
+  <Button href="/path" label="Go somewhere" />
+</Tooltip>
+```
+
+### Screen reader accessibility
+
+Though it won't guarantee the best screen reader accessibility, a good start is to make sure your _direct_ children element is semantic (not a div or span).
+
+When your direct child element is semantic, this component will add an `aria-describedby` to that element. E.g. for the link example above, the resulting mark up will be:
+
+```html
+<a href="path" aria-describedby="tooltip">Go somewhere</a>
+<!-- (in a portal) -->
+<div id="tooltip-id">Opens in a new tab</div>
+```
+
+Resulting in a screen reader announcement like:
+`Go somewhere, link, Opens in a new tab`
+
+Again, try to keep the contents of your children as simple as possible, ideally only a single natively focusable element like the example above.
+
+When your direct child is not semantic, you will get a console warning like this:
+`<Tooltip /> is not directly wrapping a semantic element, screen reader users will not be able to access the tooltip info.`
+
+
+### Tooltips, Kaizen components and avoiding common pitfalls
+
+While technically any Kaizen component can be wrapped by a `Tooltip`, as called out previously, only those with [accessible roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) like `button`, `link` or `heading`, will be readable to assistive technologies.
+
+We've created some guidance below with the most common cases for `Tooltip` and how to ensure the additional context is read to the user.
+
+#### Button and IconButton
+
+<Canvas of={TooltipStories.ButtonsWithTooltip} />
+
+While Kaizen buttons are compatible with `Tooltip`, caution is advised when using the custom `component` render prop.
+
+```JSX
+  <Tooltip text="Contact customer support.">
+    <Button
+      {...buttonProps}
+      component={() => (
+        // The most immediate child is a `div`, which has no `role`.
+        <div>
+          <button type="button">
+            Help
+          </button>
+        </div>
+      )}
+    />
+  </Tooltip>
+```
+
+In the example above, the `div` in now the direct descendant of `Tooltip`, therefore will no longer be accessible to assistive technologies.
+
+#### ButtonGroup
+
+The `Tooltip` component must wrap the children of `ButtonGroup` to be accessible to screen readers.
+
+<Canvas of={TooltipStories.ButtonGroupWithTooltip} />
+
+#### Table headers and tooltips
+
+While the composable `Tooltip` is not exposed in the Kaizen `Table`, it is important to call out that the `tooltipInfo` prop in `TableHeaderRowCell` must also have an `onClick` or `href` to be announced to assistive technologies.
+
+<Canvas of={TooltipStories.TableHeadersWithTooltips} />
+
+Without either of these, the `Tooltip` content will not be readable to keyboard users or assistive technologies.
+
+#### Tags
+
+Seen in the example below simple `Tag`s with plain text as `children` will not accessible to keyboard users or assistive technologies as it's direct descendant is a `div` with no semantic `role`.
+
+<Canvas of={TooltipStories.TagWithHoverOnlyTooltip}  />
+
+While `Tooltip` should be avoided if there are no interactive states within the `Tag`, internal elements like buttons or links can be wrapped in a `Tooltip` component to add necessary context.
+
+<Canvas of={TooltipStories.TagWithTooltip} />
+
+The [future Tag](?path=/docs/components-tag-future--docs#overview) offers a composable solution for those needing to add more context to an interactive `Tag`.
+
+#### Form components and tooltips
+
+While a `Tooltip` can seem like a natural pairing when space is a commodity, form elements still require a concise label that is _ideally_ visible (See MDN's guide on [Tooltip best practices](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role#best_practices)).
+
+<Canvas of={TooltipStories.CheckboxFieldTooltip} />
+
+In the example above, the `Tooltip` content `"Select all users"` is accessible to screen readers via keyboard navigation, however will not be announced when the input receives focus. This a limitation of `CheckboxField` and form components where the immediate `children` of `Tooltip` is a wrapper.
+
+<Canvas of={TooltipStories.CheckboxFieldWithDescriptionTooltip} />
+
+In these instances, `aria-describedby` can be leveraged to provide a description to the input.
+

package/src/{Tooltip → __overlays__/Tooltip/v1}/_docs/Tooltip.stickersheet.stories.tsx

@@ -15,7 +15,7 @@ const openTooltipInChromatic: Decorator = (Story, { args }) => {
 }
 
 export default {
-  title: "Components/Tooltip",
+  title: "Overlays/Tooltip/v1",
   parameters: {
     chromatic: { disable: false },
     controls: { disable: true },

package/src/{Tooltip → __overlays__/Tooltip/v1}/_docs/Tooltip.stories.tsx

@@ -12,11 +12,11 @@ import {
   TableRow,
 } from "~components/Table"
 import { Text } from "~components/Text"
-import { Tag } from "~components/__future__"
+import { Tag } from "~components/__future__/Tag"
 import { Tooltip } from "../index"
 
 const meta = {
-  title: "Components/Tooltip",
+  title: "Overlays/Tooltip/v1",
   component: Tooltip,
   args: {
     text: "Example tooltip text.",

package/src/__overlays__/Tooltip/v1/index.ts

@@ -0,0 +1,7 @@
+// Since we can't add a deprecation flag on a * export
+import { Tooltip as TooltipV1, TooltipProps as TooltipPropsV1 } from "./Tooltip"
+
+/** * @deprecated use v2 or upgrade to v3 for the latest release */
+export const Tooltip = TooltipV1
+/** * @deprecated use v2 or upgrade to v3 for the latest release */
+export type TooltipProps = TooltipPropsV1

package/src/{Tooltip → __overlays__/Tooltip/v2}/_docs/Tooltip.mdx

@@ -4,16 +4,14 @@ import * as TooltipStories from "./Tooltip.stories"
 
 <Meta of={TooltipStories} />
 
-# Tooltip
+# Tooltip (v2)
 
 <ResourceLinks
   sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Tooltip"
   figma="https://www.figma.com/file/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-UI-Kit%3A-Heart?type=design&node-id=1929%3A32006&mode=design&t=LwTCBZ5E1uRvOA1l-1"
-  designGuidelines="https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3075604978/Tooltip"
-  className="!mb-8"
 />
 
-<KAIOInstallation exportNames="Tooltip" />
+<KAIOInstallation exportNames="Tooltip" family="overlays" version="2" />
 
 ## Overview
 

package/src/__overlays__/Tooltip/v2/_docs/Tooltip.stories.tsx

@@ -0,0 +1,49 @@
+import React from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import * as TooltipV1Stories from "../../v1/_docs/Tooltip.stories"
+import { Tooltip } from "../index"
+
+const meta = {
+  title: "Overlays/Tooltip/v2",
+  component: Tooltip,
+  args: {
+    text: "Example tooltip text.",
+  },
+  decorators: [
+    Story => (
+      <div className="flex mt-[60px] gap-12">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: "centered",
+  },
+} satisfies Meta<typeof Tooltip>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = TooltipV1Stories.Playground
+
+export const OverflowScroll: Story = TooltipV1Stories.OverflowScroll
+
+export const ButtonsWithTooltip: Story = TooltipV1Stories.ButtonsWithTooltip
+
+export const ButtonGroupWithTooltip: Story = TooltipV1Stories.ButtonsWithTooltip
+
+export const TableHeadersWithTooltips: Story =
+  TooltipV1Stories.TableHeadersWithTooltips
+
+export const TagWithHoverOnlyTooltip: Story =
+  TooltipV1Stories.TagWithHoverOnlyTooltip
+
+export const TagWithTooltip: Story = TooltipV1Stories.TagWithTooltip
+
+export const TagWithCheckboxField: Story = TooltipV1Stories.TagWithCheckboxField
+
+export const CheckboxFieldTooltip: Story = TooltipV1Stories.CheckboxFieldTooltip
+
+export const CheckboxFieldWithDescriptionTooltip: Story =
+  TooltipV1Stories.CheckboxFieldWithDescriptionTooltip

package/src/__overlays__/Tooltip/v2/index.ts

@@ -0,0 +1 @@
+export * from "../v1/Tooltip"

package/src/__overlays__/Tooltip/v3/OverlayArrow.module.scss

@@ -0,0 +1,43 @@
+@import "~@kaizen/design-tokens/sass/shadow";
+@import "~@kaizen/design-tokens/sass/color";
+
+.overlayArrow {
+  display: flex;
+
+  // for correct arrow positioning with rounded corners we need to do bit trickery here
+  // the positioning is done in js in RAC and works by first getting size of arrow without data-placement, and isn't recomputed after update
+  // so we first set padding on arrow from all sides (that'll be used for start position computation)
+  // and then we remove it from the oposite axis
+  padding: 8px;
+
+  &[data-placement="top"],
+  &[data-placement="bottom"] {
+    padding: 0 8px;
+  }
+
+  &[data-placement="left"],
+  &[data-placement="right"] {
+    padding: 8px 0;
+  }
+
+  path {
+    fill: $color-purple-800;
+    box-shadow: $shadow-small-box-shadow;
+  }
+
+  &[data-placement="right"] svg {
+    transform: rotate(90deg);
+  }
+
+  &[data-placement="bottom"] svg {
+    transform: rotate(180deg);
+  }
+
+  &[data-placement="left"] svg {
+    transform: rotate(270deg);
+  }
+
+  &.reversed path {
+    fill: $color-white;
+  }
+}

package/src/__overlays__/Tooltip/v3/OverlayArrow.tsx

@@ -0,0 +1,34 @@
+import React from "react"
+import {
+  OverlayArrow as RACOverlayArrow,
+  type OverlayArrowProps,
+} from "react-aria-components"
+import { useReversedColors } from "~components/__utilities__/v3"
+import { mergeClassNames } from "~utils/mergeClassNames"
+
+import styles from "./OverlayArrow.module.scss"
+
+export { type OverlayArrowProps }
+
+/**
+ * An OverlayArrow renders a custom arrow element relative to an overlay element
+ * such as a popover or tooltip such that it aligns with a trigger element.
+ */
+export const OverlayArrow = (props: OverlayArrowProps): JSX.Element => {
+  const reverseColors = useReversedColors()
+
+  return (
+    <RACOverlayArrow
+      {...props}
+      className={mergeClassNames(
+        styles.overlayArrow,
+        reverseColors && styles.reversed,
+        props.className
+      )}
+    >
+      <svg width={8} height={8} viewBox="0 0 8 8">
+        <path d="M0 0 L4 4 L8 0" />
+      </svg>
+    </RACOverlayArrow>
+  )
+}