Tooltip: anchoredPosition + IconButton (#2006)

* Add breaking story * Add memex story * use behaviors deploy preview * add tooltip triangle * update snapshot * add label tooltips for story * update @primer/behaviors to latest * lint: remove unused import * Refactor Tooltip * Use Tooltip in IconButton * Add triangle styles for all directions * Add docs * Added delay * change ReactElement to ReactNode * keep ReactElement * Add tests! * compatible types :) * Fix docs * update snapshots * update behaviors to next minor * update snapshots * Fix IconButton duplicate label * missed a spot! * Fix Button story with tooltip * Apply suggestions from code review Co-authored-by: Cole Bemis <colebemis@github.com> * fix alignment with span Co-authored-by: Cole Bemis <colebemis@github.com>
primer · May 10, 2022 · d43a825 · d43a825
1 parent 0f9edca
commit d43a825
Show file tree

Hide file tree

Showing 25 changed files with 36,515 additions and 1,084 deletions.
diff --git a/docs/content/IconButton.mdx b/docs/content/IconButton.mdx
@@ -35,6 +35,16 @@ A separate component called `IconButton` is used if the action shows only an ico
 </>
 ```
 
+### Customize description / tooltip text
+
+To add description for the button, wrap `IconButton` in a `Tooltip`. Make sure you pass `aria-label` to the button as well.
+
+```jsx live
+<Tooltip text="You have no unread notifications">
+  <IconButton icon={BellIcon} aria-label="Notifications" />
+</Tooltip>
+```
+
 ## API reference
 
 Native `<button>` HTML attributes are forwarded to the underlying React `button` component and are not listed below.

diff --git a/docs/content/Tooltip.md b/docs/content/Tooltip.md
diff --git a/docs/content/Tooltip.mdx b/docs/content/Tooltip.mdx
@@ -0,0 +1,194 @@
+---
+componentId: tooltip
+title: Tooltip
+status: Alpha
+source: https://github.com/primer/react/tree/main/src/Tooltip
+storybook: '/react/storybook?path=/story/composite-components-tooltip'
+description: Use tooltips to add context to elements on the page.
+---
+
+Tooltip only appears on mouse hover or keyboard focus and contain a label or description text. Use tooltips sparingly and as a last resort. [Consider these alternatives](https://primer.style/design/accessibility/tooltip-alternatives).
+
+import {Tooltip, IconButton, Button} from '@primer/react'
+import {BellIcon, MentionIcon} from '@primer/octicons-react'
+import InlineCode from '@primer/gatsby-theme-doctocat/src/components/inline-code'
+
+<Box
+  sx={{
+    display: 'flex',
+    justifyContent: 'center',
+    border: '1px solid',
+    borderColor: 'border.default',
+    borderRadius: 2,
+    padding: 6,
+    paddingTop: 8,
+    marginBottom: 3
+  }}
+>
+  <Tooltip text="You have no unread notifications" sx={{visibility: 'visible', opacity: 1}}>
+    <IconButton icon={BellIcon} aria-label="Notifications" />
+  </Tooltip>
+</Box>
+
+When using a tooltip, follow the provided guidelines to avoid accessibility issues:
+
+- Tooltip text should be brief and to the point.
+- Tooltips should contain only **non-essential text**. Tooltips can easily be missed and are not accessible on touch devices so never use tooltips to convey critical information.
+
+## Examples
+
+### As a description for icon-only button
+
+If the tooltip content provides supplementary description, wrap the target in a `Tooltip`. The trigger element should also have a concise accessible label via `aria-label`.
+
+```jsx live
+<Tooltip text="Directly mention a team or user">
+  <IconButton aria-label="Mentions" icon={MentionIcon} variant="invisible" />
+</Tooltip>
+```
+
+### As a description for a button with visible label
+
+```jsx live
+<Tooltip text="This will immediately impact all organization members">
+  <Button variant="primary">Save</Button>
+</Tooltip>
+```
+
+### With direction
+
+Set direction of tooltip with `direction`. The tooltip is responsive and will automatically adjust direction to avoid cutting off.
+
+```jsx live
+<Box
+  sx={{
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 8,
+    marginY: 4,
+    '[data-component=tooltip]': {visibility: 'visible', opacity: 1}
+  }}
+>
+  <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}>
+    <Tooltip direction="nw" text="Tooltip text">
+      <Button>North west</Button>
+    </Tooltip>
+    <Tooltip direction="n" text="Tooltip text">
+      <Button>North</Button>
+    </Tooltip>
+    <Tooltip direction="ne" text="Tooltip text">
+      <Button>North east</Button>
+    </Tooltip>
+  </Box>
+  <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}>
+    <Tooltip direction="e" text="Tooltip text">
+      <Button>East</Button>
+    </Tooltip>
+    <Tooltip direction="w" text="Tooltip text">
+      <Button>West</Button>
+    </Tooltip>
+  </Box>
+  <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}>
+    <Tooltip direction="sw" text="Tooltip text">
+      <Button>South west</Button>
+    </Tooltip>
+    <Tooltip direction="s" text="Tooltip text">
+      <Button>South</Button>
+    </Tooltip>
+    <Tooltip direction="se" text="Tooltip text">
+      <Button>South east</Button>
+    </Tooltip>
+  </Box>
+</Box>
+```
+
+## Props
+
+### Tooltip
+
+<PropsTable>
+  <PropsTableRow name="children" required type="React.ReactNode" description="Tooltip target, single element" />
+
+  <PropsTableRow
+    name="text"
+    type="string"
+    description="The text content of the tooltip. This should be brief and no longer than a sentence"
+  />
+  <PropsTableRow
+    deprecated
+    name="aria-label"
+    type="string"
+    description={
+      <>
+        Use <InlineCode>text</InlineCode> instead
+      </>
+    }
+  />
+  <PropsTableRow
+    name="type"
+    type="'description' | 'label'"
+    defaultValue="'description'"
+    description={
+      <>
+        Use <InlineCode>aria-describedby</InlineCode> or <InlineCode>aria-labelledby</InlineCode>
+      </>
+    }
+  />
+  <PropsTableRow
+    name="direction"
+    type="'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w'"
+    defaultValue="'n'"
+    description="Sets where the tooltip renders in relation to the target"
+  />
+  <PropsTableRow name="align" deprecated type="'left' | 'right'" description="Use direction instead. Alignment relative to target" />
+  <PropsTableRow
+    name="noDelay"
+    type="boolean"
+    defaultValue="false"
+    description={
+      <>
+        When set to <InlineCode>true</InlineCode>, tooltip appears without any delay
+      </>
+    }
+  />
+  <PropsTableRow
+    name="wrap"
+    type="boolean"
+    deprecated
+    description={
+      <>
+        Use to allow text within tooltip to wrap. Deprecated: always set to <InlineCode>true</InlineCode> now.
+      </>
+    }
+  />
+  <PropsTableSxRow />
+</PropsTable>
+
+## Status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: true,
+    usageExamplesDocumented: true,
+    hasStorybookStories: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: true,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: true
+  }}
+/>
+
+## Further reading
+
+- [Tooltip alternatives](https://primer.style/design/accessibility/tooltip-alternatives)
+
+## Related components
+
+- [IconButton](/IconButton)