@ckeditor/ckeditor5-heading 48.1.1 → 48.2.0-alpha.0

package/dist/index.js

@@ -4,7 +4,7 @@
  */
 import { Command, Plugin } from '@ckeditor/ckeditor5-core/dist/index.js';
 import { Paragraph } from '@ckeditor/ckeditor5-paragraph/dist/index.js';
-import { first, priorities, Collection } from '@ckeditor/ckeditor5-utils/dist/index.js';
+import { first, priorities, Collection, logWarning } from '@ckeditor/ckeditor5-utils/dist/index.js';
 import { UIModel, createDropdown, addListToDropdown, MenuBarMenuView, MenuBarMenuListView, MenuBarMenuListItemView, MenuBarMenuListItemButtonView, ButtonView } from '@ckeditor/ckeditor5-ui/dist/index.js';
 import { IconHeading6, IconHeading5, IconHeading4, IconHeading3, IconHeading2, IconHeading1 } from '@ckeditor/ckeditor5-icons/dist/index.js';
 import { ViewDowncastWriter, enableViewPlaceholder, hideViewPlaceholder, needsViewPlaceholder, showViewPlaceholder } from '@ckeditor/ckeditor5-engine/dist/index.js';
@@ -523,6 +523,14 @@ const titleLikeElements = new Set([
         // </title>
         //
         // See: https://github.com/ckeditor/ckeditor5/issues/2005.
+        //
+        // Title is scoped to roots whose `modelElement` is the generic `$root`. Custom root
+        // `modelElement` names (including `$inlineRoot`) are intentionally not supported:
+        // the title structure (`title` + `title-content` + paragraph body placeholder) relies on
+        // the root accepting `$block` content, which is not guaranteed for custom or inline roots.
+        // Runtime codepaths below additionally guard on `schema.checkChild( root, 'title' )` so
+        // the plugin gracefully no-ops on roots where the schema does not allow the title element.
+        // eslint-disable-next-line ckeditor5-rules/no-literal-dollar-root -- registered only on the default `$root` by design
         model.schema.register('title', {
             isBlock: true,
             allowIn: '$root'
@@ -578,6 +586,31 @@ const titleLikeElements = new Set([
         this._attachPlaceholders();
         // Attach Tab handling.
         this._attachTabPressHandling();
+        this._warnIfNoSupportedRoot();
+    }
+    /**
+	 * Logs a single warning when none of the editor's roots can host the title structure. The Title feature
+	 * only operates on roots whose `modelElement` is the default `$root`; roots configured with a custom
+	 * `modelElement` are silently skipped at runtime. If no root supports the structure, the plugin is
+	 * effectively a no-op and the integrator likely wants to know.
+	 */ _warnIfNoSupportedRoot() {
+        const model = this.editor.model;
+        for (const root of model.document.getRoots()){
+            if (model.schema.checkChild(root, 'title')) {
+                return;
+            }
+        }
+        /**
+		 * The Title feature was loaded, but none of the editor's roots supports the `title` element. The feature
+		 * only operates on roots whose `modelElement` is the default `$root`; roots configured with a custom
+		 * `modelElement` (including `$inlineRoot`) are silently skipped, so `getTitle()` / `getBody()` fall back
+		 * to the regular data getter and no title structure is ever inserted.
+		 *
+		 * To use the Title feature, ensure at least one root uses the default `$root` model element. Otherwise,
+		 * remove the Title plugin from this editor's plugin list.
+		 *
+		 * @error title-no-supported-root
+		 */ logWarning('title-no-supported-root');
     }
     /**
 	 * Returns the title of the document. Note that because this plugin does not allow any formatting inside
@@ -593,6 +626,10 @@ const titleLikeElements = new Set([
 	 */ getTitle(options = {}) {
         const rootName = options.rootName ? options.rootName : undefined;
         const titleElement = this._getTitleElement(rootName);
+        // Root does not support the title structure (custom/inline root) — nothing to stringify.
+        if (!titleElement) {
+            return '';
+        }
         const titleContentElement = titleElement.getChild(0);
         return this.editor.data.stringify(titleContentElement, options);
     }
@@ -612,12 +649,25 @@ const titleLikeElements = new Set([
         const model = editor.model;
         const rootName = options.rootName ? options.rootName : undefined;
         const root = editor.model.document.getRoot(rootName);
+        // Root does not support the title structure (custom/inline root) — the whole root is the body.
+        // Delegate to the regular data getter so mixed-root callers receive useful content.
+        if (!model.schema.checkChild(root, 'title')) {
+            return data.get({
+                ...options,
+                rootName: root.rootName
+            });
+        }
+        // Root is empty / missing the expected title element (e.g. detached root or transient state) — no body to stringify.
+        const firstChild = root.getChild(0);
+        if (!firstChild || !firstChild.is('element', 'title')) {
+            return '';
+        }
         const view = editor.editing.view;
         const viewWriter = new ViewDowncastWriter(view.document);
         const rootRange = model.createRangeIn(root);
         const viewDocumentFragment = viewWriter.createDocumentFragment();
         // Find all markers that intersects with body.
-        const bodyStartPosition = model.createPositionAfter(root.getChild(0));
+        const bodyStartPosition = model.createPositionAfter(firstChild);
         const bodyRange = model.createRange(bodyStartPosition, model.createPositionAt(root, 'end'));
         const markers = new Map();
         for (const marker of model.markers){
@@ -638,7 +688,12 @@ const titleLikeElements = new Set([
     /**
 	 * Returns the `title` element when it is in the document. Returns `undefined` otherwise.
 	 */ _getTitleElement(rootName) {
-        const root = this.editor.model.document.getRoot(rootName);
+        const model = this.editor.model;
+        const root = model.document.getRoot(rootName);
+        // Root does not support the title structure (custom/inline root).
+        if (!model.schema.checkChild(root, 'title')) {
+            return;
+        }
         for (const child of root.getChildren()){
             if (isTitle(child)) {
                 return child;
@@ -675,6 +730,10 @@ const titleLikeElements = new Set([
         let changed = false;
         const model = this.editor.model;
         for (const modelRoot of this.editor.model.document.getRoots()){
+            // Skip roots that do not support the title structure (custom/inline root).
+            if (!model.schema.checkChild(modelRoot, 'title')) {
+                continue;
+            }
             const titleElements = Array.from(modelRoot.getChildren()).filter(isTitle);
             const firstTitleElement = titleElements[0];
             const firstRootChild = modelRoot.getChild(0);
@@ -711,10 +770,13 @@ const titleLikeElements = new Set([
 	 * Model post-fixer callback that adds an empty paragraph at the end of the document
 	 * when it is needed for the placeholder purposes.
 	 */ _fixBodyElement(writer) {
+        const schema = this.editor.model.schema;
         let changed = false;
         for (const rootName of this.editor.model.document.getRootNames()){
             const modelRoot = this.editor.model.document.getRoot(rootName);
-            if (modelRoot.childCount < 2) {
+            // Only insert the paragraph body placeholder when the root supports the title structure.
+            // Custom/inline roots that do not accept `title` are intentionally skipped, matching `_fixTitleElement`.
+            if (modelRoot.childCount < 2 && schema.checkChild(modelRoot, 'title')) {
                 const placeholder = writer.createElement('paragraph');
                 writer.insert(placeholder, modelRoot, 1);
                 this._bodyPlaceholder.set(rootName, placeholder);
@@ -731,6 +793,10 @@ const titleLikeElements = new Set([
         for (const rootName of this.editor.model.document.getRootNames()){
             const root = this.editor.model.document.getRoot(rootName);
             const placeholder = this._bodyPlaceholder.get(rootName);
+            // Roots that do not support the title structure never had a body placeholder created.
+            if (!placeholder) {
+                continue;
+            }
             if (shouldRemoveLastParagraph(placeholder, root)) {
                 this._bodyPlaceholder.delete(rootName);
                 writer.remove(placeholder);
@@ -768,7 +834,14 @@ const titleLikeElements = new Set([
                 if (viewRoot.isEmpty) {
                     continue;
                 }
-                // If `viewRoot` is not empty, then we can expect at least two elements in it.
+                // Skip roots whose schema does not support the title structure (custom/inline root).
+                // Their view root won't have the expected title+body layout.
+                // A title-allowed root always has a paragraph body placeholder created by `_fixBodyElement`,
+                // so the second view child is guaranteed to exist once this guard passes.
+                const modelRoot = editor.editing.mapper.toModelElement(viewRoot);
+                if (!editor.model.schema.checkChild(modelRoot, 'title')) {
+                    continue;
+                }
                 const body = viewRoot.getChild(1);
                 const oldBody = bodyViewElements.get(viewRoot.rootName);
                 // If body element has changed we need to disable placeholder on the previous element and enable on the new one.
@@ -822,6 +895,10 @@ const titleLikeElements = new Set([
                 const selectedElement = first(selection.getSelectedBlocks());
                 const selectionPosition = selection.getFirstPosition();
                 const root = editor.model.document.getRoot(selectionPosition.root.rootName);
+                // Root does not support the title structure (custom/inline root) — no title to jump to.
+                if (!model.schema.checkChild(root, 'title')) {
+                    return;
+                }
                 const title = root.getChild(0);
                 const body = root.getChild(1);
                 if (selectedElement === body && selectionPosition.isAtStart) {
@@ -835,6 +912,9 @@ const titleLikeElements = new Set([
 /**
  * A view-to-model converter for the h1 that appears at the beginning of the document (a title element).
  *
+ * Matches only the synthetic upcast parent named `$root` (the default generic root element). Title is not supported
+ * for roots whose `modelElement` is customized, so this converter intentionally does not fire on them.
+ *
  * @see module:engine/conversion/upcastdispatcher~UpcastDispatcher#event:element
  * @param evt An object containing information about the fired event.
  * @param data An object containing conversion input, a placeholder for conversion output and possibly other values.
@@ -842,6 +922,9 @@ const titleLikeElements = new Set([
  */ function dataViewModelH1Insertion(evt, data, conversionApi) {
     const modelCursor = data.modelCursor;
     const viewItem = data.viewItem;
+    // Testing against a literal `$root` is intentional: this converter must not fire on roots whose `modelElement`
+    // is customized, because the Title feature only registers its schema against `$root`.
+    // eslint-disable-next-line ckeditor5-rules/no-literal-dollar-root -- name-agnostic check would fire for unsupported custom roots
     if (!modelCursor.isAtStart || !modelCursor.parent.is('element', '$root')) {
         return;
     }
@@ -927,7 +1010,7 @@ const titleLikeElements = new Set([
  * Returns true when the last paragraph in the document was created only for the placeholder
  * purpose and it's not needed anymore. Returns false otherwise.
  */ function shouldRemoveLastParagraph(placeholder, root) {
-    if (!placeholder || !placeholder.is('element', 'paragraph') || placeholder.childCount) {
+    if (!placeholder.is('element', 'paragraph') || placeholder.childCount) {
         return false;
     }
     if (root.childCount <= 2 || root.getChild(root.childCount - 1) !== placeholder) {