feat(executor): add tab character to tab node conversion in text insert (#2832)

* feat(executor): add tab character to tab node conversion in text insert

* feat(executor): enhance text insertion to handle restrictive parent content for tab nodes

- Introduced a new integration test for the `executeTextInsert` function to validate behavior when inserting text into nodes that disallow tab nodes, specifically for the `total-page-number` type.
- Updated the `executeTextInsert` function to check if the parent node allows tab nodes before creating them, ensuring that raw tab characters are preserved as text when necessary.
- Added a utility function `parentAllowsNode` to determine if a node type can be inserted based on the parent's content match.

* feat(tabs): implement tab handling in text insertion and document extraction

- Introduced `buildTextWithTabs` and `textBetweenWithTabs` functions to manage tab characters, converting them to tab nodes during text insertion and ensuring they are correctly represented in document extraction.
- Updated existing commands (`insertHeadingAt`, `insertListItemAt`, `insertParagraphAt`) to utilize the new tab handling functions, enhancing text formatting capabilities.
- Modified tests to validate the new tab handling behavior, ensuring that tab characters are preserved and correctly processed in various scenarios.
- Added comprehensive tests for the new helper functions to ensure robust functionality across different document structures.

This update enhances the editor's ability to handle tab characters, improving the overall user experience when working with formatted text.

Author: andrii-harbour

packages/super-editor/src/editors/v1/core/commands/insertHeadingAt.js

@@ -1,3 +1,5 @@
+import { buildTextWithTabs } from '../../document-api-adapters/helpers/text-with-tabs.js';
+
 /**
  * Insert a heading node at an absolute document position.
  *
@@ -25,13 +27,13 @@ export const insertHeadingAt =
       },
     };
     const normalizedText = typeof text === 'string' ? text : '';
-    const textNode = normalizedText.length > 0 ? state.schema.text(normalizedText) : null;
+    // buildTextWithTabs splits '\t' into real tab nodes so exports emit <w:tab/>.
+    const content = normalizedText.length > 0 ? buildTextWithTabs(state.schema, normalizedText, undefined) : null;
 
     let paragraphNode;
     try {
       paragraphNode =
-        paragraphType.createAndFill(attrs, textNode ?? undefined) ??
-        paragraphType.create(attrs, textNode ? [textNode] : undefined);
+        paragraphType.createAndFill(attrs, content ?? undefined) ?? paragraphType.create(attrs, content ?? undefined);
     } catch {
       return false;
     }

packages/super-editor/src/editors/v1/core/commands/insertHeadingAt.test.js

@@ -145,7 +145,7 @@ describe('insertHeadingAt', () => {
 
     insertHeadingAt({ pos: 0, level: 1, text: 'Hello' })({ state, dispatch });
 
-    expect(state.schema.text).toHaveBeenCalledWith('Hello');
+    expect(state.schema.text).toHaveBeenCalledWith('Hello', undefined);
   });
 
   // --- tracked mode ---

packages/super-editor/src/editors/v1/core/commands/insertListItemAt.js

@@ -1,4 +1,5 @@
 import { getResolvedParagraphProperties } from '@extensions/paragraph/resolvedPropertiesCache.js';
+import { buildTextWithTabs } from '../../document-api-adapters/helpers/text-with-tabs.js';
 
 /**
  * Insert a list-item paragraph before/after a target list paragraph position.
@@ -42,12 +43,12 @@ export const insertListItemAt =
     };
 
     const normalizedText = typeof text === 'string' ? text : '';
-    const textNode = normalizedText.length > 0 ? state.schema.text(normalizedText) : undefined;
+    // buildTextWithTabs splits '\t' into real tab nodes so exports emit <w:tab/>.
+    const content = normalizedText.length > 0 ? buildTextWithTabs(state.schema, normalizedText, undefined) : undefined;
 
     let paragraphNode;
     try {
-      paragraphNode =
-        paragraphType.createAndFill(attrs, textNode) ?? paragraphType.create(attrs, textNode ? [textNode] : undefined);
+      paragraphNode = paragraphType.createAndFill(attrs, content) ?? paragraphType.create(attrs, content ?? undefined);
     } catch {
       return false;
     }

packages/super-editor/src/editors/v1/core/commands/insertListItemAt.test.js

@@ -175,7 +175,7 @@ describe('insertListItemAt', () => {
       dispatch,
     });
 
-    expect(state.schema.text).toHaveBeenCalledWith('New item');
+    expect(state.schema.text).toHaveBeenCalledWith('New item', undefined);
   });
 
   it('does not inherit sdBlockId from the target node when omitted', () => {

packages/super-editor/src/editors/v1/core/commands/insertParagraphAt.js

@@ -1,3 +1,5 @@
+import { buildTextWithTabs } from '../../document-api-adapters/helpers/text-with-tabs.js';
+
 /**
  * Insert a paragraph node at an absolute document position.
  *
@@ -16,13 +18,14 @@ export const insertParagraphAt =
       ...(paraId ? { paraId } : undefined),
     };
     const normalizedText = typeof text === 'string' ? text : '';
-    const textNode = normalizedText.length > 0 ? state.schema.text(normalizedText) : null;
+    // buildTextWithTabs splits '\t' into real tab nodes so exports emit <w:tab/>
+    // instead of a raw tab character inside <w:t>.
+    const content = normalizedText.length > 0 ? buildTextWithTabs(state.schema, normalizedText, undefined) : null;
 
     let paragraphNode;
     try {
       paragraphNode =
-        paragraphType.createAndFill(attrs, textNode ?? undefined) ??
-        paragraphType.create(attrs, textNode ? [textNode] : undefined);
+        paragraphType.createAndFill(attrs, content ?? undefined) ?? paragraphType.create(attrs, content ?? undefined);
     } catch {
       return false;
     }

packages/super-editor/src/editors/v1/core/commands/insertParagraphAt.test.js

@@ -100,7 +100,7 @@ describe('insertParagraphAt', () => {
 
     insertParagraphAt({ pos: 0, text: 'Hello' })({ state, dispatch });
 
-    expect(state.schema.text).toHaveBeenCalledWith('Hello');
+    expect(state.schema.text).toHaveBeenCalledWith('Hello', undefined);
   });
 
   it('sets forceTrackChanges meta when tracked is true', () => {

packages/super-editor/src/editors/v1/document-api-adapters/get-text-adapter.ts

@@ -1,15 +1,20 @@
 import type { Editor } from '../core/Editor.js';
 import type { GetTextInput } from '@superdoc/document-api';
 import { resolveStoryRuntime } from './story-runtime/resolve-story-runtime.js';
+import { textBetweenWithTabs } from './helpers/text-with-tabs.js';
 
 /**
  * Return the full document text content from the ProseMirror document.
  *
+ * Tab nodes are rendered as real '\t' so the extracted text round-trips with
+ * what the write APIs accept. Other inline leaves fall back to '\n' (matching
+ * the legacy behavior for non-text nodes).
+ *
  * @param editor - The editor instance.
  * @returns Plain text content of the document.
  */
 export function getTextAdapter(editor: Editor, input: GetTextInput): string {
   const runtime = resolveStoryRuntime(editor, input.in);
   const doc = runtime.editor.state.doc;
-  return doc.textBetween(0, doc.content.size, '\n', '\n');
+  return textBetweenWithTabs(doc, 0, doc.content.size, '\n', '\n');
 }

packages/super-editor/src/editors/v1/document-api-adapters/helpers/adapter-utils.ts

@@ -21,6 +21,7 @@ import { buildTextMutationResolution, readTextAtResolvedRange } from './text-mut
 import type { Transaction } from 'prosemirror-state';
 import type { Editor } from '../../core/Editor.js';
 import { DocumentApiAdapterError } from '../errors.js';
+import { buildTextWithTabs } from './text-with-tabs.js';
 
 export type WithinResult = { ok: true; range: { start: number; end: number } | undefined } | { ok: false };
 export type ResolvedTextTarget = { from: number; to: number };
@@ -228,8 +229,8 @@ export function insertParagraphAtEnd(
   applyMeta?: (tr: Transaction) => Transaction,
 ): void {
   const schema = editor.state.schema;
-  const textNode = schema.text(text);
-  const paragraph = schema.nodes.paragraph.create(null, textNode);
+  const content = buildTextWithTabs(schema, text, undefined);
+  const paragraph = schema.nodes.paragraph.create(null, content);
   const tr = editor.state.tr;
   tr.insert(pos, paragraph);
   if (applyMeta) applyMeta(tr);

packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-mutation-resolution.test.ts

@@ -1,8 +1,11 @@
+import { describe, expect, it, vi } from 'vitest';
 import type { TextAddress } from '@superdoc/document-api';
 import { buildTextMutationResolution, readTextAtResolvedRange } from './text-mutation-resolution.js';
 import type { Editor } from '../../core/Editor.js';
 
 function makeEditor(text: string): Editor {
+  // textBetweenWithTabs uses nodesBetween in real PM docs and falls back to
+  // textBetween for mocked docs that don't provide nodesBetween.
   return {
     state: {
       doc: {
@@ -13,7 +16,7 @@ function makeEditor(text: string): Editor {
 }
 
 describe('readTextAtResolvedRange', () => {
-  it('delegates to textBetween with canonical separators', () => {
+  it('reads text between resolved positions with canonical separators', () => {
     const editor = makeEditor('Hello');
     const result = readTextAtResolvedRange(editor, { from: 1, to: 6 });
 

packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-mutation-resolution.ts

@@ -1,6 +1,7 @@
 import type { TextAddress, TextMutationResolution } from '@superdoc/document-api';
 import type { Editor } from '../../core/Editor.js';
 import type { ResolvedTextTarget } from './adapter-utils.js';
+import { textBetweenWithTabs } from './text-with-tabs.js';
 
 /** Unicode Object Replacement Character — used as placeholder for leaf inline nodes in textBetween(). */
 const OBJECT_REPLACEMENT_CHAR = '\ufffc';
@@ -9,14 +10,16 @@ const OBJECT_REPLACEMENT_CHAR = '\ufffc';
  * Reads the canonical flattened text between two resolved document positions.
  *
  * Uses `\n` as the block separator and `\ufffc` (Object Replacement Character) as the
- * leaf-inline placeholder, matching the offset model used by `TextAddress`.
+ * leaf-inline placeholder, matching the offset model used by `TextAddress`. Tab
+ * nodes round-trip to a real '\t' so no-op comparisons against caller-supplied
+ * text (e.g. `write-adapter`'s replace NO_OP check) continue to match.
  *
  * @param editor - The editor instance to read from.
  * @param range - Resolved absolute document positions.
  * @returns The text content between the resolved positions.
  */
 export function readTextAtResolvedRange(editor: Editor, range: ResolvedTextTarget): string {
-  return editor.state.doc.textBetween(range.from, range.to, '\n', OBJECT_REPLACEMENT_CHAR);
+  return textBetweenWithTabs(editor.state.doc, range.from, range.to, '\n', OBJECT_REPLACEMENT_CHAR);
 }
 
 /**