pico_phone-rails 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e4c80e86756e81b40665de3fe0c6436ee462b8d5ea011992e3a8507eaedb323
-  data.tar.gz: 8ce58cb67fc8b73d92ba3b945b303a5c7360265a6ac217e5c0e1e1806c2157b7
+  metadata.gz: a6cddadddef5d95e3c070bd31fb0399be628771ee521156dc1432c196cf938f7
+  data.tar.gz: da7202512a00127735002e1b8f0eb143a5e2466d8e712895f07cbe5eb11831cf
 SHA512:
-  metadata.gz: ca51d0d37018f62fceba7ac87b2f0ebd42f4e537b55d9814e33488b48ea30aa822fd18eef92713d4a9b464e8849298e91ca41b430d1f99d471aba28b371b494b
-  data.tar.gz: dba580ca4a43fe7b83e776cf4e8430a8ca19cf9fc97f0f059c423fdd4e6ae6117f9c1dd702b4ccf878a13f3a848ac271041b62e3350d9143b230cc16523f1d33
+  metadata.gz: d508fcda421a174e0d201aa23abf472534000a8f2f878e813bc0f9bba504545c93271bbfeb4283ecbcb960ad74d20f483406938d7a965f16ff1f0c24379cbc3c
+  data.tar.gz: 18ee00d8bc5a2cf4a6b02a22ed3f69249fc83cdeb3117826beb32afd4627d26d317893ecb5bec775f800273eecbf9170641f57661a3e28fb3717ca5d63bbf49b

data/README.md

@@ -239,9 +239,37 @@ parent as the field -- `data-controller` sits on the `<input>` itself,
 which can't have descendants, so the target is found via the field's
 parent rather than Stimulus's usual descendant-scoped target lookup)
 while the user types. Never rewrites the field's value while it has
-focus -- only on blur, reformatted to national format if what's there
-parses validly, the same reformat-on-blur behavior as the plain
-(non-`live`) helper.
+focus -- only on blur.
+
+On blur, a number that matches `region:` reformats to national format, the
+same as the plain (non-`live`) helper. A number that's valid for a
+*different* country -- one that carries its own explicit signal, a leading
+`+` or a recognized IDD exit code (e.g. `"011 44 20 7946 0958"` dialed out
+of a US-configured field) -- reformats to **international** format instead,
+so it's clearly shown as a foreign number rather than misleadingly bare
+national-style digits. A bare national-style number with no country signal
+of its own (e.g. `"020 7946 0958"` typed into a `region: "US"` field) is
+left exactly as typed -- there's no reliable way to tell which of several
+countries it might belong to from the digits alone, and guessing wrong
+would mean showing the user a different, real phone number than the one
+they meant.
+
+Whether a cross-country match also clears the error is controlled by
+`strict:`:
+
+```ruby
+<%= f.pico_phone_field :phone, region: "US", live: true, strict: false %>
+```
+
+- `strict: true` (default) -- only a same-region match clears the error.
+  A number valid for a different country still reformats to international,
+  but the error stays, matching a validator that enforces `region:`.
+- `strict: false` -- any globally-valid number clears the error, matching
+  a validator that accepts any country (no `region:` option, or
+  `possible:` with no region constraint). **Keep `strict:` in sync with
+  whether the model's own `PhoneValidator` sets `region:`** -- pairing
+  `strict: false` here with a validator that still enforces `region:`
+  shows no error live, but the record still fails validation on submit.
 
 `ValidationsController` uses your app's normal CSRF protection -- the
 controller reads the token from the page's `<meta name="csrf-token">`

data/lib/pico_phone/rails/form_helper.rb

@@ -24,12 +24,16 @@ module PicoPhone
 
     # @param region [String, nil]
     # @param validate_path [String] the mounted engine's validate endpoint
+    # @param strict [Boolean] whether a number valid for a different country than +region+
+    #   still counts as invalid (matching a validator that enforces +region:+) or clears
+    #   the error (matching a validator that accepts any valid number)
     # @return [Hash] Stimulus data attributes for +live:+ validation
-    def self.live_validation_data(region, validate_path)
+    def self.live_validation_data(region, validate_path, strict: true)
       {
         controller: "phone",
         action: "input->phone#validate blur->phone#reformat",
         phone_region_value: region.to_s,
+        phone_strict_value: strict,
         phone_url_value: validate_path
       }
     end
@@ -52,11 +56,12 @@ module PicoPhone
       # @param value [String, PicoPhone::PhoneNumber, nil]
       # @param region [String, nil] ISO 3166-1 alpha-2 region for interpreting +value+ when it's a raw string
       # @param live [Boolean] wire up debounced validation/reformatting; requires the engine to be mounted
+      # @param strict [Boolean] see {PicoPhone::Rails.live_validation_data}; only relevant when +live:+ is true
       # @return [String] an HTML-safe +<input type="tel">+ tag
-      def pico_phone_field_tag(name, value = nil, region: nil, live: false, **options)
+      def pico_phone_field_tag(name, value = nil, region: nil, live: false, strict: true, **options)
         display_value = PicoPhone::Rails.phone_field_display_value(value, region)
         if live
-          data = PicoPhone::Rails.live_validation_data(region, pico_phone_rails.validate_path)
+          data = PicoPhone::Rails.live_validation_data(region, pico_phone_rails.validate_path, strict: strict)
           options[:data] = data.merge(options[:data] || {})
         end
         text_field_tag(name, display_value, options.merge(type: "tel"))
@@ -77,12 +82,14 @@ module PicoPhone
       #   called as an instance method on the form's object, a Proc is called with the object, same resolution
       #   rules as {Extraction.extract_phone_numbers_from} and {PhoneSearchIndex.maintain_phone_search_index}
       # @param live [Boolean] wire up debounced validation/reformatting; requires the engine to be mounted
+      # @param strict [Boolean] see {PicoPhone::Rails.live_validation_data}; only relevant when +live:+ is true
       # @return [String] an HTML-safe +<input type="tel">+ tag
-      def pico_phone_field(method, region: nil, live: false, **options)
+      def pico_phone_field(method, region: nil, live: false, strict: true, **options)
         resolved_region = PicoPhone::Rails.resolve_region(region, object)
         display_value = PicoPhone::Rails.phone_field_display_value(object.public_send(method), resolved_region)
         if live
-          data = PicoPhone::Rails.live_validation_data(resolved_region, @template.pico_phone_rails.validate_path)
+          validate_path = @template.pico_phone_rails.validate_path
+          data = PicoPhone::Rails.live_validation_data(resolved_region, validate_path, strict: strict)
           options[:data] = data.merge(options[:data] || {})
         end
         text_field(method, options.merge(value: display_value, type: "tel"))

data/lib/pico_phone/rails/javascript/pico_phone/rails/phone_controller.js

@@ -5,7 +5,7 @@ import { Controller } from "@hotwired/stimulus"
 // unreachable via Stimulus's normal descendant-scoped static targets.
 // Found by hand instead, scoped to the input's parent.
 export default class extends Controller {
-  static values = { url: String, region: String, debounce: { type: Number, default: 300 } }
+  static values = { url: String, region: String, strict: { type: Boolean, default: true }, debounce: { type: Number, default: 300 } }
 
   connect() {
     this.errorElement = this.element.parentElement?.querySelector('[data-phone-target="error"]') ?? null
@@ -18,7 +18,8 @@ export default class extends Controller {
 
   async reformat() {
     const data = await this.check()
-    if (data.valid) this.element.value = data.national
+    const formatted = data.national ?? data.international
+    if (formatted) this.element.value = formatted
   }
 
   async check() {
@@ -29,7 +30,7 @@ export default class extends Controller {
     const response = await fetch(this.urlValue, {
       method: "POST",
       headers,
-      body: JSON.stringify({ phone: this.element.value, region: this.regionValue }),
+      body: JSON.stringify({ phone: this.element.value, region: this.regionValue, strict: this.strictValue }),
     })
     const data = await response.json()
     if (this.errorElement) this.errorElement.textContent = data.valid || data.blank ? "" : data.message

data/lib/pico_phone/rails/validations_controller.rb

@@ -10,22 +10,60 @@ module PicoPhone
         phone = params[:phone].to_s
         return render json: { valid: false, blank: true } if phone.strip.empty?
 
-        phone_number = PicoPhone.parse(phone, params[:region].presence)
-
-        if phone_number.valid?
-          render json: {
-            valid: true,
-            blank: false,
-            e164: safe_phone_call(phone_number, :e164),
-            national: safe_phone_call(phone_number, :national)
-          }
-        else
-          render json: { valid: false, blank: false, message: I18n.t("errors.messages.invalid_phone") }
-        end
+        render json: response_for(phone, params[:region].presence)
       end
 
       private
 
+      def response_for(phone, region)
+        regional = PicoPhone.parse(phone, region)
+        return regional_payload(regional) if matches_region?(regional, region)
+
+        # `regional`'s #valid?/#country are scoped to `region` even when the input carries its
+        # own country code (a leading "+" or a recognized IDD exit code, e.g. US's "011") --
+        # #valid_countries isn't, since it works off the actually-extracted country code, and
+        # #e164/#international are unaffected by the scoping either. No second parse needed.
+        # A bare national-style number with no country code of its own (e.g. "020 7946 0958"
+        # typed into a region: "US" field) stays invalid here -- #valid_countries comes back
+        # empty because there's no signal pointing at any specific country to check against.
+        return invalid_payload if regional.valid_countries.empty?
+
+        cross_country_payload(regional)
+      end
+
+      def matches_region?(phone_number, region)
+        region ? phone_number.valid_for_country?(region) : phone_number.valid?
+      end
+
+      def regional_payload(phone_number)
+        {
+          valid: true,
+          blank: false,
+          e164: safe_phone_call(phone_number, :e164),
+          national: safe_phone_call(phone_number, :national)
+        }
+      end
+
+      def cross_country_payload(phone_number)
+        strict = params.fetch(:strict, true)
+        payload = {
+          valid: !strict,
+          blank: false,
+          e164: safe_phone_call(phone_number, :e164),
+          international: safe_phone_call(phone_number, :international)
+        }
+        payload[:message] = invalid_message if strict
+        payload
+      end
+
+      def invalid_payload
+        { valid: false, blank: false, message: invalid_message }
+      end
+
+      def invalid_message
+        I18n.t("errors.messages.invalid_phone")
+      end
+
       # @return [String, nil] nil if unparseable, matching PhoneSearchIndex's guard
       def safe_phone_call(phone_number, method_name)
         phone_number.public_send(method_name)

data/lib/pico_phone/rails/version.rb

@@ -2,6 +2,6 @@
 
 module PicoPhone
   module Rails
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pico_phone-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Gabi Jack