From 5f1ecfb9eddffd5f080d5273b1b993796407e935 Mon Sep 17 00:00:00 2001 From: Andrew Holloway Date: Tue, 7 Nov 2023 18:19:17 -0600 Subject: [PATCH] docs(Tooltip): update and improve documentation --- src/components/Tooltip/Tooltip.stories.tsx | 80 +++---- src/components/Tooltip/Tooltip.tsx | 24 ++- .../__snapshots__/Tooltip.test.tsx.snap | 197 +++--------------- 3 files changed, 90 insertions(+), 211 deletions(-) diff --git a/src/components/Tooltip/Tooltip.stories.tsx b/src/components/Tooltip/Tooltip.stories.tsx index a178debc1..ede500c89 100644 --- a/src/components/Tooltip/Tooltip.stories.tsx +++ b/src/components/Tooltip/Tooltip.stories.tsx @@ -15,7 +15,7 @@ const defaultArgs = { ), children:
•
, - align: 'right', + placement: 'right', // most stories show a visible, non-interactive tooltip. // this turns animation off to ensure stable visual snapshots duration: 0, @@ -27,6 +27,12 @@ export default { component: Tooltip, args: defaultArgs, argTypes: { + align: { + table: { + // Marking deprecated props / controls as disabled + disable: true, + }, + }, text: { control: { type: 'text', @@ -37,6 +43,17 @@ export default { type: null, }, }, + placement: { + table: { + defaultValue: { summary: 'top' }, + }, + }, + variant: { + table: { + // Marking deprecated props / controls as disabled + disable: true, + }, + }, }, parameters: { layout: 'centered', @@ -46,16 +63,19 @@ export default { diffIncludeAntiAliasing: false, }, }, - decorators: [(Story) =>
{Story()}
], + decorators: [(Story) =>
{Story()}
], } as Meta; type Args = React.ComponentProps; +type Story = StoryObj; -export const LightVariant: StoryObj = {}; - -export const LeftPlacement: StoryObj = { +/** + * The following stories demonstrate how `Tooltip` can be made to appear on different sides of the trigger. + * Each story name denotes a value pased to `placement`. + */ +export const LeftPlacement: Story = { args: { - align: 'left', + placement: 'left', children:
•
, }, parameters: { @@ -63,21 +83,21 @@ export const LeftPlacement: StoryObj = { }, }; -export const TopPlacement: StoryObj = { +export const TopPlacement: Story = { args: { - align: 'top', + placement: 'top', children:
•
, }, }; -export const BottomPlacement: StoryObj = { +export const BottomPlacement: Story = { args: { - align: 'bottom', + placement: 'bottom', children:
•
, }, }; -export const LongText: StoryObj = { +export const LongText: Story = { args: { text: ( @@ -93,57 +113,39 @@ export const LongText: StoryObj = { }, }; -export const LongTriggerText: StoryObj = { +export const LongTriggerText: Story = { args: { children:
Longer text to test placement
, }, }; -export const TextChild: StoryObj = { - render: () => ( - - Tooltip trigger - - ), -}; - -export const Interactive: StoryObj = { +/** + * Hover over the button to make the tooltip appear. + */ +export const Interactive: Story = { args: { // reset prop values defined in defaultArgs duration: undefined, visible: undefined, children: , }, - decorators: [ - (Story) => ( -
-

Hover over the button to make the tooltip appear.

- {Story()} -
- ), - ], }; -export const InteractiveDisabled: StoryObj = { +/** + * Hover over the button to make the tooltip appear. + */ +export const InteractiveDisabled: Story = { args: { duration: undefined, }, render: (args) => (
•
 ), - decorators: [ - (Story) => ( -
-

Hover over the button to make the tooltip appear.

- {Story()} -
- ), - ], }; diff --git a/src/components/Tooltip/Tooltip.tsx b/src/components/Tooltip/Tooltip.tsx index b47707cb1..6105eb78a 100644 --- a/src/components/Tooltip/Tooltip.tsx +++ b/src/components/Tooltip/Tooltip.tsx @@ -12,6 +12,10 @@ type TooltipProps = { * * Tippy also supports 'top-start', 'top-end', 'right-start', 'right-end', etc, * but our CSS currently only supports the 4 main sides. + * + * This is deprecated. Please use `placement` instead. + * + * @deprecated */ align?: 'top' | 'right' | 'bottom' | 'left'; /** @@ -57,6 +61,12 @@ type TooltipProps = { * Duration of Tooltip animation, in milliseconds. Default is 200. */ duration?: number; + /** + * Where the tooltip should be placed in relation to the element it's attached to. + * + * **Default is `'top'`.** + */ + placement?: 'top' | 'right' | 'bottom' | 'left'; /** * The trigger element the tooltip appears next to. * @@ -71,11 +81,9 @@ type TooltipProps = { text?: React.ReactNode; /** * Whether the tooltip has a light or dark background. + * @deprecated */ - variant?: - | 'light' - /** @deprecated */ - | 'dark'; + variant?: 'light' | 'dark'; /** * Whether the tooltip is always visible or always invisible. * @@ -93,7 +101,7 @@ type Plugin = Plugins[number]; /** * `import {Tooltip} from "@chanzuckerberg/eds";` * - * A styled tooltip built on Tippy.js. + * A floating information box, attached to other components on the page. Used to display option, additional information. * * https://atomiks.github.io/tippyjs/ * https://github.com/atomiks/tippyjs-react @@ -105,6 +113,7 @@ export const Tooltip = ({ childNotInteractive, className, duration = 200, + placement, text, ...rest }: TooltipProps) => { @@ -114,6 +123,9 @@ export const Tooltip = ({ ); } + // TODO: when removing `align`, remove this line and set `placement={placement}` below + const intendedPlacement = placement ?? align; + // Hides tooltip when escape key is pressed, following: // https://atomiks.github.io/tippyjs/v6/plugins/#hideonesc const hideOnEsc: Plugin = { @@ -168,7 +180,7 @@ export const Tooltip = ({ )} content={textContent} duration={duration} - placement={align} + placement={intendedPlacement} plugins={[hideOnEsc]} > {children} diff --git a/src/components/Tooltip/__snapshots__/Tooltip.test.tsx.snap b/src/components/Tooltip/__snapshots__/Tooltip.test.tsx.snap index c1db33ed1..747d800ab 100644 --- a/src/components/Tooltip/__snapshots__/Tooltip.test.tsx.snap +++ b/src/components/Tooltip/__snapshots__/Tooltip.test.tsx.snap @@ -4,10 +4,10 @@ exports[` BottomPlacement story renders snapshot 1`] = `
• @@ -16,7 +16,7 @@ exports[` BottomPlacement story renders snapshot 1`] = `
Interactive story renders snapshot 1`] = `
-
-

- Hover over the button to make the tooltip appear. -

- -
+
@@ -86,94 +81,28 @@ exports[` InteractiveDisabled story renders snapshot 1`] = `
-
-

- Hover over the button to make the tooltip appear. -

- -
- • -
- -
-
-
- -`; - -exports[` LeftPlacement story renders snapshot 1`] = ` - -
-
-
- • -
-
-
-
-