ckeditor5 1.16.2 → 1.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80773f82ac9fcdf35feac2e568206c4dd5dbd04240ae891b880549fc7192ef12
-  data.tar.gz: d4c4244344977827288691f7846bce8737c70d9df170aff1fa2fb52a3a400d1a
+  metadata.gz: 78094e2b7cf2ec9677a1eb9ee629918df4b6e9de62104cd6e2c8713b02ae7776
+  data.tar.gz: 63816a1caf2f2c42f08321f0169fb14e54e2f6424bc80834890dfde68a76f22f
 SHA512:
-  metadata.gz: 2b681fd82436a62b4da89064979c02f4952ba1c210473b3d00791fe34627555e6df6761c4fb9cdbd49ea3258a3ce508c7c2c013ae4dccb56eb452848f936024a
-  data.tar.gz: 1c2170807abc784d8905b6817a8b1fb03c08d1f8ce3be48403923b96c255232c7acea65bacd417922e0014e5b18f7eb58dd6702837d0fc7bca3df936bee9774d
+  metadata.gz: b3691b024f1cedc6da4086fea1754f6f4d7acdc2d3d9a10f5628b0b54c539e941073cff74459dd776956c758fe4da1f78b54a6c8ab0128248e1ecc9b308ba168
+  data.tar.gz: a5d4109cc5f559144a66abd7ba1b672a27d1ad41131bdead590c144d4c4b2d1eb518953267bfee9fb6fa14c9cce027416de28dece065ed852c198fd4587e08dc

data/README.md

@@ -44,8 +44,8 @@ In your view:
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <!-- 📦 Loads CKEditor assets via importmap based on initializer config -->
-  <%= ckeditor5_assets %>
+  <!-- 📦 Adds importmap with CKEditor 5 assets. Language is optional. -->
+  <%= ckeditor5_assets language: :en %>
 <% end %>
 
 <!-- 🖋️ CKEditor 5 might be placed using simple view helper ... -->
@@ -113,12 +113,12 @@ For extending CKEditor's functionality, refer to the [plugins directory](https:/
       - [`license_key(key)` method](#license_keykey-method)
       - [`premium` method](#premium-method)
       - [`editable_height(height)` method](#editable_heightheight-method)
+      - [`language(ui, content:)` method](#languageui-content-method)
       - [`translations(*languages)` method](#translationslanguages-method)
       - [`ckbox` method](#ckbox-method)
       - [`type(type)` method](#typetype-method)
       - [`toolbar(*items, should_group_when_full: true, &block)` method](#toolbaritems-should_group_when_full-true-block-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)
       - [`plugins(*names, **kwargs)` method](#pluginsnames-kwargs-method)
@@ -126,7 +126,7 @@ For extending CKEditor's functionality, refer to the [plugins directory](https:/
       - [`simple_upload_adapter(url)` method](#simple_upload_adapterurl-method)
     - [Controller / View helpers 📦](#controller--view-helpers-)
       - [`ckeditor5_element_ref(selector)` method](#ckeditor5_element_refselector-method)
-      - [`ckeditor5_preset(&block)` method](#ckeditor5_presetblock-method)
+      - [`ckeditor5_preset(name = nil, &block)` method](#ckeditor5_presetname--nil-block-method)
   - [Including CKEditor 5 assets 📦](#including-ckeditor-5-assets-)
     - [Format 📝](#format-)
       - [Using default preset](#using-default-preset)
@@ -234,6 +234,8 @@ CKEditor5::Rails.configure do
 end
 ```
 
+You can define presets in the controller using the `ckeditor5_preset` helper method. See it in the section below ([Controller / View helpers](#controller--view-helpers-)).
+
 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.
 
 ### Automatic upgrades 🔄
@@ -256,6 +258,11 @@ end
 
 #### `cdn(cdn = nil, &block)` method
 
+<details>
+  <summary>Configure custom CDN URL pattern or use predefined CDNs like jsdelivr or unpkg</summary>
+
+<br />
+
 Defines the CDN to be used for CKEditor 5 assets. The example below shows how to set the CDN to `:jsdelivr`:
 
 ```rb
@@ -283,9 +290,15 @@ CKEditor5::Rails.configure do
   end
 end
 ```
+</details>
 
 #### `version(version)` method
 
+<details>
+  <summary>Set up the version of CKEditor 5 to be used by the integration</summary>
+
+<br />
+
 Defines the version of CKEditor 5 to be used. The example below shows how to set the version to `43.2.0`:
 
 ```rb
@@ -297,9 +310,15 @@ CKEditor5::Rails.configure do
   version '43.3.1'
 end
 ```
+</details>
 
 #### `automatic_upgrades(enabled: true)` method
 
+<details>
+  <summary>Enable or disable automatic security patches and bug fixes</summary>
+
+<br />
+
 Defines if automatic upgrades should be enabled. It's enabled for the `:default` preset by default. The example below shows how to disable automatic upgrades:
 
 ```rb
@@ -315,9 +334,15 @@ end
 It means that the editor will automatically upgrade to the latest version when the gem is updated. It'll upgrade the editor only if the new patch or minor version is released. If you want to disable automatic upgrades, you can pass the `enabled: false` keyword argument to the `automatic_upgrades` method.
 
 Version is checked every nth day, where n is the number of days since the last check. Currently it's 4 days.
+</details>
 
 #### `gpl` method
 
+<details>
+  <summary>Defines the license of CKEditor 5. The example below shows how to set the license to GPL:</summary>
+
+<br />
+
 Defines the license of CKEditor 5. The example below shows how to set the license to GPL:
 
 ```rb
@@ -329,9 +354,15 @@ CKEditor5::Rails.configure do
   gpl
 end
 ```
+</details>
 
 #### `license_key(key)` method
 
+<details>
+  <summary>Defines the license key of CKEditor 5. It calls `premium` method internally. The example below shows how to set the license key:</summary>
+
+<br />
+
 Defines the license key of CKEditor 5. It calls `premium` method internally. The example below shows how to set the license key:
 
 ```rb
@@ -343,9 +374,15 @@ CKEditor5::Rails.configure do
   license_key 'your-license-key'
 end
 ```
+</details>
 
 #### `premium` method
 
+<details>
+  <summary>Defines if premium package should be included in JS assets. The example below shows how to add `ckeditor5-premium-features` to import maps:</summary>
+
+<br />
+
 Defines if premium package should be included in JS assets. The example below shows how to add `ckeditor5-premium-features` to import maps:
 
 ```rb
@@ -357,9 +394,15 @@ CKEditor5::Rails.configure do
   premium
 end
 ```
+</details>
 
 #### `editable_height(height)` method
 
+<details>
+  <summary>Set editor height in pixels - useful for fixed-size layouts</summary>
+
+<br />
+
 Defines the height of the editor. The example below shows how to set the height to `300px`:
 
 ```rb
@@ -371,9 +414,50 @@ CKEditor5::Rails.configure do
   editable_height 300
 end
 ```
+</details>
+
+#### `language(ui, content:)` method
+
+<details>
+  <summary>Set UI and content language for the editor</summary>
+
+<br />
+
+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
+
+CKEditor5::Rails.configure 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
+
+CKEditor5::Rails.configure do
+  # ... other configuration
+
+  language :pl
+end
+```
+
+The example above sets the Polish language for the UI and content. If `pl` language was not defined in the translations, the builder will append the language to the list of translations to fetch. In order to prefetch more translations, use the helper below.
+
+</details>
 
 #### `translations(*languages)` method
 
+<details>
+  <summary>Load additional language files for the editor interface</summary>
+
+<br />
+
 Defines the translations of CKEditor 5. You can pass the language codes as arguments. The example below shows how tell integration to fetch Polish and Spanish translations:
 
 ```rb
@@ -398,9 +482,15 @@ CKEditor5::Rails.configure do
   language :pl
 end
 ```
+</details>
 
 #### `ckbox` method
 
+<details>
+  <summary>Configure CKBox file manager integration</summary>
+
+<br />
+
 Defines the CKBox plugin to be included in the editor. The example below shows how to include the CKBox plugin:
 
 ```rb
@@ -412,9 +502,15 @@ CKEditor5::Rails.configure do
   ckbox '2.6.0', theme: :lark
 end
 ```
+</details>
 
 #### `type(type)` method
 
+<details>
+  <summary>Select editor type (classic, inline, balloon, decoupled, multiroot)</summary>
+
+<br />
+
 Defines the type of editor. Available options:
 
 - `:classic` - classic edytor
@@ -434,9 +530,15 @@ CKEditor5::Rails.configure do
   type :multiroot
 end
 ```
+</details>
 
 #### `toolbar(*items, should_group_when_full: true, &block)` method
 
+<details>
+  <summary>Define toolbar items and their grouping behavior</summary>
+
+<br />
+
 Defines the toolbar items. You can use predefined items like `:undo`, `:redo`, `:|` or specify custom items. There are a few special items:
 
 - `:_` - breakpoint
@@ -486,9 +588,15 @@ CKEditor5::Rails.configure do
   end
 end
 ```
+</details>
 
 #### `menubar(visible: true)` method
 
+<details>
+  <summary>Set the visibility and options for the editor menubar</summary>
+
+<br />
+
 Defines the visibility of the menubar. By default, it's set to `true`.
 
 ```rb
@@ -502,34 +610,14 @@ CKEditor5::Rails.configure do
           :bulletedList, :numberedList, :todoList, :outdent, :indent
 end
 ```
+</details>
 
-#### `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
-
-CKEditor5::Rails.configure 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
-
-CKEditor5::Rails.configure do
-  # ... other configuration
+#### `configure(name, value)` method
 
-  language :en, content: :pl
-end
-```
+<details>
+  <summary>Add custom configuration options to the editor instance</summary>
 
-#### `configure(name, value)` method
+<br />
 
 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.
 
@@ -557,9 +645,15 @@ CKEditor5::Rails.configure do
   }
 end
 ```
+</details>
 
 #### `plugin(name, premium:, import_name:)` method
 
+<details>
+  <summary>Register individual CKEditor plugins with optional premium flag</summary>
+
+<br />
+
 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:
@@ -597,11 +691,19 @@ CKEditor5::Rails.configure do
   plugin :YourPlugin, window_name: 'YourPlugin'
 end
 ```
+</details>
 
 #### `plugins(*names, **kwargs)` method
 
+<details>
+  <summary>Register multiple CKEditor plugins at once</summary>
+
+<br />
+
 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.
 
+<br />
+
 ```rb
 # config/initializers/ckeditor5.rb
 
@@ -625,9 +727,15 @@ CKEditor5::Rails.configure do
   end
 end
 ```
+</details>
 
 #### `inline_plugin(name, code)` method
 
+<details>
+  <summary>Define custom CKEditor plugins directly in the configuration</summary>
+
+<br />
+
 ⚠️ **Warning:** Use with caution as this is an inline definition of the plugin code, and it can potentially cause XSS vulnerabilities. Only use this method with static, trusted JavaScript code. The example below shows how to define a custom plugin that highlights the text:
 
 ```rb
@@ -670,11 +778,19 @@ end
 ```
 
 This approach is resistant to XSS attacks as it avoids inline JavaScript.
+</details>
 
 #### `simple_upload_adapter(url)` method
 
+<details>
+  <summary>Configure server-side image upload endpoint</summary>
+
+<br />
+
 Defines the URL for the simple upload adapter. The default endpoint is `/uploads` and the method is `POST`. The example below shows how to set the URL to `/uploads`:
 
+<br />
+
 ```rb
 # config/initializers/ckeditor5.rb
 
@@ -685,12 +801,18 @@ CKEditor5::Rails.configure do
   # or: simple_upload_adapter '/uploads'
 end
 ```
+</details>
 
 ### Controller / View helpers 📦
 
 #### `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.
+<details>
+  <summary>Defines a reference to a CKEditor 5 element.</summary>
+
+<br />
+
+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
@@ -703,10 +825,16 @@ CKEditor5::Rails.configure do
   }
 end
 ```
+</details>
+
+#### `ckeditor5_preset(name = nil, &block)` method
+
+<details>
+  <summary>The `ckeditor5_preset` method allows you to define a custom preset in your application controller.</summary>
 
-#### `ckeditor5_preset(&block)` method
+<br />
 
-The `ckeditor5_preset` method allows you to define a custom preset in your application controller. It may be useful when you want to define a preset based on the current user or request.
+It may be useful when you want to define a preset based on the current user or request.
 
 ```rb
 # app/controllers/application_controller.rb
@@ -741,6 +869,31 @@ In order to use the preset in the view, you can pass it to the `ckeditor5_assets
 <%= ckeditor5_editor %>
 ```
 
+If you want to override the preset defined in the initializer, you can search for the preset by name and then override it (it'll create copy of the preset):
+
+```rb
+# app/controllers/application_controller.rb
+
+class ApplicationController < ActionController::Base
+  def show
+    @preset = ckeditor5_preset(:default).override do
+      version '43.3.1'
+
+      toolbar :sourceEditing, :|, :bold, :italic, :underline, :strikethrough,
+              :subscript, :superscript, :removeFormat, :|, :bulletedList, :numberedList,
+              :fontFamily, :fontSize, :|, :link, :anchor, :|,
+              :fontColor, :fontBackgroundColor
+
+      plugins :Essentials, :Paragraph, :Bold, :Italic, :Underline, :Strikethrough,
+              :Subscript, :Superscript, :RemoveFormat, :List, :Link, :Font,
+              :FontFamily, :FontSize, :FontColor, :FontBackgroundColor, :SourceEditing, :Essentials, :Paragraph
+    end
+  end
+end
+```
+
+</details>
+
 ## Including CKEditor 5 assets 📦
 
 To include CKEditor 5 assets in your application, you can use the `ckeditor5_assets` helper method. This method takes the version of CKEditor 5 as an argument and includes the necessary resources of the editor. Depending on the specified configuration, it includes the JS and CSS assets from the official CKEditor 5 CDN or one of the popular CDNs.
@@ -1018,7 +1171,8 @@ If you want to override the configuration of the editor specified in default or
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets %>
+  <!-- You can override default preset in assets helper too. -->
+  <%= ckeditor5_assets translations: [:pl] %>
 <% end %>
 
 <%= ckeditor5_editor extra_config: { toolbar: [:Bold, :Italic] }, style: 'width: 600px' %>
@@ -1253,15 +1407,37 @@ This section covers frequent questions and scenarios when working with CKEditor
 
 ### Setting Editor Language 🌐
 
-You can set the language of the editor using the `language` method in the `config/initializers/ckeditor5.rb` file. The `translations` method fetches the translations files, while the `language` method sets the default language of the editor.
+You can set the language of the editor using the `language` keyword argument. The example below shows how to set the language of the editor to Polish:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets language: :pl %>
+<% end %>
+
+<%= ckeditor5_editor %>
+```
+
+It can be also set in the initializer:
 
 ```rb
-config.presets.override :default do
-  translations :pl, :es
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails.configure do
+  # Optional, it load multiple translation packs: translations :pl, :es
   language :pl
 end
 ```
 
+... or on the editor level (keep in mind to load translations in the assets helper):
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<%= ckeditor5_editor language: :pl %>
+```
+
 ### Integrating with Forms 📋
 
 You can integrate CKEditor 5 with Rails form builders like `form_for` or `simple_form`. The example below shows how to integrate CKEditor 5 with a Rails form using the `form_for` helper:

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

@@ -13,14 +13,14 @@ require_relative 'ckbox_bundle'
 module CKEditor5::Rails
   module Cdn::Helpers
     def ckeditor5_assets(preset: :default, **kwargs)
-      merge_with_editor_preset(preset, **kwargs) => {
+      mapped_preset = merge_with_editor_preset(preset, **kwargs)
+      mapped_preset => {
         cdn:,
         version:,
         translations:,
         ckbox:,
         license_key:,
-        premium:,
-        **kwargs
+        premium:
       }
 
       bundle = build_base_cdn_bundle(cdn, version, translations)
@@ -30,7 +30,7 @@ module CKEditor5::Rails
       @__ckeditor_context = {
         license_key: license_key,
         bundle: bundle,
-        preset: preset
+        preset: mapped_preset
       }
 
       Assets::AssetsBundleHtmlSerializer.new(bundle).to_html
@@ -53,17 +53,17 @@ module CKEditor5::Rails
               'Please define it in initializer. Thank you!'
       end
 
-      hash = found_preset.to_h_with_overrides(**kwargs)
+      new_preset = found_preset.clone.merge_with_hash!(**kwargs)
 
       %i[version type].each do |key|
-        next if hash[key].present?
+        next if new_preset.public_send(key).present?
 
         raise ArgumentError,
               "Poor thing. You forgot to define #{key}. Make sure you passed `#{key}:` parameter to " \
               "`ckeditor5_assets` or defined default one in your `#{preset}` preset!"
       end
 
-      hash
+      new_preset
     end
 
     def build_base_cdn_bundle(cdn, version, translations)

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

@@ -22,12 +22,13 @@ module CKEditor5::Rails
     # @param initial_data [String] Initial content for the editor
     # @param watchdog [Boolean] Whether to enable the CKEditor watchdog feature
     # @param editable_height [String, Integer] Height of the editable area (Classic editor only)
+    # @param language [String] Language code for the editor UI
     # @param html_attributes [Hash] Additional HTML attributes for the editor element
     def ckeditor5_editor( # rubocop:disable Metrics/ParameterLists
       preset: nil,
       config: nil, extra_config: {}, type: nil,
       initial_data: nil, watchdog: true,
-      editable_height: nil,
+      editable_height: nil, language: nil,
       **html_attributes, &block
     )
       validate_editor_input!(initial_data, block)
@@ -41,7 +42,8 @@ module CKEditor5::Rails
       editor_props = Editor::Props.new(
         controller_context, type, config,
         watchdog: watchdog,
-        editable_height: editable_height
+        editable_height: editable_height,
+        language: language
       )
 
       tag_attributes = html_attributes.merge(editor_props.to_attributes)

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

@@ -13,13 +13,17 @@ module CKEditor5::Rails::Editor
       multiroot: 'MultiRootEditor'
     }.freeze
 
-    def initialize(controller_context, type, config, watchdog: true, editable_height: nil)
+    def initialize(
+      controller_context, type, config,
+      watchdog: true, editable_height: nil, language: nil
+    )
       raise ArgumentError, "Invalid editor type: #{type}" unless Props.valid_editor_type?(type)
 
       @controller_context = controller_context
       @watchdog = watchdog
       @type = type
       @config = config
+      @language = language
       @editable_height = EditableHeightNormalizer.new(type).normalize(editable_height)
     end
 
@@ -59,7 +63,10 @@ module CKEditor5::Rails::Editor
     def serialize_config
       config
         .except(:plugins)
-        .tap { |cfg| cfg[:licenseKey] = controller_context[:license_key] if controller_context[:license_key] }
+        .tap do |cfg|
+          cfg[:licenseKey] = controller_context[:license_key] if controller_context[:license_key]
+          cfg[:language] = { ui: @language } if @language
+        end
         .to_json
     end
   end

data/lib/ckeditor5/rails/presets/preset_builder.rb

@@ -49,17 +49,33 @@ module CKEditor5::Rails
         license_key == 'GPL'
       end
 
-      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, {}))
-        }
+      def deconstruct_keys(keys)
+        keys.index_with do |key|
+          public_send(key)
+        end
+      end
+
+      def override(&block)
+        clone.tap do |preset|
+          preset.instance_eval(&block)
+        end
+      end
+
+      def merge_with_hash!(language: nil, **overrides) # rubocop:disable Metrics/AbcSize
+        @version = Semver.new(overrides[:version]) if overrides.key?(: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)
+        @editable_height = overrides.fetch(:editable_height, editable_height)
+        @automatic_upgrades = overrides.fetch(:automatic_upgrades, automatic_upgrades)
+        @ckbox = overrides.fetch(:ckbox, ckbox) if overrides.key?(:ckbox) || ckbox
+        @config = config.merge(overrides.fetch(:config, {}))
+
+        language(language) if language
+
+        self
       end
 
       def editable_height(height = nil)
@@ -169,6 +185,8 @@ module CKEditor5::Rails
       def language(ui = nil, content: ui) # rubocop:disable Naming/MethodParameterName
         return config[:language] if ui.nil?
 
+        @translations << ui.to_sym unless @translations.map(&:to_sym).include?(ui.to_sym)
+
         config[:language] = {
           ui: ui,
           content: content

data/lib/ckeditor5/rails/version.rb

@@ -2,7 +2,7 @@
 
 module CKEditor5
   module Rails
-    VERSION = '1.16.2'
+    VERSION = '1.17.1'
 
     DEFAULT_CKEDITOR_VERSION = '43.3.1'
   end

data/spec/e2e/features/locale_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'e2e/spec_helper'
+
+RSpec.describe 'Editor localization', type: :system do
+  describe 'setting locale via assets' do
+    it 'displays menubar in Polish' do
+      visit '/locale_via_assets'
+
+      expect(page).to have_css('.ck-editor__main')
+
+      within('.ck-menu-bar') do
+        expect(page).to have_content('Zmiana')
+        expect(page).to have_content('Wstaw')
+        expect(page).to have_content('Format')
+      end
+    end
+  end
+
+  describe 'setting locale via editor prop' do
+    it 'displays menubar in Spanish' do
+      visit '/locale_via_editor'
+
+      expect(page).to have_css('.ck-editor__main')
+
+      within('.ck-menu-bar') do
+        expect(page).to have_content('Editar')
+        expect(page).to have_content('Insertar')
+        expect(page).to have_content('Formato')
+      end
+    end
+  end
+
+  describe 'setting locale via preset' do
+    it 'displays menubar in Russian' do
+      visit '/locale_via_preset'
+
+      expect(page).to have_css('.ck-editor__main')
+
+      within('.ck-menu-bar') do
+        expect(page).to have_content('Редактировать')
+        expect(page).to have_content('Вставить')
+        expect(page).to have_content('Формат')
+      end
+    end
+  end
+end

data/spec/lib/ckeditor5/rails/cdn/helpers_spec.rb

@@ -6,19 +6,16 @@ RSpec.describe CKEditor5::Rails::Cdn::Helpers do
   let(:test_class) { Class.new { include CKEditor5::Rails::Cdn::Helpers } }
   let(:helper) { test_class.new }
   let(:preset) do
-    instance_double(
-      CKEditor5::Rails::Presets::PresetBuilder,
-      to_h_with_overrides: {
-        cdn: :cloud,
-        version: '34.1.0',
-        type: 'classic',
-        translations: %w[pl],
-        ckbox: nil,
-        license_key: nil,
-        premium: false
-      }
-    )
+    CKEditor5::Rails::Presets::PresetBuilder.new do
+      version '34.1.0'
+      type :classic
+      translations :pl
+      cdn :cloud
+      license_key nil
+      premium false
+    end
   end
+
   let(:bundle_html) { '<script src="test.js"></script>' }
   let(:serializer) do
     instance_double(CKEditor5::Rails::Assets::AssetsBundleHtmlSerializer, to_html: bundle_html)
@@ -40,7 +37,7 @@ RSpec.describe CKEditor5::Rails::Cdn::Helpers do
           .with(
             instance_of(CKEditor5::Rails::Semver),
             'ckeditor5',
-            translations: %w[pl],
+            translations: [:pl],
             cdn: :cloud
           )
           .and_call_original
@@ -50,18 +47,13 @@ RSpec.describe CKEditor5::Rails::Cdn::Helpers do
 
       context 'with premium features' do
         let(:preset) do
-          instance_double(
-            CKEditor5::Rails::Presets::PresetBuilder,
-            to_h_with_overrides: {
-              cdn: :cloud,
-              version: '34.1.0',
-              type: 'classic',
-              translations: %w[pl],
-              ckbox: nil,
-              license_key: nil,
-              premium: true
-            }
-          )
+          CKEditor5::Rails::Presets::PresetBuilder.new do
+            version '34.1.0'
+            type :classic
+            translations :pl
+            cdn :cloud
+            premium true
+          end
         end
 
         it 'creates base and premium bundles' do
@@ -69,7 +61,7 @@ RSpec.describe CKEditor5::Rails::Cdn::Helpers do
             .with(
               instance_of(CKEditor5::Rails::Semver),
               'ckeditor5',
-              translations: %w[pl],
+              translations: [:pl],
               cdn: :cloud
             )
             .and_call_original
@@ -79,7 +71,7 @@ RSpec.describe CKEditor5::Rails::Cdn::Helpers do
             .with(
               instance_of(CKEditor5::Rails::Semver),
               'ckeditor5-premium-features',
-              translations: %w[pl],
+              translations: [:pl],
               cdn: :cloud
             )
             .and_call_original
@@ -91,18 +83,13 @@ RSpec.describe CKEditor5::Rails::Cdn::Helpers do
 
       context 'with ckbox' do
         let(:preset) do
-          instance_double(
-            CKEditor5::Rails::Presets::PresetBuilder,
-            to_h_with_overrides: {
-              cdn: :cloud,
-              version: '34.1.0',
-              type: 'classic',
-              translations: %w[pl],
-              ckbox: { version: '1.0.0', theme: :lark },
-              license_key: nil,
-              premium: false
-            }
-          )
+          CKEditor5::Rails::Presets::PresetBuilder.new do
+            version '34.1.0'
+            type :classic
+            translations :pl
+            cdn :cloud
+            ckbox '1.0.0', theme: :lark
+          end
         end
 
         it 'creates ckbox bundle' do
@@ -117,49 +104,40 @@ RSpec.describe CKEditor5::Rails::Cdn::Helpers do
           helper.ckeditor5_assets(preset: :default)
         end
       end
+    end
 
-      context 'when destructuring preset hash' do
-        let(:preset) do
-          instance_double(
-            CKEditor5::Rails::Presets::PresetBuilder,
-            to_h_with_overrides: {
-              cdn: :cloud,
-              version: '34.1.0',
-              type: 'classic',
-              translations: %w[pl],
-              ckbox: nil,
-              license_key: nil,
-              premium: false,
-              extra: 'value'
-            }
-          )
-        end
-
-        it 'successfully matches and extracts required parameters' do
-          expect { helper.ckeditor5_assets(preset: :default) }.not_to raise_error
+    context 'when overriding preset values' do
+      let(:preset) do
+        CKEditor5::Rails::Presets::PresetBuilder.new do
+          version '34.1.0'
+          type :classic
+          translations :pl
+          cdn :cloud
+          license_key 'preset-license'
+          premium false
         end
       end
-    end
 
-    context 'with invalid preset' do
-      before do
-        allow(CKEditor5::Rails::Engine).to receive(:find_preset).and_return(nil)
+      it 'allows overriding preset values' do
+        helper.ckeditor5_assets(preset: :default, license_key: 'overridden-license')
+
+        expect(helper.instance_variable_get(:@__ckeditor_context)[:preset].license_key)
+          .to eq('overridden-license')
       end
 
-      it 'raises error' do
-        expect { helper.ckeditor5_assets(preset: :invalid) }
-          .to raise_error(ArgumentError, /forgot to define your invalid preset/)
+      it 'preserves non-overridden preset values' do
+        helper.ckeditor5_assets(preset: :default, license_key: 'overridden-license')
+        preset_context = helper.instance_variable_get(:@__ckeditor_context)[:preset]
+
+        expect(preset_context.version).to eq('34.1.0')
+        expect(preset_context.premium?).to be false
+        expect(preset_context.cdn).to eq(:cloud)
+        expect(preset_context.translations).to eq([:pl])
+        expect(preset_context.type).to eq(:classic)
       end
     end
 
     context 'with missing required parameters' do
-      let(:preset) do
-        instance_double(
-          CKEditor5::Rails::Presets::PresetBuilder,
-          to_h_with_overrides: { cdn: :cloud }
-        )
-      end
-
       before do
         allow(helper).to receive(:merge_with_editor_preset).and_return({})
       end
@@ -170,54 +148,24 @@ RSpec.describe CKEditor5::Rails::Cdn::Helpers do
       end
     end
 
-    context 'with empty hash from preset' do
-      let(:preset) do
-        instance_double(
-          CKEditor5::Rails::Presets::PresetBuilder,
-          to_h_with_overrides: {}
-        )
-      end
-
-      it 'raises error about missing version and type' do
-        expect { helper.ckeditor5_assets(preset: :default) }
-          .to raise_error(ArgumentError, /forgot to define version/)
+    context 'destructure non-matching preset override' do
+      before do
+        allow(CKEditor5::Rails::Engine).to receive(:find_preset).and_return(nil)
       end
-    end
-  end
 
-  context 'when overriding preset values with kwargs' do
-    let(:preset) do
-      CKEditor5::Rails::Presets::PresetBuilder.new do
-        version '34.1.0'
-        type :classic
-        translations :pl
-        cdn :cloud
-        license_key 'preset-license'
-        premium false
+      it 'raises error' do
+        expect { helper.ckeditor5_assets(preset: :invalid) }
+          .to raise_error(ArgumentError, /forgot to define your invalid preset/)
       end
     end
 
-    before do
-      allow(CKEditor5::Rails::Engine).to receive(:find_preset).and_return(preset)
-    end
-
-    it 'allows overriding preset values with kwargs' do
-      result = helper.send(:merge_with_editor_preset, :default, license_key: 'overridden-license')
-      expect(result).to include(license_key: 'overridden-license')
-    end
+    context 'with empty preset' do
+      let(:preset) { CKEditor5::Rails::Presets::PresetBuilder.new }
 
-    it 'preserves non-overridden preset values' do
-      result = helper.send(:merge_with_editor_preset, :default, license_key: 'overridden-license')
-      expect(result).to eq(
-        version: '34.1.0',
-        premium: false,
-        cdn: :cloud,
-        translations: [:pl],
-        license_key: 'overridden-license',
-        type: :classic,
-        ckbox: nil,
-        config: { plugins: [], toolbar: [] }
-      )
+      it 'raises error about missing version and type' do
+        expect { helper.ckeditor5_assets(preset: :default) }
+          .to raise_error(ArgumentError, /forgot to define version/)
+      end
     end
   end
 

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

@@ -65,6 +65,19 @@ RSpec.describe CKEditor5::Rails::Editor::Helpers::Editor do
       end.to raise_error(ArgumentError, /Cannot pass initial data and block/)
     end
 
+    context 'when language is present' do
+      it 'passes language to editor props' do
+        result = helper.ckeditor5_editor(language: 'pl')
+
+        expect(result).to include('config=')
+        config_attr = result.match(/config="([^"]+)"/)[1]
+        decoded_config = CGI.unescape_html(config_attr)
+        parsed_config = JSON.parse(decoded_config)
+
+        expect(parsed_config['language']).to eq({ 'ui' => 'pl' })
+      end
+    end
+
     context 'when automatic upgrades are enabled' do
       before do
         allow(preset).to receive(:automatic_upgrades?).and_return(true)

data/spec/lib/ckeditor5/rails/editor/props_spec.rb

@@ -45,6 +45,17 @@ RSpec.describe CKEditor5::Rails::Editor::Props do
       end
     end
 
+    context 'with language' do
+      subject(:props) { described_class.new(controller_context, type, config, language: 'pl') }
+
+      it 'includes language in config' do
+        config_json = props.to_attributes[:config]
+
+        expect(config_json).to include('language')
+        expect(JSON.parse(config_json)['language']).to eq({ 'ui' => 'pl' })
+      end
+    end
+
     context 'with license key' do
       let(:controller_context) do
         { bundle: double('Bundle', translations_scripts: []), license_key: 'ABC123' }

data/spec/lib/ckeditor5/rails/presets/preset_builder_spec.rb

@@ -70,6 +70,22 @@ RSpec.describe CKEditor5::Rails::Presets::PresetBuilder do
     end
   end
 
+  describe '#override' do
+    it 'returns a new instance with overridden values' do
+      builder.version '35.0.0'
+      builder.translations :en, :pl
+
+      overridden = builder.override do
+        version '36.0.0'
+        translations :de
+      end
+
+      expect(builder.version).to eq('35.0.0')
+      expect(overridden.version).to eq('36.0.0')
+      expect(overridden.translations).to eq([:de])
+    end
+  end
+
   describe 'configuration methods' do
     describe '#automatic_upgrades' do
       it 'enables automatic upgrades' do
@@ -266,35 +282,49 @@ RSpec.describe CKEditor5::Rails::Presets::PresetBuilder do
     end
   end
 
-  describe '#to_h_with_overrides' do
-    let(:builder) do
-      described_class.new do
-        version '35.0.0'
-        premium true
-        translations :en, :pl
-      end
+  describe '#merge_with_hash!' do
+    it 'merges hash with current configuration' do
+      builder.merge_with_hash!(version: '32.0.0', type: :inline)
+      expect(builder.version).to eq('32.0.0')
+      expect(builder.type).to eq(:inline)
     end
 
-    it 'returns hash with default values' do
-      result = builder.to_h_with_overrides
-      expect(result).to include(
-        version: '35.0.0',
-        premium: true,
-        translations: %i[en pl]
-      )
+    it 'returns self' do
+      expect(builder.merge_with_hash!(version: '35.0.0')).to eq(builder)
     end
 
-    it 'applies overrides' do
-      result = builder.to_h_with_overrides(
-        version: '36.0.0',
-        premium: false,
-        translations: [:en]
-      )
-      expect(result).to include(
-        version: '36.0.0',
-        premium: false,
-        translations: [:en]
-      )
+    it 'merges language configuration' do
+      builder.merge_with_hash!(language: :pl)
+      expect(builder.config[:language]).to eq({ ui: :pl, content: :pl })
+    end
+
+    it 'preserves existing values when not overridden' do
+      builder.version '34.0.0'
+      builder.translations :en, :pl
+      builder.premium true
+
+      builder.merge_with_hash!(type: :inline)
+
+      expect(builder.version).to eq('34.0.0')
+      expect(builder.translations).to eq(%i[en pl])
+      expect(builder.premium?).to be true
+    end
+
+    it 'merges ckbox configuration' do
+      builder.merge_with_hash!(ckbox: { version: '1.0.0', theme: :lark })
+      expect(builder.ckbox).to eq({ version: '1.0.0', theme: :lark })
+    end
+
+    it 'merges config options deeply' do
+      original_config = { plugins: [:Essentials], toolbar: { items: [:bold] } }
+      new_config = { menuBar: { isVisible: true } }
+
+      builder.merge_with_hash!(config: original_config)
+      builder.merge_with_hash!(config: new_config)
+
+      expect(builder.config[:plugins]).to eq([:Essentials])
+      expect(builder.config[:toolbar]).to eq({ items: [:bold] })
+      expect(builder.config[:menuBar]).to eq({ isVisible: true })
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ckeditor5
 version: !ruby/object:Gem::Version
-  version: 1.16.2
+  version: 1.17.1
 platform: ruby
 authors:
 - Mateusz Bagiński
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-11-23 00:00:00.000000000 Z
+date: 2024-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -82,6 +82,7 @@ files:
 - spec/e2e/features/context_spec.rb
 - spec/e2e/features/editor_types_spec.rb
 - spec/e2e/features/form_integration_spec.rb
+- spec/e2e/features/locale_spec.rb
 - spec/e2e/spec_helper.rb
 - spec/e2e/support/eventually.rb
 - spec/e2e/support/form_helpers.rb
@@ -139,6 +140,7 @@ test_files:
 - spec/e2e/features/context_spec.rb
 - spec/e2e/features/editor_types_spec.rb
 - spec/e2e/features/form_integration_spec.rb
+- spec/e2e/features/locale_spec.rb
 - spec/e2e/spec_helper.rb
 - spec/e2e/support/eventually.rb
 - spec/e2e/support/form_helpers.rb