pico_phone-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0524cbb733d2edc10a4a6f0fcb13197f2853d58f437286c7aea7bf4c30d53092
-  data.tar.gz: b29da13e7d7308a7e4e60fda8be21fbd467a5e138e6d6509ce97a719cac77afd
+  metadata.gz: ad67a4a67bfcdfd2e94072a2989dd25c23896ed5d97ef6b506a08c31548fe9f1
+  data.tar.gz: 1414db39189fdaed84124aaf1e10e8abb5ed02414668130a9f37ceb4b682ccad
 SHA512:
-  metadata.gz: c82086362cc5c8dcf692ba712c7a961b076c2d87becfd5d3ff9ccece17d7a1da095558d76748b83ecdee46fc6067c884671d6f681e2b037cf14fb06ffccc9e05
-  data.tar.gz: 0cc7b9175ebdbef5c3cddbabae8fbb8b8705b5cd7a8ffbce7077b4ef46510f895401bd6699105601d8ce13730692f09c513e4503568fe3dd2e17c4850a80bd8f
+  metadata.gz: 6aaeb277b412aa8acea4729c56a9e1c371a3e967cf4c4162d9aa430e1409842e075cf810ff2db665b605dff47ebd18e85d3367cbff4c7652fc6ed92563371700
+  data.tar.gz: e31a7f628e3b16386fc79ccc3f0d9ceb67d41db69901ccbe7ff455475da9afc3e5a05fc316b5f85946071eb4e333bb7f9e0bb10a92955d3bb99bd5f721f89b7a

data/README.md

@@ -181,6 +181,31 @@ 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.
+
 ### ActiveJob serializer
 
 ```ruby

data/lib/pico_phone/rails/form_helper.rb

@@ -0,0 +1,70 @@
+# 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
+
+    # 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
+      # @return [String] an HTML-safe +<input type="tel">+ tag
+      def pico_phone_field_tag(name, value = nil, region: nil, **options)
+        display_value = PicoPhone::Rails.phone_field_display_value(value, region)
+        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}
+      # @return [String] an HTML-safe +<input type="tel">+ tag
+      def pico_phone_field(method, region: nil, **options)
+        resolved_region = PicoPhone::Rails.resolve_region(region, object)
+        display_value = PicoPhone::Rails.phone_field_display_value(object.public_send(method), resolved_region)
+        text_field(method, options.merge(value: display_value, type: "tel"))
+      end
+    end
+  end
+end

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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pico_phone-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Gabi Jack
@@ -75,6 +75,7 @@ files:
 - lib/pico_phone/rails.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/locale/en.yml
 - lib/pico_phone/rails/normalizer.rb
 - lib/pico_phone/rails/phone_search_index.rb