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,84 @@
+---
+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>
+```
+
+### With no delay
+
+```jsx live
+<Tooltip noDelay text="Supplemetary text">
+  <Button>Button</Button>
+</Tooltip>
+```
+
+## Props
+
+<ComponentProps data={data} />

docs/gatsby-config.js

@@ -25,6 +25,7 @@ module.exports = {
           '@primer/components': path.resolve(__dirname, '../src'),
           '@primer/react': path.resolve(__dirname, '../src'),
           '@primer/react/drafts': path.resolve(__dirname, '../src/drafts'),
+          '@primer/react/experimental': path.resolve(__dirname, '../src/experimental'),
           'styled-components': path.resolve(__dirname, '..', 'node_modules', 'styled-components'),
           react: path.resolve(__dirname, 'node_modules', 'react'),
         },

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

@@ -0,0 +1,284 @@
+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`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip--default',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await expect(page).toHaveNoViolations()
+        })
+      })
+    }
+  })
+
+  test.describe('All Directions', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip-features--all-directions',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          await page.keyboard.press('Tab')
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+            `Tooltip--experimental.North.${theme}.png`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip-features--all-directions',
+            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`,
+          )
+        })
+
+        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`,
+          )
+        })
+
+        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`,
+          )
+        })
+
+        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`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip-features--label-type',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await expect(page).toHaveNoViolations()
+        })
+      })
+    }
+  })
+
+  test.describe('Multiline Text', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip-features--multiline-text',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          await page.keyboard.press('Tab')
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+            `Tooltip--experimental.Multiline Text.${theme}.png`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip-features--multiline-text',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await expect(page).toHaveNoViolations()
+        })
+      })
+    }
+  })
+
+  test.describe('On Action Menu Anchor', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip-features--on-action-menu-anchor',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          await page.keyboard.press('Tab')
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+            `Tooltip--experimental.On Action Menu Anchor.${theme}.png`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip-features--on-action-menu-anchor',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await expect(page).toHaveNoViolations()
+        })
+      })
+    }
+  })
+
+  test.describe('Files Page Example', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip-examples--files-page',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          await page.keyboard.press('Tab')
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+            `Tooltip--experimental.Files Page Example.${theme}.png`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'drafts-components-tooltip-examples--files-page',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await expect(page).toHaveNoViolations()
+        })
+      })
+    }
+  })
+})