Verify DOM element attachment during editor creation

[niegowski]

Problem

When ClassicEditor.create() is called with a DOM element that is not attached to the document (i.e., has no parentNode), the editor crashes with a cryptic, unhelpful error:

  TypeError: Cannot read properties of null (reading 'insertBefore')
      at ElementReplacer.replace (elementreplacer.ts:38:1)
      at ClassicEditorUI.init (classiceditorui.ts:114:1)
      at classiceditor.ts:310:1

This happens because ElementReplacer.replace() (ckeditor5-utils/src/elementreplacer.ts:38) calls element.parentNode!.insertBefore(...) with a non-null assertion, but parentNode is null when the element is detached from the DOM tree.

This is a common integrator mistake — for example, calling ClassicEditor.create() before the element is rendered into the DOM, or passing an element that has been removed.

Expected behavior

The editor should detect a detached element early and throw a clear CKEditorError with a descriptive error code, similar to the existing editor-source-element-already-used check in secureSourceElement() (ckeditor5-core/src/editor/utils/securesourceelement.ts).

Scope

• ClassicEditor — directly affected (uses ElementReplacer which calls parentNode.insertBefore)
• InlineEditor, BalloonEditor, DecoupledEditor, MultiRootEditor — not affected by the ElementReplacer crash (they don't use it), but they would still benefit from an early validation

Consider using a warning instead of error to avoid breaking exotic integrations.

Reproduction

// Element not in DOM
const div = document.createElement( 'div' );
ClassicEditor.create( div ); // TypeError: Cannot read properties of null (reading 'insertBefore')

// Element removed before editor creation
const el = document.querySelector( '#editor' );
el.remove();
ClassicEditor.create( el ); // Same error

[Mati365]

I checked whether it’s possible to initialize the InlineEditor and BalloonEditor in the background (on a detached element). The BalloonEditor and InlineEditor start up without any issues, and once added to the DOM tree, they start working immediately (even without needing to call editor.ui.update()).

In manual tests (with CK_DEBUG enabled by default), InlineEditor can report a warning when sizing the toolbar width https://github.com/ckeditor/ckeditor5/blob/ck/20017/packages/ckeditor5-editor-inline/src/inlineeditoruiview.ts#L197-L205; however, I haven’t observed any issues with it, and it shouldn’t log a warning in the production version.

As we agreed at the meeting - for now, only the first scenario (with ClassicEditor) needs to be changed. For the rest of the editors, I would treat this as a feature (it could be useful for preloading when loading heavier editor configurations, etc.).