docs(Tooltip): update and improve documentation

chanzuckerberg · Nov 8, 2023 · 5f1ecfb · 5f1ecfb
1 parent 5aeef5d
commit 5f1ecfb
Show file tree

Hide file tree

Showing 3 changed files with 90 additions and 211 deletions.
diff --git a/src/components/Tooltip/Tooltip.stories.tsx b/src/components/Tooltip/Tooltip.stories.tsx
@@ -15,7 +15,7 @@ const defaultArgs = {
     </span>
   ),
   children: <div className="fpo w-3 p-1">&bull;</div>,
-  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,38 +63,41 @@ export default {
       diffIncludeAntiAliasing: false,
     },
   },
-  decorators: [(Story) => <div className="p-16">{Story()}</div>],
+  decorators: [(Story) => <div className="p-8">{Story()}</div>],
 } as Meta<Args>;
 
 type Args = React.ComponentProps<typeof Tooltip>;
+type Story = StoryObj<Args>;
 
-export const LightVariant: StoryObj<Args> = {};
-
-export const LeftPlacement: StoryObj<Args> = {
+/**
+ * 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: <div className="fpo w-3 p-1">&bull;</div>,
   },
   parameters: {
     chromatic: { disableSnapshot: true },
   },
 };
 
-export const TopPlacement: StoryObj<Args> = {
+export const TopPlacement: Story = {
   args: {
-    align: 'top',
+    placement: 'top',
     children: <div className="fpo w-3 p-1">&bull;</div>,
   },
 };
 
-export const BottomPlacement: StoryObj<Args> = {
+export const BottomPlacement: Story = {
   args: {
-    align: 'bottom',
+    placement: 'bottom',
     children: <div className="fpo w-3 p-1">&bull;</div>,
   },
 };
 
-export const LongText: StoryObj<Args> = {
+export const LongText: Story = {
   args: {
     text: (
       <span>
@@ -93,57 +113,39 @@ export const LongText: StoryObj<Args> = {
   },
 };
 
-export const LongTriggerText: StoryObj<Args> = {
+export const LongTriggerText: Story = {
   args: {
     children: <div className="fpo p-1">Longer text to test placement</div>,
   },
 };
 
-export const TextChild: StoryObj<Args> = {
-  render: () => (
-    <Tooltip align="top" childNotInteractive text={defaultArgs.text} visible>
-      <span>Tooltip trigger</span>
-    </Tooltip>
-  ),
-};
-
-export const Interactive: StoryObj<Args> = {
+/**
+ * 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: <button className="fpo w-3 p-1">&bull;</button>,
   },
-  decorators: [
-    (Story) => (
-      <div>
-        <p>Hover over the button to make the tooltip appear.</p>
-        {Story()}
-      </div>
-    ),
-  ],
 };
 
-export const InteractiveDisabled: StoryObj<Args> = {
+/**
+ * Hover over the button to make the tooltip appear.
+ */
+export const InteractiveDisabled: Story = {
   args: {
     duration: undefined,
   },
   render: (args) => (
     <Tooltip
-      align="top"
       childNotInteractive
       duration={args.duration}
+      placement="top"
       text={defaultArgs.text}
     >
       <div className="fpo p-1">&bull;</div>
     </Tooltip>
   ),
-  decorators: [
-    (Story) => (
-      <div>
-        <p>Hover over the button to make the tooltip appear.</p>
-        {Story()}
-      </div>
-    ),
-  ],
 };
diff --git 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}