ckeditor5 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4325c958e2805d971859c841f0b2694490e35a7e4600e2b8bb60f35672493146
-  data.tar.gz: 23aa528bcbfbec102647898aee0fb4c064e7d16bd051fc4bf45ae94b9ed16fb6
+  metadata.gz: bb520612d3f2847e8d70c48a8ffb3d1ad4be25800dd5f141a6948caf30b07978
+  data.tar.gz: 5f9850fb6a39774ab796f67b5dc95fa0ec1e6a5fe6f04fb3481f6ff17c76e026
 SHA512:
-  metadata.gz: 7e12e3e13824889463c2500e5d26874c1dd7c1dac6c5dbf1d41b37e5bd66e25b642b92fdbcb943b4f99219302e9184bacc5c8b16902559511c69db2392e2d569
-  data.tar.gz: '090b221f5bebaedac65be2db6a230409537b891bce481258106a575a58555b59fa2a0f55b125ea114115554ecba1b2d0f80845e3b1bea14f6f743af627972810'
+  metadata.gz: 7057a3e537f5626b4754b815c1f418ddac64301350aa3b0299d5051dcda474a5f397018389a0e7c773bc1d15687043498a2bcd44518581e4233f8ab4ae85dc52
+  data.tar.gz: 0526b5810f411971ce3adafa1bad252eabaffc566f3d637b6585c2a16a6d6c938078e8b88ed88b34e610477c87c66f5dfc74d092fab2f46f183327f2fca9d287

data/README.md

@@ -84,6 +84,7 @@ Voilà! You have CKEditor 5 integrated with your Rails application. 🎉
       - [`plugin(name, premium:, import_name:)` method](#pluginname-premium-import_name-method)
       - [`plugins(*names, **kwargs)` method](#pluginsnames-kwargs-method)
       - [`inline_plugin(name, code)` method](#inline_pluginname-code-method)
+      - [`ckeditor5_element_ref(selector)` method](#ckeditor5_element_refselector-method)
   - [Including CKEditor 5 assets 📦](#including-ckeditor-5-assets-)
     - [Format 📝](#format-)
       - [Using default preset](#using-default-preset)
@@ -100,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-)
@@ -183,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`:
@@ -445,7 +446,9 @@ end
 
 #### `configure(name, value)` method
 
-Allows you to set custom configuration options. You can pass the name of the option and its value as arguments. The example below show how to set the default protocol for the link plugin to `https://`:
+Allows you to set custom configuration options. You can pass the name of the option and its value as arguments. The [`ckeditor5_element_ref(selector)` helper](#ckeditor5_element_refselector-method) allows you to reference DOM elements that will be used by the editor's features. It's particularly useful for features that need to check element presence or operate on specific DOM elements.
+
+For example, you can use it to configure font family dropdown to show only fonts available in specific elements:
 
 ```rb
 # config/initializers/ckeditor5.rb
@@ -453,8 +456,19 @@ Allows you to set custom configuration options. You can pass the name of the opt
 CKEditor5::Rails.configure do
   # ... other configuration
 
-  configure :link, {
-    defaultProtocol: 'https://'
+  configure :fontFamily, {
+    supportAllValues: true,
+    options: [
+      'default',
+      'Arial, Helvetica, sans-serif',
+      'Courier New, Courier, monospace',
+      'Georgia, serif',
+      'Lucida Sans Unicode, Lucida Grande, sans-serif',
+      'Tahoma, Geneva, sans-serif',
+      'Times New Roman, Times, serif',
+      'Trebuchet MS, Helvetica, sans-serif',
+      'Verdana, Geneva, sans-serif'
+    ]
   }
 end
 ```
@@ -538,7 +552,22 @@ CKEditor5::Rails.configure do
   JS
 end
 ```
-</details>
+
+#### `ckeditor5_element_ref(selector)` method
+
+Defines a reference to a CKEditor 5 element. In other words, it allows you to reference DOM elements that will be used by the editor's features. It's particularly useful for features that need to check element presence or operate on specific DOM elements. The primary example is the `presence list` feature that requires a reference to the element that will be used to display the list.
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails.configure do
+  # ... other configuration
+
+  configure :yourPlugin, {
+      element: ckeditor5_element_ref("body")
+  }
+end
+```
 
 ## Including CKEditor 5 assets 📦
 
@@ -934,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
    */
@@ -132,6 +150,40 @@ class CKEditorComponent extends HTMLElement {
     }
   }
 
+  /**
+   * Gets the CKEditor context instance if available.
+   *
+   * @private
+   * @returns {import('ckeditor5').ContextWatchdog|null}
+   */
+  get #contextWatchdog() {
+    return this.#context?.instance;
+  }
+
+  /**
+   * Destroys the editor instance and watchdog if available
+   */
+  async #destroy() {
+    if (this.#contextEditorId) {
+      await this.#contextWatchdog.remove(this.#contextEditorId);
+    }
+
+    await this.instance?.destroy();
+    await this.watchdog?.destroy();
+  }
+
+  /**
+   * Gets editor configuration with resolved element references
+   *
+   * @private
+   * @returns {EditorConfig}
+   */
+  #getConfig() {
+    const config = JSON.parse(this.getAttribute('config') || '{}');
+
+    return resolveElementReferences(config);
+  }
+
   /**
    * Creates a new CKEditor instance
    *
@@ -166,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);
 
@@ -180,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,
     };
@@ -197,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;
     }
 
@@ -222,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();
@@ -273,16 +343,6 @@ class CKEditorComponent extends HTMLElement {
     return this.getAttribute('watchdog') === 'true';
   }
 
-  /**
-   * Parses editor configuration from config attribute
-   *
-   * @private
-   * @returns {EditorConfig}
-   */
-  #getConfig() {
-    return JSON.parse(this.getAttribute('config') || '{}');
-  }
-
   /**
    * Queries and validates editable elements
    *
@@ -455,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
@@ -824,6 +1007,83 @@ function loadAsyncImports(imports = []) {
   }));
 }
 
+
+/**
+ * Checks if a key is safe to use in configuration objects to prevent prototype pollution.
+ *
+ * @param {string} key - Key name to check
+ * @returns {boolean} True if key is safe to use.
+ */
+function isSafeKey(key) {
+  return typeof key === 'string' &&
+          key !== '__proto__' &&
+          key !== 'constructor' &&
+          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/config_helpers.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CKEditor5::Rails
+  module Editor::ConfigHelpers
+    def ckeditor5_element_ref(selector)
+      { '$element': selector }
+    end
+  end
+end

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

@@ -3,9 +3,12 @@
 require_relative 'props_plugin'
 require_relative 'props_inline_plugin'
 require_relative 'props'
+require_relative 'config_helpers'
 
 module CKEditor5::Rails
   module Editor::Helpers
+    include Editor::ConfigHelpers
+
     class EditorContextError < StandardError; end
     class PresetNotFoundError < ArgumentError; end
     class InvalidEditableHeightError < ArgumentError; end
@@ -26,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)
@@ -88,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/presets/preset_builder.rb

@@ -3,6 +3,8 @@
 module CKEditor5::Rails
   module Presets
     class PresetBuilder
+      include Editor::ConfigHelpers
+
       attr_reader :config
 
       def initialize

data/lib/ckeditor5/rails/version.rb

@@ -2,6 +2,6 @@
 
 module CKEditor5
   module Rails
-    VERSION = '1.7.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.7.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Mateusz Bagiński
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-12 00:00:00.000000000 Z
+date: 2024-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -51,6 +51,9 @@ 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
 - lib/ckeditor5/rails/editor/props_inline_plugin.rb