@kaizen/components 1.51.0 → 1.52.1

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

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