Tooltip: Tooltip V2 as an experimental/draft with the new popover API

.changeset/blue-melons-arrive.md

@@ -0,0 +1,7 @@
+---
+'@primer/react': minor
+---
+
+Tooltip: Release Tooltip v2 as a draft/experimental
+
+<!-- Changed components: _none_ -->

docs/content/drafts/Tooltip.mdx

@@ -0,0 +1,76 @@
+---
+componentId: tooltip
+title: Tooltip
+status: Alpha
+---
+
+import data from '../../../src/drafts/Tooltip/Tooltip.docs.json'
+
+The Tooltip component is used to add context to interactive elements on the page.
+
+**_⚠️ Usage warning! ⚠️_**
+
+Tooltips as a UI pattern should be our last resort for conveying information because it is hidden by default and often with zero or little visual indicator of its existence.
+
+Before adding a tooltip, please consider: Is this information essential and necessary? Can the UI be made clearer? Can the information be shown on the page by default? See [Tooltip alternatives](https://primer.style/design/accessibility/tooltip-alternatives) for more accessible alternatives.
+
+Tooltip should only be used on an element that is interactive such as a button or a link.
+
+## Examples
+
+### Default (For additional context)
+
+Default tooltip is suitable for interactive controls that require additional context.
+
+```jsx live
+<Tooltip text="This change cannot be undone.">
+ <Button>Delete</Button>
+</Tooltip>
+```
+
+### As a label
+
+Tooltip can be used to label interactive controls that has no visible text label such as interactive icon links.
+
+```jsx live
+<Tooltip text="Contribution Documentation for 'Primer React'" type="label">
+ <Link href="https://github.com/primer/react/contributor-docs/CONTRIBUTING.md" sx={{ml: 1, color: 'fg.muted'}}>
+ <StyledOcticon icon={BookIcon} sx={{color: 'fg.muted'}} />
+ </Link>
+</Tooltip>
+```
+
+### With direction
+
+```jsx live
+<Box sx={{padding: 5, display: 'flex', gap: '8px'}}>
+ <Tooltip direction="n" text="Supplementary text">
+ <Button>North</Button>
+ </Tooltip>
+ <Tooltip direction="s" text="Supplementary text">
+ <Button>South</Button>
+ </Tooltip>
+ <Tooltip direction="e" text="Supplementary text">
+ <Button>East</Button>
+ </Tooltip>
+ <Tooltip direction="w" text="Supplementary text">
+ <Button>West</Button>
+ </Tooltip>
+ <Tooltip direction="ne" text="Supplementary text">
+ <Button>North East</Button>
+ </Tooltip>
+ <Tooltip direction="nw" text="Supplementary text">
+ <Button>North West</Button>
+ </Tooltip>
+ <Tooltip direction="se" text="Supplementary text">
+ <Button>Southeast</Button>
+ </Tooltip>
+ <Tooltip direction="sw" text="Supplementary text">
+ <Button>Southwest</Button>
+ </Tooltip>
+</Box>
+```
+
+## Props
+
+<ComponentProps data={data} />

e2e/components/Tooltip--experimental.test.ts

@@ -0,0 +1,175 @@
+import {test, expect} from '@playwright/test'
+import {visit} from '../test-helpers/storybook'
+import {themes} from '../test-helpers/themes'
+
+test.describe('Tooltip--experimental', () => {
+ test.describe('Default', () => {
+ for (const theme of themes) {
+ test.describe(theme, () => {
+ test('default @vrt', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip--default',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+
+ // Default state
+ await page.keyboard.press('Tab')
+ expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+ `Tooltip--experimental.Default.${theme}.png`,
+ {
+ threshold: 0.1,
+ },
+ )
+ })
+
+ test('axe @aat', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip--default',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+ await expect(page).toHaveNoViolations()
+ })
+ })
+ }
+ })
+
+ test.describe('Anchor Has Margin', () => {
+ for (const theme of themes) {
+ test.describe(theme, () => {
+ test('default @vrt', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip-features--anchor-has-margin',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+
+ // Default state
+ await page.keyboard.press('Tab')
+ expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+ `Tooltip--experimental.Anchor Has Margin.${theme}.png`,
+ {
+ threshold: 0.1,
+ },
+ )
+ })
+
+ test('axe @aat', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip-features--anchor-has-margin',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+ await expect(page).toHaveNoViolations()
+ })
+ })
+ }
+ })
+
+ test.describe('Calculated Direction', () => {
+ for (const theme of themes) {
+ test.describe(theme, () => {
+ test('default @vrt', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip-features--calculated-direction',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+
+ // Default state
+ await page.keyboard.press('Tab')
+ expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+ `Tooltip--experimental.Calculated Direction.${theme}.png`,
+ {
+ threshold: 0.1,
+ },
+ )
+ })
+
+ test('axe @aat', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip-features--calculated-direction',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+ await expect(page).toHaveNoViolations()
+ })
+ })
+ }
+ })
+
+ test.describe('Icon Button With Description', () => {
+ for (const theme of themes) {
+ test.describe(theme, () => {
+ test('default @vrt', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip-features--icon-button-with-description',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+
+ // Default state
+ await page.keyboard.press('Tab')
+ expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+ `Tooltip--experimental.Icon Button With Description.${theme}.png`,
+ {
+ threshold: 0.1,
+ },
+ )
+ })
+
+ test('axe @aat', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip-features--icon-button-with-description',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+ await expect(page).toHaveNoViolations()
+ })
+ })
+ }
+ })
+
+ test.describe('Label Type', () => {
+ for (const theme of themes) {
+ test.describe(theme, () => {
+ test('default @vrt', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip-features--label-type',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+
+ // Default state
+ await page.keyboard.press('Tab')
+ expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+ `Tooltip--experimental.Label Type.${theme}.png`,
+ {
+ threshold: 0.1,
+ },
+ )
+ })
+
+ test('axe @aat', async ({page}) => {
+ await visit(page, {
+ id: 'drafts-components-tooltip-features--label-type',
+ globals: {
+ colorScheme: theme,
+ },
+ })
+ await expect(page).toHaveNoViolations()
+ })
+ })
+ }
+ })
+})

jest.config.js

@@ -2,6 +2,7 @@
 
 'use strict'
 
+const path = require('node:path')
 const {REACT_VERSION_17} = process.env
 
 /**
@@ -17,12 +18,21 @@ module.exports = {
  collectCoverageFrom: ['src/**/*.{js,jsx,ts,tsx}', '!src/stories/**', '!**/*.stories.{js,jsx,ts,tsx}'],
  moduleNameMapper: {
  '\\.css$': 'jest-css-modules',
+ // We need to specify this package subpath because it does not provide a `require` conditional export path
+ '@oddbird/popover-polyfill/fn': path.join(
+ __dirname,
+ 'node_modules',
+ '@oddbird',
+ 'popover-polyfill',
+ 'dist',
+ 'popover-fn.js',
+ ),
  },
  setupFiles: ['<rootDir>/src/utils/test-helpers.tsx'],
  setupFilesAfterEnv: ['<rootDir>/src/utils/test-matchers.tsx', '<rootDir>/src/utils/test-deprecations.tsx'],
  testMatch: ['<rootDir>/(src|codemods)/**/*.test.[jt]s?(x)', '!**/*.types.test.[jt]s?(x)'],
  transformIgnorePatterns: [
- 'node_modules/(?!@github/combobox-nav|@koddsson/textarea-caret|@github/[a-z-]+-element|@lit-labs/react)',
+ 'node_modules/(?!@github/combobox-nav|@koddsson/textarea-caret|@github/[a-z-]+-element|@lit-labs/react|@oddbird/popover-polyfill)',
  ],
  watchPlugins: ['jest-watch-typeahead/filename', 'jest-watch-typeahead/testname'],
 }

package.json

@@ -99,6 +99,7 @@
  "@github/paste-markdown": "^1.4.0",
  "@github/relative-time-element": "^4.1.2",
  "@lit-labs/react": "^1.1.1",
+ "@oddbird/popover-polyfill": "0.2.2",
  "@primer/behaviors": "^1.3.4",
  "@primer/octicons-react": "^19.7.0",
  "@primer/primitives": "^7.11.11",

rollup.config.js

@@ -63,6 +63,7 @@ const ESM_ONLY = new Set([
  '@github/paste-markdown',
  '@github/relative-time-element',
  '@lit-labs/react',
+ '@oddbird/popover-polyfill',
 ])
 const dependencies = [
  ...Object.keys(packageJson.peerDependencies ?? {}),

script/generate-e2e-tests.js

@@ -1404,6 +1404,45 @@ const components = new Map([
  ],
  },
  ],
+ [
+ 'Tooltip--experimental',
+ {
+ stories: [
+ {
+ id: 'drafts-components-tooltip--default',
+ name: 'Default',
+ },
+ {
+ id: 'drafts-components-tooltip-features--anchor-has-margin',
+ name: 'Anchor Has Margin',
+ },
+ {
+ id: 'drafts-components-tooltip-features--calculated-direction',
+ name: 'Calculated Direction',
+ },
+ {
+ id: 'drafts-components-tooltip-features--icon-button-with-description',
+ name: 'Icon Button With Description',
+ },
+ {
+ id: 'drafts-components-tooltip-features--label-type',
+ name: 'Label Type',
+ },
+ {
+ id: 'drafts-components-tooltip-features--multiline-text',
+ name: 'Multiline Text',
+ },
+ {
+ id: 'drafts-components-tooltip-features--on-action-menu-anchor',
+ name: 'On Action Menu Anchor',
+ },
+ {
+ id: 'drafts-components-tooltip-examples--files-page',
+ name: 'Files Page Example',
+ },
+ ],
+ },
+ ],
  [
  'TreeView',
  {