rs-activeadmin-searchable_select 4.0.5

data/docs/activeadmin-4-gem-migration-guide.md

@@ -0,0 +1,313 @@
+# ActiveAdmin Trumbowyg 2.x Migration Guide
+
+## Overview
+This guide covers migrating from activeadmin_trumbowyg 1.x to 2.x, which adds support for ActiveAdmin 4 and modern JavaScript build tools. Version 2.x introduces a new NPM package for easier integration with esbuild and webpack projects.
+
+## What's New in Version 2.x
+
+### NPM Package Support
+- Published on NPM as `@rocket-sensei/activeadmin_trumbowyg`
+- Direct integration with esbuild and webpack projects
+- No generator needed for modern JavaScript bundlers
+- Automatic jQuery dependency management
+
+### Path Changes
+- JavaScript module paths changed from `activeadmin/` to `active_admin/`
+- CSS paths updated to follow Rails conventions
+
+### Compatibility
+- ActiveAdmin 3.x and 4.x support
+- Rails 7.0+ required
+- Ruby 3.2+ required
+- Works with both Sprockets (legacy) and Propshaft
+
+## Installation Methods
+
+### Option 1: Modern JavaScript Bundlers (esbuild/webpack) - Recommended
+
+#### Install the NPM package:
+```bash
+npm install @rocket-sensei/activeadmin_trumbowyg
+# or
+yarn add @rocket-sensei/activeadmin_trumbowyg
+```
+
+#### Import in your JavaScript entry point:
+```javascript
+// app/javascript/active_admin.js or similar
+import '@rocket-sensei/activeadmin_trumbowyg'
+```
+
+That's it! No generator needed. The package automatically handles jQuery dependencies and initialization.
+
+### Option 2: Sprockets/Importmap (Legacy)
+
+#### Add to Gemfile:
+```ruby
+gem 'activeadmin_trumbowyg', '~> 2.0'
+```
+
+#### Run the generator:
+```bash
+rails generate activeadmin_trumbowyg:install
+```
+
+This will add the necessary JavaScript and CSS to your ActiveAdmin configuration.
+
+## Migration from Version 1.x to 2.x
+
+### Step 1: Update Your Gemfile
+```ruby
+# Old (1.x)
+gem 'activeadmin_trumbowyg', '~> 1.0'
+
+# New (2.x)
+gem 'activeadmin_trumbowyg', '~> 2.0'
+```
+
+### Step 2: Update JavaScript Paths
+
+If you're using esbuild or webpack, switch to the NPM package:
+
+```javascript
+// Old (1.x) - Using gem assets
+//= require activeadmin/trumbowyg/trumbowyg
+//= require activeadmin/trumbowyg_input
+
+// New (2.x) - Using NPM package
+import '@rocket-sensei/activeadmin_trumbowyg'
+```
+
+For Sprockets users, update the paths:
+
+```javascript
+// Old (1.x)
+//= require activeadmin/trumbowyg/trumbowyg
+//= require activeadmin/trumbowyg_input
+
+// New (2.x)
+//= require active_admin/trumbowyg/trumbowyg
+//= require active_admin/trumbowyg_input
+```
+
+### Step 3: Update CSS Imports
+
+```css
+/* Old (1.x) */
+@import "activeadmin/trumbowyg/trumbowyg";
+
+/* New (2.x) */
+@import "active_admin/trumbowyg/trumbowyg";
+```
+
+## Configuration Examples
+
+### esbuild Configuration
+
+```javascript
+// esbuild.config.js
+import esbuild from 'esbuild'
+
+esbuild.build({
+  entryPoints: ['app/javascript/active_admin.js'],
+  bundle: true,
+  sourcemap: true,
+  format: 'esm',
+  outdir: 'app/assets/builds',
+  loader: {
+    '.js': 'jsx',
+  },
+  external: [], // jQuery is bundled by the NPM package
+})
+```
+
+### webpack Configuration
+
+```javascript
+// webpack.config.js
+module.exports = {
+  entry: './app/javascript/active_admin.js',
+  output: {
+    path: path.resolve(__dirname, 'app/assets/builds'),
+    filename: 'active_admin.js'
+  },
+  module: {
+    rules: [
+      {
+        test: /\.js$/,
+        exclude: /node_modules/,
+        use: 'babel-loader'
+      }
+    ]
+  }
+}
+```
+
+### Package.json Example
+
+```json
+{
+  "name": "your-app",
+  "dependencies": {
+    "@rocket-sensei/activeadmin_trumbowyg": "^2.0.0",
+    "jquery": "^3.7.1"
+  },
+  "scripts": {
+    "build": "esbuild app/javascript/*.* --bundle --sourcemap --outdir=app/assets/builds"
+  }
+}
+```
+
+## Usage in ActiveAdmin
+
+After installation, use the Trumbowyg editor in your admin forms:
+
+```ruby
+# app/admin/posts.rb
+ActiveAdmin.register Post do
+  form do |f|
+    f.inputs do
+      f.input :title
+      f.input :content, as: :trumbowyg
+      # With options
+      f.input :description, as: :trumbowyg, input_html: {
+        data: {
+          trumbowyg_options: {
+            btns: [
+              ['viewHTML'],
+              ['formatting'],
+              ['strong', 'em', 'del'],
+              ['link'],
+              ['insertImage'],
+              ['unorderedList', 'orderedList'],
+              ['horizontalRule'],
+              ['removeformat'],
+              ['fullscreen']
+            ],
+            minimalLinks: true,
+            removeformatPasted: true
+          }
+        }
+      }
+    end
+    f.actions
+  end
+end
+```
+
+## Customizing Trumbowyg
+
+### Custom Buttons and Plugins
+
+The NPM package includes all Trumbowyg plugins. To use them:
+
+```javascript
+// app/javascript/active_admin.js
+import '@rocket-sensei/activeadmin_trumbowyg'
+
+// Custom initialization (optional)
+document.addEventListener('DOMContentLoaded', () => {
+  // Custom global defaults
+  $.trumbowyg.svgPath = '/assets/icons.svg'
+  
+  // Language settings
+  $.trumbowyg.langs.en.bold = 'Strong'
+})
+```
+
+### Styling the Editor
+
+Add custom styles in your ActiveAdmin stylesheet:
+
+```scss
+// app/assets/stylesheets/active_admin.scss
+@import "active_admin/trumbowyg/trumbowyg";
+
+// Custom overrides
+.trumbowyg-box {
+  margin: 0;
+  
+  .trumbowyg-editor {
+    min-height: 300px;
+  }
+}
+
+// Dark mode support
+.dark {
+  .trumbowyg-box {
+    background: #374151;
+    
+    .trumbowyg-editor {
+      background: #1f2937;
+      color: #f3f4f6;
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Issue: Trumbowyg not initializing
+**Solution**: Ensure jQuery is loaded before the Trumbowyg package:
+```javascript
+// Correct order
+import $ from 'jquery'
+window.$ = window.jQuery = $
+import '@rocket-sensei/activeadmin_trumbowyg'
+```
+
+#### Issue: Icons not displaying
+**Solution**: The SVG path might be incorrect. Set it explicitly:
+```javascript
+$.trumbowyg.svgPath = '/assets/trumbowyg/icons.svg'
+```
+
+#### Issue: Styles not loading with NPM package
+**Solution**: Import the CSS separately in your stylesheet:
+```css
+/* app/assets/stylesheets/active_admin.scss */
+@import "@rocket-sensei/activeadmin_trumbowyg/dist/trumbowyg.min.css";
+```
+
+#### Issue: Editor not working in nested forms
+**Solution**: Re-initialize after adding new fields:
+```javascript
+$(document).on('has_many_add:after', '.has_many_container', function() {
+  $(this).find('[data-trumbowyg]').each(function() {
+    if (!$(this).hasClass('trumbowyg-textarea-init')) {
+      const options = $(this).data('trumbowyg-options') || {}
+      $(this).trumbowyg(options)
+    }
+  })
+})
+```
+
+## Breaking Changes from 1.x
+
+1. **Path changes**: All paths changed from `activeadmin/` to `active_admin/`
+2. **NPM package**: New recommended installation method via NPM
+3. **No generator for modern bundlers**: esbuild/webpack users don't need the generator
+4. **jQuery handling**: NPM package bundles jQuery dependencies automatically
+
+## Version Compatibility
+
+| activeadmin_trumbowyg | ActiveAdmin | Rails | Ruby |
+|-----------------------|-------------|-------|------|
+| 2.x                   | 3.x - 4.x   | 7.0+  | 3.2+ |
+| 1.x                   | 1.x - 3.x   | 5.2+  | 2.5+ |
+
+## Resources
+
+- [NPM Package](https://www.npmjs.com/package/@rocket-sensei/activeadmin_trumbowyg)
+- [GitHub Repository](https://github.com/rocket-sensei/activeadmin_trumbowyg)
+- [Trumbowyg Documentation](https://alex-d.github.io/Trumbowyg/)
+- [ActiveAdmin Documentation](https://activeadmin.info/)
+
+## Support
+
+For issues or questions:
+1. Check the [GitHub Issues](https://github.com/rocket-sensei/activeadmin_trumbowyg/issues)
+2. Consult the [Trumbowyg documentation](https://alex-d.github.io/Trumbowyg/) for editor-specific questions
+3. For ActiveAdmin 4 specific issues, see the [ActiveAdmin upgrade guide](https://activeadmin.info/)

data/docs/combustion.md

@@ -0,0 +1,213 @@
+# Combustion
+
+Combustion is a library to help you test your Rails Engines in a simple and effective manner, instead of creating a full Rails application in your spec or test folder.
+
+It allows you to write your specs within the context of your engine, using only the parts of a Rails app you need.
+
+## Usage
+
+Get the gem into either your gemspec or your Gemfile, depending on how you manage your engine's dependencies:
+
+```ruby
+# gemspec
+gem.add_development_dependency 'combustion', '~> 1.3'
+
+# Gemfile
+gem 'combustion', '~> 1.3'
+```
+
+In your `spec_helper.rb`, get Combustion to set itself up - which has to happen before you introduce `rspec/rails` and - if being used - `capybara/rails`. Here's an example within context:
+
+```ruby
+require 'bundler'
+
+Bundler.require :default, :development
+
+# If you're using all parts of Rails:
+Combustion.initialize! :all
+# Or, load just what you need:
+# Combustion.initialize! :active_record, :action_controller
+
+require 'rspec/rails'
+# If you're using Capybara:
+# require 'capybara/rails'
+
+RSpec.configure do |config|
+  config.use_transactional_fixtures = true
+end
+```
+
+Please note that using `:all` as an argument for `Combustion.initialize!` will load all key parts of Rails that are considered essential for that version. For example: ActiveJob is only loaded for Rails 4.2 onwards, and Sprockets is only loaded for Rails 3.1-6.1 (as it is no longer part of the default set in 7.0).
+
+You'll also want to run the generator that creates a minimal set of files expected by Rails - run this in the directory of your engine:
+
+```shell
+combust
+
+# or, if bundling with the git repo:
+bundle exec combust
+```
+
+Minitest support is considered to be experimental, but it's certainly working [for some](https://github.com/pat/combustion/issues/78). Comments on others' experiences are welcome!
+
+What Combustion is doing is setting up a Rails application at `spec/internal` - but you only need to add the files within that directory that you're going to use. Read on for some detail about what that involves.
+
+If you want to use Cucumber, I recommend starting with [these notes in issue #16](https://github.com/pat/combustion/issues/16) from Niklas Cathor.
+
+### Configuring a different test app directory
+
+If you want your app to be located somewhere other than `spec/internal`, then make sure you configure it before you call `Combustion.initialize!`:
+
+```ruby
+Combustion.path = 'spec/dummy'
+Combustion.initialize! :all
+```
+
+
+### Configuring which Rails modules should be loaded.
+
+By default, Combustion doesn't come with any of the Rails stack. You can customise this though - just pass in what you'd like loaded to the `Combustion.initialize!` call:
+
+```ruby
+Combustion.initialize! :active_record, :action_controller,
+                       :action_view, :sprockets
+```
+
+
+And then in your engine's Gemfile:
+
+```ruby
+group :test do
+  gem 'activerecord'
+  gem 'actionpack' # action_controller, action_view
+  gem 'sprockets'
+end
+```
+
+Make sure to specify the appropriate version that you want to use.
+
+ActiveSupport and Railties are always loaded, as they're an integral part of Rails.
+
+### Using Models and ActiveRecord
+
+If you're using ActiveRecord, then there are two critical files within your internal Rails app at `spec/internal` that you'll need to modify:
+
+* config/database.yml
+* db/schema.rb
+
+Both follow the same structure as in any normal Rails application - and the schema file lets you avoid migrations, as it gets run whenever the test suite starts. Here's a quick sample (note that tables are overwritten if they already exist - this is necessary):
+
+```ruby
+ActiveRecord::Schema.define do
+  create_table(:pages, :force => true) do |t|
+    t.string :name
+    t.text   :content
+    t.timestamps
+  end
+end
+```
+
+#### Disabling Database Preparation
+
+If you are preparing your own database manually or through different processes, you can disable different parts of the setup process by the following flags: `:database_reset`, `:load_schema`, and `:database_migrate`. All default to true.
+
+```ruby
+Combustion.initialize! :active_record,
+  :database_reset => false,
+  :load_schema    => false
+```
+
+### Configuring Combustion to initialise the test db from a .sql file instead of schema.rb
+
+Name the file structure.sql and configure Combustion to use it before initialising:
+
+```ruby
+Combustion.schema_format = :sql
+Combustion.initialize! :all
+```
+
+Any models that aren't provided by your engine should be located at `spec/internal/app/models`.
+
+### Using ActionController and ActionView
+
+You'll only need to add controllers and views to your internal Rails app for whatever you're testing that your engine doesn't provide - this may be nothing at all, so perhaps you don't even need `spec/internal/app/views` or `spec/internal/app/controllers` directories.
+
+However, if you're doing any testing of your engine's controllers or views, then you're going to need routes set up for them - so modify `spec/internal/config/routes.rb` accordingly:
+
+```ruby
+Rails.application.routes.draw do
+  resources :pages
+end
+```
+
+Just like in a standard Rails app, if you have a mounted engine, then its routes are accessible through whatever it has been loaded as.
+
+### Customizing Rails application settings
+
+If you would like to specify any Rails configuration parameter, you can do it without creating any environment file, simply passing a block to Combustion.initialize! like this:
+
+```ruby
+Combustion.initialize! :all do
+  config.active_record.whitelist_attributes = false
+end
+```
+
+Values given through the initialize! block will be set during Rails initialization process, exactly before the corresponding environment file inside `spec/internals/config/enviroments` is loaded (when that file exists), overriding Combustion's defaults.
+
+Parameters defined in, for instance, `spec/internals/config/environments/test.rb`, would override Combustion's defaults and also config settings passed to initialize!.
+
+### Using other Rails-focused libraries
+
+Be aware that other gems may require parts of Rails when they're loaded, and this could cause some issues with Combustion's own setup. You may need to manage the loading yourself by setting `:require` to false in your Gemfile for the gem in question, and then requiring it manually in your spec_helper. View [issue #33](https://github.com/pat/combustion/issues/33) for an example with FactoryBot.
+
+### Environment and Logging
+
+Your tests will execute within the test environment for the internal Rails app - and so logs are available at `spec/internal/log/test.log`. You should probably create that log directory so Rails doesn't complain.
+
+### Rack it up
+
+Once you've got this set up, you can fire up your test environment quite easily with Rack - a `config.ru` file is provided by the generator. Just run `rackup` and visit [http://localhost:9292](http://localhost:9292).
+
+### Get your test on!
+
+Now you're good to go - you can write specs within your engine's spec directory just like you were testing a full Rails application - models in `spec/models`, controllers in `spec/controllers`. If you bring Capybara into the mix, then the standard helpers from that will be loaded as well.
+
+```ruby
+require 'spec_helper'
+
+describe Page do
+  describe '#valid' do
+    it 'requires a name' do
+      # This is just an example. Go write your own tests!
+    end
+  end
+end
+```
+
+
+## Compatibility
+
+The current test matrix covers MRI 2.4 to 3.1, and Rails 3.1 to 7.0. It will possibly work on older versions and other Ruby implementations as well.
+
+You can also use Combustion with multiple versions of Rails to test compatibility across them. [Appraisal](https://github.com/thoughtbot/appraisal) is a gem that can help with this, and a good starting reference is the [Thinking Sphinx](https://github.com/pat/thinking-sphinx) test suite, which runs against [multiple versions](https://github.com/pat/thinking-sphinx/blob/master/Appraisals) of Rails.
+
+## Limitations and Known Issues
+
+Combustion is currently written with the expectation it'll be used with RSpec, but others have got it working with [Minitest](https://github.com/pat/combustion/issues/78). I'd love to make this more flexible - if you want to give it a shot before I get around to it, patches are very much welcome.
+
+I've not tried using this with Cucumber, but it should work in theory without too much hassle. Let me know if I'm wrong!
+
+## Contributing
+
+Please note that this project now has a [Contributor Code of Conduct](http://contributor-covenant.org/version/1/0/0/). By participating in this project you agree to abide by its terms.
+
+Contributions are very much welcome - but keep in mind the following:
+
+* Keep patches in a separate branch
+* Don't mess with the version or history file. I'll take care of that when the patch is merged in.
+
+The tests are extremely minimal, and patches to extend the suite are especially welcome.
+
+## Credits
+
+Copyright (c) 2011-2021, Combustion is developed and maintained by Pat Allan, and is released under the open MIT Licence. Many thanks to HyperTiny for encouraging its development, and [all who have contributed patches](https://github.com/pat/combustion/contributors).