feat(widgets) Styled tooltips

ibgreen · ibgreen · commit a8d7aa2f278c · 2026-07-03T10:00:10.000-04:00
diff --git a/modules/core/src/lib/widget-manager.ts b/modules/core/src/lib/widget-manager.ts
@@ -212,7 +212,7 @@ export class WidgetManager {
 
   /** Destroy an old widget */
   private _removeWidget(widget: Widget) {
-    widget.onRemove?.();
+    widget._onRemove();
 
     if (widget.rootElement) {
       widget.rootElement.remove();
diff --git a/modules/core/src/lib/widget-tooltip.ts b/modules/core/src/lib/widget-tooltip.ts
@@ -0,0 +1,184 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+const TOOLTIP_ATTR = 'data-deck-widget-tooltip';
+const GENERATED_ATTR = 'data-deck-widget-tooltip-generated';
+const OFFSET = 8;
+
+export class WidgetTooltip {
+  private anchor: HTMLElement | null = null;
+  private element: HTMLDivElement | null = null;
+  private listenerRoot: HTMLElement | null = null;
+  private prepared = false;
+
+  prepare(root: HTMLElement | null | undefined): void {
+    this.hide();
+    this.prepared = Boolean(root);
+    if (!root) return;
+
+    // Preact does not reapply unchanged title props after they are removed below.
+    for (const target of root.querySelectorAll<HTMLElement>(`[${GENERATED_ATTR}]`)) {
+      const tooltip = target.getAttribute(TOOLTIP_ATTR);
+      if (tooltip) target.setAttribute('title', tooltip);
+    }
+  }
+
+  update(root: HTMLElement | null | undefined, shortcut?: string | HTMLElement): void {
+    this.hide();
+    if (!root) return;
+
+    this.addListeners(root);
+    this.syncTargets(root, this.prepared);
+    this.prepared = false;
+    this.shortcut = shortcut;
+  }
+
+  remove(): void {
+    this.hide();
+    this.removeListeners();
+  }
+
+  private shortcut?: string | HTMLElement;
+
+  private hide(): void {
+    this.element?.remove();
+    this.element = null;
+    this.anchor = null;
+  }
+
+  private addListeners(root: HTMLElement): void {
+    if (this.listenerRoot === root) return;
+
+    this.removeListeners();
+    this.listenerRoot = root;
+    root.addEventListener('pointerover', this.onPointerOver);
+    root.addEventListener('pointerout', this.onPointerOut);
+    root.addEventListener('focusin', this.onFocusIn);
+    root.addEventListener('focusout', this.onFocusOut);
+    root.addEventListener('keydown', this.onKeyDown);
+  }
+
+  private removeListeners(): void {
+    if (!this.listenerRoot) return;
+
+    this.listenerRoot.removeEventListener('pointerover', this.onPointerOver);
+    this.listenerRoot.removeEventListener('pointerout', this.onPointerOut);
+    this.listenerRoot.removeEventListener('focusin', this.onFocusIn);
+    this.listenerRoot.removeEventListener('focusout', this.onFocusOut);
+    this.listenerRoot.removeEventListener('keydown', this.onKeyDown);
+    this.listenerRoot = null;
+  }
+
+  private syncTargets(root: HTMLElement, prepared: boolean): void {
+    if (prepared) {
+      for (const target of root.querySelectorAll<HTMLElement>(`[${GENERATED_ATTR}]:not([title])`)) {
+        this.clearGeneratedTarget(target);
+      }
+    }
+
+    for (const target of root.querySelectorAll<HTMLElement>('[title]')) {
+      const title = target.getAttribute('title');
+      const wasGenerated = target.hasAttribute(GENERATED_ATTR);
+      if (title) {
+        target.setAttribute(TOOLTIP_ATTR, title);
+        target.setAttribute(GENERATED_ATTR, '');
+        if (!target.hasAttribute('aria-label') || wasGenerated) {
+          target.setAttribute('aria-label', title);
+        }
+      } else if (wasGenerated) {
+        this.clearGeneratedTarget(target);
+      }
+      target.removeAttribute('title');
+    }
+  }
+
+  private clearGeneratedTarget(target: HTMLElement): void {
+    const tooltip = target.getAttribute(TOOLTIP_ATTR);
+    if (target.getAttribute('aria-label') === tooltip) target.removeAttribute('aria-label');
+    target.removeAttribute(TOOLTIP_ATTR);
+    target.removeAttribute(GENERATED_ATTR);
+  }
+
+  private onPointerOver = (event: PointerEvent): void => {
+    const target = this.getTarget(event.target);
+    if (target) this.show(target);
+  };
+
+  private onPointerOut = (event: PointerEvent): void => {
+    if (
+      this.anchor &&
+      !(event.relatedTarget instanceof Node && this.anchor.contains(event.relatedTarget))
+    ) {
+      this.hide();
+    }
+  };
+
+  private onFocusIn = (event: FocusEvent): void => {
+    const target = this.getTarget(event.target);
+    if (target?.matches(':focus-visible')) this.show(target);
+  };
+
+  private onFocusOut = (): void => this.hide();
+
+  private onKeyDown = (event: KeyboardEvent): void => {
+    if (event.key === 'Escape') this.hide();
+  };
+
+  private getTarget(target: EventTarget | null): HTMLElement | null {
+    const anchor = target instanceof Element ? target.closest(`[${TOOLTIP_ATTR}]`) : null;
+    return anchor instanceof HTMLElement ? anchor : null;
+  }
+
+  private show(anchor: HTMLElement): void {
+    const text = anchor.getAttribute(TOOLTIP_ATTR);
+    const root = this.listenerRoot;
+    if (!text || !root) return;
+
+    this.hide();
+    this.anchor = anchor;
+
+    const tooltip = document.createElement('div');
+    tooltip.className = 'deck-widget-tooltip';
+    tooltip.setAttribute('role', 'tooltip');
+    tooltip.append(document.createTextNode(text));
+    if (this.shortcut) {
+      tooltip.append(
+        typeof this.shortcut === 'string'
+          ? document.createTextNode(this.shortcut)
+          : this.shortcut.cloneNode(true)
+      );
+    }
+
+    const container = getContainer(root);
+    container.append(tooltip);
+    this.element = tooltip;
+    this.position(anchor, tooltip, container);
+  }
+
+  private position(anchor: HTMLElement, tooltip: HTMLDivElement, container: HTMLElement): void {
+    const anchorRect = anchor.getBoundingClientRect();
+    const containerRect = container.getBoundingClientRect();
+    const tooltipRect = tooltip.getBoundingClientRect();
+    let left = anchorRect.right - containerRect.left + OFFSET;
+    const top = anchorRect.top - containerRect.top + (anchorRect.height - tooltipRect.height) / 2;
+
+    if (left + tooltipRect.width > containerRect.width) {
+      left = anchorRect.left - containerRect.left - tooltipRect.width - OFFSET;
+    }
+    tooltip.style.left = `${clamp(left, 0, containerRect.width - tooltipRect.width)}px`;
+    tooltip.style.top = `${clamp(top, 0, containerRect.height - tooltipRect.height)}px`;
+  }
+}
+
+function getContainer(root: HTMLElement): HTMLElement {
+  const parent = root.parentElement;
+  const grandparent = parent?.parentElement;
+  return grandparent?.parentElement?.classList.contains('deck-widget-container')
+    ? grandparent
+    : parent || root;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), Math.max(min, max));
+}
diff --git a/modules/core/src/lib/widget.ts b/modules/core/src/lib/widget.ts
@@ -11,13 +11,16 @@ import type {WidgetManager, WidgetPlacement} from './widget-manager';
 import type {ViewOrViews} from './view-manager';
 import {deepEqual} from '../utils/deep-equal';
 import {applyStyles, removeStyles} from '../utils/apply-styles';
+import {WidgetTooltip} from './widget-tooltip';
 
 export type WidgetProps = {
   id?: string;
   /** CSS inline style overrides. */
   style?: Partial<CSSStyleDeclaration>;
   /** Additional CSS class. */
   className?: string;
+  /** Keyboard shortcut or other hint rendered after the standard tooltip label. */
+  shortcut?: string | HTMLElement;
   /**
    * The container that this widget is being attached to. Default to `viewId`.
    * If set to `'root'`, the widget is placed relative to the whole deck.gl canvas.
@@ -35,7 +38,8 @@ export abstract class Widget<
     id: 'widget',
     style: {},
     _container: null,
-    className: ''
+    className: '',
+    shortcut: undefined!
   };
 
   /** Unique identifier of the widget. */
@@ -57,6 +61,7 @@ export abstract class Widget<
   widgetManager?: WidgetManager;
   deck?: Deck<ViewsT>;
   rootElement?: HTMLDivElement | null;
+  private _tooltip = new WidgetTooltip();
 
   constructor(props: PropsT) {
     this.props = {
@@ -85,6 +90,7 @@ export abstract class Widget<
       applyStyles(el, props.style);
     }
 
+    this._tooltip.prepare(this.rootElement);
     Object.assign(this.props, props);
 
     // Update the HTML to match the new props
@@ -95,6 +101,7 @@ export abstract class Widget<
   updateHTML(): void {
     if (this.rootElement) {
       this.onRenderHTML(this.rootElement);
+      this._tooltip.update(this.rootElement, this.props.shortcut);
     }
   }
 
@@ -149,6 +156,12 @@ export abstract class Widget<
     return this.onAdd(params) ?? this.onCreateRootElement();
   }
 
+  /** Internal API called by Deck when the widget is removed */
+  _onRemove(): void {
+    this._tooltip.remove();
+    this.onRemove();
+  }
+
   /** Overridable by subclass - called when the widget is first added to a Deck instance
    * @returns an optional UI element that should be appended to the Deck container
    */
diff --git a/modules/widgets/src/scrollbar-widget.tsx b/modules/widgets/src/scrollbar-widget.tsx
@@ -100,7 +100,7 @@ export class ScrollbarWidget extends Widget<ScrollbarWidgetProps> {
 
   override onViewportChange(viewport: Viewport) {
     this.viewport = viewport;
-    this.onRenderHTML();
+    this.updateHTML();
   }
 
   override onRenderHTML(): void {
diff --git a/modules/widgets/src/stylesheet.css b/modules/widgets/src/stylesheet.css
@@ -105,6 +105,39 @@
   z-index: 100;
 }
 
+.deck-widget-tooltip {
+  position: absolute;
+  z-index: 1000;
+  pointer-events: none;
+  box-sizing: border-box;
+  max-width: 240px;
+  padding: 4px 8px;
+  border: var(--menu-border, unset);
+  border-radius: calc(var(--button-corner-radius, 8px) - 2px);
+  box-shadow: var(--menu-shadow, 0px 0px 8px 0px rgba(0, 0, 0, 0.25));
+  background: var(--menu-background, #fff);
+  backdrop-filter: var(--menu-backdrop-filter, unset);
+  color: var(--menu-text, rgb(24, 24, 26));
+  font-size: 12px;
+  line-height: 16px;
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  white-space: normal;
+  overflow-wrap: break-word;
+}
+
+.deck-widget-tooltip kbd {
+  font-family: inherit;
+  font-size: 11px;
+  line-height: 14px;
+  padding: 0 4px;
+  border: var(--button-inner-stroke, 1px solid rgba(0, 0, 0, 0.2));
+  border-radius: 3px;
+  background: var(--button-background, #fff);
+}
+
 /* Fullscreen styles */
 .deck-widget.deck-widget-fullscreen button.deck-widget-fullscreen-enter .deck-widget-icon {
   mask-image: var(
diff --git a/test/modules/widgets/scrollbar-widget.spec.ts b/test/modules/widgets/scrollbar-widget.spec.ts
@@ -184,7 +184,7 @@ test('ScrollbarWidget - decorations', async () => {
   expect(decoration).toBeTruthy();
   expect(decoration.style.left).toBe('20%');
   expect(decoration.style.width).toBe('20%');
-  expect(decorationContent.title).toBe('Highlight');
+  expect(decorationContent.title).toBe('');
   expect(decorationContent.style.backgroundColor).toBe('rgb(255, 255, 0)');
   expect(scrollbar.getAttribute('aria-valuenow')).toBe('200');
 
diff --git a/test/modules/widgets/selector-widget.spec.ts b/test/modules/widgets/selector-widget.spec.ts
@@ -31,7 +31,7 @@ test('SelectorWidget', async () => {
 
   await testInstance.idle();
   let button = testInstance.findElements('.deck-widget-icon-button')[0] as HTMLButtonElement;
-  expect(button.title).toBe('Grid');
+  expect(button.title).toBe('');
 
   testInstance.click('.deck-widget-icon-button');
   await testInstance.idle();
@@ -45,6 +45,6 @@ test('SelectorWidget', async () => {
 
   expect(onChange).toHaveBeenCalledWith('list');
   button = testInstance.findElements('.deck-widget-icon-button')[0] as HTMLButtonElement;
-  expect(button.title).toBe('List');
+  expect(button.title).toBe('');
   expect(testInstance.findElements('.deck-widget-dropdown-item')).toHaveLength(0);
 });
diff --git a/test/modules/widgets/theme-widget.spec.ts b/test/modules/widgets/theme-widget.spec.ts
@@ -69,7 +69,7 @@ test('ThemeWidget - button label and icon reflect current mode', async () => {
   let button = testInstance.findElements(
     '.deck-widget-theme .deck-widget-icon-button'
   )[0] as HTMLButtonElement;
-  expect(button.title).toBe('Dark Mode');
+  expect(button.title).toBe('');
   expect(button.className).toContain('deck-widget-moon');
 
   testInstance.setProps({
@@ -86,7 +86,7 @@ test('ThemeWidget - button label and icon reflect current mode', async () => {
   button = testInstance.findElements(
     '.deck-widget-theme .deck-widget-icon-button'
   )[0] as HTMLButtonElement;
-  expect(button.title).toBe('Light Mode');
+  expect(button.title).toBe('');
   expect(button.className).toContain('deck-widget-sun');
 });
 
diff --git a/test/modules/widgets/toggle-widget.spec.ts b/test/modules/widgets/toggle-widget.spec.ts
@@ -35,13 +35,13 @@ test('ToggleWidget', async () => {
   const icon = testInstance.findElements('.deck-widget-icon')[0] as HTMLDivElement;
 
   expect(root.dataset.checked).toBe('false');
-  expect(button.title).toBe('Toggle off');
+  expect(button.title).toBe('');
   expect(icon.style.backgroundColor).toBe('rgb(255, 0, 0)');
 
   testInstance.click('.deck-widget-icon-button');
 
   expect(onChange).toHaveBeenCalledWith(true);
   expect(root.dataset.checked).toBe('true');
-  expect(button.title).toBe('Toggle on');
+  expect(button.title).toBe('');
   expect(icon.style.backgroundColor).toBe('rgb(0, 255, 0)');
 });
diff --git a/test/modules/widgets/widget-tooltip.spec.ts b/test/modules/widgets/widget-tooltip.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -100,7 +100,7 @@ export class ScrollbarWidget extends Widget<ScrollbarWidgetProps> {`
`100`	`100`
`101`	`101`	`override onViewportChange(viewport: Viewport) {`
`102`	`102`	`this.viewport = viewport;`
`103`		`- this.onRenderHTML();`
	`103`	`+ this.updateHTML();`
`104`	`104`	`}`
`105`	`105`
`106`	`106`	`override onRenderHTML(): void {`