activeadmin-quill_editor/docs/update-tom-select.md

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:

"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:

  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