activeadmin-tom_select 4.1.0

data/docs/update-tom-select.md

@@ -0,0 +1,184 @@
+# Tom Select Migration Summary
+
+## Overview
+We successfully migrated ActiveAdmin Searchable Select from Select2 (jQuery-based) to Tom Select (vanilla JS, TypeScript-ready) with Tailwind CSS 4 support.
+
+## Key Changes Made
+
+### 1. Package Dependencies
+**Removed:**
+- `jquery` peer dependency
+- `select2` peer dependency
+
+**Added:**
+- `tom-select: ^2.4.3` peer dependency
+
+### 2. JavaScript Changes
+
+#### `/src/index.js`
+- Complete rewrite without jQuery dependency
+- Uses native `fetch()` for AJAX requests
+- Tom Select initialization with proper option mapping
+- Handles Select2 → Tom Select option conversion (id/text → valueField/labelField)
+
+#### Removed Legacy Files:
+- `/src/searchable_select/init.js` - Legacy compatibility file removed
+- `/spec/internal/inject-jquery.js` - jQuery injection hack removed
+- `/spec/internal/build_activeadmin_css.js` - Old CSS build hack removed
+
+### 3. CSS/Styling Changes
+
+#### New Files Created:
+- `/src/tom-select-tailwind.css` - Complete Tom Select styles with Tailwind classes (consolidated single file)
+
+#### Package Exports Updated:
+```json
+"exports": {
+  "./tom-select-tailwind": "./src/tom-select-tailwind.css"
+}
+```
+
+#### Removed Files:
+- `/src/searchable_select.css` - Consolidated into tom-select-tailwind.css
+- All legacy Select2 CSS imports
+
+### 4. Build Process (Tailwind 3)
+
+#### New Test App Structure:
+```
+/spec/internal/
+├── tailwind.config.js                   # Tailwind 3 config
+├── app/assets/stylesheets/
+│   └── active_admin.tailwind.css        # Main CSS entry with Tom Select styles
+├── build-css.js                         # Node script for CSS build
+├── esbuild.config.js                    # JavaScript build config
+└── package.json                         # Simplified scripts
+```
+
+#### Build Commands:
+- `npm run build:css` → Runs Tailwind CSS via `build-css.js`
+- `npm run build:js` → Runs esbuild for JavaScript bundling
+- `npm run build` → Builds both JS and CSS
+
+#### CSS Build Process Fix:
+- Integrated comprehensive ActiveAdmin styles from docs/tailwind-4 setup
+- Included all ActiveAdmin component styles (panels, data tables, filters, forms, etc.)
+- Tom Select styles are imported at the end of the CSS file
+- All styles are properly processed by Tailwind CSS and included in the final build
+- Fixed styling issues that were breaking ActiveAdmin UI components
+
+### 5. Test Updates
+
+#### CSS Class Changes:
+| Select2 | Tom Select |
+|---------|------------|
+| `.select2-container` | `.ts-wrapper` or `.ts-control` |
+| `.select2-dropdown` | `.ts-dropdown` |
+| `.select2-results__option` | `.ts-dropdown .option` |
+| `.select2-selection` | `.ts-control .item` |
+| `.select2-search__field` | `.ts-control input` |
+
+#### Helper Method Updates in Tests:
+- `expand_select_box`: Now clicks `.ts-control`
+- `enter_search_term`: Targets `.ts-control input`
+- `select_box_items`: Finds `.ts-dropdown .option`
+- `finished_all_ajax_requests`: No longer uses jQuery.active
+
+### 6. Documentation Structure
+
+#### Example Files (with credits):
+`/docs/tailwind-4/` - Example Tailwind 4 setup files
+- Credit: https://gist.github.com/amkisko/af1b2f7dc4f0f941437ea16400277864
+
+### 7. Migration Path for Users
+
+Users will need to:
+1. Update their `Gemfile` to use the new version
+2. Remove jQuery and Select2 dependencies
+3. Add Tom Select dependency: `npm install tom-select@^2.4.3`
+4. Update their CSS imports to use Tom Select styles
+5. If using Tailwind, import our tom-select-tailwind styles
+6. Update any custom JavaScript that referenced Select2 APIs
+
+### 8. Breaking Changes
+
+1. **No jQuery Required**: Apps no longer need jQuery for searchable selects
+2. **CSS Classes Changed**: All Select2 classes replaced with Tom Select equivalents
+3. **JavaScript API Different**: Tom Select has different initialization and options
+4. **Legacy init.js Removed**: No backward compatibility layer
+
+### 9. Benefits of Migration
+
+1. **No jQuery Dependency**: Reduces bundle size significantly
+2. **Modern JavaScript**: ES6+ modules, TypeScript support
+3. **Better Performance**: Tom Select is lighter and faster
+4. **Tailwind 4 Ready**: Native Tailwind utility classes
+5. **Future-Proof**: Active development, modern architecture
+
+### 10. Files to Commit
+
+**Modified:**
+- `/package.json` - Updated dependencies and exports
+- `/src/index.js` - Rewritten for Tom Select
+- `/spec/features/*.rb` - Updated test selectors
+- `/spec/internal/package.json` - Removed jQuery, added Tom Select
+- `/spec/internal/app/js/active_admin.js` - Tom Select import
+
+**Created:**
+- `/src/tom-select-tailwind.css`
+- `/src/searchable_select.css`
+- `/spec/internal/config/tailwind-active_admin.config.js`
+- `/spec/internal/app/assets/stylesheets/active_admin.tailwind.css`
+- `/spec/internal/lib/tasks/active_admin.rake`
+
+**Deleted:**
+- `/src/searchable_select/` directory
+- `/spec/internal/inject-jquery.js`
+- `/spec/internal/build_activeadmin_css.js`
+- `/spec/internal/tailwind-active_admin.config.js` (old location)
+
+### 11. Testing Status
+
+✅ **Tests Fixed and Working:**
+- All JavaScript initialization tests passing
+- Tom Select properly initializes in test environment
+- Clear button functionality working for all searchable selects
+- Assets properly served in test environment
+
+**Test Environment Setup:**
+- Assets must be built: `npm run build:js` and `bundle exec rake active_admin:build`
+- Assets copied to public directory for test environment: 
+  ```bash
+  mkdir -p public/javascripts public/stylesheets
+  cp app/assets/builds/active_admin.js public/javascripts/
+  cp app/assets/builds/active_admin.css public/stylesheets/
+  ```
+- Tests use Playwright driver for modern JavaScript support
+
+**Remaining Test Issues (4 failures):**
+- AJAX options not loading properly in some integration tests
+- Dropdown visibility detection needs adjustment for Tom Select
+- Search input focus/activation needs refinement
+
+### 12. Key Implementation Details
+
+#### Clear Button Feature:
+- All searchable selects are clearable by default
+- Implemented via `data-clearable="true"` attribute
+- Tom Select's `clear_button` plugin automatically added
+- Clear button positioned at `right: 2rem` for better UX
+- Can be disabled by setting `clearable: false` in Ruby options
+
+#### JavaScript Module Export:
+- Main module exports both `setupAutoInit` and `initSearchableSelects`
+- Functions made globally available in test environment via `window` object
+- Auto-initialization on DOMContentLoaded, Turbo load, and has_many_add events
+
+### 13. Next Steps
+
+1. ✅ Complete test fixes for remaining failures (mostly done)
+2. Update README.md with new installation instructions
+3. Create migration guide at `/docs/guide-update-your-app.md`
+4. Version bump to 5.0.0 (major version due to breaking changes)
+5. Test with real ActiveAdmin applications
+6. Consider adding TypeScript definitions for better IDE support

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,10 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activeadmin", "4.0.0.beta16"
+gem "devise", "~> 4.9", group: :test
+gem "propshaft", "~> 1.2", group: :test
+gem "rails", "~> 7.1"
+
+gemspec name: "activeadmin-tom_select", path: "../"