ckeditor5 0.0.1 → 1.0.0

data/lib/ckeditor5/rails/assets/webcomponent.mjs

@@ -0,0 +1,603 @@
+/**
+ * Custom web component for integrating CKEditor 5 into web applications.
+ *
+ * @class
+ * @extends HTMLElement
+ *
+ * @property {import('ckeditor5').Editor|null} instance - The current CKEditor instance
+ * @property {Record<string, HTMLElement>} editables - Object containing editable elements
+ *
+ * @fires editor-ready - Fired when editor is initialized with the editor instance as detail
+ * @fires editor-error - Fired when initialization fails with the error as detail
+ *
+ * @example
+ * // Basic usage with Classic Editor
+ * <ckeditor-component type="ClassicEditor" config='{"toolbar": ["bold", "italic"]}'>
+ * </ckeditor-component>
+ *
+ * // Multiroot editor with multiple editables
+ * <ckeditor-component type="MultirootEditor">
+ *   <ckeditor-editable-component name="title">Title content</ckeditor-editable-component>
+ *   <ckeditor-editable-component name="content">Main content</ckeditor-editable-component>
+ * </ckeditor-component>
+ */
+class CKEditorComponent extends HTMLElement {
+  /**
+   * List of attributes that trigger updates when changed
+   * @static
+   * @returns {string[]} Array of attribute names to observe
+   */
+  static get observedAttributes() {
+    return ['config', 'plugins', 'translations', 'type'];
+  }
+
+  /** @type {Promise<import('ckeditor5').Editor>|null} Promise to initialize editor instance */
+  instancePromise = Promise.withResolvers();
+
+  /** @type {import('ckeditor5').Editor|null} Current editor instance */
+  instance = null;
+
+  /** @type {Record<string, HTMLElement>} Map of editable elements by name */
+  editables = {};
+
+  /**
+   * Lifecycle callback when element is connected to DOM
+   * Initializes the editor when DOM is ready
+   * @protected
+   */
+  connectedCallback() {
+    try {
+      execIfDOMReady(() => this.#reinitializeEditor());
+    } catch (error) {
+      console.error('Failed to initialize editor:', error);
+      this.dispatchEvent(new CustomEvent('editor-error', { detail: error }));
+    }
+  }
+
+  /**
+   * Handles attribute changes and reinitializes editor if needed
+   * @protected
+   * @param {string} name - Name of changed attribute
+   * @param {string|null} oldValue - Previous attribute value
+   * @param {string|null} newValue - New attribute value
+   */
+  async attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue !== null &&
+        oldValue !== newValue &&
+        CKEditorComponent.observedAttributes.includes(name) && this.isConnected) {
+      await this.#reinitializeEditor();
+    }
+  }
+
+  /**
+   * Lifecycle callback when element is removed from DOM
+   * Destroys the editor instance
+   * @protected
+   */
+  async disconnectedCallback() {
+    try {
+      await this.instance?.destroy();
+    } catch (error) {
+      console.error('Failed to destroy editor:', error);
+    }
+  }
+
+  /**
+   * Runs a callback after the editor is ready. It waits for editor
+   * initialization if needed.
+   *
+   * @param {(editor: import('ckeditor5').Editor) => void} callback - Callback to run
+   * @returns {Promise<void>}
+   */
+  runAfterEditorReady(callback) {
+    if (this.instance) {
+      return Promise.resolve(callback(this.instance));
+    }
+
+    return this.instancePromise.then(callback);
+  }
+
+  /**
+   * Determines appropriate editor element tag based on editor type
+   * @private
+   * @returns {string} HTML tag name to use
+   */
+  get #editorElementTag() {
+    switch (this.getAttribute('type')) {
+      case 'ClassicEditor':
+        return 'textarea';
+
+      default:
+        return 'div';
+    }
+  }
+
+  /**
+   * Initializes a new CKEditor instance
+   * @private
+   * @param {Record<string, HTMLElement>|CKEditorMultiRootEditablesTracker} editables - Editable elements
+   * @returns {Promise<import('ckeditor5').Editor>} Initialized editor instance
+   * @throws {Error} When initialization fails
+   */
+  async #initializeEditor(editables) {
+    const Editor = await this.#getEditorConstructor();
+    const [plugins, translations] = await Promise.all([
+      this.#getPlugins(),
+      this.#getTranslations()
+    ]);
+
+    const instance = await Editor.create(
+      editables instanceof CKEditorMultiRootEditablesTracker
+        ? editables.getAll()
+        : editables.main,
+      {
+        ...this.#getConfig(),
+        plugins,
+        translations
+      }
+    );
+
+    this.dispatchEvent(new CustomEvent('editor-ready', { detail: instance }));
+
+    return instance;
+  }
+
+  /**
+   * Re-initializes the editor by destroying existing instance and creating new one
+   *
+   * @private
+   * @returns {Promise<void>}
+   */
+  async #reinitializeEditor() {
+    if (this.instance) {
+      this.instancePromise = Promise.withResolvers();
+
+      await this.instance.destroy();
+      this.instance = null;
+    }
+
+    this.style.display = 'block';
+
+    if (!this.#isMultiroot()) {
+      this.innerHTML = `<${this.#editorElementTag}></${this.#editorElementTag}>`;
+    }
+
+    // Let's track changes in editables if it's a multiroot editor.
+    const editables = this.#queryEditables();
+
+    if(this.#isMultiroot()) {
+      this.editables = new CKEditorMultiRootEditablesTracker(this, editables);
+    } else {
+      this.editables = editables;
+    }
+
+    try {
+      this.instance = await this.#initializeEditor(this.editables);
+      this.instancePromise.resolve(this.instance);
+    } catch (err) {
+      this.instancePromise.reject(err);
+      throw err;
+    }
+  }
+
+  /**
+   * Checks if current editor is multiroot type
+   *
+   * @private
+   * @returns {boolean}
+   */
+  #isMultiroot() {
+    return this.getAttribute('type') === 'MultiRootEditor';
+  }
+
+  /**
+   * Parses editor configuration from config attribute
+   *
+   * @private
+   * @returns {EditorConfig}
+   */
+  #getConfig() {
+    return JSON.parse(this.getAttribute('config') || '{}');
+  }
+
+  /**
+   * Queries and validates editable elements
+   *
+   * @private
+   * @returns {Record<string, HTMLElement>}
+   * @throws {Error} When required editables are missing
+   */
+  #queryEditables() {
+    if (this.#isMultiroot()) {
+      const editables = [...this.querySelectorAll('ckeditor-editable-component')];
+
+      return editables.reduce((acc, element) => {
+        if (!element.name) {
+          throw new Error('Editable component missing required "name" attribute');
+        }
+        acc[element.name] = element;
+        return acc;
+      }, Object.create(null));
+    }
+
+    const mainEditable = this.querySelector(this.#editorElementTag);
+
+    if (!mainEditable) {
+      throw new Error(`No ${this.#editorElementTag} element found`);
+    }
+
+    return { main: mainEditable };
+  }
+
+  /**
+   * Loads translation modules
+   *
+   * @private
+   * @returns {Promise<Array<any>>}
+   */
+  async #getTranslations() {
+    const raw = this.getAttribute('translations');
+    return loadAsyncImports(raw ? JSON.parse(raw) : []);
+  }
+
+  /**
+   * Loads plugin modules
+   *
+   * @private
+   * @returns {Promise<Array<any>>}
+   */
+  async #getPlugins() {
+    const raw = this.getAttribute('plugins');
+    const items = raw ? JSON.parse(raw) : [];
+    const mappedItems = items.map(item =>
+      typeof item === 'string'
+        ? { import_name: 'ckeditor5', import_as: item }
+        : item
+    );
+
+    return loadAsyncImports(mappedItems);
+  }
+
+  /**
+   * Gets editor constructor based on type attribute
+   *
+   * @private
+   * @returns {Promise<typeof import('ckeditor5').Editor>}
+   * @throws {Error} When editor type is invalid
+   */
+  async #getEditorConstructor() {
+    const CKEditor = await import('ckeditor5');
+    const editorType = this.getAttribute('type');
+
+    if (!editorType || !Object.prototype.hasOwnProperty.call(CKEditor, editorType)) {
+      throw new Error(`Invalid editor type: ${editorType}`);
+    }
+
+    return CKEditor[editorType];
+  }
+}
+
+/**
+ * Tracks and manages editable roots for CKEditor MultiRoot editor.
+ * Provides a proxy-based API for dynamically managing editable elements with automatic
+ * attachment/detachment of editor roots.
+ *
+ * @class
+ * @property {CKEditorComponent} #editorElement - Reference to parent editor component
+ * @property {Record<string, HTMLElement>} #editables - Map of tracked editable elements
+ */
+class CKEditorMultiRootEditablesTracker {
+  #editorElement;
+  #editables;
+
+  /**
+   * Creates new tracker instance wrapped in a Proxy for dynamic property access
+   *
+   * @param {CKEditorComponent} editorElement - Parent editor component reference
+   * @param {Record<string, HTMLElement>} initialEditables - Initial editable elements
+   * @returns {Proxy<CKEditorMultiRootEditablesTracker>} Proxy wrapping the tracker
+   */
+  constructor(editorElement, initialEditables = {}) {
+    this.#editorElement = editorElement;
+    this.#editables = initialEditables;
+
+    return new Proxy(this, {
+      /**
+       * Handles property access, returns class methods or editable elements
+       *
+       * @param {CKEditorMultiRootEditablesTracker} target - The tracker instance
+       * @param {string|symbol} name - Property name being accessed
+       */
+      get(target, name) {
+        if (typeof target[name] === 'function') {
+          return target[name].bind(target);
+        }
+
+        return target.#editables[name];
+      },
+
+      /**
+       * Handles setting new editable elements, triggers root attachment
+       *
+       * @param {CKEditorMultiRootEditablesTracker} target - The tracker instance
+       * @param {string} name - Name of the editable root
+       * @param {HTMLElement} element - Element to attach as editable
+       */
+      set(target, name, element) {
+        if (target.#editables[name] !== element) {
+          target.attachRoot(name, element);
+          target.#editables[name] = element;
+        }
+        return true;
+      },
+
+      /**
+       * Handles removing editable elements, triggers root detachment
+       *
+       * @param {CKEditorMultiRootEditablesTracker} target - The tracker instance
+       * @param {string} name - Name of the root to remove
+       */
+      deleteProperty(target, name) {
+        target.detachRoot(name);
+        delete target.#editables[name];
+        return true;
+      }
+    });
+  }
+
+  /**
+   * Attaches a new editable root to the editor.
+   * Creates new editor root and binds UI elements.
+   *
+   * @param {string} name - Name of the editable root
+   * @param {HTMLElement} element - DOM element to use as editable
+   * @returns {Promise<void>} Resolves when root is attached
+   */
+  async attachRoot(name, element) {
+    await this.detachRoot(name);
+
+    return this.#editorElement.runAfterEditorReady((editor) => {
+      const { ui, editing, model } = editor;
+
+      editor.addRoot(name, {
+        isUndoable: false,
+        data: element.innerHTML
+      });
+
+      const root = model.document.getRoot(name);
+
+      if (ui.getEditableElement(name)) {
+        editor.detachEditable(root);
+      }
+
+      const editable = ui.view.createEditable(name, element);
+      ui.addEditable(editable);
+      editing.view.forceRender();
+    });
+  }
+
+  /**
+   * Detaches an editable root from the editor.
+   * Removes editor root and cleans up UI bindings.
+   *
+   * @param {string} name - Name of root to detach
+   * @returns {Promise<void>} Resolves when root is detached
+   */
+  async detachRoot(name) {
+    return this.#editorElement.runAfterEditorReady(editor => {
+      const root = editor.model.document.getRoot(name);
+
+      if (root) {
+        editor.detachEditable(root);
+        editor.detachRoot(name, true);
+      }
+    });
+  }
+
+  /**
+   * Gets all currently tracked editable elements
+   *
+   * @returns {Record<string, HTMLElement>} Map of all editable elements
+   */
+  getAll() {
+    return this.#editables;
+  }
+}
+
+/**
+ * Custom HTML element representing an editable region for CKEditor.
+ * Must be used as a child of ckeditor-component element.
+ *
+ * @customElement ckeditor-editable-component
+ * @extends HTMLElement
+ *
+ * @property {string} name - The name of the editable region, accessed via getAttribute
+ * @property {HTMLDivElement} editableElement - The div element containing editable content
+ *
+ * @fires connectedCallback - When the element is added to the DOM
+ * @fires attributeChangedCallback - When element attributes change
+ * @fires disconnectedCallback - When the element is removed from the DOM
+ *
+ * @throws {Error} Throws error if not used as child of ckeditor-component
+ *
+ * @example
+ * <ckeditor-component>
+ *   <ckeditor-editable-component name="main">
+ *     Content goes here
+ *   </ckeditor-editable-component>
+ * </ckeditor-component>
+ */
+class CKEditorEditableComponent extends HTMLElement {
+  /**
+   * List of attributes that trigger updates when changed
+   *
+   * @static
+   * @returns {string[]} Array of attribute names to observe
+   */
+  static get observedAttributes() {
+    return ['name'];
+  }
+
+  /**
+   * Gets the name of this editable region
+   *
+   * @returns {string} The name attribute value
+   */
+  get name() {
+    return this.getAttribute('name');
+  }
+
+  /**
+   * Gets the actual editable DOM element
+   * @returns {HTMLDivElement|null} The div element containing editable content
+   */
+  get editableElement() {
+    return this.querySelector('div');
+  }
+
+  /**
+   * Lifecycle callback when element is added to DOM
+   * Sets up the editable element and registers it with the parent editor
+   *
+   * @throws {Error} If not used as child of ckeditor-component
+   */
+  connectedCallback() {
+    const editorComponent = this.#queryEditorElement();
+
+    if (!editorComponent ) {
+      throw new Error('ckeditor-editable-component must be a child of ckeditor-component');
+    }
+
+    this.innerHTML = `<div>${this.innerHTML}</div>`;
+    this.style.display = 'block';
+
+    editorComponent.editables[this.name] = this;
+  }
+
+  /**
+   * Lifecycle callback for attribute changes
+   * Handles name changes and propagates other attributes to editable element
+   *
+   * @param {string} name - Name of changed attribute
+   * @param {string|null} oldValue - Previous value
+   * @param {string|null} newValue - New value
+   */
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue) {
+      return;
+    }
+
+    if (name === 'name') {
+      if (!oldValue) {
+        return;
+      }
+
+      const editorComponent = this.#queryEditorElement();
+
+      if (editorComponent) {
+        editorComponent.editables[newValue] = editorComponent.editables[oldValue];
+        delete editorComponent.editables[oldValue];
+      }
+    } else {
+      this.editableElement.setAttribute(name, newValue);
+    }
+  }
+
+  /**
+   * Lifecycle callback when element is removed
+   * Un-registers this editable from the parent editor
+   */
+  disconnectedCallback() {
+    const editorComponent = this.#queryEditorElement();
+
+    if (editorComponent) {
+      delete editorComponent.editables[this.name];
+    }
+  }
+
+  /**
+   * Finds the parent editor component
+   *
+   * @private
+   * @returns {CKEditorComponent|null} Parent editor component or null if not found
+   */
+  #queryEditorElement() {
+    return this.closest('ckeditor-component');
+  }
+}
+
+/**
+ * Custom HTML element that represents a CKEditor toolbar component.
+ * Manages the toolbar placement and integration with the main editor component.
+ *
+ * @extends HTMLElement
+ * @customElement ckeditor-toolbar
+ * @example
+ * <ckeditor-toolbar></ckeditor-toolbar>
+ */
+class CKEditorToolbarComponent extends HTMLElement {
+  /**
+   * Lifecycle callback when element is added to DOM
+   * Adds the toolbar to the editor UI
+   */
+  async connectedCallback() {
+    const editor = await this.#queryEditorElement().instancePromise.promise;
+
+    this.appendChild(editor.ui.view.toolbar.element);
+  }
+
+  /**
+   * Finds the parent editor component
+   *
+   * @private
+   * @returns {CKEditorComponent|null} Parent editor component or null if not found
+   */
+  #queryEditorElement() {
+    return this.closest('ckeditor-component');
+  }
+}
+
+/**
+ * Executes callback when DOM is ready
+ *
+ * @param {() => void} callback - Function to execute
+ */
+function execIfDOMReady(callback) {
+  switch (document.readyState) {
+    case 'loading':
+      document.addEventListener('DOMContentLoaded', callback, { once: true });
+      break;
+
+    case 'interactive':
+    case 'complete':
+      setTimeout(callback, 0);
+      break;
+
+    default:
+      console.warn('Unexpected document.readyState:', document.readyState);
+      setTimeout(callback, 0);
+  }
+}
+
+/**
+ * Dynamically imports modules based on configuration
+ *
+ * @param {Array<ImportConfig>} imports - Array of import configurations
+ * @returns {Promise<Array<any>>} Loaded modules
+ */
+function loadAsyncImports(imports = []) {
+  return Promise.all(
+    imports.map(async ({ import_name, import_as, window_name }) => {
+      if (window_name && Object.prototype.hasOwnProperty.call(window, window_name)) {
+        return window[window_name];
+      }
+
+      const module = await import(import_name);
+      return import_as ? module[import_as] : module.default;
+    })
+  );
+}
+
+customElements.define('ckeditor-component', CKEditorComponent);
+customElements.define('ckeditor-editable-component', CKEditorEditableComponent);
+customElements.define('ckeditor-toolbar-component', CKEditorToolbarComponent);

data/lib/ckeditor5/rails/cdn/ckbox_bundle.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CKEditor5::Rails
+  module Cdn
+    class CKBoxBundle < Assets::AssetsBundle
+      include Cdn::UrlGenerator
+
+      attr_reader :cdn, :version, :theme, :translations
+
+      def initialize(version, theme: :lark, cdn: Engine.base.default_cdn, translations: [])
+        raise ArgumentError, 'version must be semver' unless version.is_a?(Semver)
+        raise ArgumentError, 'theme must be a string' unless theme.is_a?(String)
+        raise ArgumentError, 'translations must be an array' unless translations.is_a?(Array)
+
+        super()
+
+        @cdn = cdn
+        @version = version
+        @theme = theme
+        @translations = translations
+      end
+
+      def scripts
+        @scripts ||= [
+          Assets::JSExportsMeta.new(
+            create_cdn_url('ckbox', 'ckbox.js', version),
+            *translations_js_exports_meta
+          )
+        ]
+      end
+
+      def stylesheets
+        @stylesheets ||= [
+          create_cdn_url('ckbox', "styles/themes/#{theme}.css", version)
+        ]
+      end
+
+      private
+
+      def translations_js_exports_meta
+        translations.map do |lang|
+          url = create_cdn_url('ckbox', "translations/#{lang}.js", version)
+
+          Assets::JSExportsMeta.new(url, window_name: 'CKBOX_TRANSLATIONS', translation: true)
+        end
+      end
+    end
+  end
+end

data/lib/ckeditor5/rails/cdn/ckeditor_bundle.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CKEditor5::Rails
+  module Cdn
+    class CKEditorBundle < Assets::AssetsBundle
+      include Cdn::UrlGenerator
+
+      attr_reader :version, :translations, :import_name
+
+      def initialize(version, import_name, cdn: Engine.base.default_cdn, translations: [])
+        raise ArgumentError, 'version must be semver' unless version.is_a?(Semver)
+        raise ArgumentError, 'import_name must be a string' unless import_name.is_a?(String)
+        raise ArgumentError, 'translations must be an array' unless translations.is_a?(Array)
+
+        super()
+
+        @cdn = cdn
+        @version = version
+        @import_name = import_name
+        @translations = translations
+      end
+
+      def scripts
+        @scripts ||= [
+          js_exports_meta,
+          *translations_js_exports_meta
+        ]
+      end
+
+      def stylesheets
+        @stylesheets ||= [
+          create_cdn_url(import_name, version, "#{import_name}.css")
+        ]
+      end
+
+      private
+
+      def js_exports_meta
+        Assets::JSExportsMeta.new(
+          create_cdn_url(import_name, version, "#{import_name}.js"),
+          import_name: import_name
+        )
+      end
+
+      def translations_js_exports_meta
+        translations.map do |lang|
+          url = create_cdn_url(import_name, version, "translations/#{lang}.js")
+
+          Assets::JSExportsMeta.new(
+            url,
+            import_name: "#{import_name}/translations/#{lang}.js",
+            translation: true
+          )
+        end
+      end
+    end
+  end
+end