ckeditor5-livewire 0.0.1

package/src/hooks/hook.ts

@@ -0,0 +1,87 @@
+import type { LivewireComponent, Wire } from '../livewire';
+import type { CanBePromise } from '../types';
+
+/**
+ * An abstract class representing a class-based hook for Livewire components.
+ */
+export abstract class ClassHook<T extends object = Record<string, unknown>> {
+  /**
+   * The current state of the hook.
+   */
+  state: ClassHookState = 'mounting';
+
+  constructor(
+    /**
+     * The Livewire component instance associated with this hook.
+     */
+    protected livewireComponent: LivewireComponent,
+  ) {}
+
+  /**
+   * The ephemeral snapshot of the Livewire component.
+   */
+  get ephemeral(): T {
+    return this.livewireComponent.ephemeral as T;
+  }
+
+  /**
+   * The root HTML element of the Livewire component.
+   */
+  get element(): HTMLElement {
+    return this.livewireComponent.el;
+  }
+
+  /**
+   * The wire interface for the Livewire component.
+   */
+  get $wire(): Wire {
+    return this.livewireComponent.$wire;
+  }
+
+  /**
+   * Checks if the hook is in the process of being destroyed.
+   */
+  isBeingDestroyed(): boolean {
+    return ['destroyed', 'destroying'].includes(this.state);
+  }
+
+  /**
+   * Called when the hook has been mounted to the DOM.
+   */
+  abstract mounted(): CanBePromise<void>;
+
+  /**
+   * Called when the element has been removed from the DOM.
+   */
+  abstract destroyed(): CanBePromise<void>;
+}
+
+/**
+ * A type that represents the state of a class-based hook.
+ */
+export type ClassHookState = 'mounting' | 'mounted' | 'destroying' | 'destroyed';
+
+/**
+ * Registers a Livewire hook that watches initialization of components and manages their lifecycle.
+ *
+ * @param name - The name of the component to watch for.
+ * @param Hook - A class that extends `ClassHook` to handle component lifecycle events.
+ */
+export function registerLivewireComponentHook(name: string, Hook: { new(component: LivewireComponent): ClassHook<any>; }) {
+  window.Livewire.hook('component.init', async ({ component, cleanup }) => {
+    if (component.name !== name) {
+      return;
+    }
+
+    const instance = new Hook(component);
+
+    cleanup(async () => {
+      instance.state = 'destroying';
+      await instance.destroyed();
+      instance.state = 'destroyed';
+    });
+
+    await instance.mounted();
+    instance.state = 'mounted';
+  });
+}

package/src/hooks/index.ts

@@ -0,0 +1,21 @@
+import { ContextComponentHook } from './context';
+import { EditableComponentHook } from './editable';
+import { EditorComponentHook } from './editor';
+import { registerLivewireComponentHook } from './hook';
+import { UIPartComponentHook } from './ui-part';
+
+const COMPONENT_HOOKS = {
+  'ckeditor5': EditorComponentHook,
+  'ckeditor5-context': ContextComponentHook,
+  'ckeditor5-ui-part': UIPartComponentHook,
+  'ckeditor5-editable': EditableComponentHook,
+};
+
+/**
+ * Registers all available Livewire component hooks.
+ */
+export function registerLivewireComponentHooks() {
+  for (const [name, Hook] of Object.entries(COMPONENT_HOOKS)) {
+    registerLivewireComponentHook(name, Hook);
+  }
+}

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

@@ -0,0 +1,161 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createEditorHtmlElement,
+  createEditorPreset,
+  createEditorSnapshot,
+  createUIPartHtmlElement,
+  createUIPartSnapshot,
+  LivewireStub,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import type { Snapshot as EditorSnapshot } from './editor';
+
+import { EditorComponentHook } from './editor';
+import { registerLivewireComponentHook } from './hook';
+import { UIPartComponentHook } from './ui-part';
+
+describe('ui-part component', () => {
+  let livewireStub: LivewireStub;
+
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    livewireStub = window.Livewire = new LivewireStub();
+
+    registerLivewireComponentHook('ckeditor5', EditorComponentHook);
+    registerLivewireComponentHook('ckeditor5-ui-part', UIPartComponentHook);
+  });
+
+  afterEach(async () => {
+    await livewireStub.$internal.destroy();
+  });
+
+  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 } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-ui-part',
+        el: createUIPartHtmlElement(),
+        ephemeral: createUIPartSnapshot('toolbar'),
+      });
+
+      expect(toolbarElement).toBeTruthy();
+      expect(el.contains(toolbarElement!)).toBe(true);
+    });
+
+    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 } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-ui-part',
+        el: createUIPartHtmlElement(),
+        ephemeral: createUIPartSnapshot('menubar'),
+      });
+
+      expect(el.children.length).toBeGreaterThan(0);
+      expect(el.contains(menubarElement)).toBe(true);
+    });
+
+    it('should log error for unknown UI part name', async () => {
+      appendMultirootEditor();
+      await waitForTestEditor();
+
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-ui-part',
+        el: createUIPartHtmlElement(),
+        ephemeral: createUIPartSnapshot('unknown-part'),
+      });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Unknown UI part name: "unknown-part"'),
+      );
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('should mount UI part before editor is created', async () => {
+      const { el } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-ui-part',
+        el: createUIPartHtmlElement(),
+        ephemeral: createUIPartSnapshot('toolbar'),
+      });
+
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+      const toolbarElement = editor.ui.view.toolbar?.element;
+
+      expect(toolbarElement).toBeTruthy();
+      expect(el.contains(toolbarElement!)).toBe(true);
+    });
+  });
+
+  describe('destroying ui part', () => {
+    beforeEach(async () => {
+      appendMultirootEditor();
+      await waitForTestEditor();
+    });
+
+    it('should clear UI part element on destruction', async () => {
+      const { id, el } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-ui-part',
+        el: createUIPartHtmlElement(),
+        ephemeral: createUIPartSnapshot('toolbar'),
+      });
+
+      expect(el.children.length).toBeGreaterThan(0);
+
+      await livewireStub.$internal.unmountComponent(id);
+
+      expect(el.innerHTML).toBe('');
+      expect(el.style.display).toBe('none');
+    });
+
+    it('should hide element during destruction', async () => {
+      const { id, el } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-ui-part',
+        el: createUIPartHtmlElement(),
+        ephemeral: createUIPartSnapshot('toolbar'),
+      });
+
+      await livewireStub.$internal.unmountComponent(id);
+
+      expect(el.style.display).toBe('none');
+    });
+
+    it('should handle destruction when mounted promise is not resolved yet', async () => {
+      const { id, el } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-ui-part',
+        el: createUIPartHtmlElement(),
+        ephemeral: createUIPartSnapshot('toolbar'),
+      });
+
+      await livewireStub.$internal.unmountComponent(id);
+
+      expect(el.innerHTML).toBe('');
+      expect(el.style.display).toBe('none');
+    });
+  });
+
+  function appendMultirootEditor(initialContent: Record<string, string> = {}) {
+    livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+      name: 'ckeditor5',
+      el: createEditorHtmlElement(),
+      ephemeral: {
+        ...createEditorSnapshot(),
+        preset: createEditorPreset('multiroot'),
+        content: initialContent,
+      },
+    });
+  }
+});

package/src/hooks/ui-part.ts

@@ -0,0 +1,80 @@
+import { EditorsRegistry } from './editor/editors-registry';
+import { ClassHook } from './hook';
+
+/**
+ * UI Part hook for Livewire. It allows you to create UI parts for multi-root editors.
+ */
+export class UIPartComponentHook extends ClassHook<Snapshot> {
+  /**
+   * The promise that resolves when the UI part is mounted.
+   */
+  private mountedPromise: Promise<void> | null = null;
+
+  /**
+   * Mounts the UI part component.
+   */
+  override async mounted() {
+    const { editorId, name } = this.ephemeral;
+
+    // If the editor is not registered yet, we will wait for it to be registered.
+    this.mountedPromise = EditorsRegistry.the.execute(editorId, (editor) => {
+      const { ui } = editor;
+
+      const uiViewName = mapUIPartView(name);
+      const uiPart = (ui.view as any)[uiViewName!];
+
+      if (!uiPart) {
+        console.error(`Unknown UI part name: "${name}". Supported names are "toolbar" and "menubar".`);
+        return;
+      }
+
+      this.element.appendChild(uiPart.element);
+    });
+  }
+
+  /**
+   * Destroys the UI part component. Unmounts UI parts from the editor.
+   */
+  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.
+    await this.mountedPromise;
+    this.mountedPromise = null;
+
+    // Unmount all UI parts from the editor.
+    this.element.innerHTML = '';
+  }
+}
+
+/**
+ * Maps the UI part name to the corresponding view in the editor.
+ */
+function mapUIPartView(name: string): string | null {
+  switch (name) {
+    case 'toolbar':
+      return 'toolbar';
+
+    case 'menubar':
+      return 'menuBarView';
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * A snapshot of the Livewire component's state relevant to the CKEditor5 UI part hook.
+ */
+export type Snapshot = {
+  /**
+   * The ID of the editor instance this UI part belongs to.
+   */
+  editorId: string;
+
+  /**
+   * The name of the UI part (e.g., "toolbar", "menubar").
+   */
+  name: string;
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+import './livewire.d';
+
+import { registerLivewireComponentHooks } from './hooks';
+
+registerLivewireComponentHooks();

package/src/livewire.d.ts

@@ -0,0 +1,42 @@
+import type { CanBePromise } from './types';
+
+export type LivewireComponent<E = any> = {
+  id: string;
+  el: HTMLElement;
+  name: string;
+  ephemeral: E;
+  $wire: Wire;
+  effects: Record<string, unknown>;
+  canonical: Record<string, unknown>;
+  reactive: any;
+  children: Array<any>;
+  snapshot: Record<string, unknown>;
+  snapshotEncoded: string;
+};
+
+export type Wire = {
+  set: (key: string | Record<string, any>, value?: any) => CanBePromise<void>;
+};
+
+export type ComponentInitEvent = {
+  cleanup: (cb: VoidFunction) => void;
+  component: LivewireComponent;
+};
+
+type Hook = {
+  (event: 'component.init', callback: (attrs: ComponentInitEvent) => void): void;
+  (event: string, callback: (attrs: any) => void): void;
+};
+
+export type LivewireGlobal = {
+  find: (id: string) => LivewireComponent | undefined;
+  all: () => LivewireComponent[];
+  on: (event: string, callback: (...params: any[]) => void) => void;
+  dispatch: (event: string, ...params: any[]) => void;
+  hook: Hook;
+};
+
+declare global {
+  // eslint-disable-next-line vars-on-top
+  var Livewire: LivewireGlobal;
+}