pico_phone-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad67a4a67bfcdfd2e94072a2989dd25c23896ed5d97ef6b506a08c31548fe9f1
-  data.tar.gz: 1414db39189fdaed84124aaf1e10e8abb5ed02414668130a9f37ceb4b682ccad
+  metadata.gz: 8e4c80e86756e81b40665de3fe0c6436ee462b8d5ea011992e3a8507eaedb323
+  data.tar.gz: 8ce58cb67fc8b73d92ba3b945b303a5c7360265a6ac217e5c0e1e1806c2157b7
 SHA512:
-  metadata.gz: 6aaeb277b412aa8acea4729c56a9e1c371a3e967cf4c4162d9aa430e1409842e075cf810ff2db665b605dff47ebd18e85d3367cbff4c7652fc6ed92563371700
-  data.tar.gz: e31a7f628e3b16386fc79ccc3f0d9ceb67d41db69901ccbe7ff455475da9afc3e5a05fc316b5f85946071eb4e333bb7f9e0bb10a92955d3bb99bd5f721f89b7a
+  metadata.gz: ca51d0d37018f62fceba7ac87b2f0ebd42f4e537b55d9814e33488b48ea30aa822fd18eef92713d4a9b464e8849298e91ca41b430d1f99d471aba28b371b494b
+  data.tar.gz: dba580ca4a43fe7b83e776cf4e8430a8ca19cf9fc97f0f059c423fdd4e6ae6117f9c1dd702b4ccf878a13f3a848ac271041b62e3350d9143b230cc16523f1d33

data/README.md

@@ -206,6 +206,48 @@ 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, reformatted to national format if what's there
+parses validly, the same reformat-on-blur behavior as the plain
+(non-`live`) helper.
+
+`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,18 @@ module PicoPhone
       phone_number.valid? ? phone_number.national : string
     end
 
+    # @param region [String, nil]
+    # @param validate_path [String] the mounted engine's validate endpoint
+    # @return [Hash] Stimulus data attributes for +live:+ validation
+    def self.live_validation_data(region, validate_path)
+      {
+        controller: "phone",
+        action: "input->phone#validate blur->phone#reformat",
+        phone_region_value: region.to_s,
+        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 +51,14 @@ 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
       # @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, **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)
+          options[:data] = data.merge(options[:data] || {})
+        end
         text_field_tag(name, display_value, options.merge(type: "tel"))
       end
     end
@@ -59,10 +76,15 @@ 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
       # @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, **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)
+          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,38 @@
+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, 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()
+    if (data.valid) this.element.value = data.national
+  }
+
+  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 }),
+    })
+    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,37 @@
+# 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?
+
+        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
+      end
+
+      private
+
+      # @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.5.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.5.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: []