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

…#3394)

* Tooltip remediations as an experimental

* Update generated/components.json

* fix export path

* popover with keith and top layer height experiment to accomodate ::before

* get rid of caret, align styling and update the API

* fix after stuff

* add a calculated direction to properly position ::after relatively to tooltip

* clean up

* add a story for a dotcom usage

* re organise stories and remove caret styles for now

* ewmove unused Box

* css polyfill issues are resolved - huge thanks to Keith

* update tests to reflect default direction s

* ActionMenu.Anchor tooltip - not the cleanest code

* ActionMenu.Anchor and ActionMenu.Button with tooltip

* only type the child

* fix type

* use React.forwardRef and clean up impl for action menu anchor buttons

* move tooltip from experimental to drafts

* export tooltip in draft

* SSR friendly polyfill

* Resolve oddbird-polyfil module resolution issue - huge thanks to Josh

* add e2e stories, clean up

* test(vrt): update snapshots

* add changeset

* test(vrt): update snapshots

* update docs

* to revert later - just adding a test story to sgare

* delete snapshots to regenerate them

* test(vrt): update snapshots

* Remove animations delays and noDelay prop

* reorganise vrt

* test(vrt): update snapshots

* add threshold to snapshots

* delete failed snapshots

* delete failed snapshots

* ActionMenu.Button children undefined at dotcom

* 🔥 snapshots

* reorganise if logic in actionmenu

* test(vrt): update snapshots

* remove always failing or flaky snapshot tests

* reorganise action menu again

* add popover polyfill to the esm only modules in rollup

* add test cases for tooltip on action menu both for v1 and v2

* clean up

* Update docs/gatsby-config.js

---------

Co-authored-by: broccolinisoup <broccolinisoup@users.noreply.github.com>

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