ckeditor5 1.19.4 → 1.20.0

data/lib/ckeditor5/rails/hooks/simple_form.rb

@@ -2,7 +2,46 @@
 
 module CKEditor5::Rails::Hooks
   module SimpleForm
+    # Custom input type for Simple Form integration with CKEditor 5.
+    # This class enables seamless integration with Simple Form, allowing use of CKEditor 5
+    # as a form input with all its features and configurations.
+    #
+    # @example Basic usage in a form
+    #   <%= simple_form_for @post do |f| %>
+    #     <%= f.input :content,
+    #       as: :ckeditor5,
+    #       input_html: { style: 'width: 600px' },
+    #       required: true
+    #     %>
+    #   <% end %>
+    #
+    # @example With custom preset and styling
+    #   <%= simple_form_for @post do |f| %>
+    #     <%= f.input :content,
+    #       as: :ckeditor5,
+    #       preset: :custom,
+    #       type: :inline,
+    #       input_html: {
+    #         style: 'width: 600px',
+    #         class: 'custom-editor',
+    #         initial_data: 'Hello!'
+    #       }
+    #     %>
+    #   <% end %>
+    #
+    # @example With validation and error handling
+    #   <%= simple_form_for @post do |f| %>
+    #     <%= f.input :content,
+    #       as: :ckeditor5,
+    #       required: true,
+    #       input_html: { style: 'width: 600px' },
+    #       error: 'Content cannot be blank'
+    #     %>
+    #   <% end %>
     class CKEditor5Input < ::SimpleForm::Inputs::Base
+      # Renders the CKEditor 5 input field
+      # @param wrapper_options [Hash] Options passed from the form wrapper
+      # @return [String] Rendered editor HTML
       def input(wrapper_options = nil)
         merged_input_options = merge_wrapper_options(input_html_options, wrapper_options)
         @builder.template.ckeditor5_editor(**editor_options(merged_input_options))
@@ -10,6 +49,9 @@ module CKEditor5::Rails::Hooks
 
       private
 
+      # Builds options hash for the editor
+      # @param merged_input_options [Hash] Combined input options
+      # @return [Hash] Options for CKEditor instance
       def editor_options(merged_input_options)
         {
           preset: input_options.fetch(:preset, :default),

data/lib/ckeditor5/rails/presets/concerns/configuration_methods.rb

@@ -5,6 +5,34 @@ require 'active_support'
 module CKEditor5::Rails
   module Presets
     module Concerns
+      # ConfigurationMethods provides functionality for configuring CKEditor 5 presets and instances.
+      #
+      # This module is included in preset builders and allows setting various configuration options
+      # for the editor.
+      #
+      # @example Basic configuration in preset
+      #   presets.define :custom do
+      #     configure :height, '400px'
+      #     configure :width, '600px'
+      #   end
+      #
+      # @example Complex configuration with nested options
+      #   presets.define :custom do
+      #     configure :image, {
+      #       toolbar: ['imageTextAlternative', 'imageStyle:inline'],
+      #       styles: ['alignLeft', 'alignCenter']
+      #     }
+      #   end
+      #
+      # @example Plugin-specific configuration
+      #   presets.define :custom do
+      #     configure :heading, {
+      #       options: [
+      #         { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
+      #         { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' }
+      #       ]
+      #     }
+      #   end
       module ConfigurationMethods
         extend ActiveSupport::Concern
 
@@ -12,6 +40,23 @@ module CKEditor5::Rails
           attr_reader :config
         end
 
+        # Sets a configuration value for a given key in the editor configuration.
+        #
+        # @param key [Symbol, String] The configuration key
+        # @param value [Object] The configuration value
+        #
+        # @example Setting simple configuration
+        #   configure :width, '500px'
+        #
+        # @example Setting plugin configuration
+        #   configure :toolbar, ['bold', 'italic', '|', 'undo', 'redo']
+        #
+        # @example Setting nested configuration
+        #   configure :image, {
+        #     styles: {
+        #       options: ['alignLeft', 'alignCenter']
+        #     }
+        #   }
         def configure(key, value)
           config[key] = value
         end

data/lib/ckeditor5/rails/presets/concerns/plugin_methods.rb

@@ -6,6 +6,10 @@ module CKEditor5::Rails
       module PluginMethods
         private
 
+        # Register a plugin in the editor configuration
+        #
+        # @param plugin_obj [Editor::PropsBasePlugin] Plugin instance to register
+        # @return [Editor::PropsBasePlugin] The registered plugin
         def register_plugin(plugin_obj)
           config[:plugins] << plugin_obj
           plugin_obj
@@ -13,19 +17,69 @@ module CKEditor5::Rails
 
         public
 
+        # Registers an external plugin loaded from a URL
+        #
+        # @param name [Symbol] Plugin name
+        # @param kwargs [Hash] Plugin options like :script, :import_as, :window_name, :stylesheets
+        # @example Load plugin from URL
+        #   external_plugin :MyPlugin, script: 'https://example.com/plugin.js'
+        # @example Load with import alias
+        #   external_plugin :MyPlugin,
+        #     script: 'https://example.com/plugin.js',
+        #     import_as: 'Plugin'
         def external_plugin(name, **kwargs)
           register_plugin(Editor::PropsExternalPlugin.new(name, **kwargs))
         end
 
+        # Registers an inline plugin with raw JavaScript code
+        #
+        # @param name [Symbol] Plugin name
+        # @param code [String] JavaScript code defining the plugin
+        # @example Define custom highlight plugin
+        #   inline_plugin :MyCustomPlugin, <<~JS
+        #     import { Plugin } from 'ckeditor5';
+        #
+        #     export default class MyCustomPlugin extends Plugin {
+        #       static get pluginName() {
+        #         return 'MyCustomPlugin';
+        #       }
+        #
+        #       init() {
+        #         // Plugin initialization code
+        #       }
+        #     }
+        #   JS
         def inline_plugin(name, code)
           register_plugin(Editor::PropsInlinePlugin.new(name, code))
         end
 
+        # Register a single plugin by name
+        #
+        # @param name [Symbol, Editor::PropsBasePlugin] Plugin name or instance
+        # @param kwargs [Hash] Plugin configuration options
+        # @example Register standard plugin
+        #   plugin :Bold
+        # @example Register premium plugin
+        #   plugin :RealTimeCollaboration, premium: true
+        # @example Register custom plugin
+        #   plugin :MyPlugin, import_name: 'my-custom-plugin'
         def plugin(name, **kwargs)
           premium(true) if kwargs[:premium] && respond_to?(:premium)
           register_plugin(PluginsBuilder.create_plugin(name, **kwargs))
         end
 
+        # Register multiple plugins and configure plugin settings
+        #
+        # @param names [Array<Symbol>] Plugin names to register
+        # @param kwargs [Hash] Shared plugin configuration
+        # @example Register multiple plugins
+        #   plugins :Bold, :Italic, :Underline
+        # @example Configure plugins with block
+        #   plugins do
+        #     remove :Heading
+        #     append :SelectAll, :RemoveFormat
+        #     prepend :SourceEditing
+        #   end
         def plugins(*names, **kwargs, &block)
           config[:plugins] ||= []
 

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

@@ -8,11 +8,28 @@ module CKEditor5::Rails::Presets
   class Manager
     attr_reader :presets
 
+    # Initializes a new Manager instance and sets up the default preset
     def initialize
       @presets = {}
       define_default_preset
     end
 
+    # Define a new preset configuration
+    #
+    # @param name [Symbol] Name of the preset
+    # @param inherit [Boolean] Whether to inherit from default preset
+    # @example Define custom preset inheriting from default
+    #   presets.define :custom do
+    #     menubar visible: false
+    #     toolbar :bold, :italic
+    #   end
+    # @example Define preset from scratch
+    #   presets.define :blank, inherit: false do
+    #     version '43.3.1'
+    #     gpl
+    #     type :classic
+    #   end
+    # @return [PresetBuilder] Created preset instance
     def define(name, inherit: true, &block)
       preset = if inherit && default.present?
                  default.clone
@@ -24,35 +41,66 @@ module CKEditor5::Rails::Presets
       @presets[name] = preset
     end
 
+    # Override existing preset configuration
+    #
+    # @param name [Symbol] Name of the preset to override
+    # @example Override existing preset
+    #   presets.override :custom do
+    #     menubar visible: false
+    #     toolbar do
+    #       remove :underline, :heading
+    #     end
+    #   end
     def override(name, &block)
       @presets[name].instance_eval(&block)
     end
 
     alias extend override
 
+    # Get the default preset configuration
+    # @return [PresetBuilder, nil] Default preset or nil if not defined
     def default
       @presets[:default]
     end
 
+    # Get a preset by name
+    # @param name [Symbol] Name of the preset
+    # @return [PresetBuilder, nil] Found preset or nil if not found
     def [](name)
       @presets[name]
     end
 
     private
 
+    # Defines the default preset with common editor settings
+    # @example Basic configuration
+    #   CKEditor5::Rails.configure do
+    #     presets.define :default do
+    #       version '43.3.1'
+    #       gpl
+    #       type :classic
+    #       menubar
+    #     end
+    #   end
     def define_default_preset
       define :default do
+        # Set default version from gem constant
         version CKEditor5::Rails::DEFAULT_CKEDITOR_VERSION
 
+        # Enable automatic version upgrades for security patches
         automatic_upgrades
+
+        # Use GPL license and classic editor type
         gpl
         type :classic
         menubar
 
+        # Configure default toolbar items
         toolbar :undo, :redo, :|, :heading, :|, :bold, :italic, :underline, :|,
                 :link, :insertImage, :mediaEmbed, :insertTable, :blockQuote, :|,
                 :bulletedList, :numberedList, :todoList, :outdent, :indent
 
+        # Configure default plugins
         plugins :AccessibilityHelp, :Autoformat, :AutoImage, :Autosave,
                 :BlockQuote, :Bold, :CloudServices,
                 :Essentials, :Heading, :ImageBlock, :ImageCaption, :ImageInline,
@@ -64,6 +112,7 @@ module CKEditor5::Rails::Presets
                 :TableColumnResize, :TableProperties, :TableToolbar,
                 :TextTransformation, :TodoList, :Underline, :Undo, :Base64UploadAdapter
 
+        # Configure default image toolbar
         configure :image, {
           toolbar: ['imageTextAlternative', 'imageStyle:inline', 'imageStyle:block', 'imageStyle:side']
         }

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

@@ -8,6 +8,11 @@ module CKEditor5::Rails
       @items = plugins
     end
 
+    # Creates a plugin instance from a name or returns the plugin if it's already a PropsBasePlugin
+    #
+    # @param name [Symbol, Editor::PropsBasePlugin] Plugin name or instance
+    # @param kwargs [Hash] Additional plugin configuration
+    # @return [Editor::PropsBasePlugin] Plugin instance
     def self.create_plugin(name, **kwargs)
       if name.is_a?(Editor::PropsBasePlugin)
         name
@@ -16,10 +21,27 @@ module CKEditor5::Rails
       end
     end
 
+    # Removes specified plugins from the editor configuration
+    #
+    # @param names [Array<Symbol>] Names of plugins to remove
+    # @example Remove plugins from configuration
+    #   plugins do
+    #     remove :Heading, :Link
+    #   end
     def remove(*names)
       names.each { |name| items.delete_if { |plugin| plugin.name == name } }
     end
 
+    # Prepends plugins to the beginning of the plugins list or before a specific plugin
+    #
+    # @param names [Array<Symbol>] Names of plugins to prepend
+    # @param before [Symbol, nil] Optional plugin name before which to insert new plugins
+    # @param kwargs [Hash] Additional plugin configuration
+    # @raise [ArgumentError] When the specified 'before' plugin is not found
+    # @example Prepend plugins to configuration
+    #   plugins do
+    #     prepend :Bold, :Italic, before: :Link
+    #   end
     def prepend(*names, before: nil, **kwargs)
       new_plugins = names.map { |name| self.class.create_plugin(name, **kwargs) }
 
@@ -33,6 +55,16 @@ module CKEditor5::Rails
       end
     end
 
+    # Appends plugins to the end of the plugins list or after a specific plugin
+    #
+    # @param names [Array<Symbol>] Names of plugins to append
+    # @param after [Symbol, nil] Optional plugin name after which to insert new plugins
+    # @param kwargs [Hash] Additional plugin configuration
+    # @raise [ArgumentError] When the specified 'after' plugin is not found
+    # @example Append plugins to configuration
+    #   plugins do
+    #     append :Bold, :Italic, after: :Link
+    #   end
     def append(*names, after: nil, **kwargs)
       new_plugins = names.map { |name| self.class.create_plugin(name, **kwargs) }
 

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

@@ -10,6 +10,12 @@ module CKEditor5::Rails
       include Concerns::ConfigurationMethods
       include Concerns::PluginMethods
 
+      # @example Basic initialization
+      #   PresetBuilder.new do
+      #     version '43.3.1'
+      #     gpl
+      #     type :classic
+      #   end
       def initialize(&block)
         @version = nil
         @premium = false
@@ -28,6 +34,9 @@ module CKEditor5::Rails
         instance_eval(&block) if block_given?
       end
 
+      # @example Copy preset and modify it
+      #   original = PresetBuilder.new
+      #   copied = original.initialize_copy(original)
       def initialize_copy(source)
         super
 
@@ -41,10 +50,14 @@ module CKEditor5::Rails
         )
       end
 
+      # Check if preset is using premium features
+      # @return [Boolean]
       def premium?
         @premium
       end
 
+      # Check if preset is using GPL license
+      # @return [Boolean]
       def gpl?
         license_key == 'GPL'
       end
@@ -55,12 +68,24 @@ module CKEditor5::Rails
         end
       end
 
+      # Create a new preset by overriding current configuration
+      # @example Override existing preset
+      #   preset.override do
+      #     menubar visible: false
+      #     toolbar do
+      #       remove :underline, :heading
+      #     end
+      #   end
+      # @return [PresetBuilder] New preset instance
       def override(&block)
         clone.tap do |preset|
           preset.instance_eval(&block)
         end
       end
 
+      # Merge preset with configuration hash
+      # @param overrides [Hash] Configuration options to merge
+      # @return [self]
       def merge_with_hash!(**overrides) # rubocop:disable Metrics/AbcSize
         @version = Semver.new(overrides[:version]) if overrides.key?(:version)
         @premium = overrides.fetch(:premium, premium)
@@ -76,12 +101,22 @@ module CKEditor5::Rails
         self
       end
 
+      # Set or get editable height in pixels
+      # @param height [Integer, nil] Height in pixels
+      # @example Set editor height to 300px
+      #   editable_height 300
+      # @return [Integer, nil] Current height value
       def editable_height(height = nil)
         return @editable_height if height.nil?
 
         @editable_height = height
       end
 
+      # Configure CKBox integration
+      # @param version [String, nil] CKBox version
+      # @param theme [Symbol] Theme name (:lark)
+      # @example Enable CKBox with custom version
+      #   ckbox '2.6.0', theme: :lark
       def ckbox(version = nil, theme: :lark)
         return @ckbox if version.nil?
 
@@ -91,6 +126,11 @@ module CKEditor5::Rails
         }
       end
 
+      # Set or get license key
+      # @param license_key [String, nil] License key
+      # @example Set commercial license
+      #   license_key 'your-license-key'
+      # @return [String, nil] Current license key
       def license_key(license_key = nil)
         return @license_key if license_key.nil?
 
@@ -99,23 +139,41 @@ module CKEditor5::Rails
         cdn(:cloud) unless gpl?
       end
 
+      # Set GPL license and disable premium features
+      # @example Enable GPL license
+      #   gpl
       def gpl
         license_key('GPL')
         premium(false)
       end
 
+      # Enable or check premium features
+      # @param premium [Boolean, nil] Enable/disable premium features
+      # @example Enable premium features
+      #   premium true
+      # @return [Boolean] Premium status
       def premium(premium = nil)
         return @premium if premium.nil?
 
         @premium = premium
       end
 
+      # Set or get translations
+      # @param translations [Array<Symbol>] Language codes
+      # @example Add Polish and Spanish translations
+      #   translations :pl, :es
+      # @return [Array<Symbol>] Current translations
       def translations(*translations)
         return @translations if translations.empty?
 
         @translations = translations
       end
 
+      # Set or get editor version
+      # @param version [String, nil] Editor version
+      # @example Set specific version
+      #   version '43.3.1'
+      # @return [String, nil] Current version
       def version(version = nil)
         return @version&.to_s if version.nil?
 
@@ -127,14 +185,29 @@ module CKEditor5::Rails
         end
       end
 
+      # Enable or disable automatic version upgrades
+      # @param enabled [Boolean] Enable/disable upgrades
+      # @example Enable automatic upgrades
+      #   automatic_upgrades enabled: true
       def automatic_upgrades(enabled: true)
         @automatic_upgrades = enabled
       end
 
+      # Check if automatic upgrades are enabled
+      # @return [Boolean]
       def automatic_upgrades?
         @automatic_upgrades
       end
 
+      # Configure CDN source
+      # @param cdn [Symbol, nil] CDN name or custom block
+      # @example Use jsDelivr CDN
+      #   cdn :jsdelivr
+      # @example Custom CDN configuration
+      #   cdn do |bundle, version, path|
+      #     "https://custom-cdn.com/#{bundle}@#{version}/#{path}"
+      #   end
+      # @return [Symbol, Proc] Current CDN configuration
       def cdn(cdn = nil, &block)
         return @cdn if cdn.nil? && block.nil?
 
@@ -150,6 +223,12 @@ module CKEditor5::Rails
         end
       end
 
+      # Set or get editor type
+      # @param type [Symbol, nil] Editor type (:classic, :inline, :balloon, :decoupled)
+      # @example Set editor type to inline
+      #   type :inline
+      # @raise [ArgumentError] If invalid type provided
+      # @return [Symbol] Current editor type
       def type(type = nil)
         return @type if type.nil?
         raise ArgumentError, "Invalid editor type: #{type}" unless Editor::Props.valid_editor_type?(type)
@@ -157,16 +236,33 @@ module CKEditor5::Rails
         @type = type
       end
 
+      # Configure menubar visibility
+      # @param visible [Boolean] Show/hide menubar
+      # @example Hide menubar
+      #   menubar visible: false
       def menubar(visible: true)
         config[:menuBar] = {
           isVisible: visible
         }
       end
 
+      # Check if menubar is visible
+      # @return [Boolean]
       def menubar?
         config.dig(:menuBar, :isVisible) || false
       end
 
+      # Configure toolbar items and grouping
+      # @param items [Array<Symbol>] Toolbar items
+      # @param should_group_when_full [Boolean] Enable grouping
+      # @example Configure toolbar items
+      #   toolbar :bold, :italic, :|, :link
+      # @example Configure with block
+      #   toolbar do
+      #     append :selectAll
+      #     remove :heading
+      #   end
+      # @return [ToolbarBuilder] Toolbar configuration
       def toolbar(*items, should_group_when_full: true, &block)
         if @config[:toolbar].blank? || !items.empty?
           @config[:toolbar] = {
@@ -180,10 +276,20 @@ module CKEditor5::Rails
         builder
       end
 
+      # Check if language is configured
+      # @return [Boolean]
       def language?
         config[:language].present?
       end
 
+      # Configure editor language
+      # @param ui [Symbol, nil] UI language code
+      # @param content [Symbol] Content language code
+      # @example Set Polish UI and content language
+      #   language :pl
+      # @example Different UI and content languages
+      #   language :pl, content: :en
+      # @return [Hash, nil] Language configuration
       def language(ui = nil, content: ui) # rubocop:disable Naming/MethodParameterName
         return config[:language] if ui.nil?
 
@@ -195,6 +301,10 @@ module CKEditor5::Rails
         }
       end
 
+      # Configure simple upload adapter
+      # @param upload_url [String] Upload endpoint URL
+      # @example Enable upload adapter
+      #   simple_upload_adapter '/uploads'
       def simple_upload_adapter(upload_url = '/uploads')
         plugins do
           remove(:Base64UploadAdapter)
@@ -204,6 +314,13 @@ module CKEditor5::Rails
         configure(:simpleUpload, { uploadUrl: upload_url })
       end
 
+      # Configure WProofreader plugin
+      # @param version [String, nil] Plugin version
+      # @param cdn [String, nil] CDN URL
+      # @param config [Hash] Plugin configuration
+      # @example Basic configuration
+      #   wproofreader serviceId: 'your-service-ID',
+      #              srcUrl: 'https://svc.webspellchecker.net/spellcheck31/wscbundle/wscbundle.js'
       def wproofreader(version: nil, cdn: nil, **config)
         configure :wproofreader, config
         plugins do

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

@@ -8,10 +8,30 @@ module CKEditor5::Rails::Presets
       @items = items
     end
 
+    # Remove items from the editor toolbar.
+    #
+    # @param removed_items [Array<Symbol>] Toolbar items to be removed
+    # @example Remove items from toolbar
+    #   toolbar do
+    #     remove :underline, :heading
+    #   end
     def remove(*removed_items)
       removed_items.each { |item| items.delete(item) }
     end
 
+    # Prepend items to the editor toolbar.
+    #
+    # @param prepended_items [Array<Symbol>] Toolbar items to be prepended
+    # @param before [Symbol, nil] Optional item before which to insert new items
+    # @example Prepend items to toolbar
+    #   toolbar do
+    #     prepend :selectAll, :|, :selectAll, :selectAll
+    #   end
+    # @example Insert items before specific item
+    #   toolbar do
+    #     prepend :selectAll, before: :bold
+    #   end
+    # @raise [ArgumentError] When the specified 'before' item is not found
     def prepend(*prepended_items, before: nil)
       if before
         index = items.index(before)
@@ -23,6 +43,19 @@ module CKEditor5::Rails::Presets
       end
     end
 
+    # Append items to the editor toolbar.
+    #
+    # @param appended_items [Array<Symbol>] Toolbar items to be appended
+    # @param after [Symbol, nil] Optional item after which to insert new items
+    # @example Append items to toolbar
+    #   toolbar do
+    #     append :selectAll, :|, :selectAll, :selectAll
+    #   end
+    # @example Insert items after specific item
+    #   toolbar do
+    #     append :selectAll, after: :bold
+    #   end
+    # @raise [ArgumentError] When the specified 'after' item is not found
     def append(*appended_items, after: nil)
       if after
         index = items.index(after)

data/lib/ckeditor5/rails/version.rb

@@ -2,7 +2,7 @@
 
 module CKEditor5
   module Rails
-    VERSION = '1.19.4'
+    VERSION = '1.20.0'
 
     DEFAULT_CKEDITOR_VERSION = '43.3.1'
   end

data/spec/e2e/features/editor_types_spec.rb

@@ -153,7 +153,7 @@ RSpec.describe 'CKEditor5 Types Integration', type: :feature, js: true do
         container.appendChild(newEditable);
       JS
 
-      sleep 0.1 # Wait for component initialization
+      sleep 1 # Wait for component initialization
 
       # Find and interact with new editable
       new_editable = find("[name='new-root']")