@kaizen/components 1.51.0 → 1.52.0

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

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

@@ -0,0 +1,163 @@
+import { Canvas, Controls, Meta } from "@storybook/blocks"
+import { KAIOInstallation, ResourceLinks,  SbContent } from "~storybook/components"
+import * as docsStories from "./Tooltip.docs.stories"
+import * as exampleStories from "./Tooltip.stories"
+
+<Meta title="Overlays/Tooltip/v3/API Specification"/>
+
+<SbContent>
+  # Tooltip API Specification (v3)
+
+  Updated June 25, 2024
+</SbContent>
+
+<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="/?path=/docs/overlays-tooltip-v3-usage-guidelines--docs"
+  ariaComponentPage="https://react-spectrum.adobe.com/react-aria/Tooltip.html"
+  className="mt-16 !mb-8"
+/>
+
+<SbContent className="mb-24">
+
+  <KAIOInstallation exportNames={["Tooltip", "TooltipTrigger" ]} family="overlays" version="3" />
+
+  ## Overview
+
+  Tooltips are brief floating labels used to add additional contextual information when users hover, click or focus on an interactive element.
+</SbContent>
+
+<Canvas
+  className="mb-64"
+  of={exampleStories.OnButton}
+  source={{code: `
+<TooltipTrigger>
+  <Button label="Button" />
+  <Tooltip>Tooltip content</Tooltip>
+</TooltipTrigger>
+  `}}
+/>
+
+<SbContent className="mb-64">
+  ### React Aria
+
+  This component is built using the `react-aria-components` library and extends the [Tooltip component](https://react-spectrum.adobe.com/react-aria/Tooltip.html).
+
+  As this shares the same core [anatomy](https://react-spectrum.adobe.com/react-aria/Tooltip.html#anatomy), [props types](https://react-spectrum.adobe.com/react-aria/Tooltip.html#tooltip-1) and [functionality](https://react-spectrum.adobe.com/react-aria/Tooltip.html#features), the guidance below is tailored to our implementation and should cover known use cases of the Tooltip.
+
+  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/Tooltip.html) if not present below.
+</SbContent>
+
+<SbContent className="mb-12">
+  ## API
+</SbContent>
+
+<Controls of={exampleStories.OnButton}  />
+
+<SbContent className=" mt-64">
+  ### Placement
+
+  Placement controls where the `Tooltip` will float, relative to its reference element defined by the `triggerRef`. By default, this will float to the `bottom`.
+</SbContent>
+
+<Canvas className="mb-24" of={exampleStories.Placement}  />
+
+<SbContent>
+  The option, `shouldFlip`, will control whether the `Tooltip` inverts its orientation when insufficient room is available in the viewport. You can see the below example with a constrained [viewport here](?path=/story/overlays-tooltip-v3--should-flip&globals=viewport:small).
+</SbContent>
+
+<Canvas className="mb-64" of={docsStories.ShouldFlip}  />
+
+<SbContent>
+  ### Controlled state
+
+  By default, the `Tooltip` state is controlled, so all interactive states do not need to be defined. There may be instances where a users may want want to toggle a `Tooltip` on or off. In this case we have exposed the `isOpen` prop.
+</SbContent>
+
+<Canvas className="mb-24" of={docsStories.UncontrolledState}  />
+
+<SbContent className="mb-64">
+  `isOpen` prop will negate the default state and relinquish control of `Tooltip` open and close to the user.
+</SbContent>
+
+<SbContent>
+  ### TooltipTrigger
+
+  The `TooltipTrigger` wraps both the `Tooltip` and its trigger element, controlling the open and close interactions.
+</SbContent>
+
+```JSX
+
+<TooltipTrigger>
+ */ In this case the trigger element is the Button /*
+  <Button label="Button" />
+   */ The Tooltip and its content is a child of the trigger /*
+  <Tooltip>
+    Tooltip content
+  </Tooltip>
+</TooltipTrigger>
+```
+
+<SbContent className="mb-64">
+  Any compatible interactive element within the `TooltipTrigger` will enable the interaction state.
+</SbContent>
+
+<SbContent>
+  ### Reversed
+
+  The `Tooltip` uses the `useReversedColors` hook and `ReversedColors` provider to control the dark and light theme.
+</SbContent>
+
+<Canvas className="bg-purple-600 mb-24" of={exampleStories.OnReversed} />
+
+<SbContent>
+  To enable the reversed theme, you will need to the component or application in the `ReversedColors` provider.
+</SbContent>
+
+```JSX
+<ReversedColors isReversed={true}>
+  <Component />
+</ReversedColors>
+```
+
+<SbContent className="mb-64">
+  These utilities can be imported from `@kaizen/components/v3/utilities`. This is an emerging pattern so more documentation will come.
+</SbContent>
+
+<SbContent className="mb-32">
+  ## Examples
+
+  Here are examples of how to use the `Tooltip` with compatible Kaizen components.
+</SbContent>
+
+<SbContent>
+  ### On Button
+</SbContent>
+
+<Canvas of={exampleStories.OnButton} />
+
+<SbContent>
+  ### On Link
+</SbContent>
+
+<Canvas of={exampleStories.OnLink} />
+
+<SbContent>
+  ### On IconButton
+</SbContent>
+
+<Canvas of={exampleStories.OnIconButton} />
+
+<SbContent>
+  ### On Tabs
+</SbContent>
+
+<Canvas of={exampleStories.OnTabs} />
+
+<SbContent>
+  ### On Tag
+</SbContent>
+
+<Canvas of={exampleStories.OnCustomFocusableElement} />
+

package/src/__overlays__/Tooltip/v3/_docs/Tooltip.docs.stories.tsx

@@ -0,0 +1,203 @@
+import React from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import isChromatic from "chromatic"
+import { Button, IconButton } from "~components/Button"
+import { FieldMessage } from "~components/FieldMessage"
+import { AddIcon, QuestionIcon } from "~components/Icon"
+import { Input } from "~components/Input"
+import { Label } from "~components/Label"
+import { Focusable } from "~components/__overlays__/v3"
+import { Tooltip, TooltipTrigger } from "../index"
+import * as TestStories from "./Tooltip.spec.stories"
+
+const meta = {
+  title: "Overlays/Tooltip/v3/Docs Assets",
+  component: Tooltip,
+  parameters: {
+    layout: "centered",
+    a11y: { disable: true },
+  },
+  args: {
+    defaultOpen: isChromatic(),
+  },
+  argTypes: {
+    // eslint-disable-next-line camelcase
+    UNSTABLE_portalContainer: {
+      control: false,
+      table: { disable: true },
+    },
+    triggerRef: { control: false },
+  },
+} satisfies Meta<typeof Tooltip>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  render: ({ defaultOpen: _, isOpen, ...args }) => (
+    <TooltipTrigger defaultOpen={true} isOpen={isOpen}>
+      <Button label="Button" />
+      <Tooltip {...args}>Tooltip content</Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+export const Primary: Story = {
+  render: () => (
+    <TooltipTrigger>
+      <IconButton
+        label="Add something"
+        icon={<AddIcon role="presentation" />}
+        primary
+        // Negate the aria description (added by RAC) as it should be the
+        // same as the accessible name, therefore no need to duplicate it
+        aria-describedby={null}
+      />
+      <Tooltip>Add something</Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+export const Placement: Story = {
+  ...TestStories.Placement,
+}
+
+export const DoFieldTooltip: Story = {
+  render: () => (
+    <div>
+      <Label>Password</Label>
+      <Input type="text" />
+      <FieldMessage message="Password must be at least 8 characters." />
+    </div>
+  ),
+}
+
+export const DontFieldTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <div>
+      <TooltipTrigger>
+        <Focusable>
+          <Label>
+            Password{" "}
+            <span className="inline-flex align-middle">
+              <QuestionIcon
+                classNameOverride="w-[15px] m-auto"
+                role="presentation"
+              />
+            </span>
+          </Label>
+        </Focusable>
+        <Tooltip>Password must be at least 8 characters</Tooltip>
+      </TooltipTrigger>
+      <div className="flex gap-4">
+        <Input type="text" />
+      </div>
+    </div>
+  ),
+}
+
+export const DoConcise: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <div>
+      <TooltipTrigger>
+        <IconButton
+          label="Add topic"
+          icon={<AddIcon role="presentation" />}
+          primary
+          // Negate the aria description (added by RAC) as it should be the
+          // same as the accessible name, therefore no need to duplicate it
+          aria-describedby={null}
+        />
+        <Tooltip>Add topic to agenda</Tooltip>
+      </TooltipTrigger>
+    </div>
+  ),
+}
+
+export const DontConcise: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <div>
+      <TooltipTrigger>
+        <IconButton
+          label="Add something"
+          icon={<AddIcon role="presentation" />}
+          primary
+          // Negate the aria description (added by RAC) as it should be the
+          // same as the accessible name, therefore no need to duplicate it
+          aria-describedby={null}
+        />
+        <Tooltip>
+          Add Topic to agenda. This will create a new topic where you can
+          discuss recent work with your manager.{" "}
+        </Tooltip>
+      </TooltipTrigger>
+    </div>
+  ),
+}
+
+export const ShouldFlip: Story = {
+  play: undefined,
+  render: () => (
+    <div className="flex flex-col gap-8 pl-96 overflow-hidden max-w-[250px]">
+      <TooltipTrigger>
+        <Button label="Should flip" />
+        <Tooltip placement="end">Tooltip content</Tooltip>
+      </TooltipTrigger>
+      <TooltipTrigger>
+        <Button label="Won't flip" />
+        <Tooltip placement="end" shouldFlip={false}>
+          Tooltip content
+        </Tooltip>
+      </TooltipTrigger>
+    </div>
+  ),
+  parameters: {
+    viewport: {
+      viewports: {
+        small: {
+          name: "small",
+          styles: {
+            width: "300px",
+            height: "300px",
+          },
+        },
+      },
+      defaultViewport: "small",
+    },
+  },
+}
+
+export const UncontrolledState: Story = {
+  play: undefined,
+  args: { placement: "end", shouldFlip: false },
+  render: () => {
+    const [isOpen, setIsOpen] = React.useState<boolean>(false)
+    return (
+      <div className="flex gap-12">
+        <button type="button" onClick={() => setIsOpen(!isOpen)}>
+          Toggle open
+        </button>
+        <TooltipTrigger isOpen={isOpen}>
+          <Button label="Button" />
+          <Tooltip>Tooltip content</Tooltip>
+        </TooltipTrigger>
+      </div>
+    )
+  },
+}

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

@@ -0,0 +1,182 @@
+import { Canvas, Meta, Controls } from "@storybook/blocks"
+import { CheckIcon, ClearIcon } from "~components/Icon"
+import { ResourceLinks, SbContent, Installation } from "~storybook/components"
+import * as TooltipStories from "./Tooltip.docs.stories"
+import AnatomyPng from "./assets/tooltip_anatomy.png"
+import PlacementPng from "./assets/tooltip_placement.png"
+import Trigger1Png from "./assets/tooltip_trigger_1.png"
+import Trigger2Png from "./assets/tooltip_trigger_2.png"
+import Trigger3Png from "./assets/tooltip_trigger_3.png"
+import WhenToUsePng from "./assets/tooltip_variant.png"
+
+<Meta title="Overlays/Tooltip/v3/Usage Guidelines" />
+
+<SbContent>
+  # Tooltip (v3)
+
+  Updated June 25, 2024
+</SbContent>
+
+
+<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="/?path=/docs/overlays-tooltip-v3-usage-guidelines--docs"
+  ariaComponentPage="https://react-spectrum.adobe.com/react-aria/Tooltip.html"
+  apiSpecification="/?path=/docs/overlays-tooltip-v3-api-specifications--docs"
+  className="!mb-8"
+/>
+
+<SbContent>
+  <Installation
+    installCommand="pnpm add @kaizen/components"
+    importStatement='import { Tooltip, TooltipTrigger } from "@kaizen/components/v3/overlays"'
+  />
+
+  ## Overview
+
+  Tooltips are brief floating labels used to add additional contextual information when users hover, click or focus on an interactive element. These should offer concise explanations,  elaborating on the element they are associated with.
+</SbContent>
+
+
+<Canvas
+  of={TooltipStories.Playground}
+  source={{code: `
+<TooltipTrigger>
+  <Button label="Button" />
+  <Tooltip>Tooltip content</Tooltip>
+</TooltipTrigger>
+  `}}
+ />
+<Controls of={TooltipStories.Playground} include={["placement", "isOpen"]} className="mb-64" />
+
+
+<SbContent className="mb-64">
+  ### Anatomy
+
+  - The anatomy of a tooltip is made up of a container, description and arrow.
+    - **They do not include a title or heading**. If you need to include a title, use a Popover
+  - A tooltip is connected to a trigger element, such as a button or icon, that shows the tooltip when the interactive trigger element is hovered or focused. (More details below.)
+
+  <img src={AnatomyPng} alt="Indicates the anatomy of the Tooltip component, the Container, Label, Arrow and Trigger" className="mt-24" />
+</ SbContent>
+
+<SbContent className="mb-64">
+  ### When to use
+
+  - Tooltips are used to provide additional information when space is tight.
+  - Tooltips must be concise with one or more lines of text.
+  - Tooltips must be accessible via hover and focus only.
+  - Trigger tooltips from Interactive elements (Buttons, Links, Icon buttons) or Non-interactive elements (Icons, Abbreviations Truncated text)—be mindful of keyboard accessibility
+  - **Never include any kind of error messages** in a tooltip
+
+  <img src={WhenToUsePng} alt="Illustration of when to use the Tooltip component" className="mt-24"/>
+</ SbContent>
+
+<SbContent >
+  ### Dos and don'ts
+</SbContent >
+
+<div className="flex flex-col mt-16 gap-40 mb-64">
+  <div className="flex flex-col m-0 gap-16">
+    <SbContent variant="heading-4">
+      #### Do use tooltips to describe icons
+      Icons are not always easy to identify on their own. When you use components that don&apos;t have labels — for example, icon-only action buttons and tabs — make sure to use tooltips to provide context for the icons.
+    </SbContent>
+    <div className="grid grid-cols-2 gap-16">
+      <div className="relative [&>*]:m-0">
+        <div className="bg-green-500 absolute top-6 left-6 z-10 py-4 px-6 font-bold text-white rounded flex gap-2 items-center justify-center">
+          <CheckIcon role="presentation" />
+          <SbContent ><span className="text-white"><strong>Do</strong></span></SbContent>
+        </div>
+        <Canvas of={TooltipStories.Primary} className="border-green-500 !rounded" />
+      </div>
+    </div>
+  </div>
+
+  <div className="flex flex-col gap-16">
+    <SbContent variant="heading-4">
+      #### Don&apos;t use tooltips to communicate crucial information
+
+      Tooltips should never stop a user (or be a gate) from completing a task or performing an action. They disappear so they should never contain critical information that a user would absolutely need to proceed, or information without which a user may cause errors. If the information is crucial for a user to proceed, consider using a modal or inline notification instead.
+    </SbContent>
+    <div className="grid grid-cols-2 gap-16">
+      <div className="relative [&>*]:m-0">
+        <div className="bg-green-500 absolute top-6 left-6 z-10 py-4 px-6 font-bold text-white rounded flex gap-2 items-center justify-center">
+          <CheckIcon role="presentation" />
+          <SbContent ><span className="text-white"><strong>Do</strong></span></SbContent>
+        </div>
+        <Canvas of={TooltipStories.DoFieldTooltip} className="border-green-500 !rounded-[10px]" />
+      </div>
+      <div className="relative [&>*]:m-0">
+        <div className="bg-gray-500 absolute top-6 left-6 z-10 py-4 px-6 font-bold text-white rounded flex gap-2 items-center justify-center">
+          <ClearIcon role="presentation" />
+          <SbContent ><span className="text-white"><strong>Don&apos;t</strong></span></SbContent>
+        </div>
+        <Canvas of={TooltipStories.DontFieldTooltip} className="border-gray-500 !rounded-[10px]" />
+      </div>
+    </div>
+  </div>
+
+  <div className="flex flex-col m-0 gap-16">
+    <SbContent variant="heading-4">
+      #### Do be concise
+
+      Good tooltips contain concise and helpful information, keep it short. If you need more space, consider using a Popover. Don’t use it to duplicate information that already exists on the page. Instead, closely consider its placement and whether the disclosed copy will inform the action the user is about to perform.
+    </SbContent>
+    <div className="grid grid-cols-2 gap-16">
+      <div className="relative [&>*]:m-0">
+        <div className="bg-green-500 absolute top-6 left-6 z-10 py-4 px-6 font-bold text-white rounded flex gap-2 items-center justify-center">
+          <CheckIcon role="presentation" />
+          <SbContent ><span className="text-white"><strong>Do</strong></span></SbContent>
+        </div>
+        <Canvas of={TooltipStories.DoConcise} className="border-green-500 !rounded-[10px]" />
+      </div>
+      <div className="relative [&>*]:m-0">
+        <div className="bg-gray-500 absolute top-6 left-6 z-10 py-4 px-6 font-bold text-white rounded flex gap-2 items-center justify-center">
+          <ClearIcon role="presentation" />
+          <SbContent ><span className="text-white"><strong>Don&apos;t</strong></span></SbContent>
+        </div>
+        <Canvas of={TooltipStories.DontConcise} className="border-gray-500 !rounded-[10px]" />
+      </div>
+    </div>
+  </div>
+</div>
+
+<SbContent className="mb-64">
+  ### Placements
+
+  <img src={PlacementPng} alt="" className="mb-24" />
+
+  - Type: Dropdown to choose from Default (dark tooltip) and Reverse (light tooltip)
+  - Direction: Dropdown to choose where the arrow points
+  - Tooltip label: Input field allows you to type in the label from the properties panel
+  - Use strong signifiers for trigger elements to ensure the tooltip is discoverable.
+  - The proximity of tooltips is always paired to the element with which they are associated.
+</SbContent>
+
+<SbContent className="mb-64">
+  ### Trigger
+
+  - Should be shown on hover, click or on focus events
+  - Needs to be discoverable:
+    - E.g. something like an icon to suggest there’s a tooltip.
+    - Avoid triggering tooltips from text that excludes a visual indicator (e.g. underline)
+
+  <img src={Trigger1Png} alt="" className="my-24" />
+
+  - Only trigger tooltips from interactive elements, such as:
+    - Buttons
+    - Links
+    - Icon buttons
+
+  <img src={Trigger2Png} alt="" className="my-24" />
+
+  - Non-interactive elements (be mindful of keyboard accessibility):
+    - Icons
+    - Abbreviations (e.g. dashed underlined text for HRIS that shows a tooltip that says Human Resource Information System)
+    - Truncated text
+  - For interactive elements that trigger tooltips, only have optional information in the tooltip because it could be missed when the user clicks
+
+  <img src={Trigger3Png} alt="" className="my-24" />
+</SbContent>