remote_select 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4cce3aae6bcdda3d4094e25da7d93613b40d1971a6e62284dd0f8416569e4fa4
+  data.tar.gz: 3f4d2f7cc3ce1f84e87b4da8b5b1c9b9e33611bfae03a03e354ea2d4d6db005d
+SHA512:
+  metadata.gz: 2d0f92bff38d7f97943075af39052ff425cd3a1e1a6314bafaa3ddb0073383c2d716bc01dc00831657858187fa4e47c55567bc2e98f62a647fb61b3b23961d62
+  data.tar.gz: 95699a31cdf43ba2ff131e4bd9a017380da506f21d6f1946af94d9b5712da2e51383414e718903afb0fc5288aed498ed4f440f2d6fb111010e5c9fad7b022c98

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-20
+
+### Added
+- Initial release
+- `remote_select` form helper
+- Vanilla JS widget (`RemoteSelect`) with remote data fetching
+- Keyboard navigation and full ARIA support
+- Pagination (infinite scroll)
+- Dependent selects with auto-clearing
+- Turbo (full-page + Frames) compatibility
+- i18n support via Rails `I18n.t`
+- CSS custom properties for zero-fork theming

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ghennadii Mir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,216 @@
+# remote_select
+
+A lightweight, zero-dependency Rails form helper that renders a searchable select whose options are fetched from a JSON endpoint.
+
+Replaces Select2 / Tom Select for the common case of "type to search a remote list" — with no npm packages, no jQuery, and full Turbo support.
+
+## Features
+
+- **Remote data fetching** with debouncing and request cancellation (AbortController)
+- **Keyboard navigation** — ↑↓ arrows, Enter to select, Escape to close
+- **Full ARIA** — `role="combobox"`, `aria-expanded`, `aria-activedescendant`, `role="listbox"`
+- **Pagination** — infinite scroll loading of additional results
+- **Dependent selects** — pass values from other fields as query parameters automatically
+- **Auto-clearing** — clear selection when a dependency changes
+- **Minimum character threshold** — configurable before search fires
+- **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
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "remote_select"
+```
+
+Run:
+
+```bash
+bundle install
+```
+
+### JavaScript
+
+**Importmap** (Rails 8 default):
+
+```ruby
+# config/importmap.rb
+pin "remote_select", to: "remote_select.js"
+```
+
+```js
+// app/javascript/application.js
+import "remote_select"
+```
+
+**esbuild / rollup / webpack**:
+
+```js
+import "remote_select"
+```
+
+**Sprockets** (`application.js`):
+
+```js
+//= require remote_select
+```
+
+### Stylesheet
+
+**Sass / SCSS**:
+
+```scss
+@import 'remote_select';
+```
+
+**Sprockets** (`application.css`):
+
+```css
+/*= require remote_select */
+```
+
+## Usage
+
+### Basic
+
+```erb
+<%= form_with model: @article do |form| %>
+  <%= form.label :company_id %>
+  <%= remote_select(form, :company_id, search_companies_path,
+        placeholder: "Type to search companies...",
+        min_chars: 2) %>
+<% end %>
+```
+
+### With preselected value
+
+```erb
+<%= remote_select(form, :company_id, search_companies_path,
+      selected_value: @article.company_id,
+      selected_text:  @article.company&.name) %>
+```
+
+### Dependent select (clears when parent changes)
+
+```erb
+<%# Parent — standard Rails select %>
+<%= form.select :source, sources_options, {}, { id: "source-selector" } %>
+
+<%# Child — clears and re-fetches when source changes %>
+<%= remote_select(form, :company_id, search_companies_path,
+      depends_on: "#source-selector",
+      clear_on_dependency_change: true) %>
+```
+
+### Multiple dependencies
+
+```erb
+<%= remote_select(form, :city_id, search_cities_path,
+      depends_on: "#state-selector, #country-selector") %>
+```
+
+## Helper options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `endpoint` | String | required | JSON endpoint URL |
+| `selected_value` | String/Integer | `nil` | Pre-selected value ID |
+| `selected_text` | String | `nil` | Pre-selected display text |
+| `min_chars` | Integer | `2` | Chars needed before search fires |
+| `debounce_delay` | Integer | `250` | Debounce in milliseconds |
+| `placeholder` | String | i18n | Placeholder text |
+| `per_page` | Integer | `20` | Results per page |
+| `depends_on` | String | `nil` | CSS selector(s) of dependency field(s) |
+| `clear_on_dependency_change` | Boolean | `true` | Clear when dependency changes |
+| `empty_text` | String | i18n | Text shown when no results |
+| `loading_text` | String | i18n | Text shown while loading |
+| `html` | Hash | `{}` | Extra HTML attrs on the hidden input |
+
+## i18n
+
+Override any key in your locale files:
+
+```yaml
+# config/locales/en.yml
+en:
+  remote_select:
+    placeholder: "Type to search..."
+    empty_text: "No results found"
+    loading_text: "Loading..."
+```
+
+## Backend endpoint
+
+Your action must return JSON:
+
+```ruby
+def search_companies
+  query    = params[:q].to_s.strip
+  page     = (params[:page] || 1).to_i
+  per_page = (params[:per_page] || 20).to_i
+
+  companies = Company.order(:name)
+  companies = companies.where("name ILIKE ?", "%#{query}%") if query.present?
+
+  total   = companies.count
+  results = companies.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,
+    total:    total
+  }
+end
+```
+
+### Required response shape
+
+```json
+{
+  "results":  [{ "id": 1, "text": "Acme Corp" }],
+  "has_more": true,
+  "total":    150
+}
+```
+
+## Theming
+
+All visual properties are CSS custom properties on `.remote-select-container`. Override without touching the stylesheet:
+
+```css
+.my-form .remote-select-container {
+  --rs-focus-border-color: #198754;
+  --rs-focus-shadow: 0 0 0 0.25rem rgba(25, 135, 84, 0.25);
+  --rs-item-hover-bg: #d1e7dd;
+  --rs-border-radius: 0.25rem;
+  --rs-dropdown-max-height: 400px;
+}
+```
+
+## JavaScript API
+
+```js
+// Manual init
+const rs = new RemoteSelect(document.querySelector('#my-input'), {
+  endpoint: '/api/search',
+  minChars: 3
+});
+
+rs.setParam('category', 'books'); // add extra query param
+rs.clearParams();                 // remove all extra params
+rs.clearSelection();
+rs.openDropdown();
+rs.closeDropdown();
+rs.destroy();                     // remove all listeners + DOM
+```
+
+## Browser support
+
+Modern browsers (Chrome, Firefox, Safari, Edge). Requires ES2020 (`??`, `async/await`, `AbortController`). No IE11.
+
+## License
+
+MIT

data/app/assets/stylesheets/remote_select.css

@@ -0,0 +1,238 @@
+/* RemoteSelect component styles */
+
+/* ── Theming variables ────────────────────────────────────────────────────── */
+/* All colors and key measurements are CSS custom properties.                  */
+/* Override any of these on .remote-select-container (or :root) to retheme    */
+/* without touching this stylesheet.                                           */
+.remote-select-container {
+  --rs-text-color:          #212529;
+  --rs-muted-color:         #6c757d;
+  --rs-bg-color:            #fff;
+  --rs-border-color:        #dee2e6;
+  --rs-border-hover-color:  #adb5bd;
+  --rs-border-radius:       0.375rem;
+  --rs-focus-border-color:  #86b7fe;
+  --rs-focus-shadow:        0 0 0 0.25rem rgba(13, 110, 253, 0.25);
+  --rs-item-hover-bg:       #e9ecef;
+  --rs-item-hover-color:    #1e2125;
+  --rs-item-active-bg:      #dee2e6;
+  --rs-item-active-color:   #000;
+  --rs-error-color:         #dc3545;
+  --rs-error-bg:            #f8d7da;
+  --rs-shimmer-color:       #f8f9fa;
+  --rs-zindex:              1050;
+  --rs-dropdown-max-height: 300px;
+  --rs-results-max-height:  250px;
+
+  position: relative;
+  width: 100%;
+}
+
+.remote-select-trigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.375rem 2.25rem 0.375rem 0.75rem;
+  font-size: 1rem;
+  font-weight: 400;
+  line-height: 1.5;
+  color: var(--rs-text-color);
+  background-color: var(--rs-bg-color);
+  background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23343a40' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/%3e%3c/svg%3e");
+  background-repeat: no-repeat;
+  background-position: right 0.75rem center;
+  background-size: 16px 12px;
+  border: 1px solid var(--rs-border-color);
+  border-radius: var(--rs-border-radius);
+  appearance: none;
+  cursor: pointer;
+  user-select: none;
+  transition: border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out;
+}
+
+.remote-select-trigger:hover {
+  border-color: var(--rs-border-hover-color);
+  cursor: pointer;
+}
+
+.remote-select-trigger:focus,
+.remote-select-trigger:focus-visible {
+  color: var(--rs-text-color);
+  background-color: var(--rs-bg-color);
+  border-color: var(--rs-focus-border-color);
+  outline: 0;
+  box-shadow: var(--rs-focus-shadow);
+}
+
+.remote-select-trigger:disabled {
+  color: var(--rs-muted-color);
+  background-color: var(--rs-item-hover-bg);
+  border-color: var(--rs-border-color);
+  cursor: not-allowed;
+  opacity: 1;
+}
+
+.remote-select-value {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--rs-muted-color);
+  cursor: pointer;
+}
+
+.remote-select-trigger.has-value .remote-select-value {
+  color: var(--rs-text-color);
+  font-weight: 400;
+}
+
+.remote-select-arrow {
+  display: none;
+}
+
+/* Dropdown: hidden by default, shown when container has .is-open */
+.remote-select-dropdown {
+  display: none;
+  position: absolute;
+  top: calc(100% + 0.125rem);
+  left: 0;
+  right: 0;
+  z-index: var(--rs-zindex);
+  background-color: var(--rs-bg-color);
+  border: 1px solid rgba(0, 0, 0, 0.15);
+  border-radius: var(--rs-border-radius);
+  box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
+  max-height: var(--rs-dropdown-max-height);
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.remote-select-container.is-open .remote-select-dropdown {
+  display: flex;
+}
+
+.remote-select-search {
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  border: none;
+  border-bottom: 1px solid var(--rs-border-color);
+  font-size: 0.875rem;
+  line-height: 1.5;
+  color: var(--rs-text-color);
+  background-color: var(--rs-bg-color);
+  outline: none;
+  cursor: text;
+}
+
+.remote-select-search::placeholder {
+  color: var(--rs-muted-color);
+  opacity: 1;
+}
+
+.remote-select-search:focus {
+  color: var(--rs-text-color);
+  background-color: var(--rs-bg-color);
+  border-bottom-color: var(--rs-focus-border-color);
+  outline: 0;
+  box-shadow: inset 0 -1px 0 0 rgba(13, 110, 253, 0.25);
+}
+
+.remote-select-results {
+  flex: 1;
+  overflow-y: auto;
+  max-height: var(--rs-results-max-height);
+  padding: 0.25rem 0;
+  scrollbar-width: thin;
+  scrollbar-color: var(--rs-border-color) transparent;
+}
+
+.remote-select-item {
+  padding: 0.375rem 0.75rem;
+  font-size: 1rem;
+  color: var(--rs-text-color);
+  cursor: pointer;
+  transition: background-color 0.15s ease, color 0.15s ease;
+  user-select: none;
+}
+
+.remote-select-item:hover,
+.remote-select-item.is-focused {
+  background-color: var(--rs-item-hover-bg);
+  color: var(--rs-item-hover-color);
+  outline: none;
+}
+
+.remote-select-item:active {
+  background-color: var(--rs-item-active-bg);
+  color: var(--rs-item-active-color);
+}
+
+.remote-select-item:first-child {
+  margin-top: 0;
+}
+
+.remote-select-item:last-child {
+  margin-bottom: 0;
+}
+
+.remote-select-message {
+  padding: 0.75rem;
+  text-align: center;
+  color: var(--rs-muted-color);
+  font-size: 0.875rem;
+  font-style: italic;
+  user-select: none;
+}
+
+.remote-select-message.remote-select-error {
+  color: var(--rs-error-color);
+  background-color: var(--rs-error-bg);
+}
+
+.remote-select-message.remote-select-loader {
+  font-style: normal;
+  background: linear-gradient(90deg, transparent, var(--rs-shimmer-color), transparent);
+  background-size: 200px 100%;
+  animation: rs-loading-shimmer 1.5s infinite;
+}
+
+@keyframes rs-loading-shimmer {
+  0%   { background-position: -200px 0; }
+  100% { background-position: calc(200px + 100%) 0; }
+}
+
+/* Scrollbar styling for results (webkit browsers) */
+.remote-select-results::-webkit-scrollbar {
+  width: 6px;
+}
+
+.remote-select-results::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.remote-select-results::-webkit-scrollbar-thumb {
+  background: var(--rs-border-color);
+  border-radius: 3px;
+}
+
+.remote-select-results::-webkit-scrollbar-thumb:hover {
+  background: var(--rs-border-hover-color);
+}
+
+/* Loading state for trigger */
+.remote-select-trigger.loading {
+  background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='%23343a40' d='M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0zM7 4v4.07L9.5 9.5l.707-.707L8 6.586V4H7z'/%3e%3c/svg%3e");
+  pointer-events: none;
+  opacity: 0.7;
+}
+
+/* Responsive adjustments */
+@media (max-width: 576px) {
+  .remote-select-dropdown {
+    max-height: 60vh;
+  }
+
+  .remote-select-results {
+    max-height: calc(60vh - 60px);
+  }
+}

data/app/javascript/remote_select.js

@@ -0,0 +1,456 @@
+/**
+ * RemoteSelect - Vanilla JS remote data select component
+ * A lightweight replacement for select2/tom-select with remote data source
+ * 
+ * Features:
+ * - Remote data fetching with debouncing
+ * - Pagination support
+ * - Dynamic parameters (e.g., dependent selects)
+ * - Minimum character threshold
+ * - Preselected values
+ * - No jQuery dependency
+ */
+class RemoteSelect {
+  constructor(element, options = {}) {
+    this.element = element;
+    const ds = element.dataset;
+
+    // Options: JS options take precedence over data attributes, falling back to defaults.
+    // The object is built explicitly — no spread of raw `options` after parsed values,
+    // which would silently re-override the carefully resolved types below.
+    this.options = {
+      endpoint:                options.endpoint                ?? ds.endpoint,
+      minChars:                parseInt(options.minChars       ?? ds.minChars       ?? 2,   10),
+      debounceDelay:           parseInt(options.debounceDelay  ?? ds.debounceDelay  ?? 250, 10),
+      placeholder:             options.placeholder             ?? ds.placeholder             ?? 'Type to search...',
+      perPage:                 parseInt(options.perPage        ?? ds.perPage        ?? 20,  10),
+      dependsOn:               options.dependsOn               ?? ds.dependsOn               ?? null,
+      clearOnDependencyChange: _parseBool(options.clearOnDependencyChange ?? ds.clearOnDependencyChange, true),
+      emptyText:               options.emptyText               ?? ds.emptyText               ?? 'No results found',
+      loadingText:             options.loadingText             ?? ds.loadingText              ?? 'Loading...',
+    };
+
+    this.selectedValue       = ds.selectedValue || '';
+    this.selectedText        = ds.selectedText  || '';
+    this.currentQuery        = '';
+    this.currentPage         = 1;
+    this.hasMore             = false;
+    this.loading             = false;
+    this.debounceTimer       = null;
+    this.results             = [];
+    this.additionalParams    = {};
+    this.focusedIndex        = -1;
+    this._abortController    = null;
+    this._dependencyHandlers = [];
+    // Unique ID prefix for ARIA id references
+    this._uid = `rs-${Math.random().toString(36).slice(2, 9)}`;
+
+    this._init();
+  }
+
+  _init() {
+    this.element.style.display = 'none';
+    this._createUI();
+    this._setupEventListeners();
+    if (this.options.dependsOn) this._setupDependency();
+    if (this.selectedValue && this.selectedText) this._updateTriggerDisplay();
+  }
+
+  _createUI() {
+    this.container = document.createElement('div');
+    this.container.className = 'remote-select-container';
+
+    // Trigger — acts as the visible combobox control
+    this.trigger = document.createElement('div');
+    this.trigger.className = 'remote-select-trigger';
+    this.trigger.setAttribute('tabindex', '0');
+    this.trigger.setAttribute('role', 'combobox');
+    this.trigger.setAttribute('aria-expanded', 'false');
+    this.trigger.setAttribute('aria-haspopup', 'listbox');
+    this.trigger.setAttribute('aria-controls', `${this._uid}-listbox`);
+
+    this.valueSpan = document.createElement('span');
+    this.valueSpan.className = 'remote-select-value';
+    this.valueSpan.textContent = this.selectedText || this.options.placeholder;
+    this.trigger.appendChild(this.valueSpan);
+
+    // Dropdown
+    this.dropdown = document.createElement('div');
+    this.dropdown.className = 'remote-select-dropdown';
+    this.dropdown.id = `${this._uid}-listbox`;
+    this.dropdown.setAttribute('role', 'listbox');
+
+    // Search input inside dropdown
+    this.searchInput = document.createElement('input');
+    this.searchInput.type = 'text';
+    this.searchInput.className = 'remote-select-search';
+    this.searchInput.placeholder = this.options.placeholder;
+    this.searchInput.setAttribute('autocomplete', 'off');
+    this.searchInput.setAttribute('aria-autocomplete', 'list');
+    this.searchInput.setAttribute('aria-controls', `${this._uid}-listbox`);
+
+    // Results container
+    this.resultsContainer = document.createElement('div');
+    this.resultsContainer.className = 'remote-select-results';
+
+    this.dropdown.appendChild(this.searchInput);
+    this.dropdown.appendChild(this.resultsContainer);
+    this.container.appendChild(this.trigger);
+    this.container.appendChild(this.dropdown);
+
+    this.element.parentNode.insertBefore(this.container, this.element.nextSibling);
+  }
+
+  _setupEventListeners() {
+    // Open/close via click on trigger
+    this.trigger.addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.toggleDropdown();
+    });
+
+    // Keyboard activation of trigger (Space/Enter opens; ArrowDown opens and moves focus)
+    this.trigger.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        this.openDropdown();
+      } else if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        this.openDropdown();
+      }
+    });
+
+    // Search input typing
+    this.searchInput.addEventListener('input', (e) => {
+      this._handleSearchInput(e.target.value);
+    });
+
+    // Keyboard navigation within dropdown
+    this.searchInput.addEventListener('keydown', (e) => {
+      this._handleKeyboardNavigation(e);
+    });
+
+    // Infinite scroll pagination
+    this.resultsContainer.addEventListener('scroll', () => {
+      if (this._isScrolledToBottom() && this.hasMore && !this.loading) {
+        this.currentPage++;
+        this._fetchResults(this.currentQuery, true);
+      }
+    });
+
+    // Close on outside click — stored as named ref for cleanup in destroy()
+    this._outsideClickHandler = (e) => {
+      if (!this.container.contains(e.target)) this.closeDropdown();
+    };
+    document.addEventListener('click', this._outsideClickHandler);
+  }
+
+  _handleKeyboardNavigation(e) {
+    const items = Array.from(this.resultsContainer.querySelectorAll('.remote-select-item'));
+    if (!items.length) {
+      if (e.key === 'Escape') { this.closeDropdown(); this.trigger.focus(); }
+      return;
+    }
+
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        this._setFocusedIndex(Math.min(this.focusedIndex + 1, items.length - 1), items);
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        if (this.focusedIndex <= 0) {
+          this._setFocusedIndex(-1, items);
+        } else {
+          this._setFocusedIndex(this.focusedIndex - 1, items);
+        }
+        break;
+      case 'Enter':
+        e.preventDefault();
+        if (this.focusedIndex >= 0 && items[this.focusedIndex]) {
+          items[this.focusedIndex].click();
+        }
+        break;
+      case 'Escape':
+        this.closeDropdown();
+        this.trigger.focus();
+        break;
+    }
+  }
+
+  _setFocusedIndex(newIndex, items) {
+    // Remove highlight from previously focused item
+    if (this.focusedIndex >= 0 && items[this.focusedIndex]) {
+      items[this.focusedIndex].classList.remove('is-focused');
+      items[this.focusedIndex].setAttribute('aria-selected', 'false');
+    }
+
+    this.focusedIndex = newIndex;
+
+    if (newIndex >= 0 && items[newIndex]) {
+      items[newIndex].classList.add('is-focused');
+      items[newIndex].setAttribute('aria-selected', 'true');
+      items[newIndex].scrollIntoView({ block: 'nearest' });
+      this.trigger.setAttribute('aria-activedescendant', items[newIndex].id);
+      this.searchInput.setAttribute('aria-activedescendant', items[newIndex].id);
+    } else {
+      this.trigger.removeAttribute('aria-activedescendant');
+      this.searchInput.removeAttribute('aria-activedescendant');
+    }
+  }
+
+  _setupDependency() {
+    this.options.dependsOn.split(',').map(s => s.trim()).forEach(selector => {
+      const depEl = document.querySelector(selector);
+      if (!depEl) return;
+
+      const handler = (e) => {
+        const key = depEl.name || depEl.id;
+        this.additionalParams[key] = e.target.value;
+        if (this.options.clearOnDependencyChange) this.clearSelection();
+      };
+
+      depEl.addEventListener('change', handler);
+      this._dependencyHandlers.push({ element: depEl, handler });
+
+      // Set initial param value
+      const key = depEl.name || depEl.id;
+      this.additionalParams[key] = depEl.value;
+    });
+  }
+
+  _handleSearchInput(query) {
+    clearTimeout(this.debounceTimer);
+    this.currentQuery = query;
+    this.currentPage  = 1;
+    this.focusedIndex = -1;
+
+    if (query.length < this.options.minChars) {
+      this._setMessage(this.options.placeholder);
+      return;
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      this._fetchResults(query, false);
+    }, this.options.debounceDelay);
+  }
+
+  async _fetchResults(query, append = false) {
+    if (this.loading) return;
+
+    // Cancel any in-flight request so stale results cannot overwrite the current query
+    if (this._abortController) this._abortController.abort();
+    this._abortController = new AbortController();
+
+    this.loading = true;
+    this._showLoading(append);
+
+    try {
+      const url = new URL(this.options.endpoint, window.location.origin);
+      url.searchParams.set('q', query);
+      url.searchParams.set('page', this.currentPage);
+      url.searchParams.set('per_page', this.options.perPage);
+
+      Object.entries(this.additionalParams).forEach(([key, val]) => {
+        if (val !== null && val !== undefined && val !== '') url.searchParams.set(key, val);
+      });
+
+      const response = await fetch(url, {
+        signal: this._abortController.signal,
+        headers: { 'Accept': 'application/json', 'X-Requested-With': 'XMLHttpRequest' },
+      });
+
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+
+      const data   = await response.json();
+      this.results = append ? [...this.results, ...data.results] : data.results;
+      this.hasMore = data.has_more || false;
+      this._renderResults(append);
+    } catch (err) {
+      if (err.name === 'AbortError') return; // request was intentionally cancelled
+      console.error('RemoteSelect fetch error:', err);
+      this._showError();
+    } finally {
+      this.loading = false;
+    }
+  }
+
+  _showLoading(append) {
+    if (!append) {
+      this._setMessage(this.options.loadingText, 'remote-select-loader');
+    } else {
+      const loader = document.createElement('div');
+      loader.className = 'remote-select-message remote-select-loader';
+      loader.textContent = this.options.loadingText;
+      this.resultsContainer.appendChild(loader);
+    }
+  }
+
+  _showError() {
+    this._setMessage('Error loading results', 'remote-select-error');
+  }
+
+  // Clear the results area and render a single status message (safe — uses textContent)
+  _setMessage(text, extraClass = '') {
+    this.resultsContainer.innerHTML = '';
+    const msg = document.createElement('div');
+    msg.className = ['remote-select-message', extraClass].filter(Boolean).join(' ');
+    msg.textContent = text;
+    this.resultsContainer.appendChild(msg);
+  }
+
+  _renderResults(append) {
+    if (!append) {
+      this.resultsContainer.innerHTML = '';
+      this.focusedIndex = -1;
+    } else {
+      const loader = this.resultsContainer.querySelector('.remote-select-loader');
+      if (loader) loader.remove();
+    }
+
+    if (this.results.length === 0 && !append) {
+      this._setMessage(this.options.emptyText);
+      return;
+    }
+
+    const toRender = append ? this.results.slice(-this.options.perPage) : this.results;
+
+    toRender.forEach(result => {
+      const escapedId = CSS.escape(String(result.id));
+      if (append && this.resultsContainer.querySelector(`[data-value="${escapedId}"]`)) return;
+
+      const item = document.createElement('div');
+      item.className    = 'remote-select-item';
+      item.id           = `${this._uid}-option-${result.id}`;
+      item.dataset.value = result.id;
+      item.textContent  = result.text; // textContent — never innerHTML — prevents XSS
+      item.setAttribute('role', 'option');
+      item.setAttribute('aria-selected', 'false');
+
+      item.addEventListener('click', (e) => {
+        e.stopPropagation();
+        this.selectItem(result.id, result.text);
+      });
+
+      this.resultsContainer.appendChild(item);
+    });
+  }
+
+  // ─── Public API ───────────────────────────────────────────────────────────
+
+  selectItem(value, text) {
+    this.selectedValue = value;
+    this.selectedText  = text;
+    this.element.value = value;
+    this.element.dispatchEvent(new Event('change', { bubbles: true }));
+    this._updateTriggerDisplay();
+    this.closeDropdown();
+    this.trigger.focus();
+  }
+
+  clearSelection() {
+    this.selectedValue = '';
+    this.selectedText  = '';
+    this.element.value = '';
+    this._updateTriggerDisplay();
+    this.element.dispatchEvent(new Event('change', { bubbles: true }));
+  }
+
+  toggleDropdown() {
+    this.container.classList.contains('is-open') ? this.closeDropdown() : this.openDropdown();
+  }
+
+  openDropdown() {
+    if (this.container.classList.contains('is-open')) return;
+    this.container.classList.add('is-open');
+    this.trigger.setAttribute('aria-expanded', 'true');
+    this.searchInput.value = '';
+    this.currentQuery = '';
+    this.currentPage  = 1;
+    this.focusedIndex = -1;
+    this._setMessage(this.options.placeholder);
+    this.searchInput.focus();
+  }
+
+  closeDropdown() {
+    if (!this.container.classList.contains('is-open')) return;
+    this.container.classList.remove('is-open');
+    this.trigger.setAttribute('aria-expanded', 'false');
+    this.trigger.removeAttribute('aria-activedescendant');
+    this.searchInput.removeAttribute('aria-activedescendant');
+    this.searchInput.value = '';
+    this.focusedIndex = -1;
+  }
+
+  setParam(key, value) { this.additionalParams[key] = value; }
+  clearParams() { this.additionalParams = {}; }
+
+  destroy() {
+    if (this._abortController) this._abortController.abort();
+    document.removeEventListener('click', this._outsideClickHandler);
+    this._dependencyHandlers.forEach(({ element, handler }) => {
+      element.removeEventListener('change', handler);
+    });
+    this._dependencyHandlers = [];
+    this.container.remove();
+    this.element.style.display = '';
+  }
+
+  // ─── Private helpers ─────────────────────────────────────────────────────
+
+  _updateTriggerDisplay() {
+    this.valueSpan.textContent = this.selectedText || this.options.placeholder;
+    this.trigger.classList.toggle('has-value', Boolean(this.selectedValue));
+  }
+
+  _isScrolledToBottom() {
+    const { scrollHeight, scrollTop, clientHeight } = this.resultsContainer;
+    return scrollHeight - scrollTop - clientHeight < 50;
+  }
+}
+
+// ─── Module-level helpers ─────────────────────────────────────────────────────
+
+function _parseBool(value, defaultValue) {
+  if (value === undefined || value === null) return defaultValue;
+  if (typeof value === 'boolean') return value;
+  return value !== 'false' && value !== '0';
+}
+
+// ─── Auto-init (Turbo-compatible, no Stimulus required) ──────────────────────
+
+const _rsInstances = new WeakMap();
+
+function _rsInit(root = document) {
+  root.querySelectorAll('[data-remote-select]').forEach(el => {
+    if (!_rsInstances.has(el)) _rsInstances.set(el, new RemoteSelect(el));
+  });
+}
+
+function _rsDestroy(root = document) {
+  root.querySelectorAll('[data-remote-select]').forEach(el => {
+    if (_rsInstances.has(el)) {
+      _rsInstances.get(el).destroy();
+      _rsInstances.delete(el);
+    }
+  });
+}
+
+// Works without Turbo — fires on plain page load
+document.addEventListener('DOMContentLoaded', () => _rsInit());
+
+// Turbo full-page navigation (no-op if Turbo is not present)
+document.addEventListener('turbo:load', () => _rsInit());
+
+// Turbo Frames — scope init to just the updated frame element
+document.addEventListener('turbo:frame-load', (e) => _rsInit(e.target));
+
+// Cleanup before Turbo replaces the DOM — removes event listeners before elements are gone
+document.addEventListener('turbo:before-render',       (e) => _rsDestroy(e.detail.newBody));
+document.addEventListener('turbo:before-frame-render', (e) => _rsDestroy(e.target));
+
+// Global export for <script> tag / CDN usage
+window.RemoteSelect = RemoteSelect;
+
+// ESM export for importmaps (Rails 8 default) and bundlers (esbuild, rollup, etc.)
+export { RemoteSelect };
+export default RemoteSelect;

data/config/locales/en.yml

@@ -0,0 +1,5 @@
+en:
+  remote_select:
+    placeholder: "Type to search..."
+    empty_text: "No results found"
+    loading_text: "Loading..."

data/lib/remote_select/engine.rb

@@ -0,0 +1,11 @@
+module RemoteSelect
+  class Engine < ::Rails::Engine
+    isolate_namespace RemoteSelect
+
+    initializer "remote_select.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include RemoteSelect::ViewHelpers
+      end
+    end
+  end
+end

data/lib/remote_select/version.rb

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

data/lib/remote_select/view_helpers.rb

@@ -0,0 +1,54 @@
+module RemoteSelect
+  module ViewHelpers
+    # Renders a remote-data searchable select for a Rails form.
+    #
+    # @param form      [ActionView::Helpers::FormBuilder] Rails form builder
+    # @param attribute [Symbol]  model attribute (becomes the hidden field name)
+    # @param endpoint  [String]  URL that returns JSON { results: [...], has_more: bool }
+    # @param options   [Hash]    see below
+    #
+    # Options:
+    #   :selected_value            [String/Integer] pre-selected value id
+    #   :selected_text             [String]         pre-selected display text
+    #   :min_chars                 [Integer]        chars needed before search fires (default: 2)
+    #   :debounce_delay            [Integer]        debounce in ms (default: 250)
+    #   :placeholder               [String]         i18n: remote_select.placeholder
+    #   :per_page                  [Integer]        results per page (default: 20)
+    #   :depends_on                [String]         CSS selector(s) of dependency field(s)
+    #   :clear_on_dependency_change [Boolean]       clear on dependency change (default: true)
+    #   :empty_text                [String]         i18n: remote_select.empty_text
+    #   :loading_text              [String]         i18n: remote_select.loading_text
+    #   :html                      [Hash]           extra HTML attrs for the hidden input
+    #
+    def remote_select(form, attribute, endpoint, options = {})
+      selected_value = options.delete(:selected_value) || form.object.try(attribute)
+      selected_text  = options.delete(:selected_text)
+      html_options   = options.delete(:html) || {}
+
+      data_attrs = {
+        remote_select:  true,
+        endpoint:       endpoint,
+        selected_value: selected_value,
+        selected_text:  selected_text
+      }
+
+      data_attrs[:placeholder]  = options[:placeholder]  || I18n.t("remote_select.placeholder",  default: "Type to search...")
+      data_attrs[:empty_text]   = options[:empty_text]   || I18n.t("remote_select.empty_text",   default: "No results found")
+      data_attrs[:loading_text] = options[:loading_text] || I18n.t("remote_select.loading_text", default: "Loading...")
+
+      %i[min_chars debounce_delay per_page depends_on].each do |key|
+        data_attrs[key] = options[key] if options[key].present?
+      end
+
+      unless options[:clear_on_dependency_change].nil?
+        data_attrs[:clear_on_dependency_change] = options[:clear_on_dependency_change]
+      end
+
+      html_options[:data] ||= {}
+      html_options[:data].merge!(data_attrs)
+      html_options[:class] = [html_options[:class], "remote-select-input"].compact.join(" ")
+
+      form.hidden_field(attribute, html_options)
+    end
+  end
+end

data/lib/remote_select.rb

@@ -0,0 +1,7 @@
+require "remote_select/version"
+require "remote_select/view_helpers"
+
+module RemoteSelect
+  # Engine is only loaded in a Rails context
+  require "remote_select/engine" if defined?(Rails)
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: remote_select
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ghennadii Mir
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: |
+  A zero-dependency Rails form helper that renders a searchable dropdown
+  whose options are fetched from a JSON endpoint. Supports pagination,
+  dependent selects, keyboard navigation, full ARIA, i18n, and Turbo.
+email:
+- ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/assets/stylesheets/remote_select.css
+- app/javascript/remote_select.js
+- config/locales/en.yml
+- lib/remote_select.rb
+- lib/remote_select/engine.rb
+- lib/remote_select/version.rb
+- lib/remote_select/view_helpers.rb
+homepage: https://github.com/GhennadiiMir/remote_select
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/GhennadiiMir/remote_select
+  source_code_uri: https://github.com/GhennadiiMir/remote_select
+  changelog_uri: https://github.com/GhennadiiMir/remote_select/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Lightweight vanilla-JS remote-data select for Rails forms
+test_files: []