country_state_select 3.2.0 → 4.0.0

data/app/javascript/country_state_select/country_state_select.js

@@ -0,0 +1,245 @@
+// Dependency-free core: no jQuery required. Works as an ES module (npm,
+// importmap-rails, esbuild/webpack) and is also compiled by `rake js:build`
+// into a plain-script build for Sprockets users — see
+// vendor/assets/javascript/country_state_select_vanilla.js. Keep this file
+// as the single source of truth; edit the compiled build only by re-running
+// `rake js:build`.
+//
+// The legacy jQuery + Chosen implementation
+// (vendor/assets/javascript/country_state_select.js.erb) is kept for
+// backward compatibility but is deprecated — new apps should use this file,
+// optionally through the bundled Stimulus controller (controller.js).
+
+export default function CountryStateSelect(options) {
+  var countryId = options.country_id;
+  var stateId = options.state_id;
+  var cityId = options.city_id;
+  var hasCityField = !!cityId;
+  var announce = options.announce !== false;
+  var offlineData = options.offline_data || null;
+  var statesUrl = options.states_url || '/find_states';
+  var citiesUrl = options.cities_url || '/find_cities';
+  var enhancer = options.enhance; // optional fn(selectEl, tomSelectOptions) e.g. Tom Select hookup
+  var enhancerOptions = options.enhance_options || {};
+  var liveRegion = announce ? ensureLiveRegion() : null;
+
+  var enhancedInstances = {};
+
+  init();
+
+  return { refresh: init, destroy: destroy };
+
+  // ====== ***** INITIALIZATION ***** ===================================== //
+
+  function init() {
+    enhance(countryId);
+
+    var countryEl = document.getElementById(countryId);
+    if (!countryEl) return;
+
+    countryEl.addEventListener('change', function () {
+      findStates(countryEl.value, { userInitiated: true });
+    });
+
+    if (hasCityField) {
+      document.addEventListener('change', delegatedStateChange);
+    }
+
+    // Edit-form support: a server-rendered form (e.g. via the FormBuilder
+    // helpers, which read the model's current country/state to pick the
+    // right <select> options) already shows the correct state/city on
+    // load — trust it and only enhance it, rather than discarding it for
+    // a fresh, unselected fetch. Only fetch here for fields that truly
+    // need it: a plain/manual integration where the target is still a
+    // blank shell (a text input, or a <select> with no real options),
+    // even though the country already has a value. Pre-selection for that
+    // fetch comes from an explicit option or a `data-selected-value`/
+    // `data-selected-city` attribute.
+    var countryValue = countryEl.value;
+    var stateEl = document.getElementById(stateId);
+    var cityEl = hasCityField ? document.getElementById(cityId) : null;
+
+    if (isPopulated(stateEl)) {
+      enhance(stateId);
+    } else if (countryValue) {
+      var preselectedState = options.selected_state || (stateEl && stateEl.getAttribute('data-selected-value'));
+      findStates(countryValue, { preselect: preselectedState, silent: true });
+      return; // findStates cascades into the city fetch itself once it resolves
+    }
+
+    if (isPopulated(cityEl)) {
+      enhance(cityId);
+    } else if (hasCityField && stateEl && stateEl.value) {
+      var preselectedCity = options.selected_city || (cityEl && cityEl.getAttribute('data-selected-city'));
+      findCities(stateEl.value, countryValue, { preselect: preselectedCity, silent: true });
+    }
+  }
+
+  function isPopulated(el) {
+    return !!el && el.tagName === 'SELECT' && el.options.length > 1;
+  }
+
+  function destroy() {
+    document.removeEventListener('change', delegatedStateChange);
+  }
+
+  function delegatedStateChange(event) {
+    if (event.target && event.target.id === stateId) {
+      findCities(event.target.value, document.getElementById(countryId).value, { userInitiated: true });
+    }
+  }
+
+  // ====== ***** DATA LOOKUP ***** ========================================= //
+
+  function findStates(countryCode, ctx) {
+    ctx = ctx || {};
+    if (ctx.userInitiated) findCities('', '', { silent: true });
+
+    if (offlineData && offlineData.states) {
+      buildStatesDropdown(offlineData.states[countryCode] || [], ctx);
+      return;
+    }
+
+    fetchJson(statesUrl, { country_id: countryCode }).then(function (data) {
+      buildStatesDropdown(data || [], ctx);
+    });
+  }
+
+  function findCities(stateCode, countryCode, ctx) {
+    ctx = ctx || {};
+    if (!hasCityField) return;
+
+    if (offlineData && offlineData.cities) {
+      var key = countryCode + ':' + stateCode;
+      buildCitiesDropdown(offlineData.cities[key] || [], ctx);
+      return;
+    }
+
+    fetchJson(citiesUrl, { country_id: countryCode, state_id: stateCode }).then(function (data) {
+      buildCitiesDropdown(data || [], ctx);
+    });
+  }
+
+  function fetchJson(url, params) {
+    var query = Object.keys(params)
+      .map(function (k) { return encodeURIComponent(k) + '=' + encodeURIComponent(params[k] == null ? '' : params[k]); })
+      .join('&');
+
+    return fetch(url + '?' + query, {
+      headers: { Accept: 'application/json' },
+      credentials: 'same-origin'
+    }).then(function (response) {
+      if (!response.ok) return [];
+      return response.json();
+    }).catch(function () {
+      return [];
+    });
+  }
+
+  // ====== ***** DOM BUILDING ***** ======================================== //
+
+  function buildStatesDropdown(data, ctx) {
+    rebuildField(stateId, data, ctx.preselect, options.state_placeholder);
+    if (!ctx.silent) announceUpdate('State options updated');
+
+    var countryHasChanged = ctx.userInitiated;
+    if (hasCityField) {
+      if (countryHasChanged) {
+        findCities('', '', { silent: true });
+      } else if (ctx.preselect !== undefined) {
+        var stateEl = document.getElementById(stateId);
+        var preselectedCity = options.selected_city || (stateEl && stateEl.getAttribute('data-selected-city'));
+        findCities(stateEl ? stateEl.value : '', countryId && document.getElementById(countryId).value, {
+          preselect: preselectedCity,
+          silent: true
+        });
+      }
+    }
+  }
+
+  function buildCitiesDropdown(data, ctx) {
+    rebuildField(cityId, data.map(function (name) { return [name, name]; }), ctx.preselect, options.city_placeholder);
+    if (!ctx.silent) announceUpdate('City options updated');
+  }
+
+  // Rebuilds `fieldId` as a <select> (data present) or a plain text <input>
+  // (no data for the parent selection) while preserving its id/name/class —
+  // mutating the existing node in place rather than replaceWith() keeps
+  // external references (Tom Select instances, other listeners) valid.
+  function rebuildField(fieldId, pairs, preselectValue, placeholder) {
+    var el = document.getElementById(fieldId);
+    if (!el) return;
+
+    destroyEnhancement(fieldId);
+
+    if (!pairs || pairs.length === 0) {
+      var input = document.createElement('input');
+      input.type = 'text';
+      input.id = fieldId;
+      input.name = el.name;
+      input.className = el.className;
+      el.replaceWith(input);
+      return;
+    }
+
+    var select = document.createElement('select');
+    select.id = fieldId;
+    select.name = el.name;
+    select.className = el.className;
+
+    var blank = document.createElement('option');
+    blank.textContent = placeholder || '';
+    blank.value = '';
+    select.appendChild(blank);
+
+    pairs.forEach(function (pair) {
+      var opt = document.createElement('option');
+      opt.value = pair[0];
+      opt.textContent = pair[1];
+      if (preselectValue != null && String(pair[0]) === String(preselectValue)) {
+        opt.selected = true;
+      }
+      select.appendChild(opt);
+    });
+
+    el.replaceWith(select);
+    enhance(fieldId);
+  }
+
+  function enhance(fieldId) {
+    if (!fieldId || typeof enhancer !== 'function') return;
+    var el = document.getElementById(fieldId);
+    if (!el || el.tagName !== 'SELECT') return;
+
+    enhancedInstances[fieldId] = enhancer(el, enhancerOptions);
+  }
+
+  function destroyEnhancement(fieldId) {
+    var instance = enhancedInstances[fieldId];
+    if (instance && typeof instance.destroy === 'function') instance.destroy();
+    delete enhancedInstances[fieldId];
+  }
+
+  // ====== ***** ACCESSIBILITY ***** ======================================= //
+
+  function ensureLiveRegion() {
+    var existing = document.getElementById('country-state-select-live-region');
+    if (existing) return existing;
+
+    var region = document.createElement('div');
+    region.id = 'country-state-select-live-region';
+    region.setAttribute('aria-live', 'polite');
+    region.setAttribute('role', 'status');
+    region.style.position = 'absolute';
+    region.style.width = '1px';
+    region.style.height = '1px';
+    region.style.overflow = 'hidden';
+    region.style.clip = 'rect(0 0 0 0)';
+    document.body.appendChild(region);
+    return region;
+  }
+
+  function announceUpdate(message) {
+    if (liveRegion) liveRegion.textContent = message;
+  }
+}

data/config/importmap.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+pin 'country_state_select', to: 'country_state_select/country_state_select.js'
+pin 'country_state_select/controller', to: 'country_state_select/controller.js'

data/config/routes.rb

@@ -1,8 +1,18 @@
 # frozen_string_literal: true
 
-Rails.application.routes.draw do
-  scope module: 'country_state_select' do
-    post 'find_states' => 'cscs#find_states'
-    post 'find_cities' => 'cscs#find_cities'
+# Rails loads (evals) every engine's config/routes.rb as a plain file each
+# time routes are drawn, expecting it to call `.draw` itself — that's why
+# this isn't wrapped in the usual `Engine.routes.draw` block. Guarding on
+# `draw_routes` here (rather than only documenting an opt-out) is what lets
+# a host app disable the top-level /find_states, /find_cities routes and
+# mount the engine at a custom path instead — see README "Custom route path".
+if CountryStateSelect.configuration.draw_routes
+  Rails.application.routes.draw do
+    scope module: 'country_state_select' do
+      # GET is the correct verb for these read-only lookups (and sidesteps CSRF).
+      # POST is kept so existing host apps that wired the old routes keep working.
+      match 'find_states' => 'cscs#find_states', via: %i[get post]
+      match 'find_cities' => 'cscs#find_cities', via: %i[get post]
+    end
   end
 end

data/country_state_select.gemspec

@@ -13,16 +13,26 @@ Gem::Specification.new do |spec|
   spec.description   = 'Country State Select is a Ruby Gem that aims to make Country and State/Province selection a cinch in Ruby on Rails environments.'
   spec.homepage      = 'https://github.com/arvindvyas/Country-State-Select'
   spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.1'
 
-  spec.files         = `git ls-files -z`.split("\x0")
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.start_with?('spec/dummy/') }
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'rake', '~> 12.3.3'
-  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'bundler-audit'
+  spec.add_development_dependency 'capybara'
+  spec.add_development_dependency 'importmap-rails'
+  spec.add_development_dependency 'propshaft'
+  spec.add_development_dependency 'puma'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec-rails'
+  spec.add_development_dependency 'sqlite3'
+  spec.add_development_dependency 'stimulus-rails'
 
   spec.add_runtime_dependency 'city-state'
-  spec.add_runtime_dependency 'rails'
+  spec.add_runtime_dependency 'rails', '>= 7.0'
 end

data/docs/cities.md

@@ -0,0 +1,35 @@
+# City support
+
+City data comes from the same [city-state](https://github.com/loureirorg/city-state) gem as countries and states. Coverage varies a lot by country — it's strong for the US and reasonably populated for many others, but it is not exhaustive. If a state has no city data, the field falls back to a plain text input, the same way a country with no states falls back for the state field.
+
+Coverage gaps are a known limitation of the underlying data, not something this gem can fix directly — but you're not stuck with it: see [Custom data sources](../README.md#custom-data-sources) in the README to swap in your own city data (a database table, a paid geodata API, etc.) without changing any of your views or JavaScript.
+
+## form_with
+
+```erb
+<div data-controller="country-state-select">
+  <%= f.country_select :country %>
+  <%= f.state_select :state, :country %>
+  <%= f.city_select :city, :state, :country %>
+</div>
+```
+
+`city_select` takes `(method, state_method, country_method, options = {}, html_options = {})` — it reads the model's current state and country to decide whether to render a `<select>` (data available) or a text `<input>` (no data for that state/country pair).
+
+## simple_form
+
+```erb
+<% options = { form: f, field_names: { state: :state_field, country: :country_field } } %>
+<%= f.input :city_field, CountryStateSelect.city_options(options) %>
+```
+
+## Direct API
+
+```ruby
+CountryStateSelect.collect_cities('CA', 'US')
+# => ["Los Angeles", "San Francisco", ...]
+```
+
+## JavaScript
+
+Any of the JS integrations (Stimulus, vanilla/Sprockets, or the legacy jQuery build) pick up a city field automatically when you pass `city_id` (or, for the Stimulus controller, add a `city` target) alongside `country_id`/`state_id`. See the README's [JavaScript setup](../README.md#javascript-setup) section.

data/docs/json-api.md

@@ -0,0 +1,41 @@
+# JSON lookup API
+
+The engine exposes two read-only, cacheable JSON endpoints. They back the bundled JavaScript, but are documented here so a SPA, mobile app, or hand-rolled integration can call them directly.
+
+## `GET /find_states`
+
+**Params:** `country_id` — an ISO 3166-1 alpha-2 country code (e.g. `US`).
+
+**Response:** an array of `[code, name]` pairs, or `[]` if the country has no states.
+
+```
+GET /find_states?country_id=US
+```
+
+```json
+[["AK", "Alaska"], ["AL", "Alabama"], ["AR", "Arkansas"], ...]
+```
+
+Honors whatever `only_countries`/`except_countries`/`priority_countries` and custom `data_source` are configured — it does not bypass your configuration the way calling the underlying data gem directly would.
+
+## `GET /find_cities`
+
+**Params:** `state_id`, `country_id`.
+
+**Response:** an array of plain city name strings, or `[]` if `state_id` is blank or the pair has no data.
+
+```
+GET /find_cities?state_id=CA&country_id=US
+```
+
+```json
+["Los Angeles", "San Francisco", "San Diego", ...]
+```
+
+## Caching
+
+Both endpoints send `Cache-Control` and `ETag` headers based on `CountryStateSelect.configuration.cache_duration` (default: 1 day). A conditional `GET` with a matching `If-None-Match` gets a `304 Not Modified` with no body. Set `cache_duration = nil` to disable both.
+
+## Routes
+
+These are mounted at `/find_states` and `/find_cities` by default. See the README's [Custom route path](../README.md#custom-route-path) section to change that.

data/docs/migration-v4.md

@@ -0,0 +1,32 @@
+# Migrating from 3.x to 4.0
+
+## Requirements changed
+
+- **Rails >= 7.0** is now required (Propshaft/importmap-rails, the default modern asset pipeline this release targets, itself requires Rails 7+). Rails 3–6 support (`engine3.rb`, `railtie.rb`) has been removed. If you're on an older Rails, stay on the `country_state_select` 3.x series.
+- **Ruby >= 3.1** is now required.
+
+## Nothing breaks if you do nothing
+
+The Ruby API (`countries_collection`, `collect_states`, `state_options`, `city_options`, etc.) and the legacy jQuery/Chosen JavaScript (`vendor/assets/javascript/country_state_select.js.erb`) are unchanged and still work exactly as in 3.x, aside from the fixes below. You can upgrade the gem, bump your Rails version if needed, and keep everything else as-is.
+
+## Behavior fixes worth knowing about
+
+- **`cities_collection` (the simple_form helper) now actually filters by country.** In 3.x it silently ignored the `:country` key in `field_names` and only ever looked up cities by state, which meant it never respected the country half of a state/country pair. Duplicate state codes across countries would have picked up the wrong country's cities. If you were relying on that behavior, it's now consistent with `collect_cities(state, country)`, i.e. it needs `field_names` to include both `:state` and `:country`.
+- **`/find_states` and `/find_cities` are HTTP-cached by default** (`Cache-Control` + `ETag`, 1 day). This is new — 3.x sent no caching headers at all. Set `CountryStateSelect.configure { |c| c.cache_duration = nil }` to opt out.
+- **`/find_states` and `/find_cities` now go through your configured data source and `only`/`except`/`priority` filters**, not the `city-state` gem directly. This only changes behavior if you set those new options.
+
+## New, opt-in features
+
+Everything in the README's Configuration section — `priority_countries`, `only`/`except` filtering, `flags`, `dial_codes`, `localize_names`, a pluggable `data_source`, `draw_routes` — is new in 4.0 and defaults to off/unchanged, so adopting the gem doesn't require adopting any of it.
+
+## If you want to modernize your JavaScript
+
+You don't have to — the legacy jQuery/Chosen build keeps working — but if you want to drop the jQuery dependency:
+
+1. Remove `//= require country_state_select` and `//= require chosen-jquery` (and the corresponding CSS `require`s) from your asset manifest.
+2. Follow the README's [JavaScript setup](../README.md#javascript-setup) for whichever pipeline you use (importmap+Stimulus is the default for Rails 7/8 apps).
+3. If you were using `chosen_ui: true`, the modern equivalent is [Tom Select](https://tom-select.js.org/) — Chosen is unmaintained. The Stimulus controller has a `tom-select` value for this; the vanilla/npm build takes an `enhance` callback for the same purpose.
+
+## If you want to switch from simple_form to `form_with`
+
+Also optional. `f.country_select`, `f.state_select`, `f.city_select` are new `form_with`/`form_for` builder methods that don't require simple_form — see the README's [Using it in a form](../README.md#using-it-in-a-form) section. Your existing simple_form-based views keep working unchanged.

data/gemfiles/rails_7.0.gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'rails', '~> 7.0.0'
+# Rails 7.0/7.1's sqlite3 adapter only supports the 1.4.x gem; the gemspec's
+# unpinned `sqlite3` dependency otherwise resolves to the latest 2.x series.
+gem 'sqlite3', '~> 1.4'
+
+gemspec path: '..'

data/gemfiles/rails_7.1.gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'rails', '~> 7.1.0'
+
+gemspec path: '..'

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'rails', '~> 7.2.0'
+
+gemspec path: '..'

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'rails', '~> 8.0.0'
+
+gemspec path: '..'

data/lib/country_state_select/configuration.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module CountryStateSelect
+  # Global, per-app configuration. Set it from an initializer:
+  #
+  #   CountryStateSelect.configure do |config|
+  #     config.priority_countries = %w[US IN GB]
+  #     config.flags = true
+  #     config.cache_duration = 1.week
+  #   end
+  #
+  # Every option here is a *default* — the equivalent per-call keyword
+  # (e.g. `countries_collection(priority: ...)`) always wins.
+  class Configuration
+    # Data source answering countries/states/cities lookups. Accepts an
+    # object implementing DataSources::Base or a symbol (:city_state).
+    attr_accessor :data_source
+
+    # ISO codes listed first in the country dropdown (issue #66).
+    attr_accessor :priority_countries
+
+    # Whitelist / blacklist of ISO codes applied to every country lookup.
+    attr_accessor :only_countries, :except_countries
+
+    # Prepend the emoji flag to country labels ("🇮🇳 India").
+    attr_accessor :flags
+
+    # Append the international dial code to country labels ("India (+91)").
+    attr_accessor :dial_codes
+
+    # Translate country names through I18n / the `countries` gem when
+    # translations are available. Labels fall back to the English name.
+    attr_accessor :localize_names
+
+    # How long the JSON lookup endpoints are HTTP-cached (they serve
+    # static data). Set to nil/false to disable cache headers.
+    attr_accessor :cache_duration
+
+    # Draw the legacy top-level `/find_states` + `/find_cities` routes in
+    # the host app. Disable if you mount the engine at a custom path:
+    #
+    #   config.draw_routes = false
+    #   # config/routes.rb: mount CountryStateSelect::Rails::Engine => '/csc'
+    attr_accessor :draw_routes
+
+    def initialize
+      @data_source = :city_state
+      @priority_countries = []
+      @only_countries = nil
+      @except_countries = nil
+      @flags = false
+      @dial_codes = false
+      @localize_names = false
+      @cache_duration = 86_400 # 1 day, in seconds
+      @draw_routes = true
+    end
+
+    def data_source_instance
+      @data_source_instance ||=
+        case data_source
+        when :city_state, nil then DataSources::CityState.new
+        when Symbol then raise ArgumentError, "Unknown data source: #{data_source.inspect}"
+        else data_source
+        end
+    end
+
+    # Invalidate the memoized adapter when the source changes at runtime
+    # (mostly useful in tests).
+    def data_source=(source)
+      @data_source_instance = nil
+      @data_source = source
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/country_state_select/country_metadata.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CountryStateSelect
+  # Optional label decoration: flag emoji and/or international dial code.
+  # Both read from a small bundled table so the gem stays dependency-free;
+  # a country missing from the table (rare, mostly disputed territories)
+  # simply renders without the decoration instead of raising.
+  module CountryMetadata
+    DIAL_CODES = YAML.safe_load_file(
+      File.expand_path('data/dial_codes.yml', __dir__)
+    ).freeze
+
+    def self.decorate(code, name)
+      label = name
+      label = "#{flag(code)} #{label}" if CountryStateSelect.configuration.flags && flag(code)
+      label = "#{label} (+#{DIAL_CODES[code.to_s]})" if CountryStateSelect.configuration.dial_codes && DIAL_CODES[code.to_s]
+      label
+    end
+
+    # Converts a two-letter ISO code to its flag emoji via the Unicode
+    # "Regional Indicator Symbol" trick (each letter A-Z maps to U+1F1E6..).
+    def self.flag(code)
+      chars = code.to_s.upcase.chars
+      return nil unless chars.length == 2 && chars.all? { |c| c.match?(/[A-Z]/) }
+
+      chars.map { |c| [0x1F1E6 + (c.ord - 'A'.ord)].pack('U') }.join
+    end
+  end
+end