ckeditor5 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18736efccfe3547f18ff9df5418fd5f93aafa426423c3ca8daca99de481c6c60
-  data.tar.gz: 6be07d38f24ba131e3a8444175b8416561706a97d74bd581d8568703ef3544f2
+  metadata.gz: bb520612d3f2847e8d70c48a8ffb3d1ad4be25800dd5f141a6948caf30b07978
+  data.tar.gz: 5f9850fb6a39774ab796f67b5dc95fa0ec1e6a5fe6f04fb3481f6ff17c76e026
 SHA512:
-  metadata.gz: c40e50c2093c7f8c311b8565a54ddc4835aba887ced1e36b4802c6681769a8f2e4f39812443e688f6e31ff4932eef76282664be82d7cdbb4b667c9febe76374f
-  data.tar.gz: f9a999fb8a325323e497b225f3c8bed54cc24befc5bcd2cc90a93a25dece1d539e5e33a34fbe2a4f9570e462527492e061819563b7fad19e61d24fae8a39953e
+  metadata.gz: 7057a3e537f5626b4754b815c1f418ddac64301350aa3b0299d5051dcda474a5f397018389a0e7c773bc1d15687043498a2bcd44518581e4233f8ab4ae85dc52
+  data.tar.gz: 0526b5810f411971ce3adafa1bad252eabaffc566f3d637b6585c2a16a6d6c938078e8b88ed88b34e610477c87c66f5dfc74d092fab2f46f183327f2fca9d287

data/README.md

@@ -101,6 +101,9 @@ Voilà! You have CKEditor 5 integrated with your Rails application. 🎉
     - [Inline editor 📝](#inline-editor-)
     - [Balloon editor 🎈](#balloon-editor-)
     - [Decoupled editor 🌐](#decoupled-editor-)
+  - [Using Context 📦](#using-context-)
+    - [Benefits of Using Context in Collaboration 🤝](#benefits-of-using-context-in-collaboration-)
+    - [Using Context in CKEditor 5 🔄](#using-context-in-ckeditor-5-)
   - [How to access editor instance? 🤔](#how-to-access-editor-instance-)
   - [Common Tasks and Solutions 💡](#common-tasks-and-solutions-)
     - [Setting Editor Language 🌐](#setting-editor-language-)
@@ -184,9 +187,6 @@ Configuration of the editor can be complex, and it's recommended to use the [CKE
 
 ### Available Configuration Methods ⚙️
 
-<details>
-  <summary>Expand to show available methods 📖</summary>
-
 #### `cdn(cdn = nil, &block)` method
 
 Defines the CDN to be used for CKEditor 5 assets. The example below shows how to set the CDN to `:jsdelivr`:
@@ -569,8 +569,6 @@ CKEditor5::Rails.configure do
 end
 ```
 
-</details>
-
 ## Including CKEditor 5 assets 📦
 
 To include CKEditor 5 assets in your application, you can use the `ckeditor5_assets` helper method. This method takes the version of CKEditor 5 as an argument and includes the necessary resources of the editor. Depending on the specified configuration, it includes the JS and CSS assets from the official CKEditor 5 CDN or one of the popular CDNs.
@@ -965,6 +963,46 @@ If you want to use a decoupled editor, you can pass the `type` keyword argument
 <% end %>
 ```
 
+## Using Context 📦
+
+Context CKEditor 5 is a feature that allows multiple editor instances to share a common configuration and state. This is particularly useful in collaborative environments where multiple users are editing different parts of the same document simultaneously. By using a shared context, all editor instances can synchronize their configurations, plugins, and other settings, ensuring a consistent editing experience across all users.
+
+### Benefits of Using Context in Collaboration 🤝
+
+1. **Consistency**: Ensures that all editor instances have the same configuration, plugins, and settings, providing a uniform editing experience.
+2. **Synchronization**: Allows real-time synchronization of content and changes across multiple editor instances, making collaborative editing seamless.
+3. **Resource Sharing**: Reduces the overhead of loading and initializing multiple editor instances by sharing common resources and configurations.
+4. **Simplified Management**: Makes it easier to manage and update the configuration and state of multiple editor instances from a single point.
+
+### Using Context in CKEditor 5 🔄
+
+Format of the `ckeditor5_context` helper:
+
+```erb
+<%= ckeditor5_context config: { ...you context config... }, plugins: [ ...your context plugins... ] do %>
+  <%= ckeditor5_editor %>
+  <%= ckeditor5_editor %>
+<% end %>
+```
+
+Example usage:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets preset: :ultrabasic %>
+<% end %>
+
+<%= ckeditor5_context do %>
+  <%= ckeditor5_editor initial_data: 'Hello World' %>
+
+  <br>
+
+  <%= ckeditor5_editor initial_data: 'Hello World 2' %>
+<% end %>
+```
+
 ## How to access editor instance? 🤔
 
 You can access the editor instance using plain HTML and JavaScript, as CKEditor 5 is a web component with defined `instance`, `instancePromise` and `editables` properties.

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

@@ -57,16 +57,30 @@ class CKEditorComponent extends HTMLElement {
   /** @type {String} Initial HTML passed to component */
   #initialHTML = '';
 
+  /** @type {CKEditorContextComponent|null} */
+  #context = null;
+
+  /** @type {String} ID of editor within context */
+  #contextEditorId = null;
+
   /**
    * Lifecycle callback when element is connected to DOM
    * Initializes the editor when DOM is ready
    * @protected
    */
   connectedCallback() {
+    this.#context = this.closest('ckeditor-context-component');
     this.#initialHTML = this.innerHTML;
 
     try {
-      execIfDOMReady(() => this.#reinitializeEditor());
+      execIfDOMReady(async () => {
+        if (this.#context) {
+          await this.#context.instancePromise.promise;
+          this.#context.registerEditor(this);
+        }
+
+        await this.reinitializeEditor();
+      });
     } catch (error) {
       console.error('Failed to initialize editor:', error);
       this.dispatchEvent(new CustomEvent('editor-error', { detail: error }));
@@ -84,7 +98,7 @@ class CKEditorComponent extends HTMLElement {
     if (oldValue !== null &&
         oldValue !== newValue &&
         CKEditorComponent.observedAttributes.includes(name) && this.isConnected) {
-      await this.#reinitializeEditor();
+      await this.reinitializeEditor();
     }
   }
 
@@ -94,9 +108,12 @@ class CKEditorComponent extends HTMLElement {
    * @protected
    */
   async disconnectedCallback() {
+    if (this.#context) {
+      this.#context.unregisterEditor(this);
+    }
+
     try {
-      await this.instance?.destroy();
-      await this.watchdog?.destroy();
+      await this.#destroy();
     } catch (error) {
       console.error('Failed to destroy editor:', error);
     }
@@ -119,6 +136,7 @@ class CKEditorComponent extends HTMLElement {
 
   /**
    * Determines appropriate editor element tag based on editor type
+   *
    * @private
    * @returns {string} HTML tag name to use
    */
@@ -133,57 +151,25 @@ class CKEditorComponent extends HTMLElement {
   }
 
   /**
-   * Resolves element references in configuration object.
-   * Looks for objects with { $element: "selector" } format and replaces them with actual elements.
+   * Gets the CKEditor context instance if available.
    *
    * @private
-   * @param {Object} obj - Configuration object to process
-   * @returns {Object} Processed configuration object with resolved element references
+   * @returns {import('ckeditor5').ContextWatchdog|null}
    */
-  #resolveElementReferences(obj) {
-    if (!obj || typeof obj !== 'object') {
-      return obj;
-    }
-
-    if (Array.isArray(obj)) {
-      return obj.map(item => this.#resolveElementReferences(item));
-    }
-
-    const result = Object.create(null);
-
-    for (const key of Object.getOwnPropertyNames(obj)) {
-      if (!isSafeKey(key)) {
-        console.warn(`Suspicious key "${key}" detected in config, skipping`);
-        continue;
-      }
-
-      const value = obj[key];
-
-      if (value && typeof value === 'object') {
-        if (value.$element) {
-          const selector = value.$element;
-
-          if (typeof selector !== 'string') {
-            console.warn(`Invalid selector type for "${key}", expected string`);
-            continue;
-          }
-
-          const element = document.querySelector(selector);
-
-          if (!element) {
-            console.warn(`Element not found for selector: ${selector}`);
-          }
+  get #contextWatchdog() {
+    return this.#context?.instance;
+  }
 
-          result[key] = element || null;
-        } else {
-          result[key] = this.#resolveElementReferences(value);
-        }
-      } else {
-        result[key] = value;
-      }
+  /**
+   * Destroys the editor instance and watchdog if available
+   */
+  async #destroy() {
+    if (this.#contextEditorId) {
+      await this.#contextWatchdog.remove(this.#contextEditorId);
     }
 
-    return result;
+    await this.instance?.destroy();
+    await this.watchdog?.destroy();
   }
 
   /**
@@ -195,7 +181,7 @@ class CKEditorComponent extends HTMLElement {
   #getConfig() {
     const config = JSON.parse(this.getAttribute('config') || '{}');
 
-    return this.#resolveElementReferences(config);
+    return resolveElementReferences(config);
   }
 
   /**
@@ -232,13 +218,27 @@ class CKEditorComponent extends HTMLElement {
       plugins,
     };
 
-    console.warn('Initializing CKEditor with:', { config, watchdog: this.hasWatchdog() });
+    console.warn('Initializing CKEditor with:', { config, watchdog: this.hasWatchdog(), context: this.#context });
 
     // Initialize watchdog if needed
     let watchdog = null;
     let instance = null;
-
-    if (this.hasWatchdog()) {
+    let contextId = null;
+
+    if (this.#context) {
+      contextId = uid();
+
+      await this.#contextWatchdog.add( {
+        creator: (_element, _config) => Editor.create(_element, _config),
+        id: contextId,
+        sourceElementOrData: content,
+        type: 'editor',
+        config,
+      } );
+
+      instance = this.#contextWatchdog.getItem(contextId);
+    } else if (this.hasWatchdog()) {
+      // Let's create use with plain watchdog.
       const { EditorWatchdog } = await import('ckeditor5');
       const watchdog = new EditorWatchdog(Editor);
 
@@ -246,12 +246,14 @@ class CKEditorComponent extends HTMLElement {
 
       instance = watchdog.editor;
     } else {
+      // Let's create the editor without watchdog.
       instance = await Editor.create(content, config);
     }
 
     this.dispatchEvent(new CustomEvent('editor-ready', { detail: instance }));
 
     return {
+      contextId,
       instance,
       watchdog,
     };
@@ -263,11 +265,12 @@ class CKEditorComponent extends HTMLElement {
    * @private
    * @returns {Promise<void>}
    */
-  async #reinitializeEditor() {
+  async reinitializeEditor() {
     if (this.instance) {
       this.instancePromise = Promise.withResolvers();
 
-      await this.instance.destroy();
+      await this.#destroy();
+
       this.instance = null;
     }
 
@@ -288,10 +291,11 @@ class CKEditorComponent extends HTMLElement {
     }
 
     try {
-      const { watchdog, instance } = await this.#initializeEditor(this.editables || this.#getConfig().initialData || '');
+      const { watchdog, instance, contextId } = await this.#initializeEditor(this.editables || this.#getConfig().initialData || '');
 
       this.watchdog = watchdog;
       this.instance = instance;
+      this.#contextEditorId = contextId;
 
       this.#setupContentSync();
       this.#setupEditableHeight();
@@ -511,6 +515,129 @@ class CKEditorComponent extends HTMLElement {
   }
 }
 
+/**
+ * Custom element that provides shared CKEditor context for multiple editors.
+ *
+ * @extends HTMLElement
+ * @example
+ *
+ * <ckeditor-context-component plugins='[ ... ]'>
+ *  <ckeditor-component type="ClassicEditor" config='{"toolbar": ["bold", "italic"]}'>
+ *  <ckeditor-component type="ClassicEditor" config='{"toolbar": ["bold", "italic"]}'>
+ * </ckeditor-component>
+ */
+class CKEditorContextComponent extends HTMLElement {
+  static get observedAttributes() {
+    return ['plugins', 'config'];
+  }
+
+  /** @type {import('ckeditor5').Context|null} */
+  instance = null;
+
+  /** @type {Promise<import('ckeditor5').Context>} */
+  instancePromise = Promise.withResolvers();
+
+  /** @type {Set<CKEditorComponent>} */
+  #connectedEditors = new Set();
+
+  async connectedCallback() {
+    try {
+      execIfDOMReady(() => this.#initializeContext());
+    } catch (error) {
+      console.error('Failed to initialize context:', error);
+      this.dispatchEvent(new CustomEvent('context-error', { detail: error }));
+    }
+  }
+
+  async attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue !== null && oldValue !== newValue) {
+      await this.#initializeContext();
+    }
+  }
+
+  async disconnectedCallback() {
+    if (this.instance) {
+      await this.instance.destroy();
+      this.instance = null;
+    }
+  }
+
+  /**
+   * Register editor component with this context
+   *
+   * @param {CKEditorComponent} editor
+   */
+  registerEditor(editor) {
+    this.#connectedEditors.add(editor);
+  }
+
+  /**
+   * Unregister editor component from this context
+   *
+   * @param {CKEditorComponent} editor
+   */
+  unregisterEditor(editor) {
+    this.#connectedEditors.delete(editor);
+  }
+
+  /**
+   * Initialize CKEditor context with shared configuration
+   *
+   * @private
+   */
+  async #initializeContext() {
+    if (this.instance) {
+      this.instancePromise = Promise.withResolvers();
+
+      await this.instance.destroy();
+
+      this.instance = null;
+    }
+
+    const { Context, ContextWatchdog } = await import('ckeditor5');
+    const plugins = await this.#getPlugins();
+    const config = this.#getConfig();
+
+    this.instance = new ContextWatchdog(Context, {
+      crashNumberLimit: 10
+    });
+
+    await this.instance.create({
+      ...config,
+      plugins
+    });
+
+    this.instance.on('itemError', (...args) => {
+      console.error('Context item error:', ...args);
+    });
+
+    this.instancePromise.resolve(this.instance);
+    this.dispatchEvent(new CustomEvent('context-ready', { detail: this.instance }));
+
+    // Reinitialize connected editors.
+    await Promise.all(
+      [...this.#connectedEditors].map(editor => editor.reinitializeEditor())
+    );
+  }
+
+  async #getPlugins() {
+    const raw = this.getAttribute('plugins');
+
+    return loadAsyncImports(raw ? JSON.parse(raw) : []);
+  }
+
+  /**
+   * Gets context configuration with resolved element references.
+   *
+   * @private
+   */
+  #getConfig() {
+    const config = JSON.parse(this.getAttribute('config') || '{}');
+
+    return resolveElementReferences(config);
+  }
+}
+
 /**
  * Tracks and manages editable roots for CKEditor MultiRoot editor.
  * Provides a proxy-based API for dynamically managing editable elements with automatic
@@ -894,6 +1021,69 @@ function isSafeKey(key) {
           key !== 'prototype';
 }
 
+/**
+ * Resolves element references in configuration object.
+ * Looks for objects with { $element: "selector" } format and replaces them with actual elements.
+ *
+ * @param {Object} obj - Configuration object to process
+ * @returns {Object} Processed configuration object with resolved element references
+ */
+function resolveElementReferences(obj) {
+  if (!obj || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => resolveElementReferences(item));
+  }
+
+  const result = Object.create(null);
+
+  for (const key of Object.getOwnPropertyNames(obj)) {
+    if (!isSafeKey(key)) {
+      console.warn(`Suspicious key "${key}" detected in config, skipping`);
+      continue;
+    }
+
+    const value = obj[key];
+
+    if (value && typeof value === 'object') {
+      if (value.$element) {
+        const selector = value.$element;
+
+        if (typeof selector !== 'string') {
+          console.warn(`Invalid selector type for "${key}", expected string`);
+          continue;
+        }
+
+        const element = document.querySelector(selector);
+
+        if (!element) {
+          console.warn(`Element not found for selector: ${selector}`);
+        }
+
+        result[key] = element || null;
+      } else {
+        result[key] = resolveElementReferences(value);
+      }
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Custom element that provides shared CKEditor context for multiple editors.
+ *
+ * @returns {String} unique id
+ */
+function uid() {
+  return Math.random().toString(36).substring(2);
+}
+
 customElements.define('ckeditor-component', CKEditorComponent);
 customElements.define('ckeditor-editable-component', CKEditorEditableComponent);
 customElements.define('ckeditor-ui-part-component', CKEditorUIPartComponent);
+customElements.define('ckeditor-context-component', CKEditorContextComponent);

data/lib/ckeditor5/rails/context/helpers.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'props'
+
+module CKEditor5::Rails::Context
+  module Helpers
+    def ckeditor5_context(**config, &block)
+      context_props = Props.new(config)
+
+      tag.send(:'ckeditor-context-component', **context_props.to_attributes, &block)
+    end
+  end
+end

data/lib/ckeditor5/rails/context/props.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CKEditor5::Rails
+  module Context
+    class Props
+      def initialize(config)
+        @config = config
+      end
+
+      def to_attributes
+        {
+          plugins: serialize_plugins,
+          config: serialize_config
+        }
+      end
+
+      private
+
+      attr_reader :config
+
+      def serialize_plugins
+        (config[:plugins] || []).map { |plugin| Editor::PropsPlugin.normalize(plugin).to_h }.to_json
+      end
+
+      def serialize_config
+        config.except(:plugins).to_json
+      end
+    end
+  end
+end

data/lib/ckeditor5/rails/editor/helpers.rb

@@ -29,16 +29,13 @@ module CKEditor5::Rails
       type ||= preset.type
 
       validated_height = validate_editable_height(type, editable_height) || preset.editable_height
-      editor_props = Editor::Props.new(
-        controller_context, type, config,
-        watchdog: watchdog
-      )
-
-      render_editor_component(
-        editor_props,
-        html_attributes.merge(validated_height ? { 'editable-height' => validated_height } : {}),
-        &block
-      )
+      editor_props = Editor::Props.new(controller_context, type, config, watchdog: watchdog)
+
+      tag_attributes = html_attributes
+                       .merge(editor_props.to_attributes)
+                       .merge(validated_height ? { 'editable-height' => validated_height } : {})
+
+      tag.send(:'ckeditor-component', **tag_attributes, &block)
     end
 
     def ckeditor5_editable(name = nil, **kwargs, &block)
@@ -91,10 +88,6 @@ module CKEditor5::Rails
         raise PresetNotFoundError, "Preset #{preset} is not defined."
     end
 
-    def render_editor_component(props, html_attributes, &block)
-      tag.send(:'ckeditor-component', **props.to_attributes, **html_attributes, &block)
-    end
-
     def validate_editable_height(type, height)
       return nil if height.nil?
 

data/lib/ckeditor5/rails/helpers.rb

@@ -3,11 +3,13 @@
 require_relative 'cdn/helpers'
 require_relative 'cloud/helpers'
 require_relative 'editor/helpers'
+require_relative 'context/helpers'
 
 module CKEditor5::Rails
   module Helpers
     include Cdn::Helpers
     include Cloud::Helpers
     include Editor::Helpers
+    include Context::Helpers
   end
 end

data/lib/ckeditor5/rails/version.rb

@@ -2,6 +2,6 @@
 
 module CKEditor5
   module Rails
-    VERSION = '1.8.0'
+    VERSION = '1.9.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ckeditor5
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Mateusz Bagiński
@@ -51,6 +51,8 @@ files:
 - lib/ckeditor5/rails/cdn/helpers.rb
 - lib/ckeditor5/rails/cdn/url_generator.rb
 - lib/ckeditor5/rails/cloud/helpers.rb
+- lib/ckeditor5/rails/context/helpers.rb
+- lib/ckeditor5/rails/context/props.rb
 - lib/ckeditor5/rails/editor/config_helpers.rb
 - lib/ckeditor5/rails/editor/helpers.rb
 - lib/ckeditor5/rails/editor/props.rb