ckeditor5-blazor 0.1.0

package/src/shared/is-plain-object.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { isPlainObject } from './is-plain-object';
+
+describe('isPlainObject', () => {
+  it('returns true for plain objects', () => {
+    expect(isPlainObject({})).toBe(true);
+    expect(isPlainObject({ a: 1, b: 2 })).toBe(true);
+    expect(isPlainObject(Object.create(null))).toBe(true);
+  });
+
+  it('returns false for arrays', () => {
+    expect(isPlainObject([])).toBe(false);
+    expect(isPlainObject([1, 2, 3])).toBe(false);
+  });
+
+  it('returns false for null', () => {
+    expect(isPlainObject(null)).toBe(false);
+  });
+
+  it('returns false for primitives', () => {
+    expect(isPlainObject(42)).toBe(false);
+    expect(isPlainObject('string')).toBe(false);
+    expect(isPlainObject(true)).toBe(false);
+    expect(isPlainObject(undefined)).toBe(false);
+    expect(isPlainObject(Symbol('sym'))).toBe(false);
+  });
+
+  it('returns false for class instances', () => {
+    class MyClass {}
+    expect(isPlainObject(new MyClass())).toBe(false);
+  });
+
+  it('returns false for functions', () => {
+    expect(isPlainObject(() => {})).toBe(false);
+    expect(isPlainObject(() => {})).toBe(false);
+  });
+});

package/src/shared/is-plain-object.ts

@@ -0,0 +1,15 @@
+/**
+ * Utility to check if a value is a plain object (not an array, not null, not a class instance).
+ *
+ * @param value The value to check.
+ * @returns True if the value is a plain object, false otherwise.
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (Object.prototype.toString.call(value) !== '[object Object]') {
+    return false;
+  }
+
+  const proto = Object.getPrototypeOf(value);
+
+  return proto === Object.prototype || proto === null;
+}

package/src/shared/map-object-values.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { mapObjectValues } from './map-object-values';
+
+describe('mapObjectValues', () => {
+  it('should map object values using the provided mapper function', () => {
+    const input = { a: 1, b: 2, c: 3 };
+    const mapper = (value: number) => value * 2;
+    const result = mapObjectValues(input, mapper);
+
+    expect(result).toEqual({ a: 2, b: 4, c: 6 });
+  });
+
+  it('should pass the key to the mapper function', () => {
+    const input = { x: 'foo', y: 'bar' };
+    const mapper = (value: string, key: string) => `${key}:${value}`;
+    const result = mapObjectValues(input, mapper);
+
+    expect(result).toEqual({ x: 'x:foo', y: 'y:bar' });
+  });
+
+  it('should return an empty object if the input is empty', () => {
+    const input: Record<string, number> = {};
+    const mapper = (value: number) => value * 2;
+    const result = mapObjectValues(input, mapper);
+
+    expect(result).toEqual({});
+  });
+});

package/src/shared/map-object-values.ts

@@ -0,0 +1,19 @@
+/**
+ * Maps the values of an object using a provided mapper function.
+ *
+ * @param obj The object whose values will be mapped.
+ * @param mapper A function that takes a value and its key, and returns a new value.
+ * @template T The type of the original values in the object.
+ * @template U The type of the new values in the object.
+ * @returns A new object with the same keys as the original, but with values transformed by
+ */
+export function mapObjectValues<T, U>(
+  obj: Record<string, T>,
+  mapper: (value: T, key: string) => U,
+): Record<string, U> {
+  const mappedEntries = Object
+    .entries(obj)
+    .map(([key, value]) => [key, mapper(value, key)] as const);
+
+  return Object.fromEntries(mappedEntries);
+}

package/src/shared/once.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { once } from './once';
+
+describe('once', () => {
+  it('should call the original function only once', () => {
+    const mockFn = vi.fn().mockReturnValue('result');
+    const onceFn = once(mockFn);
+
+    onceFn();
+    onceFn();
+    onceFn();
+
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should return the same result on subsequent calls', () => {
+    const mockFn = vi.fn().mockReturnValue('test-result');
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn();
+    const result2 = onceFn();
+    const result3 = onceFn();
+
+    expect(result1).toBe('test-result');
+    expect(result2).toBe('test-result');
+    expect(result3).toBe('test-result');
+  });
+
+  it('should pass arguments to the original function', () => {
+    const mockFn = vi.fn();
+    const onceFn = once(mockFn);
+
+    onceFn('arg1', 'arg2', 'arg3');
+    onceFn('different', 'args');
+
+    expect(mockFn).toHaveBeenCalledTimes(1);
+    expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2', 'arg3');
+  });
+
+  it('should preserve the context (this) when called', () => {
+    const context = { value: 'test-context' };
+    const mockFn = vi.fn(function (this: typeof context) {
+      return this.value;
+    });
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn.call(context);
+    const result2 = onceFn.call({ value: 'different-context' });
+
+    expect(result1).toBe('test-context');
+    expect(result2).toBe('test-context');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should work with functions that return undefined', () => {
+    const mockFn = vi.fn().mockReturnValue(undefined);
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn();
+    const result2 = onceFn();
+
+    expect(result1).toBeUndefined();
+    expect(result2).toBeUndefined();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should work with async functions', async () => {
+    const mockFn = vi.fn().mockResolvedValue('async-result');
+    const onceFn = once(mockFn);
+
+    const result1 = await onceFn();
+    const result2 = await onceFn();
+
+    expect(result1).toBe('async-result');
+    expect(result2).toBe('async-result');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should maintain function signature for type safety', () => {
+    const originalFn = (a: string, b: number): string => `${a}-${b}`;
+    const onceFn = once(originalFn);
+
+    const result = onceFn('test', 42);
+
+    expect(result).toBe('test-42');
+    expect(typeof result).toBe('string');
+  });
+
+  it('should work with functions that have no parameters', () => {
+    let counter = 0;
+    const mockFn = vi.fn(() => ++counter);
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn();
+    const result2 = onceFn();
+
+    expect(result1).toBe(1);
+    expect(result2).toBe(1);
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should work with functions that return objects', () => {
+    const returnValue = { id: 1, name: 'test' };
+    const mockFn = vi.fn().mockReturnValue(returnValue);
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn();
+    const result2 = onceFn();
+
+    expect(result1).toBe(returnValue);
+    expect(result2).toBe(returnValue);
+    expect(result1).toEqual({ id: 1, name: 'test' });
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+});

package/src/shared/once.ts

@@ -0,0 +1,12 @@
+export function once<T extends (...args: any[]) => any>(fn: T): T {
+  let called = false;
+  let result: ReturnType<T>;
+
+  return function (this: any, ...args: Parameters<T>): ReturnType<T> {
+    if (!called) {
+      called = true;
+      result = fn.apply(this, args);
+    }
+    return result;
+  } as T;
+}

package/src/shared/shallow-equal.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import { shallowEqual } from './shallow-equal';
+
+describe('shallowEqual', () => {
+  it('should return true for identical objects', () => {
+    const obj = { a: 1, b: 2 };
+    expect(shallowEqual(obj, obj)).toBe(true);
+  });
+
+  it('should return true for objects with same primitive values', () => {
+    const objA = { a: 1, b: 'test', c: true };
+    const objB = { a: 1, b: 'test', c: true };
+    expect(shallowEqual(objA, objB)).toBe(true);
+  });
+
+  it('should return false for objects with different values', () => {
+    const objA = { a: 1, b: 2 };
+    const objB = { a: 1, b: 3 };
+    expect(shallowEqual(objA, objB)).toBe(false);
+  });
+
+  it('should return false for objects with different keys', () => {
+    const objA = { a: 1, b: 2 };
+    const objB = { a: 1, c: 2 } as any;
+    expect(shallowEqual(objA, objB)).toBe(false);
+  });
+
+  it('should return false for objects with different number of keys', () => {
+    const objA = { a: 1, b: 2 };
+    const objB = { a: 1 };
+    expect(shallowEqual(objA, objB)).toBe(false);
+  });
+
+  it('should return true for empty objects', () => {
+    expect(shallowEqual({}, {})).toBe(true);
+  });
+
+  it('should return false for nested objects with same structure but different references', () => {
+    const objA = { a: { nested: 1 } };
+    const objB = { a: { nested: 1 } };
+    expect(shallowEqual(objA, objB)).toBe(false);
+  });
+
+  it('should return true for nested objects with same reference', () => {
+    const nested = { value: 1 };
+    const objA = { a: nested };
+    const objB = { a: nested };
+    expect(shallowEqual(objA, objB)).toBe(true);
+  });
+});

package/src/shared/shallow-equal.ts

@@ -0,0 +1,30 @@
+/**
+ * Performs a shallow comparison of two objects.
+ *
+ * @param objA - The first object to compare.
+ * @param objB - The second object to compare.
+ * @returns True if the objects are shallowly equal, false otherwise.
+ */
+export function shallowEqual<T extends Record<string, unknown>>(
+  objA: T,
+  objB: T,
+): boolean {
+  if (objA === objB) {
+    return true;
+  }
+
+  const keysA = Object.keys(objA);
+  const keysB = Object.keys(objB);
+
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+
+  for (const key of keysA) {
+    if (objA[key] !== objB[key] || !Object.prototype.hasOwnProperty.call(objB, key)) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/shared/timeout.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { timeout } from './timeout.js';
+
+describe('timeout', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should resolve after specified milliseconds', async () => {
+    const promise = timeout(1000);
+
+    vi.advanceTimersByTime(1000);
+
+    await expect(promise).resolves.toBeUndefined();
+  });
+
+  it('should not resolve before specified time', async () => {
+    let resolved = false;
+    const promise = timeout(1000).then(() => {
+      resolved = true;
+    });
+
+    vi.advanceTimersByTime(500);
+
+    expect(resolved).toBe(false);
+
+    vi.advanceTimersByTime(500);
+    await promise;
+
+    expect(resolved).toBe(true);
+  });
+
+  it('should resolve immediately when milliseconds is 0', async () => {
+    const promise = timeout(0);
+
+    vi.advanceTimersByTime(0);
+
+    await expect(promise).resolves.toBeUndefined();
+  });
+
+  it('should handle multiple concurrent timeouts', async () => {
+    const results: number[] = [];
+
+    const promise1 = timeout(100).then(() => results.push(1));
+    const promise2 = timeout(200).then(() => results.push(2));
+    const promise3 = timeout(150).then(() => results.push(3));
+
+    vi.advanceTimersByTime(100);
+    await promise1;
+    expect(results).toEqual([1]);
+
+    vi.advanceTimersByTime(50);
+    await promise3;
+    expect(results).toEqual([1, 3]);
+
+    vi.advanceTimersByTime(50);
+    await promise2;
+    expect(results).toEqual([1, 3, 2]);
+  });
+});

package/src/shared/timeout.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns a promise that resolves after a specified number of milliseconds.
+ *
+ * @param ms The number of milliseconds to wait.
+ * @returns A promise that resolves after the specified time.
+ */
+export function timeout(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve();
+    }, ms);
+  });
+}

package/src/shared/uid.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { uid } from './uid';
+
+describe('uid', () => {
+  it('should return a string', () => {
+    const id = uid();
+    expect(typeof id).toBe('string');
+  });
+
+  it('should return a non-empty string', () => {
+    const id = uid();
+    expect(id.length).toBeGreaterThan(0);
+  });
+
+  it('should return different values on subsequent calls', () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => uid()));
+    expect(ids.size).toBe(1000);
+  });
+
+  it('should only contain alphanumeric characters', () => {
+    const id = uid();
+    expect(/^[a-z0-9]+$/i.test(id)).toBe(true);
+  });
+});

package/src/shared/uid.ts

@@ -0,0 +1,8 @@
+/**
+ * Generates a unique identifier string
+ *
+ * @returns Random string that can be used as unique identifier
+ */
+export function uid() {
+  return Math.random().toString(36).substring(2);
+}

package/src/shared/wait-for-dom-ready.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { timeout } from './timeout.js';
+import { waitForDOMReady } from './wait-for-dom-ready.js';
+
+describe('waitForDOMReady', () => {
+  let originalReadyState: DocumentReadyState;
+
+  beforeEach(() => {
+    originalReadyState = document.readyState;
+  });
+
+  afterEach(() => {
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return originalReadyState; },
+    });
+
+    vi.restoreAllMocks();
+  });
+
+  it('should resolve immediately if readyState is "interactive"', async () => {
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return 'interactive'; },
+    });
+
+    const spy = vi.fn();
+    void waitForDOMReady().then(spy);
+
+    await timeout(0);
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('should resolve immediately if readyState is "complete"', async () => {
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return 'complete'; },
+    });
+
+    const spy = vi.fn();
+    void waitForDOMReady().then(spy);
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('should wait for DOMContentLoaded event if readyState is "loading"', async () => {
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return 'loading'; },
+    });
+
+    const addEventListenerSpy = vi.spyOn(document, 'addEventListener');
+    const spy = vi.fn();
+
+    void waitForDOMReady().then(spy);
+
+    expect(addEventListenerSpy).toHaveBeenCalledWith('DOMContentLoaded', expect.any(Function), { once: true });
+    expect(spy).not.toHaveBeenCalled();
+
+    // Simulate the event
+    const handler = addEventListenerSpy.mock.calls[0]?.[1] as EventListener;
+    handler({} as Event);
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('should warn and resolve immediately for unexpected readyState', async () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return 'unexpected'; },
+    });
+
+    const spy = vi.fn();
+    void waitForDOMReady().then(spy);
+
+    await timeout(0);
+    expect(consoleWarnSpy).toHaveBeenCalledWith('Unexpected document.readyState:', 'unexpected');
+    expect(spy).toHaveBeenCalled();
+
+    consoleWarnSpy.mockRestore();
+  });
+});

package/src/shared/wait-for-dom-ready.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns a promise that resolves when the DOM is fully loaded and ready.
+ */
+export function waitForDOMReady(): Promise<void> {
+  return new Promise((resolve) => {
+    switch (document.readyState) {
+      case 'loading':
+        document.addEventListener('DOMContentLoaded', () => resolve(), { once: true });
+        break;
+
+      case 'interactive':
+      case 'complete':
+        setTimeout(resolve, 0);
+        break;
+
+      default:
+        console.warn('Unexpected document.readyState:', document.readyState);
+        setTimeout(resolve, 0);
+    }
+  });
+}

package/src/shared/wait-for-interactive-attribute.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { markElementAsInteractive, waitForInteractiveAttribute } from './wait-for-interactive-attribute';
+
+describe('waitForInteractiveAttribute', () => {
+  let element: HTMLElement;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    element = document.createElement('div');
+    document.body.appendChild(element);
+  });
+
+  afterEach(() => {
+    document.body.removeChild(element);
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it('should resolve immediately if the element already has the data-cke-interactive attribute', async () => {
+    markElementAsInteractive(element);
+
+    const result = waitForInteractiveAttribute(element);
+
+    await expect(result.promise).resolves.toBeUndefined();
+  });
+
+  it('should wait for the data-cke-interactive attribute to be added', async () => {
+    const result = waitForInteractiveAttribute(element);
+    const successSpy = vi.fn();
+
+    // Attach a spy to the promise to track its resolution status
+    void result.promise.then(successSpy);
+
+    // 1. Ensure the promise is pending initially (flush microtasks)
+    await vi.advanceTimersByTimeAsync(0);
+    expect(successSpy).not.toHaveBeenCalled();
+
+    // 2. Add the attribute
+    markElementAsInteractive(element);
+
+    // 3. Ensure the promise resolves after the mutation
+    await expect(result.promise).resolves.toBeUndefined();
+    expect(successSpy).toHaveBeenCalled();
+  });
+
+  it('should NOT resolve if a different attribute is added', async () => {
+    const result = waitForInteractiveAttribute(element);
+    const successSpy = vi.fn();
+
+    void result.promise.then(successSpy);
+
+    // Add an irrelevant attribute
+    element.setAttribute('data-other', '');
+
+    // Advance time and flush tasks to give the observer a chance to react (incorrectly)
+    await vi.advanceTimersByTimeAsync(100);
+
+    // The promise should still be pending
+    expect(successSpy).not.toHaveBeenCalled();
+  });
+
+  it('should disconnect the observer automatically when the attribute is added', async () => {
+    // Spy on the native MutationObserver disconnect method
+    const disconnectSpy = vi.spyOn(MutationObserver.prototype, 'disconnect');
+
+    const result = waitForInteractiveAttribute(element);
+    markElementAsInteractive(element);
+
+    await result.promise;
+
+    expect(disconnectSpy).toHaveBeenCalled();
+  });
+
+  it('should allow disconnecting the observer manually and stop listening', async () => {
+    const disconnectSpy = vi.spyOn(MutationObserver.prototype, 'disconnect');
+    const result = waitForInteractiveAttribute(element);
+    const successSpy = vi.fn();
+
+    void result.promise.then(successSpy);
+
+    // 1. Manually disconnect
+    result.disconnect();
+    expect(disconnectSpy).toHaveBeenCalled();
+
+    // 2. Add the attribute AFTER disconnecting
+    markElementAsInteractive(element);
+
+    // 3. Verify the promise remains pending (observer should be dead)
+    await vi.advanceTimersByTimeAsync(100);
+    expect(successSpy).not.toHaveBeenCalled();
+  });
+});

package/src/shared/wait-for-interactive-attribute.ts

@@ -0,0 +1,50 @@
+/**
+ * Waits for the 'data-cke-interactive' attribute to be added to the element.
+ */
+export function waitForInteractiveAttribute(element: HTMLElement): WaitForInteractiveResult {
+  if (element.hasAttribute('data-cke-interactive')) {
+    return { promise: Promise.resolve(), disconnect: () => {} };
+  }
+
+  let observer: MutationObserver;
+
+  const promise = new Promise<void>((resolve) => {
+    observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (
+          mutation.type === 'attributes'
+          && mutation.attributeName === 'data-cke-interactive'
+          && element.hasAttribute('data-cke-interactive')
+        ) {
+          observer.disconnect();
+          resolve();
+          break;
+        }
+      }
+    });
+
+    observer.observe(element, { attributes: true });
+  });
+
+  return {
+    promise,
+    disconnect: () => observer?.disconnect(),
+  };
+}
+
+/**
+ * Marks the given element as interactive by adding the 'data-cke-interactive' attribute.
+ *
+ * @param element - The HTML element to mark as interactive.
+ */
+export function markElementAsInteractive(element: HTMLElement) {
+  element.setAttribute('data-cke-interactive', 'true');
+}
+
+/**
+ * Result of waiting for the interactive attribute.
+ */
+export type WaitForInteractiveResult = {
+  promise: Promise<void>;
+  disconnect: () => void;
+};