ckeditor5-livewire 1.9.0 → 1.11.0

package/src/shared/async-registry.test.ts

@@ -96,30 +96,6 @@ describe('async registry', () => {
       registry.unregister('item1');
       expect(registry.getItems()).not.toContain(item);
     });
-
-    it('should throw an error if trying to unregister an item that is not registered', () => {
-      expect(() => registry.unregister('nonexistent')).toThrow(
-        'Item with ID "nonexistent" is not registered.',
-      );
-    });
-
-    it('should also unregister the default item if the unregistered item was the default one', async () => {
-      const item1 = createMockItem('item1');
-
-      registry.register('item1', item1); // This also registers it as default
-
-      // Check it is the default
-      const promise = registry.execute(null, item => item);
-
-      await expect(promise).resolves.toBe(item1);
-
-      registry.unregister('item1');
-
-      // Now check that the default is also gone
-      expect(() => registry.unregister(null)).toThrow(
-        'Item with ID "null" is not registered.',
-      );
-    });
   });
 
   describe('execute', () => {
@@ -234,7 +210,7 @@ describe('async registry', () => {
     });
   });
 
-  describe('getitems', () => {
+  describe('getItems', () => {
     it('should return all registered items', () => {
       const item1 = createMockItem('item1');
       const item2 = createMockItem('item2');
@@ -244,7 +220,7 @@ describe('async registry', () => {
 
       const items = registry.getItems();
 
-      expect(items).toHaveLength(3); // item1, item2, and default (which is item1)
+      expect(items).toHaveLength(3);
       expect(items).toContain(item1);
       expect(items).toContain(item2);
     });
@@ -252,16 +228,30 @@ describe('async registry', () => {
     it('should return unique items if some point to the same instance', () => {
       const item1 = createMockItem('item1');
 
-      registry.register('item1', item1); // This also registers it as default
+      registry.register('item1', item1);
 
       const items = registry.getItems();
 
-      expect(items).toHaveLength(2); // item1 and default (which is item1)
+      expect(items).toHaveLength(2);
       expect(items.filter(e => e === item1)).toHaveLength(2);
     });
   });
 
-  describe('hasitem', () => {
+  describe('getItem', () => {
+    it('should return registered item', () => {
+      const item = createMockItem('item1');
+
+      registry.register('item1', item);
+
+      expect(registry.getItem('item1')).toBe(item);
+    });
+
+    it('should return undefined if item doesn\'t exist', () => {
+      expect(registry.getItem('item1')).toBeUndefined();
+    });
+  });
+
+  describe('hasItem', () => {
     it('should return true if an item with the given ID is registered', () => {
       const item = createMockItem('item1');
 
@@ -402,6 +392,197 @@ describe('async registry', () => {
     });
   });
 
+  describe('reset', () => {
+    it('should destroy all registered items', async () => {
+      const item1 = createMockItem('item1');
+      const item2 = createMockItem('item2');
+
+      registry.register('item1', item1);
+      registry.register('item2', item2);
+
+      await registry.reset();
+
+      expect(registry.getItems()).toHaveLength(0);
+    });
+
+    it('should call destroy on each unique item', async () => {
+      const destroyMock1 = vi.fn().mockResolvedValue(undefined);
+      const destroyMock2 = vi.fn().mockResolvedValue(undefined);
+
+      const item1 = { name: 'item1', destroy: destroyMock1 } as unknown as Mockitem;
+      const item2 = { name: 'item2', destroy: destroyMock2 } as unknown as Mockitem;
+
+      registry.register('item1', item1);
+      registry.register('item2', item2);
+
+      await registry.reset();
+
+      expect(destroyMock1).toHaveBeenCalledOnce();
+      expect(destroyMock2).toHaveBeenCalledOnce();
+    });
+
+    it('should clear watchers so they are no longer called after reset', async () => {
+      const watcher = vi.fn();
+      registry.watch(watcher);
+
+      await registry.reset();
+      watcher.mockClear();
+
+      const item = createMockItem('item1');
+      registry.register('item1', item);
+
+      expect(watcher).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('mountEffect', () => {
+    it('should call onMount immediately when item is already registered', () => {
+      const item = createMockItem('item1');
+      registry.register('item1', item);
+
+      const onMount = vi.fn();
+      registry.mountEffect('item1', onMount);
+
+      expect(onMount).toHaveBeenCalledOnce();
+      expect(onMount).toHaveBeenCalledWith(item);
+    });
+
+    it('should call onMount when item registers later', () => {
+      const onMount = vi.fn();
+      registry.mountEffect('item1', onMount);
+
+      expect(onMount).not.toHaveBeenCalled();
+
+      const item = createMockItem('item1');
+      registry.register('item1', item);
+
+      expect(onMount).toHaveBeenCalledOnce();
+      expect(onMount).toHaveBeenCalledWith(item);
+    });
+
+    it('should call cleanup returned by onMount when item is unregistered', () => {
+      const item = createMockItem('item1');
+      registry.register('item1', item);
+
+      const cleanup = vi.fn();
+      registry.mountEffect('item1', () => cleanup);
+
+      registry.unregister('item1');
+
+      expect(cleanup).toHaveBeenCalledOnce();
+    });
+
+    it('should call cleanup and re-call onMount on re-registration', () => {
+      const item1a = createMockItem('item1');
+      registry.register('item1', item1a);
+
+      const cleanup = vi.fn();
+      const onMount = vi.fn(() => cleanup);
+      registry.mountEffect('item1', onMount);
+
+      expect(onMount).toHaveBeenCalledOnce();
+
+      registry.unregister('item1');
+      expect(cleanup).toHaveBeenCalledOnce();
+
+      const item1b = createMockItem('item1');
+      registry.register('item1', item1b);
+
+      expect(onMount).toHaveBeenCalledTimes(2);
+      expect(onMount).toHaveBeenLastCalledWith(item1b);
+    });
+
+    it('should not call onMount if item never registers', () => {
+      const onMount = vi.fn();
+      const stop = registry.mountEffect('item1', onMount);
+
+      stop();
+
+      expect(onMount).not.toHaveBeenCalled();
+    });
+
+    it('should run cleanup and stop watching when stop is called with item mounted', () => {
+      const item = createMockItem('item1');
+      registry.register('item1', item);
+
+      const cleanup = vi.fn();
+      const stop = registry.mountEffect('item1', () => cleanup);
+
+      stop();
+
+      expect(cleanup).toHaveBeenCalledOnce();
+
+      // Watcher should be gone — unregistering should not trigger cleanup again.
+      registry.unregister('item1');
+
+      expect(cleanup).toHaveBeenCalledOnce();
+    });
+
+    it('should not call cleanup when stop is called before item registers', () => {
+      const cleanup = vi.fn();
+      const onMount = vi.fn(() => cleanup);
+      const stop = registry.mountEffect('item1', onMount);
+
+      stop();
+
+      expect(onMount).not.toHaveBeenCalled();
+      expect(cleanup).not.toHaveBeenCalled();
+    });
+
+    it('should call onMount and immediately run cleanup when item registers after stop', () => {
+      const cleanup = vi.fn();
+      const onMount = vi.fn(() => cleanup);
+      const stop = registry.mountEffect('item1', onMount);
+
+      stop();
+
+      const item = createMockItem('item1');
+      registry.register('item1', item);
+
+      expect(onMount).toHaveBeenCalledOnce();
+      expect(onMount).toHaveBeenCalledWith(item);
+      expect(cleanup).toHaveBeenCalledOnce();
+    });
+
+    it('should stop watching after late cleanup fires', () => {
+      const onMount = vi.fn();
+      const stop = registry.mountEffect('item1', onMount);
+
+      stop();
+
+      const item1 = createMockItem('item1');
+      registry.register('item1', item1);
+
+      expect(onMount).toHaveBeenCalledOnce();
+
+      // Watcher should have been removed after late cleanup — further changes are ignored.
+      registry.unregister('item1');
+      registry.register('item1', createMockItem('item1'));
+
+      expect(onMount).toHaveBeenCalledOnce();
+    });
+
+    it('should not throw when onMount returns void and stop is called', () => {
+      const item = createMockItem('item1');
+      registry.register('item1', item);
+
+      const stop = registry.mountEffect('item1', () => {});
+
+      expect(() => stop()).not.toThrow();
+    });
+
+    it('should work with the default null ID', () => {
+      const item = createMockItem('item1');
+      registry.register('item1', item); // also registered as default
+
+      const onMount = vi.fn();
+      registry.mountEffect(null, onMount);
+
+      expect(onMount).toHaveBeenCalledOnce();
+      expect(onMount).toHaveBeenCalledWith(item);
+    });
+  });
+
   describe('waitFor', () => {
     it('should return a promise that resolves with the item instance', async () => {
       const item1 = createMockItem('item1');
@@ -518,7 +699,7 @@ describe('async registry', () => {
       const item1 = createMockItem('item1');
       registry.register('item1', item1);
 
-      expect(watcher).toHaveBeenCalledTimes(3);
+      expect(watcher).toHaveBeenCalledTimes(2);
     });
 
     it('should call watcher when item is unregistered', () => {
@@ -531,7 +712,7 @@ describe('async registry', () => {
       watcher.mockClear();
       registry.unregister('item1');
 
-      expect(watcher).toHaveBeenCalledTimes(2); // Unregister + default unregister
+      expect(watcher).toHaveBeenCalledTimes(1);
     });
 
     it('should call watcher when all items are destroyed', async () => {

package/src/shared/async-registry.ts

@@ -1,3 +1,5 @@
+import { areMapsEqual } from './are-maps-equal';
+
 /**
  * Generic async registry for objects with an async destroy method.
  * Provides a way to register, unregister, and execute callbacks on objects by ID.
@@ -23,6 +25,18 @@ export class AsyncRegistry<T extends Destructible> {
    */
   private readonly watchers = new Set<RegistryWatcher<T>>();
 
+  /**
+   * Batch nesting depth. When > 0, watcher notifications are deferred.
+   */
+  private batchDepth = 0;
+
+  /**
+   * Snapshot of the last state dispatched to watchers, used for change detection.
+   */
+  private lastNotifiedItems: Map<any, any> | null = null;
+
+  private lastNotifiedErrors: Map<any, any> | null = null;
+
   /**
    * Executes a function on an item.
    * If the item is not yet registered, it will wait for it to be registered.
@@ -68,6 +82,66 @@ export class AsyncRegistry<T extends Destructible> {
     });
   }
 
+  /**
+   * Reactively binds a mount/unmount lifecycle to a single registry item.
+   *
+   * @param id The ID of the item to observe.
+   * @param onMount Function executed when the item mounts.
+   * @returns A function that stops observing and immediately runs any pending cleanup.
+   */
+  mountEffect<E extends T = T>(
+    id: RegistryId | null,
+    onMount: (item: E) => (() => void) | void,
+  ): () => void {
+    let cleanup: VoidFunction | void;
+    let mountedItem: T | undefined;
+    let unmounted = false;
+
+    const unwatch = this.watch((items) => {
+      const item = items.get(id);
+
+      if (item === mountedItem) {
+        return;
+      }
+
+      cleanup?.();
+      cleanup = undefined;
+      mountedItem = item;
+
+      if (!item) {
+        return;
+      }
+
+      try {
+        const newCleanup = onMount(item as E);
+
+        if (unmounted) {
+          newCleanup?.();
+          unwatch();
+        }
+        else {
+          cleanup = newCleanup;
+        }
+      }
+      catch (err) {
+        /* v8 ignore start -- @preserve */
+        console.error(err);
+        throw err;
+        /* v8 ignore end */
+      }
+    });
+
+    return () => {
+      unmounted = true;
+
+      if (mountedItem) {
+        unwatch();
+        cleanup?.();
+        cleanup = undefined;
+      }
+    };
+  }
+
   /**
    * Registers an item.
    *
@@ -75,24 +149,27 @@ export class AsyncRegistry<T extends Destructible> {
    * @param item The item instance.
    */
   register(id: RegistryId | null, item: T): void {
-    if (this.items.has(id)) {
-      throw new Error(`Item with ID "${id}" is already registered.`);
-    }
+    this.batch(() => {
+      if (this.items.has(id)) {
+        throw new Error(`Item with ID "${id}" is already registered.`);
+      }
 
-    this.resetErrors(id);
-    this.items.set(id, item);
+      this.resetErrors(id);
+      this.items.set(id, item);
 
-    // Execute all pending callbacks for this item (synchronously).
-    const pending = this.pendingCallbacks.get(id);
+      // Execute all pending callbacks for this item (synchronously).
+      const pending = this.pendingCallbacks.get(id);
 
-    if (pending) {
-      pending.success.forEach(callback => callback(item));
-      this.pendingCallbacks.delete(id);
-    }
+      if (pending) {
+        pending.success.forEach(callback => callback(item));
+        this.pendingCallbacks.delete(id);
+      }
 
-    // Register the first item as the default item (null ID).
-    this.registerAsDefault(id, item);
-    this.notifyWatchers();
+      // Register the first item as the default item (null ID).
+      if (this.items.size === 1 && id !== null) {
+        this.register(null, item);
+      }
+    });
   }
 
   /**
@@ -102,24 +179,23 @@ export class AsyncRegistry<T extends Destructible> {
    * @param error The error to register.
    */
   error(id: RegistryId | null, error: any): void {
-    this.items.delete(id);
-    this.initializationErrors.set(id, error);
+    this.batch(() => {
+      this.items.delete(id);
+      this.initializationErrors.set(id, error);
 
-    // Execute all pending error callbacks for this item.
-    const pending = this.pendingCallbacks.get(id);
+      // Execute all pending error callbacks for this item.
+      const pending = this.pendingCallbacks.get(id);
 
-    if (pending) {
-      pending.error.forEach(callback => callback(error));
-      this.pendingCallbacks.delete(id);
-    }
-
-    // Set as default error if this is the first error and no items exist.
-    if (this.initializationErrors.size === 1 && !this.items.size) {
-      this.error(null, error);
-    }
+      if (pending) {
+        pending.error.forEach(callback => callback(error));
+        this.pendingCallbacks.delete(id);
+      }
 
-    // Notify watchers about the error state.
-    this.notifyWatchers();
+      // Set as default error if this is the first error and no items exist.
+      if (this.initializationErrors.size === 1 && !this.items.size) {
+        this.error(null, error);
+      }
+    });
   }
 
   /**
@@ -142,21 +218,23 @@ export class AsyncRegistry<T extends Destructible> {
    * Un-registers an item.
    *
    * @param id The ID of the item.
+   * @param resetPendingCallbacks If true resets pending callbacks.
    */
-  unregister(id: RegistryId | null): void {
-    if (!this.items.has(id)) {
-      throw new Error(`Item with ID "${id}" is not registered.`);
-    }
+  unregister(id: RegistryId | null, resetPendingCallbacks: boolean = true): void {
+    this.batch(() => {
+      // If unregistering the default item, clear it.
+      if (id && this.items.get(null) === this.items.get(id)) {
+        this.unregister(null, false);
+      }
 
-    // If unregistering the default item, clear it.
-    if (id && this.items.get(null) === this.items.get(id)) {
-      this.unregister(null);
-    }
+      this.items.delete(id);
 
-    this.items.delete(id);
-    this.pendingCallbacks.delete(id);
+      if (resetPendingCallbacks) {
+        this.pendingCallbacks.delete(id);
+      }
 
-    this.notifyWatchers();
+      this.resetErrors(id);
+    });
   }
 
   /**
@@ -168,6 +246,15 @@ export class AsyncRegistry<T extends Destructible> {
     return Array.from(this.items.values());
   }
 
+  /**
+   * Returns single registered item.
+   *
+   * @returns Registered item.
+   */
+  getItem(id: RegistryId | null): T | undefined {
+    return this.items.get(id);
+  }
+
   /**
    * Checks if an item with the given ID is registered.
    *
@@ -207,7 +294,41 @@ export class AsyncRegistry<T extends Destructible> {
 
     await Promise.all(promises);
 
-    this.notifyWatchers();
+    this.flushWatchers();
+  }
+
+  /**
+   * Destroys all registered editors and removes all watchers.
+   */
+  async reset() {
+    await this.destroyAll();
+    this.watchers.clear();
+  }
+
+  /**
+   * Executes a callback while deferring all watcher notifications.
+   * A single notification is fired synchronously after the callback returns,
+   * but only if the registry actually changed.
+   *
+   * Batches can be nested — watchers are notified only when the outermost
+   * batch completes.
+   *
+   * @param fn The callback to execute.
+   * @returns The return value of the callback.
+   */
+  batch<R>(fn: () => R): R {
+    this.batchDepth++;
+
+    try {
+      return fn();
+    }
+    finally {
+      this.batchDepth--;
+
+      if (this.batchDepth === 0) {
+        this.flushWatchers();
+      }
+    }
   }
 
   /**
@@ -238,15 +359,23 @@ export class AsyncRegistry<T extends Destructible> {
   }
 
   /**
-   * Notifies all watchers about changes to the registry.
+   * Immediately dispatches the current state to all watchers if it changed.
    */
-  private notifyWatchers(): void {
-    this.watchers.forEach(
-      watcher => watcher(
-        new Map(this.items),
-        new Map(this.initializationErrors),
-      ),
-    );
+  private flushWatchers(): void {
+    if (
+      areMapsEqual(this.lastNotifiedItems, this.items)
+      && areMapsEqual(this.lastNotifiedErrors, this.initializationErrors)
+    ) {
+      return;
+    }
+
+    this.lastNotifiedItems = new Map(this.items);
+    this.lastNotifiedErrors = new Map(this.initializationErrors);
+
+    this.watchers.forEach(watcher => watcher(
+      new Map(this.items),
+      new Map(this.initializationErrors),
+    ));
   }
 
   /**
@@ -265,18 +394,6 @@ export class AsyncRegistry<T extends Destructible> {
 
     return pending;
   }
-
-  /**
-   * Registers an item as the default (null ID) item if it's the first one.
-   *
-   * @param id The ID of the item being registered.
-   * @param item The item instance.
-   */
-  private registerAsDefault(id: RegistryId | null, item: T): void {
-    if (this.items.size === 1 && id !== null) {
-      this.register(null, item);
-    }
-  }
 }
 
 /**

package/src/shared/index.ts

@@ -1,3 +1,4 @@
+export * from './are-maps-equal';
 export * from './async-registry';
 export * from './camel-case';
 export * from './debounce';