pico_phone-rails 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0524cbb733d2edc10a4a6f0fcb13197f2853d58f437286c7aea7bf4c30d53092
-  data.tar.gz: b29da13e7d7308a7e4e60fda8be21fbd467a5e138e6d6509ce97a719cac77afd
+  metadata.gz: 8e4c80e86756e81b40665de3fe0c6436ee462b8d5ea011992e3a8507eaedb323
+  data.tar.gz: 8ce58cb67fc8b73d92ba3b945b303a5c7360265a6ac217e5c0e1e1806c2157b7
 SHA512:
-  metadata.gz: c82086362cc5c8dcf692ba712c7a961b076c2d87becfd5d3ff9ccece17d7a1da095558d76748b83ecdee46fc6067c884671d6f681e2b037cf14fb06ffccc9e05
-  data.tar.gz: 0cc7b9175ebdbef5c3cddbabae8fbb8b8705b5cd7a8ffbce7077b4ef46510f895401bd6699105601d8ce13730692f09c513e4503568fe3dd2e17c4850a80bd8f
+  metadata.gz: ca51d0d37018f62fceba7ac87b2f0ebd42f4e537b55d9814e33488b48ea30aa822fd18eef92713d4a9b464e8849298e91ca41b430d1f99d471aba28b371b494b
+  data.tar.gz: dba580ca4a43fe7b83e776cf4e8430a8ca19cf9fc97f0f059c423fdd4e6ae6117f9c1dd702b4ccf878a13f3a848ac271041b62e3350d9143b230cc16523f1d33

data/README.md

@@ -181,6 +181,73 @@ reasoning as `containing_phone_number` above.
 every model, so identical names would collide and one would silently shadow
 the other.)
 
+### Form field helper
+
+```ruby
+<%= pico_phone_field_tag :phone, @contact.phone, region: "US" %>
+<%= f.pico_phone_field :phone, region: "US" %>
+```
+
+Renders an `<input type="tel">` showing the number in national format when
+it parses validly, or exactly what the user typed otherwise -- so re-editing
+an invalid or partial number never shows a blank or garbled reformat. Works
+whether the attribute is a plain string or already a `PicoPhone::PhoneNumber`
+(via the attribute type above), and accepts `region:` as a String, Symbol
+(instance method on the form's object), or Proc, same resolution rules as
+extraction and the search index:
+
+```ruby
+f.pico_phone_field :phone, region: ->(contact) { contact.organization.region }
+```
+
+Named `pico_phone_field`/`pico_phone_field_tag` rather than Rails' own
+`phone_field`/`f.phone_field` (an existing core alias for `telephone_field`,
+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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module PicoPhone
+  module Rails
+    # Computes what a phone field should display: the number's national
+    # format if it parses validly, the raw string otherwise -- so a user
+    # re-editing an invalid or partial number sees exactly what they typed,
+    # not a blank or garbled reformat. Shared by {FormHelper} and
+    # {FormBuilderExtension}.
+    #
+    # @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
+    # @return [String, nil]
+    def self.phone_field_display_value(value, region)
+      return nil if value.nil?
+      return (value.valid? ? value.national : value.to_s) if value.is_a?(PicoPhone::PhoneNumber)
+
+      string = value.to_s
+      return string if string.empty?
+
+      phone_number = PicoPhone.parse(string, region)
+      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
+    # underlying +<input>+ free to submit whatever string the user types.
+    #
+    # Named distinctly from Rails' own +phone_field_tag+/+f.phone_field+
+    # (a built-in alias for +telephone_field+, plain +<input type="tel">+
+    # with no formatting) rather than overriding it -- 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.
+    #
+    # @example
+    #   pico_phone_field_tag :phone, @contact.phone, region: "US"
+    module FormHelper
+      # @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, 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
+
+    # Included into ActionView::Helpers::FormBuilder by the railtie once
+    # ActionView loads. Adds +f.pico_phone_field+, mirroring
+    # {FormHelper#pico_phone_field_tag} but bound to the form's object.
+    #
+    # @example
+    #   f.pico_phone_field :phone, region: "US"
+    #   f.pico_phone_field :phone, region: ->(contact) { contact.organization.region }
+    module FormBuilderExtension
+      # @param method [Symbol] the attribute to render
+      # @param region [String, Symbol, Proc, nil] ISO 3166-1 alpha-2 region for interpreting the attribute's
+      #   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, 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
+  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/railtie.rb

@@ -37,6 +37,14 @@ module PicoPhone
         end
       end
 
+      initializer "pico_phone_rails.form_helper" do
+        ActiveSupport.on_load(:action_view) do
+          require "pico_phone/rails/form_helper"
+          include PicoPhone::Rails::FormHelper
+          ::ActionView::Helpers::FormBuilder.include PicoPhone::Rails::FormBuilderExtension
+        end
+      end
+
       initializer "pico_phone_rails.i18n" do |app|
         app.config.i18n.load_path += Dir[File.expand_path("locale/*.yml", __dir__)]
       end

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.3.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.3.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,8 +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
@@ -82,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:
@@ -110,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: []