ckeditor5-livewire 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ckeditor5-livewire",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "CKEditor 5 integration for Laravel Livewire",
   "author": "Mateusz Bagiński <cziken58@gmail.com>",
   "license": "MIT",

package/src/hooks/context/context.test.ts

@@ -106,7 +106,7 @@ describe('context component', () => {
       expect(context?.plugins.get('CustomPlugin')).toBeInstanceOf(CustomPlugin);
     });
 
-    it('registered plugins should support custom translations', async () => {
+    describe('language', () => {
       class CustomPlugin extends ContextPlugin {
         static get pluginName() {
           return 'CustomPlugin';
@@ -117,71 +117,96 @@ describe('context component', () => {
         }
       }
 
-      CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
+      beforeEach(() => {
+        CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
+      });
 
-      livewireStub.$internal.appendComponentToDOM({
-        name: 'ckeditor5-context',
-        el: createContextHtmlElement(),
-        canonical: createContextSnapshot(DEFAULT_TEST_CONTEXT_ID, {
-          customTranslations: {
-            en: {
-              HELLO: 'Hello from CustomPlugin',
+      it('registered plugins should support custom translations', async () => {
+        livewireStub.$internal.appendComponentToDOM({
+          name: 'ckeditor5-context',
+          el: createContextHtmlElement(),
+          canonical: createContextSnapshot(DEFAULT_TEST_CONTEXT_ID, {
+            customTranslations: {
+              en: {
+                HELLO: 'Hello from CustomPlugin',
+              },
             },
-          },
-          config: {
-            plugins: ['CustomPlugin'],
-          },
-        }),
-      });
+            config: {
+              plugins: ['CustomPlugin'],
+            },
+          }),
+        });
 
-      const { context } = await waitForTestContext();
-      const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
+        const { context } = await waitForTestContext();
+        const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
 
-      expect(plugin.getHelloTitle()).toBe('Hello from CustomPlugin');
-    });
+        expect(plugin.getHelloTitle()).toBe('Hello from CustomPlugin');
+      });
 
-    it('should support custom language for context translations', async () => {
-      class CustomPlugin extends ContextPlugin {
-        static get pluginName() {
-          return 'CustomPlugin';
-        }
+      it('should support custom language for context translations', async () => {
+        livewireStub.$internal.appendComponentToDOM({
+          name: 'ckeditor5-context',
+          el: createContextHtmlElement(),
+          canonical: createContextSnapshot(
+            DEFAULT_TEST_CONTEXT_ID,
+            {
+              customTranslations: {
+                en: {
+                  HELLO: 'Hello from CustomPlugin',
+                },
+                pl: {
+                  HELLO: 'Witaj z CustomPlugin',
+                },
+              },
+              config: {
+                plugins: ['CustomPlugin'],
+              },
+            },
+            {
+              ui: 'pl',
+              content: 'pl',
+            },
+          ),
+        });
 
-        getHelloTitle() {
-          return this.context.t('HELLO');
-        }
-      }
+        const { context } = await waitForTestContext();
+        const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
 
-      CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
+        expect(plugin.getHelloTitle()).toBe('Witaj z CustomPlugin');
+      });
 
-      livewireStub.$internal.appendComponentToDOM({
-        name: 'ckeditor5-context',
-        el: createContextHtmlElement(),
-        canonical: createContextSnapshot(
-          DEFAULT_TEST_CONTEXT_ID,
-          {
-            customTranslations: {
-              en: {
-                HELLO: 'Hello from CustomPlugin',
+      it('should resolve $translation references in the context configuration', async () => {
+        livewireStub.$internal.appendComponentToDOM({
+          name: 'ckeditor5-context',
+          el: createContextHtmlElement(),
+          canonical: createContextSnapshot(
+            DEFAULT_TEST_CONTEXT_ID,
+            {
+              customTranslations: {
+                en: {
+                  Custom: 'Custom value',
+                },
+                pl: {
+                  Custom: 'Wartość niestandardowa',
+                },
               },
-              pl: {
-                HELLO: 'Witaj z CustomPlugin',
+              config: {
+                customPlugin: {
+                  label: { $translation: 'Custom' },
+                },
               },
             },
-            config: {
-              plugins: ['CustomPlugin'],
+            {
+              ui: 'pl',
+              content: 'pl',
             },
-          },
-          {
-            ui: 'pl',
-            content: 'pl',
-          },
-        ),
-      });
+          ),
+        });
 
-      const { context } = await waitForTestContext();
-      const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
+        const { context } = await waitForTestContext();
 
-      expect(plugin.getHelloTitle()).toBe('Witaj z CustomPlugin');
+        expect((context!.config.get('customPlugin') as any).label).toBe('Wartość niestandardowa');
+      });
     });
   });
 

package/src/hooks/context/context.ts

@@ -9,6 +9,8 @@ import {
   loadAllEditorTranslations,
   loadEditorPlugins,
   normalizeCustomTranslations,
+  resolveEditorConfigElementReferences,
+  resolveEditorConfigTranslations,
 } from '../editor/utils';
 import { ContextsRegistry } from './contexts-registry';
 
@@ -47,8 +49,14 @@ export class ContextComponentHook extends ClassHook<Snapshot> {
         ...watchdogConfig,
       });
 
+      // Construct parsed config. First resolve DOM element references in the provided configuration.
+      let resolvedConfig = resolveEditorConfigElementReferences(config);
+
+      // Then resolve translation references in the provided configuration, using the mixed translations.
+      resolvedConfig = resolveEditorConfigTranslations([...mixedTranslations].reverse(), language.ui, resolvedConfig);
+
       await instance.create({
-        ...config,
+        ...resolvedConfig,
         language,
         plugins: loadedPlugins,
         ...mixedTranslations.length && {

package/src/hooks/editor/editor.test.ts

@@ -531,6 +531,39 @@ describe('editor component', () => {
 
       expect(editor.t('Bold')).toBe('Czcionka grubaśna');
     });
+
+    it('should resolve $translation references in the editor configuration', async () => {
+      const preset = createEditorPreset(
+        'classic',
+        {
+          customPlugin: {
+            label: { $translation: 'Custom' },
+          },
+        },
+        {
+          pl: {
+            Custom: 'Mocarna czcionka',
+          },
+        },
+      );
+
+      livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+        name: 'ckeditor5',
+        el: createEditorHtmlElement(),
+        canonical: {
+          ...createEditorSnapshot(),
+          preset,
+          language: {
+            ui: 'pl',
+            content: 'pl',
+          },
+        },
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect((editor.config.get('customPlugin') as any).label).toBe('Mocarna czcionka');
+    });
   });
 
   describe('`watchdog` snapshot parameter`', () => {

package/src/hooks/editor/editor.ts

@@ -21,6 +21,7 @@ import {
   queryEditablesElements,
   queryEditablesSnapshotContent,
   resolveEditorConfigElementReferences,
+  resolveEditorConfigTranslations,
   setEditorEditableHeight,
   unwrapEditorContext,
   unwrapEditorWatchdog,
@@ -222,9 +223,15 @@ export class EditorComponentHook extends ClassHook<Snapshot> {
         sourceElements = sourceElements['main'];
       }
 
+      // Construct parsed config. First resolve DOM element references in the provided configuration.
+      let resolvedConfig = resolveEditorConfigElementReferences(config);
+
+      // Then resolve translation references in the provided configuration, using the mixed translations.
+      resolvedConfig = resolveEditorConfigTranslations([...mixedTranslations].reverse(), language.ui, resolvedConfig);
+
       // Construct parsed config.
       const parsedConfig = {
-        ...resolveEditorConfigElementReferences(config),
+        ...resolvedConfig,
         initialData,
         licenseKey,
         plugins: loadedPlugins,

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

@@ -8,5 +8,6 @@ export * from './load-editor-translations';
 export * from './normalize-custom-translations';
 export * from './query-editor-editables';
 export * from './resolve-editor-config-elements-references';
+export * from './resolve-editor-config-translations';
 export * from './set-editor-editable-height';
 export * from './wrap-with-watchdog';

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

@@ -1,3 +1,5 @@
+import type { Translations } from 'ckeditor5';
+
 /**
  * Loads all required translations for the editor based on the language configuration.
  *
@@ -10,7 +12,7 @@
 export async function loadAllEditorTranslations(
   language: { ui: string; content: string; },
   hasPremium: boolean,
-) {
+): Promise<Translations[]> {
   const translations = [language.ui, language.content];
   const loadedTranslations = await Promise.all(
     [

package/src/hooks/editor/utils/resolve-editor-config-translations.test.ts

@@ -0,0 +1,131 @@
+import type { Translations } from 'ckeditor5';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { resolveEditorConfigTranslations } from './resolve-editor-config-translations';
+
+describe('resolveEditorConfigTranslations', () => {
+  let translationsPacks: Translations[];
+
+  beforeEach(() => {
+    translationsPacks = [
+      makePack('en', {
+        HELLO: 'Hello world',
+        NESTED: 'nested value',
+        ARRAY: 'array value',
+      }),
+    ];
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('resolves a single translation reference', () => {
+    const config = {
+      foo: { $translation: 'HELLO' },
+    };
+
+    const result = resolveEditorConfigTranslations(translationsPacks, 'en', config);
+    expect(result.foo).toBe('Hello world');
+  });
+
+  it('respects specified language when multiple packs present', () => {
+    const packs: Translations[] = [
+      makePack('en', { KEY: 'english' }),
+      makePack('pl', { KEY: 'polish' }),
+    ];
+
+    const result = resolveEditorConfigTranslations(packs, 'pl', { foo: { $translation: 'KEY' } });
+    expect(result.foo).toBe('polish');
+  });
+
+  it('returns null if translation key not found', () => {
+    const config = {
+      foo: { $translation: 'MISSING' },
+    };
+
+    const result = resolveEditorConfigTranslations(translationsPacks, 'en', config);
+    expect(result.foo).toBeNull();
+  });
+
+  it('recursively resolves nested translation references', () => {
+    const config = {
+      nested: {
+        bar: { $translation: 'NESTED' },
+      },
+    };
+
+    const result = resolveEditorConfigTranslations(translationsPacks, 'en', config);
+    expect(result.nested.bar).toBe('nested value');
+  });
+
+  it('resolves translation references in arrays', () => {
+    const config = [
+      { $translation: 'HELLO' },
+      { $translation: 'ARRAY' },
+      { notTranslation: 123 },
+    ];
+
+    const result = resolveEditorConfigTranslations(translationsPacks, 'en', config);
+
+    expect(result[0]).toBe('Hello world');
+    expect(result[1]).toBe('array value');
+    expect(result[2]).toEqual({ notTranslation: 123 });
+  });
+
+  it('returns primitives as is', () => {
+    expect(resolveEditorConfigTranslations(translationsPacks, 'en', 42 as any)).toBe(42);
+    expect(resolveEditorConfigTranslations(translationsPacks, 'en', 'foo' as any)).toBe('foo');
+    expect(resolveEditorConfigTranslations(translationsPacks, 'en', null as any)).toBe(null);
+    expect(resolveEditorConfigTranslations(translationsPacks, 'en', undefined as any)).toBe(undefined);
+  });
+
+  it('warns for missing translation key', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const config = { foo: { $translation: 'UNKNOWN' } };
+
+    resolveEditorConfigTranslations(translationsPacks, 'en', config);
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Translation not found for key: UNKNOWN'));
+  });
+
+  it('selects translations based on the provided language when multiple packs are given', () => {
+    const packs: Translations[] = [
+      makePack('en', { HELLO: 'Hello world', ARRAY: 'array value' }),
+      makePack('pl', { NESTED: 'nested value' }),
+    ];
+
+    const config = {
+      foo: { $translation: 'HELLO' },
+      nested: { bar: { $translation: 'NESTED' } },
+      arr: [{ $translation: 'ARRAY' }],
+      missing: { $translation: 'NOTHING' },
+    };
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const resultEn = resolveEditorConfigTranslations(packs, 'en', config);
+
+    expect(resultEn.foo).toBe('Hello world');
+    expect(resultEn.nested.bar).toBeNull();
+    expect(resultEn.arr[0]).toBe('array value');
+    expect(resultEn.missing).toBeNull();
+
+    const resultPl = resolveEditorConfigTranslations(packs, 'pl', config);
+
+    expect(resultPl.foo).toBeNull();
+    expect(resultPl.nested.bar).toBe('nested value');
+    expect(resultPl.arr[0]).toBeNull();
+    expect(resultPl.missing).toBeNull();
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Translation not found for key: NOTHING'));
+  });
+});
+
+function makePack(lang: string, dict: Record<string, string>): Translations {
+  return {
+    [lang]: {
+      dictionary: dict,
+      getPluralForm: null,
+    },
+  };
+}

package/src/hooks/editor/utils/resolve-editor-config-translations.ts

@@ -0,0 +1,77 @@
+import type { Translations } from 'ckeditor5';
+
+/**
+ * Resolves translation references in a configuration object.
+ *
+ * The configuration may contain objects with the form `{ $translation: "some.key" }`.
+ * These are replaced with the actual string from the provided translations map.
+ *
+ * The function will walk the provided object recursively, handling arrays and
+ * nested objects. Primitive values are returned as-is. If a translation key is
+ * not present in the map, a warning is logged and `null` is returned for that
+ * value.
+ *
+ * @param translations - An array of CKEditor `Translations` objects. Each translation
+ *                       pack will be searched in order for the requested key, and the
+ *                       first matching value will be returned. This mirrors the format
+ *                       returned by `loadAllEditorTranslations` and simplifies the
+ *                       caller's API.
+ * @param language - Language identifier to look up in the packs. Only this locale
+ *                   will be consulted, ensuring that keys from other languages are
+ *                   ignored even if they appear earlier in the array.
+ * @param obj - Configuration object to process
+ * @returns Processed configuration object with resolved translations.
+ */
+export function resolveEditorConfigTranslations<T>(
+  translations: Translations[],
+  language: string,
+  obj: T,
+): T {
+  if (!obj || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => resolveEditorConfigTranslations(translations, language, item)) as T;
+  }
+
+  const anyObj = obj as any;
+
+  if (anyObj.$translation && typeof anyObj.$translation === 'string') {
+    const key: string = anyObj.$translation;
+    const value = getTranslationValue(translations, key, language);
+
+    if (value === undefined) {
+      console.warn(`Translation not found for key: ${key}`);
+    }
+
+    return (value !== undefined ? value : null) as T;
+  }
+
+  const result = Object.create(null);
+
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = resolveEditorConfigTranslations(translations, language, value);
+  }
+
+  return result as T;
+}
+
+/**
+ * Look up a translation value inside the provided map or array of CKEditor packs.
+ */
+function getTranslationValue(
+  translations: Translations[],
+  key: string,
+  language: string,
+): string | ReadonlyArray<string> | undefined {
+  for (const pack of translations) {
+    const langData = pack[language];
+
+    if (langData?.dictionary && key in langData.dictionary) {
+      return langData.dictionary[key] as string | ReadonlyArray<string>;
+    }
+  }
+
+  return undefined;
+}