From 22e8fb58da809c564771548c3458b2bc00671e34 Mon Sep 17 00:00:00 2001 From: Gleb Tv Date: Wed, 24 Sep 2025 14:13:42 +0300 Subject: [PATCH] rm unneded doc file --- docs/update-tom-select.md | 184 -------------------------------------- 1 file changed, 184 deletions(-) delete mode 100644 docs/update-tom-select.md diff --git a/docs/update-tom-select.md b/docs/update-tom-select.md deleted file mode 100644 index ea70343..0000000 --- a/docs/update-tom-select.md +++ /dev/null @@ -1,184 +0,0 @@ -# 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 \ No newline at end of file