ckeditor5-phoenix 0.1.0

package/src/hooks/editor/utils/load-editor-plugins.ts

@@ -0,0 +1,50 @@
+import type { PluginConstructor } from 'ckeditor5';
+
+import type { EditorPlugin } from '../typings';
+
+/**
+ * Loads CKEditor plugins from base and premium packages.
+ * First tries to load from the base 'ckeditor5' package, then falls back to 'ckeditor5-premium-features'.
+ *
+ * @param plugins - Array of plugin names to load
+ * @returns Promise that resolves to an array of loaded Plugin instances
+ * @throws Error if a plugin is not found in either package
+ */
+export async function loadEditorPlugins(plugins: EditorPlugin[]): Promise<PluginConstructor[]> {
+  const basePackage: Record<string, any> = await import('ckeditor5');
+  let premiumPackage: Record<string, any> | null = null;
+
+  const loaders = plugins.map(async (plugin) => {
+    // Let's first try to load the plugin from the base package.
+    // Coverage is disabled due to Vitest issues with mocking dynamic imports.
+
+    /* v8 ignore start */
+    const { [plugin]: basePkgImport } = basePackage;
+
+    if (basePkgImport) {
+      return basePkgImport as PluginConstructor;
+    }
+
+    // Plugin not found in base package, try premium package.
+    if (!premiumPackage) {
+      try {
+        premiumPackage = await import('ckeditor5-premium-features');
+      }
+      catch (error) {
+        console.error(`Failed to load premium package: ${error}`);
+      }
+    }
+
+    const { [plugin]: premiumPkgImport } = premiumPackage || {};
+
+    if (premiumPkgImport) {
+      return premiumPkgImport as PluginConstructor;
+    }
+
+    // Plugin not found in either package, throw an error.
+    throw new Error(`Plugin "${plugin}" not found in base or premium packages.`);
+    /* v8 ignore end */
+  });
+
+  return Promise.all(loaders);
+}

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

@@ -0,0 +1,140 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { queryAllEditorEditables } from './query-all-editor-editables';
+
+describe('queryAllEditorEditables', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('should return empty object when no editables found', () => {
+    const result = queryAllEditorEditables('test-editor');
+    expect(result).toEqual({});
+  });
+
+  it('should find editables with specific editor ID', () => {
+    document.body.innerHTML = `
+      <div data-cke-editor-id="test-editor" data-cke-editable-root-name="main" data-cke-editable-initial-value="Initial content">
+        <div data-cke-editable-content>Content area</div>
+      </div>
+    `;
+
+    const result = queryAllEditorEditables('test-editor');
+
+    expect(result).toHaveProperty('main');
+    expect(result['main']?.content).toBeInstanceOf(HTMLElement);
+    expect(result['main']?.initialValue).toBe('Initial content');
+  });
+
+  it('should find editables without editor ID (fallback)', () => {
+    document.body.innerHTML = `
+      <div data-cke-editable-root-name="main" data-cke-editable-initial-value="Initial content">
+        <div data-cke-editable-content>Content area</div>
+      </div>
+    `;
+
+    const result = queryAllEditorEditables('any-editor');
+
+    expect(result).toHaveProperty('main');
+    expect(result['main']?.content).toBeInstanceOf(HTMLElement);
+    expect(result['main']?.initialValue).toBe('Initial content');
+  });
+
+  it('should handle multiple editables', () => {
+    document.body.innerHTML = `
+      <div data-cke-editor-id="test-editor" data-cke-editable-root-name="main" data-cke-editable-initial-value="Main content">
+        <div data-cke-editable-content>Main area</div>
+      </div>
+      <div data-cke-editor-id="test-editor" data-cke-editable-root-name="sidebar" data-cke-editable-initial-value="Sidebar content">
+        <div data-cke-editable-content>Sidebar area</div>
+      </div>
+    `;
+
+    const result = queryAllEditorEditables('test-editor');
+
+    expect(Object.keys(result)).toHaveLength(2);
+    expect(result).toHaveProperty('main');
+    expect(result).toHaveProperty('sidebar');
+    expect(result['main']?.initialValue).toBe('Main content');
+    expect(result['sidebar']?.initialValue).toBe('Sidebar content');
+  });
+
+  it('should ignore editables without content element', () => {
+    document.body.innerHTML = `
+      <div data-cke-editor-id="test-editor" data-cke-editable-root-name="main" data-cke-editable-initial-value="Initial content">
+        <!-- No content element -->
+      </div>
+    `;
+
+    const result = queryAllEditorEditables('test-editor');
+
+    expect(result).toEqual({});
+  });
+
+  it('should ignore editables without name attribute', () => {
+    document.body.innerHTML = `
+      <div data-cke-editor-id="test-editor" data-cke-editable-initial-value="Initial content">
+        <div data-cke-editable-content>Content area</div>
+      </div>
+    `;
+
+    const result = queryAllEditorEditables('test-editor');
+
+    expect(result).toEqual({});
+  });
+
+  it('should use empty string as default initial value', () => {
+    document.body.innerHTML = `
+      <div data-cke-editor-id="test-editor" data-cke-editable-root-name="main">
+        <div data-cke-editable-content>Content area</div>
+      </div>
+    `;
+
+    const result = queryAllEditorEditables('test-editor');
+
+    expect(result).toHaveProperty('main');
+    expect(result['main']?.initialValue).toBe('');
+  });
+
+  it('should filter by specific editor ID', () => {
+    document.body.innerHTML = `
+      <div data-cke-editor-id="editor1" data-cke-editable-root-name="main" data-cke-editable-initial-value="Editor 1 content">
+        <div data-cke-editable-content>Editor 1 area</div>
+      </div>
+      <div data-cke-editor-id="editor2" data-cke-editable-root-name="main" data-cke-editable-initial-value="Editor 2 content">
+        <div data-cke-editable-content>Editor 2 area</div>
+      </div>
+    `;
+
+    const result1 = queryAllEditorEditables('editor1');
+    const result2 = queryAllEditorEditables('editor2');
+
+    expect(result1).toHaveProperty('main');
+    expect(result1['main']?.initialValue).toBe('Editor 1 content');
+
+    expect(result2).toHaveProperty('main');
+    expect(result2['main']?.initialValue).toBe('Editor 2 content');
+  });
+
+  it('should handle complex nested structures', () => {
+    document.body.innerHTML = `
+      <div class="editor-container">
+        <div data-cke-editor-id="test-editor" data-cke-editable-root-name="header" data-cke-editable-initial-value="Header content">
+          <div class="wrapper">
+            <div data-cke-editable-content class="content-area">Header area</div>
+          </div>
+        </div>
+        <div data-cke-editor-id="test-editor" data-cke-editable-root-name="body" data-cke-editable-initial-value="Body content">
+          <div data-cke-editable-content>Body area</div>
+        </div>
+      </div>
+    `;
+
+    const result = queryAllEditorEditables('test-editor');
+
+    expect(Object.keys(result)).toHaveLength(2);
+    expect(result).toHaveProperty('header');
+    expect(result).toHaveProperty('body');
+    expect(result['header']?.content.className).toBe('content-area');
+  });
+});

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

@@ -0,0 +1,47 @@
+import type { EditorId } from '../typings';
+
+/**
+ * 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> {
+  const iterator = document.querySelectorAll<HTMLElement>(
+    [
+      `[data-cke-editor-id="${editorId}"][data-cke-editable-root-name]`,
+      '[data-cke-editable-root-name]:not([data-cke-editor-id])',
+    ]
+      .join(', '),
+  );
+
+  return (
+    Array
+      .from(iterator)
+      .reduce<Record<string, EditableItem>>((acc, element) => {
+        const name = element.getAttribute('data-cke-editable-root-name');
+        const initialValue = element.getAttribute('data-cke-editable-initial-value') || '';
+        const content = element.querySelector('[data-cke-editable-content]') as HTMLElement;
+
+        if (!name || !content) {
+          return acc;
+        }
+
+        return {
+          ...acc,
+          [name]: {
+            content,
+            initialValue,
+          },
+        };
+      }, Object.create({}))
+  );
+}
+
+/**
+ * Type representing an editable item within an editor.
+ */
+export type EditableItem = {
+  content: HTMLElement;
+  initialValue: string;
+};

package/src/hooks/editor/utils/read-preset-or-throw.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+
+import { readPresetOrThrow } from './read-preset-or-throw';
+
+describe('readPresetOrThrow', () => {
+  it('should parse valid preset configuration', () => {
+    const element = document.createElement('div');
+    const preset = {
+      type: 'classic',
+      config: {
+        plugins: ['Plugin1', 'Plugin2'],
+        toolbar: ['bold', 'italic'],
+      },
+      license: {
+        key: 'test-license-key',
+      },
+    };
+    element.setAttribute('cke-preset', JSON.stringify(preset));
+
+    const result = readPresetOrThrow(element);
+
+    expect(result).toEqual(preset);
+  });
+
+  it('should throw error when cke-preset attribute is missing', () => {
+    const element = document.createElement('div');
+
+    expect(() => readPresetOrThrow(element)).toThrow(
+      'CKEditor5 hook requires a "cke-preset" attribute on the element.',
+    );
+  });
+
+  it('should throw error when type is missing', () => {
+    const element = document.createElement('div');
+    const preset = {
+      config: { plugins: [] },
+      license: { key: 'test-key' },
+    };
+    element.setAttribute('cke-preset', JSON.stringify(preset));
+
+    expect(() => readPresetOrThrow(element)).toThrow(
+      'CKEditor5 hook configuration must include "editor", "config", and "license" properties.',
+    );
+  });
+
+  it('should throw error when config is missing', () => {
+    const element = document.createElement('div');
+    const preset = {
+      type: 'classic',
+      license: { key: 'test-key' },
+    };
+    element.setAttribute('cke-preset', JSON.stringify(preset));
+
+    expect(() => readPresetOrThrow(element)).toThrow(
+      'CKEditor5 hook configuration must include "editor", "config", and "license" properties.',
+    );
+  });
+
+  it('should throw error when license is missing', () => {
+    const element = document.createElement('div');
+    const preset = {
+      type: 'classic',
+      config: { plugins: [] },
+    };
+    element.setAttribute('cke-preset', JSON.stringify(preset));
+
+    expect(() => readPresetOrThrow(element)).toThrow(
+      'CKEditor5 hook configuration must include "editor", "config", and "license" properties.',
+    );
+  });
+
+  it('should throw error for invalid editor type', () => {
+    const element = document.createElement('div');
+    const preset = {
+      type: 'invalid-type',
+      config: { plugins: [] },
+      license: { key: 'test-key' },
+    };
+    element.setAttribute('cke-preset', JSON.stringify(preset));
+
+    expect(() => readPresetOrThrow(element)).toThrow(
+      'Invalid editor type: invalid-type. Must be one of: inline, classic, balloon, decoupled, multiroot.',
+    );
+  });
+
+  it('should handle all valid editor types', () => {
+    const validTypes = ['inline', 'classic', 'balloon', 'decoupled', 'multiroot'];
+
+    validTypes.forEach((type) => {
+      const element = document.createElement('div');
+      const preset = {
+        type,
+        config: { plugins: [] },
+        license: { key: 'test-key' },
+      };
+      element.setAttribute('cke-preset', JSON.stringify(preset));
+
+      expect(() => readPresetOrThrow(element)).not.toThrow();
+      const result = readPresetOrThrow(element);
+      expect(result.type).toBe(type);
+    });
+  });
+
+  it('should throw error for invalid JSON', () => {
+    const element = document.createElement('div');
+    element.setAttribute('cke-preset', 'invalid-json');
+
+    expect(() => readPresetOrThrow(element)).toThrow();
+  });
+
+  it('should handle complex configuration objects', () => {
+    const element = document.createElement('div');
+    const preset = {
+      type: 'classic',
+      config: {
+        plugins: ['Plugin1', 'Plugin2'],
+        toolbar: {
+          items: ['bold', 'italic', 'link'],
+          shouldNotGroupWhenFull: true,
+        },
+        image: {
+          toolbar: ['imageStyle:full', 'imageStyle:side'],
+        },
+        customProperty: 'custom-value',
+      },
+      license: {
+        key: 'complex-license-key',
+      },
+    };
+
+    element.setAttribute('cke-preset', JSON.stringify(preset));
+
+    const result = readPresetOrThrow(element);
+
+    expect(result).toEqual(preset);
+    expect(result.config['toolbar']['items']).toEqual(['bold', 'italic', 'link']);
+    expect(result.config['customProperty']).toBe('custom-value');
+  });
+
+  it('should handle empty attribute gracefully', () => {
+    const element = document.createElement('div');
+    element.setAttribute('cke-preset', '');
+
+    expect(() => readPresetOrThrow(element)).toThrow(
+      'CKEditor5 hook requires a "cke-preset" attribute on the element.',
+    );
+  });
+
+  it('should handle null values in configuration', () => {
+    const element = document.createElement('div');
+    const preset = {
+      type: 'classic',
+      config: null,
+      license: { key: 'test-key' },
+    };
+    element.setAttribute('cke-preset', JSON.stringify(preset));
+
+    expect(() => readPresetOrThrow(element)).toThrow(
+      'CKEditor5 hook configuration must include "editor", "config", and "license" properties.',
+    );
+  });
+});

package/src/hooks/editor/utils/read-preset-or-throw.ts

@@ -0,0 +1,33 @@
+import type { EditorPreset } from '../typings';
+
+import { EDITOR_TYPES } from '../typings';
+
+/**
+ * Reads the hook configuration from the element's attribute and parses it as JSON.
+ *
+ * @param element - The HTML element that contains the hook configuration.
+ * @returns The parsed hook configuration.
+ */
+export function readPresetOrThrow(element: HTMLElement): EditorPreset {
+  const attributeValue = element.getAttribute('cke-preset');
+
+  if (!attributeValue) {
+    throw new Error('CKEditor5 hook requires a "cke-preset" attribute on the element.');
+  }
+
+  const { type, config, license } = JSON.parse(attributeValue);
+
+  if (!type || !config || !license) {
+    throw new Error('CKEditor5 hook configuration must include "editor", "config", and "license" properties.');
+  }
+
+  if (!EDITOR_TYPES.includes(type)) {
+    throw new Error(`Invalid editor type: ${type}. Must be one of: ${EDITOR_TYPES.join(', ')}.`);
+  }
+
+  return {
+    type,
+    config,
+    license,
+  };
+}

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/index.ts

@@ -0,0 +1,9 @@
+import { EditableHook } from './editable';
+import { EditorHook } from './editor';
+import { UIPartHook } from './ui-part';
+
+export const Hooks = {
+  CKEditor5: EditorHook,
+  CKEditable: EditableHook,
+  CKUIPart: UIPartHook,
+};