ckeditor5-livewire 1.8.0 → 1.10.0

package/src/hooks/editable.test.ts

@@ -50,6 +50,58 @@ describe('editable component', () => {
       expect(editor.getData({ rootName: 'foo' })).toBe('<p>Initial foo component</p>');
     });
 
+    it('should apply root attributes when mounting editable', async () => {
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        canonical: {
+          ...createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+          rootAttributes: {
+            'data-test': 'initial',
+          },
+        },
+      });
+
+      const root = editor.model.document.getRoot('foo')!;
+
+      expect(root.getAttribute('data-test')).toBe('initial');
+    });
+
+    it('should update root attributes after commit', async () => {
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+
+      const { id } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        canonical: {
+          ...createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+          rootAttributes: {
+            'data-test': 'initial',
+          },
+        },
+      });
+
+      const root = editor.model.document.getRoot('foo')!;
+
+      expect(root.getAttribute('data-test')).toBe('initial');
+
+      await livewireStub.$internal.dispatchComponentCommit(id, {
+        rootAttributes: {
+          'data-test': 'updated',
+        },
+      });
+
+      await vi.waitFor(() => {
+        expect(root.getAttribute('data-test')).toBe('updated');
+      });
+    });
+
     it('should add editable root to the editor after mounting editor (non-empty editor, other editable defined before)', async () => {
       livewireStub.$internal.appendComponentToDOM({
         name: 'ckeditor5-editable',
@@ -200,6 +252,9 @@ describe('editable component', () => {
 
       expect(input.value).toBe('<p>Initial foo component</p>');
 
+      // Debounce should be active only while the editor is focused.
+      editor.ui.focusTracker.isFocused = true;
+
       editor.setData({
         foo: '<p>Modified foo content</p>',
       });
@@ -212,6 +267,28 @@ describe('editable component', () => {
 
       expect(input.value).toBe('<p>Modified foo content</p>');
     });
+
+    it('should synchronize input value immediately when editor is not focused', async () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement({
+          id: 'editable-foo',
+        }),
+        canonical: createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+      });
+
+      const input = queryEditableInput('editable-foo')!;
+
+      expect(input.value).toBe('<p>Initial foo component</p>');
+
+      editor.ui.focusTracker.isFocused = false;
+
+      editor.setData({
+        foo: '<p>Modified foo content</p>',
+      });
+
+      expect(input.value).toBe('<p>Modified foo content</p>');
+    });
   });
 
   describe('livewire <> editor synchronization', () => {
@@ -250,6 +327,9 @@ describe('editable component', () => {
 
         expect($wire.set).toHaveBeenCalledWith('content', '<p>Initial foo component</p>');
 
+        // Debounce should be active only when the editor is focused.
+        editor.ui.focusTracker.isFocused = true;
+
         editor.setData({
           foo: '<p>Modified foo content</p>',
         });
@@ -262,6 +342,29 @@ describe('editable component', () => {
 
         expect($wire.set).toHaveBeenCalledWith('content', '<p>Modified foo content</p>');
       });
+
+      it('should synchronize socket content immediately when editor is not focused', async () => {
+        const { $wire } = livewireStub.$internal.appendComponentToDOM({
+          name: 'ckeditor5-editable',
+          el: createEditableHtmlElement(),
+          canonical: {
+            ...createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+            saveDebounceMs: 500,
+          },
+        });
+
+        expect($wire.set).toHaveBeenCalledWith('content', '<p>Initial foo component</p>');
+
+        vi.mocked($wire.set).mockClear();
+
+        editor.ui.focusTracker.isFocused = false;
+
+        editor.setData({
+          foo: '<p>Modified foo content</p>',
+        });
+
+        expect($wire.set).toHaveBeenCalledWith('content', '<p>Modified foo content</p>');
+      });
     });
 
     describe('sync editable content after commit', () => {

package/src/hooks/editable.ts

@@ -1,9 +1,11 @@
 import type { MultiRootEditor } from 'ckeditor5';
 
+import type { RootAttributesUpdater } from './utils';
+
 import { debounce } from '../shared';
 import { EditorsRegistry } from './editor/editors-registry';
-import { isWireModelConnected } from './editor/utils';
 import { ClassHook } from './hook';
+import { createRootAttributesUpdater, isWireModelConnected } from './utils';
 
 /**
  * Editable hook for Livewire. It allows you to create editables for multi-root editors.
@@ -14,6 +16,11 @@ export class EditableComponentHook extends ClassHook<Snapshot> {
    */
   private editorPromise: Promise<MultiRootEditor | null> | null = null;
 
+  /**
+   * The root attributes updater for the editable's root.
+   */
+  private rootAttributesUpdater: RootAttributesUpdater | null = null;
+
   /**
    * Pending content to apply when the editor loses focus.
    */
@@ -65,19 +72,64 @@ export class EditableComponentHook extends ClassHook<Snapshot> {
       // Add livewire sync.
       this.syncTypingContentPush(editor);
       this.setupPendingReceivedContentHandlers(editor);
+      this.applyRootAttributes(editor);
 
       return editor;
     });
   }
 
+  /**
+   * Called when the component is updated by Livewire.
+   */
+  override async afterCommitSynced(): Promise<void> {
+    const editor = (await this.editorPromise)!;
+
+    this.applyCanonicalContentToEditor(editor);
+    this.applyRootAttributes(editor);
+  }
+
+  /**
+   * Destroys the editable component. Unmounts root from the editor.
+   */
+  override async destroyed() {
+    const { rootName } = this.canonical;
+
+    // Let's hide the element during destruction to prevent flickering.
+    this.element.style.display = 'none';
+
+    // Let's wait for the mounted promise to resolve before proceeding with destruction.
+    const editor = await this.editorPromise;
+    this.editorPromise = null;
+
+    // Remove root attributes we may have set on this root.
+    this.rootAttributesUpdater?.(null);
+
+    // Unmount root from the editor if editor is still registered.
+    if (editor && editor.state !== 'destroyed') {
+      const root = editor.model.document.getRoot(rootName);
+
+      /* v8 ignore next if -- @preserve */
+      if (root && 'detachEditable' in editor) {
+        editor.detachEditable(root);
+        editor.detachRoot(rootName, false);
+      }
+    }
+  }
+
   /**
    * Setups the content sync from the editor to Livewire on user input with debounce.
    */
   private syncTypingContentPush(editor: MultiRootEditor) {
     const { rootName, saveDebounceMs } = this.canonical;
+
     const input = this.element.querySelector<HTMLInputElement>('input');
+    let isDestroyed = false;
 
     const sync = () => {
+      if (isDestroyed) {
+        return;
+      }
+
       const html = editor.getData({ rootName });
 
       if (input) {
@@ -88,12 +140,21 @@ export class EditableComponentHook extends ClassHook<Snapshot> {
     };
 
     const debouncedSync = debounce(saveDebounceMs, sync);
+    const onChangeData = () => {
+      if (editor.ui.focusTracker.isFocused) {
+        debouncedSync();
+      }
+      else {
+        sync();
+      }
+    };
 
-    editor.model.document.on('change:data', debouncedSync);
+    editor.model.document.on('change:data', onChangeData);
     sync();
 
     this.onBeforeDestroy(() => {
-      editor.model.document.off('change:data', debouncedSync);
+      isDestroyed = true;
+      editor.model.document.off('change:data', onChangeData);
     });
   }
 
@@ -155,37 +216,13 @@ export class EditableComponentHook extends ClassHook<Snapshot> {
   }
 
   /**
-   * Called when the component is updated by Livewire.
+   * Applies root attributes from the Livewire snapshot to the editor root.
    */
-  override async afterCommitSynced(): Promise<void> {
-    const editor = (await this.editorPromise)!;
+  private applyRootAttributes(editor: MultiRootEditor): void {
+    const { rootName, rootAttributes } = this.canonical;
 
-    this.applyCanonicalContentToEditor(editor);
-  }
-
-  /**
-   * Destroys the editable component. Unmounts root from the editor.
-   */
-  override async destroyed() {
-    const { rootName } = this.canonical;
-
-    // Let's hide the element during destruction to prevent flickering.
-    this.element.style.display = 'none';
-
-    // Let's wait for the mounted promise to resolve before proceeding with destruction.
-    const editor = await this.editorPromise;
-    this.editorPromise = null;
-
-    // Unmount root from the editor if editor is still registered.
-    if (editor && editor.state !== 'destroyed') {
-      const root = editor.model.document.getRoot(rootName);
-
-      /* v8 ignore next if -- @preserve */
-      if (root && 'detachEditable' in editor) {
-        editor.detachEditable(root);
-        editor.detachRoot(rootName, false);
-      }
-    }
+    this.rootAttributesUpdater ??= createRootAttributesUpdater(editor, rootName);
+    this.rootAttributesUpdater(rootAttributes);
   }
 }
 
@@ -212,4 +249,9 @@ export type Snapshot = {
    * The debounce time in milliseconds for saving changes.
    */
   saveDebounceMs: number;
+
+  /**
+   * Root attributes to apply to the editable root.
+   */
+  rootAttributes?: Record<string, unknown>;
 };

package/src/hooks/editor/editor.test.ts

@@ -375,6 +375,53 @@ describe('editor component', () => {
         }).not.toThrow();
       });
     });
+
+    describe('root attributes', () => {
+      it('should apply root attributes from snapshot', async () => {
+        const { id } = livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+          name: 'ckeditor5',
+          el: createEditorHtmlElement(),
+          canonical: createEditorSnapshot({
+            rootAttributes: {
+              'data-test': 'initial',
+              'foo': 'bar',
+            },
+          }),
+        });
+
+        const editor = await waitForTestEditor();
+        const root = editor.model.document.getRoot('main')!;
+
+        expect(root.getAttribute('data-test')).toBe('initial');
+        expect(root.getAttribute('foo')).toBe('bar');
+
+        // Ensure attributes managed by other consumers are not removed.
+        editor.model.change((writer) => {
+          writer.setAttribute('external', 'value', root);
+        });
+
+        await livewireStub.$internal.dispatchComponentCommit<EditorSnapshot>(id, {
+          rootAttributes: {
+            'data-test': 'updated',
+          },
+        });
+
+        await vi.waitFor(() => {
+          expect(root.getAttribute('data-test')).toBe('updated');
+          expect(root.getAttribute('foo')).toBeUndefined();
+          expect(root.getAttribute('external')).toBe('value');
+        });
+
+        await livewireStub.$internal.dispatchComponentCommit<EditorSnapshot>(id, {
+          rootAttributes: null as any,
+        });
+
+        await vi.waitFor(() => {
+          expect(root.getAttribute('data-test')).toBeUndefined();
+          expect(root.getAttribute('external')).toBe('value');
+        });
+      });
+    });
   });
 
   describe('`editableHeight` snapshot parameter`', () => {
@@ -432,6 +479,9 @@ describe('editor component', () => {
 
       const editor = await waitForTestEditor();
 
+      // Debounce should only be applied while the editor is focused.
+      editor.ui.focusTracker.isFocused = true;
+
       vi.mocked($wire.set).mockClear();
       editor.setData('<p>Debounce test</p>');
 
@@ -442,6 +492,24 @@ describe('editor component', () => {
       expect($wire.set).toHaveBeenCalledExactlyOnceWith('content', { main: '<p>Debounce test</p>' });
     });
 
+    it('should immediately send `$wire.set` when editor is not focused', async () => {
+      const { $wire } = livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+        name: 'ckeditor5',
+        el: createEditorHtmlElement(),
+        canonical: {
+          ...createEditorSnapshot(),
+          saveDebounceMs: 400,
+        },
+      });
+
+      const editor = await waitForTestEditor();
+
+      vi.mocked($wire.set).mockClear();
+      editor.setData('<p>Debounce test</p>');
+
+      expect($wire.set).toHaveBeenCalledExactlyOnceWith('content', { main: '<p>Debounce test</p>' });
+    });
+
     it('should use parameter to debounce input sync', async () => {
       livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
         name: 'ckeditor5',

package/src/hooks/editor/editor.ts

@@ -1,11 +1,13 @@
 import type { Editor } from 'ckeditor5';
 
+import type { RootAttributesUpdater } from '../utils';
 import type { EditorId, EditorLanguage, EditorPreset } from './typings';
 import type { EditorCreator } from './utils';
 
 import { ContextsRegistry } from '../../hooks/context';
 import { isEmptyObject, waitFor } from '../../shared';
 import { ClassHook } from '../hook';
+import { createRootAttributesUpdater } from '../utils';
 import { EditorsRegistry } from './editors-registry';
 import {
   createLivewireSyncPlugin,
@@ -37,6 +39,11 @@ export class EditorComponentHook extends ClassHook<Snapshot> {
    */
   private editorPromise: Promise<Editor> | null = null;
 
+  /**
+   * Root attributes updater for the main editor root.
+   */
+  private rootAttributesUpdater: RootAttributesUpdater | null = null;
+
   /**
    * @inheritdoc
    */
@@ -115,7 +122,23 @@ export class EditorComponentHook extends ClassHook<Snapshot> {
   override async afterCommitSynced(): Promise<void> {
     const editor = await this.editorPromise;
 
-    editor?.fire('afterCommitSynced');
+    /* v8 ignore if -- @preserve */
+    if (editor) {
+      editor.fire('afterCommitSynced');
+      this.applyRootAttributes(editor);
+    }
+  }
+
+  /**
+   * Applies root attributes from the Livewire snapshot to the editor.
+   *
+   * Note: we only apply attributes to the `main` root in the editor.
+   */
+  private applyRootAttributes(editor: Editor): void {
+    const { rootAttributes } = this.canonical;
+
+    this.rootAttributesUpdater ??= createRootAttributesUpdater(editor, 'main');
+    this.rootAttributesUpdater(rootAttributes);
   }
 
   /**
@@ -261,6 +284,8 @@ export class EditorComponentHook extends ClassHook<Snapshot> {
       setEditorEditableHeight(editor, editableHeight);
     }
 
+    this.applyRootAttributes(editor);
+
     return editor;
   };
 }
@@ -350,4 +375,9 @@ export type Snapshot = {
    * The language of the editor UI and content.
    */
   language: EditorLanguage;
+
+  /**
+   * Root attributes to apply to the main editor root.
+   */
+  rootAttributes?: Record<string, unknown>;
 };

package/src/hooks/editor/plugins/livewire-sync.ts

@@ -3,7 +3,8 @@ import type { PluginConstructor } from 'ckeditor5';
 import type { EditorComponentHook } from '../editor';
 
 import { debounce, shallowEqual } from '../../../shared';
-import { getEditorRootsValues, isWireModelConnected } from '../utils';
+import { isWireModelConnected } from '../../utils';
+import { getEditorRootsValues } from '../utils';
 
 /**
  * Creates a LivewireSync plugin class.
@@ -124,10 +125,18 @@ export async function createLivewireSyncPlugin(
      * Setups the content push event for the editor.
      */
     private setupTypingContentPush() {
-      const { model } = this.editor;
+      const { editor } = this;
+      const { model, ui } = editor;
       const { $wire } = component;
 
+      let isDestroyed = false;
+
       const syncContentChange = () => {
+        /* v8 ignore next if -- @preserve */
+        if (isDestroyed) {
+          return;
+        }
+
         const values = this.getEditorRootsValues();
 
         // Prevent looping when editor changed content from Livewire.
@@ -140,8 +149,23 @@ export async function createLivewireSyncPlugin(
         }
       };
 
-      model.document.on('change:data', debounce(saveDebounceMs, syncContentChange));
-      this.editor.once('ready', syncContentChange);
+      const debouncedSync = debounce(saveDebounceMs, syncContentChange);
+      const onChangeData = () => {
+        if (ui.focusTracker.isFocused) {
+          debouncedSync();
+        }
+        else {
+          syncContentChange();
+        }
+      };
+
+      model.document.on('change:data', onChangeData);
+
+      editor.once('ready', syncContentChange);
+      editor.once('destroy', () => {
+        isDestroyed = true;
+        model.document.off('change:data', onChangeData);
+      });
     }
 
     /**

package/src/hooks/editor/utils/index.ts

@@ -1,7 +1,6 @@
 export * from './create-editor-in-context';
 export * from './get-editor-roots-values';
 export * from './is-single-root-editor';
-export * from './is-wire-model-connected';
 export * from './load-editor-constructor';
 export * from './load-editor-plugins';
 export * from './load-editor-translations';

package/src/hooks/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './is-wire-model-connected';
+export * from './root-attributes-updater';

package/src/hooks/{editor/utils → utils}/is-wire-model-connected.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { html } from '../../../../test-utils/html';
+import { html } from '~/test-utils/html';
+
 import { isWireModelConnected } from './is-wire-model-connected';
 
 describe('isWireModelConnected', () => {

package/src/hooks/{editor/utils → utils}/is-wire-model-connected.ts

@@ -1,3 +1,9 @@
+/**
+ * Checks if the given element is connected to a wire:model directive in its ancestry.
+ *
+ * @param element - The HTML element to check for wire:model connection.
+ * @returns True if the element is connected to a wire:model directive, false otherwise.
+ */
 export function isWireModelConnected(element: HTMLElement): boolean {
   let parent: HTMLElement | null = element;
 

package/src/hooks/utils/root-attributes-updater.ts

@@ -0,0 +1,46 @@
+import type { Editor } from 'ckeditor5';
+
+/**
+ * Creates a function that synchronizes root attributes on the given editor root.
+ *
+ * The returned function tracks which attributes were set by itself and will only
+ * remove attributes it previously managed. This avoids interfering with other
+ * consumers that may also change attributes on the same root.
+ *
+ * @param editor The editor instance containing the root to manage.
+ * @param rootName The name of the root to manage attributes on.
+ * @returns A function that can be called with the desired set of attributes to apply them to the root.
+ *          Calling the function with `null` or an empty object will clear all attributes previously set by it.
+ */
+export function createRootAttributesUpdater(editor: Editor, rootName: string): RootAttributesUpdater {
+  const managedAttrs = new Set<string>();
+
+  return (rootAttributes?: Record<string, unknown> | null) => {
+    editor.model.enqueueChange({ isUndoable: false }, (writer) => {
+      const root = editor.model.document.getRoot(rootName);
+
+      /* v8 ignore next if -- @preserve */
+      if (!root) {
+        return;
+      }
+
+      // Remove previously managed attributes that are no longer requested.
+      for (const key of managedAttrs) {
+        if (rootAttributes && key in rootAttributes) {
+          continue;
+        }
+
+        writer.removeAttribute(key, root);
+        managedAttrs.delete(key);
+      }
+
+      // Apply or overwrite requested attributes.
+      for (const [key, value] of Object.entries(rootAttributes ?? {})) {
+        writer.setAttribute(key, value, root);
+        managedAttrs.add(key);
+      }
+    });
+  };
+}
+
+export type RootAttributesUpdater = (rootAttributes?: Record<string, unknown> | null) => void;

package/dist/hooks/editor/utils/is-wire-model-connected.d.ts

@@ -1,2 +0,0 @@
-export declare function isWireModelConnected(element: HTMLElement): boolean;
-//# sourceMappingURL=is-wire-model-connected.d.ts.map

package/dist/hooks/editor/utils/is-wire-model-connected.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-wire-model-connected.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/editor/utils/is-wire-model-connected.ts"],"names":[],"mappings":"AAAA,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAalE"}