country_state_select 3.2.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8f77a9628df0c6d9f3f67493a93621ea6f22a458a04c26969aecb71922778ff
-  data.tar.gz: 050561b2a48f6ca39fde1287adf09236ed4a0e983effe55e19a59aa540e551dc
+  metadata.gz: '07096615806cb6927cc87f41dd9f52a468a4abbbc3995f14510e5d4a9c76586f'
+  data.tar.gz: 106a0cd51d710611182c4f07c2b28de1e2efde86bd0170f8ce0cedb784bfcee7
 SHA512:
-  metadata.gz: 4a2487931fa56393723cd3d06d3d18449876c8bb743673583132aa8f7e098eb5b0cd82efd501ee2cf846cc2d627434f39d8f0e5dba03ed0997cd1b0f0a793f26
-  data.tar.gz: 90efce81dba401f57355c7186f7857145b92fc4f5a2afccb95f83b6489a6f6f5612d4c03bf5eb37f387cecf1d25857f139f59744d0a06abf0f81fe7183db8044
+  metadata.gz: 4b478c6e74ed49cde30de69c0695d6ba82b32931bf778acd723d848b1e749f5389c359010f4c32a4753c8cea682839d28c1e741fe4f083eb8c03d2a6f065a23f
+  data.tar.gz: e3f8d5c2f1aebee96f819354a56d9d0d227c490134d4f8c1a012e434ad0500b7cad1227f604a0bd155b9d7a82f9258f239054daeb93bbbe437854440e780038d

data/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  ruby-versions:
+    name: Ruby ${{ matrix.ruby }} (latest Rails)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.1', '3.2', '3.3', '3.4']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rspec
+
+  rails-versions:
+    name: Rails ${{ matrix.rails }} (Ruby 3.3)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        rails: ['7.0', '7.1', '7.2', '8.0']
+    env:
+      BUNDLE_GEMFILE: gemfiles/rails_${{ matrix.rails }}.gemfile
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rspec

data/.gitignore

@@ -21,3 +21,5 @@ tmp
 *.a
 mkmf.log
 .idea/
+vendor/bundle/
+gemfiles/*.gemfile.lock

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 4.0.0
+
+Modernization release. See [docs/migration-v4.md](docs/migration-v4.md) for the full upgrade guide — existing 3.x code (Ruby API and the legacy jQuery JS) keeps working unchanged.
+
+### Added
+- Dependency-free JavaScript core (`app/javascript/country_state_select/country_state_select.js`), with builds for importmap-rails/npm (ESM) and Sprockets (`vendor/assets/javascript/country_state_select_vanilla.js`, compiled via `rake js:build`).
+- A Stimulus controller (`country_state_select/controller`) with `states-url`/`cities-url`/`tom-select`/`announce`/`state-placeholder`/`city-placeholder` values.
+- npm package (`package.json`) exposing the core and Stimulus controller as ES modules; `@hotwired/stimulus` is an optional peer dependency.
+- Native `form_with`/`form_for` support: `f.country_select`, `f.state_select`, `f.city_select` — simple_form is no longer required. They render the model's current selection server-side (correct on edit forms without waiting on JS) and stamp Stimulus target data attributes automatically.
+- `rails g country_state_select:install` generator (initializer + setup instructions).
+- `CountryStateSelect.configure` with `priority_countries`, `only_countries`/`except_countries`, `flags`, `dial_codes`, `localize_names`, `cache_duration`, `draw_routes`, and a pluggable `data_source` (`CountryStateSelect::DataSources::Base`).
+- `only:`/`except:`/`priority:` keyword options on `countries_collection`, `countries_except`, `collect_states`.
+- Flag emoji and international dial code label decoration for countries.
+- I18n-localized country names, with an optional soft integration with the `countries` gem.
+- HTTP caching (`Cache-Control` + `ETag`, conditional `GET` → `304`) on the `/find_states`/`/find_cities` JSON endpoints; configurable via `cache_duration`.
+- `config.draw_routes = false` + documented pattern for mounting the lookup routes at a custom path.
+- An `aria-live` region announcing dropdown updates, and edit-form pre-population support in the new JS (skips a redundant AJAX round-trip when the server already rendered the correct selection; only fetches when a field is genuinely still a blank shell).
+- `spec/dummy`: a runnable Rails 7/8 demo app (Propshaft + importmap + Stimulus) that doubles as the integration test target.
+- CI matrix expanded to Rails 7.0/7.1/7.2/8.0 in addition to the Ruby version matrix (`gemfiles/`).
+- `docs/json-api.md`, `docs/cities.md`, `docs/migration-v4.md`.
+
+### Changed
+- **Requires Rails >= 7.0 and Ruby >= 3.1.** Rails 3–6 support (`engine3.rb`, `railtie.rb`) removed — stay on `country_state_select` 3.x for older Rails.
+- `cities_collection` (the simple_form helper) now actually passes the country through to the lookup, instead of silently ignoring it — see the migration guide if you relied on the old (incorrect) behavior.
+- `/find_states` and `/find_cities` now resolve through the configured data source and `only`/`except`/`priority` filters rather than calling the underlying data gem directly.
+
+### Deprecated
+- The jQuery + Chosen JavaScript (`vendor/assets/javascript/country_state_select.js.erb`) is kept for backward compatibility but is deprecated in favor of the new dependency-free build.
+
+## 3.3.1
+
+### Fixed
+- **CSRF / verb:** the `find_states` and `find_cities` lookup routes now accept
+  `GET` (the correct verb for read-only data) in addition to `POST`, and the
+  controller skips forgery protection. Previously the front-end's AJAX `POST`
+  had no CSRF token and would raise `ActionController::InvalidAuthenticityToken`
+  on a default Rails app. The bundled JavaScript now issues `GET` requests.
+- **Data mutation:** `countries_collection` no longer calls `except!` (bang) on
+  the hash that `city-state` memoizes, which permanently mutated the gem's
+  shared country data for the process. It now uses a non-mutating `reject`.
+- **Consistent return shape:** `collect_cities` now always returns an `Array`
+  (empty when there is no data), matching `collect_states`, instead of `nil`.
+- **Duplicate AJAX requests:** the state-change handler that triggers the city
+  lookup is now bound once via event delegation instead of being re-bound on
+  every country change (the old behaviour stacked listeners and fired multiple
+  requests per change — the long-standing `[142] FIXME`).
+- **JavaScript hardening:** option markup now quotes the `value` attribute and
+  HTML-escapes labels; `html` and loop counters are properly scoped instead of
+  leaking to the global object.
+
+### Changed
+- CI moved to GitHub Actions running the RSpec suite across Ruby 3.0–3.3. The
+  unused Travis and CircleCI configs (the latter never ran the tests) were
+  removed.

data/README.md

@@ -1,155 +1,240 @@
-## Country State Select 
-[![Build Status](https://travis-ci.org/arvindvyas/Country-State-Select.svg?branch=master)](https://travis-ci.org/arvindvyas/Country-State-Select)  
+## Country State Select
+[![CI](https://github.com/arvindvyas/Country-State-Select/actions/workflows/ci.yml/badge.svg)](https://github.com/arvindvyas/Country-State-Select/actions/workflows/ci.yml)
 [![Code Climate](https://codeclimate.com/github/arvindvyas/Country-State-Select/badges/gpa.svg)](https://codeclimate.com/github/arvindvyas/Country-State-Select)
 
+Country State Select gives you cascading Country → State/Province → City dropdowns for Rails forms: pick a country, the state field repopulates; pick a state, the city field repopulates.
 
+![Cascading country, state, and city selects](docs/images/cascading-select-demo.png)
 
-Country State Select is a library that provides an easy API to generate Country , State / Province  and City dropdowns for use in forms.
+Country/state/state data comes from the [city-state](https://github.com/loureirorg/city-state) gem (pluggable — see [Custom data sources](#custom-data-sources)).
 
-When implemented correctly, a State / Province dropdown is filled with appropriate regions based upon what Country a user has selected .
+**v4.0 is a modernization release.** Highlights:
 
-For instance, if a user chooses "United States of America" for a Country dropdown, the State dropdown will be filled with the 50 appropriate states plus the District of Columbia also then user can list city according to state selection but currently cities are limited.
+- Dependency-free JavaScript (no jQuery) with a bundled [Stimulus](https://stimulus.hotwired.dev/) controller
+- Works with importmap-rails, Sprockets, Propshaft, or npm/esbuild/webpack
+- Native `form_with`/`form_for` support (`f.country_select`, `f.state_select`, `f.city_select`) — simple_form is no longer required
+- `priority_countries`, `only`/`except` filtering, flags, dial codes, I18n-localized names
+- A pluggable data source adapter
+- HTTP-cached JSON lookup endpoints
+- An install generator (`rails g country_state_select:install`)
 
-The data for Countries and States is populated by the excellent [city-state](https://github.com/loureirorg/city-state) gem. 
+Upgrading from 3.x? See [docs/migration-v4.md](docs/migration-v4.md) — the legacy jQuery/Chosen JavaScript still works, but Rails < 7.0 is no longer supported (stay on the 3.x gem for older Rails).
 
-# Demo
-  https://country-state-select.herokuapp.com
+## Installation
 
-# Getting Started
+```ruby
+gem 'country_state_select'
+```
 
-Country State Select is released as a Ruby Gem and requires the Rails environment as well.
+```
+bundle install
+rails g country_state_select:install   # optional: initializer + setup instructions
+```
 
-To install, simply add the following to your Gemfile.
+Requires Rails >= 7.0 and Ruby >= 3.1.
 
-    gem 'country_state_select'
-  
-Then run 
-    
-    bundle install
+## JavaScript setup
 
-# NOTE 
-In the latest version we have removed all the dependencies of js and you are feel free to use any js you can use predefine method to populate data
+Pick the one that matches your app. All of them talk to the same `/find_states` and `/find_cities` JSON endpoints (see [docs/json-api.md](docs/json-api.md)).
 
-Don't forget to restart your server after you install it.
-## Setup Gem
-if not autoloaded than please add in your application.js
-      //= require country_state_select
+### Importmap + Stimulus (Rails 7/8 default)
 
-## chosen JavaScript assets
-  The application makes use of the chosen-rails library for a better user experience.  This can be disabled if desired.  
-  
-  If you're using chosen-rails, please add the following to app/assets/javascripts/application.js:
-  
-      //= require chosen-jquery
+The engine registers its pins automatically — no `pin` lines to write yourself. In `app/javascript/application.js`:
 
+```js
+import "country_state_select"
+import { Application } from "@hotwired/stimulus"
+import CountryStateSelectController from "country_state_select/controller"
 
-## chosen CSS assets
+const application = Application.start()
+application.register("country-state-select", CountryStateSelectController)
+```
 
-  You'll also need to add the chosen-rails stylesheet.
+Or, with `stimulus-rails`' `app/javascript/controllers/index.js` auto-loading convention, just re-export it as its own controller file:
 
-  If you're using chosen-rails, please add the following to app/assets/stylesheets/application.css:
+```js
+// app/javascript/controllers/country_state_select_controller.js
+export { default } from "country_state_select/controller"
+```
 
-    *= require chosen
+Then in a view, wrap your fields in a controller container:
 
- or
-    
-    @import "chosen";
-    
-    
-# Form Implementation in SimpleForm
+```erb
+<div data-controller="country-state-select">
+  <%= f.country_select :country %>
+  <%= f.state_select :state, :country %>
+  <%= f.city_select :city, :state, :country %>
+</div>
+```
 
-Implementation in a view is simple. 
+Stimulus controller values (all optional, set as `data-country-state-select-<value>-value="..."`):
 
-Just create a simple_form object like so:
-```ruby
-<%= simple_form_for @form_object do |f| 
-  f.button :submit
-end %>
-```    
-Once your form object is created, add in fields for your user to select a Country and State / Province.      
+| Value | Default | Purpose |
+|---|---|---|
+| `states-url` | `/find_states` | Override if you disabled `draw_routes` and mounted the engine elsewhere |
+| `cities-url` | `/find_cities` | Same, for cities |
+| `tom-select` | `false` | Enhance the selects with [Tom Select](https://tom-select.js.org/) once populated (requires `TomSelect` to be loaded globally) |
+| `announce` | `true` | Announce dropdown updates via an `aria-live` region |
+| `state-placeholder` / `city-placeholder` | `""` | Blank option text shown before a real selection |
 
-## Country Field
+### Sprockets (no jQuery)
 
-To add the Country field, add an input field like the following:
+```js
+//= require country_state_select_vanilla
+```
 
-    <%= f.input :country_field, collection: CountryStateSelect.countries_collection %>
-  
-The above code is simply a normal simple_form field object with a collection of countries passed to it using the CountryStateSelect library.  
+```js
+document.addEventListener('DOMContentLoaded', function () {
+  CountryStateSelect({ country_id: "country_field_id", state_id: "state_field_id" })
+})
+```
 
-You can pass any of the normal options that a field object accepts - :label, :input_html, etc.    
-    
-## States / Provinces Field
+### npm / esbuild / webpack
 
-To list the States / Provinces, add an input field like the following:
+```
+npm install country_state_select @hotwired/stimulus
+```
 
-    <%= options = { form: f, field_names: { :country => :country_field, :state => :state_field } }
-    
-    f.input :state_field, CountryStateSelect.state_options(options) %>
-    
-It's important to note that the :country and :state keys in the :field_names object must contain the correct values in order for the correct States / Provinces to load into the window. 
+```js
+import CountryStateSelectController from "country_state_select/controller"
+// or, for the framework-agnostic core directly:
+import CountryStateSelect from "country_state_select"
+```
 
-Other than that, it's yet another standard simple_form field object.  
+`@hotwired/stimulus` is an optional peer dependency — only needed if you import the `/controller` entry point.
 
-Any options that are valid in simple_form field can be passed into the options hash.
+### Legacy jQuery + Chosen (deprecated)
 
-# Required JavaScript
+Still bundled for apps upgrading from 3.x. New apps should use one of the options above.
 
-The magic of the library is the JavaScript that is performed on the fields.  This JavaScript needs to be included in order for the proper State / Provinces to be selected based upon your Country selection.  
+```js
+//= require country_state_select
+//= require chosen-jquery   // optional, if you want the Chosen UI
+```
 
-Add this JavaScript to the page that is loading your form:
-```javascript
-$(document).on('ready page:load', function() {
-  return CountryStateSelect({
+```js
+$(document).on('turbo:load', function () {
+  CountryStateSelect({
     country_id: "country_field_id",
-    state_id: "state_field_id"
-  });
-});
+    state_id: "state_field_id",
+    chosen_ui: true,
+    chosen_options: { disable_search_threshold: 10 }
+  })
+})
 ```
-If you are using CoffeeScript, use the following:
-```coffescript
-$(document).on 'ready page:load', ->
-    CountryStateSelect({ country_id: "country_field_id", state_id: "state_field_id" })
- ```
 
-The country_id accepts the form ID for the country field.  The state_id accepts the form ID for the state field.
+## Using it in a form
+
+### `form_with` (no simple_form required)
 
-The easiest way to determine the ID is to view the source in the web browser. (Or, you could set it in the options hash.)
+```erb
+<%= form_with model: @business do |f| %>
+  <div data-controller="country-state-select">
+    <%= f.country_select :country, include_blank: true %>
+    <%= f.state_select :state, :country %>
+    <%= f.city_select :city, :state, :country %>
+  </div>
+<% end %>
+```
 
-The ID being referred to is like the following in a select menu:
+- `state_select`/`city_select` read the model's *current* country/state to render the right options server-side — on an edit form, the saved state and city show up correctly without waiting on JavaScript.
+- When the parent selection has no states/cities (e.g. a country with no states), the field renders as a plain text input, same as before.
+- `only:`, `except:`, and `priority:` options work on all three: `f.country_select :country, priority: %w[US CA]`.
 
-    <select id="country_field_id"></select>
-   
-# chosen UI improvements (optional)
+### simple_form (unchanged from 3.x)
 
-The CountryStateSelect interface offers the option to turn the Chosen library on or off.  
+```erb
+<%= simple_form_for @form_object do |f| %>
+  <%= f.input :country_field, collection: CountryStateSelect.countries_collection %>
 
-To turn it on, set it to true:
-```javascript
-$(document).on('ready page:load', function() {
-  return CountryStateSelect({
-    chosen_ui: true,
-    chosen_options: { 
-      disable_search_threshold: 10,
-      width: '95%'
-    },
-    ...
-    ...
-    ...
-  });
-}); 
-```
-To turn it off, set it to false:
-```javascript
-$(document).on('ready page:load', function() {
-  return CountryStateSelect({
-    chosen_ui: false,
-    ...
-    ...
-    ...
-  });
-});
-```    
+  <% options = { form: f, field_names: { country: :country_field, state: :state_field } } %>
+  <%= f.input :state_field, CountryStateSelect.state_options(options) %>
+<% end %>
+```
+
+City support: see [docs/cities.md](docs/cities.md).
+
+## Configuration
+
+```ruby
+# config/initializers/country_state_select.rb
+CountryStateSelect.configure do |config|
+  config.priority_countries = %w[US CA GB]   # shown first in the dropdown
+  config.only_countries = %w[US CA GB IN]    # restrict the list
+  config.except_countries = %w[KP]           # or exclude specific ones
+
+  config.flags = true          # "🇮🇳 India"
+  config.dial_codes = true     # "India (+91)"
+  config.localize_names = true # translate names via I18n / the `countries` gem
+
+  config.cache_duration = 1.day # HTTP cache on /find_states, /find_cities; nil disables it
+  config.draw_routes = true     # set false to mount the engine at a custom path instead
+end
+```
+
+Every option here can also be passed per-call: `CountryStateSelect.countries_collection(priority: %w[US])`, `f.country_select :country, only: %w[US CA]`.
+
+### Custom data sources
+
+Swap out `city-state` (e.g. for a database table, or the `countries` gem) by implementing the adapter interface:
+
+```ruby
+class MyDataSource < CountryStateSelect::DataSources::Base
+  def countries
+    { US: 'United States', IN: 'India' } # code => English name
+  end
+
+  def states(country_code)
+    [[:CA, 'California'], [:NY, 'New York']] # [code, name] pairs
+  end
+
+  def cities(state_code, country_code)
+    ['Los Angeles', 'San Francisco'] # plain names
+  end
+end
+
+CountryStateSelect.configure { |c| c.data_source = MyDataSource.new }
+```
+
+### Custom route path
+
+By default the engine draws `/find_states` and `/find_cities` at the top level. To mount it elsewhere:
+
+```ruby
+# config/initializers/country_state_select.rb
+CountryStateSelect.configure { |c| c.draw_routes = false }
+```
+
+```ruby
+# config/routes.rb
+scope path: '/csc' do
+  match 'find_states' => 'country_state_select/cscs#find_states', via: :get
+  match 'find_cities' => 'country_state_select/cscs#find_cities', via: :get
+end
+```
+
+Then pass the matching URLs to the JS: `states_url: '/csc/find_states'` (or the Stimulus `states-url-value`).
+
+## JSON API
+
+The lookup endpoints are documented in [docs/json-api.md](docs/json-api.md) — useful if you're driving the selects from a SPA or mobile client instead of the bundled JS.
+
+## Development
+
+```
+bundle install
+bundle exec rspec
+```
+
+The dummy Rails app used for integration tests lives in `spec/dummy` and doubles as a runnable demo:
+
+```
+cd spec/dummy
+bin/rails server
+```
+
+CI runs the suite across Ruby 3.1–3.4 (latest Rails) and Rails 7.0/7.1/7.2/8.0 (see `gemfiles/`).
 
 ## Contributing
-  Fork, fix, then send a pull request.
- 
+
+Fork, fix, then send a pull request.

data/Rakefile

@@ -1,3 +1,29 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
+
+namespace :js do
+  desc 'Compile app/javascript/country_state_select/country_state_select.js into the ' \
+       'Sprockets-loadable vendor/assets/javascript/country_state_select_vanilla.js build'
+  task :build do
+    source_path = File.expand_path('app/javascript/country_state_select/country_state_select.js', __dir__)
+    dest_path = File.expand_path('vendor/assets/javascript/country_state_select_vanilla.js', __dir__)
+
+    source = File.read(source_path)
+    body = source.sub('export default function CountryStateSelect(options) {', 'function CountryStateSelect(options) {')
+    raise "Could not find the expected export in #{source_path} — did the function signature change?" if body == source
+
+    File.write(dest_path, <<~JS)
+      // GENERATED FILE — do not edit directly.
+      // Source: app/javascript/country_state_select/country_state_select.js
+      // Regenerate with `rake js:build` after editing the source.
+      (function (global) {
+      #{body.gsub(/^/, '  ').rstrip}
+
+        global.CountryStateSelect = CountryStateSelect;
+      })(this);
+    JS
+
+    puts "Wrote #{dest_path}"
+  end
+end

data/app/controllers/country_state_select/cscs_controller.rb

@@ -3,20 +3,43 @@
 # @author : Arvind Vyas
 module CountryStateSelect
   class CscsController < ApplicationController
-    def find_states
-      csc = CS.states(params[:country_id])
+    # These are read-only data lookups served over GET, so CSRF tokens are not
+    # required. Skipping forgery protection also keeps the endpoints usable when
+    # a host app still wires them up as POST without sending a token.
+    skip_forgery_protection if respond_to?(:skip_forgery_protection)
 
-      respond_to do |format|
-        format.json { render json: csc.to_a }
-      end
+    def find_states
+      # `[[code, name], ...]` shape — the front-end uses element 0 as the option
+      # value (ISO code) and element 1 as the label. Goes through the
+      # configured data source (not `CS` directly) so a custom adapter and
+      # only/except/priority filtering apply here too.
+      render_cached(CountryStateSelect.raw_states(params[:country_id]), params[:country_id])
     end
 
-    # Sent it to state_id and  country id it will return cities of that states
+    # Send it a state_id and country_id; returns the cities of that state.
     def find_cities
-      cities = CS.cities(params[:state_id].to_sym, params[:country_id].to_sym)
+      render_cached(
+        CountryStateSelect.collect_cities(params[:state_id], params[:country_id]),
+        [params[:state_id], params[:country_id]]
+      )
+    end
+
+    private
+
+    # The underlying data is static per params, so this is safe to cache
+    # both at the HTTP layer (Cache-Control) and via conditional GET
+    # (ETag/304), avoiding a render entirely on repeat lookups. Disabled by
+    # setting `CountryStateSelect.configuration.cache_duration = nil`.
+    def render_cached(data, cache_key)
+      duration = CountryStateSelect.configuration.cache_duration
+
+      if duration
+        expires_in duration, public: true
+        return unless stale?(etag: cache_key)
+      end
 
       respond_to do |format|
-        format.json { render json: cities.to_a }
+        format.json { render json: data }
       end
     end
   end

data/app/javascript/country_state_select/controller.js

@@ -0,0 +1,66 @@
+// Stimulus wrapper around country_state_select.js — the idiomatic way to
+// wire this up on Rails 7/8 with Hotwire/Turbo and no manual JS per page.
+//
+//   <div data-controller="country-state-select"
+//        data-country-state-select-tom-select-value="true">
+//     <select data-country-state-select-target="country" ...>
+//     <select data-country-state-select-target="state" ...>
+//     <select data-country-state-select-target="city" ...>   (optional)
+//   </div>
+//
+// Register it once in your controllers/index.js:
+//
+//   import { Application } from '@hotwired/stimulus'
+//   import CountryStateSelectController from 'country_state_select/controller'
+//   const application = Application.start()
+//   application.register('country-state-select', CountryStateSelectController)
+//
+// Requires `@hotwired/stimulus` as a peer dependency in the host app —
+// it is not bundled or re-exported by this package.
+//
+// Imports the bare specifier "country_state_select" (the importmap pin /
+// npm package name) rather than a relative path — a relative import would
+// resolve against this file's own fingerprinted asset URL under Sprockets/
+// Propshaft (e.g. controller-a1b2c3.js), bypassing the import map entirely
+// and 404ing, since browsers only consult import maps for bare specifiers.
+import { Controller } from '@hotwired/stimulus';
+import CountryStateSelect from 'country_state_select';
+
+export default class CountryStateSelectController extends Controller {
+  static targets = ['country', 'state', 'city'];
+  static values = {
+    statesUrl: { type: String, default: '/find_states' },
+    citiesUrl: { type: String, default: '/find_cities' },
+    tomSelect: { type: Boolean, default: false },
+    announce: { type: Boolean, default: true },
+    statePlaceholder: { type: String, default: '' },
+    cityPlaceholder: { type: String, default: '' }
+  };
+
+  connect() {
+    this.instance = CountryStateSelect({
+      country_id: this.countryTarget.id,
+      state_id: this.stateTarget.id,
+      city_id: this.hasCityTarget ? this.cityTarget.id : undefined,
+      states_url: this.statesUrlValue,
+      cities_url: this.citiesUrlValue,
+      state_placeholder: this.statePlaceholderValue,
+      city_placeholder: this.cityPlaceholderValue,
+      announce: this.announceValue,
+      enhance: this.tomSelectValue ? this.tomSelectEnhancer.bind(this) : undefined
+    });
+  }
+
+  disconnect() {
+    if (this.instance) this.instance.destroy();
+  }
+
+  tomSelectEnhancer(selectEl, opts) {
+    if (typeof TomSelect === 'undefined') {
+      console.warn('country-state-select: tomSelectValue is true but TomSelect is not loaded'); // eslint-disable-line no-console
+      return null;
+    }
+
+    return new TomSelect(selectEl, opts);
+  }
+}