activeadmin-tom_select 4.1.0 → 4.1.2

data/docs/update-tom-select.md

@@ -1,184 +1,348 @@
-# Tom Select Migration Summary
+# Tom Select Migration Guide for ActiveAdmin 4
 
 ## Overview
-We successfully migrated ActiveAdmin Searchable Select from Select2 (jQuery-based) to Tom Select (vanilla JS, TypeScript-ready) with Tailwind CSS 4 support.
+This guide documents the complete migration from ActiveAdmin Searchable Select (Select2-based) to Tom Select (vanilla JS, no jQuery) with Tailwind CSS 4 support.
 
-## Key Changes Made
+## Key Benefits of Migration
 
-### 1. Package Dependencies
-**Removed:**
-- `jquery` peer dependency
-- `select2` peer dependency
+1. **No jQuery Dependency**: Tom Select is pure vanilla JavaScript, reducing bundle size
+2. **Modern JavaScript**: ES6+ modules, better performance
+3. **ActiveAdmin 4 Compatible**: Full support for latest ActiveAdmin
+4. **Smaller Bundle**: Removed jQuery and Select2 dependencies
 
-**Added:**
-- `tom-select: ^2.4.3` peer dependency
+## Installation Steps
 
-### 2. JavaScript Changes
+### 1. Update Gemfile
 
-#### `/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)
+```ruby
+# Remove old gem
+# gem 'rs-activeadmin-searchable_select', github: 'glebtv/activeadmin-searchable_select'
 
-#### 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
+# Add new gem (from RubyGems)
+gem 'activeadmin-tom_select'
+```
 
-#### New Files Created:
-- `/src/tom-select-tailwind.css` - Complete Tom Select styles with Tailwind classes (consolidated single file)
+### 2. Update package.json
 
-#### Package Exports Updated:
 ```json
-"exports": {
-  "./tom-select-tailwind": "./src/tom-select-tailwind.css"
+{
+  "dependencies": {
+    // Remove these:
+    // "jquery": "^3.7.1",
+    // "select2": "^4.1.0-rc.0",
+    // "@rocket-sensei/activeadmin-searchable_select": "^4.0.1",
+
+    // Add these:
+    "tom-select": "^2.4.3",
+    "activeadmin-tom_select": "^4.1.0"
+  }
 }
 ```
 
-#### Removed Files:
-- `/src/searchable_select.css` - Consolidated into tom-select-tailwind.css
-- All legacy Select2 CSS imports
+### 3. Update JavaScript (app/js/active_admin.js)
+
+```javascript
+// Import ActiveAdmin core first - includes all features and Rails UJS
+import "@activeadmin/activeadmin";
+
+// Import Tom Select
+import TomSelect from 'tom-select';
+window.TomSelect = TomSelect;
+
+// Import and setup ActiveAdmin Tom Select
+import { setupAutoInit, initSearchableSelects } from 'activeadmin-tom_select';
+window.initSearchableSelects = initSearchableSelects;
+setupAutoInit();
+
+console.log('ActiveAdmin loaded with Tom Select');
+```
+
+**Important**: Do NOT include jQuery - it's no longer needed!
+
+### 4. Configure CSS (app/assets/stylesheets/active_admin.tailwind.css)
+
+**CRITICAL**: Use Tailwind's @import syntax instead of @tailwind directives when importing vendor CSS:
+
+```css
+/* Use @import syntax for proper processing order */
+@import "tailwindcss/base";
+@import "tailwindcss/components";
+@import "tailwindcss/utilities";
+
+/* Import vendor CSS */
+@import 'tom-select/dist/css/tom-select.css';
+@import 'activeadmin-tom_select/src/tom-select-tailwind.css';
+
+/* Your custom styles here */
+```
+
+**Why @import instead of @tailwind?**
+- Tailwind only processes imports at the top of the file
+- Using @tailwind directives with vendor CSS imports can cause processing issues
+- The @import syntax ensures proper CSS cascade order
+
+### 5. Update Build Configuration
+
+#### esbuild.config.js
+```javascript
+#!/usr/bin/env node
+const esbuild = require('esbuild');
+const path = require('path');
+
+const config = {
+  entryPoints: [
+    'app/js/active_admin.js'
+  ],
+  bundle: true,
+  sourcemap: true,
+  format: 'esm',
+  outdir: 'app/assets/builds',
+  publicPath: '/assets',
+  loader: {
+    '.js': 'js',
+    '.jsx': 'jsx',
+  },
+  define: {
+    'global': 'window'
+  }
+};
+
+// Build logic here...
+```
+
+#### tailwind-active_admin.config.js
+```javascript
+const execSync = require("node:child_process").execSync;
+const activeAdminPlugin = require('@activeadmin/activeadmin/plugin');
+
+const activeAdminPath = execSync("bundle show activeadmin", {
+  encoding: "utf-8",
+}).trim();
+
+module.exports = {
+  content: [
+    `${activeAdminPath}/vendor/javascript/flowbite.js`,
+    `${activeAdminPath}/plugin.js`,
+    `${activeAdminPath}/app/views/**/*.{arb,erb,html,rb}`,
+    "./app/admin/**/*.{arb,erb,html,rb}",
+    "./app/views/active_admin/**/*.{arb,erb,html,rb}",
+    "./app/views/admin/**/*.{arb,erb,html,rb}",
+    "./app/js/**/*.{js,jsx}",
+    "./app/views/**/*.{erb,html}"
+  ],
+  darkMode: "selector",
+  plugins: [activeAdminPlugin],
+  safelist: [
+    // Tom Select classes
+    'tom-select-input',
+    { pattern: /^ts-/ },
+    // Other ActiveAdmin dynamic classes
+    'panel-collapsed',
+    'status-tag',
+    // Add your custom classes here
+  ]
+};
+```
+
+### 6. Create Rake Task for CSS Building (lib/tasks/active_admin.rake)
+
+```ruby
+namespace :active_admin do
+  desc "Build Active Admin Tailwind stylesheets"
+  task build: :environment do
+    command = [
+      "npx", "tailwindcss",
+      "-i", Rails.root.join("app/assets/stylesheets/active_admin.tailwind.css").to_s,
+      "-o", Rails.root.join("app/assets/builds/active_admin.css").to_s,
+      "-c", Rails.root.join("tailwind-active_admin.config.js").to_s,
+      "-m"
+    ]
+
+    puts "Building Active Admin CSS..."
+    system(*command, exception: true)
+  end
+
+  desc "Watch Active Admin Tailwind stylesheets"
+  task watch: :environment do
+    command = [
+      "npx", "tailwindcss",
+      "--watch",
+      "-i", Rails.root.join("app/assets/stylesheets/active_admin.tailwind.css").to_s,
+      "-o", Rails.root.join("app/assets/builds/active_admin.css").to_s,
+      "-c", Rails.root.join("tailwind-active_admin.config.js").to_s,
+      "-m"
+    ]
+
+    puts "Watching Active Admin CSS..."
+    system(*command)
+  end
+end
+
+Rake::Task["assets:precompile"].enhance(["active_admin:build"]) if Rake::Task.task_defined?("assets:precompile")
+```
 
-### 4. Build Process (Tailwind 3)
+### 7. Update package.json Scripts
 
-#### New Test App Structure:
+```json
+{
+  "scripts": {
+    "build:js": "node esbuild.config.js",
+    "build:css": "bundle exec rake active_admin:build",
+    "build": "npm run build:js && npm run build:css",
+    "watch:js": "node esbuild.config.js --watch",
+    "watch:css": "bundle exec rake active_admin:watch",
+    "dev": "npm run watch:js & npm run watch:css"
+  }
+}
 ```
-/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
+
+## Migration Cleanup
+
+### Files to Remove
+- `inject-jquery.js` - No longer needed
+- Any Select2-specific CSS files
+- jQuery-specific initialization code
+
+### Update Initializers
+```ruby
+# config/initializers/activeadmin_tom_select.rb (rename from activeadmin_searchable_select.rb)
+require 'activeadmin-tom_select' if defined?(ActiveAdmin)
 ```
 
-#### 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
+### Remove jQuery References
+- Remove jQuery from package.json
+- Remove inject-jquery.js from esbuild config
+- Update any custom JavaScript to use vanilla JS instead of jQuery
+
+## Usage in ActiveAdmin
+
+The usage remains the same - no changes needed in your admin files:
+
+```ruby
+ActiveAdmin.register User do
+  # In forms
+  form do |f|
+    f.input :company, as: :searchable_select
+    f.input :role, as: :searchable_select,
+            ajax: { resource: Role }
+  end
+
+  # In filters
+  filter :company, as: :searchable_select
+  filter :created_by, as: :searchable_select,
+         ajax: { resource: User }
+end
+```
 
-#### 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
+## CSS Class Changes for Custom Styling
 
-### 5. Test Updates
+If you have custom CSS, update these selectors:
 
-#### CSS Class Changes:
-| Select2 | Tom Select |
-|---------|------------|
-| `.select2-container` | `.ts-wrapper` or `.ts-control` |
+| Old (Select2) | New (Tom Select) |
+|--------------|------------------|
+| `.select2-container` | `.ts-wrapper` |
 | `.select2-dropdown` | `.ts-dropdown` |
 | `.select2-results__option` | `.ts-dropdown .option` |
-| `.select2-selection` | `.ts-control .item` |
+| `.select2-selection` | `.ts-control` |
 | `.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
+## Troubleshooting
+
+### Issue: Tom Select not initializing
+**Solution**: Ensure that:
+- `window.TomSelect` is defined in browser console
+- `setupAutoInit()` is called after importing
+- No JavaScript errors in console
+
+### Issue: Styles not loading
+**Solution**:
+- Verify CSS imports are using @import syntax, not @tailwind
+- Check that tom-select CSS is in node_modules
+- Ensure Tailwind processes the CSS file
+
+### Issue: "elements.forEach is not a function" error
+**Solution**: The `initSearchableSelects` function expects a NodeList or array, not a jQuery object. Use:
+```javascript
+// Correct - vanilla JS
+const elements = document.querySelectorAll('.searchable-select-input');
+
+// Incorrect - jQuery object
+const elements = $('.searchable-select-input');
+```
+
+### Issue: Build errors with missing files
+**Solution**: Run `npm install` and `bundle install` to ensure all dependencies are installed
+
+## Performance Improvements
+
+After migration, you should see:
+- **Reduced bundle size**: ~200KB smaller without jQuery
+- **Faster initialization**: Tom Select is more performant
+- **Better memory usage**: No jQuery overhead
+- **Cleaner code**: Pure ES6 modules
+
+## Complete Example Configuration
+
+For a working example, here's the minimal setup:
+
+**Gemfile:**
+```ruby
+gem 'activeadmin', '~> 4.0.0.beta'
+gem 'activeadmin-tom_select'
+```
+
+**package.json:**
+```json
+{
+  "dependencies": {
+    "@activeadmin/activeadmin": "^4.0.0-beta16",
+    "tom-select": "^2.4.3",
+    "activeadmin-tom_select": "^4.1.0"
+  }
+}
+```
+
+**app/js/active_admin.js:**
+```javascript
+import "@activeadmin/activeadmin";
+import TomSelect from 'tom-select';
+import { setupAutoInit, initSearchableSelects } from 'activeadmin-tom_select';
+
+window.TomSelect = TomSelect;
+window.initSearchableSelects = initSearchableSelects;
+setupAutoInit();
+```
+
+**app/assets/stylesheets/active_admin.tailwind.css:**
+```css
+@import "tailwindcss/base";
+@import "tailwindcss/components";
+@import "tailwindcss/utilities";
+@import 'tom-select/dist/css/tom-select.css';
+@import 'activeadmin-tom_select/src/tom-select-tailwind.css';
+```
+
+## Benefits Achieved
+
+1. ✅ **No jQuery Required**: Completely removed jQuery dependency
+2. ✅ **Modern JavaScript**: Using ES6 modules and vanilla JS
+3. ✅ **Smaller Bundle**: Reduced JavaScript bundle by ~200KB
+4. ✅ **Better Performance**: Faster initialization and runtime
+5. ✅ **Future-Proof**: Tom Select is actively maintained
+6. ✅ **ActiveAdmin 4 Ready**: Full compatibility with latest version
+
+## Migration Checklist
+
+- [ ] Update Gemfile with `activeadmin-tom_select`
+- [ ] Run `bundle install`
+- [ ] Update package.json dependencies
+- [ ] Run `npm install`
+- [ ] Update JavaScript imports in active_admin.js
+- [ ] Update CSS to use @import syntax
+- [ ] Create/update rake tasks for CSS building
+- [ ] Update build scripts in package.json
+- [ ] Remove jQuery and Select2 dependencies
+- [ ] Test all searchable selects in development
+- [ ] Update any custom CSS selectors
+- [ ] Remove old initialization files
+- [ ] Deploy and test in production

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

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    activeadmin-tom_select (4.1.0)
+    activeadmin-tom_select (4.1.2)
       activeadmin (>= 3.0, < 5)
       ransack (>= 1.8, < 5)
 
@@ -148,7 +148,7 @@ GEM
     formtastic (5.0.0)
       actionpack (>= 6.0.0)
     formtastic_i18n (0.7.0)
-    globalid (1.2.1)
+    globalid (1.3.0)
       activesupport (>= 6.1)
     has_scope (0.8.2)
       actionpack (>= 5.2)
@@ -165,7 +165,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.13.2)
+    json (2.15.0)
     kaminari (1.2.2)
       activesupport (>= 4.1.0)
       kaminari-actionview (= 1.2.2)
@@ -189,12 +189,12 @@ GEM
       net-imap
       net-pop
       net-smtp
-    marcel (1.0.4)
+    marcel (1.1.0)
     matrix (0.4.3)
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2025.0909)
+    mime-types-data (3.2025.0924)
     mini_mime (1.1.5)
     minitest (5.25.5)
     mutex_m (0.3.0)
@@ -222,7 +222,7 @@ GEM
       prettyprint
     prettyprint (0.2.0)
     prism (1.5.1)
-    propshaft (1.2.1)
+    propshaft (1.3.1)
       actionpack (>= 7.0.0)
       activesupport (>= 7.0.0)
       rack
@@ -272,9 +272,9 @@ GEM
       zeitwerk (~> 2.6)
     rainbow (3.1.1)
     rake (13.3.0)
-    ransack (4.3.0)
-      activerecord (>= 6.1.5)
-      activesupport (>= 6.1.5)
+    ransack (4.4.0)
+      activerecord (>= 7.1)
+      activesupport (>= 7.1)
       i18n
     rdoc (6.14.2)
       erb
@@ -301,7 +301,7 @@ GEM
       rspec-expectations (~> 3.13)
       rspec-mocks (~> 3.13)
       rspec-support (~> 3.13)
-    rspec-support (3.13.5)
+    rspec-support (3.13.6)
     rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
     rubocop (1.80.2)
@@ -329,7 +329,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    sqlite3 (2.7.3-x86_64-linux-gnu)
+    sqlite3 (2.7.4-x86_64-linux-gnu)
     stringio (3.1.7)
     thor (1.4.0)
     timeout (0.4.3)