ckeditor5 1.0.4 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23e478e9988398f0612c2831798b5cd7a2abb9e6f21a8777e22964fe97974041
-  data.tar.gz: 817dfd3d0a94ef227c8e5845636468cf2aec54dbd19127f09feccd2c65d818cd
+  metadata.gz: ad357ef6b45ba35fdea777e70dae559476bd57040b23f49cfefa3581b4b3aafc
+  data.tar.gz: 89da75ef1325766ad4a2f0d81152822f8774b55efdf81bd76b8d9479332cb749
 SHA512:
-  metadata.gz: 00d576237488fcf65f5ceb1df860f1a2c6a31beccfc4361d57253ae014998072f083f282f66d4d0114e5eb8f50f3c838c56e172ded14bd559dbfe2b6d7c0abf4
-  data.tar.gz: a76c84be02f3c76acd8c4a39505264677ab34e3b4536887e1309da41417846346cee2f86718fef8e64f897acd4f5488f373def7c2299a49ca5ac8397ae296cf9
+  metadata.gz: f4f599b202ef0c109e14ff12c25f09890808d53e2116b2d3b6e51dfbfc5f389ea1d62651aa1a493fb897838e56ca2f3345addee8eebd55f5c2b7126f55169ce3
+  data.tar.gz: fc254a7f703defae55c901a444329772e177dfbfc8d0ee4ea3864c6c516b1c36f64e21166ec2e787d79ce368e09981ad524f4187842f31b53b8084ab690ed13b

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,20 +16,68 @@ Add this line to your application's Gemfile:
 gem 'ckeditor5'
 ```
 
-## Presets
+Usage in your Rails application:
 
-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.
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets version: '43.2.0', translations: [:pl, :es] %>
+<% end %>
+
+<%= ckeditor5_editor style: 'width: 600px' %>
+```
 
-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.
+Result:
+
+![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-️)
+      - [`version(version)` method](#versionversion-method)
+      - [`gpl` method](#gpl-method)
+      - [`premium` method](#premium-method)
+      - [`translations(*languages)` method](#translationslanguages-method)
+      - [`license_key(key)` method](#license_keykey-method)
+      - [`ckbox` method](#ckbox-method)
+      - [`type(type)` method](#typetype-method)
+      - [`plugins(*names, **kwargs)` method](#pluginsnames-kwargs-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 🎨
 
-The example below shows how to define a custom preset with a classic editor and a custom toolbar:
+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 create your own by defining it in the `config/initializers/ckeditor5.rb` file using the `config.presets.define` method. The example below illustrates the setup of 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
-    shape :classic
+    gpl # Use GPL license
+
+    type :classic
 
     menubar
 
@@ -51,7 +99,7 @@ CKEditor5::Rails::Engine.configure do |config|
 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.
+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 old configuration. The example below shows how to hide the menubar in the default preset:
 
 ```rb
 # config/initializers/ckeditor5.rb
@@ -63,64 +111,145 @@ CKEditor5::Rails::Engine.configure do |config|
 end
 ```
 
-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.
+Configuration of the editor can be complex, and it's recommended to use the CKEditor 5 [online builder](https://ckeditor.com/ckeditor-5/online-builder/) to generate the configuration. It allows you to select the features you want to include and generate the configuration code in JavaScript format.  Keep in mind that you need to convert the JavaScript configuration to Ruby format before using it in this gem.
 
-### Available Configuration Methods
+### Available Configuration Methods ⚙️
 
-#### `shape(type)` method
+<details>
+  <summary>Expand to show available methods 📖</summary>
 
-Defines the type of editor. Available options:
+#### `version(version)` method
 
-- `:classic` - standard editor
-- `:inline` - inline editor
-- `:balloon` - balloon editor
-- `:multiroot` - editor with multiple editing areas
+Defines the version of CKEditor 5 to be used. The example below shows how to set the version to `43.2.0`:
+
+```rb
+# config/initializers/ckeditor5.rb
 
-The example below shows how to define a multiroot editor:
+config.presets.define :custom do
+  # ... other configuration
+
+  version '43.2.0'
+end
+```
+
+#### `gpl` method
+
+Defines the license of CKEditor 5. The example below shows how to set the license to GPL:
 
 ```rb
+# config/initializers/ckeditor5.rb
+
 config.presets.define :custom do
-  shape :multiroot
+  # ... other configuration
+
+  gpl
 end
 ```
 
-#### `plugins(*names)` method
+#### `premium` method
 
-Defines the plugins to be included in the editor. You can specify multiple plugins by passing their names as arguments.
+Defines if premium package (`ckeditor5-premium-features`) should be used.
 
 ```rb
+# config/initializers/ckeditor5.rb
+
 config.presets.define :custom do
-  plugins :Bold, :Italic, :Underline, :Link
+  # ... other configuration
+
+  premium
 end
 ```
 
-#### `toolbar(*items, should_group_when_full: true)` method
+#### `translations(*languages)` method
 
-Defines the toolbar items. You can use predefined items like `:undo`, `:redo`, `:|` or specify custom items. There are a few special items:
+Defines the translations of CKEditor 5. You can pass the language codes as arguments. The example below shows how to set the Polish and Spanish translations:
 
-- `:_` - breakpoint
-- `:|` - separator
+```rb
+# config/initializers/ckeditor5.rb
 
-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.
+config.presets.define :custom do
+  # ... other configuration
+
+  translations :pl, :es
+end
+```
+
+#### `license_key(key)` method
+
+Defines the license key of CKEditor 5. It calls `premium` method internally. The example below shows how to set the 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
+  license_key 'your-license-key'
 end
 ```
 
-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).
+#### `ckbox` method
 
-Defines the toolbar items. You can use predefined items like `:undo`, `:redo`, `:|` or specify custom items. There are few special items:
+Defines the CKBox plugin to be included in the editor. The example below shows how to include the CKBox plugin:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  ckbox '2.5.4', theme: :lark
+end
+```
+
+#### `type(type)` method
+
+Defines the type of editor. Available options:
+
+- `:classic` - classic edytor
+- `:inline` - inline editor
+- `:decoupled` - decoupled editor
+- `:balloon` - balloon editor
+- `:multiroot` - editor with multiple editing areas
+
+The example below sets the editor type to `multiroot` in the custom preset:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  type :multiroot
+end
+```
+
+#### `plugins(*names, **kwargs)` method
+
+Defines the plugins to be included in the editor. You can specify multiple plugins by passing their names as arguments. The keyword arguments are identical to the configuration of the `plugin` method defined below.
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  plugins :Bold, :Italic, :Underline, :Link
+end
+```
+
+#### `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
 
+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.
+
 ```rb
+# config/initializers/ckeditor5.rb
+
 config.presets.define :custom do
   # ... other configuration
 
@@ -137,6 +266,8 @@ Keep in mind that the order of items is important, and you should install the co
 Defines the visibility of the menubar. By default, it's set to `true`.
 
 ```rb
+# config/initializers/ckeditor5.rb
+
 config.presets.define :custom do
   # ... other configuration
 
@@ -151,7 +282,11 @@ end
 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
 ```
@@ -159,7 +294,11 @@ 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
 ```
@@ -169,7 +308,11 @@ end
 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://'
   }
@@ -183,7 +326,11 @@ Defines a plugin to be included in the editor. You can pass the name of the plug
 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
 ```
@@ -191,15 +338,330 @@ 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
 ```
 
-## License
+</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.
+
+Keep in mind that you need to include the helper result in the `head` section of your layout. In examples below, we use `content_for` helper to include the assets in the `head` section of the view.
+
+### 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.
+
+Version is optional as long as you defined it in the `config/initializers/ckeditor5.rb` file. If you want to use the default version, you can omit the `version` keyword argument:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets %>
+<% end %>
+```
+
+Set the version in the `config/initializers/ckeditor5.rb` file:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails::Engine.configure do
+  presets.override :default do
+    version '43.3.0'
+  end
+end
+```
+
+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 otherwise the editor won't work as there are no CKEditor 5 JavaScript and CSS files loaded.
+
+### 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 %>
+<% 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 %>
+<% 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 %>
+<% 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 %>
+<% 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 %>
+<% 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 %>
+<% 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 %>
+<% end %>
+
+<%= ckeditor5_editor type: :balloon, style: 'width: 600px' %>
+```
+
+### 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 %>
+<% 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 📜
 
 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/cdn/ckbox_bundle.rb

@@ -7,7 +7,7 @@ module CKEditor5::Rails
 
       attr_reader :cdn, :version, :theme, :translations
 
-      def initialize(version, theme: :lark, cdn: Engine.base.default_cdn, translations: [])
+      def initialize(version, theme: :lark, cdn: Engine.default_preset.cdn, translations: [])
         raise ArgumentError, 'version must be semver' unless version.is_a?(Semver)
         raise ArgumentError, 'theme must be a string' unless theme.is_a?(String)
         raise ArgumentError, 'translations must be an array' unless translations.is_a?(Array)

data/lib/ckeditor5/rails/cdn/ckeditor_bundle.rb

@@ -7,7 +7,7 @@ module CKEditor5::Rails
 
       attr_reader :version, :translations, :import_name
 
-      def initialize(version, import_name, cdn: Engine.base.default_cdn, translations: [])
+      def initialize(version, import_name, cdn: Engine.default_preset.cdn, translations: [])
         raise ArgumentError, 'version must be semver' unless version.is_a?(Semver)
         raise ArgumentError, 'import_name must be a string' unless import_name.is_a?(String)
         raise ArgumentError, 'translations must be an array' unless translations.is_a?(Array)

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

@@ -6,7 +6,17 @@ require_relative 'ckbox_bundle'
 
 module CKEditor5::Rails
   module Cdn::Helpers
-    def ckeditor5_cdn_assets(version:, cdn:, license_key: 'GPL', premium: false, translations: [], ckbox: nil)
+    def ckeditor5_cdn_assets(preset: :default, **kwargs)
+      merge_with_editor_preset(preset, **kwargs) => {
+        cdn:,
+        version:,
+        translations:,
+        ckbox:,
+        license_key:,
+        premium:,
+        **kwargs
+      }
+
       bundle = build_base_cdn_bundle(cdn, version, translations)
       bundle << build_premium_cdn_bundle(cdn, version, translations) if premium
       bundle << build_ckbox_cdn_bundle(ckbox) if ckbox
@@ -29,12 +39,34 @@ module CKEditor5::Rails
       if kwargs[:license_key] && kwargs[:license_key] != 'GPL'
         ckeditor5_cloud_assets(**kwargs)
       else
-        ckeditor5_cdn_assets(**kwargs.merge(cdn: Engine.base.default_cdn))
+        ckeditor5_cdn_assets(**kwargs.merge(cdn: Engine.default_preset.cdn))
       end
     end
 
     private
 
+    def merge_with_editor_preset(preset, **kwargs)
+      found_preset = Engine.base.presets[preset]
+
+      if found_preset.blank?
+        raise ArgumentError,
+              "Poor thing. You forgot to define your #{preset} preset. " \
+              'Please define it in initializer. Thank you!'
+      end
+
+      hash = found_preset.to_h_with_overrides(**kwargs)
+
+      %i[version type].each do |key|
+        next if hash[key].present?
+
+        raise ArgumentError,
+              "Poor thing. You forgot to define #{key}. Make sure you passed `#{key}:` parameter to " \
+              "`ckeditor5_cdn_assets` or defined default one in your `#{preset}` preset!"
+      end
+
+      hash
+    end
+
     def build_base_cdn_bundle(cdn, version, translations)
       Cdn::CKEditorBundle.new(
         Semver.new(version),

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.rb

@@ -54,7 +54,7 @@ module CKEditor5::Rails::Editor
     def serialize_config
       config
         .except(:plugins)
-        .merge(licenseKey: context[:license_key] || 'GPL')
+        .tap { |cfg| cfg[:licenseKey] = context[:license_key] if context[:license_key] }
         .to_json
     end
   end

data/lib/ckeditor5/rails/engine.rb

@@ -7,12 +7,6 @@ module CKEditor5::Rails
   class Engine < ::Rails::Engine
     config.ckeditor5 = ActiveSupport::OrderedOptions.new
 
-    # Specifies which CDN should be used to load CKEditor 5 using the ckeditor5_assets helper.
-    # It is possible to use the following CDNs:
-    # - :unpkg
-    # - :jsdelivr (default)
-    config.ckeditor5.default_cdn = :jsdelivr
-
     # Specifies configuration of editors generated by gem.
     config.ckeditor5.presets = PresetsManager.new
 
@@ -26,6 +20,10 @@ module CKEditor5::Rails
       config.ckeditor5
     end
 
+    def self.default_preset
+      config.ckeditor5.presets.default
+    end
+
     def self.configure
       yield config.ckeditor5
     end

data/lib/ckeditor5/rails/presets.rb

@@ -31,7 +31,9 @@ module CKEditor5::Rails
 
     def define_default_preset
       define :default do
-        shape :classic
+        gpl
+
+        type :classic
 
         menubar
 
@@ -54,17 +56,79 @@ module CKEditor5::Rails
   end
 
   class PresetBuilder
-    attr_reader :type, :config
+    attr_reader :config
 
     def initialize
+      @version = nil
+      @premium = false
+      @cdn = :jsdelivr
+      @translations = []
+      @license_key = nil
       @type = :classic
+      @ckbox = nil
       @config = {
         plugins: [],
         toolbar: []
       }
     end
 
-    def shape(type)
+    def to_h_with_overrides(**overrides)
+      {
+        version: overrides.fetch(:version, version),
+        premium: overrides.fetch(:premium, premium),
+        cdn: overrides.fetch(:cdn, cdn),
+        translations: overrides.fetch(:translations, translations),
+        license_key: overrides.fetch(:license_key, license_key),
+        type: overrides.fetch(:type, type),
+        ckbox: overrides.fetch(:ckbox, ckbox),
+        config: config.merge(overrides.fetch(:config, {}))
+      }
+    end
+
+    def ckbox(version = nil, theme: :lark)
+      return @ckbox if version.nil?
+
+      @ckbox = { version: version, theme: theme }
+    end
+
+    def license_key(license_key = nil)
+      return @license_key if license_key.nil?
+
+      @license_key = license_key
+    end
+
+    def gpl
+      license_key('GPL')
+      premium(false)
+    end
+
+    def premium(premium = nil)
+      return @premium if premium.nil?
+
+      @premium = premium
+    end
+
+    def translations(*translations)
+      return @translations if translations.empty?
+
+      @translations = translations
+    end
+
+    def version(version = nil)
+      return @version.to_s if version.nil?
+
+      @version = Semver.new(version)
+    end
+
+    def cdn(cdn = nil)
+      return @cdn if cdn.nil?
+
+      @cdn = cdn
+    end
+
+    def type(type = nil)
+      return @type if type.nil?
+
       raise ArgumentError, "Invalid editor type: #{type}" unless Editor::Props.valid_editor_type?(type)
 
       @type = type

data/lib/ckeditor5/rails/semver.rb

@@ -6,7 +6,7 @@ class CKEditor5::Rails::Semver
   alias to_s :version
 
   def initialize(version)
-    @version = version
+    @version = version.to_s
     validate!
   end
 

data/lib/ckeditor5/rails/version.rb

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

metadata

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