@kaizen/components 1.50.0 → 1.52.0

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>
+  )
+}

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

@@ -0,0 +1,67 @@
+@import "~@kaizen/design-tokens/sass/shadow";
+@import "~@kaizen/design-tokens/sass/border";
+@import "~@kaizen/design-tokens/sass/color";
+@import "~@kaizen/design-tokens/sass/animation";
+@import "~@kaizen/design-tokens/sass/typography";
+@import "~@kaizen/design-tokens/sass/spacing";
+
+.tooltip {
+  max-width: 200px;
+  padding: $spacing-8 $spacing-12;
+  color: $color-white;
+  text-align: center;
+  font-family: $typography-paragraph-extra-small-font-family;
+  font-size: $typography-paragraph-extra-small-font-size;
+  font-weight: $typography-paragraph-extra-small-font-weight;
+  letter-spacing: $typography-paragraph-extra-small-letter-spacing;
+  line-height: $typography-paragraph-extra-small-line-height;
+  border-radius: $border-solid-border-radius;
+  box-shadow: $shadow-small-box-shadow;
+  background-color: $color-purple-800;
+  text-wrap: pretty;
+
+  /* fixes FF gap */
+  transform: translate3d(0, 0, 0);
+
+  &.reversed {
+    background-color: $color-white;
+    color: $color-purple-800;
+  }
+
+  &[data-placement="top"] {
+    --origin: translateY(4px);
+  }
+
+  &[data-placement="bottom"] {
+    --origin: translateY(-4px);
+  }
+
+  &[data-placement="right"] {
+    --origin: translateX(-4px);
+  }
+
+  &[data-placement="left"] {
+    --origin: translateX(4px);
+  }
+
+  &[data-entering] {
+    animation: slide $animation-duration-fast;
+  }
+
+  &[data-exiting] {
+    animation: slide $animation-duration-fast reverse
+      $animation-easing-function-ease-in;
+  }
+}
+
+@keyframes slide {
+  from {
+    transform: var(--origin);
+    opacity: 0;
+  }
+
+  to {
+    transform: translateY(0);
+    opacity: 1;
+  }
+}

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

@@ -0,0 +1,101 @@
+import React, { forwardRef, useContext, useLayoutEffect, useState } from "react"
+import { VisuallyHidden } from "react-aria"
+import {
+  Tooltip as RACTooltip,
+  TooltipContext,
+  TooltipProps as RACTooltipProps,
+  TooltipTriggerStateContext,
+  useContextProps,
+} from "react-aria-components"
+import { useReversedColors } from "~components/__utilities__/v3"
+import { mergeClassNames } from "~utils/mergeClassNames"
+import { OverlayArrow } from "./OverlayArrow"
+import styles from "./Tooltip.module.scss"
+
+export { TooltipContext }
+
+export type TooltipProps = Omit<RACTooltipProps, "offset"> & {
+  /**
+   * The additional offset applied along the main axis between the element and its
+   * anchor element.
+   * @default 8
+   */
+  offset?: number
+  /**
+   * The placement of the tooltip relative to the trigger.
+   * + we're intentionally limiting the placement options to rtl friendly ones (start, end, top, bottom)
+   */
+  placement?:
+    | "bottom"
+    | "bottom start"
+    | "bottom end"
+    | "top"
+    | "top start"
+    | "top end"
+    | "start"
+    | "start top"
+    | "start bottom"
+    | "end"
+    | "end top"
+    | "end bottom"
+}
+
+/**
+ * A tooltip displays a description of an element on hover or focus.
+ */
+export const Tooltip = forwardRef<HTMLDivElement, TooltipProps>(
+  ({ children, className, ...props }, ref): JSX.Element => {
+    const [{ triggerRef }] = useContextProps(
+      { children, className, ...props },
+      ref,
+      TooltipContext
+    )
+    const contextState = useContext(TooltipTriggerStateContext)
+    const reverseColors = useReversedColors()
+    const [shouldInlineHiddenContent, setShouldInlineHiddenContent] =
+      useState(false)
+
+    useLayoutEffect(() => {
+      setShouldInlineHiddenContent(
+        !!triggerRef?.current?.getAttribute("data-inline-hidden-content")
+      )
+    }, [triggerRef])
+
+    return (
+      <>
+        <RACTooltip
+          ref={ref}
+          offset={8}
+          {...props}
+          className={mergeClassNames(
+            styles.tooltip,
+            className,
+            reverseColors && styles.reversed
+          )}
+        >
+          {renderProps => (
+            <>
+              <OverlayArrow />
+              {typeof children === "function"
+                ? children(renderProps)
+                : children}
+            </>
+          )}
+        </RACTooltip>
+        {shouldInlineHiddenContent ? (
+          <VisuallyHidden>
+            {typeof children === "function"
+              ? children({
+                  placement: "center",
+                  isEntering: false,
+                  isExiting: false,
+                  state: contextState,
+                  defaultChildren: undefined,
+                })
+              : children}
+          </VisuallyHidden>
+        ) : null}
+      </>
+    )
+  }
+)

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

@@ -0,0 +1,30 @@
+import React from "react"
+import {
+  TooltipTrigger as RACTooltipTrigger,
+  TooltipTriggerComponentProps,
+} from "react-aria-components"
+
+export type TooltipTriggerProps = Omit<
+  TooltipTriggerComponentProps,
+  "delay" | "closeDelay"
+> & {
+  /**
+   * The delay time for the tooltip to show up. [See guidelines](https://spectrum.adobe.com/page/tooltip/#Immediate-or-delayed-appearance).
+   * @default 300
+   */
+  delay?: number
+  /**
+   * The delay time for the tooltip to close. [See guidelines](https://spectrum.adobe.com/page/tooltip/#Warmup-and-cooldown).
+   * @default 300
+   */
+  closeDelay?: number
+}
+
+/**
+ * TooltipTrigger wraps around a trigger element and a Tooltip. It handles opening and closing
+ * the Tooltip when the user hovers over or focuses the trigger, and positioning the Tooltip
+ * relative to the trigger.
+ */
+export const TooltipTrigger = (props: TooltipTriggerProps): JSX.Element => (
+  <RACTooltipTrigger delay={300} closeDelay={300} {...props} />
+)