From 101d3f4e7ded92e6d2a618ab88923a3aabfd052a Mon Sep 17 00:00:00 2001
From: Dave Rupert <rupertdavid@microsoft.com>
Date: Tue, 17 Sep 2024 10:51:33 -0500
Subject: [PATCH 1/7] feat(web-components): add tooltip component

---
 packages/web-components/docs/api-report.md    |  52 ++++++
 packages/web-components/src/index-rollup.ts   |   1 +
 packages/web-components/src/index.ts          |   1 +
 packages/web-components/src/tooltip/define.ts |   4 +
 packages/web-components/src/tooltip/index.ts  |   5 +
 .../src/tooltip/tooltip.definition.ts         |  17 ++
 .../src/tooltip/tooltip.options.ts            |  26 +++
 .../src/tooltip/tooltip.spec.ts               | 135 ++++++++++++++++
 .../src/tooltip/tooltip.stories.ts            | 151 ++++++++++++++++++
 .../src/tooltip/tooltip.styles.ts             |  94 +++++++++++
 .../src/tooltip/tooltip.template.ts           |  12 ++
 .../web-components/src/tooltip/tooltip.ts     | 116 ++++++++++++++
 12 files changed, 614 insertions(+)
 create mode 100644 packages/web-components/src/tooltip/define.ts
 create mode 100644 packages/web-components/src/tooltip/index.ts
 create mode 100644 packages/web-components/src/tooltip/tooltip.definition.ts
 create mode 100644 packages/web-components/src/tooltip/tooltip.options.ts
 create mode 100644 packages/web-components/src/tooltip/tooltip.spec.ts
 create mode 100644 packages/web-components/src/tooltip/tooltip.stories.ts
 create mode 100644 packages/web-components/src/tooltip/tooltip.styles.ts
 create mode 100644 packages/web-components/src/tooltip/tooltip.template.ts
 create mode 100644 packages/web-components/src/tooltip/tooltip.ts

diff --git a/packages/web-components/docs/api-report.md b/packages/web-components/docs/api-report.md
index 2fcf53a72c60a..8a6743d150377 100644
--- a/packages/web-components/docs/api-report.md
+++ b/packages/web-components/docs/api-report.md
@@ -4029,6 +4029,58 @@ export const ToggleButtonStyles: ElementStyles;
 // @public
 export const ToggleButtonTemplate: ElementViewTemplate<ToggleButton>;
 
+// @public
+export class Tooltip extends FASTElement {
+    constructor();
+    anchor: string;
+    // (undocumented)
+    connectedCallback(): void;
+    delay: number;
+    // (undocumented)
+    disconnectedCallback(): void;
+    // (undocumented)
+    elementInternals: ElementInternals;
+    handleBlur: () => void;
+    handleFocus: () => void;
+    handleMouseEnter: () => void;
+    handleMouseLeave: () => void;
+    // @internal
+    hideTooltip(delay?: number): void;
+    positioning: string;
+    // @internal
+    showTooltip(delay?: number): void;
+    // @internal
+    tooltip: HTMLElement;
+}
+
+// @public
+export const TooltipDefinition: FASTElementDefinition<typeof Tooltip>;
+
+// @public
+export const TooltipPositioning: {
+    'above-start': string;
+    above: string;
+    'above-end': string;
+    'below-start': string;
+    below: string;
+    'below-end': string;
+    'before-top': string;
+    before: string;
+    'before-bottom': string;
+    'after-top': string;
+    after: string;
+    'after-bottom': string;
+};
+
+// @public
+export type TooltipPositioning = ValuesOf<typeof TooltipPositioning>;
+
+// @public
+export const TooltipStyles: ElementStyles;
+
+// @public
+export const TooltipTemplate: ViewTemplate<Tooltip, any>;
+
 // Warning: (ae-missing-release-tag) "typographyBody1StrongerStyles" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
diff --git a/packages/web-components/src/index-rollup.ts b/packages/web-components/src/index-rollup.ts
index 832770e275eec..33b12fce648d9 100644
--- a/packages/web-components/src/index-rollup.ts
+++ b/packages/web-components/src/index-rollup.ts
@@ -36,3 +36,4 @@ import './textarea/define.js';
 import './text-input/define.js';
 import './text/define.js';
 import './toggle-button/define.js';
+import './tooltip/define.js';
diff --git a/packages/web-components/src/index.ts b/packages/web-components/src/index.ts
index a9f1707983906..36ff11fa9ee84 100644
--- a/packages/web-components/src/index.ts
+++ b/packages/web-components/src/index.ts
@@ -295,6 +295,7 @@ export {
   ToggleButtonTemplate,
 } from './toggle-button/index.js';
 export type { ToggleButtonOptions } from './toggle-button/index.js';
+export { Tooltip, TooltipDefinition, TooltipPositioning, TooltipStyles, TooltipTemplate } from './tooltip/index.js';
 export {
   darkModeStylesheetBehavior,
   forcedColorsStylesheetBehavior,
diff --git a/packages/web-components/src/tooltip/define.ts b/packages/web-components/src/tooltip/define.ts
new file mode 100644
index 0000000000000..ca1312dd587df
--- /dev/null
+++ b/packages/web-components/src/tooltip/define.ts
@@ -0,0 +1,4 @@
+import { FluentDesignSystem } from '../fluent-design-system.js';
+import { definition } from './tooltip.definition.js';
+
+definition.define(FluentDesignSystem.registry);
diff --git a/packages/web-components/src/tooltip/index.ts b/packages/web-components/src/tooltip/index.ts
new file mode 100644
index 0000000000000..ed075c91df59f
--- /dev/null
+++ b/packages/web-components/src/tooltip/index.ts
@@ -0,0 +1,5 @@
+export { definition as TooltipDefinition } from './tooltip.definition.js';
+export { Tooltip } from './tooltip.js';
+export { TooltipPositioning } from './tooltip.options.js';
+export { styles as TooltipStyles } from './tooltip.styles.js';
+export { template as TooltipTemplate } from './tooltip.template.js';
diff --git a/packages/web-components/src/tooltip/tooltip.definition.ts b/packages/web-components/src/tooltip/tooltip.definition.ts
new file mode 100644
index 0000000000000..eb88d205fdd88
--- /dev/null
+++ b/packages/web-components/src/tooltip/tooltip.definition.ts
@@ -0,0 +1,17 @@
+import { FluentDesignSystem } from '../fluent-design-system.js';
+import { Tooltip } from './tooltip.js';
+import { styles } from './tooltip.styles.js';
+import { template } from './tooltip.template.js';
+
+/**
+ * The {@link Tooltip } custom element definition.
+ *
+ * @public
+ * @remarks
+ * HTML Element: `<fluent-tooltip>`
+ */
+export const definition = Tooltip.compose({
+  name: `${FluentDesignSystem.prefix}-tooltip`,
+  template,
+  styles,
+});
diff --git a/packages/web-components/src/tooltip/tooltip.options.ts b/packages/web-components/src/tooltip/tooltip.options.ts
new file mode 100644
index 0000000000000..9ce8a6fe73cb8
--- /dev/null
+++ b/packages/web-components/src/tooltip/tooltip.options.ts
@@ -0,0 +1,26 @@
+import type { ValuesOf } from '../utils/typings.js';
+
+/**
+ * An example Tooltip option
+ * @public
+ */
+export const TooltipPositioning = {
+  'above-start': 'block-start span-inline-end',
+  above: 'block-start',
+  'above-end': 'block-start span-inline-start',
+  'below-start': 'block-end span-inline-end',
+  below: 'block-end',
+  'below-end': 'block-end span-inline-start',
+  'before-top': 'inline-start span-block-end',
+  before: 'inline-start',
+  'before-bottom': 'inline-start span-block-start',
+  'after-top': 'inline-end span-block-end',
+  after: 'inline-end',
+  'after-bottom': 'inline-end span-block-start',
+};
+
+/**
+ * An example TooltipPosition type
+ * @public
+ */
+export type TooltipPositioning = ValuesOf<typeof TooltipPositioning>;
diff --git a/packages/web-components/src/tooltip/tooltip.spec.ts b/packages/web-components/src/tooltip/tooltip.spec.ts
new file mode 100644
index 0000000000000..744e570f7af08
--- /dev/null
+++ b/packages/web-components/src/tooltip/tooltip.spec.ts
@@ -0,0 +1,135 @@
+import { test } from '@playwright/test';
+import { expect, fixtureURL } from '../helpers.tests.js';
+import type { Tooltip } from './tooltip.js';
+
+test.describe('Tooltip', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto(fixtureURL('components-tooltip-tooltip--tooltip'));
+    await page.waitForFunction(() => customElements.whenDefined('fluent-tooltip'));
+
+    await page.setContent(/* html */ `
+      <button id="target">Target</button>
+      <fluent-tooltip anchor="target">This is a tooltip</fluent-tooltip>
+    `);
+  });
+
+  /**
+   * WAI ARIA rules
+   * The element that serves as the tooltip container has role tooltip.
+   * The element that triggers the tooltip references the tooltip element with aria-describedby.
+   */
+  test('should have the role set to `tooltip`', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    await expect(element).toHaveJSProperty('elementInternals.role', 'tooltip');
+  });
+
+  test('should have the `aria-describedby` attribute set to the tooltip id', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    const button = page.locator('button');
+
+    await expect(element).toHaveAttribute('id', 'tooltip-target');
+    await expect(button).toHaveAttribute('aria-describedby', 'tooltip-target');
+  });
+
+  test('should not be visible by default', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    await expect(element).toBeHidden();
+  });
+
+  test('default placement should be set to `above`', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    await expect(element).toHaveAttribute('positioning', 'above');
+  });
+
+  test('should show the tooltip on hover', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    const button = page.locator('button');
+
+    await expect(element).toBeHidden();
+    await button.hover();
+    await expect(element).toBeVisible();
+  });
+
+  test('should show the tooltip on focus', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    const button = page.locator('button');
+
+    await expect(element).toBeHidden();
+    await button.focus();
+    await expect(element).toBeVisible();
+    await button.blur();
+    await expect(element).toBeHidden();
+  });
+
+  test('position should be set to `above` when `positioning` is set to `above`', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    const button = page.locator('button');
+
+    await element.evaluate((node: Tooltip) => {
+      node.positioning = 'above';
+    });
+    await expect(element).toHaveAttribute('positioning', 'above');
+
+    // show the element to get the position
+    await button.focus();
+
+    const buttonTop = await button.evaluate((node: HTMLElement) => node.getBoundingClientRect().top);
+    const elementBottom = await element.evaluate((node: HTMLElement) => node.getBoundingClientRect().bottom);
+
+    await expect(buttonTop).toBeGreaterThan(elementBottom);
+  });
+
+  test('position should be set to `below` when `positioning` is set to `below`', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    const button = page.locator('button');
+
+    await element.evaluate((node: Tooltip) => {
+      node.positioning = 'below';
+    });
+    await expect(element).toHaveAttribute('positioning', 'below');
+
+    // show the element to get the position
+    await button.focus();
+
+    const buttonBottom = await button.evaluate((node: HTMLElement) => node.getBoundingClientRect().bottom);
+    const elementTop = await element.evaluate((node: HTMLElement) => node.getBoundingClientRect().top);
+
+    await expect(buttonBottom).toBeLessThan(elementTop);
+  });
+
+  test('position should be set to `before` when `positioning` is set to `before`', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    const button = page.locator('button');
+
+    await element.evaluate((node: Tooltip) => {
+      node.positioning = 'before';
+    });
+    await expect(element).toHaveAttribute('positioning', 'before');
+
+    // show the element to get the position
+    await button.focus();
+
+    const buttonLeft = await button.evaluate((node: HTMLElement) => node.getBoundingClientRect().left);
+    const elementRight = await element.evaluate((node: HTMLElement) => node.getBoundingClientRect().right);
+
+    await expect(buttonLeft).toBeGreaterThan(elementRight);
+  });
+
+  test('position should be set to `after` when `positioning` is set to `after`', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    const button = page.locator('button');
+
+    await element.evaluate((node: Tooltip) => {
+      node.positioning = 'after';
+    });
+    await expect(element).toHaveAttribute('positioning', 'after');
+
+    // show the element to get the position
+    await button.focus();
+
+    const buttonRight = await button.evaluate((node: HTMLElement) => node.getBoundingClientRect().right);
+    const elementLeft = await element.evaluate((node: HTMLElement) => node.getBoundingClientRect().left);
+
+    await expect(buttonRight).toBeLessThan(elementLeft);
+  });
+});
diff --git a/packages/web-components/src/tooltip/tooltip.stories.ts b/packages/web-components/src/tooltip/tooltip.stories.ts
new file mode 100644
index 0000000000000..ef906f5e73e2c
--- /dev/null
+++ b/packages/web-components/src/tooltip/tooltip.stories.ts
@@ -0,0 +1,151 @@
+import { html, repeat } from '@microsoft/fast-element';
+import { uniqueId } from '@microsoft/fast-web-utilities';
+import { Meta, renderComponent, Story } from '../helpers.stories.js';
+import { definition } from './tooltip.definition.js';
+import { Tooltip } from './tooltip.js';
+import { TooltipPositioning } from './tooltip.options.js';
+
+const storyTemplate = html`
+  <fluent-link id="${story => story.anchor}" href="#">Hover me</fluent-link>
+  <fluent-tooltip
+    anchor="${story => story.anchor}"
+    positioning="${story => story.positioning}"
+    delay="${story => story.delay}"
+  >
+    ${story => story.slottedContent?.()}
+  </fluent-tooltip>
+`;
+
+export default {
+  title: 'Components/Tooltip',
+  component: definition.name,
+  render: renderComponent(storyTemplate),
+  args: {
+    anchor: uniqueId('anchor'),
+    positioning: 'above',
+    delay: 250,
+  },
+  argTypes: {
+    anchor: {
+      control: 'text',
+      description: 'The target element for the tooltip to anchor on',
+      table: { category: 'attributes', type: { summary: 'string' } },
+    },
+    slottedContent: {
+      control: false,
+      description: 'The default slot',
+      table: { category: 'slots', type: {} },
+    },
+    delay: {
+      control: 'number',
+      description: 'Number of milliseconds to delay the tooltip from showing/hiding',
+      table: { category: 'attributes', type: { summary: 'number' } },
+    },
+    positioning: {
+      control: 'select',
+      options: Object.keys(TooltipPositioning),
+      table: { category: 'attributes', type: { summary: 'Controls the positioning of the tooltip' } },
+    },
+  },
+} as unknown as Meta<Tooltip>;
+
+export const Default: Story<Tooltip> = renderComponent(storyTemplate).bind({});
+Default.args = {
+  slottedContent: () => html`Really long tooltip content goes here. lorem ipsum dolor sit amet.`,
+};
+
+const iconArrowRight = (rotation = 0) => html`<svg
+  transform="rotate(${rotation})"
+  width="20"
+  height="20"
+  viewBox="0 0 20 20"
+  fill="currentColor"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <path
+    d="M12.149 3.14636C11.9537 3.34158 11.9536 3.65816 12.1489 3.85347L15.2939 7H10.0001C7.06756 7 4.40686 8.63986 3.06365 11.0427C2.92891 11.2838 3.01508 11.5884 3.25612 11.7231C3.49716 11.8579 3.80179 11.7717 3.93653 11.5307C5.10604 9.43851 7.43601 8 10.0001 8H15.2928L12.1489 11.1454C11.9536 11.3407 11.9537 11.6573 12.149 11.8525C12.3443 12.0478 12.6609 12.0477 12.8561 11.8524L16.8396 7.86711C16.9383 7.77577 17.0001 7.6451 17.0001 7.5V7.5C17.0002 7.37199 16.9514 7.24367 16.8537 7.14598L12.8561 3.14653C12.6609 2.95122 12.3443 2.95115 12.149 3.14636ZM12.0001 15C12.0001 13.8954 11.1047 13 10.0001 13C8.89552 13 8.00009 13.8954 8.00009 15C8.00009 16.1046 8.89552 17 10.0001 17C11.1047 17 12.0001 16.1046 12.0001 15ZM10.0001 14C10.5524 14 11.0001 14.4477 11.0001 15C11.0001 15.5523 10.5524 16 10.0001 16C9.4478 16 9.00009 15.5523 9.00009 15C9.00009 14.4477 9.4478 14 10.0001 14Z"
+  />
+</svg>`;
+
+const iconArrowLeft = (rotation = 0) => html`<svg
+  transform="rotate(${rotation})"
+  width="20"
+  height="20"
+  viewBox="0 0 20 20"
+  fill="currentColor"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <path
+    d="M7.85107 3.14636C8.04638 3.34158 8.04645 3.65816 7.85124 3.85347L4.70617 7H10C12.9325 7 15.5932 8.63986 16.9364 11.0427C17.0712 11.2838 16.985 11.5884 16.744 11.7231C16.5029 11.8579 16.1983 11.7717 16.0636 11.5307C14.894 9.43851 12.5641 8 10 8H4.70725L7.85124 11.1454C8.04645 11.3407 8.04638 11.6573 7.85107 11.8525C7.65577 12.0478 7.33918 12.0477 7.14397 11.8524L3.16054 7.86711C3.06181 7.77577 3 7.6451 3 7.5C3 7.50009 3 7.49991 3 7.5C2.99993 7.37199 3.04872 7.24367 3.14636 7.14598L7.14397 3.14653C7.33918 2.95122 7.65577 2.95115 7.85107 3.14636ZM8 15C8 13.8954 8.89543 13 10 13C11.1046 13 12 13.8954 12 15C12 16.1046 11.1046 17 10 17C8.89543 17 8 16.1046 8 15ZM10 14C9.44772 14 9 14.4477 9 15C9 15.5523 9.44772 16 10 16C10.5523 16 11 15.5523 11 15C11 14.4477 10.5523 14 10 14Z"
+  />
+</svg>`;
+
+const iconArrowUp = (rotation = 0) => html`<svg
+  transform="rotate(${rotation})"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="currentColor"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <path
+    d="M12.75 13.75C12.75 14.1642 12.4142 14.5 12 14.5C11.5858 14.5 11.25 14.1642 11.25 13.75V4.49365L7.76581 7.79446C7.46511 8.07934 6.99041 8.06651 6.70554 7.76581C6.42066 7.46511 6.43349 6.99041 6.73419 6.70554L11.4842 2.20554C11.7735 1.93149 12.2265 1.93149 12.5158 2.20554L17.2658 6.70554C17.5665 6.99041 17.5793 7.46511 17.2945 7.76581C17.0096 8.06651 16.5349 8.07934 16.2342 7.79446L12.75 4.49365V13.75ZM15 19C15 20.6569 13.6569 22 12 22C10.3431 22 9 20.6569 9 19C9 17.3431 10.3431 16 12 16C13.6569 16 15 17.3431 15 19ZM10.5 19C10.5 19.8284 11.1716 20.5 12 20.5C12.8284 20.5 13.5 19.8284 13.5 19C13.5 18.1716 12.8284 17.5 12 17.5C11.1716 17.5 10.5 18.1716 10.5 19Z"
+  />
+</svg>`;
+
+const glyphs = {
+  'above-start': iconArrowRight(-90),
+  above: iconArrowUp(),
+  'above-end': iconArrowLeft(90),
+  'below-start': iconArrowLeft(-90),
+  below: iconArrowUp(180),
+  'below-end': iconArrowRight(90),
+  'before-top': iconArrowLeft(0),
+  before: iconArrowUp(-90),
+  'before-bottom': iconArrowRight(180),
+  'after-top': iconArrowRight(),
+  after: iconArrowUp(90),
+  'after-bottom': iconArrowLeft(180),
+};
+
+const positionButtonTemplate = html`
+  <fluent-button id="btn-${x => x.id}" style="grid-area: ${x => x.id}">
+    ${x => glyphs[x.id as keyof typeof glyphs]}
+  </fluent-button>
+`;
+
+const positionTooltipTemplate = html`
+  <fluent-tooltip anchor="btn-${x => x.id}" positioning="${x => x.id}"> ${x => x.id} </fluent-tooltip>
+`;
+
+export const Positioning: Story<Tooltip> = renderComponent(html`
+  <style>
+    .grid {
+      box-sizing: border-box;
+      display: grid;
+      gap: 4px;
+      max-width: min-content;
+      grid-template-areas:
+        '. above-start above above-end .'
+        'before-top . . . after-top'
+        'before . . . after'
+        'before-bottom . . . after-bottom'
+        '. below-start below below-end .';
+    }
+    .grid fluent-button {
+      aspect-ratio: 1;
+      min-width: 44px;
+    }
+    /* Fallbacks positions are too aggressive and break demo */
+    .grid ~ fluent-tooltip {
+      position-try-fallbacks: none;
+    }
+  </style>
+  <div class="grid">${repeat(x => x.storyItems, positionButtonTemplate)}</div>
+
+  ${repeat(x => x.storyItems, positionTooltipTemplate)}
+`).bind({});
+
+Positioning.args = {
+  storyItems: Object.keys(TooltipPositioning).map(id => ({ id })),
+};
diff --git a/packages/web-components/src/tooltip/tooltip.styles.ts b/packages/web-components/src/tooltip/tooltip.styles.ts
new file mode 100644
index 0000000000000..4ca1d16934519
--- /dev/null
+++ b/packages/web-components/src/tooltip/tooltip.styles.ts
@@ -0,0 +1,94 @@
+import { css } from '@microsoft/fast-element';
+import { display } from '../utils/display.js';
+
+import {
+  borderRadiusMedium,
+  colorNeutralBackground1,
+  colorNeutralForeground1,
+  colorNeutralShadowAmbient,
+  colorNeutralShadowKey,
+  fontFamilyBase,
+  fontSizeBase200,
+  lineHeightBase200,
+  spacingHorizontalXS,
+  spacingVerticalXS,
+} from '../theme/design-tokens.js';
+
+/**
+ * Styles for the tooltip component
+ * @public
+ */
+export const styles = css`
+  ${display('inline-flex')}
+
+  :host(:not(:popover-open)) {
+    display: none;
+  }
+
+  :host {
+    --blockOffset: ${spacingVerticalXS};
+    --inlineOffset: ${spacingHorizontalXS};
+    background: ${colorNeutralBackground1};
+    border-radius: ${borderRadiusMedium};
+    border: 1px solid var(--colorTransparentStroke);
+    box-sizing: border-box;
+    color: ${colorNeutralForeground1};
+    display: inline-flex;
+    filter: drop-shadow(0 0 2px ${colorNeutralShadowAmbient}) drop-shadow(0 4px 8px ${colorNeutralShadowKey});
+    font-family: ${fontFamilyBase};
+    font-size: ${fontSizeBase200};
+    inset-area: block-start;
+    line-height: ${lineHeightBase200};
+    margin: 0;
+    max-width: 240px;
+    padding: 4px 11px 6px;
+    position-try-fallbacks: flip-block flip-inline;
+    position: absolute;
+    width: max-content;
+    z-index: 1;
+  }
+
+  :host(:is([positioning^='above'], [positioning^='below'])) {
+    margin-block: var(--blockOffset);
+  }
+  :host(:is([positioning^='before'], [positioning^='after'])) {
+    margin-inline: var(--inlineOffset);
+  }
+
+  :host([positioning='above-start']) {
+    inset-area: block-start span-inline-end;
+  }
+  :host([positioning='above']) {
+    inset-area: block-start;
+  }
+  :host([positioning='above-end']) {
+    inset-area: block-start span-inline-start;
+  }
+  :host([positioning='below-start']) {
+    inset-area: block-end span-inline-end;
+  }
+  :host([positioning='below']) {
+    inset-area: block-end;
+  }
+  :host([positioning='below-end']) {
+    inset-area: block-end span-inline-start;
+  }
+  :host([positioning='before-top']) {
+    inset-area: inline-start span-block-end;
+  }
+  :host([positioning='before']) {
+    inset-area: inline-start;
+  }
+  :host([positioning='before-bottom']) {
+    inset-area: inline-start span-block-start;
+  }
+  :host([positioning='after-top']) {
+    inset-area: inline-end span-block-end;
+  }
+  :host([positioning='after']) {
+    inset-area: inline-end;
+  }
+  :host([positioning='after-bottom']) {
+    inset-area: inline-end span-block-start;
+  }
+`;
diff --git a/packages/web-components/src/tooltip/tooltip.template.ts b/packages/web-components/src/tooltip/tooltip.template.ts
new file mode 100644
index 0000000000000..aef051d1237c4
--- /dev/null
+++ b/packages/web-components/src/tooltip/tooltip.template.ts
@@ -0,0 +1,12 @@
+import { html, ref } from '@microsoft/fast-element';
+import type { Tooltip } from './tooltip.js';
+
+/**
+ * Template for the tooltip component
+ * @public
+ */
+export const template = html<Tooltip>`
+  <template ${ref('tooltip')} id="tooltip-${x => x.anchor}" popover="manual" aria-hidden="true">
+    <slot></slot>
+  </template>
+`;
diff --git a/packages/web-components/src/tooltip/tooltip.ts b/packages/web-components/src/tooltip/tooltip.ts
new file mode 100644
index 0000000000000..3aa868f903e37
--- /dev/null
+++ b/packages/web-components/src/tooltip/tooltip.ts
@@ -0,0 +1,116 @@
+import { attr, FASTElement } from '@microsoft/fast-element';
+
+/**
+ * A Tooltip Custom HTML Element.
+ * @public
+ */
+export class Tooltip extends FASTElement {
+  public elementInternals = this.attachInternals();
+
+  /**
+   * Set the delay for the tooltip
+   */
+  @attr
+  public delay: number = 250;
+
+  /**
+   * Set the positioning of the tooltip
+   */
+  @attr
+  public positioning: string = 'above';
+
+  /**
+   * Reference to the tooltip element
+   * @internal
+   */
+  public tooltip!: HTMLElement;
+
+  /**
+   * The id of the anchor element for the tooltip
+   * @public
+   */
+  @attr
+  public anchor: string = '';
+
+  /**
+   * Reference to the anchor element
+   * @internal
+   */
+  private anchorElement: HTMLElement | null = null;
+
+  public constructor() {
+    super();
+    this.elementInternals.role = 'tooltip';
+  }
+
+  public connectedCallback(): void {
+    super.connectedCallback();
+
+    this.anchorElement = document.getElementById(this.anchor) || null;
+
+    if (this.anchorElement) {
+      this.anchorElement.setAttribute('aria-describedby', `tooltip-${this.anchor}`);
+
+      // @ts-expect-error Baseline 2024
+      this.anchorElement.style.anchorName = `--${this.anchor}`;
+      // @ts-expect-error Baseline 2024
+      this.style.positionAnchor = `--${this.anchor}`;
+
+      this.anchorElement.addEventListener('focus', this.handleFocus);
+      this.anchorElement.addEventListener('blur', this.handleBlur);
+      this.anchorElement.addEventListener('mouseenter', this.handleMouseEnter);
+      this.anchorElement.addEventListener('mouseleave', this.handleMouseLeave);
+    }
+  }
+
+  public disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.anchorElement?.removeEventListener('focus', this.handleFocus);
+    this.anchorElement?.removeEventListener('blur', this.handleBlur);
+    this.anchorElement?.removeEventListener('mouseenter', this.handleMouseEnter);
+    this.anchorElement?.removeEventListener('mouseleave', this.handleMouseLeave);
+  }
+
+  /**
+   * Shows the tooltip
+   * @param delay Number of milliseconds to delay showing the tooltip
+   * @internal
+   */
+  public showTooltip(delay: number = 0): void {
+    setTimeout(() => {
+      this.tooltip.setAttribute('aria-hidden', 'false');
+      // @ts-expect-error Baseline 2024
+      this.showPopover();
+    }, delay);
+  }
+
+  /**
+   * Hide the tooltip
+   * @param delay Number of milliseconds to delay hiding the tooltip
+   * @internal
+   */
+  public hideTooltip(delay: number = 0): void {
+    setTimeout(() => {
+      this.tooltip.setAttribute('aria-hidden', 'true');
+      // @ts-expect-error Baseline 2024
+      this.hidePopover();
+    }, delay);
+  }
+
+  /**
+   * Show the tooltip on mouse enter
+   */
+  public handleMouseEnter = () => this.showTooltip(this.delay);
+  /**
+   * Hide the tooltip on mouse leave
+   */
+  public handleMouseLeave = () => this.hideTooltip(this.delay);
+  /**
+   * Show the tooltip on focus
+   */
+  public handleFocus = () => this.showTooltip();
+  /**
+   * Hide the tooltip on blur
+   */
+  public handleBlur = () => this.hideTooltip();
+}

From f3d4fc6a2f5bc4768203cf6b6ff9a3863878030c Mon Sep 17 00:00:00 2001
From: Dave Rupert <rupertdavid@microsoft.com>
Date: Tue, 17 Sep 2024 12:00:05 -0500
Subject: [PATCH 2/7] add changefile

---
 ...eb-components-037cbaec-4ee8-4f24-8cb7-1ae8ea8546f4.json | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 change/@fluentui-web-components-037cbaec-4ee8-4f24-8cb7-1ae8ea8546f4.json

diff --git a/change/@fluentui-web-components-037cbaec-4ee8-4f24-8cb7-1ae8ea8546f4.json b/change/@fluentui-web-components-037cbaec-4ee8-4f24-8cb7-1ae8ea8546f4.json
new file mode 100644
index 0000000000000..f82c20fa0fa23
--- /dev/null
+++ b/change/@fluentui-web-components-037cbaec-4ee8-4f24-8cb7-1ae8ea8546f4.json
@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat: add Tooltip component",
+  "packageName": "@fluentui/web-components",
+  "email": "rupertdavid@microsoft.com",
+  "dependentChangeType": "patch"
+}

From 78e6bce8f4d27b8614524d08c51868f6e2e83b3f Mon Sep 17 00:00:00 2001
From: Dave Rupert <rupertdavid@microsoft.com>
Date: Tue, 17 Sep 2024 12:14:19 -0500
Subject: [PATCH 3/7] fix default story

---
 .../src/tooltip/tooltip.stories.ts            | 30 +++++++++----------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/packages/web-components/src/tooltip/tooltip.stories.ts b/packages/web-components/src/tooltip/tooltip.stories.ts
index ef906f5e73e2c..f6c5fe5b8924e 100644
--- a/packages/web-components/src/tooltip/tooltip.stories.ts
+++ b/packages/web-components/src/tooltip/tooltip.stories.ts
@@ -1,33 +1,31 @@
-import { html, repeat } from '@microsoft/fast-element';
+import { html, render, repeat } from '@microsoft/fast-element';
 import { uniqueId } from '@microsoft/fast-web-utilities';
 import { Meta, renderComponent, Story } from '../helpers.stories.js';
 import { definition } from './tooltip.definition.js';
 import { Tooltip } from './tooltip.js';
 import { TooltipPositioning } from './tooltip.options.js';
 
-const storyTemplate = html`
-  <fluent-link id="${story => story.anchor}" href="#">Hover me</fluent-link>
-  <fluent-tooltip
-    anchor="${story => story.anchor}"
-    positioning="${story => story.positioning}"
-    delay="${story => story.delay}"
-  >
-    ${story => story.slottedContent?.()}
-  </fluent-tooltip>
-`;
+const storyTemplate = () => {
+  const id = uniqueId('anchor');
+
+  return html`
+    <fluent-link id="${id}" href="#">Hover me</fluent-link>
+    <fluent-tooltip anchor="${id}" positioning="${story => story.positioning}" delay="${story => story.delay}">
+      ${story => story.slottedContent?.()}
+    </fluent-tooltip>
+  `;
+};
 
 export default {
   title: 'Components/Tooltip',
   component: definition.name,
-  render: renderComponent(storyTemplate),
+  render: renderComponent(storyTemplate()),
   args: {
-    anchor: uniqueId('anchor'),
     positioning: 'above',
     delay: 250,
   },
   argTypes: {
     anchor: {
-      control: 'text',
       description: 'The target element for the tooltip to anchor on',
       table: { category: 'attributes', type: { summary: 'string' } },
     },
@@ -49,7 +47,9 @@ export default {
   },
 } as unknown as Meta<Tooltip>;
 
-export const Default: Story<Tooltip> = renderComponent(storyTemplate).bind({});
+export const Default: Story<Tooltip> = args => {
+  return renderComponent(html`${render(args, storyTemplate)}`)(args);
+};
 Default.args = {
   slottedContent: () => html`Really long tooltip content goes here. lorem ipsum dolor sit amet.`,
 };

From d22b3ead8a7bc7dc65123f229d2e766bab424846 Mon Sep 17 00:00:00 2001
From: Dave Rupert <rupertdavid@microsoft.com>
Date: Thu, 19 Sep 2024 16:11:43 -0500
Subject: [PATCH 4/7] updates per feedback

---
 packages/web-components/docs/api-report.md    |  5 +--
 .../src/tooltip/tooltip.options.ts            |  4 +-
 .../src/tooltip/tooltip.spec.ts               | 13 ++++++-
 .../src/tooltip/tooltip.stories.ts            |  3 +-
 .../src/tooltip/tooltip.styles.ts             | 33 +++++++++--------
 .../src/tooltip/tooltip.template.ts           |  4 +-
 .../web-components/src/tooltip/tooltip.ts     | 37 ++++++++++++-------
 7 files changed, 58 insertions(+), 41 deletions(-)

diff --git a/packages/web-components/docs/api-report.md b/packages/web-components/docs/api-report.md
index 8a6743d150377..9fa00871a6efc 100644
--- a/packages/web-components/docs/api-report.md
+++ b/packages/web-components/docs/api-report.md
@@ -4035,10 +4035,9 @@ export class Tooltip extends FASTElement {
     anchor: string;
     // (undocumented)
     connectedCallback(): void;
-    delay: number;
+    delay?: number;
     // (undocumented)
     disconnectedCallback(): void;
-    // (undocumented)
     elementInternals: ElementInternals;
     handleBlur: () => void;
     handleFocus: () => void;
@@ -4049,8 +4048,6 @@ export class Tooltip extends FASTElement {
     positioning: string;
     // @internal
     showTooltip(delay?: number): void;
-    // @internal
-    tooltip: HTMLElement;
 }
 
 // @public
diff --git a/packages/web-components/src/tooltip/tooltip.options.ts b/packages/web-components/src/tooltip/tooltip.options.ts
index 9ce8a6fe73cb8..a7157f9130f79 100644
--- a/packages/web-components/src/tooltip/tooltip.options.ts
+++ b/packages/web-components/src/tooltip/tooltip.options.ts
@@ -1,7 +1,7 @@
 import type { ValuesOf } from '../utils/typings.js';
 
 /**
- * An example Tooltip option
+ * The TooltipPositioning options and their corresponding CSS values
  * @public
  */
 export const TooltipPositioning = {
@@ -20,7 +20,7 @@ export const TooltipPositioning = {
 };
 
 /**
- * An example TooltipPosition type
+ * The TooltipPositioning type
  * @public
  */
 export type TooltipPositioning = ValuesOf<typeof TooltipPositioning>;
diff --git a/packages/web-components/src/tooltip/tooltip.spec.ts b/packages/web-components/src/tooltip/tooltip.spec.ts
index 744e570f7af08..342eebca54997 100644
--- a/packages/web-components/src/tooltip/tooltip.spec.ts
+++ b/packages/web-components/src/tooltip/tooltip.spec.ts
@@ -14,10 +14,21 @@ test.describe('Tooltip', () => {
   });
 
   /**
-   * WAI ARIA rules
+   * ARIA APG Tooltip Pattern {@link https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/ }
+   * ESC dismisses the tooltip.
    * The element that serves as the tooltip container has role tooltip.
    * The element that triggers the tooltip references the tooltip element with aria-describedby.
    */
+  test('escape key should hide the tooltip', async ({ page }) => {
+    const element = page.locator('fluent-tooltip');
+    const button = page.locator('button');
+
+    await button.focus();
+    await expect(element).toBeVisible();
+    await page.keyboard.press('Escape');
+    await expect(element).toBeHidden();
+  });
+
   test('should have the role set to `tooltip`', async ({ page }) => {
     const element = page.locator('fluent-tooltip');
     await expect(element).toHaveJSProperty('elementInternals.role', 'tooltip');
diff --git a/packages/web-components/src/tooltip/tooltip.stories.ts b/packages/web-components/src/tooltip/tooltip.stories.ts
index f6c5fe5b8924e..83549ee53be2e 100644
--- a/packages/web-components/src/tooltip/tooltip.stories.ts
+++ b/packages/web-components/src/tooltip/tooltip.stories.ts
@@ -22,7 +22,6 @@ export default {
   render: renderComponent(storyTemplate()),
   args: {
     positioning: 'above',
-    delay: 250,
   },
   argTypes: {
     anchor: {
@@ -36,7 +35,7 @@ export default {
     },
     delay: {
       control: 'number',
-      description: 'Number of milliseconds to delay the tooltip from showing/hiding',
+      description: 'Number of milliseconds to delay the tooltip from showing/hiding on hover. Default is 250ms',
       table: { category: 'attributes', type: { summary: 'number' } },
     },
     positioning: {
diff --git a/packages/web-components/src/tooltip/tooltip.styles.ts b/packages/web-components/src/tooltip/tooltip.styles.ts
index 4ca1d16934519..aeade002d652a 100644
--- a/packages/web-components/src/tooltip/tooltip.styles.ts
+++ b/packages/web-components/src/tooltip/tooltip.styles.ts
@@ -1,6 +1,5 @@
 import { css } from '@microsoft/fast-element';
 import { display } from '../utils/display.js';
-
 import {
   borderRadiusMedium,
   colorNeutralBackground1,
@@ -13,6 +12,7 @@ import {
   spacingHorizontalXS,
   spacingVerticalXS,
 } from '../theme/design-tokens.js';
+import { TooltipPositioning } from './tooltip.options.js';
 
 /**
  * Styles for the tooltip component
@@ -42,53 +42,54 @@ export const styles = css`
     margin: 0;
     max-width: 240px;
     padding: 4px 11px 6px;
-    position-try-fallbacks: flip-block flip-inline;
     position: absolute;
-    width: max-content;
+    width: auto;
     z-index: 1;
   }
 
-  :host(:is([positioning^='above'], [positioning^='below'])) {
+  :host(:is([positioning^='above'], [positioning^='below'], :not([positioning]))) {
     margin-block: var(--blockOffset);
+    position-try-fallbacks: flip-block;
   }
   :host(:is([positioning^='before'], [positioning^='after'])) {
     margin-inline: var(--inlineOffset);
+    position-try-fallbacks: flip-inline;
   }
 
   :host([positioning='above-start']) {
-    inset-area: block-start span-inline-end;
+    inset-area: ${TooltipPositioning['above-start']};
   }
   :host([positioning='above']) {
-    inset-area: block-start;
+    inset-area: ${TooltipPositioning.above};
   }
   :host([positioning='above-end']) {
-    inset-area: block-start span-inline-start;
+    inset-area: ${TooltipPositioning['above-end']};
   }
   :host([positioning='below-start']) {
-    inset-area: block-end span-inline-end;
+    inset-area: ${TooltipPositioning['below-start']};
   }
   :host([positioning='below']) {
-    inset-area: block-end;
+    inset-area: ${TooltipPositioning.below};
   }
   :host([positioning='below-end']) {
-    inset-area: block-end span-inline-start;
+    inset-area: ${TooltipPositioning['below-end']};
   }
   :host([positioning='before-top']) {
-    inset-area: inline-start span-block-end;
+    inset-area: ${TooltipPositioning['before-top']};
   }
   :host([positioning='before']) {
-    inset-area: inline-start;
+    inset-area: ${TooltipPositioning.before};
   }
   :host([positioning='before-bottom']) {
-    inset-area: inline-start span-block-start;
+    inset-area: ${TooltipPositioning['before-bottom']};
   }
   :host([positioning='after-top']) {
-    inset-area: inline-end span-block-end;
+    inset-area: ${TooltipPositioning['after-top']};
   }
   :host([positioning='after']) {
-    inset-area: inline-end;
+    inset-area: ${TooltipPositioning.after};
   }
   :host([positioning='after-bottom']) {
-    inset-area: inline-end span-block-start;
+    inset-area: ${TooltipPositioning['after-bottom']};
   }
 `;
diff --git a/packages/web-components/src/tooltip/tooltip.template.ts b/packages/web-components/src/tooltip/tooltip.template.ts
index aef051d1237c4..b115a45b239d1 100644
--- a/packages/web-components/src/tooltip/tooltip.template.ts
+++ b/packages/web-components/src/tooltip/tooltip.template.ts
@@ -1,4 +1,4 @@
-import { html, ref } from '@microsoft/fast-element';
+import { html } from '@microsoft/fast-element';
 import type { Tooltip } from './tooltip.js';
 
 /**
@@ -6,7 +6,7 @@ import type { Tooltip } from './tooltip.js';
  * @public
  */
 export const template = html<Tooltip>`
-  <template ${ref('tooltip')} id="tooltip-${x => x.anchor}" popover="manual" aria-hidden="true">
+  <template id="tooltip-${x => x.anchor}" popover aria-hidden="true">
     <slot></slot>
   </template>
 `;
diff --git a/packages/web-components/src/tooltip/tooltip.ts b/packages/web-components/src/tooltip/tooltip.ts
index 3aa868f903e37..1e226a3be729b 100644
--- a/packages/web-components/src/tooltip/tooltip.ts
+++ b/packages/web-components/src/tooltip/tooltip.ts
@@ -2,32 +2,35 @@ import { attr, FASTElement } from '@microsoft/fast-element';
 
 /**
  * A Tooltip Custom HTML Element.
+ * Based on ARIA APG Tooltip Pattern {@link https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/ }
  * @public
  */
 export class Tooltip extends FASTElement {
+  /**
+   * The attached element internals
+   */
   public elementInternals = this.attachInternals();
 
   /**
    * Set the delay for the tooltip
    */
   @attr
-  public delay: number = 250;
+  public delay?: number;
 
   /**
-   * Set the positioning of the tooltip
+   * The default delay for the tooltip
+   * @internal
    */
-  @attr
-  public positioning: string = 'above';
+  private defaultDelay: number = 250;
 
   /**
-   * Reference to the tooltip element
-   * @internal
+   * Set the positioning of the tooltip
    */
-  public tooltip!: HTMLElement;
+  @attr
+  public positioning?: string;
 
   /**
    * The id of the anchor element for the tooltip
-   * @public
    */
   @attr
   public anchor: string = '';
@@ -76,9 +79,9 @@ export class Tooltip extends FASTElement {
    * @param delay Number of milliseconds to delay showing the tooltip
    * @internal
    */
-  public showTooltip(delay: number = 0): void {
+  public showTooltip(delay: number = this.defaultDelay): void {
     setTimeout(() => {
-      this.tooltip.setAttribute('aria-hidden', 'false');
+      this.setAttribute('aria-hidden', 'false');
       // @ts-expect-error Baseline 2024
       this.showPopover();
     }, delay);
@@ -89,9 +92,15 @@ export class Tooltip extends FASTElement {
    * @param delay Number of milliseconds to delay hiding the tooltip
    * @internal
    */
-  public hideTooltip(delay: number = 0): void {
+  public hideTooltip(delay: number = this.defaultDelay): void {
     setTimeout(() => {
-      this.tooltip.setAttribute('aria-hidden', 'true');
+      // Detect if the tooltip or anchor element is still hovered and enqueue another hide
+      if (this.matches(':hover') || this.anchorElement?.matches(':hover')) {
+        this.hideTooltip(delay);
+        return;
+      }
+
+      this.setAttribute('aria-hidden', 'true');
       // @ts-expect-error Baseline 2024
       this.hidePopover();
     }, delay);
@@ -108,9 +117,9 @@ export class Tooltip extends FASTElement {
   /**
    * Show the tooltip on focus
    */
-  public handleFocus = () => this.showTooltip();
+  public handleFocus = () => this.showTooltip(0);
   /**
    * Hide the tooltip on blur
    */
-  public handleBlur = () => this.hideTooltip();
+  public handleBlur = () => this.hideTooltip(0);
 }

From e2599d4d143ed0cf463ec5f7e5934b0d03f20fab Mon Sep 17 00:00:00 2001
From: Dave Rupert <rupertdavid@microsoft.com>
Date: Thu, 19 Sep 2024 17:54:36 -0500
Subject: [PATCH 5/7] convert anchorElement to a getter

---
 packages/web-components/src/tooltip/tooltip.ts | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/packages/web-components/src/tooltip/tooltip.ts b/packages/web-components/src/tooltip/tooltip.ts
index 1e226a3be729b..1448e23c69dd8 100644
--- a/packages/web-components/src/tooltip/tooltip.ts
+++ b/packages/web-components/src/tooltip/tooltip.ts
@@ -39,7 +39,9 @@ export class Tooltip extends FASTElement {
    * Reference to the anchor element
    * @internal
    */
-  private anchorElement: HTMLElement | null = null;
+  private get anchorElement(): HTMLElement | null {
+    return document.getElementById(this.anchor ?? '');
+  }
 
   public constructor() {
     super();
@@ -48,9 +50,6 @@ export class Tooltip extends FASTElement {
 
   public connectedCallback(): void {
     super.connectedCallback();
-
-    this.anchorElement = document.getElementById(this.anchor) || null;
-
     if (this.anchorElement) {
       this.anchorElement.setAttribute('aria-describedby', `tooltip-${this.anchor}`);
 

From e9a37e1224643a31e47ebaa361aa6c7e906ae843 Mon Sep 17 00:00:00 2001
From: Dave Rupert <rupertdavid@microsoft.com>
Date: Fri, 20 Sep 2024 14:49:54 -0500
Subject: [PATCH 6/7] fixes per feedback

---
 .../web-components/src/tooltip/tooltip.options.ts     |  2 +-
 packages/web-components/src/tooltip/tooltip.spec.ts   | 11 ++++++++++-
 packages/web-components/src/tooltip/tooltip.styles.ts |  3 ++-
 packages/web-components/src/tooltip/tooltip.ts        |  7 ++++---
 4 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/packages/web-components/src/tooltip/tooltip.options.ts b/packages/web-components/src/tooltip/tooltip.options.ts
index a7157f9130f79..319b9b1cee6c7 100644
--- a/packages/web-components/src/tooltip/tooltip.options.ts
+++ b/packages/web-components/src/tooltip/tooltip.options.ts
@@ -17,7 +17,7 @@ export const TooltipPositioning = {
   'after-top': 'inline-end span-block-end',
   after: 'inline-end',
   'after-bottom': 'inline-end span-block-start',
-};
+} as const;
 
 /**
  * The TooltipPositioning type
diff --git a/packages/web-components/src/tooltip/tooltip.spec.ts b/packages/web-components/src/tooltip/tooltip.spec.ts
index 342eebca54997..0dd2f8949da70 100644
--- a/packages/web-components/src/tooltip/tooltip.spec.ts
+++ b/packages/web-components/src/tooltip/tooltip.spec.ts
@@ -49,7 +49,16 @@ test.describe('Tooltip', () => {
 
   test('default placement should be set to `above`', async ({ page }) => {
     const element = page.locator('fluent-tooltip');
-    await expect(element).toHaveAttribute('positioning', 'above');
+    const button = page.locator('button');
+    await expect(element).not.toHaveAttribute('positioning', 'above');
+
+    // show the element to get the position
+    await button.focus();
+
+    const buttonTop = await button.evaluate((node: HTMLElement) => node.getBoundingClientRect().top);
+    const elementBottom = await element.evaluate((node: HTMLElement) => node.getBoundingClientRect().bottom);
+
+    await expect(buttonTop).toBeGreaterThan(elementBottom);
   });
 
   test('should show the tooltip on hover', async ({ page }) => {
diff --git a/packages/web-components/src/tooltip/tooltip.styles.ts b/packages/web-components/src/tooltip/tooltip.styles.ts
index aeade002d652a..c440e0a16b242 100644
--- a/packages/web-components/src/tooltip/tooltip.styles.ts
+++ b/packages/web-components/src/tooltip/tooltip.styles.ts
@@ -6,6 +6,7 @@ import {
   colorNeutralForeground1,
   colorNeutralShadowAmbient,
   colorNeutralShadowKey,
+  colorTransparentStroke,
   fontFamilyBase,
   fontSizeBase200,
   lineHeightBase200,
@@ -30,7 +31,7 @@ export const styles = css`
     --inlineOffset: ${spacingHorizontalXS};
     background: ${colorNeutralBackground1};
     border-radius: ${borderRadiusMedium};
-    border: 1px solid var(--colorTransparentStroke);
+    border: 1px solid ${colorTransparentStroke};
     box-sizing: border-box;
     color: ${colorNeutralForeground1};
     display: inline-flex;
diff --git a/packages/web-components/src/tooltip/tooltip.ts b/packages/web-components/src/tooltip/tooltip.ts
index 1448e23c69dd8..8414b9536240d 100644
--- a/packages/web-components/src/tooltip/tooltip.ts
+++ b/packages/web-components/src/tooltip/tooltip.ts
@@ -1,4 +1,4 @@
-import { attr, FASTElement } from '@microsoft/fast-element';
+import { attr, FASTElement, nullableNumberConverter } from '@microsoft/fast-element';
 
 /**
  * A Tooltip Custom HTML Element.
@@ -14,7 +14,7 @@ export class Tooltip extends FASTElement {
   /**
    * Set the delay for the tooltip
    */
-  @attr
+  @attr({ converter: nullableNumberConverter })
   public delay?: number;
 
   /**
@@ -40,7 +40,8 @@ export class Tooltip extends FASTElement {
    * @internal
    */
   private get anchorElement(): HTMLElement | null {
-    return document.getElementById(this.anchor ?? '');
+    const rootNode = this.getRootNode();
+    return (rootNode instanceof ShadowRoot ? rootNode : document).getElementById(this.anchor ?? '');
   }
 
   public constructor() {

From 93b4e68e8e1ca8c407b19e71e18a064a27758e4c Mon Sep 17 00:00:00 2001
From: Dave Rupert <rupertdavid@microsoft.com>
Date: Mon, 23 Sep 2024 15:19:52 -0500
Subject: [PATCH 7/7] allow author-defined ids on tooltip

---
 .../web-components/src/tooltip/tooltip.stories.ts   |  3 ++-
 .../web-components/src/tooltip/tooltip.styles.ts    |  2 +-
 .../web-components/src/tooltip/tooltip.template.ts  |  2 +-
 packages/web-components/src/tooltip/tooltip.ts      | 13 ++++++++++++-
 4 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/packages/web-components/src/tooltip/tooltip.stories.ts b/packages/web-components/src/tooltip/tooltip.stories.ts
index 83549ee53be2e..d292a4ff3e27b 100644
--- a/packages/web-components/src/tooltip/tooltip.stories.ts
+++ b/packages/web-components/src/tooltip/tooltip.stories.ts
@@ -40,8 +40,9 @@ export default {
     },
     positioning: {
       control: 'select',
+      description: 'Controls the positioning of the tooltip',
       options: Object.keys(TooltipPositioning),
-      table: { category: 'attributes', type: { summary: 'Controls the positioning of the tooltip' } },
+      table: { category: 'attributes', type: { summary: 'string' } },
     },
   },
 } as unknown as Meta<Tooltip>;
diff --git a/packages/web-components/src/tooltip/tooltip.styles.ts b/packages/web-components/src/tooltip/tooltip.styles.ts
index c440e0a16b242..ce27c412dc0f3 100644
--- a/packages/web-components/src/tooltip/tooltip.styles.ts
+++ b/packages/web-components/src/tooltip/tooltip.styles.ts
@@ -40,7 +40,7 @@ export const styles = css`
     font-size: ${fontSizeBase200};
     inset-area: block-start;
     line-height: ${lineHeightBase200};
-    margin: 0;
+    margin: unset; /* Remove browser default for [popover] */
     max-width: 240px;
     padding: 4px 11px 6px;
     position: absolute;
diff --git a/packages/web-components/src/tooltip/tooltip.template.ts b/packages/web-components/src/tooltip/tooltip.template.ts
index b115a45b239d1..226448c4f04f4 100644
--- a/packages/web-components/src/tooltip/tooltip.template.ts
+++ b/packages/web-components/src/tooltip/tooltip.template.ts
@@ -6,7 +6,7 @@ import type { Tooltip } from './tooltip.js';
  * @public
  */
 export const template = html<Tooltip>`
-  <template id="tooltip-${x => x.anchor}" popover aria-hidden="true">
+  <template id="${x => x.id}" popover aria-hidden="true">
     <slot></slot>
   </template>
 `;
diff --git a/packages/web-components/src/tooltip/tooltip.ts b/packages/web-components/src/tooltip/tooltip.ts
index 8414b9536240d..63df42663a090 100644
--- a/packages/web-components/src/tooltip/tooltip.ts
+++ b/packages/web-components/src/tooltip/tooltip.ts
@@ -1,4 +1,5 @@
 import { attr, FASTElement, nullableNumberConverter } from '@microsoft/fast-element';
+import { uniqueId } from '@microsoft/fast-web-utilities';
 
 /**
  * A Tooltip Custom HTML Element.
@@ -11,6 +12,16 @@ export class Tooltip extends FASTElement {
    */
   public elementInternals = this.attachInternals();
 
+  /**
+   * The item ID
+   *
+   * @public
+   * @remarks
+   * HTML Attribute: id
+   */
+  @attr
+  public id: string = uniqueId('tooltip-');
+
   /**
    * Set the delay for the tooltip
    */
@@ -52,7 +63,7 @@ export class Tooltip extends FASTElement {
   public connectedCallback(): void {
     super.connectedCallback();
     if (this.anchorElement) {
-      this.anchorElement.setAttribute('aria-describedby', `tooltip-${this.anchor}`);
+      this.anchorElement.setAttribute('aria-describedby', this.id);
 
       // @ts-expect-error Baseline 2024
       this.anchorElement.style.anchorName = `--${this.anchor}`;