Sign up (with export icon)

utils/dom/shadowrootregistry

Api-module iconmodule

Classes

Type Definitions

Functions

  • Chevron-right icon

    listenToEventRoots( registry, options ) → () => void

    Attaches emitter's callback to the global document and to every event root tracked by registry, and keeps that up to date – attaching to roots that appear later, detaching from roots that disappear – for as long as the returned function is not called.

    It replaces a pair of a document listener and listenToShadowRoots:

    const stopListening = listenToEventRoots( editor.ui.shadowRootRegistry, {
    	emitter: view,
    	event: 'scroll',
    	listenerOptions: { useCapture: true },
    	callback: repositionOnScroll
    } );
    Copy code

    The global document is always listened to, even if no registered node lives in it, so the callback receives the same events as a listener on document would, plus the events of the other event roots. Each root is listened to once, no matter how many registered nodes it hosts.

    As with listenToShadowRoots, use useCapture: true for events that do not bubble, such as scroll.

    Call the returned function to detach. There is nothing to refresh, as the listener follows the registry on its own.

    Type parameters

    TEvent: extends keyof DomEventMap

    Parameters

    registry: ShadowRootRegistry

    The registry whose event roots should be listened to.

    options: DomTargetsListenerOptions<TEvent>

    Describes the listener to attach to each event root.

    Returns

    () => void
  • Chevron-right icon

    listenToShadowRoots( registry, options ) → () => void

    Some DOM events never reach a listener on document if they originate inside a shadow root — scroll and mouseenter/mouseleave, for instance, do not cross a shadow boundary at all. This function is how code that needs those events anyway reacts to them for every shadow root a registry is currently tracking: it attaches emitter's callback directly to each one tracked by registry, and keeps that up to date — attaching to roots that appear later, detaching from roots that disappear — for as long as the returned function is not called.

    Attach it alongside the document listener rather than instead of it — one covers the light DOM, the other each shadow root:

    view.listenTo( global.document, 'scroll', repositionOnScroll, { useCapture: true } );
    
    const stopListening = listenToShadowRoots( editor.ui.shadowRootRegistry, {
    	emitter: view,
    	event: 'scroll',
    	listenerOptions: { useCapture: true },
    	callback: repositionOnScroll
    } );
    Copy code

    To cover both with a single call, use listenToEventRoots instead.

    The useCapture above is not incidental. The events this function exists for do not bubble when fired on an element, so a listener on a shadow root only sees one that originates inside that root during the capture phase. Without it the listener is attached but never fires.

    Call the returned function to detach. There is nothing to refresh, as the listener follows the registry on its own.

    Type parameters

    TEvent: extends keyof DomEventMap

    Parameters

    registry: ShadowRootRegistry

    The registry whose shadow roots should be listened to.

    options: DomTargetsListenerOptions<TEvent>

    Describes the listener to attach to each shadow root.

    Returns

    () => void