pico_phone-rails 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad67a4a67bfcdfd2e94072a2989dd25c23896ed5d97ef6b506a08c31548fe9f1
-  data.tar.gz: 1414db39189fdaed84124aaf1e10e8abb5ed02414668130a9f37ceb4b682ccad
+  metadata.gz: a6cddadddef5d95e3c070bd31fb0399be628771ee521156dc1432c196cf938f7
+  data.tar.gz: da7202512a00127735002e1b8f0eb143a5e2466d8e712895f07cbe5eb11831cf
 SHA512:
-  metadata.gz: 6aaeb277b412aa8acea4729c56a9e1c371a3e967cf4c4162d9aa430e1409842e075cf810ff2db665b605dff47ebd18e85d3367cbff4c7652fc6ed92563371700
-  data.tar.gz: e31a7f628e3b16386fc79ccc3f0d9ceb67d41db69901ccbe7ff455475da9afc3e5a05fc316b5f85946071eb4e333bb7f9e0bb10a92955d3bb99bd5f721f89b7a
+  metadata.gz: d508fcda421a174e0d201aa23abf472534000a8f2f878e813bc0f9bba504545c93271bbfeb4283ecbcb960ad74d20f483406938d7a965f16ff1f0c24379cbc3c
+  data.tar.gz: 18ee00d8bc5a2cf4a6b02a22ed3f69249fc83cdeb3117826beb32afd4627d26d317893ecb5bec775f800273eecbf9170641f57661a3e28fb3717ca5d63bbf49b

data/README.md

@@ -206,6 +206,76 @@ a plain `<input type="tel">` with no formatting) -- redefining a core Rails
 helper would silently change behavior for every `phone_field` call in an
 app, not just ones backed by a PicoPhone-managed attribute.
 
+### Live validation
+
+Mount the engine:
+
+```ruby
+# config/routes.rb
+mount PicoPhone::Rails::Engine, at: "/pico_phone"
+```
+
+The controller is auto-pinned into `importmap-rails` when present, but
+still needs to be registered with your Stimulus application -- pinning
+only makes it importable, the same as any other pinned module:
+
+```js
+// app/javascript/controllers/index.js
+import { application } from "controllers/application"
+import PhoneController from "pico_phone/rails/phone_controller"
+application.register("phone", PhoneController)
+```
+
+Then opt in per field:
+
+```ruby
+<%= f.pico_phone_field :phone, region: "US", live: true %>
+<span data-phone-target="error"></span>
+```
+
+Debounces input and POSTs to the mounted engine, showing the error message
+in a sibling `data-phone-target="error"` element (anywhere under the same
+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.
+
+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">`
+(rendered by Rails' own `csrf_meta_tags`, already in any standard layout)
+and sends it with every request, no extra setup needed.
+
 ### ActiveJob serializer
 
 ```ruby

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+PicoPhone::Rails::Engine.routes.draw do
+  post "validate", to: "validations#validate"
+end

data/lib/pico_phone/rails/engine.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require "pico_phone/rails/validations_controller"
+
+module PicoPhone
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace PicoPhone::Rails
+
+      initializer "pico_phone_rails.assets" do |app|
+        app.config.assets.paths << Pathname.new(__dir__).join("javascript") if app.config.respond_to?(:assets)
+      end
+
+      # importmap-rails draws config.importmap.paths in its own "importmap"
+      # initializer -- appending after that is a no-op, so this must run before.
+      # A no-op itself if importmap-rails isn't installed.
+      initializer "pico_phone_rails.importmap", before: "importmap" do |app|
+        next unless app.config.respond_to?(:importmap)
+
+        app.config.importmap.paths << Pathname.new(__dir__).join("javascript.rb")
+        app.config.importmap.cache_sweepers << Pathname.new(__dir__).join("javascript")
+      end
+    end
+  end
+end

data/lib/pico_phone/rails/form_helper.rb

@@ -22,6 +22,22 @@ module PicoPhone
       phone_number.valid? ? phone_number.national : string
     end
 
+    # @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, 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
+
     # Included into ActionView::Base by the railtie once ActionView loads.
     # Adds +pico_phone_field_tag+, a +text_field_tag+-like helper that
     # displays national format for a valid number while leaving the
@@ -39,9 +55,15 @@ module PicoPhone
       # @param name [String, Symbol]
       # @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, **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, strict: strict)
+          options[:data] = data.merge(options[:data] || {})
+        end
         text_field_tag(name, display_value, options.merge(type: "tel"))
       end
     end
@@ -59,10 +81,17 @@ module PicoPhone
       #   raw value when it isn't already a {PicoPhone::PhoneNumber} -- a String is used as-is, a Symbol is
       #   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, **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
+          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"))
       end
     end

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

@@ -0,0 +1,39 @@
+import { Controller } from "@hotwired/stimulus"
+
+// data-controller sits on the <input> itself, which can't have children --
+// so the error element (a sibling, placed wherever the caller wants) is
+// 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, strict: { type: Boolean, default: true }, debounce: { type: Number, default: 300 } }
+
+  connect() {
+    this.errorElement = this.element.parentElement?.querySelector('[data-phone-target="error"]') ?? null
+  }
+
+  validate() {
+    clearTimeout(this.timeout)
+    this.timeout = setTimeout(() => this.check(), this.debounceValue)
+  }
+
+  async reformat() {
+    const data = await this.check()
+    const formatted = data.national ?? data.international
+    if (formatted) this.element.value = formatted
+  }
+
+  async check() {
+    const headers = { "Content-Type": "application/json", Accept: "application/json" }
+    const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content
+    if (csrfToken) headers["X-CSRF-Token"] = csrfToken
+
+    const response = await fetch(this.urlValue, {
+      method: "POST",
+      headers,
+      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
+    return data
+  }
+}

data/lib/pico_phone/rails/javascript.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+pin "pico_phone/rails/phone_controller", to: "pico_phone/rails/phone_controller.js"

data/lib/pico_phone/rails/validations_controller.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "action_controller"
+
+module PicoPhone
+  module Rails
+    # `region:` always arrives as an already-resolved String -- no record lookup.
+    class ValidationsController < ActionController::Base
+      def validate
+        phone = params[:phone].to_s
+        return render json: { valid: false, blank: true } if phone.strip.empty?
+
+        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)
+      rescue TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/pico_phone/rails/version.rb

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

data/lib/pico_phone/rails.rb

@@ -16,3 +16,4 @@ require "pico_phone/rails/normalizer"
 require "pico_phone/rails/extraction"
 require "pico_phone/rails/phone_search_index"
 require "pico_phone/rails/railtie" if defined?(Rails::Railtie)
+require "pico_phone/rails/engine" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pico_phone-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Gabi Jack
@@ -56,8 +56,11 @@ description: 'pico_phone-rails wires the pico_phone gem into Rails: a :phone_num
   class macro that rewrites phone attributes to E.164 before validation, extract_phone_numbers_from
   for pulling phone numbers out of free text (with an optional persisted backend for
   cross-record search), maintain_phone_search_index for keeping search columns in
-  sync on an existing phone-number table, and an ActiveJob serializer so a PhoneNumber
-  survives being passed as a job argument.'
+  sync on an existing phone-number table, pico_phone_field_tag/f.pico_phone_field
+  form helpers that display national format for a valid number without discarding
+  what the user typed, live: true on those same helpers for debounced Stimulus-driven
+  validation and reformatting via a mountable engine, and an ActiveJob serializer
+  so a PhoneNumber survives being passed as a job argument.'
 email:
 - gabi@gabijack.com
 executables: []
@@ -66,6 +69,7 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- config/routes.rb
 - lib/generators/pico_phone/rails/extracted_phone_numbers/extracted_phone_numbers_generator.rb
 - lib/generators/pico_phone/rails/extracted_phone_numbers/templates/create_pico_phone_rails_extracted_phone_numbers.rb.tt
 - lib/generators/pico_phone/rails/phone_number/phone_number_generator.rb
@@ -73,9 +77,12 @@ files:
 - lib/generators/pico_phone/rails/phone_number/templates/model.rb.tt
 - lib/phone_validator.rb
 - lib/pico_phone/rails.rb
+- lib/pico_phone/rails/engine.rb
 - lib/pico_phone/rails/extracted_phone_number.rb
 - lib/pico_phone/rails/extraction.rb
 - lib/pico_phone/rails/form_helper.rb
+- lib/pico_phone/rails/javascript.rb
+- lib/pico_phone/rails/javascript/pico_phone/rails/phone_controller.js
 - lib/pico_phone/rails/locale/en.yml
 - lib/pico_phone/rails/normalizer.rb
 - lib/pico_phone/rails/phone_search_index.rb
@@ -83,6 +90,7 @@ files:
 - lib/pico_phone/rails/region_resolution.rb
 - lib/pico_phone/rails/serializers/phone_number_serializer.rb
 - lib/pico_phone/rails/type.rb
+- lib/pico_phone/rails/validations_controller.rb
 - lib/pico_phone/rails/version.rb
 homepage: https://github.com/gjack/pico_phone-rails
 licenses:
@@ -111,5 +119,6 @@ requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
 summary: 'Rails integration for pico_phone: attribute type, validator, normalizer,
-  free-text extraction, phone search index, and ActiveJob serializer'
+  free-text extraction, phone search index, form field helpers, live validation, and
+  ActiveJob serializer'
 test_files: []