remote_select 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cce3aae6bcdda3d4094e25da7d93613b40d1971a6e62284dd0f8416569e4fa4
-  data.tar.gz: 3f4d2f7cc3ce1f84e87b4da8b5b1c9b9e33611bfae03a03e354ea2d4d6db005d
+  metadata.gz: 15df89b787a91d68146ed4b189ba178c6ba1e0f83f9f5cffbd7e613cd3ccf3cd
+  data.tar.gz: 4187104ab27012204f54186dcf2047fb3c75523f10de6a4e05eee795d2c7a565
 SHA512:
-  metadata.gz: 2d0f92bff38d7f97943075af39052ff425cd3a1e1a6314bafaa3ddb0073383c2d716bc01dc00831657858187fa4e47c55567bc2e98f62a647fb61b3b23961d62
-  data.tar.gz: 95699a31cdf43ba2ff131e4bd9a017380da506f21d6f1946af94d9b5712da2e51383414e718903afb0fc5288aed498ed4f440f2d6fb111010e5c9fad7b022c98
+  metadata.gz: 2e0272bf4bef5398addcc85d635ad09ee6a1f78e7df4987e8f71d032ab966d4e80dc9bc88ecf376b758651104189d0e85e2248c03b2e3ac3222f02f60895febf
+  data.tar.gz: '089a736b827eadffdd02d3b0dd1bfe996f7f1f9c43a9dc7d0012c08849b2a295b77a014162c573d77377200cf42ac531ebd25659289f7120205c0c27973e7ae0'

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2026-03-20
+
+### Added
+- **Install generator** (`rails generate remote_select:install`) — copies JS and CSS into the consuming app with pipeline-specific post-install instructions. Works with esbuild, rollup, webpack, importmap, and Sprockets.
+- **Select2-compatible response parsing** — accepts both `has_more` and `pagination.more` response formats, enabling zero-backend-change migration from Select2.
+- **AI assistant integration guide** (`COPILOT_INSTRUCTIONS.md`) — concise reference for coding assistants to integrate the gem correctly.
+- **Minitest test suite** — view helper tests, generator tests, JS/CSS source integrity tests, version tests.
+- **CSS custom properties documentation** in README with full theming reference table.
+- **Version headers** in JS and CSS source files for traceability.
+
+### Changed
+- README restructured with generator-first installation flow, per-pipeline setup instructions (collapsible details), and dual response format documentation.
+
+### Fixed
+- JS/CSS files are now resolvable by esbuild, rollup, webpack, and Vite via the install generator (previously only worked with importmap/Sprockets).
+- Pagination with `has_more: false` now correctly returns `false` (changed `||` to `??` to avoid truthy coercion).
+
 ## [0.1.0] - 2026-03-20
 
 ### Added

data/COPILOT_INSTRUCTIONS.md

@@ -0,0 +1,151 @@
+# remote_select — AI Coding Assistant Integration Guide
+
+> Concise reference for LLMs and coding assistants integrating `remote_select` into Rails applications.
+
+## What it is
+
+A **Ruby gem** (not an npm package) providing a searchable remote-data select for Rails forms. Zero JS dependencies, no jQuery, no Stimulus required. Works with Turbo.
+
+## Quick integration checklist
+
+1. `gem "remote_select"` in Gemfile → `bundle install`
+2. `rails generate remote_select:install` (copies JS + CSS, prints pipeline-specific instructions)
+3. Import JS in entry point (see pipeline table below)
+4. Import CSS in entry point (see pipeline table below)
+5. Add `remote_select()` helper in form view
+6. Create JSON search endpoint in controller
+
+## Asset pipeline setup
+
+| Pipeline | JS import | CSS import |
+|----------|-----------|------------|
+| **esbuild / rollup / webpack** | `import "./remote_select"` in `application.js` | `@import "./remote_select";` in SCSS/CSS entry |
+| **importmap (Rails 8)** | `pin "remote_select"` in `config/importmap.rb` + `import "remote_select"` | `*= require remote_select` in `application.css` |
+| **Sprockets** | `//= require remote_select` | `*= require remote_select` |
+
+For **esbuild/rollup/webpack**: the generator **must** be run — bare `import "remote_select"` will fail because the gem path is not in `node_modules`.
+
+For **importmap/Sprockets**: the generator is optional — the engine registers asset paths automatically.
+
+## View helper signature
+
+```ruby
+remote_select(form, attribute, endpoint, options = {})
+```
+
+### Parameters
+
+- `form` — Rails form builder instance
+- `attribute` — model attribute symbol (e.g., `:company_id`)
+- `endpoint` — URL string returning JSON (e.g., `search_companies_path`)
+- `options` — Hash:
+
+| Key | Type | Default |
+|-----|------|---------|
+| `:selected_value` | String/Integer | `nil` |
+| `:selected_text` | String | `nil` |
+| `:min_chars` | Integer | `2` |
+| `:debounce_delay` | Integer | `250` |
+| `:placeholder` | String | `"Type to search..."` |
+| `:per_page` | Integer | `20` |
+| `:depends_on` | String | `nil` (CSS selectors, comma-separated) |
+| `:clear_on_dependency_change` | Boolean | `true` |
+| `:empty_text` | String | `"No results found"` |
+| `:loading_text` | String | `"Loading..."` |
+| `:html` | Hash | `{}` (extra attrs on hidden input) |
+
+## Typical form usage
+
+```erb
+<%= form_with model: @article do |form| %>
+  <%= remote_select(form, :company_id, search_companies_path,
+        selected_value: @article.company_id,
+        selected_text:  @article.company&.name,
+        placeholder: "Search companies...",
+        min_chars: 2) %>
+<% end %>
+```
+
+## Dependent select pattern
+
+```erb
+<%= form.select :country_id, countries_options, {}, { id: "country-select" } %>
+<%= remote_select(form, :city_id, search_cities_path,
+      depends_on: "#country-select",
+      clear_on_dependency_change: true) %>
+```
+
+The `country_id` param is automatically appended to the fetch URL when the parent changes.
+
+## Required JSON endpoint
+
+The controller action receives `q`, `page`, `per_page` as query params (plus any dependency params). It must return:
+
+```ruby
+def search_companies
+  query    = params[:q].to_s.strip
+  page     = (params[:page] || 1).to_i
+  per_page = (params[:per_page] || 20).to_i
+
+  scope = Company.order(:name)
+  scope = scope.where("name ILIKE ?", "%#{query}%") if query.present?
+
+  total   = scope.count
+  results = scope.limit(per_page).offset((page - 1) * per_page)
+
+  render json: {
+    results:  results.map { |c| { id: c.id, text: c.name } },
+    has_more: (page * per_page) < total
+  }
+end
+```
+
+### Accepted response shapes
+
+```json
+{ "results": [{ "id": 1, "text": "Name" }], "has_more": true }
+```
+
+```json
+{ "results": [{ "id": 1, "text": "Name" }], "pagination": { "more": true } }
+```
+
+Both formats work. Each result object **must** have `id` and `text` keys.
+
+## Route example
+
+```ruby
+# config/routes.rb
+get "companies/search", to: "companies#search", as: :search_companies
+```
+
+## Theming
+
+Override CSS custom properties — no need to edit the stylesheet:
+
+```css
+.remote-select-container {
+  --rs-focus-border-color: #198754;
+  --rs-border-radius: 0.25rem;
+  --rs-dropdown-max-height: 400px;
+}
+```
+
+## Common mistakes to avoid
+
+1. **Do NOT** use bare `import "remote_select"` with esbuild/webpack — run the generator first
+2. **Do NOT** add an npm package — this is a Ruby gem only
+3. **Do NOT** forget the `text` key in JSON results — `name` won't work, must be `text`
+4. **Do NOT** skip `selected_text` when setting `selected_value` — both are needed for preselection display
+5. **Do NOT** add Stimulus controllers — the component auto-initializes on `DOMContentLoaded` and `turbo:load`
+
+## JS API (for programmatic use)
+
+```js
+const el = document.querySelector('[data-remote-select]');
+// Access instance if needed:
+const rs = new RemoteSelect(el, { endpoint: '/search', minChars: 1 });
+rs.setParam('category', 'books');
+rs.clearSelection();
+rs.destroy();
+```

data/README.md

@@ -16,7 +16,8 @@ Replaces Select2 / Tom Select for the common case of "type to search a remote li
 - **Preselected values** — display preselected options on page load
 - **i18n** — default strings resolved via `I18n.t` with English fallbacks
 - **Turbo compatible** — full-page navigation and Turbo Frames, no Stimulus required
-- **No dependencies** — pure vanilla JavaScript
+- **Select2-compatible** — accepts Select2 `pagination.more` response format out of the box
+- **No dependencies** — pure vanilla JavaScript (ES2020)
 
 ## Installation
 
@@ -32,9 +33,26 @@ Run:
 bundle install
 ```
 
-### JavaScript
+Then run the install generator to copy JS and CSS into your app:
 
-**Importmap** (Rails 8 default):
+```bash
+rails generate remote_select:install
+```
+
+The generator copies two files and prints setup instructions for your specific asset pipeline (esbuild, importmap, Sprockets, etc.).
+
+Use `--force` to overwrite previously copied files when updating the gem:
+
+```bash
+rails generate remote_select:install --force
+```
+
+### Manual setup (if you prefer not to use the generator)
+
+<details>
+<summary>Importmap (Rails 8 default)</summary>
+
+No generator needed — importmap resolves from the engine automatically.
 
 ```ruby
 # config/importmap.rb
@@ -46,32 +64,47 @@ pin "remote_select", to: "remote_select.js"
 import "remote_select"
 ```
 
-**esbuild / rollup / webpack**:
+For CSS, add to `application.css`:
 
-```js
-import "remote_select"
+```css
+/*= require remote_select */
 ```
 
-**Sprockets** (`application.js`):
+</details>
+
+<details>
+<summary>Sprockets (no bundler)</summary>
 
 ```js
+// app/assets/javascripts/application.js
 //= require remote_select
 ```
 
-### Stylesheet
+```css
+/* app/assets/stylesheets/application.css */
+/*= require remote_select */
+```
 
-**Sass / SCSS**:
+</details>
 
-```scss
-@import 'remote_select';
+<details>
+<summary>esbuild / rollup / webpack (jsbundling-rails)</summary>
+
+Run the generator first (see above), then:
+
+```js
+// app/javascript/application.js
+import "./remote_select"
 ```
 
-**Sprockets** (`application.css`):
+For CSS, add to your SCSS/CSS entry:
 
-```css
-/*= require remote_select */
+```scss
+@import './remote_select';
 ```
 
+</details>
+
 ## Usage
 
 ### Basic
@@ -144,7 +177,9 @@ en:
 
 ## Backend endpoint
 
-Your action must return JSON:
+Your action must return JSON with a `results` array. Pagination is optional.
+
+### Recommended format
 
 ```ruby
 def search_companies
@@ -166,8 +201,6 @@ def search_companies
 end
 ```
 
-### Required response shape
-
 ```json
 {
   "results":  [{ "id": 1, "text": "Acme Corp" }],
@@ -176,6 +209,19 @@ end
 }
 ```
 
+### Select2-compatible format (also accepted)
+
+If you're migrating from Select2, your existing endpoints work as-is:
+
+```json
+{
+  "results":  [{ "id": 1, "text": "Acme Corp" }],
+  "pagination": { "more": true }
+}
+```
+
+Both `has_more` and `pagination.more` are recognized. If neither is present, pagination is disabled.
+
 ## Theming
 
 All visual properties are CSS custom properties on `.remote-select-container`. Override without touching the stylesheet:
@@ -190,6 +236,23 @@ All visual properties are CSS custom properties on `.remote-select-container`. O
 }
 ```
 
+### Available CSS custom properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--rs-text-color` | `#212529` | Main text color |
+| `--rs-muted-color` | `#6c757d` | Placeholder / message color |
+| `--rs-bg-color` | `#fff` | Background |
+| `--rs-border-color` | `#dee2e6` | Border color |
+| `--rs-border-radius` | `0.375rem` | Corner radius |
+| `--rs-focus-border-color` | `#86b7fe` | Focus ring border |
+| `--rs-focus-shadow` | blue 0.25rem | Focus ring shadow |
+| `--rs-item-hover-bg` | `#e9ecef` | Hovered item background |
+| `--rs-error-color` | `#dc3545` | Error text color |
+| `--rs-zindex` | `1050` | Dropdown z-index |
+| `--rs-dropdown-max-height` | `300px` | Dropdown max height |
+| `--rs-results-max-height` | `250px` | Results list max height |
+
 ## JavaScript API
 
 ```js
@@ -209,7 +272,7 @@ rs.destroy();                     // remove all listeners + DOM
 
 ## Browser support
 
-Modern browsers (Chrome, Firefox, Safari, Edge). Requires ES2020 (`??`, `async/await`, `AbortController`). No IE11.
+Modern browsers (Chrome, Firefox, Safari, Edge). Requires ES2020 (`??`, `?.`, `async/await`, `AbortController`). No IE11.
 
 ## License
 

data/app/assets/stylesheets/remote_select.css

@@ -1,3 +1,4 @@
+/* remote_select v0.2.0 — https://github.com/GhennadiiMir/remote_select */
 /* RemoteSelect component styles */
 
 /* ── Theming variables ────────────────────────────────────────────────────── */

data/app/javascript/remote_select.js

@@ -1,3 +1,4 @@
+// remote_select v0.2.0 — https://github.com/GhennadiiMir/remote_select
 /**
  * RemoteSelect - Vanilla JS remote data select component
  * A lightweight replacement for select2/tom-select with remote data source
@@ -263,7 +264,7 @@ class RemoteSelect {
 
       const data   = await response.json();
       this.results = append ? [...this.results, ...data.results] : data.results;
-      this.hasMore = data.has_more || false;
+      this.hasMore = data.has_more ?? data.pagination?.more ?? false;
       this._renderResults(append);
     } catch (err) {
       if (err.name === 'AbortError') return; // request was intentionally cancelled

data/lib/generators/remote_select/install_generator.rb

@@ -0,0 +1,119 @@
+require "rails/generators/base"
+
+module RemoteSelect
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Copy remote_select JS and CSS into your application"
+
+      class_option :force, type: :boolean, default: false,
+        desc: "Overwrite existing files"
+
+      def copy_javascript
+        source = RemoteSelect::Engine.root.join("app/javascript/remote_select.js")
+        dest   = File.join(destination_root, "app/javascript/remote_select.js")
+
+        if File.exist?(dest) && !options[:force]
+          say_status :skip, "app/javascript/remote_select.js already exists (use --force to overwrite)", :yellow
+        else
+          version_comment = "// remote_select v#{RemoteSelect::VERSION} — copied by rails generate remote_select:install\n"
+          create_file "app/javascript/remote_select.js", version_comment + source.read
+        end
+      end
+
+      def copy_stylesheet
+        source = RemoteSelect::Engine.root.join("app/assets/stylesheets/remote_select.css")
+        dest   = File.join(destination_root, "app/assets/stylesheets/remote_select.css")
+
+        if File.exist?(dest) && !options[:force]
+          say_status :skip, "app/assets/stylesheets/remote_select.css already exists (use --force to overwrite)", :yellow
+        else
+          version_comment = "/* remote_select v#{RemoteSelect::VERSION} — copied by rails generate remote_select:install */\n"
+          create_file "app/assets/stylesheets/remote_select.css", version_comment + source.read
+        end
+      end
+
+      def print_post_install
+        say ""
+        say "remote_select files copied successfully!", :green
+        say ""
+
+        js_pipeline = detect_js_pipeline
+        case js_pipeline
+        when :importmap
+          say "Importmap detected. Add to config/importmap.rb:"
+          say '  pin "remote_select"'
+          say ""
+          say "And in app/javascript/application.js:"
+          say '  import "remote_select"'
+        when :esbuild, :rollup, :webpack
+          say "#{js_pipeline} detected. Add to app/javascript/application.js:"
+          say '  import "./remote_select"'
+        else
+          say "Add to your JS entry point:"
+          say '  import "./remote_select"'
+        end
+
+        say ""
+
+        css_pipeline = detect_css_pipeline
+        case css_pipeline
+        when :cssbundling
+          say "cssbundling (sass) detected. Add to your main SCSS/CSS entry:"
+          say '  @import "./remote_select";'
+        when :sprockets
+          say "Sprockets detected. Add to application.css:"
+          say '  *= require remote_select'
+        else
+          say "Add to your CSS entry point:"
+          say '  @import "./remote_select";'
+          say '  or (Sprockets): *= require remote_select'
+        end
+      end
+
+      private
+
+      def app_root
+        Pathname.new(destination_root)
+      end
+
+      def detect_js_pipeline
+        return :importmap if app_root.join("config/importmap.rb").exist?
+
+        pkg = read_package_json
+        return nil unless pkg
+
+        build_script = pkg.dig("scripts", "build") || ""
+        deps = (pkg["dependencies"] || {}).merge(pkg["devDependencies"] || {})
+
+        return :esbuild  if deps.key?("esbuild") || build_script.include?("esbuild")
+        return :rollup   if deps.key?("rollup")  || build_script.include?("rollup")
+        return :webpack  if deps.key?("webpack") || build_script.include?("webpack")
+
+        nil
+      end
+
+      def detect_css_pipeline
+        pkg = read_package_json
+        if pkg
+          build_css = pkg.dig("scripts", "build:css") || ""
+          deps = (pkg["dependencies"] || {}).merge(pkg["devDependencies"] || {})
+          return :cssbundling if build_css.include?("sass") || deps.key?("sass")
+        end
+
+        if app_root.join("app/assets/stylesheets/application.css").exist?
+          return :sprockets
+        end
+
+        nil
+      end
+
+      def read_package_json
+        path = app_root.join("package.json")
+        return nil unless path.exist?
+        JSON.parse(path.read)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/remote_select/version.rb

@@ -1,3 +1,3 @@
 module RemoteSelect
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: remote_select
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ghennadii Mir
@@ -35,11 +35,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- COPILOT_INSTRUCTIONS.md
 - LICENSE
 - README.md
 - app/assets/stylesheets/remote_select.css
 - app/javascript/remote_select.js
 - config/locales/en.yml
+- lib/generators/remote_select/install_generator.rb
 - lib/remote_select.rb
 - lib/remote_select/engine.rb
 - lib/remote_select/version.rb