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',
     {