view_partial_form_builder 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99ab630e8601d66da9873d48a3c1abbb3611df65e8aa57cb165b3397f2d2b085
-  data.tar.gz: d1a221e7ce27c1e3c48b6dad21c9cf5c72c67db3da17cf8d83a072d7691f5211
+  metadata.gz: 1d1550e43fb981483d25dedf89ab64478b5dd2c5803b4aa7345ae6d7efba4fe2
+  data.tar.gz: d8bb992d8d959d2288c761d764275af9e470081145884b6bfcff7b7dda3fdc45
 SHA512:
-  metadata.gz: 44950718466b81b4928ffe33060cc7a90cce087702e8d3830d189bd2e5f1ec1b8fd0bdca68845f94ffdda02ec15febe8fa847bc78dc613e00682f28eab7a072c
-  data.tar.gz: 1bae64c4d9601d0a265b442bc9de563c691a2d76753414901aac0db176757bc132ff22ed1e92e890d3415b2cc277d705b4cffe1830fe97c7a846176a59803f1f
+  metadata.gz: 121978b8280e71e3cf114291cf4874949c9323f7b909ab7cd93602f1a3fb00b143c2028ed1188623c8b926efe8b3a27e67005947599d66b8e1cb33c98d8c589e
+  data.tar.gz: 9e56d40123f55fac7ee53b3bd3e087ccc35bdf3ca709485cad0d636fb41f7f684744dbc068d7af13bcdc6aa246e9707373c557f792d86a1d3fee1cd76468e4f0

data/README.md

@@ -87,7 +87,7 @@ generating HTML through Rails' helpers:
 <%# app/views/form_builder/_button.html.erb %>
 
 <div class="button-wrapper">
-  <%= form.button(*arguments, **options, &block) %>
+  <%= form.button(value, options, &block) %>
 </div>
 ```
 
@@ -116,31 +116,8 @@ In addition, each view partial receives:
 * `form` - a reference to the instance of `ViewPartialFormBuilder`, which is a
   descendant of [`ActionView::Helpers::FormBuilder`][FormBuilder]
 
-* `arguments` - an Array containing the arguments the helper received, in the
-  order they were received. This can be useful to pass to the view partial's
-  helper by [splatting them][splat] out.
-
 * `&block` - a callable, `yield`-able block if the helper method was passed one
 
-In cases when a [`ActionView::Helpers::FormBuilder` helper
-method][FormBuilder]'s last arguments are options (either `Hash` instances or
-[keyword arguments][]), they're omitted from the `arguments` array.
-
-If you want to pass-through all arguments, options, and block parameters, you
-can splat them out:
-
-```html+erb
-<%# app/views/form_builder/_label.html.erb %>
-
-<%= form.label(*arguments, **options, &block) %>
-```
-
-```html+erb
-<%# app/views/form_builder/_select.html.erb %>
-
-<%= form.select(*arguments, **html_options, &block) %>
-```
-
 #### Handling DOMTokenList attributes
 
 An [HTML element's `class` attribute][mdn-class] is treated by browsers as a
@@ -158,16 +135,12 @@ When rendering a field's DOMTokenList-backed attributes (like `class` or
 controllers][stimulus-controller]), transforming and combining singular `String`
 instances into lists of token can be very useful.
 
-To simplify those scenarios, a partial's template-local optional attributes are
-made available with the `#merge_token_lists` method.
-
 These optional attributes are available through the `options` or `html_options`
 partial-local variables. Their name will depend on the partial's corresponding
 [`ActionView::Helpers::FormBuilder`][FormBuilder] interface.
 
-Calls to `#merge_token_lists` will merge the key-value pairs and return a new
-Hash-like structure. The attribute's value will be transformed into an `Array`.
-Given call to `form.text_field` and a corresponding partial declaration:
+To "merge" attributes together, you can combine Ruby's `String` interpolation
+and `Hash#delete`:
 
 ```html+erb
   <%# app/views/users/new.html.erb %>
@@ -177,7 +150,11 @@ Given call to `form.text_field` and a corresponding partial declaration:
 
 <# app/views/form_builder/_text_field.html.erb %>
 
-<%= form.text_field(*arguments, **options.merge_token_lists(class: "text-field")) %>
+<%= form.text_field(
+  method,
+  class: "text-field #{options.delete(:class)}",
+  **options
+) %>
 ```
 
 The resulting HTML `<input>` element will merge have its [`class`
@@ -192,7 +169,6 @@ values:
 [button]: https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-button
 [local_assigns]: https://api.rubyonrails.org/classes/ActionView/Template.html#method-i-local_assigns
 [splat]: https://ruby-doc.org/core-2.2.0/doc/syntax/calling_methods_rdoc.html#label-Array+to+Arguments+Conversion
-[keyword arguments]: https://thoughtbot.com/blog/ruby-2-keyword-arguments
 [mdn-class]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class
 [DOMTokenList]: https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList
 [classList]: https://developer.mozilla.org/en-US/docs/Web/API/Element/classList
@@ -210,7 +186,7 @@ block-local `form` variable:
 ```erb
 <%# app/views/users/form_builder/_email_field.html.erb %>
 
-<%= form.default.email_field(*arguments, **options) %>
+<%= form.default.email_field(method, options) %>
 ```
 
 When passing a `model:` or `scope:` to calls to [`form_with`][form_with],
@@ -225,26 +201,41 @@ For example, when calling `form_with(model: User.new)`, a partial declared in
 <%# app/views/users/form_builder/_password_field.html.erb %>
 
 <div class="password-field-wrapper">
-  <%= form.password_field(*arguments, **options) %>
+  <%= form.password_field(method, options) %>
 </div>
 ```
 
-If you'd like to render a specific partial for a field, you can declare the name
-as the `partial:` option:
+If you'd like to render a specific partial for a field, make sure that you pass
+along the `form:` (along with any other partial-local variables) as part of the
+`render` call's `locals:` option:
+
 
 ```erb
 <%# app/views/users/new.html.erb %>
 
 <%= form_with(model: User.new) do |form| %>
-  <%= form.email_field(:email, partial: "emails/my_special_text_field") %>
+  <%= render("emails/my_special_email_field", {
+    form: form,
+    method: :email,
+    options: { class: "user-email" },
+  ) %>
 <% end %>
+
+<%# app/views/emails/_my_special_email_field.html.erb %>
+
+<%= form.email_field(
+  method,
+  class: "my-special-email #{options.delete(:class)},
+  **options
+) %>
 ```
 
 #### Composing partials
 
-Passing a `partial:` key can be useful for layering partials on top of one
-another. For instance, consider an administrative interface that shares styles
-with a consumer facing site, but has additional bells and whistles.
+Layering partials on top of one another can be useful to share foundational
+styles and configuration across your fields. For instance, consider an
+administrative interface that shares styles with a consumer facing site, but has
+additional bells and whistles.
 
 Declare the consumer facing inputs (in this example, `<input type="search">`):
 
@@ -252,11 +243,16 @@ Declare the consumer facing inputs (in this example, `<input type="search">`):
 <%# app/views/form_builder/_search_field.html.erb %>
 
 <%= form.search_field(
-  *arguments,
-  **options.merge_token_lists(
-    class: "search-field",
-    "data-controller": "input->search#executeQuery",
-  ),
+  method,
+  class: "
+    search-field
+    #{options.delete(:class}
+  ",
+  "data-controller": "
+    input->search#executeQuery
+    #{options.delete(:"data-controller")}
+  ",
+  **options
 ) %>
 ```
 
@@ -267,12 +263,15 @@ foundation built by the more general definitions:
 <%# app/views/admin/form_builder/_search_field.html.erb %>
 
 <%= form.search_field(
-  *arguments,
-  partial: "form_builder/search_field",
-  **options.merge_token_lists(
-    class: "search-field--admin",
-    "data-controller": "focus->admin-search#clearResults",
-  ),
+  method,
+  class: "
+    search-field--admin
+    #{options.delete(:class}
+  ",
+  "data-controller": "
+    focus->admin-search#clearResults
+    #{options.delete(:"data-controller")}
+  ",
 ) %>
 ```
 

data/lib/view_partial_form_builder/form_builder.rb

@@ -261,9 +261,17 @@ module ViewPartialFormBuilder
     def render_partial(field, locals, fallback:, &block)
       options = locals.fetch(:options, {})
       partial_override = options.delete(:partial)
-      locals = objectify_options(options).merge(locals, form: self)
+      options_as_locals = objectify_options(options)
+      locals = DeprecatedHash.new(
+        options_as_locals.merge(locals, form: self),
+        deprecated_keys: options_as_locals.keys + [:arguments],
+      )
 
       partial = if partial_override.present?
+        ActiveSupport::Deprecation.new("0.2.0", "ViewPartialFormBuilder").warn(<<~WARNING)
+          Providing a `partial:` option for a form field is deprecated.
+        WARNING
+
         find_partial(partial_override, locals, prefixes: [])
       else
         find_partial(field, locals, prefixes: prefixes_after(field))
@@ -284,7 +292,15 @@ module ViewPartialFormBuilder
         prefixes,
         template_is_partial,
         locals.keys,
-      ).first
+      ).first.tap do |partial|
+        root_directory = ViewPartialFormBuilder.view_partial_directory
+
+        if partial&.virtual_path == "#{root_directory}/_#{template_name}"
+          ActiveSupport::Deprecation.new("0.2.0", "ViewPartialFormBuilder").warn(<<~WARNING.strip)
+            Declare root-level partials in app/views/application/#{root_directory}/, not app/views/#{root_directory}/.
+          WARNING
+        end
+      end
     end
 
     def prefixes_after(template_name)
@@ -310,4 +326,22 @@ module ViewPartialFormBuilder
       end
     end
   end
+
+  class DeprecatedHash < Hash
+    def initialize(hash, deprecated_keys: [])
+      super()
+      merge!(hash)
+      @deprecated_keys = deprecated_keys
+    end
+
+    def [](key)
+      if @deprecated_keys.include?(key)
+        ActiveSupport::Deprecation.new("0.2.0", "ViewPartialFormBuilder").warn <<~WARNING
+          Accessing `#{key}` from partials is deprecated.
+        WARNING
+      end
+
+      super
+    end
+  end
 end

data/lib/view_partial_form_builder/html_attributes.rb

@@ -1,5 +1,13 @@
 module ViewPartialFormBuilder
   class HtmlAttributes
+    deprecate merge_token_lists: <<~'WARNING', deprecator: ActiveSupport::Deprecation.new("0.2.0", "ViewPartialFormBuilder")
+
+      As an alternative, merge arguments through String interpolation:
+
+      <%= form.label(method, class: "label #{options.delete(:class)}", **options) %>
+
+    WARNING
+
     def initialize(**attributes)
       @attributes = attributes
     end

data/lib/view_partial_form_builder/version.rb

@@ -1,3 +1,3 @@
 module ViewPartialFormBuilder
-  VERSION = '0.1.4'
+  VERSION = '0.1.5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: view_partial_form_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Sean Doyle