rs-activeadmin-searchable_select 4.0.5

data/docs/upload-system.md

@@ -0,0 +1,225 @@
+# CKEditor5-Rails Upload System Documentation
+
+## Overview
+
+The CKEditor5-Rails gem implements a flexible image upload system that allows users to upload images directly from the editor to a server endpoint instead of embedding them as Base64. The system is designed to be backend-agnostic and can integrate with various storage solutions including ActiveStorage and Shrine.
+
+## Architecture
+
+### Core Components
+
+#### 1. SimpleUploadAdapter Plugin (`lib/ckeditor5/rails/plugins/simple_upload_adapter.rb`)
+
+The heart of the upload system is an inline JavaScript plugin that:
+- Extends CKEditor5's Plugin class
+- Requires the FileRepository plugin as a dependency
+- Implements the upload adapter factory pattern
+- Handles file uploads via XMLHttpRequest with progress tracking
+
+**Location**: `lib/ckeditor5/rails/plugins/simple_upload_adapter.rb`
+
+**Key Features**:
+- Async/await based upload handling
+- Progress tracking through XMLHttpRequest events
+- CSRF token integration for Rails security
+- Abort capability for cancelled uploads
+- JSON response parsing for uploaded file URLs
+
+#### 2. PropsInlinePlugin Base Class (`lib/ckeditor5/rails/editor/props_inline_plugin.rb`)
+
+The upload adapter extends this base class which:
+- Wraps JavaScript code in an async IIFE (Immediately Invoked Function Expression)
+- Supports optional code compression via Terser
+- Provides window-based plugin registration mechanism
+- Handles plugin initialization errors gracefully
+
+**Location**: `lib/ckeditor5/rails/editor/props_inline_plugin.rb`
+
+#### 3. Plugin Registration System (`lib/ckeditor5/rails/plugins.rb`)
+
+Central registry that:
+- Loads all core plugins including SimpleUploadAdapter
+- Manages plugin dependencies
+- Handles plugin patches and fixes
+
+**Location**: `lib/ckeditor5/rails/plugins.rb`
+
+## Configuration System
+
+### Preset Builder Integration (`lib/ckeditor5/rails/presets/preset_builder.rb`)
+
+The upload adapter is configured through the preset system:
+
+```ruby
+def simple_upload_adapter(upload_url = '/uploads', compress: !@disallow_inline_plugin_compression)
+  plugins do
+    remove(:Base64UploadAdapter)  # Remove default Base64 adapter
+  end
+  
+  plugin(Plugins::SimpleUploadAdapter.new(compress: compress))
+  configure(:simpleUpload, { uploadUrl: upload_url })
+end
+```
+
+**Location**: `lib/ckeditor5/rails/presets/preset_builder.rb:394-401`
+
+**Configuration Steps**:
+1. Removes the default Base64UploadAdapter plugin
+2. Adds the SimpleUploadAdapter plugin
+3. Configures the upload URL endpoint
+4. Optionally enables/disables JavaScript compression
+
+### Usage in Presets
+
+Upload functionality is enabled in presets via:
+
+```ruby
+# In preset definition
+simple_upload_adapter           # Uses default '/uploads' endpoint
+simple_upload_adapter '/custom'  # Custom endpoint
+```
+
+**Example Location**: `sandbox/config/initializers/ckeditor5.rb:82`
+
+## Frontend Implementation
+
+### Upload Flow
+
+1. **User Action**: User selects/pastes an image in the editor
+2. **Plugin Activation**: FileRepository triggers createUploadAdapter
+3. **Adapter Creation**: SimpleUploadAdapter creates an upload instance
+4. **FormData Preparation**: File wrapped in FormData with 'upload' field name
+5. **Security Headers**: 
+   - X-Requested-With: XMLHttpRequest
+   - X-CSRF-Token: Extracted from meta tag
+6. **Upload Process**:
+   - Progress events update loader.uploaded/uploadTotal
+   - Success (200-299): Parse JSON response for URL
+   - Error handling for failed/aborted uploads
+7. **Editor Update**: Returned URL replaces placeholder image
+
+### Response Format
+
+Server must return JSON with structure:
+```json
+{
+  "url": "https://example.com/uploads/image.jpg"
+}
+```
+
+## Integration Points
+
+### 1. Rails Controller
+
+The upload endpoint (not included in gem) should:
+- Accept POST requests to configured URL
+- Process multipart/form-data with 'upload' field
+- Store file using preferred backend (ActiveStorage, Shrine, etc.)
+- Return JSON with uploaded file URL
+- Handle CSRF token validation
+
+### 2. Helper Methods
+
+Upload configuration accessible via:
+- `ckeditor5_editor` helper in views
+- Preset configuration in initializers
+- Runtime configuration overrides
+
+**Location**: `lib/ckeditor5/rails/editor/helpers/editor_helpers.rb`
+
+### 3. Engine Registration
+
+Upload adapter available through:
+- Engine preset system
+- Direct plugin inclusion
+- Configuration DSL methods
+
+**Location**: `lib/ckeditor5/rails/engine.rb:83`
+
+## File Structure
+
+```
+lib/ckeditor5/rails/
+├── plugins/
+│   ├── simple_upload_adapter.rb    # Main upload adapter implementation
+│   └── ...
+├── editor/
+│   ├── props_inline_plugin.rb      # Base class for inline plugins
+│   └── helpers/
+│       └── editor_helpers.rb       # View helpers for editor
+├── presets/
+│   └── preset_builder.rb           # Configuration DSL with upload method
+└── engine.rb                        # Rails engine with upload registration
+```
+
+## Configuration Examples
+
+### Basic Setup
+
+```ruby
+CKEditor5::Rails.configure do
+  # Enable with default /uploads endpoint
+  simple_upload_adapter
+end
+```
+
+### Custom Endpoint
+
+```ruby
+CKEditor5::Rails.configure do
+  # Custom upload endpoint
+  simple_upload_adapter '/api/images/upload'
+end
+```
+
+### With Compression Disabled
+
+```ruby
+CKEditor5::Rails.configure do
+  # Disable JavaScript compression for debugging
+  simple_upload_adapter '/uploads', compress: false
+end
+```
+
+## Key Implementation Details
+
+### JavaScript Plugin Structure
+
+The plugin is written as an ES6 module that:
+1. Imports required CKEditor5 modules dynamically
+2. Returns a class extending Plugin
+3. Implements standard CKEditor5 plugin lifecycle
+4. Integrates with FileRepository for upload management
+
+### Security Considerations
+
+- CSRF token automatically extracted from Rails meta tag
+- XMLHttpRequest marked with X-Requested-With header
+- Server-side validation responsibility lies with implementer
+
+### Error Handling
+
+- Network errors caught and rejected with descriptive messages
+- HTTP status codes outside 200-299 range treated as errors
+- Upload abort capability for user cancellation
+
+## Backend Requirements
+
+To implement the upload endpoint:
+
+1. **Route Definition**: Add POST route to configured URL
+2. **File Processing**: Handle multipart upload with 'upload' parameter
+3. **Storage Backend**: Integrate with ActiveStorage, Shrine, or custom solution
+4. **Response Format**: Return JSON with 'url' key
+5. **Security**: Validate CSRF tokens and user permissions
+
+## Extension Points
+
+The system supports:
+- Multiple upload adapters via plugin system
+- Custom configuration through preset builder
+- Backend flexibility through endpoint abstraction
+- Compression toggle for development/production
+- Integration with various storage backends
+
+This architecture provides a clean separation between the editor frontend and storage backend, allowing developers to implement uploads using their preferred Rails patterns and storage solutions.

data/gemfiles/rails_7.x_active_admin_4.x.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activeadmin", "4.0.0.beta16"
+gem "rspec_junit_formatter", require: false
+gem "simplecov", require: false
+gem "simplecov-cobertura", require: false
+gem "rails", "~> 7.1"
+
+gemspec path: "../"

data/gemfiles/rails_7.x_active_admin_4.x.gemfile.lock

@@ -0,0 +1,371 @@
+PATH
+  remote: ..
+  specs:
+    rs-activeadmin-searchable_select (4.0.5)
+      activeadmin (~> 4.0.0.beta)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (7.1.5.2)
+      actionpack (= 7.1.5.2)
+      activesupport (= 7.1.5.2)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (7.1.5.2)
+      actionpack (= 7.1.5.2)
+      activejob (= 7.1.5.2)
+      activerecord (= 7.1.5.2)
+      activestorage (= 7.1.5.2)
+      activesupport (= 7.1.5.2)
+      mail (>= 2.7.1)
+      net-imap
+      net-pop
+      net-smtp
+    actionmailer (7.1.5.2)
+      actionpack (= 7.1.5.2)
+      actionview (= 7.1.5.2)
+      activejob (= 7.1.5.2)
+      activesupport (= 7.1.5.2)
+      mail (~> 2.5, >= 2.5.4)
+      net-imap
+      net-pop
+      net-smtp
+      rails-dom-testing (~> 2.2)
+    actionpack (7.1.5.2)
+      actionview (= 7.1.5.2)
+      activesupport (= 7.1.5.2)
+      nokogiri (>= 1.8.5)
+      racc
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    actiontext (7.1.5.2)
+      actionpack (= 7.1.5.2)
+      activerecord (= 7.1.5.2)
+      activestorage (= 7.1.5.2)
+      activesupport (= 7.1.5.2)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (7.1.5.2)
+      activesupport (= 7.1.5.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activeadmin (4.0.0.beta16)
+      arbre (~> 2.0)
+      csv
+      formtastic (>= 5.0)
+      formtastic_i18n (>= 0.7)
+      inherited_resources (~> 2.0)
+      kaminari (>= 1.2.1)
+      railties (>= 7.0)
+      ransack (>= 4.0)
+    activejob (7.1.5.2)
+      activesupport (= 7.1.5.2)
+      globalid (>= 0.3.6)
+    activemodel (7.1.5.2)
+      activesupport (= 7.1.5.2)
+    activerecord (7.1.5.2)
+      activemodel (= 7.1.5.2)
+      activesupport (= 7.1.5.2)
+      timeout (>= 0.4.0)
+    activestorage (7.1.5.2)
+      actionpack (= 7.1.5.2)
+      activejob (= 7.1.5.2)
+      activerecord (= 7.1.5.2)
+      activesupport (= 7.1.5.2)
+      marcel (~> 1.0)
+    activesupport (7.1.5.2)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      mutex_m
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    appraisal (2.5.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    arbre (2.2.0)
+      activesupport (>= 7.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.4.1)
+    bigdecimal (3.2.3)
+    builder (3.3.0)
+    capybara (3.40.0)
+      addressable
+      matrix
+      mini_mime (>= 0.1.3)
+      nokogiri (~> 1.11)
+      rack (>= 1.6.0)
+      rack-test (>= 0.6.3)
+      regexp_parser (>= 1.5, < 3.0)
+      xpath (~> 3.2)
+    capybara-playwright-driver (0.5.7)
+      addressable
+      capybara
+      playwright-ruby-client (>= 1.16.0)
+    combustion (1.5.0)
+      activesupport (>= 3.0.0)
+      railties (>= 3.0.0)
+      thor (>= 0.14.6)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.4)
+    crass (1.0.6)
+    csv (3.3.5)
+    database_cleaner-active_record (2.2.2)
+      activerecord (>= 5.a)
+      database_cleaner-core (~> 2.0)
+    database_cleaner-core (2.0.1)
+    date (3.4.1)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    drb (2.2.3)
+    erb (5.0.2)
+    erubi (1.13.1)
+    formtastic (5.0.0)
+      actionpack (>= 6.0.0)
+    formtastic_i18n (0.7.0)
+    git (1.19.1)
+      addressable (~> 2.8)
+      rchardet (~> 1.8)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    has_scope (0.8.2)
+      actionpack (>= 5.2)
+      activesupport (>= 5.2)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    inherited_resources (2.1.0)
+      actionpack (>= 7.0)
+      has_scope (>= 0.6)
+      railties (>= 7.0)
+      responders (>= 2)
+    io-console (0.8.1)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.13.2)
+    kaminari (1.2.2)
+      activesupport (>= 4.1.0)
+      kaminari-actionview (= 1.2.2)
+      kaminari-activerecord (= 1.2.2)
+      kaminari-core (= 1.2.2)
+    kaminari-actionview (1.2.2)
+      actionview
+      kaminari-core (= 1.2.2)
+    kaminari-activerecord (1.2.2)
+      activerecord
+      kaminari-core (= 1.2.2)
+    kaminari-core (1.2.2)
+    logger (1.7.0)
+    loofah (2.24.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    matrix (0.4.3)
+    mime-types (3.7.0)
+      logger
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2025.0902)
+    mini_mime (1.1.5)
+    minitest (5.25.5)
+    mutex_m (0.3.0)
+    net-imap (0.5.10)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.4)
+    nokogiri (1.18.9-x86_64-linux-gnu)
+      racc (~> 1.4)
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    playwright-ruby-client (1.55.0)
+      concurrent-ruby (>= 1.1.6)
+      mime-types (>= 3.0)
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.4.0)
+    propshaft (1.2.1)
+      actionpack (>= 7.0.0)
+      activesupport (>= 7.0.0)
+      rack
+    psych (5.2.6)
+      date
+      stringio
+    public_suffix (6.0.2)
+    puma (6.6.1)
+      nio4r (~> 2.0)
+    racc (1.8.1)
+    rack (3.2.1)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.2.1)
+      rack (>= 3)
+    rails (7.1.5.2)
+      actioncable (= 7.1.5.2)
+      actionmailbox (= 7.1.5.2)
+      actionmailer (= 7.1.5.2)
+      actionpack (= 7.1.5.2)
+      actiontext (= 7.1.5.2)
+      actionview (= 7.1.5.2)
+      activejob (= 7.1.5.2)
+      activemodel (= 7.1.5.2)
+      activerecord (= 7.1.5.2)
+      activestorage (= 7.1.5.2)
+      activesupport (= 7.1.5.2)
+      bundler (>= 1.15.0)
+      railties (= 7.1.5.2)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (7.1.5.2)
+      actionpack (= 7.1.5.2)
+      activesupport (= 7.1.5.2)
+      irb
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rainbow (2.2.2)
+      rake
+    rake (13.3.0)
+    ransack (4.3.0)
+      activerecord (>= 6.1.5)
+      activesupport (>= 6.1.5)
+      i18n
+    rchardet (1.9.0)
+    rdoc (6.14.2)
+      erb
+      psych (>= 4.0.0)
+    regexp_parser (2.11.2)
+    reline (0.6.2)
+      io-console (~> 0.5)
+    responders (3.1.1)
+      actionpack (>= 5.2)
+      railties (>= 5.2)
+    rexml (3.4.2)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-rails (6.1.5)
+      actionpack (>= 6.1)
+      activesupport (>= 6.1)
+      railties (>= 6.1)
+      rspec-core (~> 3.13)
+      rspec-expectations (~> 3.13)
+      rspec-mocks (~> 3.13)
+      rspec-support (~> 3.13)
+    rspec-support (3.13.5)
+    rspec_junit_formatter (0.6.0)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    rubocop (1.50.2)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.46.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    semmy (1.2.0)
+      git (~> 1.3)
+      rainbow (~> 2.1)
+      unindent (~> 1.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-cobertura (3.1.0)
+      rexml
+      simplecov (~> 0.19)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    sqlite3 (2.7.3-x86_64-linux-gnu)
+    stringio (3.1.7)
+    thor (1.4.0)
+    timeout (0.4.3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.6.0)
+    unindent (1.0)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    xpath (3.2.0)
+      nokogiri (~> 1.8)
+    zeitwerk (2.7.3)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  activeadmin (= 4.0.0.beta16)
+  appraisal (~> 2.2)
+  bundler (>= 1.5, < 3)
+  capybara (~> 3.39)
+  capybara-playwright-driver (~> 0.5)
+  combustion (~> 1.5)
+  database_cleaner-active_record (~> 2.1)
+  propshaft
+  puma (~> 6.0)
+  rails (~> 7.1)
+  rake
+  rs-activeadmin-searchable_select!
+  rspec-rails (~> 6.0)
+  rspec_junit_formatter
+  rubocop (~> 1.50.0)
+  semmy (~> 1.0)
+  simplecov
+  simplecov-cobertura
+  sqlite3 (~> 2.1)
+
+BUNDLED WITH
+   2.4.10

data/gemfiles/rails_8.x_active_admin_4.x.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activeadmin", "4.0.0.beta16"
+gem "rspec_junit_formatter", require: false
+gem "simplecov", require: false
+gem "simplecov-cobertura", require: false
+gem "rails", "~> 8.0"
+
+gemspec path: "../"