ckeditor5 1.21.0 → 1.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c524ae4eac93eeecf2e8aa8905044faeb0d3d1496e418f22c7abe3863f0538e3
-  data.tar.gz: faf447ab629a6a2ed95106461d2bcc6f4a75aef14e9e6e3b4c0da0cfcc2f7dd4
+  metadata.gz: 541773f43272493bbe29d3baf236cab3e85231f03b31c5d070b4917e6ecdea26
+  data.tar.gz: cb06989fd313768d6c1a5990f3dd49525fd1482b29a6b542c6d2778092eb3ad5
 SHA512:
-  metadata.gz: 83c7332860095fbfdb127a3202a1c38ac2383f671e828a9258ed01e0daff1f232583d77ed3b17badf467f65999c1bc97a068f35df915cd1eb35ef4ee54f569cc
-  data.tar.gz: 54bef9bf69740d134937aa5e6dd16d7ca8190a5da4fb36dde81db695ab571449036f9628c88321f2c12dbc6092b3adc6a9173ded26d363694686eaec5f3e71b4
+  metadata.gz: 5855d32cb3fcfd5da47b650683c215bda3dc1842f8e9d10af599eecec515d00ca120adc0be299d6410c5bd5a12df7d8df6c4c49b0d0d5d6477e65ccb3841a99a
+  data.tar.gz: 437632ab7d5599ddcd452b3dfefa218d2541db59896c50cba8ade94081c40ac4c9a9e144c82daa684174f88d50ac300d341eae07e5d675fe6a90f7ef15d667db

data/README.md

@@ -610,6 +610,39 @@ CKEditor5::Rails.configure do
   end
 end
 ```
+
+If you want to append groups of items, you can use the `group` method:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails.configure do
+  # ... other configuration
+
+  toolbar do
+    group :text_formatting, label: 'Text Formatting', icon: 'threeVerticalDots' do
+      append :bold, :italic, :underline, :strikethrough, separator,
+             :subscript, :superscript, :removeFormat
+    end
+  end
+end
+```
+
+If you want add new line or the separator, you can use the `break_line` or `separator` methods:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails.configure do
+  # ... other configuration
+
+  toolbar do
+    append :bold, break_line
+    append separator, :italic
+  end
+end
+```
+
 </details>
 
 #### `menubar(visible: true)` method

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

@@ -1,13 +1,46 @@
 # frozen_string_literal: true
 
 module CKEditor5::Rails::Presets
+  # Builder class for configuring CKEditor5 toolbar items.
+  #
+  # @example Basic toolbar configuration
+  #   toolbar = ToolbarBuilder.new([:bold, :italic])
+  #   toolbar.append(:link)
+  #   toolbar.prepend(:heading)
   class ToolbarBuilder
     attr_reader :items
 
+    # Initialize a new toolbar builder with given items.
+    #
+    # @param items [Array<Symbol>] Initial toolbar items
+    # @example Create new toolbar
+    #   ToolbarBuilder.new([:bold, :italic, :|, :link])
     def initialize(items)
       @items = items
     end
 
+    # Returns toolbar line break symbol
+    #
+    # @return [Symbol] Line break symbol (-)
+    # @example Add line break to toolbar
+    #   toolbar do
+    #     append :bold, break_line, :italic
+    #   end
+    def break_line
+      :-
+    end
+
+    # Returns toolbar separator symbol
+    #
+    # @return [Symbol] Separator symbol (|)
+    # @example Add separator to toolbar
+    #   toolbar do
+    #     append :bold, separator, :italic
+    #   end
+    def separator
+      :|
+    end
+
     # Remove items from the editor toolbar.
     #
     # @param removed_items [Array<Symbol>] Toolbar items to be removed
@@ -16,7 +49,9 @@ module CKEditor5::Rails::Presets
     #     remove :underline, :heading
     #   end
     def remove(*removed_items)
-      removed_items.each { |item| items.delete(item) }
+      items.delete_if do |existing_item|
+        removed_items.any? { |item_to_remove| item_matches?(existing_item, item_to_remove) }
+      end
     end
 
     # Prepend items to the editor toolbar.
@@ -34,7 +69,7 @@ module CKEditor5::Rails::Presets
     # @raise [ArgumentError] When the specified 'before' item is not found
     def prepend(*prepended_items, before: nil)
       if before
-        index = items.index(before)
+        index = find_item_index(before)
         raise ArgumentError, "Item '#{before}' not found in array" unless index
 
         items.insert(index, *prepended_items)
@@ -58,7 +93,7 @@ module CKEditor5::Rails::Presets
     # @raise [ArgumentError] When the specified 'after' item is not found
     def append(*appended_items, after: nil)
       if after
-        index = items.index(after)
+        index = find_item_index(after)
         raise ArgumentError, "Item '#{after}' not found in array" unless index
 
         items.insert(index + 1, *appended_items)
@@ -66,5 +101,84 @@ module CKEditor5::Rails::Presets
         items.push(*appended_items)
       end
     end
+
+    # Find group by name in toolbar items
+    #
+    # @param name [Symbol] Group name to find
+    # @return [ToolbarGroupItem, nil] Found group or nil
+    def find_group(name)
+      items.find { |item| item.is_a?(ToolbarGroupItem) && item.name == name }
+    end
+
+    # Remove group by name from toolbar items
+    #
+    # @param name [Symbol] Group name to remove
+    def remove_group(name)
+      items.delete_if { |item| item.is_a?(ToolbarGroupItem) && item.name == name }
+    end
+
+    # Create and add new group to toolbar
+    #
+    # @param name [Symbol] Group name
+    # @param options [Hash] Group options (label:, icons:)
+    # @param block [Proc] Configuration block
+    # @return [ToolbarGroupItem] Created group
+    def group(name, **options, &block)
+      group = ToolbarGroupItem.new(name, [], **options)
+      group.instance_eval(&block) if block_given?
+      items << group
+      group
+    end
+
+    private
+
+    # Find index of an item or group by name
+    #
+    # @param item [Symbol] Item or group name to find
+    # @return [Integer, nil] Index of the found item or nil
+    def find_item_index(item)
+      items.find_index { |existing_item| item_matches?(existing_item, item) }
+    end
+
+    # Checks if the existing item matches the given item or group name
+    #
+    # @param existing_item [Symbol, ToolbarGroupItem] Item to check
+    # @param item [Symbol] Item or group name to match against
+    # @return [Boolean] true if items match, false otherwise
+    # @example Check if items match
+    #   item_matches?(:bold, :bold)           # => true
+    #   item_matches?(group(:text), :text)    # => true
+    def item_matches?(existing_item, item)
+      if existing_item.is_a?(ToolbarGroupItem)
+        existing_item.name == item
+      else
+        existing_item == item
+      end
+    end
+  end
+
+  # Builder class for configuring CKEditor5 toolbar groups.
+  # Allows creating named groups of toolbar items with optional labels and icons.
+  #
+  # @example Creating a text formatting group
+  #   group = ToolbarGroupItem.new(:text_formatting, [:bold, :italic], label: 'Text')
+  #   group.append(:underline)
+  class ToolbarGroupItem < ToolbarBuilder
+    attr_reader :name, :label, :icon
+
+    # Initialize a new toolbar group item.
+    #
+    # @param name [Symbol] Name of the toolbar group
+    # @param items [Array<Symbol>, ToolbarBuilder] Items to be included in the group
+    # @param label [String, nil] Optional label for the group
+    # @param icon [String, nil] Optional icon for the group
+    # @example Create a new toolbar group
+    #   ToolbarGroupItem.new(:text, [:bold, :italic], label: 'Text formatting')
+    def initialize(name, items = [], label: nil, icon: nil)
+      super(items)
+      @name = name
+      @label = label
+      @icon = icon
+    end
   end
 end

data/lib/ckeditor5/rails/version.rb

@@ -2,7 +2,7 @@
 
 module CKEditor5
   module Rails
-    VERSION = '1.21.0'
+    VERSION = '1.22.0'
 
     DEFAULT_CKEDITOR_VERSION = '44.0.0'
   end

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

@@ -67,4 +67,123 @@ RSpec.describe CKEditor5::Rails::Presets::ToolbarBuilder do
       end
     end
   end
+
+  describe '#break_line' do
+    it 'returns line break symbol' do
+      expect(builder.break_line).to eq(:-)
+    end
+  end
+
+  describe '#separator' do
+    it 'returns separator symbol' do
+      expect(builder.separator).to eq(:|)
+    end
+  end
+
+  describe '#group' do
+    it 'creates and adds a new group' do
+      builder.group(:text, label: 'Text') do
+        append(:bold, :italic)
+      end
+
+      group = builder.items.last
+      expect(group).to be_a(CKEditor5::Rails::Presets::ToolbarGroupItem)
+      expect(group.name).to eq(:text)
+      expect(group.items).to eq(%i[bold italic])
+      expect(group.label).to eq('Text')
+    end
+
+    it 'creates group without configuration block' do
+      group = builder.group(:text, label: 'Text')
+
+      expect(group).to be_a(CKEditor5::Rails::Presets::ToolbarGroupItem)
+      expect(group.items).to be_empty
+    end
+  end
+
+  describe '#find_group' do
+    it 'returns group by name' do
+      builder.group(:text, label: 'Text')
+      builder.group(:formatting, label: 'Format')
+
+      group = builder.find_group(:formatting)
+      expect(group).to be_a(CKEditor5::Rails::Presets::ToolbarGroupItem)
+      expect(group.name).to eq(:formatting)
+    end
+
+    it 'returns nil when group not found' do
+      expect(builder.find_group(:nonexistent)).to be_nil
+    end
+  end
+
+  describe '#remove_group' do
+    it 'removes group by name' do
+      builder.group(:text, label: 'Text')
+      builder.group(:formatting, label: 'Format')
+
+      builder.remove_group(:text)
+      expect(builder.find_group(:text)).to be_nil
+      expect(builder.find_group(:formatting)).to be_present
+    end
+
+    it 'ignores non-existent groups' do
+      builder.group(:text, label: 'Text')
+
+      expect { builder.remove_group(:nonexistent) }.not_to(change { builder.items.count })
+    end
+  end
+
+  describe 'interacting with groups' do
+    let(:text_group) do
+      builder.group(:text, label: 'Text') do
+        append(:bold, :italic)
+      end
+    end
+
+    before do
+      text_group
+    end
+
+    it 'prepends items before group' do
+      builder.prepend(:undo, :redo, before: :text)
+      expect(builder.items.map { |i| i.is_a?(CKEditor5::Rails::Presets::ToolbarGroupItem) ? i.name : i })
+        .to eq(%i[bold italic | link undo redo text])
+    end
+
+    it 'appends items after group' do
+      builder.append(:undo, :redo, after: :text)
+      expect(builder.items.map { |i| i.is_a?(CKEditor5::Rails::Presets::ToolbarGroupItem) ? i.name : i })
+        .to eq(%i[bold italic | link text undo redo])
+    end
+
+    it 'removes group using remove method' do
+      builder.remove(:text)
+      expect(builder.items).to eq(%i[bold italic | link])
+    end
+  end
+end
+
+RSpec.describe CKEditor5::Rails::Presets::ToolbarGroupItem do
+  let(:items) { %i[bold italic] }
+  let(:group) { described_class.new(:formatting, items, label: 'Format', icon: 'format') }
+
+  describe '#initialize' do
+    it 'creates a group with given parameters' do
+      expect(group.name).to eq(:formatting)
+      expect(group.items).to eq(items)
+      expect(group.label).to eq('Format')
+      expect(group.icon).to eq('format')
+    end
+  end
+
+  it 'inherits toolbar manipulation methods' do
+    group.append(:underline)
+    expect(group.items).to eq(%i[bold italic underline])
+
+    group.prepend(:heading)
+    expect(group.items).to eq(%i[heading bold italic underline])
+
+    group.remove(:italic)
+    expect(group.items).to eq(%i[heading bold underline])
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ckeditor5
 version: !ruby/object:Gem::Version
-  version: 1.21.0
+  version: 1.22.0
 platform: ruby
 authors:
 - Mateusz Bagiński
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-12-03 00:00:00.000000000 Z
+date: 2024-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails