import { Canvas, Controls, Meta } from '@storybook/blocks'
import { KAIOInstallation, ResourceLinks } from '~storybook/components'
import * as docsStories from './Tooltip.docs.stories'
import * as exampleStories from './Tooltip.stories'

<Meta title="Components/Tooltip/API Specification" />

# Tooltip API Specification

Updated June 25, 2024

<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-next-usage-guidelines--docs"
  ariaComponentPage="https://react-spectrum.adobe.com/react-aria/Tooltip.html"
/>

<KAIOInstallation exportNames={['Tooltip', 'TooltipTrigger']} />

## Overview

Tooltips are brief floating labels used to add additional contextual information when users hover, click or focus on an interactive element.

<Canvas
  className="mb-64"
  of={exampleStories.OnButton}
  source={{
    code: `
<TooltipTrigger>
  <Button>Button</Button>
  <Tooltip>Tooltip content</Tooltip>
</TooltipTrigger>
  `,
  }}
/>

### 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.

## API

<Controls of={exampleStories.OnButton} />

### 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`.

<Canvas className="mb-24" of={exampleStories.Placement} />

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/components-tooltip-docs-assets--should-flip&globals=viewport:small).

<Canvas className="mb-64" of={docsStories.ShouldFlip} />

### 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.

<Canvas className="mb-24" of={docsStories.UncontrolledState} />

`isOpen` prop will negate the default state and relinquish control of `Tooltip` open and close to
the user.

### TooltipTrigger

The `TooltipTrigger` wraps both the `Tooltip` and its trigger element, controlling the open and close interactions.

```jsx
<TooltipTrigger>
  /* In this case the trigger element is the Button */
  <Button>Button</Button>
  /* The Tooltip and its content is a child of the trigger */
  <Tooltip>Tooltip content</Tooltip>
</TooltipTrigger>
```

Any compatible interactive element within the `TooltipTrigger` will enable the interaction state.

### Reversed

The `Tooltip` uses the `useReversedColors` hook and `ReversedColors` provider to control the dark and light theme.

<Canvas className="bg-purple-600 mb-24" of={exampleStories.OnReversed} />

To enable the reversed theme, you will need to the component or application in the
`ReversedColors` provider.

```jsx
<ReversedColors isReversed={true}>
  <Component />
</ReversedColors>
```

These utilities can be imported from `@kaizen/components/next`. This is an emerging
pattern so more documentation will come.

## Examples

Here are examples of how to use the `Tooltip` with compatible Kaizen components.

### On Button

<Canvas of={exampleStories.OnButton} />

### On Link

<Canvas of={exampleStories.OnLink} />

### On IconButton

<Canvas of={exampleStories.OnIconButton} />

### On Tabs

<Canvas of={exampleStories.OnTabs} />

### On Tag

<Canvas of={exampleStories.OnCustomFocusableElement} />