ckeditor5 1.8.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18736efccfe3547f18ff9df5418fd5f93aafa426423c3ca8daca99de481c6c60
-  data.tar.gz: 6be07d38f24ba131e3a8444175b8416561706a97d74bd581d8568703ef3544f2
+  metadata.gz: e3e06c4a4882429855d9570658be64f10fffd97371d0ae60e9aee2ecec08df00
+  data.tar.gz: f48eabec0f1bcab9299be0f00094f2e1078a757582a705e57d504748943b5790
 SHA512:
-  metadata.gz: c40e50c2093c7f8c311b8565a54ddc4835aba887ced1e36b4802c6681769a8f2e4f39812443e688f6e31ff4932eef76282664be82d7cdbb4b667c9febe76374f
-  data.tar.gz: f9a999fb8a325323e497b225f3c8bed54cc24befc5bcd2cc90a93a25dece1d539e5e33a34fbe2a4f9570e462527492e061819563b7fad19e61d24fae8a39953e
+  metadata.gz: c989f7723dadc126c356b579f50160b09f3c359af8a791a919bcff0595c7387241f89f5a63a100c482878d0f067c094f45619628094d6a8c0659d797d75cb514
+  data.tar.gz: a411bbde271725fbaeddfc58023307837ffac5e26d4814ed13e922288846129973a2b297681076b480982485a91ed4b5c527056cf2b9b799cfbb321a5ed83762

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-)
+    - [Using Context in CKEditor 5 🔄](#using-context-in-ckeditor-5-)
+    - [Example usage of `ckeditor5_context` helper 📝](#example-usage-of-ckeditor5_context-helper-)
   - [How to access editor instance? 🤔](#how-to-access-editor-instance-)
   - [Common Tasks and Solutions 💡](#common-tasks-and-solutions-)
     - [Setting Editor Language 🌐](#setting-editor-language-)
@@ -112,6 +115,8 @@ Voilà! You have CKEditor 5 integrated with your Rails application. 🎉
   - [Events fired by the editor 🔊](#events-fired-by-the-editor-)
     - [`editor-ready` event](#editor-ready-event)
     - [`editor-error` event](#editor-error-event)
+    - [`editor-change` event](#editor-change-event)
+    - [Inline event handling](#inline-event-handling)
   - [Trademarks 📜](#trademarks-)
   - [License 📜](#license-)
 
@@ -184,9 +189,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 +571,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 +965,45 @@ 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.
+
+![CKEditor 5 Context](docs/context.png)
+
+### Using Context in CKEditor 5 🔄
+
+Format of the `ckeditor5_context` helper:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<%= ckeditor5_context config: { ... }, plugins: [ ... ] do %>
+  <%= ckeditor5_editor %>
+  <%= ckeditor5_editor %>
+<% end %>
+```
+
+The `ckeditor5_context` helper takes the `config` and `plugins` keyword arguments. The `config` keyword argument allows you to define the shared configuration of the editor instances, while the `plugins` keyword argument allows you to define the shared plugins. Format of these arguments is the same as in the `ckeditor5_editor` helper.
+
+### Example usage of `ckeditor5_context` helper 📝
+
+```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.
@@ -1222,6 +1261,8 @@ class HighlightCommand extends Command {
 
 ## Events fired by the editor 🔊
 
+CKEditor 5 provides a set of events that you can listen to in order to react to changes in the editor. You can listen to these events using the `addEventListener` method or by defining event handlers directly in the view.
+
 ### `editor-ready` event
 
 The event is fired when the initialization of the editor is completed. You can listen to it using the `editor-ready` event.
@@ -1242,6 +1283,40 @@ document.getElementById('editor').addEventListener('editor-error', () => {
 });
 ```
 
+### `editor-change` event
+
+The event is fired when the content of the editor changes. You can listen to it using the `editor-change` event.
+
+```js
+document.getElementById('editor').addEventListener('editor-change', () => {
+  console.log('Editor content has changed');
+});
+```
+
+### Inline event handling
+
+You can also define event handlers directly in the view using the `oneditorchange`, `oneditorerror`, and `oneditorready` attributes.
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<script type="text/javascript">
+  function onEditorChange(event) {
+    // event.detail.editor, event.detail.data
+  }
+
+  function onEditorError(event) {
+    // event.detail.editor
+  }
+
+  function onEditorReady(event) {
+    // event.detail.editor
+  }
+</script>
+
+<%= ckeditor5_editor style: 'width: 600px', id: 'editor', oneditorchange: 'onEditorChange', oneditorerror: 'onEditorError', oneditorready: 'onEditorReady' %>
+```
+
 ## Trademarks 📜
 
 CKEditor® is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com/) All rights reserved. For more information about the license of CKEditor® please visit [CKEditor's licensing page](https://ckeditor.com/legal/ckeditor-oss-license/).
@@ -1250,6 +1325,6 @@ This gem is not owned by CKSource and does not use the CKEditor® trademark for
 
 ## License 📜
 
-This project is licensed under the terms of the [GNU General Public License v2.0](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html). See the [LICENSE](LICENSE) file for details.
+This project is licensed under the terms of the [GNU General Public License v2.0 or later](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html). See the [LICENSE](LICENSE) file for details.
 
-This project uses CKEditor 5 which is licensed under the terms of [GNU General Public License Version 2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html). For more information about CKEditor 5 licensing, please see their [official documentation](https://ckeditor.com/legal/ckeditor-oss-license/).
+This project uses CKEditor 5 which is licensed under the terms of [GNU General Public License Version 2 or later](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html). For more information about CKEditor 5 licensing, please see their [official documentation](https://ckeditor.com/legal/ckeditor-oss-license/).

data/lib/ckeditor5/rails/assets/assets_bundle_html_serializer.rb

@@ -3,9 +3,9 @@
 require 'uri'
 require 'action_view'
 
-module CKEditor5::Rails::Assets
-  WEBCOMPONENT_SOURCE = File.read(File.join(__dir__, 'webcomponent.mjs')).html_safe
+require_relative 'webcomponent_bundle'
 
+module CKEditor5::Rails::Assets
   class AssetsBundleHtmlSerializer
     include ActionView::Helpers::TagHelper
 
@@ -38,7 +38,7 @@ module CKEditor5::Rails::Assets
     private
 
     def web_component_tag
-      @web_component_tag ||= tag.script(WEBCOMPONENT_SOURCE, type: 'module', nonce: true)
+      @web_component_tag ||= tag.script(WebComponentBundle.source, type: 'module', nonce: true)
     end
 
     def window_scripts_tags

data/lib/ckeditor5/rails/assets/webcomponent_bundle.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CKEditor5::Rails::Assets
+  module WebComponentBundle
+    WEBCOMPONENTS_PATH = File.join(__dir__, 'webcomponents')
+    WEBCOMPONENTS_MODULES = [
+      'utils.mjs',
+      'components/editable.mjs',
+      'components/ui-part.mjs',
+      'components/editor.mjs',
+      'components/context.mjs'
+    ].freeze
+
+    module_function
+
+    def source
+      @source ||= WEBCOMPONENTS_MODULES.map do |file|
+        File.read(File.join(WEBCOMPONENTS_PATH, file))
+      end.join("\n").html_safe
+    end
+  end
+end

data/lib/ckeditor5/rails/assets/webcomponents/components/context.mjs

@@ -0,0 +1,113 @@
+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);
+  }
+}
+
+customElements.define('ckeditor-context-component', CKEditorContextComponent);

data/lib/ckeditor5/rails/assets/webcomponents/components/editable.mjs

@@ -0,0 +1,113 @@
+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() {
+    // The default value is set mainly for decoupled editors where the name is not required.
+    return this.getAttribute('name') || 'editable';
+  }
+
+  /**
+   * 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() {
+    execIfDOMReady(() => {
+      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';
+
+      if (editorComponent.isDecoupled()) {
+        editorComponent.runAfterEditorReady(editor => {
+          this.appendChild(editor.ui.view[this.name].element);
+        });
+      } else {
+        if (!this.name) {
+          throw new Error('Editable component missing required "name" attribute');
+        }
+
+        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') || document.body.querySelector('ckeditor-component');
+  }
+}
+
+customElements.define('ckeditor-editable-component', CKEditorEditableComponent);