ckeditor5-livewire 0.0.1

package/src/hooks/editor/editor.ts

@@ -0,0 +1,357 @@
+import type { Editor } from 'ckeditor5';
+
+import type { EditorId, EditorLanguage, EditorPreset, EditorType } from './typings';
+import type { EditorCreator } from './utils';
+
+import { ContextsRegistry } from '../../hooks/context';
+import { isEmptyObject, waitFor } from '../../shared';
+import { ClassHook } from '../hook';
+import { EditorsRegistry } from './editors-registry';
+import {
+  createLivewireSyncPlugin,
+  createSyncEditorWithInputPlugin,
+} from './plugins';
+import {
+  createEditorInContext,
+  isSingleEditingLikeEditor,
+  loadAllEditorTranslations,
+  loadEditorConstructor,
+  loadEditorPlugins,
+  normalizeCustomTranslations,
+  queryEditablesElements,
+  queryEditablesSnapshotContent,
+  resolveEditorConfigElementReferences,
+  setEditorEditableHeight,
+  unwrapEditorContext,
+  unwrapEditorWatchdog,
+  wrapWithWatchdog,
+} from './utils';
+
+/**
+ * The Livewire hook that manages the lifecycle of CKEditor5 instances.
+ */
+export class EditorComponentHook extends ClassHook<Snapshot> {
+  /**
+   * The promise that resolves to the editor instance.
+   */
+  private editorPromise: Promise<Editor> | null = null;
+
+  /**
+   * @inheritdoc
+   */
+  override async mounted(): Promise<void> {
+    const { editorId } = this.ephemeral;
+
+    EditorsRegistry.the.resetErrors(editorId);
+
+    try {
+      this.editorPromise = this.createEditor();
+
+      const editor = await this.editorPromise;
+
+      // Do not even try to broadcast about the registration of the editor
+      // if hook was immediately destroyed.
+      if (!this.isBeingDestroyed()) {
+        EditorsRegistry.the.register(editorId, editor);
+
+        editor.once('destroy', () => {
+          if (EditorsRegistry.the.hasItem(editorId)) {
+            EditorsRegistry.the.unregister(editorId);
+          }
+        });
+      }
+    }
+    catch (error: any) {
+      this.editorPromise = null;
+      EditorsRegistry.the.error(editorId, error);
+    }
+  }
+
+  /**
+   * Destroys the editor instance when the component is destroyed.
+   * This is important to prevent memory leaks and ensure that the editor is properly cleaned up.
+   */
+  override async destroyed() {
+    // 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.
+    try {
+      const editor = await this.editorPromise;
+
+      if (!editor) {
+        return;
+      }
+
+      const editorContext = unwrapEditorContext(editor);
+      const watchdog = unwrapEditorWatchdog(editor);
+
+      if (editorContext) {
+        // If context is present, make sure it's not in unmounting phase, as it'll kill the editors.
+        // If it's being destroyed, don't do anything, as the context will take care of it.
+        if (editorContext.state !== 'unavailable') {
+          await editorContext.context.remove(editorContext.editorContextId);
+        }
+      }
+      else if (watchdog) {
+        await watchdog.destroy();
+      }
+      else {
+        await editor.destroy();
+      }
+    }
+    finally {
+      this.editorPromise = null;
+    }
+  }
+
+  /**
+   * Creates the CKEditor instance.
+   */
+  private async createEditor() {
+    const {
+      preset,
+      editorId,
+      contextId,
+      editableHeight,
+      emit,
+      saveDebounceMs,
+      language,
+      watchdog,
+      content,
+    } = this.ephemeral;
+
+    const {
+      customTranslations,
+      editorType,
+      licenseKey,
+      config: { plugins, ...config },
+    } = preset;
+
+    // Wrap editor creator with watchdog if needed.
+    let Constructor: EditorCreator = await loadEditorConstructor(editorType);
+    const context = await (
+      contextId
+        ? ContextsRegistry.the.waitFor(contextId)
+        : null
+    );
+
+    // Do not use editor specific watchdog if context is attached, as the context is by default protected.
+    if (watchdog && !context) {
+      const wrapped = await wrapWithWatchdog(Constructor);
+
+      ({ Constructor } = wrapped);
+      wrapped.watchdog.on('restart', () => {
+        const newInstance = wrapped.watchdog.editor!;
+
+        this.editorPromise = Promise.resolve(newInstance);
+
+        EditorsRegistry.the.register(editorId, newInstance);
+      });
+    }
+
+    const { loadedPlugins, hasPremium } = await loadEditorPlugins(plugins);
+
+    // Add integration specific plugins.
+    loadedPlugins.push(
+      await createLivewireSyncPlugin(
+        {
+          emit,
+          saveDebounceMs,
+          $wire: this.$wire,
+        },
+      ),
+    );
+
+    if (isSingleEditingLikeEditor(editorType)) {
+      loadedPlugins.push(
+        await createSyncEditorWithInputPlugin(saveDebounceMs),
+      );
+    }
+
+    // Mix custom translations with loaded translations.
+    const loadedTranslations = await loadAllEditorTranslations(language, hasPremium);
+    const mixedTranslations = [
+      ...loadedTranslations,
+      normalizeCustomTranslations(customTranslations || {}),
+    ]
+      .filter(translations => !isEmptyObject(translations));
+
+    // Let's query all elements, and create basic configuration.
+    let initialData: string | Record<string, string> = {
+      ...content,
+      ...queryEditablesSnapshotContent(editorId, editorType),
+    };
+
+    if (isSingleEditingLikeEditor(editorType)) {
+      initialData = initialData['main'] || '';
+    }
+
+    // Depending of the editor type, and parent lookup for nearest context or initialize it without it.
+    const editor = await (async () => {
+      let sourceElementOrData = queryEditablesElements(editorId, editorType);
+
+      // Handle special case when user specified `initialData` of several root elements, but editable components
+      // are not yet present in the DOM. In other words - editor is initialized before attaching root elements.
+      if (shouldWaitForRoots(sourceElementOrData, editorType)) {
+        const requiredRoots = Object.keys(initialData as Record<string, string>);
+
+        if (!checkIfAllRootsArePresent(sourceElementOrData, requiredRoots)) {
+          sourceElementOrData = await waitForAllRootsToBePresent(editorId, editorType, requiredRoots);
+          initialData = {
+            ...content,
+            ...queryEditablesSnapshotContent(editorId, editorType),
+          };
+        }
+      }
+
+      // Construct parsed config.
+      const parsedConfig = {
+        ...resolveEditorConfigElementReferences(config),
+        initialData,
+        licenseKey,
+        plugins: loadedPlugins,
+        language,
+        ...mixedTranslations.length && {
+          translations: mixedTranslations,
+        },
+      };
+
+      if (!context || !(sourceElementOrData instanceof HTMLElement)) {
+        return Constructor.create(sourceElementOrData as any, parsedConfig);
+      }
+
+      const result = await createEditorInContext({
+        context,
+        element: sourceElementOrData,
+        creator: Constructor,
+        config: parsedConfig,
+      });
+
+      return result.editor;
+    })();
+
+    if (isSingleEditingLikeEditor(editorType) && editableHeight) {
+      setEditorEditableHeight(editor, editableHeight);
+    }
+
+    return editor;
+  };
+}
+
+/**
+ * Checks if all required root elements are present in the elements object.
+ *
+ * @param elements The elements object mapping root IDs to HTMLElements.
+ * @param requiredRoots The list of required root IDs.
+ * @returns True if all required roots are present, false otherwise.
+ */
+function checkIfAllRootsArePresent(elements: Record<string, HTMLElement>, requiredRoots: string[]): boolean {
+  return requiredRoots.every(rootId => elements[rootId]);
+}
+
+/**
+ * Waits for all required root elements to be present in the DOM.
+ *
+ * @param editorId The editor's ID.
+ * @param editorType The type of the editor.
+ * @param requiredRoots The list of required root IDs.
+ * @returns A promise that resolves to the record of root elements.
+ */
+async function waitForAllRootsToBePresent(
+  editorId: EditorId,
+  editorType: EditorType,
+  requiredRoots: string[],
+): Promise<Record<string, HTMLElement>> {
+  await waitFor(
+    () => {
+      const elements = queryEditablesElements(editorId, editorType) as unknown as Record<string, HTMLElement>;
+
+      if (!checkIfAllRootsArePresent(elements, requiredRoots)) {
+        throw new Error(
+          'It looks like not all required root elements are present yet.\n'
+          + '* If you want to wait for them, ensure they are registered before editor initialization.\n'
+          + '* If you want lazy initialize roots, consider removing root values from the `initialData` config '
+          + 'and assign initial data in editable components.\n'
+          + `Missing roots: ${requiredRoots.filter(rootId => !elements[rootId]).join(', ')}.`,
+        );
+      }
+
+      return true;
+    },
+    { timeOutAfter: 2000, retryAfter: 100 },
+  );
+
+  return queryEditablesElements(editorId, editorType) as unknown as Record<string, HTMLElement>;
+}
+
+/**
+ * Type guard to check if we should wait for multiple root elements.
+ *
+ * @param elements The elements retrieved for the editor.
+ * @param editorType The type of the editor.
+ * @returns True if we should wait for multiple root elements, false otherwise.
+ */
+function shouldWaitForRoots(
+  elements: HTMLElement | Record<string, HTMLElement>,
+  editorType: EditorType,
+): elements is Record<string, HTMLElement> {
+  return (
+    !isSingleEditingLikeEditor(editorType)
+    && typeof elements === 'object'
+    && !(elements instanceof HTMLElement)
+  );
+}
+
+/**
+ * A snapshot of the Livewire component's state relevant to the CKEditor5 hook.
+ */
+export type Snapshot = {
+  /**
+   * The unique identifier for the CKEditor5 instance.
+   */
+  editorId: string;
+
+  /**
+   * Whether to use a watchdog for the CKEditor5 instance.
+   */
+  watchdog: boolean;
+
+  /**
+   * The identifier of the CKEditor context.
+   */
+  contextId: string | null;
+
+  /**
+   * The debounce time in milliseconds for saving content changes.
+   */
+  saveDebounceMs: number;
+
+  /**
+   * The preset configuration for the CKEditor5 instance.
+   */
+  preset: EditorPreset;
+
+  /**
+   * The content of the editor, mapped by ID of root elements.
+   */
+  content: Record<string, string>;
+
+  /**
+   * The height of the editable area, if specified.
+   */
+  editableHeight: number | null;
+
+  /**
+   * The language of the editor UI and content.
+   */
+  language: EditorLanguage;
+
+  /**
+   * The global events of the editor to forward to Livewire.
+   */
+  emit: {
+    change: boolean;
+    focus: boolean;
+  };
+};

package/src/hooks/editor/editors-registry.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+
+import { AsyncRegistry } from '../../shared/async-registry';
+import { EditorsRegistry } from './editors-registry';
+
+describe('editors registry', () => {
+  it('should be singleton of async registry', () => {
+    expect(EditorsRegistry.the).toBeInstanceOf(AsyncRegistry);
+  });
+});

package/src/hooks/editor/editors-registry.ts

@@ -0,0 +1,10 @@
+import type { Editor } from 'ckeditor5';
+
+import { AsyncRegistry } from '../../shared/async-registry';
+
+/**
+ * It provides a way to register editors and execute callbacks on them when they are available.
+ */
+export class EditorsRegistry extends AsyncRegistry<Editor> {
+  static readonly the = new EditorsRegistry();
+}

package/src/hooks/editor/index.ts

@@ -0,0 +1,2 @@
+export * from './editor';
+export * from './typings';

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

@@ -0,0 +1,2 @@
+export * from './livewire-sync';
+export * from './sync-editor-with-input';

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

@@ -0,0 +1,85 @@
+import type { PluginConstructor } from 'ckeditor5';
+
+import type { Wire } from '../../../livewire';
+
+import { debounce } from '../../../shared';
+import { getEditorRootsValues } from '../utils';
+
+/**
+ * Creates a LivewireSync plugin class.
+ */
+export async function createLivewireSyncPlugin(
+  {
+    emit,
+    saveDebounceMs,
+    $wire,
+  }: Attrs,
+): Promise<PluginConstructor> {
+  const { Plugin } = await import('ckeditor5');
+
+  return class LivewireSync extends Plugin {
+    /**
+     * The name of the plugin.
+     */
+    static get pluginName() {
+      return 'LivewireSync' as const;
+    }
+
+    /**
+     * Initializes the plugin.
+     */
+    public init(): void {
+      if (emit.change) {
+        this.setupTypingContentPush();
+      }
+
+      if (emit.focus) {
+        this.setupFocusableEventPush();
+      }
+    }
+
+    /**
+     * Setups the content push event for the editor.
+     */
+    private setupTypingContentPush() {
+      const { model } = this.editor;
+
+      const syncContentChange = () => {
+        $wire.set('content', this.getEditorRootsValues());
+      };
+
+      model.document.on('change:data', debounce(saveDebounceMs, syncContentChange));
+      syncContentChange();
+    }
+
+    /**
+     * Setups the event push for the editor.
+     */
+    private setupFocusableEventPush() {
+      const { ui } = this.editor;
+
+      const pushEvent = () => {
+        $wire.set('focused', ui.focusTracker.isFocused);
+        $wire.set('content', this.getEditorRootsValues());
+      };
+
+      ui.focusTracker.on('change:isFocused', pushEvent);
+    }
+
+    /**
+     * Gets the current values of all editor roots.
+     */
+    private getEditorRootsValues(): Record<string, string> {
+      return getEditorRootsValues(this.editor);
+    }
+  };
+}
+
+/**
+ * The attributes required to create the LivewireSync plugin.
+ */
+type Attrs = {
+  emit: { change?: boolean; focus?: boolean; };
+  saveDebounceMs: number;
+  $wire: Wire;
+};

package/src/hooks/editor/plugins/sync-editor-with-input.ts

@@ -0,0 +1,76 @@
+import type { ClassicEditor, PluginConstructor } from 'ckeditor5';
+
+import { debounce } from '../../../shared';
+
+/**
+ * Creates a SyncEditorWithInput plugin class.
+ */
+export async function createSyncEditorWithInputPlugin(saveDebounceMs: number): Promise<PluginConstructor> {
+  const { Plugin } = await import('ckeditor5');
+
+  return class SyncEditorWithInput extends Plugin {
+    /**
+     * The input element to synchronize with.
+     */
+    private input: HTMLInputElement | null = null;
+
+    /**
+     * The form element reference for cleanup.
+     */
+    private form: HTMLFormElement | null = null;
+
+    /**
+     * The name of the plugin.
+     */
+    static get pluginName() {
+      return 'SyncEditorWithInput' as const;
+    }
+
+    /**
+     * Initializes the plugin.
+     */
+    public afterInit(): void {
+      const { editor } = this;
+      const editorElement = (editor as ClassicEditor).sourceElement as HTMLElement;
+
+      // Try to find the associated input field.
+      const editorId = editorElement.id.replace(/_editor$/, '');
+
+      this.input = document.getElementById(`${editorId}_input`) as HTMLInputElement | null;
+
+      if (!this.input) {
+        return;
+      }
+
+      // Setup handlers.
+      editor.model.document.on('change:data', debounce(saveDebounceMs, () => this.sync()));
+      editor.once('ready', this.sync);
+
+      // Setup form integration.
+      this.form = this.input.closest('form');
+      this.form?.addEventListener('submit', this.sync);
+    }
+
+    /**
+     * Synchronizes the editor's content with the input field.
+     */
+    private sync = (): void => {
+      const newValue = this.editor.getData();
+
+      this.input!.value = newValue;
+      this.input!.dispatchEvent(new Event('input', { bubbles: true }));
+    };
+
+    /**
+     * Destroys the plugin.
+     */
+    public override destroy(): void {
+      if (this.form) {
+        this.form.removeEventListener('submit', this.sync);
+      }
+
+      this.input = null;
+      this.form = null;
+    }
+  };
+}

package/src/hooks/editor/typings.ts

@@ -0,0 +1,114 @@
+/**
+ * Represents a unique identifier for a CKEditor5 editor instance.
+ * This is typically the ID of the HTML element that the editor is attached to.
+ */
+export type EditorId = string;
+
+/**
+ * Defines editor type supported by CKEditor5.
+ */
+export type EditorType = 'inline' | 'classic' | 'balloon' | 'decoupled' | 'multiroot';
+
+/**
+ * Represents a CKEditor5 plugin as a string identifier.
+ */
+export type EditorPlugin = string;
+
+/**
+ * Configuration object for CKEditor5 editor instance.
+ */
+export type EditorConfig = {
+  /**
+   * Array of plugin identifiers to be loaded by the editor.
+   */
+  plugins: EditorPlugin[];
+
+  /**
+   * Other configuration options are flexible and can be any key-value pairs.
+   */
+  [key: string]: any;
+};
+
+/**
+ * Configuration object for CKEditor5 cloud services.
+ */
+export type EditorCloudConfig = {
+  /**
+   * The version of CKEditor5 being used.
+   */
+  editorVersion: string;
+
+  /**
+   * Indicates whether the CKEditor5 instance is a premium version.
+   */
+  premium: boolean;
+
+  /**
+   * List of language codes for translations available in the CKEditor5 instance.
+   */
+  translations: string[];
+
+  /**
+   * Configuration for CKEditor5's upload adapter.
+   */
+  ckbox: {
+    version: string;
+    theme: string | null;
+  } | null;
+};
+
+/**
+ * Configuration object for the CKEditor5 hook.
+ */
+export type EditorPreset = {
+  /**
+   * The configuration of the cloud.
+   */
+  cloud: EditorCloudConfig | null;
+
+  /**
+   * The type of CKEditor5 editor to use.
+   * Must be one of the predefined types: 'inline', 'classic', 'balloon', 'decoupled', or 'multiroot'.
+   */
+  editorType: EditorType;
+
+  /**
+   * The configuration object for the CKEditor5 editor.
+   * This should match the configuration expected by CKEditor5.
+   */
+  config: EditorConfig;
+
+  /**
+   * The license key for CKEditor5.
+   * This is required for using CKEditor5 with a valid license.
+   */
+  licenseKey: string;
+
+  /**
+   * Optional watchdog configuration for error recovery.
+   */
+  watchdogConfig?: Record<string, any> | null;
+
+  /**
+   * Optional custom translations for the editor.
+   * This allows for localization of the editor interface.
+   */
+  customTranslations?: EditorCustomTranslationsDictionary | null;
+};
+
+/**
+ * Represents the language settings for the CKEditor5 editor.
+ */
+export type EditorLanguage = {
+  ui: string;
+  content: string;
+};
+
+/**
+ * Represents custom translations for the editor.
+ */
+export type EditorCustomTranslationsDictionary = {
+  [language: string]: {
+    [key: string]: string | ReadonlyArray<string>;
+  };
+};