@kaizen/components 0.0.0-canary-debug-kaizenprovider-20241223004555 → 0.0.0-canary-debug-kaizen-provider-take-2-20241223005900

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

@@ -0,0 +1,311 @@
+import React from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import { ButtonGroup } from "~components/ButtonGroup"
+import { CheckboxField } from "~components/Checkbox"
+import { FilterButtonBase } from "~components/Filter/FilterButton/subcomponents/FilterButtonBase"
+import {
+  TableContainer,
+  TableHeader,
+  TableHeaderRowCell,
+  TableRow,
+} from "~components/Table"
+import { Text } from "~components/Text"
+import { Button, IconButton } from "~components/__actions__/v2"
+import { Icon } from "~components/__future__"
+import { Tag } from "~components/__future__/Tag"
+import { Tooltip } from "../index"
+
+const meta = {
+  title: "Overlays/Tooltip/v1",
+  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 = {
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: "shown",
+      },
+    },
+  },
+  render: args => (
+    <Tooltip {...args}>
+      <Button label="Hover or focus me" />
+    </Tooltip>
+  ),
+}
+
+export const OverflowScroll: Story = {
+  render: props => (
+    <>
+      <p>
+        Default Placement is &apos;above&apos;. Scroll horizontally or
+        vertically to view the Tooltip &quot;flip&quot; and move according to
+        the space of the viewport. Ensuring the Tooltip does not get cut off.
+      </p>
+
+      <div
+        style={{
+          display: "flex",
+          width: "300px",
+          maxHeight: "700px",
+          overflow: "scroll",
+          border: "solid black 2px",
+          flexDirection: "column",
+        }}
+      >
+        <div
+          style={{
+            width: "500px",
+            marginLeft: "200px",
+            marginTop: "400px",
+          }}
+        >
+          <div
+            style={{
+              width: "300px",
+              height: "200px",
+              textAlign: "center",
+              position: "relative",
+            }}
+          >
+            <Tooltip {...props} display="inline-block" text="Tooltip label">
+              <Button label="Default" />
+            </Tooltip>
+          </div>
+        </div>
+        <div
+          style={{
+            width: "500px",
+            marginLeft: "200px",
+          }}
+        >
+          <div
+            style={{
+              width: "300px",
+              height: "100px",
+              textAlign: "center",
+              position: "relative",
+            }}
+          >
+            <Tooltip {...props} display="inline" text="Tooltip label">
+              <Icon name="info" alt="Info" isFilled />
+            </Tooltip>
+          </div>
+        </div>
+        <div
+          style={{
+            width: "500px",
+            marginLeft: "200px",
+            marginBottom: "500px",
+          }}
+        >
+          <div
+            style={{
+              width: "300px",
+              height: "200px",
+              textAlign: "center",
+              position: "relative",
+            }}
+          >
+            <Text tag="div" variant="body">
+              Lorem ipsum dolor sit amet consectetur adipisicing elit. Ratione
+              nulla quas corporis? Perspiciatis, ratione voluptas{" "}
+              <Tooltip {...props} display="inline-block" text="Tooltip label">
+                <Tag>ad veniam sapiente</Tag>
+              </Tooltip>{" "}
+              Maxime harum, ducimus maiores itaque pariatur quod vel porro
+              mollitia. Lorem ipsum dolor sit{" "}
+              <Tooltip {...props} display="inline" text="Open in new tab">
+                {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
+                <a href="#">
+                  amet consectetur adipisicing elit Itaque obcaecati maxime
+                  molestiae blanditiis pariatur
+                </a>
+              </Tooltip>
+              . Magni perspiciatis assumenda in adipisci, eaque commodi quidem
+              dolore, tempore provident animi{" "}
+            </Text>
+          </div>
+        </div>
+      </div>
+    </>
+  ),
+}
+
+export const ButtonsWithTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: args => (
+    <>
+      <Tooltip {...args} text="Contact customer support.">
+        <Button
+          label="Help"
+          icon={<Icon name="help" isPresentational isFilled />}
+        />
+      </Tooltip>
+      <Tooltip {...args} text="Remove the link from current selection.">
+        <IconButton
+          label="Remove link"
+          icon={<Icon name="link_off" isPresentational />}
+        />
+      </Tooltip>
+    </>
+  ),
+}
+
+export const ButtonGroupWithTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: args => (
+    <>
+      <ButtonGroup>
+        <Tooltip {...args} text="Sort by first">
+          <FilterButtonBase>First</FilterButtonBase>
+        </Tooltip>
+        <Tooltip {...args} text="Sort by last">
+          <FilterButtonBase>Last</FilterButtonBase>
+        </Tooltip>
+      </ButtonGroup>
+    </>
+  ),
+}
+
+export const TableHeadersWithTooltips: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <>
+      <TableContainer>
+        <TableHeader>
+          <TableRow>
+            <TableHeaderRowCell
+              labelText="Resources"
+              sorting="descending"
+              width={3 / 12}
+              onClick={(): void => undefined}
+              tooltipInfo="Sort Resources by descending"
+            />
+            <TableHeaderRowCell
+              labelText="Supplementary"
+              width={3 / 12}
+              onClick={(): void => undefined}
+              sorting="ascending"
+              tooltipInfo="Sort Supplementary by ascending"
+            />
+            <TableHeaderRowCell labelText="Date" width={3 / 12} />
+            <TableHeaderRowCell labelText="Price" width={3 / 12} />
+          </TableRow>
+        </TableHeader>
+      </TableContainer>
+    </>
+  ),
+}
+
+export const TagWithHoverOnlyTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <Tooltip text="John Jonson Johnington the Third">
+      <Tag>John Jonson Jo...</Tag>
+    </Tooltip>
+  ),
+}
+
+export const TagWithTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <Tag>
+      <Tooltip text="Visit John Jonson's profile">
+        <a className="text-inherit font no-underline" href="#John">
+          John Jonson
+        </a>
+      </Tooltip>
+    </Tag>
+  ),
+}
+
+export const TagWithCheckboxField: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <>
+      <Tooltip text="Select all users">
+        <CheckboxField labelText="Users" id="sb-checkbox-tooltip--id" />
+      </Tooltip>
+    </>
+  ),
+}
+
+export const CheckboxFieldTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <>
+      <Tooltip text="Select all users">
+        <CheckboxField labelText="Users" id="sb-checkbox-tooltip--id" />
+      </Tooltip>
+    </>
+  ),
+}
+
+export const CheckboxFieldWithDescriptionTooltip: Story = {
+  parameters: {
+    docs: {
+      source: { type: "dynamic" },
+    },
+  },
+  render: () => (
+    <>
+      <Tooltip text="Select all users">
+        <CheckboxField
+          labelText="Users"
+          id="sb-checkbox-tooltip--id"
+          aria-describedby="sb-checkbox-description--id"
+        />
+        <span id="sb-checkbox-description--id" className="sr-only">
+          Select all users
+        </span>
+      </Tooltip>
+    </>
+  ),
+}

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/__overlays__/Tooltip/v1/subcomponents/AppearanceAnim.tsx

@@ -0,0 +1,85 @@
+import React, { useState } from "react"
+import { useDebouncedCallback } from "use-debounce"
+
+type AnimationProps = {
+  isAnimIn?: boolean
+  isAnimOut?: boolean
+  prevIsOpen?: boolean
+  animationDuration?: number
+  isVisible: boolean
+}
+
+const ANIM_DURATION_MS = 400
+
+export const AnimationContext = React.createContext<AnimationProps>({
+  isVisible: false,
+  isAnimIn: false,
+  isAnimOut: false,
+})
+
+/**
+ * Simply applies a css animation to transition a component in and out.
+ * When the component is no longer needed, it will no longer be rendered to the
+ * dom.
+ */
+export const AnimationProvider = ({
+  isVisible,
+  animationDuration = ANIM_DURATION_MS,
+  ...otherProps
+}: AnimationProps & { children?: React.ReactNode }): JSX.Element => {
+  const [isAnimIn, setIsAnimIn] = useState(false)
+  const [isAnimOut, setIsAnimOut] = useState(false)
+  const [prevIsOpen, setPrevIsOpen] = useState(false)
+
+  // Keeps the modal visible while the css animation is completing
+  const trackAnimOutCompleted = useDebouncedCallback(
+    () => {
+      setIsAnimOut(false)
+    },
+    animationDuration,
+    { leading: false }
+  )
+
+  // Allows us to flash the component in an "invisible" state, for one frame.
+  // Then set it to "visible". This allows us to make sure the css transition
+  // actually works.
+  const trackAnimInCompleted = useDebouncedCallback(
+    () => {
+      setIsAnimIn(false)
+    },
+    0,
+    { leading: false }
+  )
+
+  if (isVisible !== prevIsOpen) {
+    setPrevIsOpen(isVisible)
+    if (!isVisible) {
+      trackAnimInCompleted.cancel()
+      setIsAnimOut(true)
+      trackAnimOutCompleted()
+    } else {
+      trackAnimOutCompleted.cancel()
+      setIsAnimIn(true)
+      trackAnimInCompleted()
+    }
+  }
+
+  return (
+    <AnimationContext.Provider
+      value={{
+        isVisible,
+        isAnimOut,
+        isAnimIn,
+      }}
+      {...otherProps}
+    />
+  )
+}
+
+export const useAnimation = (): AnimationProps => {
+  const context = React.useContext(AnimationContext)
+  if (!context) {
+    throw new Error("useAnimation must be used within a AnimationProvider")
+  }
+  return context
+}

package/src/__overlays__/Tooltip/v1/utils/isSemanticElement.spec.tsx

@@ -0,0 +1,55 @@
+import React from "react"
+import { vi } from "vitest"
+import { Button, IconButton } from "~components/__actions__/v2"
+import { Icon } from "~components/__future__"
+import { isSemanticElement } from "./isSemanticElement"
+
+describe("isSemanticElement", () => {
+  it("returns true if provided a native element with a semantic role", () => {
+    expect(
+      isSemanticElement(
+        <button onClick={vi.fn()} type="button">
+          click
+        </button>
+      )
+    ).toBe(true)
+    expect(isSemanticElement(<a href="/">link</a>)).toBe(true)
+  })
+
+  it("returns false if provided a non-semantic element", () => {
+    expect(isSemanticElement(<span>click</span>)).toBe(false)
+    expect(isSemanticElement(<div>link</div>)).toBe(false)
+  })
+
+  it("returns true if provided one of the Kaizen components from the allowed list", () => {
+    expect(isSemanticElement(<Button label="Click" />)).toBe(true)
+    expect(isSemanticElement(<IconButton label="click" />)).toBe(true)
+  })
+
+  it("will return true if provided a non-semantic element with a semantic role", () => {
+    expect(
+      isSemanticElement(
+        <span tabIndex={0} role="button" onKeyDown={vi.fn()} onClick={vi.fn()}>
+          custom semantic el
+        </span>
+      )
+    ).toBe(true)
+    expect(
+      isSemanticElement(
+        <div tabIndex={0} role="button" onKeyDown={vi.fn()} onClick={vi.fn()}>
+          custom semantic el
+        </div>
+      )
+    ).toBe(true)
+    expect(
+      isSemanticElement(
+        <div role="textbox" contentEditable="true" aria-multiline="true" />
+      )
+    ).toBe(true)
+  })
+
+  it("returns false if provided an element using a role 'presentation' or 'none'", () => {
+    expect(isSemanticElement(<Icon name="add" isPresentational />)).toBe(false)
+    expect(isSemanticElement(<span role="none">Hello</span>)).toBe(false)
+  })
+})

package/src/__overlays__/Tooltip/v1/utils/isSemanticElement.tsx

@@ -0,0 +1,35 @@
+import React, { ReactNode } from "react"
+
+// Noting that this is contingent on our displayName for our components -  this something we control
+const allowedDisplayNames = ["Button", "IconButton", "FilterButtonBase"]
+
+export function extractDisplayName(type: React.FunctionComponent): string {
+  return type.displayName || type.name || "Unknown"
+}
+
+/**
+ *  Validates implicit or explicitly semantic roles required to make `aria-describedby` announce predictably with screen readers
+ */
+export const isSemanticElement = (
+  element: ReactNode
+): element is React.ReactElement => {
+  if (!React.isValidElement(element)) return false
+
+  const { props, type } = element
+
+  if ("role" in props) {
+    return props.role !== "presentation" && props.role !== "none"
+  }
+
+  if (typeof type !== "string") {
+    // As we are only checking whether this matches to our allowedDisplayNames
+    // type casting should be fine
+    const displayName = extractDisplayName(
+      type as unknown as React.FunctionComponent
+    )
+
+    return allowedDisplayNames.includes(displayName)
+  }
+
+  return !(type === "div" || type === "span")
+}

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

@@ -0,0 +1,131 @@
+import { Canvas, Controls, Meta } from "@storybook/blocks"
+import { ResourceLinks, KAIOInstallation } from "~storybook/components"
+import * as TooltipStories from "./Tooltip.stories"
+
+<Meta of={TooltipStories} />
+
+# 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"
+/>
+
+<KAIOInstallation exportNames="Tooltip" family="overlays" version="2" />
+
+## 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/__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"