utils/dom/whenelementconnected

Calls the callback once the given element is connected to a document, and at most once.

For code that has to act on the tree an element lives in – injecting styles, resolving a mount target – but is handed the element before it is mounted. The editable of a DecoupledEditor, or of any editor created from a data string, is put in the DOM by the integrator at an arbitrary point in time. An element that is already connected is reported synchronously, so the caller needs no second path for that case.

"Connected" means connected to a document: an element in a shadow tree qualifies once that tree's host does, and one in a detached tree never does. It is not a visibility check – the element may be connected while having no box of its own, or while an ancestor is not rendered.

The waiting is backed by a ResizeObserver, so the notification is asynchronous and arrives once the element is rendered. For an element mounted into a display: none subtree the callback may therefore run on the mount or only once that subtree is shown, depending on the engine. It runs exactly once either way.

Parameters

element: HTMLElement

The element to wait for.

callback: () => void

Called once element is connected, or immediately if it already is.

Returns

() => void

Cancels the waiting. Safe to call any number of times, and does nothing once the callback has run.