Tooltip tweaks

- Move to tooltips directory to appease linting.
- Add files to grd.
- Simplify implementation a little bit.
- Enforce ids on non-template construction and validate it against
  aria-details/describedby.
- Show tooltip on focus.

Bug: 392078321
Change-Id: I36485bcdd748ce99dd3a9ae5bcb375c0b5c1837d
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6305499
Commit-Queue: Philip Pfaffe <[email protected]>
Auto-Submit: Philip Pfaffe <[email protected]>
Reviewed-by: Kim-Anh Tran <[email protected]>

Author: pfaffe

config/gni/devtools_grd_files.gni

@@ -766,6 +766,7 @@ grd_files_release_sources = [
   "front_end/ui/components/switch/switch.js",
   "front_end/ui/components/text_editor/text_editor.js",
   "front_end/ui/components/text_prompt/text_prompt.js",
+  "front_end/ui/components/tooltips/tooltips.js",
   "front_end/ui/components/tree_outline/tree_outline.js",
   "front_end/ui/legacy/components/color_picker/color_picker.js",
   "front_end/ui/legacy/components/cookie_table/cookie_table.js",
@@ -2346,6 +2347,8 @@ grd_files_debug_sources = [
   "front_end/ui/components/text_editor/theme.js",
   "front_end/ui/components/text_prompt/TextPrompt.js",
   "front_end/ui/components/text_prompt/textPrompt.css.js",
+  "front_end/ui/components/tooltips/Tooltip.js",
+  "front_end/ui/components/tooltips/tooltip.css.js",
   "front_end/ui/components/tree_outline/TreeOutline.js",
   "front_end/ui/components/tree_outline/TreeOutlineUtils.js",
   "front_end/ui/components/tree_outline/treeOutline.css.js",

front_end/BUILD.gn

@@ -249,7 +249,7 @@ group("unittests") {
     "ui/components/switch:unittests",
     "ui/components/text_editor:unittests",
     "ui/components/text_prompt:unittests",
-    "ui/components/tooltip:unittests",
+    "ui/components/tooltips:unittests",
     "ui/components/tree_outline:unittests",
     "ui/legacy:copy_stylesheets_for_server",
     "ui/legacy:unittests",

front_end/panels/elements/BUILD.gn

@@ -93,6 +93,7 @@ devtools_module("elements") {
     "../../ui/components/floating_button:bundle",
     "../../ui/components/highlighting:bundle",
     "../../ui/components/text_editor:bundle",
+    "../../ui/components/tooltips:bundle",
     "../../ui/components/tree_outline:bundle",
     "../../ui/legacy:bundle",
     "../../ui/legacy/components/color_picker:bundle",

front_end/ui/components/docs/tooltip/BUILD.gn

@@ -12,7 +12,7 @@ ts_library("ts") {
   deps = [
     "../../../../testing",
     "../../../lit:bundle",
-    "../../tooltip:bundle",
+    "../../tooltips:bundle",
   ]
 }
 

front_end/ui/components/docs/tooltip/basic.ts

@@ -5,7 +5,7 @@
 import * as FrontendHelpers from '../../../../testing/EnvironmentHelpers.js';
 import * as Lit from '../../../lit/lit.js';
 import * as ComponentHelpers from '../../helpers/helpers.js';
-import {Tooltip} from '../../tooltip/Tooltip.js';
+import {Tooltip} from '../../tooltips/Tooltip.js';
 
 const {html} = Lit;
 

front_end/ui/components/tooltip/BUILD.gn renamed to front_end/ui/components/tooltips/BUILD.gn

@@ -15,7 +15,10 @@ generate_css("css_files") {
 devtools_module("tooltip") {
   sources = [ "Tooltip.ts" ]
 
-  deps = [ "../../lit:bundle" ]
+  deps = [
+    "../../../ui/visual_logging:bundle",
+    "../../lit:bundle",
+  ]
 }
 
 devtools_entrypoint("bundle") {

front_end/ui/components/tooltip/Tooltip.test.ts renamed to front_end/ui/components/tooltips/Tooltip.test.ts

@@ -6,19 +6,12 @@ import {renderElementIntoDOM} from '../../../testing/DOMHelpers.js';
 import {checkForPendingActivity} from '../../../testing/TrackAsyncOperations.js';
 import * as Lit from '../../lit/lit.js';
 
-import * as TooltipModule from './Tooltip.js';
-import type {TooltipVariant} from './Tooltip.js';
+import * as Tooltips from './tooltips.js';
 
-const {
-  closestAnchor,
-  Tooltip,
-} = TooltipModule;
-
-const {html, Directives} = Lit;
-const {ref, createRef} = Directives;
+const {html} = Lit;
 
 interface RenderProps {
-  variant?: TooltipVariant;
+  variant?: Tooltips.Tooltip.TooltipVariant;
   attribute?: 'aria-describedby'|'aria-details';
   useClick?: boolean;
 }
@@ -69,6 +62,38 @@ describe('Tooltip', () => {
     assert.isTrue(container.querySelector('devtools-tooltip')?.open);
   });
 
+  it('should be activated if focused', async () => {
+    const container = renderTooltip();
+
+    const button = container.querySelector('button');
+    button?.dispatchEvent(new FocusEvent('focus'));
+
+    await checkForPendingActivity();
+    assert.isTrue(container.querySelector('devtools-tooltip')?.open);
+  });
+
+  it('should not be activated if un-hovered', async () => {
+    const container = renderTooltip();
+
+    const button = container.querySelector('button');
+    button?.dispatchEvent(new MouseEvent('mouseenter'));
+    button?.dispatchEvent(new MouseEvent('mouseleave'));
+
+    await checkForPendingActivity();
+    assert.isFalse(container.querySelector('devtools-tooltip')?.open);
+  });
+
+  it('should not be activated if un-focused', async () => {
+    const container = renderTooltip();
+
+    const button = container.querySelector('button');
+    button?.dispatchEvent(new FocusEvent('focus'));
+    button?.dispatchEvent(new FocusEvent('blur'));
+
+    await checkForPendingActivity();
+    assert.isFalse(container.querySelector('devtools-tooltip')?.open);
+  });
+
   it('should not open on hover if use-click is set', async () => {
     const container = renderTooltip({useClick: true});
 
@@ -79,6 +104,16 @@ describe('Tooltip', () => {
     assert.isFalse(container.querySelector('devtools-tooltip')?.open);
   });
 
+  it('should not open on focus if use-click is set', async () => {
+    const container = renderTooltip({useClick: true});
+
+    const button = container.querySelector('button');
+    button?.dispatchEvent(new FocusEvent('focus'));
+
+    await checkForPendingActivity();
+    assert.isFalse(container.querySelector('devtools-tooltip')?.open);
+  });
+
   it('should open with click if use-click is set', () => {
     const container = renderTooltip({useClick: true});
 
@@ -113,13 +148,14 @@ describe('Tooltip', () => {
   it('can be instantiated programatically', () => {
     const container = document.createElement('div');
     const anchor = document.createElement('button');
-    const tooltip = new Tooltip({id: 'tooltip-id', anchor});
+    anchor.setAttribute('aria-describedby', 'tooltip-id');
+    const tooltip = new Tooltips.Tooltip.Tooltip({id: 'tooltip-id', anchor});
     tooltip.append('Text content');
     container.appendChild(anchor);
     container.appendChild(tooltip);
     renderElementIntoDOM(container);
 
-    assert.strictEqual(anchor.style.anchorName, '--tooltip-id-anchor');
+    assert.strictEqual(anchor.style.anchorName, '--devtools-tooltip-tooltip-id-anchor');
   });
 
   it('should hide the tooltip if anchor is removed from DOM', async () => {
@@ -134,81 +170,3 @@ describe('Tooltip', () => {
     assert.isFalse(container.querySelector('devtools-tooltip')?.open);
   });
 });
-
-describe('closestAnchor', () => {
-  function renderTemplate(template: Lit.TemplateResult) {
-    const container = document.createElement('div');
-    Lit.render(template, container);
-    renderElementIntoDOM(container);
-  }
-
-  it('finds a previous sibling anchor', () => {
-    const origin = createRef();
-    const expectedAchnor = createRef();
-    // clang-format off
-    renderTemplate(html`
-      <div class="anchor" ${ref(expectedAchnor)}></div>
-      <div ${ref(origin)}></div>
-    `);
-    // clang-format on
-
-    const actual = closestAnchor(origin.value!, '.anchor');
-
-    assert.strictEqual(actual, expectedAchnor.value);
-  });
-
-  it('finds a parent', () => {
-    const origin = createRef();
-    const expectedAchnor = createRef();
-    // clang-format off
-    renderTemplate(html`
-      <div class="anchor" ${ref(expectedAchnor)}>
-        <div ${ref(origin)}></div>
-      </div>
-    `);
-    // clang-format on
-
-    const actual = closestAnchor(origin.value!, '.anchor');
-
-    assert.strictEqual(actual, expectedAchnor.value);
-  });
-
-  it('finds an ancestors decendant', () => {
-    const origin = createRef();
-    const expectedAchnor = createRef();
-    // clang-format off
-    renderTemplate(html`
-      <div>
-        <div>
-          <div class="anchor" ${ref(expectedAchnor)}></div>
-        </div>
-        <div>
-          <div ${ref(origin)}></div>
-        </div>
-      </div>
-    `);
-    // clang-format on
-
-    const actual = closestAnchor(origin.value!, '.anchor');
-
-    assert.strictEqual(actual, expectedAchnor.value);
-  });
-
-  it('takes the next anchor up the tree', () => {
-    const origin = createRef();
-    const expectedAchnor = createRef();
-    // clang-format off
-    renderTemplate(html`
-      <div class="anchor a"></div>
-      <div class="anchor b"></div>
-      <div class="anchor c" ${ref(expectedAchnor)}></div>
-      <div ${ref(origin)}></div>
-      <div class="anchor d"></div>
-    `);
-    // clang-format on
-
-    const actual = closestAnchor(origin.value!, '.anchor');
-
-    assert.strictEqual(actual, expectedAchnor.value);
-  });
-});

front_end/ui/components/tooltip/Tooltip.ts renamed to front_end/ui/components/tooltips/Tooltip.ts

@@ -11,7 +11,7 @@ const {html} = Lit;
 export type TooltipVariant = 'simple'|'rich';
 
 export interface TooltipProperties {
-  id?: string;
+  id: string;
   variant?: TooltipVariant;
   anchor?: HTMLElement;
 }
@@ -65,15 +65,21 @@ export class Tooltip extends HTMLElement {
     this.setAttribute('variant', variant);
   }
 
-  constructor({id, variant, anchor}: TooltipProperties = {}) {
+  constructor(properties?: TooltipProperties) {
     super();
-    if (id) {
-      this.id = id;
+    if (properties) {
+      this.id = properties.id;
     }
-    if (variant) {
-      this.variant = variant;
+    if (properties?.variant) {
+      this.variant = properties.variant;
+    }
+    if (properties?.anchor) {
+      const ref = properties.anchor.getAttribute('aria-details') ?? properties.anchor.getAttribute('aria-describedby');
+      if (ref !== properties.id) {
+        throw new Error('aria-details or aria-describedby must be set on the anchor');
+      }
+      this.#anchor = properties.anchor;
     }
-    this.#anchor = anchor ?? null;
   }
 
   attributeChangedCallback(name: string): void {
@@ -117,7 +123,7 @@ export class Tooltip extends HTMLElement {
     }, this.hoverDelay);
   };
 
-  hideTooltip = (event: MouseEvent): void => {
+  hideTooltip = (event: MouseEvent|FocusEvent): void => {
     if (this.#timeout) {
       window.clearTimeout(this.#timeout);
     }
@@ -167,6 +173,8 @@ export class Tooltip extends HTMLElement {
         this.#anchor.addEventListener('click', this.toggle);
       } else {
         this.#anchor.addEventListener('mouseenter', this.showTooltip);
+        this.#anchor.addEventListener('focus', this.showTooltip);
+        this.#anchor.addEventListener('blur', this.hideTooltip);
         this.#anchor.addEventListener('mouseleave', this.hideTooltip);
         this.addEventListener('mouseleave', this.hideTooltip);
       }
@@ -179,9 +187,14 @@ export class Tooltip extends HTMLElement {
   }
 
   #removeEventListeners(): void {
+    if (this.#timeout) {
+      window.clearTimeout(this.#timeout);
+    }
     if (this.#anchor) {
       this.#anchor.removeEventListener('click', this.toggle);
       this.#anchor.removeEventListener('mouseenter', this.showTooltip);
+      this.#anchor.removeEventListener('focus', this.showTooltip);
+      this.#anchor.removeEventListener('blur', this.hideTooltip);
       this.#anchor.removeEventListener('mouseleave', this.hideTooltip);
     }
     this.removeEventListener('mouseleave', this.hideTooltip);
@@ -192,29 +205,35 @@ export class Tooltip extends HTMLElement {
   }
 
   #attachToAnchor(): void {
-    const id = this.getAttribute('id');
-    if (!id) {
-      throw new Error('<devtools-tooltip> must have an id.');
-    }
-    const describedbyAnchor = closestAnchor(this, `[aria-describedby="${id}"]`);
-    const detailsAnchor = closestAnchor(this, `[aria-details="${id}"]`);
-    const anchor = this.#anchor ?? describedbyAnchor ?? detailsAnchor;
-    if (!anchor) {
-      throw new Error(`No anchor for tooltip with id ${id} found.`);
-    }
-    if (!(anchor instanceof HTMLElement)) {
-      throw new Error('Anchor must be an HTMLElement.');
-    }
-    if (this.variant === 'rich' && describedbyAnchor) {
-      console.warn(`The anchor for tooltip ${
-          id} was defined with "aria-describedby". For rich tooltips "aria-details" is more appropriate.`);
+    if (!this.#anchor) {
+      const id = this.getAttribute('id');
+      if (!id) {
+        throw new Error('<devtools-tooltip> must have an id.');
+      }
+      const root = this.getRootNode() as Document | ShadowRoot;
+      if (root.querySelectorAll(`#${id}`)?.length > 1) {
+        throw new Error('Duplicate <devtools-tooltip> ids found.');
+      }
+      const describedbyAnchor = root.querySelector(`[aria-describedby="${id}"]`);
+      const detailsAnchor = root.querySelector(`[aria-details="${id}"]`);
+      const anchor = describedbyAnchor ?? detailsAnchor;
+      if (!anchor) {
+        throw new Error(`No anchor for tooltip with id ${id} found.`);
+      }
+      if (!(anchor instanceof HTMLElement)) {
+        throw new Error('Anchor must be an HTMLElement.');
+      }
+      this.#anchor = anchor;
+      if (this.variant === 'rich' && describedbyAnchor) {
+        console.warn(`The anchor for tooltip ${
+            id} was defined with "aria-describedby". For rich tooltips "aria-details" is more appropriate.`);
+      }
     }
 
-    const anchorName = `--${id}-anchor`;
-    anchor.style.anchorName = anchorName;
+    const anchorName = `--devtools-tooltip-${this.id}-anchor`;
+    this.#anchor.style.anchorName = anchorName;
     this.style.positionAnchor = anchorName;
-    this.#observeAnchorRemoval(anchor);
-    this.#anchor = anchor;
+    this.#observeAnchorRemoval(this.#anchor);
   }
 
   #observeAnchorRemoval(anchor: Element): void {
@@ -239,15 +258,6 @@ export class Tooltip extends HTMLElement {
   }
 }
 
-export function closestAnchor(tooltip: Element, selector: string): Element|null {
-  const anchors: NodeListOf<Element>|undefined = (tooltip.getRootNode() as Element)?.querySelectorAll(selector);
-  // Find the last anchor with a matching selector that is before the tooltip in the document order.
-  const anchor = [...anchors ?? []]
-                     .filter(anchor => tooltip.compareDocumentPosition(anchor) & Node.DOCUMENT_POSITION_PRECEDING)
-                     .at(-1);
-  return anchor ?? null;
-}
-
 customElements.define('devtools-tooltip', Tooltip);
 
 declare global {