activeadmin-tom_select 4.1.0 → 4.1.1

data/docs/guide-update-your-app.md

@@ -12,7 +12,10 @@ echo "gem 'activeadmin-tom_select', '~> 4.1.0'" >> Gemfile
 bundle install
 
 # Install NPM packages
-npm install @rocket-sensei/activeadmin-tom_select tom-select
+npm install activeadmin-tom_select tom-select
+
+# Install PostCSS plugins (REQUIRED for CSS imports to work)
+npm install postcss postcss-import postcss-nesting autoprefixer
 
 # Then follow Step 3 and onward below
 ```
@@ -21,11 +24,11 @@ npm install @rocket-sensei/activeadmin-tom_select tom-select
 
 Our fork provides:
 - ✅ Full ActiveAdmin 4.0 support
-- ✅ Rails 8 and Propshaft compatibility  
+- ✅ Rails 8 and Propshaft compatibility
 - ✅ Modern JavaScript bundler support (esbuild/webpack/importmap)
 - ✅ **Tom Select** instead of Select2 (no jQuery dependency!)
 - ✅ Virtual scroll for large datasets with pagination
-- ✅ Proper NPM package distribution under @rocket-sensei scope
+- ✅ Proper NPM package distribution as activeadmin-tom_select
 - ✅ Improved test suite with static ActiveAdmin registrations
 - ✅ Active maintenance and support
 
@@ -67,12 +70,19 @@ Remove old packages and install the new ones:
 
 ```bash
 # Remove old packages if present
-npm uninstall @codevise/activeadmin-searchable_select @rocket-sensei/activeadmin-searchable_select jquery select2
+npm uninstall @codevise/activeadmin-searchable_select activeadmin-searchable_select jquery select2
 
 # Install new packages (Tom Select instead of Select2)
-npm install @rocket-sensei/activeadmin-tom_select tom-select
+npm install activeadmin-tom_select tom-select
+
+# CRITICAL: Install PostCSS plugins for CSS imports to work
+npm install postcss postcss-import postcss-nesting autoprefixer
 ```
 
+**Note:** The `activeadmin-tom_select` package includes both JavaScript and CSS files:
+- JavaScript: Auto-initialization and helper functions
+- CSS: Tailwind-optimized Tom Select styles at `activeadmin-tom_select/src/tom-select-tailwind.css`
+
 ### Step 3: Update JavaScript Imports
 
 Update your `app/javascript/active_admin.js`:
@@ -87,7 +97,7 @@ import TomSelect from 'tom-select';
 window.TomSelect = TomSelect;
 
 // Import and auto-initialize searchable selects
-import { setupAutoInit } from '@rocket-sensei/activeadmin-tom_select';
+import { setupAutoInit } from 'activeadmin-tom_select';
 setupAutoInit();
 ```
 
@@ -101,7 +111,7 @@ import TomSelect from 'tom-select';
 window.TomSelect = TomSelect;
 
 // Import the initialization function
-import { initSearchableSelects } from '@rocket-sensei/activeadmin-tom_select';
+import { initSearchableSelects } from 'activeadmin-tom_select';
 
 // Initialize manually when needed
 document.addEventListener('DOMContentLoaded', function() {
@@ -110,18 +120,45 @@ document.addEventListener('DOMContentLoaded', function() {
 });
 ```
 
-### Step 4: Add Tom Select CSS
+### Step 4: Configure CSS Build Process (For Tailwind CSS with ActiveAdmin 4)
+
+## ⚠️ CRITICAL CSS SETUP REQUIREMENTS
+
+**IMPORTANT**: The CSS build process has very specific requirements that must be followed exactly:
+
+1. **Input file MUST use `.tailwind.css` extension** (not `.css`)
+2. **MUST have PostCSS configuration with `postcss-import` plugin**
+3. **MUST NOT use CDN imports** - all CSS must be imported from npm packages
+4. **The rake task MUST include the `--postcss` flag**
+
+### Required Files Setup
 
-Add to your ActiveAdmin stylesheet (`app/assets/stylesheets/active_admin.css` or `.scss`):
+#### 1. Create PostCSS Configuration (`postcss.config.js`)
+
+```javascript
+module.exports = {
+  plugins: [
+    require('postcss-import'),     // CRITICAL: Required for @import to work
+    require('postcss-nesting'),     // Optional: For nested CSS
+    require('autoprefixer'),        // Optional: For browser compatibility
+  ],
+}
+```
+
+#### 2. Create Tailwind Input File (`app/assets/stylesheets/active_admin.tailwind.css`)
 
 ```css
-/* Import Tom Select styles */
-@import 'tom-select/dist/css/tom-select.css';
+@import "tailwindcss/base";
+@import "tailwindcss/components";
+@import "tailwindcss/utilities";
+
+/* CRITICAL: Import Tom Select styles from npm package, NOT from CDN! */
+@import "@rocket-sensei/activeadmin-tom_select/src/tom-select-tailwind.css";
 
-/* Or if using CDN: */
-@import url('https://cdn.jsdelivr.net/npm/tom-select@2.4.3/dist/css/tom-select.css');
+/* Import any custom styles */
+@import "./active_admin_custom.css";
 
-/* Optional: Custom styling for searchable selects */
+/* Custom styling for searchable selects */
 .searchable-select-input {
   width: 100%;
 }
@@ -132,13 +169,122 @@ Add to your ActiveAdmin stylesheet (`app/assets/stylesheets/active_admin.css` or
 }
 ```
 
+#### 3. Create Rake Task (`lib/tasks/active_admin.rake`)
+
+```ruby
+namespace :active_admin do
+  desc 'Build Active Admin Tailwind stylesheets'
+  task :build do
+    require 'fileutils'
+
+    root = Rails.root
+
+    # Ensure builds directory exists
+    FileUtils.mkdir_p(File.join(root, 'app/assets/builds'))
+
+    # Build with Tailwind CLI (CRITICAL: include --postcss flag!)
+    command = [
+      'npx', 'tailwindcss',
+      '-i', File.join(root, 'app/assets/stylesheets/active_admin.tailwind.css'),
+      '-o', File.join(root, 'app/assets/builds/active_admin.css'),
+      '-c', File.join(root, 'tailwind.config.js'),
+      '--postcss', File.join(root, 'postcss.config.js'),  # CRITICAL: Must specify PostCSS config
+      '-m'
+    ]
+
+    system(*command, exception: true)
+
+    puts 'Built Active Admin CSS with Tailwind'
+  end
+
+  desc 'Watch Active Admin Tailwind stylesheets'
+  task :watch do
+    root = Rails.root
+
+    # Watch for changes
+    command = [
+      'npx', 'tailwindcss',
+      '--watch',
+      '-i', File.join(root, 'app/assets/stylesheets/active_admin.tailwind.css'),
+      '-o', File.join(root, 'app/assets/builds/active_admin.css'),
+      '-c', File.join(root, 'tailwind.config.js'),
+      '--postcss', File.join(root, 'postcss.config.js'),  # CRITICAL: Must specify PostCSS config
+      '-m'
+    ]
+
+    system(*command)
+  end
+end
+
+# Enhance existing rake tasks
+if Rake::Task.task_defined?('assets:precompile')
+  Rake::Task['assets:precompile'].enhance(['active_admin:build'])
+end
+```
+
+#### 4. Update package.json scripts
+
+```json
+{
+  "scripts": {
+    "build:js": "esbuild app/javascript/*.* --bundle --sourcemap --format=esm --outdir=app/assets/builds --public-path=/assets",
+    "build:css": "bundle exec rake active_admin:build",
+    "build": "npm run build:js && npm run build:css",
+    "watch:css": "bundle exec rake active_admin:watch"
+  }
+}
+```
+
+#### 5. Build your CSS
+
+```bash
+# One-time build
+bundle exec rake active_admin:build
+
+# Or use npm script
+npm run build:css
+
+# For development with watch mode
+bundle exec rake active_admin:watch
+# or
+npm run watch:css
+```
+
+### Common Build Errors and Solutions
+
+#### Tom Select CSS Not Included in Built File
+
+**Symptoms**: The built CSS file doesn't contain any Tom Select styles (no `.ts-wrapper`, `.ts-control`, etc. classes)
+
+**Causes and Solutions**:
+1. **Using CDN imports**: CDN imports (`@import url('https://...')`) are NOT processed by Tailwind. You MUST import from npm packages.
+2. **Wrong file extension**: Input file must be `.tailwind.css`, not `.css`
+3. **Missing PostCSS config**: Without `postcss-import` plugin, `@import` statements won't work
+4. **Missing `--postcss` flag**: The rake task must include `--postcss` flag
+
+**How to verify CSS is included**:
+```bash
+# Check if Tom Select classes are in the built file
+grep -c "ts-wrapper\|ts-control\|ts-dropdown" app/assets/builds/active_admin.css
+# Should return a number > 0
+```
+
+### Option B: Using Regular CSS (without Tailwind) - NOT RECOMMENDED
+
+⚠️ **WARNING**: Using CDN imports or regular CSS imports without a proper build process will likely result in missing styles when using Tailwind CSS build. We strongly recommend using the Tailwind setup above.
+
+If you absolutely must use regular CSS without Tailwind, you'll need a different build process that can handle CSS imports, such as:
+- Using Webpack with css-loader
+- Using esbuild with CSS plugins
+- Using a dedicated CSS bundler
+
 ### Step 5: For Importmap Users
 
 If you're using importmap instead of esbuild, add to `config/importmap.rb`:
 
 ```ruby
 pin "tom-select", to: "https://ga.jspm.io/npm:tom-select@2.4.3/dist/js/tom-select.complete.min.js"
-pin "@rocket-sensei/activeadmin-tom_select", to: "@rocket-sensei--activeadmin-tom_select.js"
+pin "activeadmin-tom_select", to: "activeadmin-tom_select.js"
 ```
 
 And update your `app/javascript/active_admin.js`:
@@ -151,7 +297,7 @@ import TomSelect from "tom-select";
 window.TomSelect = TomSelect;
 
 // Import and auto-initialize searchable selects
-import { setupAutoInit } from "@rocket-sensei/activeadmin-tom_select";
+import { setupAutoInit } from "activeadmin-tom_select";
 setupAutoInit();
 ```
 
@@ -194,11 +340,36 @@ This usually happens when Tom Select isn't properly imported. Ensure:
 2. `window.TomSelect = TomSelect` is set to make it globally available
 3. The NPM package is installed: `npm install tom-select`
 
-### Styles Not Loading
+### Styles Not Loading / CSS Missing
+
+This is a common issue when migrating to ActiveAdmin 4 with Tailwind CSS. Here's how to fix it:
+
+#### Checklist for Tailwind CSS Users:
+
+1. ✅ **File Extension**: Is your input file named `active_admin.tailwind.css` (NOT `active_admin.css`)?
+2. ✅ **PostCSS Config**: Do you have `postcss.config.js` with `postcss-import` plugin?
+3. ✅ **NPM Packages**: Are PostCSS plugins installed? (`npm install postcss postcss-import`)
+4. ✅ **No CDN Imports**: Are you importing from npm packages, not CDN URLs?
+5. ✅ **Rake Task**: Does your rake task include `--postcss` flag?
+6. ✅ **Build Output**: Does `app/assets/builds/active_admin.css` contain Tom Select classes?
+
+Run this diagnostic command:
+```bash
+# Check if everything is set up correctly
+echo "Checking setup..."
+[ -f postcss.config.js ] && echo "✅ PostCSS config exists" || echo "❌ Missing postcss.config.js"
+[ -f app/assets/stylesheets/active_admin.tailwind.css ] && echo "✅ Tailwind CSS file exists" || echo "❌ Missing active_admin.tailwind.css"
+grep -q "postcss-import" postcss.config.js && echo "✅ postcss-import configured" || echo "❌ postcss-import not in config"
+grep -q "@rocket-sensei/activeadmin-tom_select" app/assets/stylesheets/active_admin.tailwind.css && echo "✅ Tom Select import found" || echo "❌ Tom Select import missing"
+grep -q "ts-wrapper" app/assets/builds/active_admin.css 2>/dev/null && echo "✅ Tom Select CSS in built file" || echo "❌ Tom Select CSS NOT in built file"
+```
+
+#### Common CSS Issues:
 
-1. Verify the Tom Select CSS import is in your stylesheet
-2. Check that your build process includes the stylesheets
-3. Clear your browser cache and restart Rails server
+- **Dropdown not styled**: Missing Tom Select CSS - verify all setup steps above
+- **Width issues**: Add `.ts-wrapper { min-width: 50%; }` to your styles
+- **Z-index problems**: Tom Select dropdowns may need higher z-index in some layouts
+- **Missing icons**: Ensure the Tom Select CSS is fully loaded
 
 ### Ajax Options Not Loading
 
@@ -228,7 +399,7 @@ f.input :tags, as: :searchable_select, ajax: true, multiple: true
 ## Differences from Original Gem
 
 1. **Tom Select instead of Select2**: No jQuery dependency required!
-2. **NPM Scope**: Package is now `@rocket-sensei/activeadmin-tom_select`
+2. **NPM Package**: Package is now `activeadmin-tom_select` or `@rocket-sensei/activeadmin-tom_select`
 3. **Gem Name**: Gem is now `activeadmin-tom_select`
 4. **Virtual Scroll**: Automatic pagination for large datasets
 5. **Rails 8 Ready**: Full support for Propshaft and modern Rails
@@ -261,10 +432,12 @@ If you're migrating from a Select2-based version to this Tom Select version:
 ## Need Help?
 
 If you encounter issues:
-1. Check that all JavaScript packages are installed
-2. Verify your bundler configuration
-3. Clear browser cache and Rails tmp/cache
-4. Check browser console for errors
+1. Run the diagnostic command above to check your setup
+2. Verify all npm packages are installed
+3. Check that PostCSS config is correct
+4. Ensure no CDN imports are being used
+5. Clear browser cache and Rails tmp/cache
+6. Check browser console for errors
 
 For bug reports or questions, please visit:
 https://github.com/rs-pro/activeadmin-tom_select/issues