TooltipManager

The instance of the balloon panel that renders and positions the tooltip.

The view rendering text of the tooltip.

Maps each DOM tree (the document or a shadow root) that hosts tooltip-bearing UI to the body collection the shared tooltip balloon should be pinned into for targets in that tree. Rebuilt from _registrations by _rebuild.

Stores the reference to the DOM element the tooltip is attached to. null when there's no tooltip in the UI.

Stores the current tooltip position. null when there's no tooltip in the UI.

An instance of the mutation observer that keeps track on target element attributes changes.

A debounced version of _pinTooltip. Tooltips show with a delay to avoid flashing and to improve the UX.

The number of holders (editors and features) currently using the singleton, so it is destroyed only when the last one releases it.

Shadow roots the manager currently has listeners attached to.

A debounced version of _unpinTooltip. Tooltips hide with a delay to allow hovering of their titles.

A set of default positioning functions used by the TooltipManager to pin tooltips in different positions.

A reference to the TooltipManager instance. The class is a singleton and as such, successive attempts at creating instances should return this instance.

The body collections the shared tooltip balloon may be pinned into, each with the sources describing where its tooltip-bearing UI lives: an optional ShadowRootRegistry (the shadow roots its out-of-collection UI occupies) and an optional emitter whose update event should reposition a pinned tooltip.

Creates an instance of the tooltip manager. Private – use for to obtain the shared singleton.

Parameters

locale: Locale

Delegates selected events to another Emitter. For instance:

emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );

then eventX is delegated (fired by) emitterB and emitterC along with data:

emitterA.fire( 'eventX', data );

and eventY is delegated (fired by) emitterC along with data:

emitterA.fire( 'eventY', data );

Parameters

events: Array<string>

Event names that will be delegated to another emitter.

Returns

EmitterMixinDelegateChain

Fires an event, executing all callbacks registered for it.

The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

Type parameters

TEvent: extends BaseEvent

The type describing the event. See BaseEvent.

Parameters

eventOrInfo: GetNameOrEventInfo<TEvent>

The name of the event or EventInfo object if event is delegated.

args: TEvent[ 'args' ]

Additional arguments to be passed to the callbacks.

Returns

GetEventInfo<TEvent>[ 'return' ]

By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).

Registers a callback function to be executed when an event is fired in a specific (emitter) object.

Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.

// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );

An event callback can stop the event and set the return value of the fire method.

Type parameters

TEvent: extends BaseEvent

The type describing the event. See BaseEvent.

Parameters

emitter: Emitter

The object that fires the event.

event: TEvent[ 'name' ]

The name of the event.

callback: GetCallback<TEvent>

The function to be called on event.

options?: CallbackOptions

Additional options.

Returns

void

Registers a callback function to be executed when an event is fired in a specific (emitter) object.

Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.

// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );

An event callback can stop the event and set the return value of the fire method.

Type parameters

TEvent: extends BaseEvent

The type describing the event. See BaseEvent.

Parameters

emitter: Emitter

The object that fires the event.

event: TEvent[ 'name' ]

The name of the event.

callback: GetCallback<TEvent>

The function to be called on event.

options?: GetCallbackOptions<TEvent>

Additional options.

Returns

void

Registers a callback function to be executed when an event is fired in a specific Emitter or DOM Node. It is backwards compatible with listenTo.

Type parameters

K: extends keyof DomEventMap

Parameters

emitter: Window | EventTarget | Node

The object that fires the event.

event: K

The name of the event.

callback: ( this: this, ev: EventInfo, event: DomEventMap[ K ] ) => void

The function to be called on event.

options?: CallbackOptions & object

Additional options.

Returns

void

Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

Parameters

event: string

The name of the event.

callback: Function

The function to stop being called.

Returns

void

Registers a callback function to be executed when an event is fired.

Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

Type parameters

TEvent: extends BaseEvent

The type descibing the event. See BaseEvent.

Parameters

event: TEvent[ 'name' ]

The name of the event.

callback: GetCallback<TEvent>

The function to be called on event.

options?: GetCallbackOptions<TEvent>

Additional options.

Returns

void

Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

Type parameters

TEvent: extends BaseEvent

The type descibing the event. See BaseEvent.

Parameters

event: TEvent[ 'name' ]

The name of the event.

callback: GetCallback<TEvent>

The function to be called on event.

options?: GetCallbackOptions<TEvent>

Additional options.

Returns

void

Registers a body collection the shared tooltip balloon may be pinned into, so that a tooltip triggered inside its DOM tree is hosted there instead of an unrelated one – keeping it in the same shadow tree, not clipped by or mis-styled across a boundary. Editors register their own body collection; features that render floating UI in their own body collection register it too, which is what lets them display tooltips without an editor.

Parameters

bodyCollection: BodyCollection

The body collection to register.

options: BodyCollectionRegistration

Additional sources describing where this collection's tooltip-bearing UI lives.

Defaults to {}

Returns

void

Marks one holder as done with the singleton (see for). When the last holder releases it, the singleton unpins the tooltip, destroys the shared balloon and drops every listener.

Returns

void

Stops delegating events. It can be used at different levels:

• To stop delegating all events.
• To stop delegating a specific event to all emitters.
• To stop delegating a specific event to a specific emitter.

Parameters

event?: string

The name of the event to stop delegating. If omitted, stops it all delegations.

emitter?: Emitter

(requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.

Returns

void

Stops listening for events. It can be used at different levels:

• To stop listening to a specific callback.
• To stop listening to a specific event.
• To stop listening to all events fired by a specific object.
• To stop listening to all events fired by all objects.

Parameters

emitter?: Emitter

The object to stop listening to. If omitted, stops it for all objects.

event?: string

(Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

callback?: Function

(Requires the event) The function to be removed from the call list for the given event.

Returns

void

Stops listening for events. It can be used at different levels: It is backwards compatible with listenTo.

• To stop listening to a specific callback.
• To stop listening to a specific event.
• To stop listening to all events fired by a specific object.
• To stop listening to all events fired by all objects.

Parameters

emitter?: Window | EventTarget | Node | Emitter

The object to stop listening to. If omitted, stops it for all objects.

event?: string

(Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

callback?: Function

(Requires the event) The function to be removed from the call list for the given event.

Returns

void

Reverts registerBodyCollection: stops hosting the shared balloon in the given collection and drops the listeners set up for it. Pulls the shared balloon out first, so it never dangles in a collection that is going away.

Parameters

bodyCollection: BodyCollection

The body collection to unregister.

Returns

void

Returns the body collection the shared tooltip balloon should be pinned into. The balloon is a singleton, but each registered body collection can live in a different DOM tree (a shadow root, or a configured ui.overlayContainer). To keep the tooltip in the tree of the hovered element — so it is styled by that tree's sheets and not clipped by another root — the tree is looked up in _bodyCollectionByTree, which maps every tree hosting tooltip-bearing UI (a collection's own mount tree, and an editor's editable, toolbar or menu bar trees) to the collection that should host it.

A body collection is mounted lazily and unmounted when its host leaves the document, and a configured ui.overlayContainer may be detached — a body in either state would render the balloon outside the document and hide tooltips, so the mount target must be connected, not merely set. When no connected body collection hosts the hovered element's tree, it falls back to the first connected registrant, then to the first registered one, and to null when nothing is registered at all.

Parameters

targetDomElement: HTMLElement

The element the tooltip is being pinned to.

Returns

BodyCollection | null

Returns the distinct update emitters of all registered body collections.

Deduplicated, because an emitter can be shared by several registrations (an editor and a feature hosting its own overlay layer both follow the editor's UI update) while listeners are attached per emitter, not per registration – listening once per registration would reposition a pinned tooltip several times per update.

Returns

Set<Emitter>

Moves the shared tooltip balloon into the body collection returned by _getConnectedBodyCollection, first removing it from any registered body collection that previously hosted it. The balloon is a singleton shared by every registrant, so it must belong to exactly one collection at a time; otherwise unregistering one collection would detach the shared element while another registrant still references it.

Parameters

targetDomElement: HTMLElement

The element the tooltip is being pinned to, used to prefer the body collection that hosts its DOM tree.

Returns

boolean

true if a host body collection was found (and the balloon moved into it), false when none is registered and the tooltip therefore cannot be shown.

Handles displaying tooltips on mouseenter and focus in DOM.

Parameters

evt: EventInfo

An object containing information about the fired event.

domEvent: any

The DOM event.

Returns

void

Handles hiding tooltips on keydown in DOM.

Parameters

evt: EventInfo

An object containing information about the fired event.

domEvent: KeyboardEvent

The DOM event.

Returns

void

Handles hiding tooltips on mouseleave and blur in DOM.

Parameters

evt: EventInfo

An object containing information about the fired event.

domEvent: any

The DOM event.

Returns

void

Handles hiding tooltips on scroll in DOM.

Parameters

evt: unknown

An object containing information about the fired event.

domEvent: any

The DOM event.

Returns

void

Pins the tooltip to a specific DOM element.

Parameters

targetDomElement: HTMLElement

Element to be pinned to.

options: TooltipData

Options for the tooltip.

Returns

void

Rebuilds _bodyCollectionByTree from _registrations: every registered collection claims the DOM tree it is mounted in, and – for editors – every shadow root its registry reports (ancestor-inclusive, so nested and decoupled trees resolve too). Then re-syncs the per-shadow-root listeners.

Returns

void

Attaches or detaches listeners on shadow roots so they match the shadow roots that host tooltip-bearing UI exactly, i.e. the shadow-root keys of _bodyCollectionByTree.

The listeners duplicate the ones on document for two different reasons:

• mouseenter, mouseleave and scroll are not composed, so their event path ends at the shadow root they originated in and the document listeners never see them at all. Here the per-root listener is what delivers the event.
• focus and blur are composed, so the capturing document listeners do see them (the capture phase walks the whole composed path even though these events do not bubble) — but with target retargeted to the shadow host, which is useless for getDescendantWithTooltip(). Here the per-root listener is what provides the real target. It cannot be replaced by reading composedPath()[0] on document, because that path is truncated at the boundary of a closed root.

Since the capture phase runs outwards-in, the document listener fires before these; see the isShadowHostOf() guards in _onEnterOrFocus and _onLeaveOrBlur, which make the outer listeners step aside for the innermost one.

Returns

void

Unpins the tooltip and cancels all queued pinning.

Returns

void

Updates the position of the tooltip so it stays in sync with the element it is pinned to.

Hides the tooltip when the element is no longer visible in DOM or the tooltip text was removed.

Returns

void

Returns the shared TooltipManager singleton, creating it – with the given locale – on first use, and marks one more holder as using it. Every caller must later release it, so the singleton is destroyed once the last holder is gone.

Editors and features obtain the manager this way and then register the body collection their tooltip-bearing UI renders into. A feature therefore does not need an editor reference to display tooltips – it attaches to the same singleton directly.

Parameters

locale: Locale

The locale used to create the tooltip views on first use.

Returns

TooltipManager

Returns balloonPanelView positioning functions for a given position name.

Parameters

position: TooltipPosition

Name of the position (s, se, sw, n, e, or w).

Returns

Array<PositioningFunction>

Positioning functions to be used by the balloonPanelView.