country_state_select 4.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '07096615806cb6927cc87f41dd9f52a468a4abbbc3995f14510e5d4a9c76586f'
-  data.tar.gz: 106a0cd51d710611182c4f07c2b28de1e2efde86bd0170f8ce0cedb784bfcee7
+  metadata.gz: b44110d0208f2adeaa74cd4300fdae9edc51dffc5d7f4523cf23a720fd79c352
+  data.tar.gz: ed1bb261ce072b64e3b03434ae6157fbaa01fc830501285cbb5ed8d4f4b71a74
 SHA512:
-  metadata.gz: 4b478c6e74ed49cde30de69c0695d6ba82b32931bf778acd723d848b1e749f5389c359010f4c32a4753c8cea682839d28c1e741fe4f083eb8c03d2a6f065a23f
-  data.tar.gz: e3f8d5c2f1aebee96f819354a56d9d0d227c490134d4f8c1a012e434ad0500b7cad1227f604a0bd155b9d7a82f9258f239054daeb93bbbe437854440e780038d
+  metadata.gz: '0378bdd52c565fa664d7df27ef41e339392d4a94262db5b5bd8f074b80c10412af1f2ab546880f540f9cb27937bebcdc415275ead5f8d1113a4e538a15ff30b5'
+  data.tar.gz: 7c0fda7c020be2912f2337e52761610ac58886bdeecb61cd396afa175f2036e9c12913bdd6203798be7fbb471e6d63e33abdb8f22f3df53a5f4df798669ae9df

data/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: bundler
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: monthly

data/.github/workflows/ci.yml

@@ -5,6 +5,9 @@ on:
     branches: [master]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   ruby-versions:
     name: Ruby ${{ matrix.ruby }} (latest Rails)
@@ -12,9 +15,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['3.1', '3.2', '3.3', '3.4']
+        ruby: ['3.1', '3.2', '3.3', '3.4', '4.0']
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
@@ -28,14 +31,26 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        rails: ['7.0', '7.1', '7.2', '8.0']
+        rails: ['7.0', '7.1', '7.2', '8.0', '8.1']
     env:
       BUNDLE_GEMFILE: gemfiles/rails_${{ matrix.rails }}.gemfile
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '3.3'
           bundler-cache: true
       - name: Run tests
         run: bundle exec rspec
+
+  javascript:
+    name: JavaScript
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          cache: npm
+      - run: npm ci
+      - run: npm test

data/.gitignore

@@ -23,3 +23,4 @@ mkmf.log
 .idea/
 vendor/bundle/
 gemfiles/*.gemfile.lock
+node_modules

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 4.0.1
+
+### Fixed
+- Rebuilt state/city fields now keep all of the original element's attributes (`required`, `aria-*`, `disabled`, Stimulus `data-*-target`, ...). Previously only `id`, `name` and `class` survived the first country/state change, which dropped validation and accessibility wiring and broke Stimulus reconnects ("Missing target element").
+- A slow `/find_states` or `/find_cities` response for a previous selection can no longer overwrite the dropdown for the current one.
+- `destroy()` now removes the country `change` listener, and `refresh()` no longer stacks a second set of listeners (which caused duplicate lookups per change).
+- Changing the country no longer sends two `/find_cities` requests for an empty state; the city field is cleared client-side.
+- The lookup endpoints' ETag now includes the gem version and the data source's `cache_key`, so browsers re-fetch after an upgrade or a data change instead of receiving a stale `304`. Custom data sources can override `cache_key`.
+
+### Changed
+- CI: Ruby 4.0 and Rails 8.1 added to the matrix, a JavaScript test job (`npm test`, Node test runner + jsdom), least-privilege workflow `permissions`, and Dependabot for Actions/bundler/npm.
+
 ## 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.

data/README.md

@@ -1,12 +1,15 @@
-## Country State Select
+# Country State Select
+
+[![Gem Version](https://img.shields.io/gem/v/country_state_select)](https://rubygems.org/gems/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)
+[![Downloads](https://img.shields.io/gem/dt/country_state_select)](https://rubygems.org/gems/country_state_select)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
 
 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/state data comes from the [city-state](https://github.com/loureirorg/city-state) gem (pluggable — see [Custom data sources](#custom-data-sources)).
+Country, state and city data comes from the [city-state](https://github.com/loureirorg/city-state) gem (pluggable — see [Custom data sources](#custom-data-sources)).
 
 **v4.0 is a modernization release.** Highlights:
 
@@ -18,7 +21,20 @@ Country/state/state data comes from the [city-state](https://github.com/loureiro
 - HTTP-cached JSON lookup endpoints
 - An install generator (`rails g country_state_select:install`)
 
-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).
+See the [CHANGELOG](CHANGELOG.md) for what changed in each release. 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).
+
+## Table of contents
+
+- [Installation](#installation)
+- [Supported versions](#supported-versions)
+- [JavaScript setup](#javascript-setup)
+- [JavaScript API](#javascript-api)
+- [Using it in a form](#using-it-in-a-form)
+- [Configuration](#configuration)
+- [JSON API](#json-api)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
@@ -31,7 +47,14 @@ bundle install
 rails g country_state_select:install   # optional: initializer + setup instructions
 ```
 
-Requires Rails >= 7.0 and Ruby >= 3.1.
+## Supported versions
+
+| Gem version | Ruby | Rails |
+|---|---|---|
+| 4.x | 3.1 – 4.0 | 7.0 – 8.1 |
+| 3.x | no minimum declared | 3.0 – 7.x (use 3.x for Rails < 7.0) |
+
+CI tests every Ruby and Rails version listed for 4.x. Rails 7.0 and 7.1 and Ruby 3.1 and 3.2 are past end of life upstream; they still pass CI but may be dropped in a future major version.
 
 ## JavaScript setup
 
@@ -85,14 +108,22 @@ Stimulus controller values (all optional, set as `data-country-state-select-<val
 
 ```js
 document.addEventListener('DOMContentLoaded', function () {
-  CountryStateSelect({ country_id: "country_field_id", state_id: "state_field_id" })
+  CountryStateSelect({
+    country_id: "country_field_id",
+    state_id: "state_field_id",
+    city_id: "city_field_id" // optional
+  })
 })
 ```
 
+All options are listed in [JavaScript API](#javascript-api). If you use Turbo without Stimulus, see [Turbo without Stimulus](#turbo-without-stimulus).
+
 ### npm / esbuild / webpack
 
+The package is not on the npm registry yet. Install it from GitHub:
+
 ```
-npm install country_state_select @hotwired/stimulus
+npm install github:arvindvyas/Country-State-Select @hotwired/stimulus
 ```
 
 ```js
@@ -123,6 +154,69 @@ $(document).on('turbo:load', function () {
 })
 ```
 
+## JavaScript API
+
+The Stimulus controller is a thin wrapper around one function. Call it directly when you aren't using Stimulus:
+
+```js
+const csc = CountryStateSelect({ country_id: "country", state_id: "state", city_id: "city" })
+```
+
+| Option | Default | Purpose |
+|---|---|---|
+| `country_id` | required | `id` of the country `<select>` |
+| `state_id` | required | `id` of the state field |
+| `city_id` | none | `id` of the city field; leave it out for a country → state form |
+| `states_url` / `cities_url` | `/find_states` / `/find_cities` | Lookup endpoints, if you mounted them elsewhere |
+| `state_placeholder` / `city_placeholder` | `""` | Text of the blank first option |
+| `selected_state` / `selected_city` | none | Value to pre-select when the field is filled on page load. You can also set `data-selected-value` on the state field or `data-selected-city` on the state or city field |
+| `announce` | `true` | Announce updates through an `aria-live` region |
+| `enhance` | none | `function (selectEl, options)` called on every rebuilt `<select>`, e.g. to attach Tom Select. Return an object with `destroy()` so it can be torn down before the next rebuild |
+| `enhance_options` | `{}` | Passed as the second argument to `enhance` |
+| `offline_data` | none | Serve lookups from memory instead of the endpoints (see below) |
+
+It returns `{ refresh, destroy }`:
+
+- `refresh()` re-reads the fields and re-attaches listeners, e.g. after you replace the form's HTML. It can be called repeatedly; listeners are not duplicated.
+- `destroy()` removes all listeners and tears down any `enhance` instances.
+
+**How fields are updated.** When the country changes, the state field is rebuilt with the new options and the city field is cleared. If there is nothing to list, the field becomes a text input so the user can type a value. The rebuilt field keeps every attribute of the original (`id`, `name`, `class`, `required`, `aria-*`, `data-*`, and so on), so validation, accessibility labels and Stimulus targets survive. If the user changes the country or state again before a lookup returns, the older response is ignored.
+
+**Tom Select without Stimulus:**
+
+```js
+CountryStateSelect({
+  country_id: "country",
+  state_id: "state",
+  enhance: (el, opts) => new TomSelect(el, opts),
+  enhance_options: { create: false }
+})
+```
+
+**Offline data.** Skip the network by passing the lookup data up front. States are keyed by country code, cities by `"COUNTRY:STATE"`. A missing `cities` key falls back to the endpoint.
+
+```js
+CountryStateSelect({
+  country_id: "country", state_id: "state", city_id: "city",
+  offline_data: {
+    states: { US: [["CA", "California"], ["NY", "New York"]] },
+    cities: { "US:CA": ["Los Angeles", "San Francisco"] }
+  }
+})
+```
+
+### Turbo without Stimulus
+
+The Stimulus controller cleans up after itself. With the plain function, destroy the instance before Turbo caches the page, or each visit leaves another listener on `document`:
+
+```js
+let csc
+document.addEventListener("turbo:load", () => {
+  csc = CountryStateSelect({ country_id: "country", state_id: "state", city_id: "city" })
+})
+document.addEventListener("turbo:before-cache", () => csc?.destroy())
+```
+
 ## Using it in a form
 
 ### `form_with` (no simple_form required)
@@ -174,9 +268,11 @@ end
 
 Every option here can also be passed per-call: `CountryStateSelect.countries_collection(priority: %w[US])`, `f.country_select :country, only: %w[US CA]`.
 
+The `priority_countries`, `only_countries` and `except_countries` settings shape the **country** list. They are not applied by the `/find_states` and `/find_cities` endpoints.
+
 ### Custom data sources
 
-Swap out `city-state` (e.g. for a database table, or the `countries` gem) by implementing the adapter interface:
+Swap out `city-state` (e.g. for a database table, or the `countries` gem) by implementing the adapter interface. The lookup endpoints, form helpers and `collect_*` methods all go through it, so no view or JavaScript changes are needed:
 
 ```ruby
 class MyDataSource < CountryStateSelect::DataSources::Base
@@ -191,11 +287,19 @@ class MyDataSource < CountryStateSelect::DataSources::Base
   def cities(state_code, country_code)
     ['Los Angeles', 'San Francisco'] # plain names
   end
+
+  # Optional: part of the lookup endpoints' ETag. Return something that
+  # changes with your data so browsers don't keep serving a stale 304.
+  def cache_key
+    "my-data-#{Location.maximum(:updated_at).to_i}"
+  end
 end
 
 CountryStateSelect.configure { |c| c.data_source = MyDataSource.new }
 ```
 
+`cache_key` defaults to the class name. The lookup responses are HTTP-cached (1 day by default), and their `ETag` is built from the gem version, this key and the request params. If your data can change without a deploy, return a key that changes with it; otherwise browsers that already hold a response keep getting `304 Not Modified` until it expires.
+
 ### Custom route path
 
 By default the engine draws `/find_states` and `/find_cities` at the top level. To mount it elsewhere:
@@ -221,20 +325,50 @@ The lookup endpoints are documented in [docs/json-api.md](docs/json-api.md) —
 
 ## Development
 
+Ruby specs:
+
 ```
 bundle install
 bundle exec rspec
+
+# against a specific Rails version
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle exec rspec
 ```
 
-The dummy Rails app used for integration tests lives in `spec/dummy` and doubles as a runnable demo:
+JavaScript tests (Node's built-in test runner with jsdom, in `test/javascript/`):
+
+```
+npm ci
+npm test
+```
+
+The JavaScript source of truth is `app/javascript/country_state_select/country_state_select.js`. After editing it, regenerate the Sprockets build and commit both files:
+
+```
+bundle exec rake js:build
+```
+
+The dummy Rails app used for the request specs 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/`).
+CI runs the Ruby suite on Ruby 3.1–4.0 (latest Rails) and on Rails 7.0, 7.1, 7.2, 8.0 and 8.1 (see `gemfiles/`), plus the JavaScript tests.
 
 ## Contributing
 
-Fork, fix, then send a pull request.
+1. Fork the repo and create a branch.
+2. Make your change with a test: an RSpec example for Ruby, a `test/javascript/` test for the JS.
+3. If you changed the JS source, run `bundle exec rake js:build`.
+4. Run `bundle exec rspec` and `npm test`.
+5. Add a line under the next version in `CHANGELOG.md`.
+6. Open a pull request.
+
+Bug reports and questions are welcome in [GitHub issues](https://github.com/arvindvyas/Country-State-Select/issues).
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/app/controllers/country_state_select/cscs_controller.rb

@@ -30,12 +30,16 @@ module CountryStateSelect
     # 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`.
+    # The ETag includes the gem version and the data source's cache_key so
+    # an upgrade or a data change invalidates responses browsers already hold.
     def render_cached(data, cache_key)
-      duration = CountryStateSelect.configuration.cache_duration
+      configuration = CountryStateSelect.configuration
+      duration = configuration.cache_duration
 
       if duration
         expires_in duration, public: true
-        return unless stale?(etag: cache_key)
+        etag = [CountryStateSelect::VERSION, configuration.data_source_instance.cache_key, cache_key]
+        return unless stale?(etag: etag)
       end
 
       respond_to do |format|

data/app/javascript/country_state_select/country_state_select.js

@@ -24,10 +24,14 @@ export default function CountryStateSelect(options) {
   var liveRegion = announce ? ensureLiveRegion() : null;
 
   var enhancedInstances = {};
+  var boundCountryEl = null;
+  var statesRequestId = 0;
+  var citiesRequestId = 0;
+  var NON_TRANSFERABLE_ATTRIBUTES = ['type', 'value'];
 
   init();
 
-  return { refresh: init, destroy: destroy };
+  return { refresh: refresh, destroy: destroy };
 
   // ====== ***** INITIALIZATION ***** ===================================== //
 
@@ -37,9 +41,8 @@ export default function CountryStateSelect(options) {
     var countryEl = document.getElementById(countryId);
     if (!countryEl) return;
 
-    countryEl.addEventListener('change', function () {
-      findStates(countryEl.value, { userInitiated: true });
-    });
+    countryEl.addEventListener('change', countryChange);
+    boundCountryEl = countryEl;
 
     if (hasCityField) {
       document.addEventListener('change', delegatedStateChange);
@@ -79,10 +82,26 @@ export default function CountryStateSelect(options) {
     return !!el && el.tagName === 'SELECT' && el.options.length > 1;
   }
 
+  function refresh() {
+    removeListeners();
+    init();
+  }
+
   function destroy() {
+    removeListeners();
+    Object.keys(enhancedInstances).forEach(destroyEnhancement);
+  }
+
+  function removeListeners() {
+    if (boundCountryEl) boundCountryEl.removeEventListener('change', countryChange);
+    boundCountryEl = null;
     document.removeEventListener('change', delegatedStateChange);
   }
 
+  function countryChange(event) {
+    findStates(event.target.value, { userInitiated: true });
+  }
+
   function delegatedStateChange(event) {
     if (event.target && event.target.id === stateId) {
       findCities(event.target.value, document.getElementById(countryId).value, { userInitiated: true });
@@ -91,8 +110,13 @@ export default function CountryStateSelect(options) {
 
   // ====== ***** DATA LOOKUP ***** ========================================= //
 
+  // Each lookup takes a fresh request id; a response is only applied if no
+  // newer lookup for the same field started while it was in flight, so a
+  // slow reply for a previously selected country/state can't overwrite the
+  // current one.
   function findStates(countryCode, ctx) {
     ctx = ctx || {};
+    var requestId = ++statesRequestId;
     if (ctx.userInitiated) findCities('', '', { silent: true });
 
     if (offlineData && offlineData.states) {
@@ -101,6 +125,7 @@ export default function CountryStateSelect(options) {
     }
 
     fetchJson(statesUrl, { country_id: countryCode }).then(function (data) {
+      if (requestId !== statesRequestId) return;
       buildStatesDropdown(data || [], ctx);
     });
   }
@@ -108,6 +133,12 @@ export default function CountryStateSelect(options) {
   function findCities(stateCode, countryCode, ctx) {
     ctx = ctx || {};
     if (!hasCityField) return;
+    var requestId = ++citiesRequestId;
+
+    if (!stateCode) {
+      buildCitiesDropdown([], ctx);
+      return;
+    }
 
     if (offlineData && offlineData.cities) {
       var key = countryCode + ':' + stateCode;
@@ -116,6 +147,7 @@ export default function CountryStateSelect(options) {
     }
 
     fetchJson(citiesUrl, { country_id: countryCode, state_id: stateCode }).then(function (data) {
+      if (requestId !== citiesRequestId) return;
       buildCitiesDropdown(data || [], ctx);
     });
   }
@@ -142,18 +174,15 @@ export default function CountryStateSelect(options) {
     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
-        });
-      }
+    // A user-initiated country change already cleared the city field in
+    // findStates, so only the initial (pre-selected) load cascades here.
+    if (hasCityField && !ctx.userInitiated && 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
+      });
     }
   }
 
@@ -163,9 +192,12 @@ export default function CountryStateSelect(options) {
   }
 
   // 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.
+  // (no data for the parent selection). The new element replaces the old
+  // one, so every attribute is carried over (id, name, class, required,
+  // aria-*, Stimulus target data attributes, ...) — otherwise validation,
+  // accessibility wiring and Stimulus targets are lost after the first
+  // rebuild. Tom Select instances are torn down first and re-created on
+  // the new node.
   function rebuildField(fieldId, pairs, preselectValue, placeholder) {
     var el = document.getElementById(fieldId);
     if (!el) return;
@@ -174,18 +206,14 @@ export default function CountryStateSelect(options) {
 
     if (!pairs || pairs.length === 0) {
       var input = document.createElement('input');
+      copyAttributes(el, 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;
+    copyAttributes(el, select);
 
     var blank = document.createElement('option');
     blank.textContent = placeholder || '';
@@ -206,6 +234,12 @@ export default function CountryStateSelect(options) {
     enhance(fieldId);
   }
 
+  function copyAttributes(from, to) {
+    Array.prototype.forEach.call(from.attributes, function (attr) {
+      if (NON_TRANSFERABLE_ATTRIBUTES.indexOf(attr.name) === -1) to.setAttribute(attr.name, attr.value);
+    });
+  }
+
   function enhance(fieldId) {
     if (!fieldId || typeof enhancer !== 'function') return;
     var el = document.getElementById(fieldId);

data/docs/json-api.md

@@ -16,7 +16,7 @@ GET /find_states?country_id=US
 [["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.
+Resolves through the configured `data_source`, so a custom adapter is used here too. The country settings (`only_countries`, `except_countries`, `priority_countries`) are not applied: they shape the country list, and this endpoint returns the states of whatever country code it is given.
 
 ## `GET /find_cities`
 
@@ -34,7 +34,9 @@ GET /find_cities?state_id=CA&country_id=US
 
 ## 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.
+Both endpoints send `Cache-Control: public` and an `ETag` when `CountryStateSelect.configuration.cache_duration` is set (default: 1 day). Set `cache_duration = nil` to send neither.
+
+The `ETag` is built from the gem version, the data source's `cache_key` and the request params. A conditional `GET` whose `If-None-Match` matches gets `304 Not Modified` with no body. Upgrading the gem (or the `city-state` gem, for the default data source) changes the `ETag`, so clients re-fetch. A custom data source whose data changes at runtime should return a changing `cache_key`; see [Custom data sources](../README.md#custom-data-sources).
 
 ## Routes
 

data/gemfiles/rails_8.1.gemfile

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

data/lib/country_state_select/data_sources/base.rb

@@ -22,6 +22,14 @@ module CountryStateSelect
       def cities(_state_code, _country_code)
         raise NotImplementedError
       end
+
+      # Part of the ETag on the JSON lookup endpoints. Change it whenever the
+      # underlying data changes (e.g. a table's max updated_at) so browsers
+      # holding a cached response re-fetch instead of getting a 304.
+      # @return [String]
+      def cache_key
+        self.class.name
+      end
     end
   end
 end

data/lib/country_state_select/data_sources/city_state.rb

@@ -23,6 +23,10 @@ module CountryStateSelect
 
         CS.cities(state_code.to_sym, country_code.to_s.empty? ? nil : country_code.to_sym) || []
       end
+
+      def cache_key
+        "#{super}/#{Gem.loaded_specs['city-state']&.version}"
+      end
     end
   end
 end

data/lib/country_state_select/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CountryStateSelect
-  VERSION = '4.0.0'
+  VERSION = '4.0.1'
 end