country_state_select 3.2.0 → 4.0.0

data/lib/country_state_select/data/dial_codes.yml

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+#
+# ISO 3166-1 alpha-2 => ITU international dial code (without the leading +).
+# Territories that share a country's dial code (e.g. Caribbean NANP members)
+# repeat that code, matching real-world usage.
+AC: '247'
+AD: '376'
+AE: '971'
+AF: '93'
+AG: '1268'
+AI: '1264'
+AL: '355'
+AM: '374'
+AO: '244'
+AQ: '672'
+AR: '54'
+AS: '1684'
+AT: '43'
+AU: '61'
+AW: '297'
+AX: '358'
+AZ: '994'
+BA: '387'
+BB: '1246'
+BD: '880'
+BE: '32'
+BF: '226'
+BG: '359'
+BH: '973'
+BI: '257'
+BJ: '229'
+BL: '590'
+BM: '1441'
+BN: '673'
+BO: '591'
+BQ: '599'
+BR: '55'
+BS: '1242'
+BT: '975'
+BW: '267'
+BY: '375'
+BZ: '501'
+CA: '1'
+CC: '61'
+CD: '243'
+CF: '236'
+CG: '242'
+CH: '41'
+CI: '225'
+CK: '682'
+CL: '56'
+CM: '237'
+CN: '86'
+CO: '57'
+CR: '506'
+CU: '53'
+CV: '238'
+CW: '599'
+CX: '61'
+CY: '357'
+CZ: '420'
+DE: '49'
+DJ: '253'
+DK: '45'
+DM: '1767'
+DO: '1'
+DZ: '213'
+EC: '593'
+EE: '372'
+EG: '20'
+EH: '212'
+ER: '291'
+ES: '34'
+ET: '251'
+FI: '358'
+FJ: '679'
+FK: '500'
+FM: '691'
+FO: '298'
+FR: '33'
+GA: '241'
+GB: '44'
+GD: '1473'
+GE: '995'
+GF: '594'
+GG: '44'
+GH: '233'
+GI: '350'
+GL: '299'
+GM: '220'
+GN: '224'
+GP: '590'
+GQ: '240'
+GR: '30'
+GT: '502'
+GU: '1671'
+GW: '245'
+GY: '592'
+HK: '852'
+HN: '504'
+HR: '385'
+HT: '509'
+HU: '36'
+ID: '62'
+IE: '353'
+IL: '972'
+IM: '44'
+IN: '91'
+IO: '246'
+IQ: '964'
+IR: '98'
+IS: '354'
+IT: '39'
+JE: '44'
+JM: '1876'
+JO: '962'
+JP: '81'
+KE: '254'
+KG: '996'
+KH: '855'
+KI: '686'
+KM: '269'
+KN: '1869'
+KP: '850'
+KR: '82'
+KW: '965'
+KY: '1345'
+KZ: '7'
+LA: '856'
+LB: '961'
+LC: '1758'
+LI: '423'
+LK: '94'
+LR: '231'
+LS: '266'
+LT: '370'
+LU: '352'
+LV: '371'
+LY: '218'
+MA: '212'
+MC: '377'
+MD: '373'
+ME: '382'
+MF: '590'
+MG: '261'
+MH: '692'
+MK: '389'
+ML: '223'
+MM: '95'
+MN: '976'
+MO: '853'
+MP: '1670'
+MQ: '596'
+MR: '222'
+MS: '1664'
+MT: '356'
+MU: '230'
+MV: '960'
+MW: '265'
+MX: '52'
+MY: '60'
+MZ: '258'
+NA: '264'
+NC: '687'
+NE: '227'
+NF: '672'
+NG: '234'
+NI: '505'
+NL: '31'
+'NO': '47'
+NP: '977'
+NR: '674'
+NU: '683'
+NZ: '64'
+OM: '968'
+PA: '507'
+PE: '51'
+PF: '689'
+PG: '675'
+PH: '63'
+PK: '92'
+PL: '48'
+PM: '508'
+PR: '1'
+PS: '970'
+PT: '351'
+PW: '680'
+PY: '595'
+QA: '974'
+RE: '262'
+RO: '40'
+RS: '381'
+RU: '7'
+RW: '250'
+SA: '966'
+SB: '677'
+SC: '248'
+SD: '249'
+SE: '46'
+SG: '65'
+SH: '290'
+SI: '386'
+SJ: '47'
+SK: '421'
+SL: '232'
+SM: '378'
+SN: '221'
+SO: '252'
+SR: '597'
+SS: '211'
+ST: '239'
+SV: '503'
+SX: '1721'
+SY: '963'
+SZ: '268'
+TC: '1649'
+TD: '235'
+TG: '228'
+TH: '66'
+TJ: '992'
+TK: '690'
+TL: '670'
+TM: '993'
+TN: '216'
+TO: '676'
+TR: '90'
+TT: '1868'
+TV: '688'
+TW: '886'
+TZ: '255'
+UA: '380'
+UG: '256'
+US: '1'
+UY: '598'
+UZ: '998'
+VA: '39'
+VC: '1784'
+VE: '58'
+VG: '1284'
+VI: '1340'
+VN: '84'
+VU: '678'
+WF: '681'
+WS: '685'
+XK: '383'
+YE: '967'
+YT: '262'
+ZA: '27'
+ZM: '260'
+ZW: '263'

data/lib/country_state_select/data_sources/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CountryStateSelect
+  module DataSources
+    # Adapter interface. Implement this to back CountryStateSelect with a
+    # different data provider (a database table, the `countries` gem, a
+    # remote API, ...) instead of the bundled `city-state` gem — this is
+    # what closes out issue #25 (limited/missing city data) without the
+    # gem itself owning the data problem.
+    class Base
+      # @return [Hash{Symbol=>String}] ISO code => English country name
+      def countries
+        raise NotImplementedError
+      end
+
+      # @return [Array<Array(Symbol,String)>] raw [code, name] pairs
+      def states(_country_code)
+        raise NotImplementedError
+      end
+
+      # @return [Array<String>] city names
+      def cities(_state_code, _country_code)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/country_state_select/data_sources/city_state.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'city-state'
+
+module CountryStateSelect
+  module DataSources
+    # Default adapter, backed by the `city-state` gem (unchanged behavior
+    # from 3.x). `CS.countries` returns a Hash memoized for the whole
+    # process, so every read here is non-mutating.
+    class CityState < Base
+      def countries
+        CS.countries.reject { |k, _| k == :COUNTRY_ISO_CODE }
+      end
+
+      def states(country_code)
+        return [] if country_code.nil? || country_code.to_s.empty?
+
+        (CS.states(country_code) || {}).to_a
+      end
+
+      def cities(state_code, country_code)
+        return [] if state_code.nil? || state_code.to_s.empty?
+
+        CS.cities(state_code.to_sym, country_code.to_s.empty? ? nil : country_code.to_sym) || []
+      end
+    end
+  end
+end

data/lib/country_state_select/engine.rb

@@ -5,6 +5,37 @@
 module CountryStateSelect
   module Rails
     class Engine < ::Rails::Engine
+      initializer 'country_state_select.form_builder' do
+        ActiveSupport.on_load(:action_view) do
+          ActionView::Helpers::FormBuilder.include CountryStateSelect::FormBuilder
+        end
+      end
+
+      # Sprockets/Propshaft: makes both the new dependency-free build
+      # (vendor/assets/javascript/country_state_select_vanilla.js) and the
+      # deprecated jQuery build resolvable via `//= require` or
+      # `stylesheet_link_tag`, and makes app/javascript resolvable as an
+      # asset path for importmap-rails pins (see config/importmap.rb).
+      initializer 'country_state_select.assets' do |app|
+        if app.config.respond_to?(:assets)
+          app.config.assets.paths << root.join('app/javascript').to_s
+          app.config.assets.paths << root.join('vendor/assets/javascript').to_s
+        end
+      end
+
+      # Registers this engine's pins (country_state_select,
+      # country_state_select/controller) with importmap-rails, if the host
+      # app has it installed, so apps get them for free instead of having
+      # to hand-write `pin "country_state_select", to: ...` themselves.
+      # Safe to define even when importmap-rails isn't present — Rails
+      # initializer ordering just no-ops a `before:` reference to a name
+      # that doesn't exist.
+      initializer 'country_state_select.importmap', before: 'importmap' do |app|
+        next unless app.config.respond_to?(:importmap)
+
+        app.config.importmap.paths << root.join('config/importmap.rb')
+        app.config.importmap.cache_sweepers << root.join('app/javascript')
+      end
     end
   end
 end

data/lib/country_state_select/form_builder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module CountryStateSelect
+  # Native `form_with`/`form_for` support — `f.state_select` renders a plain
+  # HTML <select> (or a text <input> when the current country has no states,
+  # matching simple_form's `state_options` behavior) without requiring
+  # simple_form. Both helpers stamp `data-controller`/`data-*-target`
+  # attributes so the bundled Stimulus controller (app/javascript/
+  # country_state_select/controller.js) wires up automatically — wrap the
+  # fields in a `data-controller="country-state-select"` container and no
+  # further JS is needed.
+  module FormBuilder
+    FILTER_KEYS = %i[only except priority].freeze
+
+    def country_select(method, options = {}, html_options = {})
+      collection = CountryStateSelect.countries_collection(options.slice(*FILTER_KEYS))
+      merged_html = html_options.reverse_merge(data: { 'country-state-select-target': 'country' })
+
+      select(method, collection, options.except(*FILTER_KEYS), merged_html)
+    end
+
+    def state_select(method, country_method, options = {}, html_options = {})
+      country_value = object.public_send(country_method)
+      states = CountryStateSelect.collect_states(country_value, **options.slice(*FILTER_KEYS))
+      merged_html = html_options.reverse_merge(data: { 'country-state-select-target': 'state' })
+
+      if states.empty?
+        # FormBuilder#text_field (generated for the `field_helpers` list)
+        # only takes (method, options) — html attributes and options share
+        # one hash, unlike `select`'s separate options/html_options.
+        text_field(method, options.except(*FILTER_KEYS).merge(merged_html))
+      else
+        select(method, states, options.except(*FILTER_KEYS), merged_html)
+      end
+    end
+
+    def city_select(method, state_method, country_method, options = {}, html_options = {})
+      cities = CountryStateSelect.collect_cities(object.public_send(state_method), object.public_send(country_method))
+      merged_html = html_options.reverse_merge(data: { 'country-state-select-target': 'city' })
+
+      if cities.empty?
+        text_field(method, options.merge(merged_html))
+      else
+        select(method, cities.zip(cities), options, merged_html)
+      end
+    end
+  end
+end

data/lib/country_state_select/localization.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CountryStateSelect
+  # Best-effort translation of country names for the current I18n.locale.
+  #
+  # Two lookup strategies, tried in order, so neither is a hard dependency:
+  #
+  #   1. The `countries` gem (ISO3166::Country), if the host app already
+  #      depends on it — it ships translations for all ISO locales.
+  #   2. A `country_state_select.countries.<ISO_CODE>` key in the host
+  #      app's own locale files, for apps that want to supply their own.
+  #
+  # Falls back to the English name from the data source when neither
+  # strategy has a translation, so `localize_names` is always safe to turn
+  # on even with sparse translation coverage.
+  module Localization
+    module_function
+
+    def country_name(code, english_name)
+      return english_name unless CountryStateSelect.configuration.localize_names
+
+      via_countries_gem(code) || via_i18n(code) || english_name
+    end
+
+    def via_countries_gem(code)
+      return nil unless defined?(::ISO3166::Country)
+
+      ::ISO3166::Country.new(code.to_s)&.translations&.[](I18n.locale.to_s)
+    rescue StandardError
+      nil
+    end
+
+    def via_i18n(code)
+      key = "country_state_select.countries.#{code}"
+      translated = I18n.t(key, default: nil)
+      translated if translated.present?
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/country_state_select/version.rb

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

data/lib/country_state_select.rb

@@ -1,23 +1,51 @@
 # frozen_string_literal: true
 
+require 'yaml'
 require 'country_state_select/version'
-require 'city-state'
+require 'country_state_select/configuration'
+require 'country_state_select/data_sources/base'
+require 'country_state_select/data_sources/city_state'
+require 'country_state_select/localization'
+require 'country_state_select/country_metadata'
+require 'country_state_select/form_builder'
 require 'rails'
 
 module CountryStateSelect
-  # Collect the Countries
-  def self.countries_collection
-    CS.countries.except!(:COUNTRY_ISO_CODE).collect { |p| [p[1], p[0]] }.compact
+  # Collect the Countries as [label, code] pairs, honoring configuration
+  # (priority_countries, only/except, flags, dial_codes, localize_names)
+  # and any per-call overrides passed in `options`.
+  #
+  #   CountryStateSelect.countries_collection
+  #   CountryStateSelect.countries_collection(priority: %w[US IN], only: %w[US IN GB])
+  def self.countries_collection(options = {})
+    config = configuration
+    raw = config.data_source_instance.countries
+
+    only = options.fetch(:only, config.only_countries)
+    except = options.fetch(:except, config.except_countries)
+    priority = options.fetch(:priority, config.priority_countries)
+
+    raw = raw.select { |code, _| only.map(&:to_s).include?(code.to_s) } if only
+    raw = raw.reject { |code, _| except.map(&:to_s).include?(code.to_s) } if except
+
+    labeled = raw.collect do |code, name|
+      localized = Localization.country_name(code, name)
+      [CountryMetadata.decorate(code, localized), code]
+    end
+
+    reorder_by_priority(labeled, priority)
   end
 
-  # Pass array of unwanted countries to get back all except those in the array
+  # Pass array of unwanted countries to get back all except those in the array.
+  # Kept for backward compatibility with 3.x; prefer `countries_collection(except: ...)`.
   def self.countries_except(*except)
-    countries_collection.collect { |c| c unless except.include?(c[1]) }.compact
+    except = except.flatten.compact
+    countries_collection(except: except.presence)
   end
 
   # Return either the State (String) or States (Array)
   def self.states_collection(f, options)
-    states = collect_states(f.object.send(options[:country]))
+    states = collect_states(f.object.send(options[:country]), **filter_opts(options))
     return f.object.send(options[:state]) if states.empty?
 
     states
@@ -25,31 +53,45 @@ module CountryStateSelect
 
   # Return either the City (String) or Cities (Array)
   def self.cities_collection(f, options)
-    cities = collect_cities(f.object.send(options[:state]))
+    collect_cities(f.object.send(options[:state]), f.object.send(options[:country]))
+  end
+
+  # Return the raw [code, name] pairs for a given Country's states/provinces
+  # — the shape the JSON lookup endpoint hands to the front-end (element 0
+  # is the option value, element 1 is the label).
+  def self.raw_states(country, only: nil, except: nil, priority: nil)
+    return [] if country.nil? || country.to_s.empty?
+
+    states = configuration.data_source_instance.states(country) # [[code, name], ...]
+    states = states.select { |code, _| only.map(&:to_s).include?(code.to_s) } if only
+    states = states.reject { |code, _| except.map(&:to_s).include?(code.to_s) } if except
+
+    reorder_by_priority(states, priority, index: 0)
   end
 
-  # Return the collected States for a given Country
-  def self.collect_states(country)
-    CS.states(country).collect { |p| [p[1], p[0]] }.compact
+  # Return the collected States for a given Country, as [name, code] pairs
+  # — the shape simple_form/options_for_select expects (label, then value).
+  def self.collect_states(country, only: nil, except: nil, priority: nil)
+    raw_states(country, only: only, except: except, priority: priority).collect { |code, name| [name, code] }
   end
 
-  # Return the cities of given state and country
+  # Return the cities of given state and country.
   def self.collect_cities(state_id = '', country_id = '')
-    return [] if state_id.nil? || country_id.nil?
+    return [] if state_id.nil? || country_id.nil? || state_id.to_s.empty?
 
-    CS.cities(state_id.to_sym, country_id.to_sym)
+    configuration.data_source_instance.cities(state_id, country_id)
   end
 
   # Return a hash for use in the simple_form
   def self.state_options(options)
     states = states_collection(options[:form], options[:field_names])
-    options = merge_hash(options, states)
+    merge_hash(options, states)
   end
 
   # Return a hash for use in the simple_form
   def self.city_options(options)
-    cities =  cities_collection(options[:form], options[:field_names])
-    options = merge_hash(options, cities)
+    cities = cities_collection(options[:form], options[:field_names])
+    merge_hash(options, cities)
   end
 
   # Create hash to use in the simple_form
@@ -58,15 +100,33 @@ module CountryStateSelect
     options = options.merge(as: :string) if collections.instance_of?(String)
     options
   end
+
+  # Moves entries whose code is in `priority` (in that order) to the front
+  # of `collection`, followed by everything else in its original order.
+  def self.reorder_by_priority(collection, priority, index: 1)
+    return collection if priority.nil? || priority.empty?
+
+    priority_codes = priority.map(&:to_s)
+    by_code = collection.group_by { |entry| entry[index].to_s }
+
+    head = priority_codes.filter_map { |code| by_code[code]&.first }
+    tail = collection - head
+
+    head + tail
+  end
+  private_class_method :reorder_by_priority
+
+  def self.filter_opts(options)
+    return {} unless options.is_a?(Hash)
+
+    options.slice(:only, :except, :priority)
+  end
+  private_class_method :filter_opts
 end
 
 case ::Rails.version.to_s
-when /^[4-7]./
+when /^[7-9]\./, /^\d{2}\./
   require 'country_state_select/engine'
-when /^3\.[12]/
-  require 'country_state_select/engine3'
-when /^3\.0/
-  require 'country_state_select/railtie'
 else
-  raise 'Unsupported rails version'
+  raise 'Unsupported Rails version — CountryStateSelect 4.x requires Rails >= 7.0. Use CountryStateSelect 3.x for older Rails.'
 end

data/lib/generators/country_state_select/install/install_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module CountryStateSelect
+  module Generators
+    # rails g country_state_select:install
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a CountryStateSelect initializer and prints JS setup instructions.'
+
+      def copy_initializer
+        template 'initializer.rb', 'config/initializers/country_state_select.rb'
+      end
+
+      def show_readme
+        readme 'README' if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/country_state_select/install/templates/README

@@ -0,0 +1,34 @@
+===============================================================================
+
+CountryStateSelect is installed. An initializer was created at
+config/initializers/country_state_select.rb — uncomment what you need.
+
+Next, pick ONE JavaScript integration:
+
+  Importmap (Rails 7/8 default) — pins are registered automatically, in
+  app/javascript/application.js:
+
+    import "country_state_select"
+    import { Application } from "@hotwired/stimulus"
+    import CountryStateSelectController from "country_state_select/controller"
+    Application.start().register("country-state-select", CountryStateSelectController)
+
+  Sprockets (no jQuery required):
+
+    //= require country_state_select_vanilla
+
+  npm / esbuild / webpack:
+
+    npm install country_state_select @hotwired/stimulus
+
+Then in a view, wrap your fields in a Stimulus controller container:
+
+  <div data-controller="country-state-select">
+    <%= f.country_select :country %>
+    <%= f.state_select :state, :country %>
+  </div>
+
+See https://github.com/arvindvyas/Country-State-Select#readme for the full
+guide, including simple_form usage and the legacy jQuery/Chosen path.
+
+===============================================================================

data/lib/generators/country_state_select/install/templates/initializer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+CountryStateSelect.configure do |config|
+  # ISO codes shown first in the country dropdown.
+  # config.priority_countries = %w[US CA GB]
+
+  # Restrict the country list instead of showing all ~250 countries.
+  # config.only_countries = %w[US CA GB IN AU]
+  # config.except_countries = %w[KP]
+
+  # Decorate country labels.
+  # config.flags = true          # "🇮🇳 India"
+  # config.dial_codes = true     # "India (+91)"
+
+  # Translate country names via I18n / the `countries` gem, when available.
+  # config.localize_names = true
+
+  # How long the JSON lookup endpoints are HTTP-cached, in seconds.
+  # Set to nil to disable caching.
+  # config.cache_duration = 1.day
+
+  # Set to false if you want to mount the engine at a custom path instead
+  # of the default top-level /find_states, /find_cities routes.
+  # config.draw_routes = false
+
+  # Swap in your own data source (a DB table, the `countries` gem, ...) by
+  # implementing CountryStateSelect::DataSources::Base and assigning it here.
+  # config.data_source = MyApp::CountryDataSource.new
+end