ckeditor5 1.9.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb520612d3f2847e8d70c48a8ffb3d1ad4be25800dd5f141a6948caf30b07978
-  data.tar.gz: 5f9850fb6a39774ab796f67b5dc95fa0ec1e6a5fe6f04fb3481f6ff17c76e026
+  metadata.gz: cbd754782a22b999b5843eedf90b499ba82f44dfac2ceb51f3c46898800482e2
+  data.tar.gz: c7945b1c9efeb3579a70ac0aaa832bac46147c512b9de98dff3dbf5a3187afad
 SHA512:
-  metadata.gz: 7057a3e537f5626b4754b815c1f418ddac64301350aa3b0299d5051dcda474a5f397018389a0e7c773bc1d15687043498a2bcd44518581e4233f8ab4ae85dc52
-  data.tar.gz: 0526b5810f411971ce3adafa1bad252eabaffc566f3d637b6585c2a16a6d6c938078e8b88ed88b34e610477c87c66f5dfc74d092fab2f46f183327f2fca9d287
+  metadata.gz: e1263373ca9e36adf9d63b8ff23d88933231cdacb8378cedc9f17819ae59924064e04bec14731e3907808af138ecd2afc4cd80cb2db9b943f221d1b8d9ccdf43
+  data.tar.gz: a8c822abfc9f0f191785d2cea17d5eb7d5d9696c2d3337c9fbdd4ff302f9ef1bf2b46fca90cc9b221f00c1a37c0d124c92fb74dde125dc5e8cd2aaf9b683f8bc

data/Gemfile

@@ -6,11 +6,21 @@ gem 'bundler', '~> 2.5', '>= 2.5.21'
 
 group :development do
   gem 'brakeman', '~> 6.1', '>= 6.1.1', require: false
+  gem 'guard', '~> 2.19', '>= 2.19.0'
+  gem 'guard-process', '~> 1.2'
+  gem 'pry', '~> 0.15', '>= 0.15.0'
+  gem 'rails', '~> 7.0', '>= 7.0.0'
   gem 'rake', '~> 13.2', '>= 13.2.1'
   gem 'rspec', '~> 3.13'
+  gem 'rspec-expectations', '~> 3.13'
+  gem 'rspec-rails', '~> 7.0'
   gem 'rubocop', '~> 1.66', require: false
   gem 'rubocop-rails', '~> 2.26', '>= 2.26.2', require: false
   gem 'rubocop-rails-omakase', '~> 1.0.0', require: false
+  gem 'simple_form', '~> 5.3', '>= 5.3.0'
+  gem 'slim', '~> 5.2', '>= 5.2.0'
+  gem 'sprockets-rails', '~> 3.2', '>= 3.2.2'
+  gem 'sqlite3', '>= 1.4'
 end
 
 group :test, :development do

data/README.md

@@ -102,8 +102,8 @@ Voilà! You have CKEditor 5 integrated with your Rails application. 🎉
     - [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-)
+    - [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-)
@@ -115,6 +115,9 @@ 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)
+  - [Gem Development 🛠](#gem-development-)
   - [Trademarks 📜](#trademarks-)
   - [License 📜](#license-)
 
@@ -967,25 +970,24 @@ If you want to use a decoupled editor, you can pass the `type` keyword argument
 
 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.
+![CKEditor 5 Context](docs/context.png)
 
 ### Using Context in CKEditor 5 🔄
 
 Format of the `ckeditor5_context` helper:
 
 ```erb
-<%= ckeditor5_context config: { ...you context config... }, plugins: [ ...your context plugins... ] do %>
+<!-- app/views/demos/index.html.erb -->
+
+<%= ckeditor5_context config: { ... }, plugins: [ ... ] do %>
   <%= ckeditor5_editor %>
   <%= ckeditor5_editor %>
 <% end %>
 ```
 
-Example usage:
+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 -->
@@ -1260,6 +1262,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.
@@ -1280,6 +1284,54 @@ 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 id: 'editor',
+    oneditorchange: 'onEditorChange',
+    oneditorerror: 'onEditorError',
+    oneditorready: 'onEditorReady'
+%>
+```
+
+## Gem Development 🛠
+
+If you want to contribute to the gem, you can clone the repository and run the following commands:
+
+```sh
+gem install bundler -v 2.5.22
+bundle install
+bundle exec guard
+```
+
 ## 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/).
@@ -1288,6 +1340,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,12 +38,12 @@ 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
       @window_scripts_tags ||= safe_join(bundle.scripts.filter_map do |script|
-        tag.script(src: script.url, nonce: true, async: true) if script.window?
+        tag.script(src: script.url, nonce: true, async: true, crossorigin: 'anonymous') if script.window?
       end)
     end
 

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);