Lexical API: Added content module, testing and documented

resources/js/wysiwyg/api/__tests__/api-test-utils.ts

@@ -1,13 +1,14 @@
 import {createTestContext} from "lexical/__tests__/utils";
 import {EditorApi} from "../api";
 import {EditorUiContext} from "../../ui/framework/core";
+import {LexicalEditor} from "lexical";
 
 
 /**
  * Create an instance of the EditorApi and EditorUiContext.
  */
-export function createEditorApiInstance(): { api: EditorApi; context: EditorUiContext } {
+export function createEditorApiInstance(): { api: EditorApi; context: EditorUiContext, editor: LexicalEditor} {
     const context = createTestContext();
     const api = new EditorApi(context);
-    return {api, context};
+    return {api, context, editor: context.editor};
 }

resources/js/wysiwyg/api/__tests__/content.test.ts

@@ -0,0 +1,93 @@
+import {createEditorApiInstance} from "./api-test-utils";
+import {$createParagraphNode, $createTextNode, $getRoot, IS_BOLD, LexicalEditor} from "lexical";
+import {expectNodeShapeToMatch} from "lexical/__tests__/utils";
+
+
+describe('Editor API: Content Module', () => {
+
+    describe('insertHtml()', () => {
+        it('should insert html at selection by default', () => {
+            const {api, editor} = createEditorApiInstance();
+            insertAndSelectSampleBlock(editor);
+
+            api.content.insertHtml('<strong>pp</strong>');
+            editor.commitUpdates();
+
+            expectNodeShapeToMatch(editor, [
+                {type: 'paragraph', children: [
+                    {text: 'He'},
+                    {text: 'pp', format: IS_BOLD},
+                    {text: 'o World'}
+                ]}
+            ]);
+        });
+
+        it('should handle a mix of inline and block elements', () => {
+            const {api, editor} = createEditorApiInstance();
+            insertAndSelectSampleBlock(editor);
+
+            api.content.insertHtml('<p>cat</p><strong>pp</strong><p>dog</p>');
+            editor.commitUpdates();
+
+            expectNodeShapeToMatch(editor, [
+                {type: 'paragraph', children: [{text: 'cat'}]},
+                {type: 'paragraph', children: [
+                        {text: 'He'},
+                        {text: 'pp', format: IS_BOLD},
+                        {text: 'o World'}
+                    ]},
+                {type: 'paragraph', children: [{text: 'dog'}]},
+            ]);
+        });
+
+        it('should throw and error if an invalid position is provided', () => {
+            const {api, editor} = createEditorApiInstance();
+            insertAndSelectSampleBlock(editor);
+
+
+            expect(() => {
+                api.content.insertHtml('happy<p>cat</p>', 'near-the-end');
+            }).toThrow('Invalid position: near-the-end. Valid positions are: start, end, selection');
+        });
+
+        it('should append html if end provided as a position', () => {
+            const {api, editor} = createEditorApiInstance();
+            insertAndSelectSampleBlock(editor);
+
+            api.content.insertHtml('happy<p>cat</p>', 'end');
+            editor.commitUpdates();
+
+            expectNodeShapeToMatch(editor, [
+                {type: 'paragraph', children: [{text: 'Hello World'}]},
+                {type: 'paragraph', children: [{text: 'happy'}]},
+                {type: 'paragraph', children: [{text: 'cat'}]},
+            ]);
+        });
+
+        it('should prepend html if start provided as a position', () => {
+            const {api, editor} = createEditorApiInstance();
+            insertAndSelectSampleBlock(editor);
+
+            api.content.insertHtml('happy<p>cat</p>', 'start');
+            editor.commitUpdates();
+
+            expectNodeShapeToMatch(editor, [
+                {type: 'paragraph', children: [{text: 'happy'}]},
+                {type: 'paragraph', children: [{text: 'cat'}]},
+                {type: 'paragraph', children: [{text: 'Hello World'}]},
+            ]);
+        });
+    });
+
+    function insertAndSelectSampleBlock(editor: LexicalEditor) {
+        editor.updateAndCommit(() => {
+            const p = $createParagraphNode();
+            const text = $createTextNode('Hello World');
+            p.append(text);
+            $getRoot().append(p);
+
+            text.select(2, 4);
+        });
+    }
+
+});

resources/js/wysiwyg/api/api.ts

@@ -1,11 +1,14 @@
 import {EditorApiUiModule} from "./ui";
 import {EditorUiContext} from "../ui/framework/core";
+import {EditorApiContentModule} from "./content";
 
 export class EditorApi {
 
     public ui: EditorApiUiModule;
+    public content: EditorApiContentModule;
 
     constructor(context: EditorUiContext) {
         this.ui = new EditorApiUiModule(context);
+        this.content = new EditorApiContentModule(context);
     }
 }

resources/js/wysiwyg/api/content.ts

@@ -0,0 +1,26 @@
+import {EditorUiContext} from "../ui/framework/core";
+import {appendHtmlToEditor, insertHtmlIntoEditor, prependHtmlToEditor} from "../utils/actions";
+
+
+export class EditorApiContentModule {
+    readonly #context: EditorUiContext;
+
+    constructor(context: EditorUiContext) {
+        this.#context = context;
+    }
+
+    insertHtml(html: string, position: string = 'selection'): void {
+        const validPositions = ['start', 'end', 'selection'];
+        if (!validPositions.includes(position)) {
+            throw new Error(`Invalid position: ${position}. Valid positions are: ${validPositions.join(', ')}`);
+        }
+
+        if (position === 'start') {
+            prependHtmlToEditor(this.#context.editor, html);
+        } else if (position === 'end') {
+            appendHtmlToEditor(this.#context.editor, html);
+        } else {
+            insertHtmlIntoEditor(this.#context.editor, html);
+        }
+    }
+}