ckeditor5-livewire 0.0.1

package/src/hooks/editor/utils/normalize-custom-translations.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+
+import type { EditorCustomTranslationsDictionary } from '../typings';
+
+import { normalizeCustomTranslations } from './normalize-custom-translations';
+
+describe('normalizeCustomTranslations', () => {
+  it('should normalize empty translations object', () => {
+    const input: EditorCustomTranslationsDictionary = {};
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({});
+  });
+
+  it('should normalize single language translation', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      en: {
+        Bold: 'Bold Text',
+        Italic: 'Italic Text',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      en: {
+        dictionary: {
+          Bold: 'Bold Text',
+          Italic: 'Italic Text',
+        },
+      },
+    });
+  });
+
+  it('should normalize multiple language translations', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      en: {
+        Bold: 'Bold Text',
+        Italic: 'Italic Text',
+      },
+      pl: {
+        Bold: 'Pogrubienie',
+        Italic: 'Kursywa',
+      },
+      de: {
+        Bold: 'Fett',
+        Italic: 'Kursiv',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      en: {
+        dictionary: {
+          Bold: 'Bold Text',
+          Italic: 'Italic Text',
+        },
+      },
+      pl: {
+        dictionary: {
+          Bold: 'Pogrubienie',
+          Italic: 'Kursywa',
+        },
+      },
+      de: {
+        dictionary: {
+          Bold: 'Fett',
+          Italic: 'Kursiv',
+        },
+      },
+    });
+  });
+
+  it('should handle empty dictionary for a language', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      en: {},
+      pl: {
+        Bold: 'Pogrubienie',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      en: {
+        dictionary: {},
+      },
+      pl: {
+        dictionary: {
+          Bold: 'Pogrubienie',
+        },
+      },
+    });
+  });
+
+  it('should preserve special characters and unicode in translations', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      zh: {
+        粗体: '加粗文本',
+        斜体: '斜体文本',
+      },
+      ar: {
+        Bold: 'عريض',
+        Italic: 'مائل',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      zh: {
+        dictionary: {
+          粗体: '加粗文本',
+          斜体: '斜体文本',
+        },
+      },
+      ar: {
+        dictionary: {
+          Bold: 'عريض',
+          Italic: 'مائل',
+        },
+      },
+    });
+  });
+
+  it('should handle language codes with regions', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      'en-US': {
+        Color: 'Color',
+      },
+      'en-GB': {
+        Color: 'Colour',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      'en-US': {
+        dictionary: {
+          Color: 'Color',
+        },
+      },
+      'en-GB': {
+        dictionary: {
+          Color: 'Colour',
+        },
+      },
+    });
+  });
+});

package/src/hooks/editor/utils/normalize-custom-translations.ts

@@ -0,0 +1,18 @@
+import type { Translations } from 'ckeditor5';
+
+import type { EditorCustomTranslationsDictionary } from '../typings';
+
+import { mapObjectValues } from '../../../shared';
+
+/**
+ * This function takes a custom translations object and maps it to the format expected by CKEditor5.
+ * Each translation dictionary is wrapped in an object with a `dictionary` key.
+ *
+ * @param translations - The custom translations to normalize.
+ * @returns A normalized translations object suitable for CKEditor5.
+ */
+export function normalizeCustomTranslations(translations: EditorCustomTranslationsDictionary): Translations {
+  return mapObjectValues(translations, dictionary => ({
+    dictionary,
+  }));
+}

package/src/hooks/editor/utils/query-editor-editables.ts

@@ -0,0 +1,102 @@
+import type { EditorId, EditorType } from '../typings';
+
+import { filterObjectValues, mapObjectValues } from '../../../shared';
+import { isSingleEditingLikeEditor } from './is-single-editing-like-editor';
+
+/**
+ * Queries all editable elements within a specific editor instance.
+ *
+ * @param editorId The ID of the editor to query.
+ * @returns An object mapping editable names to their corresponding elements and initial values.
+ */
+export function queryAllEditorEditables(editorId: EditorId): Record<string, EditableItem> {
+  return (
+    window.Livewire
+      .all()
+      .filter(({ name, ephemeral }) => name === 'ckeditor5-editable' && ephemeral['editorId'] === editorId)
+      .reduce<Record<string, EditableItem>>((acc, { ephemeral, el }) => ({
+        ...acc,
+        [ephemeral['rootName'] as string]: {
+          element: el.querySelector('[data-cke-editable-content]')!,
+          content: ephemeral['content'],
+        },
+      }), Object.create({}))
+  );
+}
+
+/**
+ * Gets the initial root elements for the editor based on its type.
+ *
+ * @param editorId The editor's ID.
+ * @param type The type of the editor.
+ * @returns The root element(s) for the editor.
+ */
+export function queryEditablesElements(editorId: EditorId, type: EditorType) {
+  // While the `decoupled` editor is a single editing-like editor, it has a different structure
+  // and requires special handling to get the main editable.
+  if (type === 'decoupled') {
+    const { element } = queryDecoupledMainEditableOrThrow(editorId);
+
+    return element;
+  }
+
+  if (isSingleEditingLikeEditor(type)) {
+    return document.getElementById(`${editorId}_editor`)!;
+  }
+
+  const editables = queryAllEditorEditables(editorId);
+
+  return mapObjectValues(editables, ({ element }) => element);
+}
+
+/**
+ * Gets the initial data for the roots of the editor. If the editor is a single editing-like editor,
+ * it retrieves the initial value from the element's attribute. Otherwise, it returns an object mapping
+ * editable names to their initial values.
+ *
+ * @param editorId The editor's ID.
+ * @param type The type of the editor.
+ * @returns The initial values for the editor's roots.
+ */
+export function queryEditablesSnapshotContent(editorId: EditorId, type: EditorType) {
+  // While the `decoupled` editor is a single editing-like editor, it has a different structure
+  // and requires special handling to get the main editable.
+  if (type === 'decoupled') {
+    const { content } = queryDecoupledMainEditableOrThrow(editorId);
+
+    // If initial value is not set, then pick it from the editor element.
+    if (typeof content === 'string') {
+      return {
+        main: content,
+      };
+    }
+  }
+
+  const editables = queryAllEditorEditables(editorId);
+  const values = mapObjectValues(editables, ({ content }) => content);
+
+  return filterObjectValues(values, value => typeof value === 'string') as Record<string, string>;
+}
+
+/**
+ * Queries the main editable for a decoupled editor and throws an error if not found.
+ *
+ * @param editorId The ID of the editor to query.
+ */
+function queryDecoupledMainEditableOrThrow(editorId: EditorId) {
+  const mainEditable = queryAllEditorEditables(editorId)['main'];
+
+  if (!mainEditable) {
+    throw new Error(`No "main" editable found for editor with ID "${editorId}".`);
+  }
+
+  return mainEditable;
+}
+
+/**
+ * Type representing an editable item within an editor.
+ */
+export type EditableItem = {
+  element: HTMLElement;
+  content: string | null;
+};

package/src/hooks/editor/utils/resolve-editor-config-elements-references.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { resolveEditorConfigElementReferences } from './resolve-editor-config-elements-references';
+
+describe('resolveEditorConfigElementReferences', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('resolves a single element reference', () => {
+    const div = document.createElement('div');
+    div.id = 'test-div';
+    document.body.appendChild(div);
+
+    const config = {
+      foo: { $element: '#test-div' },
+    };
+
+    const result = resolveEditorConfigElementReferences(config);
+    expect(result.foo).toBe(div);
+  });
+
+  it('returns null if element not found', () => {
+    const config = {
+      foo: { $element: '#not-exist' },
+    };
+    const result = resolveEditorConfigElementReferences(config);
+
+    expect(result.foo).toBeNull();
+  });
+
+  it('recursively resolves nested element references', () => {
+    const span = document.createElement('span');
+    span.className = 'my-span';
+    document.body.appendChild(span);
+
+    const config = {
+      nested: {
+        bar: { $element: '.my-span' },
+      },
+    };
+
+    const result = resolveEditorConfigElementReferences(config);
+    expect(result.nested.bar).toBe(span);
+  });
+
+  it('resolves element references in arrays', () => {
+    const el1 = document.createElement('div');
+    el1.id = 'el1';
+    document.body.appendChild(el1);
+
+    const el2 = document.createElement('div');
+    el2.id = 'el2';
+    document.body.appendChild(el2);
+
+    const config = [
+      { $element: '#el1' },
+      { $element: '#el2' },
+      { notElement: 123 },
+    ];
+
+    const result = resolveEditorConfigElementReferences(config);
+
+    expect(result[0]).toBe(el1);
+    expect(result[1]).toBe(el2);
+    expect(result[2]).toEqual({ notElement: 123 });
+  });
+
+  it('returns primitives as is', () => {
+    expect(resolveEditorConfigElementReferences(42)).toBe(42);
+    expect(resolveEditorConfigElementReferences('foo')).toBe('foo');
+    expect(resolveEditorConfigElementReferences(null)).toBe(null);
+    expect(resolveEditorConfigElementReferences(undefined)).toBe(undefined);
+  });
+
+  it('warns for invalid selector type', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const config = { foo: { $element: '.foo' } };
+
+    resolveEditorConfigElementReferences(config);
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Element not found for selector: .foo'));
+    warnSpy.mockRestore();
+  });
+
+  it('warns if element not found', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const config = { foo: { $element: '#not-found' } };
+
+    resolveEditorConfigElementReferences(config);
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Element not found'));
+    warnSpy.mockRestore();
+  });
+});

package/src/hooks/editor/utils/resolve-editor-config-elements-references.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolves element references in configuration object.
+ * Looks for objects with { $element: "selector" } format and replaces them with actual DOM elements.
+ *
+ * @param obj - Configuration object to process
+ * @returns Processed configuration object with resolved element references
+ */
+export function resolveEditorConfigElementReferences<T>(obj: T): T {
+  if (!obj || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => resolveEditorConfigElementReferences(item)) as T;
+  }
+
+  const anyObj = obj as any;
+
+  if (anyObj.$element && typeof anyObj.$element === 'string') {
+    const element = document.querySelector(anyObj.$element);
+
+    if (!element) {
+      console.warn(`Element not found for selector: ${anyObj.$element}`);
+    }
+
+    return (element || null) as T;
+  }
+
+  const result = Object.create(null);
+
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = resolveEditorConfigElementReferences(value);
+  }
+
+  return result as T;
+}

package/src/hooks/editor/utils/set-editor-editable-height.test.ts

@@ -0,0 +1,131 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { setEditorEditableHeight } from './set-editor-editable-height';
+
+// Mock CKEditor5 types and interfaces
+const mockWriter = {
+  setStyle: vi.fn(),
+};
+
+const mockRoot = {
+  // Mock root element
+};
+
+const mockViewDocument = {
+  getRoot: vi.fn(() => mockRoot),
+};
+
+const mockView = {
+  change: vi.fn(callback => callback(mockWriter)),
+  document: mockViewDocument,
+};
+
+const mockEditing = {
+  view: mockView,
+};
+
+const mockEditor = {
+  editing: mockEditing,
+};
+
+describe('setEditorEditableHeight', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should set height style on editor root element', () => {
+    const height = 300;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockView.change).toHaveBeenCalledWith(expect.any(Function));
+    expect(mockViewDocument.getRoot).toHaveBeenCalled();
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '300px', mockRoot);
+  });
+
+  it('should handle different height values', () => {
+    const heights = [100, 200, 500, 1000];
+
+    heights.forEach((height) => {
+      vi.clearAllMocks();
+
+      setEditorEditableHeight(mockEditor as any, height);
+
+      expect(mockWriter.setStyle).toHaveBeenCalledWith('height', `${height}px`, mockRoot);
+    });
+  });
+
+  it('should handle zero height', () => {
+    const height = 0;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '0px', mockRoot);
+  });
+
+  it('should handle negative height values', () => {
+    const height = -100;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '-100px', mockRoot);
+  });
+
+  it('should handle decimal height values', () => {
+    const height = 250.5;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '250.5px', mockRoot);
+  });
+
+  it('should call view.change with correct callback', () => {
+    const height = 400;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockView.change).toHaveBeenCalledTimes(1);
+    expect(mockView.change).toHaveBeenCalledWith(expect.any(Function));
+  });
+
+  it('should work with different editor instances', () => {
+    const anotherMockEditor = {
+      editing: {
+        view: {
+          change: vi.fn(callback => callback(mockWriter)),
+          document: {
+            getRoot: vi.fn(() => mockRoot),
+          },
+        },
+      },
+    };
+
+    const height = 350;
+
+    setEditorEditableHeight(anotherMockEditor as any, height);
+
+    expect(anotherMockEditor.editing.view.change).toHaveBeenCalledWith(expect.any(Function));
+    expect(anotherMockEditor.editing.view.document.getRoot).toHaveBeenCalled();
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '350px', mockRoot);
+  });
+
+  it('should handle editor with null root gracefully', () => {
+    const mockEditorWithNullRoot = {
+      editing: {
+        view: {
+          change: vi.fn(callback => callback(mockWriter)),
+          document: {
+            getRoot: vi.fn(() => null),
+          },
+        },
+      },
+    };
+
+    const height = 200;
+
+    // Should not throw error even with null root
+    expect(() => setEditorEditableHeight(mockEditorWithNullRoot as any, height)).not.toThrow();
+
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '200px', null);
+  });
+});

package/src/hooks/editor/utils/set-editor-editable-height.ts

@@ -0,0 +1,15 @@
+import type { Editor } from 'ckeditor5';
+
+/**
+ * Sets the height of the editable area in the CKEditor instance.
+ *
+ * @param instance - The CKEditor instance to modify.
+ * @param height - The height in pixels to set for the editable area.
+ */
+export function setEditorEditableHeight(instance: Editor, height: number): void {
+  const { editing } = instance;
+
+  editing.view.change((writer) => {
+    writer.setStyle('height', `${height}px`, editing.view.document.getRoot()!);
+  });
+}

package/src/hooks/editor/utils/wrap-with-watchdog.test.ts

@@ -0,0 +1,45 @@
+import { ClassicEditor, EditorWatchdog } from 'ckeditor5';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { unwrapEditorWatchdog, wrapWithWatchdog } from './wrap-with-watchdog';
+
+describe('wrap with watchdog', () => {
+  let element: HTMLElement;
+
+  beforeEach(async () => {
+    element = document.createElement('div');
+    document.body.appendChild(element);
+  });
+
+  afterEach(() => {
+    element.remove();
+  });
+
+  it('returns editor instance after calling Constructor.create', async () => {
+    const { Constructor } = await wrapWithWatchdog(ClassicEditor);
+    const editor = await Constructor.create(element, {
+      licenseKey: 'GPL',
+    });
+
+    expect(editor).toBeInstanceOf(ClassicEditor);
+
+    await editor.destroy();
+  });
+
+  it('returns instance of watchdog', async () => {
+    const { watchdog } = await wrapWithWatchdog(ClassicEditor);
+
+    expect(watchdog).toBeInstanceOf(EditorWatchdog);
+  });
+
+  it('should be possible to unwrap watchdog from editor instance', async () => {
+    const { Constructor } = await wrapWithWatchdog(ClassicEditor);
+    const editor = await Constructor.create(element, {
+      licenseKey: 'GPL',
+    });
+
+    expect(unwrapEditorWatchdog(editor)).toBeInstanceOf(EditorWatchdog);
+
+    await editor.destroy();
+  });
+});

package/src/hooks/editor/utils/wrap-with-watchdog.ts

@@ -0,0 +1,51 @@
+import type { Editor, EditorWatchdog } from 'ckeditor5';
+
+const EDITOR_WATCHDOG_SYMBOL = Symbol.for('elixir-editor-watchdog');
+
+/**
+ * Wraps an Editor creator with a watchdog for automatic recovery.
+ *
+ * @param Editor - The Editor creator to wrap.
+ * @returns The Editor creator wrapped with a watchdog.
+ */
+export async function wrapWithWatchdog(Editor: EditorCreator) {
+  const { EditorWatchdog } = await import('ckeditor5');
+  const watchdog = new EditorWatchdog(Editor);
+
+  watchdog.setCreator(async (...args: Parameters<typeof Editor['create']>) => {
+    const editor = await Editor.create(...args);
+
+    (editor as any)[EDITOR_WATCHDOG_SYMBOL] = watchdog;
+
+    return editor;
+  });
+
+  return {
+    watchdog,
+    Constructor: {
+      create: async (...args: Parameters<typeof Editor['create']>) => {
+        await watchdog.create(...args);
+
+        return watchdog.editor!;
+      },
+    },
+  };
+}
+
+/**
+ * Unwraps the EditorWatchdog from the editor instance.
+ */
+export function unwrapEditorWatchdog(editor: Editor): EditorWatchdog | null {
+  if (EDITOR_WATCHDOG_SYMBOL in editor) {
+    return (editor as any)[EDITOR_WATCHDOG_SYMBOL] as EditorWatchdog;
+  }
+
+  return null;
+}
+
+/**
+ * Type representing an Editor creator with a create method.
+ */
+export type EditorCreator = {
+  create: (...args: any) => Promise<Editor>;
+};