ckeditor5 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11255f34bfbd4ad2c1657efc1e5df34390d2adefb67a0e39a02ffc5be814ae84
-  data.tar.gz: 7fb31aa484581713750c55c6c0d0dce21d71a13063b4b77687f9663403b1c35d
+  metadata.gz: e8e40a31c033d3d5cfc96667757993fd4a92614a5e5bedacb93ec20d82419bd2
+  data.tar.gz: fb172fb186502165dd06475a980fd9ccbd21751076cf5a420edc64ace4129734
 SHA512:
-  metadata.gz: a52319bf5229236fbb4bb9f0d7515aa0cd68717c2b483cb2f2dd132f580600c7009d1fbe26e5fad1b356708b743839cd2a8d3998a8476ae24d1b7f3ae7d3f640
-  data.tar.gz: 960c18eecd8ae02b5caa418b47cbdaff3fd618382f53e630fe83bb310322622f19832e728f9d86ee11ff866da0d2abe8efd37ced1c7a1f8f05103c0f0dba43c5
+  metadata.gz: 64889f53d365c640f498efc484fbab12e05cfe93b80a9ab448c5bc5e3cb45bd24f313bce90ebd04cfd656c7cbd7c9cc60f7c982d7cf0aee8128cbc50633304ac
+  data.tar.gz: 1f9985d8cf29068eb70ecb93bf2c8e85a177750d0241e28075b1ba916a6e3a43cef71bd5598f4f25e25c6d9751cc36639065aa28065d592ff888012dbfd5bde3

data/README.md

@@ -1,4 +1,4 @@
-# CKEditor 5 Rails Integration
+# CKEditor 5 Rails Integration ✨
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-orange.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 ![Gem Version](https://img.shields.io/gem/v/ckeditor5?style=flat-square)
@@ -8,7 +8,7 @@
 
 Unofficial CKEditor 5 Ruby on Rails integration gem. Provides seamless integration of CKEditor 5 with Rails applications through web components and helper methods.
 
-## Installation
+## Installation 🛠️
 
 Add this line to your application's Gemfile:
 
@@ -16,29 +16,61 @@ Add this line to your application's Gemfile:
 gem 'ckeditor5'
 ```
 
-## Basic Usage
+Usage in your Rails application:
 
-### Presets
+```erb
+<!-- app/views/demos/index.html.erb -->
 
-Override default preset configuration:
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.2.0', translations: [:pl, :es] %>
+<% end %>
 
-```rb
-# config/initializers/ckeditor5.rb
-
-CKEditor5::Rails::Engine.configure do |config|
-  config.presets.override :default do |preset|
-    preset.menubar visible: false
-  end
-end
+<%= ckeditor5_editor style: 'width: 600px' %>
 ```
 
-Create new preset:
+Effect:
+
+![CKEditor 5 Classic Editor in Ruby on Rails application](docs/intro-classic-editor.png)
+
+## Table of Contents 📚
+
+- [CKEditor 5 Rails Integration ✨](#ckeditor-5-rails-integration-)
+  - [Installation 🛠️](#installation-️)
+  - [Table of Contents 📚](#table-of-contents-)
+  - [Presets 🎨](#presets-)
+    - [Available Configuration Methods ⚙️](#available-configuration-methods-️)
+      - [`shape(type)` method](#shapetype-method)
+      - [`plugins(*names)` method](#pluginsnames-method)
+      - [`toolbar(*items, should_group_when_full: true)` method](#toolbaritems-should_group_when_full-true-method)
+      - [`menubar(visible: true)` method](#menubarvisible-true-method)
+      - [`language(ui, content:)` method](#languageui-content-method)
+      - [`configure(name, value)` method](#configurename-value-method)
+      - [`plugin(name, premium:, import_name:)` method](#pluginname-premium-import_name-method)
+  - [Including CKEditor 5 assets 📦](#including-ckeditor-5-assets-)
+    - [Lazy loading 🚀](#lazy-loading-)
+    - [GPL usage 🆓](#gpl-usage-)
+    - [Commercial usage 💰](#commercial-usage-)
+  - [Editor placement 🏗️](#editor-placement-️)
+    - [Classic editor 📝](#classic-editor-)
+    - [Multiroot editor 🌳](#multiroot-editor-)
+    - [Inline editor 📝](#inline-editor-)
+    - [Balloon editor 🎈](#balloon-editor-)
+    - [Decoupled editor 🌐](#decoupled-editor-)
+  - [License 📜](#license-)
+
+## Presets 🎨
+
+Presets are predefined configurations of CKEditor 5, allowing quick setup with specific features. The gem includes a `:default` preset with common features like bold, italic, underline, and link for the classic editor.
+
+You can override the default preset or create your own by defining a new preset in the `config/initializers/ckeditor5.rb` file using the `config.presets.define` method.
+
+The example below shows how to define a custom preset with a classic editor and a custom toolbar:
 
 ```rb
 # config/initializers/ckeditor5.rb
 
 CKEditor5::Rails::Engine.configure do |config|
-  config.presets.define :custom do |preset|
+  config.presets.define :custom
     shape :classic
 
     menubar
@@ -59,64 +91,461 @@ CKEditor5::Rails::Engine.configure do |config|
             :TextTransformation, :TodoList, :Underline, :Undo, :Base64UploadAdapter
   end
 end
+```
+
+In order to override existing presets, you can use the `config.presets.override` method. The method takes the name of the preset you want to override and a block with the new configuration. In example below, we override the `:default` preset to hide the menubar.
 
-# Somewhere in your view
+```rb
+# config/initializers/ckeditor5.rb
 
-= ckeditor5_editor preset: :custom
+CKEditor5::Rails::Engine.configure do |config|
+  config.presets.override :default do
+    menubar visible: false
+  end
+end
 ```
 
-### CDN Configuration
+You can generate your preset using the CKEditor 5 [online builder](https://ckeditor.com/ckeditor-5/online-builder/). After generating the configuration, you can copy it to the `config/initializers/ckeditor5.rb` file.
+
+### Available Configuration Methods ⚙️
+
+<details>
+  <summary>Expand to show available methods 📖</summary>
+
+#### `shape(type)` method
+
+Defines the type of editor. Available options:
 
-#### jsDelivr (Default)
+- `:classic` - classic edytor
+- `:inline` - inline editor
+- `:decoupled` - decoupled editor
+- `:balloon` - balloon editor
+- `:multiroot` - editor with multiple editing areas
 
-```slim
-- content_for :head
-  = ckeditor5_assets version: '43.2.0'
+The example below shows how to define a multiroot editor:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  shape :multiroot
+end
 ```
 
-#### unpkg
+#### `plugins(*names)` method
+
+Defines the plugins to be included in the editor. You can specify multiple plugins by passing their names as arguments.
 
-```slim
-- content_for :head
-  = ckeditor5_unpkg_assets version: '43.2.0'
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  plugins :Bold, :Italic, :Underline, :Link
+end
 ```
 
-#### CKEditor Cloud
+#### `toolbar(*items, should_group_when_full: true)` method
+
+Defines the toolbar items. You can use predefined items like `:undo`, `:redo`, `:|` or specify custom items. There are a few special items:
+
+- `:_` - breakpoint
+- `:|` - separator
 
-It's available only for licensed users.
+The `should_group_when_full` keyword argument determines whether the toolbar should group items when there is not enough space. It's set to `true` by default.
 
-```slim
-- content_for :head
-  = ckeditor5_assets version: '43.2.0', license_key: 'YOUR-LICENSE-KEY'
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  toolbar :undo, :redo, :|, :heading, :|, :bold, :italic, :underline, :|,
+          :link, :insertImage, :ckbox, :mediaEmbed, :insertTable, :blockQuote, :|,
+          :bulletedList, :numberedList, :todoList, :outdent, :indent
+end
 ```
 
-### Editor type
+Keep in mind that the order of items is important, and you should install the corresponding plugins. You can find the list of available plugins in the [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/framework/architecture/plugins.html).
 
-#### Classic Editor
+#### `menubar(visible: true)` method
 
-```slim
-- content_for :head
-  = ckeditor5_assets version: '43.2.0' # Optional: translations: [ :pl, :es ]
+Defines the visibility of the menubar. By default, it's set to `true`.
 
-= ckeditor5_editor
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  toolbar :undo, :redo, :|, :heading, :|, :bold, :italic, :underline, :|,
+          :link, :insertImage, :ckbox, :mediaEmbed, :insertTable, :blockQuote, :|,
+          :bulletedList, :numberedList, :todoList, :outdent, :indent
+end
 ```
 
-#### Multiroot Editor
+#### `language(ui, content:)` method
+
+Defines the language of the editor. You can pass the language code as an argument. Keep in mind that the UI and content language can be different. The example below shows how to set the Polish language for the UI and content:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  language :pl
+end
+```
+
+In order to set the language for the content, you can pass the `content` keyword argument:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  language :en, content: :pl
+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://`:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  configure :link, {
+    defaultProtocol: 'https://'
+  }
+end
+```
+
+#### `plugin(name, premium:, import_name:)` method
+
+Defines a plugin to be included in the editor. You can pass the name of the plugin as an argument. The `premium` keyword argument determines whether the plugin is premium. The `import_name` keyword argument specifies the name of the package to import the plugin from.
+
+The example below show how to import Bold plugin from the `ckeditor5` npm package:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  plugin :Bold
+end
+```
+
+In order to import a plugin from a custom package, you can pass the `import_name` keyword argument:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  plugin :YourPlugin, import_name: 'your-package'
+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 assets. It allows you to specify custom translations to be included.
+
+Keep in mind that you need to include the assets in the `head` section of your layout. In examples below, we use `content_for` to include the assets in the `head` section.
+
+### Lazy loading 🚀
+
+<details>
+  <summary>Loading JS and CSS Assets</summary>
+
+All JS assets defined by the `ckeditor5_assets` helper method are loaded asynchronously. It means that the assets are loaded in the background without blocking the rendering of the page. However, the CSS assets are loaded synchronously to prevent the flash of unstyled content and ensure that the editor is styled correctly.
+
+It has been achieved by using web components, together with import maps, which are supported by modern browsers. The web components are used to define the editor and its plugins, while the import maps are used to define the dependencies between the assets.
+
+</details>
+
+### GPL usage 🆓
+
+If you want to use CKEditor 5 under the GPL license, you can include the assets using the `ckeditor5_assets` helper method with the `version` keyword argument. The example below shows how to include the assets for version `43.3.0`:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.3.0' %>
+<% end %>
+```
+
+It'll include the necessary assets for the GPL license from one of the most popular CDNs. In our scenario, we use the `jsdelivr` CDN which is the default one.
+
+In order to use `unpkg` CDN, you can pass the `cdn` keyword argument with the value `:unpkg`:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.3.0', cdn: :unpkg %>
+<% end %>
+```
+
+or using helper function:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_jsdelivr_assets version: '43.3.0' %>
+<% end %>
+```
+
+Translating CKEditor 5 is possible by passing the `translations` keyword argument with the languages codes array. The example below shows how to include the Polish translations:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.3.0', translations: [:pl] %>
+<% end %>
+```
+
+Keep in mind, that you need to include the translations in the `config/initializers/ckeditor5.rb` file:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails::Engine.configure do
+  presets.override :default do
+    language :pl
+  end
+end
+```
+
+### Commercial usage 💰
+
+<details>
+  <summary>Expand to show more</summary>
+
+If you want to use CKEditor 5 under a commercial license, you can include the assets using the `ckeditor5_assets` helper method with the `license_key` keyword argument. The example below shows how to include the assets for the commercial license:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets license_key: 'your-license-key' %>
+<% end %>
+```
+
+In this scenario, the assets are included from the official CKEditor 5 CDN which is more reliable and provides better performance, especially for commercial usage.
+
+</details>
+
+## Editor placement 🏗️
+
+The `ckeditor5_editor` helper renders CKEditor 5 instances in your views. Before using it, ensure you've included the necessary assets in your page's head section.
+
+### Classic editor 📝
+
+The classic editor is the most common type of editor. It provides a toolbar with various formatting options like bold, italic, underline, and link.
+
+It looks like this:
+
+![CKEditor 5 Classic Editor in Ruby on Rails application with Menubar](docs/classic-editor-with-toolbar.png)
+
+The example below shows how to include the classic editor in your view:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.3.0' %>
+<% end %>
+
+<%= ckeditor5_editor style: 'width: 600px' %>
+```
+
+You can pass the `style` keyword argument to the `ckeditor5_editor` helper to define the editor's style. The example above shows how to set the width of the editor to `600px`. However you can pass any HTML attribute you want, such as `class`, `id`, `data-*`, etc.
+
+While example above uses predefined `:default` preset, you can use your custom presets by passing the `preset` keyword argument:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.3.0' %>
+<% end %>
+
+<%= ckeditor5_editor preset: :custom, style: 'width: 600px' %>
+```
+
+If your configuration is even more complex, you can pass the `config` and `type` arguments with the configuration hash:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.3.0' %>
+<% end %>
+
+<%= ckeditor5_editor type: :classic, config: { plugins: [:Bold, :Italic], toolbar: [:Bold, :Italic] }, style: 'width: 600px' %>
+```
+
+If you want to override the configuration of the editor specified in default or custom preset, you can pass the `extra_config` keyword argument with the configuration hash:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.3.0' %>
+<% end %>
+
+<%= ckeditor5_editor extra_config: { toolbar: [:Bold, :Italic] }, style: 'width: 600px' %>
+```
+
+### Multiroot editor 🌳
+
+The multiroot editor allows you to create an editor with multiple editable areas. It's useful when you want to create a CMS with multiple editable areas on a single page.
+
+- `ckeditor5_editor`: Defines the editor instance.
+- `ckeditor5_editable`: Defines the editable areas within the editor.
+- `ckeditor5_toolbar`: Defines the toolbar for the editor.
+
+![CKEditor 5 Multiroot Editor in Ruby on Rails application](docs/multiroot-editor.png)
+
+If you want to use a multiroot editor, you can pass the `type` keyword argument with the value `:multiroot`:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.2.0' %>
+<% end %>
+
+<%= ckeditor5_editor type: :multiroot, style: 'width: 600px' do %>
+  <%= ckeditor5_toolbar %>
+  <br>
+  <%= ckeditor5_editable 'toolbar', style: 'border: 1px solid var(--ck-color-base-border);' do %>
+    This is a toolbar editable
+  <% end %>
+  <br>
+  <%= ckeditor5_editable 'content', style: 'border: 1px solid var(--ck-color-base-border)' %>
+  <br>
+<% end %>
+```
+
+Roots can be defined later to the editor by simply adding new elements rendered by `ckeditor5_editable` helper.
+
+### Inline editor 📝
+
+Inline editor allows you to create an editor that can be placed inside any element. Keep in mind that inline editor does not work with `textarea` elements so it might be not suitable for all use cases.
+
+![CKEditor 5 Inline Editor in Ruby on Rails application](docs/inline-editor.png)
+
+If you want to use an inline editor, you can pass the `type` keyword argument with the value `:inline`:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.2.0' %>
+<% end %>
+
+<%= ckeditor5_editor type: :inline, style: 'width: 600px' %>
+```
+
+### Balloon editor 🎈
+
+Balloon editor is a floating toolbar editor that provides a minimalistic interface. It's useful when you want to create a simple editor with a floating toolbar.
+
+![CKEditor 5 Balloon Editor in Ruby on Rails application](docs/balloon-editor.png)
+
+If you want to use a balloon editor, you can pass the `type` keyword argument with the value `:balloon`:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.2.0' %>
+<% end %>
+
+<%= ckeditor5_editor type: :balloon, style: 'width: 600px' %>
+```
 
-```slim
-= ckeditor5_editor type: :multiroot do
-  = ckeditor5_toolbar
-  br
-  = ckeditor5_editable 'editable-a' do
-    | This is a toolbar editable
-  br
-  = ckeditor5_editable 'editable-b'
+### Decoupled editor 🌐
+
+Decoupled editor is a variant of classic editor that allows you to separate the editor from the content area. It's useful when you want to create a custom interface with the editor.
+
+![CKEditor 5 Decoupled Editor in Ruby on Rails application](docs/decoupled-editor.png)
+
+If you want to use a decoupled editor, you can pass the `type` keyword argument with the value `:decoupled`:
+
+```erb
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.2.0', translations: [:pl, :es] %>
+<% end %>
+
+<style>
+  .menubar-container,
+  .editable-container,
+  .toolbar-container {
+    position: relative;
+    border: 1px solid red;
+  }
+
+  .menubar-container::after,
+  .editable-container::after,
+  .toolbar-container::after {
+    content: attr(class);
+    position: absolute;
+    background: red;
+    color: #fff;
+    top: 0;
+    right: 0;
+    font: 10px/2 monospace;
+    padding: .1em .3em;
+  }
+
+  .menubar-container,
+  .toolbar-container {
+    padding: 1em;
+  }
+
+  .editable-container {
+    padding: 3em;
+    overflow-y: scroll;
+    max-height: 300px;
+  }
+
+  .editable-container .ck-editor__editable {
+    min-height: 21cm;
+    padding: 2em;
+    border: 1px #D3D3D3 solid;
+    border-radius: var(--ck-border-radius);
+    background: white;
+    box-shadow: 0 0 5px rgba(0, 0, 0, 0.1);
+  }
+</style>
+
+<%= ckeditor5_editor type: :decoupled, style: 'width: 600px' do %>
+  <div class="menubar-container"><%= ckeditor5_menubar %></div>
+  <br>
+  <div class="toolbar-container"><%= ckeditor5_toolbar %></div>
+  <br>
+  <div class="editable-container"><%= ckeditor5_editable %></div>
+<% end %>
 ```
 
-## License
+## License 📜
 
 The MIT License (MIT)
-Copyright (c) Mateusz Bagiński / Łukasz Modliński
+Mateusz Bagiński / Łukasz Modliński
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

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

@@ -94,7 +94,7 @@ class CKEditorComponent extends HTMLElement {
       return Promise.resolve(callback(this.instance));
     }
 
-    return this.instancePromise.then(callback);
+    return this.instancePromise.promise.then(callback);
   }
 
   /**
@@ -115,25 +115,33 @@ class CKEditorComponent extends HTMLElement {
   /**
    * Initializes a new CKEditor instance
    * @private
-   * @param {Record<string, HTMLElement>|CKEditorMultiRootEditablesTracker} editables - Editable elements
+   * @param {Record<string, HTMLElement>|CKEditorMultiRootEditablesTracker} editablesOrContent - Editable or content
    * @returns {Promise<import('ckeditor5').Editor>} Initialized editor instance
    * @throws {Error} When initialization fails
    */
-  async #initializeEditor(editables) {
+  async #initializeEditor(editablesOrContent) {
     const Editor = await this.#getEditorConstructor();
     const [plugins, translations] = await Promise.all([
       this.#getPlugins(),
       this.#getTranslations()
     ]);
 
+    let content = editablesOrContent;
+
+    if (editablesOrContent instanceof CKEditorMultiRootEditablesTracker) {
+      content = editablesOrContent.getAll();
+    } else if (typeof editablesOrContent !== 'string') {
+      content = editablesOrContent.main;
+    }
+
     const instance = await Editor.create(
-      editables instanceof CKEditorMultiRootEditablesTracker
-        ? editables.getAll()
-        : editables.main,
+      content,
       {
         ...this.#getConfig(),
+        ...translations.length && {
+          translations
+        },
         plugins,
-        translations
       }
     );
 
@@ -158,21 +166,21 @@ class CKEditorComponent extends HTMLElement {
 
     this.style.display = 'block';
 
-    if (!this.#isMultiroot()) {
+    if (!this.isMultiroot() && !this.isDecoupled()) {
       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);
+    if(this.isMultiroot()) {
+      this.editables = new CKEditorMultiRootEditablesTracker(this, this.#queryEditables());
+    } else if (this.isDecoupled()) {
+      this.editables = null;
     } else {
-      this.editables = editables;
+      this.editables = this.#queryEditables();
     }
 
     try {
-      this.instance = await this.#initializeEditor(this.editables);
+      this.instance = await this.#initializeEditor(this.editables || this.#getConfig().initialData || '');
       this.instancePromise.resolve(this.instance);
     } catch (err) {
       this.instancePromise.reject(err);
@@ -186,10 +194,20 @@ class CKEditorComponent extends HTMLElement {
    * @private
    * @returns {boolean}
    */
-  #isMultiroot() {
+  isMultiroot() {
     return this.getAttribute('type') === 'MultiRootEditor';
   }
 
+  /**
+   * Checks if current editor is decoupled type
+   *
+   * @private
+   * @returns {boolean}
+   */
+  isDecoupled() {
+    return this.getAttribute('type') === 'DecoupledEditor';
+  }
+
   /**
    * Parses editor configuration from config attribute
    *
@@ -208,7 +226,11 @@ class CKEditorComponent extends HTMLElement {
    * @throws {Error} When required editables are missing
    */
   #queryEditables() {
-    if (this.#isMultiroot()) {
+    if (this.isDecoupled()) {
+      return {};
+    }
+
+    if (this.isMultiroot()) {
       const editables = [...this.querySelectorAll('ckeditor-editable-component')];
 
       return editables.reduce((acc, element) => {
@@ -444,7 +466,8 @@ class CKEditorEditableComponent extends HTMLElement {
    * @returns {string} The name attribute value
    */
   get name() {
-    return this.getAttribute('name');
+    // The default value is set mainly for decoupled editors where the name is not required.
+    return this.getAttribute('name') || 'editable';
   }
 
   /**
@@ -462,16 +485,28 @@ class CKEditorEditableComponent extends HTMLElement {
    * @throws {Error} If not used as child of ckeditor-component
    */
   connectedCallback() {
-    const editorComponent = this.#queryEditorElement();
+    execIfDOMReady(() => {
+      const editorComponent = this.#queryEditorElement();
 
-    if (!editorComponent ) {
-      throw new Error('ckeditor-editable-component must be a child of ckeditor-component');
-    }
+      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';
+      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;
+        editorComponent.editables[this.name] = this;
+      }
+    });
   }
 
   /**
@@ -522,28 +557,31 @@ class CKEditorEditableComponent extends HTMLElement {
    * @returns {CKEditorComponent|null} Parent editor component or null if not found
    */
   #queryEditorElement() {
-    return this.closest('ckeditor-component');
+    return this.closest('ckeditor-component') || document.body.querySelector('ckeditor-component');
   }
 }
 
 /**
- * Custom HTML element that represents a CKEditor toolbar component.
- * Manages the toolbar placement and integration with the main editor component.
+ * Custom HTML element that represents a CKEditor UI part component.
+ * It helpers with management of toolbar and other elements.
  *
  * @extends HTMLElement
- * @customElement ckeditor-toolbar
+ * @customElement ckeditor-ui-part-component
  * @example
- * <ckeditor-toolbar></ckeditor-toolbar>
+ * <ckeditor-ui-part-component></ckeditor-ui-part-component>
  */
-class CKEditorToolbarComponent extends HTMLElement {
+class CKEditorUIPartComponent 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;
+  connectedCallback() {
+    execIfDOMReady(async () => {
+      const uiPart = this.getAttribute('name');
+      const editor = await this.#queryEditorElement().instancePromise.promise;
 
-    this.appendChild(editor.ui.view.toolbar.element);
+      this.appendChild(editor.ui.view[uiPart].element);
+    });
   }
 
   /**
@@ -553,7 +591,7 @@ class CKEditorToolbarComponent extends HTMLElement {
    * @returns {CKEditorComponent|null} Parent editor component or null if not found
    */
   #queryEditorElement() {
-    return this.closest('ckeditor-component');
+    return this.closest('ckeditor-component') || document.body.querySelector('ckeditor-component');
   }
 }
 
@@ -600,4 +638,4 @@ function loadAsyncImports(imports = []) {
 
 customElements.define('ckeditor-component', CKEditorComponent);
 customElements.define('ckeditor-editable-component', CKEditorEditableComponent);
-customElements.define('ckeditor-toolbar-component', CKEditorToolbarComponent);
+customElements.define('ckeditor-ui-part-component', CKEditorUIPartComponent);

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

@@ -25,15 +25,24 @@ module CKEditor5::Rails
         context: context
       )
 
-      render_editor_component(editor_props, html_attributes, &(type == :multiroot ? block : nil))
+      render_editor_component(editor_props, html_attributes,
+                              &(%i[multiroot decoupled].include?(type) ? block : nil))
     end
 
-    def ckeditor5_editable(name, **kwargs, &block)
+    def ckeditor5_editable(name = nil, **kwargs, &block)
       tag.send(:'ckeditor-editable-component', name: name, **kwargs, &block)
     end
 
+    def ckeditor5_ui_part(name, **kwargs, &block)
+      tag.send(:'ckeditor-ui-part-component', name: name, **kwargs, &block)
+    end
+
     def ckeditor5_toolbar(**kwargs)
-      tag.send(:'ckeditor-toolbar-component', **kwargs)
+      ckeditor5_ui_part('toolbar', **kwargs)
+    end
+
+    def ckeditor5_menubar(**kwargs)
+      ckeditor5_ui_part('menuBarView', **kwargs)
     end
 
     private

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

@@ -4,9 +4,11 @@ module CKEditor5::Rails::Editor
   class PropsPlugin
     delegate :to_h, to: :import_meta
 
-    def initialize(name, premium: false)
+    def initialize(name, premium: false, import_name: nil)
       @name = name
       @premium = premium
+      @import_name = import_name
+      @import_name ||= premium ? 'ckeditor5-premium-features' : 'ckeditor5'
     end
 
     def self.normalize(plugin)
@@ -19,12 +21,12 @@ module CKEditor5::Rails::Editor
 
     private
 
-    attr_reader :name, :premium
+    attr_reader :name, :premium, :import_name
 
     def import_meta
       ::CKEditor5::Rails::Assets::JSImportMeta.new(
         import_as: name,
-        import_name: premium ? 'ckeditor5-premium-features' : 'ckeditor5'
+        import_name: import_name
       )
     end
   end

data/lib/ckeditor5/rails/presets.rb

@@ -80,20 +80,26 @@ module CKEditor5::Rails
       }
     end
 
-    def toolbar(*items)
-      @config[:toolbar] = items
+    def toolbar(*items, should_group_when_full: true)
+      @config[:toolbar] = {
+        items: items,
+        shouldNotGroupWhenFull: !should_group_when_full
+      }
     end
 
-    def plugin(name, premium: false)
-      @config[:plugins] << Editor::PropsPlugin.new(name, premium: premium)
+    def plugin(name, **kwargs)
+      @config[:plugins] << Editor::PropsPlugin.new(name, **kwargs)
     end
 
-    def plugins(*names, premium: false)
-      names.each { |name| plugin(name, premium: premium) }
+    def plugins(*names, **kwargs)
+      names.each { |name| plugin(name, **kwargs) }
     end
 
-    def language(lang)
-      @config[:language] = lang
+    def language(ui, content: ui) # rubocop:disable Naming/MethodParameterName
+      @config[:language] = {
+        ui: ui,
+        content: content
+      }
     end
   end
 end

data/lib/ckeditor5/rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CKEditor5::Rails
-  VERSION = '1.0.3'
+  VERSION = '1.0.5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ckeditor5
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.5
 platform: ruby
 authors:
 - Mateusz Bagiński