ckeditor5-blazor 0.1.0

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

@@ -0,0 +1,232 @@
+/**
+ * Loads all required translations for the editor based on the language configuration.
+ *
+ * @param language - The language configuration object containing UI and content language codes.
+ * @param language.ui - The UI language code.
+ * @param language.content - The content language code.
+ * @param hasPremium - Whether premium features are enabled and premium translations should be loaded.
+ * @returns A promise that resolves to an array of loaded translation objects.
+ */
+export async function loadAllEditorTranslations(
+  language: { ui: string; content: string; },
+  hasPremium: boolean,
+) {
+  const translations = [language.ui, language.content];
+  const loadedTranslations = await Promise.all(
+    [
+      loadEditorPkgTranslations('ckeditor5', translations),
+
+      /* v8 ignore next -- @preserve */
+      hasPremium && loadEditorPkgTranslations('ckeditor5-premium-features', translations),
+    ].filter(pkg => !!pkg),
+  )
+    .then(translations => translations.flat());
+
+  return loadedTranslations;
+}
+
+/**
+ * Loads the editor translations for the given languages.
+ *
+ * Make sure this function is properly compiled and bundled in self hosted environments!
+ *
+ * @param pkg - The package to load translations from ('ckeditor5' or 'ckeditor5-premium-features').
+ * @param translations - The list of language codes to load translations for.
+ * @returns A promise that resolves to an array of loaded translation packs.
+ */
+async function loadEditorPkgTranslations(
+  pkg: EditorPkgName,
+  translations: string[],
+) {
+  return await Promise.all(
+    translations
+      .filter(lang => lang !== 'en') // 'en' is the default language, no need to load it.
+      .map(async (lang) => {
+        const pack = await loadEditorTranslation(pkg, lang);
+
+        /* v8 ignore next -- @preserve */
+        return pack?.default ?? pack;
+      })
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Type representing the package name for CKEditor 5.
+ */
+type EditorPkgName = 'ckeditor5' | 'ckeditor5-premium-features';
+
+/**
+ * Load translation for CKEditor 5
+ * @param pkg - Package type: 'ckeditor5' or 'premium'
+ * @param lang - Language code (e.g., 'pl', 'en', 'de')
+ * @returns Translation object or null if failed
+ */
+async function loadEditorTranslation(pkg: EditorPkgName, lang: string): Promise<any> {
+  try {
+    /* v8 ignore next if -- @preserve */
+    if (pkg === 'ckeditor5') {
+      switch (lang) {
+        case 'af': return await import('ckeditor5/translations/af.js');
+        case 'ar': return await import('ckeditor5/translations/ar.js');
+        case 'ast': return await import('ckeditor5/translations/ast.js');
+        case 'az': return await import('ckeditor5/translations/az.js');
+        case 'bg': return await import('ckeditor5/translations/bg.js');
+        case 'bn': return await import('ckeditor5/translations/bn.js');
+        case 'bs': return await import('ckeditor5/translations/bs.js');
+        case 'ca': return await import('ckeditor5/translations/ca.js');
+        case 'cs': return await import('ckeditor5/translations/cs.js');
+        case 'da': return await import('ckeditor5/translations/da.js');
+        case 'de': return await import('ckeditor5/translations/de.js');
+        case 'de-ch': return await import('ckeditor5/translations/de-ch.js');
+        case 'el': return await import('ckeditor5/translations/el.js');
+        case 'en': return await import('ckeditor5/translations/en.js');
+        case 'en-au': return await import('ckeditor5/translations/en-au.js');
+        case 'en-gb': return await import('ckeditor5/translations/en-gb.js');
+        case 'eo': return await import('ckeditor5/translations/eo.js');
+        case 'es': return await import('ckeditor5/translations/es.js');
+        case 'es-co': return await import('ckeditor5/translations/es-co.js');
+        case 'et': return await import('ckeditor5/translations/et.js');
+        case 'eu': return await import('ckeditor5/translations/eu.js');
+        case 'fa': return await import('ckeditor5/translations/fa.js');
+        case 'fi': return await import('ckeditor5/translations/fi.js');
+        case 'fr': return await import('ckeditor5/translations/fr.js');
+        case 'gl': return await import('ckeditor5/translations/gl.js');
+        case 'gu': return await import('ckeditor5/translations/gu.js');
+        case 'he': return await import('ckeditor5/translations/he.js');
+        case 'hi': return await import('ckeditor5/translations/hi.js');
+        case 'hr': return await import('ckeditor5/translations/hr.js');
+        case 'hu': return await import('ckeditor5/translations/hu.js');
+        case 'hy': return await import('ckeditor5/translations/hy.js');
+        case 'id': return await import('ckeditor5/translations/id.js');
+        case 'it': return await import('ckeditor5/translations/it.js');
+        case 'ja': return await import('ckeditor5/translations/ja.js');
+        case 'jv': return await import('ckeditor5/translations/jv.js');
+        case 'kk': return await import('ckeditor5/translations/kk.js');
+        case 'km': return await import('ckeditor5/translations/km.js');
+        case 'kn': return await import('ckeditor5/translations/kn.js');
+        case 'ko': return await import('ckeditor5/translations/ko.js');
+        case 'ku': return await import('ckeditor5/translations/ku.js');
+        case 'lt': return await import('ckeditor5/translations/lt.js');
+        case 'lv': return await import('ckeditor5/translations/lv.js');
+        case 'ms': return await import('ckeditor5/translations/ms.js');
+        case 'nb': return await import('ckeditor5/translations/nb.js');
+        case 'ne': return await import('ckeditor5/translations/ne.js');
+        case 'nl': return await import('ckeditor5/translations/nl.js');
+        case 'no': return await import('ckeditor5/translations/no.js');
+        case 'oc': return await import('ckeditor5/translations/oc.js');
+        case 'pl': return await import('ckeditor5/translations/pl.js');
+        case 'pt': return await import('ckeditor5/translations/pt.js');
+        case 'pt-br': return await import('ckeditor5/translations/pt-br.js');
+        case 'ro': return await import('ckeditor5/translations/ro.js');
+        case 'ru': return await import('ckeditor5/translations/ru.js');
+        case 'si': return await import('ckeditor5/translations/si.js');
+        case 'sk': return await import('ckeditor5/translations/sk.js');
+        case 'sl': return await import('ckeditor5/translations/sl.js');
+        case 'sq': return await import('ckeditor5/translations/sq.js');
+        case 'sr': return await import('ckeditor5/translations/sr.js');
+        case 'sr-latn': return await import('ckeditor5/translations/sr-latn.js');
+        case 'sv': return await import('ckeditor5/translations/sv.js');
+        case 'th': return await import('ckeditor5/translations/th.js');
+        case 'tk': return await import('ckeditor5/translations/tk.js');
+        case 'tr': return await import('ckeditor5/translations/tr.js');
+        case 'tt': return await import('ckeditor5/translations/tt.js');
+        case 'ug': return await import('ckeditor5/translations/ug.js');
+        case 'uk': return await import('ckeditor5/translations/uk.js');
+        case 'ur': return await import('ckeditor5/translations/ur.js');
+        case 'uz': return await import('ckeditor5/translations/uz.js');
+        case 'vi': return await import('ckeditor5/translations/vi.js');
+        case 'zh': return await import('ckeditor5/translations/zh.js');
+        case 'zh-cn': return await import('ckeditor5/translations/zh-cn.js');
+        default:
+          console.warn(`Language ${lang} not found in ckeditor5 translations`);
+          return null;
+      }
+    }
+    else {
+      // Premium features translations
+      switch (lang) {
+        case 'af': return await import('ckeditor5-premium-features/translations/af.js');
+        case 'ar': return await import('ckeditor5-premium-features/translations/ar.js');
+        case 'ast': return await import('ckeditor5-premium-features/translations/ast.js');
+        case 'az': return await import('ckeditor5-premium-features/translations/az.js');
+        case 'bg': return await import('ckeditor5-premium-features/translations/bg.js');
+        case 'bn': return await import('ckeditor5-premium-features/translations/bn.js');
+        case 'bs': return await import('ckeditor5-premium-features/translations/bs.js');
+        case 'ca': return await import('ckeditor5-premium-features/translations/ca.js');
+        case 'cs': return await import('ckeditor5-premium-features/translations/cs.js');
+        case 'da': return await import('ckeditor5-premium-features/translations/da.js');
+        case 'de': return await import('ckeditor5-premium-features/translations/de.js');
+        case 'de-ch': return await import('ckeditor5-premium-features/translations/de-ch.js');
+        case 'el': return await import('ckeditor5-premium-features/translations/el.js');
+        case 'en': return await import('ckeditor5-premium-features/translations/en.js');
+        case 'en-au': return await import('ckeditor5-premium-features/translations/en-au.js');
+        case 'en-gb': return await import('ckeditor5-premium-features/translations/en-gb.js');
+        case 'eo': return await import('ckeditor5-premium-features/translations/eo.js');
+        case 'es': return await import('ckeditor5-premium-features/translations/es.js');
+        case 'es-co': return await import('ckeditor5-premium-features/translations/es-co.js');
+        case 'et': return await import('ckeditor5-premium-features/translations/et.js');
+        case 'eu': return await import('ckeditor5-premium-features/translations/eu.js');
+        case 'fa': return await import('ckeditor5-premium-features/translations/fa.js');
+        case 'fi': return await import('ckeditor5-premium-features/translations/fi.js');
+        case 'fr': return await import('ckeditor5-premium-features/translations/fr.js');
+        case 'gl': return await import('ckeditor5-premium-features/translations/gl.js');
+        case 'gu': return await import('ckeditor5-premium-features/translations/gu.js');
+        case 'he': return await import('ckeditor5-premium-features/translations/he.js');
+        case 'hi': return await import('ckeditor5-premium-features/translations/hi.js');
+        case 'hr': return await import('ckeditor5-premium-features/translations/hr.js');
+        case 'hu': return await import('ckeditor5-premium-features/translations/hu.js');
+        case 'hy': return await import('ckeditor5-premium-features/translations/hy.js');
+        case 'id': return await import('ckeditor5-premium-features/translations/id.js');
+        case 'it': return await import('ckeditor5-premium-features/translations/it.js');
+        case 'ja': return await import('ckeditor5-premium-features/translations/ja.js');
+        case 'jv': return await import('ckeditor5-premium-features/translations/jv.js');
+        case 'kk': return await import('ckeditor5-premium-features/translations/kk.js');
+        case 'km': return await import('ckeditor5-premium-features/translations/km.js');
+        case 'kn': return await import('ckeditor5-premium-features/translations/kn.js');
+        case 'ko': return await import('ckeditor5-premium-features/translations/ko.js');
+        case 'ku': return await import('ckeditor5-premium-features/translations/ku.js');
+        case 'lt': return await import('ckeditor5-premium-features/translations/lt.js');
+        case 'lv': return await import('ckeditor5-premium-features/translations/lv.js');
+        case 'ms': return await import('ckeditor5-premium-features/translations/ms.js');
+        case 'nb': return await import('ckeditor5-premium-features/translations/nb.js');
+        case 'ne': return await import('ckeditor5-premium-features/translations/ne.js');
+        case 'nl': return await import('ckeditor5-premium-features/translations/nl.js');
+        case 'no': return await import('ckeditor5-premium-features/translations/no.js');
+        case 'oc': return await import('ckeditor5-premium-features/translations/oc.js');
+        case 'pl': return await import('ckeditor5-premium-features/translations/pl.js');
+        case 'pt': return await import('ckeditor5-premium-features/translations/pt.js');
+        case 'pt-br': return await import('ckeditor5-premium-features/translations/pt-br.js');
+        case 'ro': return await import('ckeditor5-premium-features/translations/ro.js');
+        case 'ru': return await import('ckeditor5-premium-features/translations/ru.js');
+        case 'si': return await import('ckeditor5-premium-features/translations/si.js');
+        case 'sk': return await import('ckeditor5-premium-features/translations/sk.js');
+        case 'sl': return await import('ckeditor5-premium-features/translations/sl.js');
+        case 'sq': return await import('ckeditor5-premium-features/translations/sq.js');
+        case 'sr': return await import('ckeditor5-premium-features/translations/sr.js');
+        case 'sr-latn': return await import('ckeditor5-premium-features/translations/sr-latn.js');
+        case 'sv': return await import('ckeditor5-premium-features/translations/sv.js');
+        case 'th': return await import('ckeditor5-premium-features/translations/th.js');
+        case 'tk': return await import('ckeditor5-premium-features/translations/tk.js');
+        case 'tr': return await import('ckeditor5-premium-features/translations/tr.js');
+        case 'tt': return await import('ckeditor5-premium-features/translations/tt.js');
+        case 'ug': return await import('ckeditor5-premium-features/translations/ug.js');
+        case 'uk': return await import('ckeditor5-premium-features/translations/uk.js');
+        case 'ur': return await import('ckeditor5-premium-features/translations/ur.js');
+        case 'uz': return await import('ckeditor5-premium-features/translations/uz.js');
+        case 'vi': return await import('ckeditor5-premium-features/translations/vi.js');
+        case 'zh': return await import('ckeditor5-premium-features/translations/zh.js');
+        case 'zh-cn': return await import('ckeditor5-premium-features/translations/zh-cn.js');
+        default:
+          console.warn(`Language ${lang} not found in premium translations`);
+          return await import('ckeditor5-premium-features/translations/en.js'); // fallback to English
+      }
+    }
+  }
+  /* v8 ignore start -- @preserve */
+  catch (error) {
+    console.error(`Failed to load translation for ${pkg}/${lang}:`, error);
+    return null;
+  }
+  /* v8 ignore stop -- @preserve */
+}

package/src/elements/editor/utils/normalize-custom-translations.test.ts

@@ -0,0 +1,152 @@
+import type { EditorCustomTranslationsDictionary } from '../typings';
+
+import { describe, expect, it } from 'vitest';
+
+import { normalizeCustomTranslations } from './normalize-custom-translations';
+
+describe('normalizeCustomTranslations', () => {
+  it('should normalize empty translations object', () => {
+    const input: EditorCustomTranslationsDictionary = {};
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({});
+  });
+
+  it('should normalize single language translation', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      en: {
+        Bold: 'Bold Text',
+        Italic: 'Italic Text',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      en: {
+        dictionary: {
+          Bold: 'Bold Text',
+          Italic: 'Italic Text',
+        },
+      },
+    });
+  });
+
+  it('should normalize multiple language translations', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      en: {
+        Bold: 'Bold Text',
+        Italic: 'Italic Text',
+      },
+      pl: {
+        Bold: 'Pogrubienie',
+        Italic: 'Kursywa',
+      },
+      de: {
+        Bold: 'Fett',
+        Italic: 'Kursiv',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      en: {
+        dictionary: {
+          Bold: 'Bold Text',
+          Italic: 'Italic Text',
+        },
+      },
+      pl: {
+        dictionary: {
+          Bold: 'Pogrubienie',
+          Italic: 'Kursywa',
+        },
+      },
+      de: {
+        dictionary: {
+          Bold: 'Fett',
+          Italic: 'Kursiv',
+        },
+      },
+    });
+  });
+
+  it('should handle empty dictionary for a language', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      en: {},
+      pl: {
+        Bold: 'Pogrubienie',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      en: {
+        dictionary: {},
+      },
+      pl: {
+        dictionary: {
+          Bold: 'Pogrubienie',
+        },
+      },
+    });
+  });
+
+  it('should preserve special characters and unicode in translations', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      zh: {
+        粗体: '加粗文本',
+        斜体: '斜体文本',
+      },
+      ar: {
+        Bold: 'عريض',
+        Italic: 'مائل',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      zh: {
+        dictionary: {
+          粗体: '加粗文本',
+          斜体: '斜体文本',
+        },
+      },
+      ar: {
+        dictionary: {
+          Bold: 'عريض',
+          Italic: 'مائل',
+        },
+      },
+    });
+  });
+
+  it('should handle language codes with regions', () => {
+    const input: EditorCustomTranslationsDictionary = {
+      'en-US': {
+        Color: 'Color',
+      },
+      'en-GB': {
+        Color: 'Colour',
+      },
+    };
+
+    const result = normalizeCustomTranslations(input);
+
+    expect(result).toEqual({
+      'en-US': {
+        dictionary: {
+          Color: 'Color',
+        },
+      },
+      'en-GB': {
+        dictionary: {
+          Color: 'Colour',
+        },
+      },
+    });
+  });
+});

package/src/elements/editor/utils/normalize-custom-translations.ts

@@ -0,0 +1,17 @@
+import type { EditorCustomTranslationsDictionary } from '../typings';
+import type { Translations } from 'ckeditor5';
+
+import { mapObjectValues } from '../../../shared';
+
+/**
+ * This function takes a custom translations object and maps it to the format expected by CKEditor5.
+ * Each translation dictionary is wrapped in an object with a `dictionary` key.
+ *
+ * @param translations - The custom translations to normalize.
+ * @returns A normalized translations object suitable for CKEditor5.
+ */
+export function normalizeCustomTranslations(translations: EditorCustomTranslationsDictionary): Translations {
+  return mapObjectValues(translations, dictionary => ({
+    dictionary,
+  }));
+}

package/src/elements/editor/utils/query-all-editor-ids.ts

@@ -0,0 +1,9 @@
+/**
+ * Queries all CKEditor 5 editor IDs present in the document.
+ */
+export function queryAllEditorIds(): string[] {
+  return Array
+    .from(document.querySelectorAll<HTMLElement>('cke5-editor'))
+    .map(element => element.getAttribute('data-cke-editor-id'))
+    .filter((id): id is string => id !== null);
+}

package/src/elements/editor/utils/query-editor-editables.ts

@@ -0,0 +1,101 @@
+import type { EditorId } from '../typings';
+
+import { filterObjectValues, mapObjectValues } from '../../../shared';
+
+/**
+ * Gets the initial root elements for the editor based on its type.
+ *
+ * @param editorId The editor's ID.
+ * @returns The root element(s) for the editor.
+ */
+export function queryEditablesElements(editorId: EditorId) {
+  const editables = queryAllEditorEditables(editorId);
+
+  return mapObjectValues(editables, ({ element }) => element);
+}
+
+/**
+ * Gets the initial data for the roots of the editor. If the editor is a single editing-like editor,
+ * it retrieves the initial value from the element's attribute. Otherwise, it returns an object mapping
+ * editable names to their initial values.
+ *
+ * @param editorId The editor's ID.
+ * @returns The initial values for the editor's roots.
+ */
+export function queryEditablesSnapshotContent(editorId: EditorId) {
+  const editables = queryAllEditorEditables(editorId);
+  const values = mapObjectValues(editables, ({ content }) => content);
+
+  return filterObjectValues(values, value => typeof value === 'string') as Record<string, string>;
+}
+
+/**
+ * Queries all editable elements within a specific editor instance. It picks
+ * initial values from actually rendered elements or from the editor container's.
+ *
+ * It may differ from the `initialData` used during editor creation, as it might
+ * not set all roots or set different values.
+ *
+ * @param editorId The ID of the editor to query.
+ * @returns An object mapping editable names to their corresponding elements and initial values.
+ */
+function queryAllEditorEditables(editorId: EditorId) {
+  const acc = (
+    Array
+      .from(document.querySelectorAll<HTMLElement>(`cke5-editable[data-cke-editor-id="${editorId}"]`))
+      .reduce<Record<string, EditableItem>>((acc, element) => {
+        const rootName = element.getAttribute('data-cke-root-name')!;
+        const content = element.getAttribute('data-cke-content');
+
+        acc[rootName] = {
+          element: element.querySelector<HTMLElement>('[data-cke-editable-content]')!,
+          content,
+        };
+
+        return acc;
+      }, Object.create({}))
+  );
+
+  const editor = document.querySelector<HTMLElement>(`cke5-editor[data-cke-editor-id="${editorId}"]`);
+
+  /* v8 ignore next -- @preserve */
+  if (!editor) {
+    return acc;
+  }
+
+  const currentMain = acc['main'];
+  const initialRootEditableValue = JSON.parse(editor.getAttribute('data-cke-content')!);
+  const contentElement = document.querySelector<HTMLElement>(`#${editorId}_editor `);
+
+  // If found `main` editable, but it has no content, try to fill it from the editor container.
+  if (currentMain && initialRootEditableValue?.['main']) {
+    return {
+      ...acc,
+      main: {
+        ...currentMain,
+        content: currentMain.content || initialRootEditableValue['main'],
+      },
+    };
+  }
+
+  // If no `main` editable found, try to create it from the editor container.
+  if (contentElement) {
+    return {
+      ...acc,
+      main: {
+        element: contentElement,
+        content: initialRootEditableValue?.['main'] || null,
+      },
+    };
+  }
+
+  return acc;
+}
+
+/**
+ * Type representing an editable item within an editor.
+ */
+export type EditableItem = {
+  element: HTMLElement;
+  content: string | null;
+};

package/src/elements/editor/utils/resolve-editor-config-elements-references.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { resolveEditorConfigElementReferences } from './resolve-editor-config-elements-references';
+
+describe('resolveEditorConfigElementReferences', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('resolves a single element reference', () => {
+    const div = document.createElement('div');
+    div.id = 'test-div';
+    document.body.appendChild(div);
+
+    const config = {
+      foo: { $element: '#test-div' },
+    };
+
+    const result = resolveEditorConfigElementReferences(config);
+    expect(result.foo).toBe(div);
+  });
+
+  it('returns null if element not found', () => {
+    const config = {
+      foo: { $element: '#not-exist' },
+    };
+    const result = resolveEditorConfigElementReferences(config);
+
+    expect(result.foo).toBeNull();
+  });
+
+  it('recursively resolves nested element references', () => {
+    const span = document.createElement('span');
+    span.className = 'my-span';
+    document.body.appendChild(span);
+
+    const config = {
+      nested: {
+        bar: { $element: '.my-span' },
+      },
+    };
+
+    const result = resolveEditorConfigElementReferences(config);
+    expect(result.nested.bar).toBe(span);
+  });
+
+  it('resolves element references in arrays', () => {
+    const el1 = document.createElement('div');
+    el1.id = 'el1';
+    document.body.appendChild(el1);
+
+    const el2 = document.createElement('div');
+    el2.id = 'el2';
+    document.body.appendChild(el2);
+
+    const config = [
+      { $element: '#el1' },
+      { $element: '#el2' },
+      { notElement: 123 },
+    ];
+
+    const result = resolveEditorConfigElementReferences(config);
+
+    expect(result[0]).toBe(el1);
+    expect(result[1]).toBe(el2);
+    expect(result[2]).toEqual({ notElement: 123 });
+  });
+
+  it('returns primitives as is', () => {
+    expect(resolveEditorConfigElementReferences(42)).toBe(42);
+    expect(resolveEditorConfigElementReferences('foo')).toBe('foo');
+    expect(resolveEditorConfigElementReferences(null)).toBe(null);
+    expect(resolveEditorConfigElementReferences(undefined)).toBe(undefined);
+  });
+
+  it('warns for invalid selector type', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const config = { foo: { $element: '.foo' } };
+
+    resolveEditorConfigElementReferences(config);
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Element not found for selector: .foo'));
+    warnSpy.mockRestore();
+  });
+
+  it('warns if element not found', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const config = { foo: { $element: '#not-found' } };
+
+    resolveEditorConfigElementReferences(config);
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Element not found'));
+    warnSpy.mockRestore();
+  });
+});

package/src/elements/editor/utils/resolve-editor-config-elements-references.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolves element references in configuration object.
+ * Looks for objects with { $element: "selector" } format and replaces them with actual DOM elements.
+ *
+ * @param obj - Configuration object to process
+ * @returns Processed configuration object with resolved element references
+ */
+export function resolveEditorConfigElementReferences<T>(obj: T): T {
+  if (!obj || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => resolveEditorConfigElementReferences(item)) as T;
+  }
+
+  const anyObj = obj as any;
+
+  if (anyObj.$element && typeof anyObj.$element === 'string') {
+    const element = document.querySelector(anyObj.$element);
+
+    if (!element) {
+      console.warn(`Element not found for selector: ${anyObj.$element}`);
+    }
+
+    return (element || null) as T;
+  }
+
+  const result = Object.create(null);
+
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = resolveEditorConfigElementReferences(value);
+  }
+
+  return result as T;
+}