@heartlandone/vega 2.102.0 → 2.103.0

package/dist/collection/components/vega-rich-text-editor/slimmers/controllers/helper/input-event-handler/insert-paragraph-handler.js

@@ -3,24 +3,25 @@ import { BaseHandler } from './base-handler';
 import { SplitBlockWithNodeAction } from '../../../../dto/actions/split-block-with-node-action';
 import { MergeTwoBlocksNodesAction } from '../../../../dto/actions/merge-two-blocks-nodes-action';
 import { InsertNewParagraphAction } from '../../../../dto/actions/insert-new-paragraph-action';
+import { ModifyContentActionType } from '../../../../dto/actions/modify-content-action.abstract';
+import { UpdateCursorPositionAction } from '../../../../dto/actions/update-cursor-position-action';
 /** Insert a paragraph in a rich text editor based on the current selection and event. User type enter will trigger this callback */
 export class InsertParagraphHandler extends BaseHandler {
   /**
    * Create new paragraph node and add node to state value
+   *
+   * @returns {CompositionStep[] | void} The content + caret steps applied atomically as one flushable composition.
    */
   handleEvent() {
     const selectedBlocks = this.selectionController.getSelectedBlocks();
     if (selectedBlocks.length) {
-      if (selectedBlocks.length < 2) {
-        this.breakSingleBlock();
-      }
-      else {
-        this.breakMultipleBlocks();
-      }
+      return selectedBlocks.length < 2 ? this.breakSingleBlock() : this.breakMultipleBlocks();
     }
   }
   /**
    * Handles breaking blocks in an RTE editor based on the current selection and position.
+   *
+   * @returns {CompositionStep[]} The content + caret steps for the multi-block break.
    */
   breakMultipleBlocks() {
     const selectedBlocks = this.selectionController.getSelectedBlocks();
@@ -58,36 +59,71 @@ export class InsertParagraphHandler extends BaseHandler {
        */
       if (firstBlock.type !== lastBlock.type &&
         range.startContainer.nodeType === range.endContainer.nodeType) {
-        firstBlock.apply(new MergeTwoBlocksNodesAction(lastBlock));
-        const splitAction = new SplitBlockWithNodeAction(cursorNode, cursorNode['text'].length);
-        firstBlock.apply(splitAction);
-        this.switchCaretPositionToNextElement(splitAction.newBlock);
-        return;
+        const mergeStep = {
+          target: firstBlock,
+          action: new MergeTwoBlocksNodesAction(lastBlock),
+        };
+        // Split offset is read at apply time, after the merge step has run.
+        // eslint-disable-next-line jsdoc/require-jsdoc
+        const splitStep = () => ({
+          target: firstBlock,
+          action: new SplitBlockWithNodeAction(cursorNode, cursorNode['text'].length),
+        });
+        // eslint-disable-next-line jsdoc/require-jsdoc
+        const caretStep = (context) => {
+          const splitAction = context.getAction(ModifyContentActionType.SPLIT_BLOCK_WITH_NODE);
+          if (splitAction) {
+            return this.caretToNextElement(splitAction.newBlock);
+          }
+        };
+        return [mergeStep, splitStep, caretStep];
       }
     }
-    this.selectionController.enqueueSelectionRangeFutureState(cursorNode, range.startOffset);
+    return [
+      {
+        target: this.currentState,
+        action: new UpdateCursorPositionAction(cursorNode, range.startOffset),
+      },
+    ];
   }
   /**
    * Handles breaking a single block in an RTE editor based on the current selection and position.
+   *
+   * @returns {CompositionStep[]} The content + caret steps for the single-block break.
    */
   breakSingleBlock() {
     const cursorNode = this.removeSelectionRange();
     const currentBlock = cursorNode instanceof RTENode ? cursorNode.parent : cursorNode;
     const { startOffset } = this.selectionController.getCurrentRange();
+    let result = [];
     if (currentBlock) {
-      const breakAction = new InsertNewParagraphAction(cursorNode, startOffset);
-      currentBlock.apply(breakAction);
-      this.switchCaretPositionToNextElement(breakAction.newBlock);
+      const breakStep = {
+        target: currentBlock,
+        action: new InsertNewParagraphAction(cursorNode, startOffset),
+      };
+      // eslint-disable-next-line jsdoc/require-jsdoc
+      const caretStep = (context) => {
+        const breakAction = context.getAction(ModifyContentActionType.INSERT_NEW_PARAGRAPH);
+        if (breakAction) {
+          return this.caretToNextElement(breakAction.newBlock);
+        }
+      };
+      result = [breakStep, caretStep];
     }
+    return result;
   }
   /**
-   * Moves the caret to the next block element in a rich text editor.
+   * Builds the caret operation that moves onto the first child of the newly created block.
    *
-   * @param {RTEBlock} newBlock - Represents a new create block element in a rich text editor.
+   * @param {Nullable<RTEBlock>} newBlock - The block created by the break, or null when none was created.
+   * @returns {CompositionOperation | void} The caret operation, or nothing when there is no target block.
    */
-  switchCaretPositionToNextElement(newBlock) {
+  caretToNextElement(newBlock) {
     if (newBlock && newBlock.children) {
-      this.selectionController.enqueueSelectionRangeFutureState(newBlock.children[0], 0);
+      return {
+        target: this.currentState,
+        action: new UpdateCursorPositionAction(newBlock.children[0], 0),
+      };
     }
   }
 }

package/dist/collection/components/vega-rich-text-editor/slimmers/controllers/helper/input-event-handler/insert-paste-handler.js

@@ -2,13 +2,16 @@ import { BaseHandler } from './base-handler';
 import { AppendChildrenAction } from '../../../../dto/actions/append-child-nodes-action';
 import ElementToDtoStrategyProcessor from '../element-to-dto-strategy/element-to-dto-strategy-processor';
 import { StylePreservator } from '../../../../../../helpers/csp/styles-preservator';
+import { htmlContainsTable, htmlToPlainText } from '../../../../utils/html-to-plain-text-utils';
 import { PasteContentAction } from '../../../../dto/actions/paste-content-action';
 import { RTETextBlock } from '../../../../dto/blocks/text-block';
 import { RTETextNode } from '../../../../dto/nodes/text-node';
 import { generateUUID } from '../../../../../../utils/misc';
-import { escapeHtml } from '../../../../helpers/utils';
+import { escapeHtml, normalizePlainTextLines, toPlainPasteLines } from '../../../../helpers/utils';
 import { ReplaceSelectedTextAction } from '../../../../dto/actions/replace-selected-text-action';
-import { RTE_PASTE_MODE_DATA_TYPE, RTE_PASTE_MODE_WORD } from '../../../../constants/constant';
+import { RTE_PASTE_MODE_DATA_TYPE, RTE_PASTE_MODE_PLAIN, RTE_PASTE_MODE_WORD, RTE_PRESERVED_WHITESPACE_DATA_TYPE, } from '../../../../constants/constant';
+import { ModifyContentActionType } from '../../../../dto/actions/modify-content-action.abstract';
+import { UpdateCursorPositionAction } from '../../../../dto/actions/update-cursor-position-action';
 /**
  * Handle user paste
  */
@@ -17,53 +20,57 @@ export class InsertPasteHandler extends BaseHandler {
    * Update the state value when user paste html elements.
    *
    * @param {InputEvent} event - Paste event.
+   * @returns {CompositionStep[]} The content + caret steps applied atomically as one flushable composition.
    */
   handleEvent(event) {
     const currentRange = this.selectionController.getCurrentRange();
     const payload = this.getPastePayload(event);
-    if (this.insertPlainTextInline(payload, currentRange)) {
-      return;
+    const inlineSteps = this.insertPlainTextInline(payload, currentRange);
+    if (inlineSteps) {
+      return inlineSteps;
     }
-    const blocks = this.parsePastedElements(event);
+    const blocks = this.parsePastedElements(event, currentRange);
     const startContainer = (currentRange === null || currentRange === void 0 ? void 0 : currentRange.startContainer) || undefined;
     if (!startContainer) {
       // When the selection/range is unavailable (e.g. the caret was lost while
       // the paste-mode chooser had focus), still append the pasted content to
       // the root so the paste is never silently dropped.
-      this.insertBlocksToRoot(blocks);
+      return this.insertBlocksToRoot(blocks);
     }
-    else if (this.isRootContainer(startContainer)) {
-      this.insertBlocksToRoot(blocks);
+    if (this.isRootContainer(startContainer)) {
       // TODO: Need to check below logic, it seems not correct https://gethired.atlassian.net/browse/VD-7779
+      return this.insertBlocksToRoot(blocks);
     }
-    else if (this.isEmptyParagraph(startContainer)) {
-      this.insertBlocksBeforeEmptyBlock(blocks, currentRange);
-    }
-    else {
-      this.insertBlocksToContent(blocks, currentRange);
+    if (this.isEmptyParagraph(startContainer)) {
+      return this.insertBlocksBeforeEmptyBlock(blocks, currentRange);
     }
+    return this.insertBlocksToContent(blocks, currentRange);
   }
   /**
    * Inserts plain-text paste content into the current text node at caret position.
    *
    * @param {RTEPastePayload} payload - Clipboard payload.
    * @param {RTERange} currentRange - Current selection range.
-   * @returns {boolean} True when inline insertion is handled.
+   * @returns {CompositionStep[] | undefined} The content + caret steps when inline insertion applies, otherwise undefined.
    */
   insertPlainTextInline(payload, currentRange) {
     var _a, _b;
     const selectedNodes = ((_b = (_a = this.selectionController).getSelectedNodes) === null || _b === void 0 ? void 0 : _b.call(_a)) || [];
     if (!this.shouldPasteAsInlinePlainText(payload, currentRange, selectedNodes)) {
-      return false;
+      return undefined;
     }
     const text = payload.text.replace(/\r\n?/g, '\n');
     const cursorNode = selectedNodes.find((node) => node instanceof RTETextNode) || currentRange.startNode;
     if (!(cursorNode instanceof RTETextNode)) {
-      return false;
-    }
-    cursorNode.apply(new ReplaceSelectedTextAction(text, currentRange));
-    this.selectionController.enqueueSelectionRangeFutureState(cursorNode, currentRange.startOffset + text.length);
-    return true;
+      return undefined;
+    }
+    return [
+      { target: cursorNode, action: new ReplaceSelectedTextAction(text, currentRange) },
+      {
+        target: this.currentState,
+        action: new UpdateCursorPositionAction(cursorNode, currentRange.startOffset + text.length),
+      },
+    ];
   }
   /**
    * Determines whether the payload should be inserted as inline plain text.
@@ -128,68 +135,116 @@ export class InsertPasteHandler extends BaseHandler {
    * Insert the blocks to root
    *
    * @param { RTEContentBlock[]} blocks - blocks
+   * @returns {CompositionStep[]} The append step for the root.
    */
   insertBlocksToRoot(blocks) {
-    this.currentState.apply(new AppendChildrenAction(blocks));
+    return [{ target: this.currentState, action: new AppendChildrenAction(blocks) }];
   }
   /**
    * Insert the blocks into the current content block at the specified range.
    *
    * @param { RTEContentBlock[]} blocks - blocks
    * @param { RTERange } rteRange - rteRange
+   * @returns {CompositionStep[]} The content + caret steps for the content branch.
    */
   insertBlocksToContent(blocks, rteRange) {
-    var _a;
     const isCollapsedRange = rteRange.startNode === rteRange.endNode && rteRange.startOffset === rteRange.endOffset;
     const cursorNode = isCollapsedRange
       ? rteRange.startNode
       : this.removeSelectionRange();
     if (cursorNode && cursorNode.parent) {
-      const pasteAction = new PasteContentAction(blocks, cursorNode, rteRange.startOffset, rteRange);
-      cursorNode.parent.apply(pasteAction);
-      if (pasteAction.futureFocusNode) {
-        this.selectionController.enqueueSelectionRangeFutureState(pasteAction.futureFocusNode, (_a = pasteAction.futureFocusNodeOffset) !== null && _a !== void 0 ? _a : 0);
-      }
-      else if (pasteAction.futureFocusBlock) {
-        this.switchCaretPositionToNextElement(pasteAction.futureFocusBlock, pasteAction.futureFocusAtEnd);
-      }
-    }
-    else {
-      // No resolvable cursor position: fall back to appending at the root so
-      // the pasted content is preserved instead of being discarded.
-      this.insertBlocksToRoot(blocks);
-    }
+      const contentStep = {
+        target: cursorNode.parent,
+        action: new PasteContentAction(blocks, cursorNode, rteRange.startOffset, rteRange),
+      };
+      // eslint-disable-next-line jsdoc/require-jsdoc
+      const caretStep = (context) => {
+        var _a;
+        const pasteAction = context.getAction(ModifyContentActionType.PASTE_CONTENT);
+        if (pasteAction && pasteAction.futureFocusNode) {
+          return {
+            target: this.currentState,
+            action: new UpdateCursorPositionAction(pasteAction.futureFocusNode, (_a = pasteAction.futureFocusNodeOffset) !== null && _a !== void 0 ? _a : 0),
+          };
+        }
+        if (pasteAction && pasteAction.futureFocusBlock) {
+          return this.caretToBlockOperation(pasteAction.futureFocusBlock, pasteAction.futureFocusAtEnd);
+        }
+      };
+      return [contentStep, caretStep];
+    }
+    // No resolvable cursor position: fall back to appending at the root so
+    // the pasted content is preserved instead of being discarded.
+    return this.insertBlocksToRoot(blocks);
   }
   /**
    * Insert the blocks before to current block
    *
    * @param { RTEContentBlock[]} blocks - blocks
    * @param { RTERange } rteRange - rteRange
+   * @returns {CompositionStep[]} The content + caret steps for the empty-paragraph branch.
    */
   insertBlocksBeforeEmptyBlock(blocks, rteRange) {
     const cursorNode = this.removeSelectionRange();
     const currentBlock = cursorNode === null || cursorNode === void 0 ? void 0 : cursorNode.parent;
     if (currentBlock) {
-      const pasteAction = new PasteContentAction(blocks, cursorNode, 0, rteRange);
-      currentBlock.apply(pasteAction);
-      if (pasteAction.futureFocusBlock) {
-        this.switchCaretPositionToNextElement(pasteAction.futureFocusBlock, pasteAction.futureFocusAtEnd);
-      }
-    }
-    else {
-      // No resolvable empty block: fall back to appending at the root so the
-      // pasted content is preserved instead of being discarded.
-      this.insertBlocksToRoot(blocks);
-    }
+      const contentStep = {
+        target: currentBlock,
+        action: new PasteContentAction(blocks, cursorNode, 0, rteRange),
+      };
+      // eslint-disable-next-line jsdoc/require-jsdoc
+      const caretStep = (context) => {
+        const pasteAction = context.getAction(ModifyContentActionType.PASTE_CONTENT);
+        if (pasteAction && pasteAction.futureFocusBlock) {
+          return this.caretToBlockOperation(pasteAction.futureFocusBlock, pasteAction.futureFocusAtEnd);
+        }
+      };
+      return [contentStep, caretStep];
+    }
+    // No resolvable empty block: fall back to appending at the root so the
+    // pasted content is preserved instead of being discarded.
+    return this.insertBlocksToRoot(blocks);
   }
   /**
    * Format and parse elements from user paste with simple style preservation.
    *
    * @param {InputEvent} event - Paste event.
+   * @param {RTERange} [currentRange] - Optional range used to resolve the paste location.
    * @returns {RTEContentBlock[]} - RTEContentBlock.
    */
-  parsePastedElements(event) {
+  parsePastedElements(event, currentRange) {
+    var _a;
     const payload = this.getPastePayload(event);
+    if (payload.type === RTE_PASTE_MODE_PLAIN) {
+      // Native tables encode their layout as tab-separated cells (one row per line) in
+      // text/plain, so pasting that verbatim keeps the rows/columns. Non-native tables (rich text
+      // editor tables) put a blank line between cells in text/plain, so they derive from HTML
+      // instead: htmlToPlainText puts each cell on its own line with no gaps while keeping in-cell breaks.
+      let plainText;
+      let hasEncodedWhitespace = (_a = payload.hasEncodedWhitespace) !== null && _a !== void 0 ? _a : false;
+      if (payload.html &&
+        payload.text &&
+        payload.text.includes('\t') &&
+        htmlContainsTable(payload.html)) {
+        plainText = payload.text;
+      }
+      else if (payload.html && htmlContainsTable(payload.html)) {
+        plainText = this.extractPlainTextFromHtml(payload.html, true);
+        hasEncodedWhitespace = true;
+      }
+      else {
+        plainText = '';
+        if (payload.text) {
+          plainText = payload.text;
+        }
+        else if (payload.html) {
+          plainText = this.extractPlainTextFromHtml(payload.html, true);
+          hasEncodedWhitespace = true;
+        }
+      }
+      const styleSource = (currentRange === null || currentRange === void 0 ? void 0 : currentRange.startNode) instanceof RTETextNode ? currentRange.startNode : undefined;
+      return this.buildPlainTextParagraph(plainText, styleSource, hasEncodedWhitespace);
+    }
     let pastedHTML = payload.html || '';
     if (!pastedHTML) {
       pastedHTML = this.parsePlainText(payload.text || '');
@@ -227,16 +282,21 @@ export class InsertPasteHandler extends BaseHandler {
     return resultBlocks;
   }
   /**
-   * Extracts readable plain text from clipboard HTML.
+   * Extracts plain text from HTML when clipboard lacks `text/plain`.
    *
    * @param {string} html - Clipboard text/html payload.
+   * @param {boolean} keepPreservedWhitespaceMarkers - Keep code-block indentation as sentinels so
+   * the plain-mode boundary collapse in `toPlainPasteLines` does not strip it (that helper decodes
+   * the sentinels). Must stay `false` for the rich path, which feeds `parsePlainText` directly.
    * @returns {string} - Plain text extracted from HTML.
    */
-  extractPlainTextFromHtml(html) {
+  extractPlainTextFromHtml(html, keepPreservedWhitespaceMarkers = false) {
     // Preserve inline styles before parsing to avoid style-src-attr CSP violations.
     const safeHtml = StylePreservator.preserve(html).getProcessedHtml();
-    const parsedDoc = new DOMParser().parseFromString(safeHtml, 'text/html');
-    return (parsedDoc.body.textContent || '').replace(/\r\n?/g, '\n');
+    return htmlToPlainText(safeHtml, {
+      preserveBoundaryBlankLines: true,
+      keepPreservedWhitespaceMarkers,
+    });
   }
   /**
    * Builds plain-text paragraph blocks when element strategy parsing returns no output.
@@ -245,7 +305,7 @@ export class InsertPasteHandler extends BaseHandler {
    * @returns {RTEContentBlock[]} Fallback text blocks.
    */
   buildPlainTextFallbackBlocks(text) {
-    return text.split('\n').map((line) => {
+    return normalizePlainTextLines(text).map((line) => {
       const paragraph = new RTETextBlock(generateUUID(), 'paragraph');
       const textNode = new RTETextNode(`${paragraph.id}1`, line, paragraph);
       paragraph.apply(new AppendChildrenAction([textNode]));
@@ -253,21 +313,66 @@ export class InsertPasteHandler extends BaseHandler {
     });
   }
   /**
-   * Moves the caret to a block element in a rich text editor after paste.
+   * Builds plain-text paragraphs by splitting on `\n`.
+   *
+   * Shares `toPlainPasteLines` with `PlainPasteProcessingStrategy` so both
+   * representations of plain-mode content (HTML and RTE nodes) agree on line
+   * boundaries and boundary whitespace.
+   *
+   * @param {string} text - Plain text clipboard content.
+   * @param {RTETextNode} [styleSource] - Optional style to preserve in all nodes.
+   * @param {boolean} decodeEncodedWhitespace - Decode HTML-derived whitespace markers.
+   * @returns {RTEContentBlock[]} Paragraph-per-line blocks.
+   */
+  buildPlainTextParagraph(text, styleSource, decodeEncodedWhitespace = false) {
+    const lines = toPlainPasteLines(text, decodeEncodedWhitespace);
+    return lines.map((line, lineIndex) => {
+      const paragraph = new RTETextBlock(generateUUID(), 'paragraph');
+      // Always attach a text node (empty for blank lines) so empty paragraphs
+      // render with a zero-width space and keep their visible line height,
+      // instead of collapsing to an invisible zero-height `<p></p>`.
+      const node = this.createPlainTextNode(paragraph, lineIndex, line, styleSource);
+      paragraph.apply(new AppendChildrenAction([node]));
+      return paragraph;
+    });
+  }
+  /**
+   * Creates a text node for plain paste; optionally inherits style from source node.
+   *
+   * @param {RTETextBlock} paragraph - Parent paragraph.
+   * @param {number} index - Character index for node ID generation.
+   * @param {string} text - Text content.
+   * @param {RTETextNode} [styleSource] - Optional style to inherit.
+   * @returns {RTETextNode} Created text node.
+   */
+  createPlainTextNode(paragraph, index, text, styleSource) {
+    const node = styleSource
+      ? styleSource.cloneWithText(text)
+      : new RTETextNode(`${paragraph.id}-${index}`, text, paragraph);
+    node.parent = paragraph;
+    return node;
+  }
+  /**
+   * Builds the caret operation that moves onto a block element in a rich text editor after paste.
    *
    * @param {RTEBlock} newBlock - Block element to move the caret to.
    * @param {boolean} atEnd - When true, places the caret after the last character of the block's last node; otherwise at offset 0 of the first node.
+   * @returns {CompositionOperation | void} The caret operation, or nothing when the block has no children.
    */
-  switchCaretPositionToNextElement(newBlock, atEnd = false) {
+  caretToBlockOperation(newBlock, atEnd = false) {
     var _a, _b;
     if (newBlock && newBlock.children) {
       if (atEnd) {
         const lastNode = newBlock.children[newBlock.children.length - 1];
-        this.selectionController.enqueueSelectionRangeFutureState(lastNode, (_b = (_a = lastNode.text) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0);
-      }
-      else {
-        this.selectionController.enqueueSelectionRangeFutureState(newBlock.children[0], 0);
+        return {
+          target: this.currentState,
+          action: new UpdateCursorPositionAction(lastNode, (_b = (_a = lastNode.text) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0),
+        };
       }
+      return {
+        target: this.currentState,
+        action: new UpdateCursorPositionAction(newBlock.children[0], 0),
+      };
     }
   }
   /**
@@ -489,6 +594,7 @@ export class InsertPasteHandler extends BaseHandler {
       html: event.dataTransfer.getData('text/html') || eventPayload.html || '',
       text: event.dataTransfer.getData('text/plain') || eventPayload.text || '',
       type: event.dataTransfer.getData(RTE_PASTE_MODE_DATA_TYPE) || '',
+      hasEncodedWhitespace: event.dataTransfer.getData(RTE_PRESERVED_WHITESPACE_DATA_TYPE) === 'true',
     };
   }
 }

package/dist/collection/components/vega-rich-text-editor/slimmers/controllers/helper/input-event-handler/insert-text-handler.js

@@ -1,36 +1,52 @@
 import { BaseHandler } from './base-handler';
 import { RTETextBlock } from '../../../../dto/blocks/text-block';
-import { ZERO_WIDTH_SPACE } from '../../../../constants/constant';
+import { RTE_UPDATE_SOURCE_KEY, RTEUpdateSource, ZERO_WIDTH_SPACE } from '../../../../constants/constant';
 import { RTETextNode } from '../../../../dto/nodes/text-node';
 import { UpdateTextAction } from '../../../../dto/actions/update-text-action';
 import { ReplaceSelectedTextAction } from '../../../../dto/actions/replace-selected-text-action';
 import { InsertChildrenBeforeAction } from '../../../../dto/actions/insert-children-before-block';
 import { InsertTextToDecoratorNodeAction } from '../../../../dto/actions/insert-text-to-decorator-node-action';
+import { UpdateCursorPositionAction } from '../../../../dto/actions/update-cursor-position-action';
 /** Handles inserting text into a VegaRTEContent based on the current selection and input event. User input character will trigger this callback */
 export class InsertTextHandler extends BaseHandler {
   /**
    * Update the state value when user type character
    *
    * @param {InputEvent} event - The input event object
+   * @returns {Nullable<CompositionStep[]>} The content actions the base handler applies as one flushable unit.
    */
   handleEvent(event) {
+    // The composition input controller stamps its synthesized `beforeinput` events with the
+    // composition update source; pick that up so the flush notification carries the right
+    // source without the caller having to inspect the event.
+    if (this.flushOptions) {
+      this.flushOptions.updateSource =
+        event[RTE_UPDATE_SOURCE_KEY] === RTEUpdateSource.Composition
+          ? RTEUpdateSource.Composition
+          : RTEUpdateSource.Default;
+    }
     const text = event.data;
     const currentRange = this.selectionController.getCurrentRange();
     const { startContainer, startOffset } = currentRange;
     const selectedNodes = this.selectionController.getSelectedNodes();
+    const steps = [];
+    // The caret move is appended as the final composition step so content + caret apply and flush atomically.
+    let caretNode = null;
+    let caretOffset = 0;
+    let updateFlag = false;
     if (selectedNodes.length < 2) {
       if (!selectedNodes.length && this.isRootContainer(startContainer)) {
-        const cursorNode = this.insertTextToRoot(text);
-        this.selectionController.enqueueSelectionRangeFutureState(cursorNode, text.length);
+        caretNode = this.insertTextToRoot(text, steps);
+        caretOffset = text.length;
       }
       else if (selectedNodes[0] instanceof RTETextNode) {
         if (selectedNodes[0].isContentEditable()) {
           let nextOffset = startOffset + text.length;
-          let updateFlag = false;
           let cursorNode = selectedNodes[0];
           if (cursorNode.text === '\n') {
-            cursorNode = this.insertTextToLineBreakNode(cursorNode, text);
-            updateFlag = true;
+            cursorNode = this.insertTextToLineBreakNode(cursorNode, text, steps);
+            // UpdateTextAction replaces the \n with the input, so the caret lands at the text end.
+            nextOffset = text.length;
           }
           else {
             if (startContainer.nodeValue === ZERO_WIDTH_SPACE &&
@@ -39,40 +55,54 @@ export class InsertTextHandler extends BaseHandler {
               startContainer.nodeValue = '';
               nextOffset = nextOffset - ZERO_WIDTH_SPACE.length;
             }
-            if (cursorNode instanceof RTETextNode) {
-              updateFlag = true;
-              cursorNode.apply(new ReplaceSelectedTextAction(text, currentRange));
-            }
+            steps.push({
+              target: cursorNode,
+              action: new ReplaceSelectedTextAction(text, currentRange),
+            });
           }
-          updateFlag &&
-            this.selectionController.enqueueSelectionRangeFutureState(cursorNode, Math.min(nextOffset, cursorNode['text'].length));
+          caretNode = cursorNode;
+          // Content applies later via the composition, so use the post-apply offset directly (no pre-apply clamp).
+          caretOffset = nextOffset;
         }
         else {
-          selectedNodes[0].parent.apply(new InsertTextToDecoratorNodeAction(selectedNodes[0], text, startOffset));
+          steps.push({
+            target: selectedNodes[0].parent,
+            action: new InsertTextToDecoratorNodeAction(selectedNodes[0], text, startOffset),
+          });
         }
       }
     }
     else {
       // The selected nodes is multiple nodes
       const cursorNode = this.removeSelectionRange(true);
+      updateFlag = true;
       if (cursorNode instanceof RTETextNode) {
-        cursorNode.apply(new ReplaceSelectedTextAction(text, currentRange));
-        this.selectionController.enqueueSelectionRangeFutureState(cursorNode, Math.min(startOffset + text.length, cursorNode.text.length));
+        steps.push({ target: cursorNode, action: new ReplaceSelectedTextAction(text, currentRange) });
+        caretNode = cursorNode;
+        caretOffset = startOffset + text.length;
       }
     }
+    if (caretNode) {
+      steps.push({
+        target: this.currentState,
+        action: new UpdateCursorPositionAction(caretNode, caretOffset),
+      });
+    }
+    return updateFlag || steps.length > 0 ? steps : undefined;
   }
   /**
    * Insert the text in root element when root container is empty, should create text block and text node
    *
    * @param {string} text The insert text
-   * @returns {RTETextNode} The new create text node
+   * @param {CompositionStep[]} steps The composition steps collector to append the update action to
+   * @returns {Nullable<RTETextNode>} The new create text node
    */
-  insertTextToRoot(text) {
+  insertTextToRoot(text, steps) {
     if (this.currentState &&
       this.currentState.children[0] &&
       this.currentState.children[0] instanceof RTETextBlock) {
       const firstNode = this.currentState.children[0].children[0];
-      firstNode.apply(new UpdateTextAction(text));
+      steps.push({ target: firstNode, action: new UpdateTextAction(text) });
       return firstNode;
     }
   }
@@ -81,20 +111,24 @@ export class InsertTextHandler extends BaseHandler {
    *
    * @param {RTETextNode} lineBreakNode The current line break node, the text value is \n
    * @param {string} text The text need to insert
+   * @param {CompositionStep[]} steps The composition steps collector to append the resulting action to
    * @returns {Nullable<RTETextNode>} The new text node or the current line break node
    */
-  insertTextToLineBreakNode(lineBreakNode, text) {
+  insertTextToLineBreakNode(lineBreakNode, text, steps) {
     const { startOffset, endOffset } = this.selectionController.getCurrentRange();
     const textBlock = lineBreakNode.parent;
     if (textBlock instanceof RTETextBlock) {
       const index = textBlock.children.indexOf(lineBreakNode);
       if (startOffset === 0 && startOffset === endOffset && textBlock.children[index + 1]) {
         const newTextNode = lineBreakNode.cloneWithText(text);
-        textBlock.apply(new InsertChildrenBeforeAction(lineBreakNode, newTextNode));
+        steps.push({
+          target: textBlock,
+          action: new InsertChildrenBeforeAction(lineBreakNode, newTextNode),
+        });
         return newTextNode;
       }
       else {
-        lineBreakNode.apply(new UpdateTextAction(text));
+        steps.push({ target: lineBreakNode, action: new UpdateTextAction(text) });
         return lineBreakNode;
       }
     }