ckeditor5-symfony 1.0.0

package/src/elements/editor/utils/query-all-editor-ids.ts

@@ -0,0 +1,9 @@
+/**
+ * Queries all CKEditor 5 editor IDs present in the document.
+ */
+export function queryAllEditorIds(): string[] {
+  return Array
+    .from(document.querySelectorAll<HTMLElement>('cke5-editor'))
+    .map(element => element.getAttribute('data-cke-editor-id'))
+    .filter((id): id is string => id !== null);
+}

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

@@ -0,0 +1,101 @@
+import type { EditorId } from '../typings';
+
+import { filterObjectValues, mapObjectValues } from '../../../shared';
+
+/**
+ * Gets the initial root elements for the editor based on its type.
+ *
+ * @param editorId The editor's ID.
+ * @returns The root element(s) for the editor.
+ */
+export function queryEditablesElements(editorId: EditorId) {
+  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.
+ * @returns The initial values for the editor's roots.
+ */
+export function queryEditablesSnapshotContent(editorId: EditorId) {
+  const editables = queryAllEditorEditables(editorId);
+  const values = mapObjectValues(editables, ({ content }) => content);
+
+  return filterObjectValues(values, value => typeof value === 'string') as Record<string, string>;
+}
+
+/**
+ * Queries all editable elements within a specific editor instance. It picks
+ * initial values from actually rendered elements or from the editor container's.
+ *
+ * It may differ from the `initialData` used during editor creation, as it might
+ * not set all roots or set different values.
+ *
+ * @param editorId The ID of the editor to query.
+ * @returns An object mapping editable names to their corresponding elements and initial values.
+ */
+function queryAllEditorEditables(editorId: EditorId) {
+  const acc = (
+    Array
+      .from(document.querySelectorAll<HTMLElement>(`cke5-editable[data-cke-editor-id="${editorId}"]`))
+      .reduce<Record<string, EditableItem>>((acc, element) => {
+        const rootName = element.getAttribute('data-cke-root-name')!;
+        const content = element.getAttribute('data-cke-content');
+
+        acc[rootName] = {
+          element: element.querySelector<HTMLElement>('[data-cke-editable-content]')!,
+          content,
+        };
+
+        return acc;
+      }, Object.create({}))
+  );
+
+  const editor = document.querySelector<HTMLElement>(`cke5-editor[data-cke-editor-id="${editorId}"]`);
+
+  /* v8 ignore next 3 */
+  if (!editor) {
+    return acc;
+  }
+
+  const currentMain = acc['main'];
+  const initialRootEditableValue = JSON.parse(editor.getAttribute('data-cke-content')!);
+  const contentElement = document.querySelector<HTMLElement>(`#${editorId}_editor `);
+
+  // If found `main` editable, but it has no content, try to fill it from the editor container.
+  if (currentMain && initialRootEditableValue?.['main']) {
+    return {
+      ...acc,
+      main: {
+        ...currentMain,
+        content: currentMain.content || initialRootEditableValue['main'],
+      },
+    };
+  }
+
+  // If no `main` editable found, try to create it from the editor container.
+  if (contentElement) {
+    return {
+      ...acc,
+      main: {
+        element: contentElement,
+        content: initialRootEditableValue?.['main'] || null,
+      },
+    };
+  }
+
+  return acc;
+}
+
+/**
+ * Type representing an editable item within an editor.
+ */
+export type EditableItem = {
+  element: HTMLElement;
+  content: string | null;
+};

package/src/elements/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/elements/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/elements/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/elements/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/elements/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/elements/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>;
+};

package/src/elements/index.ts

@@ -0,0 +1,14 @@
+export {
+  ContextComponentElement,
+  type ContextConfig,
+  type ContextCreatorConfig,
+  ContextsRegistry,
+} from './context';
+export { EditableComponentElement } from './editable';
+export {
+  type EditorCloudConfig,
+  EditorComponentElement,
+  type EditorConfig,
+} from './editor';
+export { registerCustomElements } from './register-custom-elements';
+export { UIPartComponentElement } from './ui-part';

package/src/elements/register-custom-elements.ts

@@ -0,0 +1,24 @@
+import { ContextComponentElement } from './context';
+import { EditableComponentElement } from './editable';
+import { EditorComponentElement } from './editor';
+import { UIPartComponentElement } from './ui-part';
+
+const CUSTOM_ELEMENTS = {
+  'cke5-editor': EditorComponentElement,
+  'cke5-context': ContextComponentElement,
+  'cke5-ui-part': UIPartComponentElement,
+  'cke5-editable': EditableComponentElement,
+};
+
+/**
+ * Registers all available Symfony component hooks.
+ */
+export function registerCustomElements() {
+  for (const [name, CustomElement] of Object.entries(CUSTOM_ELEMENTS)) {
+    if (window.customElements.get(name)) {
+      continue;
+    }
+
+    window.customElements.define(name, CustomElement);
+  }
+}

package/src/elements/ui-part.test.ts

@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createEditorPreset,
+  createUIPartSnapshot,
+  renderTestEditor,
+  renderTestUIPart,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { CustomEditorPluginsRegistry } from './editor/custom-editor-plugins';
+import { EditorsRegistry } from './editor/editors-registry';
+import { registerCustomElements } from './register-custom-elements';
+
+describe('ui-part component', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    registerCustomElements();
+  });
+
+  afterEach(async () => {
+    document.body.innerHTML = '';
+    CustomEditorPluginsRegistry.the.unregisterAll();
+    EditorsRegistry.the.reset();
+    vi.restoreAllMocks();
+  });
+
+  describe('mounting ui part', () => {
+    it('should mount toolbar to the editor after mounting editor', async () => {
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+      const toolbarElement = editor.ui.view.toolbar?.element;
+
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      await vi.waitFor(() => {
+        expect(el.contains(toolbarElement!)).toBe(true);
+      });
+
+      expect(toolbarElement).toBeTruthy();
+    });
+
+    it('should mount menubar to the editor after mounting editor', async () => {
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+      const menubarElement = (editor.ui.view as any).menuBarView.element;
+
+      const el = renderTestUIPart(createUIPartSnapshot('menubar'));
+
+      await vi.waitFor(() => {
+        expect(el.children.length).toBeGreaterThan(0);
+      });
+
+      expect(el.contains(menubarElement)).toBe(true);
+    });
+
+    it('should mount UI part before editor is created', async () => {
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+      const toolbarElement = editor.ui.view.toolbar?.element;
+
+      await vi.waitFor(() => {
+        expect(el.contains(toolbarElement!)).toBe(true);
+      });
+
+      expect(toolbarElement).toBeTruthy();
+    });
+
+    it('should default to first editor ID if data-cke-editor-id is missing', async () => {
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+      const toolbarElement = editor.ui.view.toolbar?.element;
+
+      // Render UI part without editorId
+      const el = renderTestUIPart({ editorId: undefined } as any);
+
+      await vi.waitFor(() => {
+        expect(el.contains(toolbarElement!)).toBe(true);
+      });
+
+      expect(toolbarElement).toBeTruthy();
+    });
+  });
+
+  describe('destroying ui part', () => {
+    beforeEach(async () => {
+      appendMultirootEditor();
+      await waitForTestEditor();
+    });
+
+    it('should clear UI part element on destruction', async () => {
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      await vi.waitFor(() => {
+        expect(el.children.length).toBeGreaterThan(0);
+      });
+
+      el.remove();
+
+      await vi.waitFor(() => {
+        expect(el.innerHTML).toBe('');
+      });
+
+      expect(el.style.display).toBe('none');
+    });
+
+    it('should hide element during destruction', async () => {
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      // If we remove immediately, disconnectedCallback should hide it.
+      el.remove();
+
+      // Ensure style is updated synchronously or microtask
+      expect(el.style.display).toBe('none');
+    });
+
+    it('should handle destruction when mounted promise is not resolved yet', async () => {
+      document.body.innerHTML = '';
+      EditorsRegistry.the.reset();
+
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      el.remove();
+
+      expect(el.innerHTML).toBe('');
+      expect(el.style.display).toBe('none');
+    });
+  });
+
+  function appendMultirootEditor(initialContent: Record<string, string> = {}) {
+    renderTestEditor({
+      preset: createEditorPreset('multiroot'),
+      content: initialContent,
+    });
+  }
+});