view_component-form 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf9294810dc61eeda3187f0a15bd0fd41076a1aff08e35088123ff7b6394a7bc
-  data.tar.gz: 1e354c3e739a66eabb5d4e33627ab6393a6385deebc4fbf05fbb7fdff514d8ce
+  metadata.gz: f44ea4d5228e0e3e42b68bac848d7806d73097cbbca8b27758d5f55b11ab0a94
+  data.tar.gz: 1fa7588808ca2371b6b82679747292b22f3ba126ead0e870906d8ccbeef3845d
 SHA512:
-  metadata.gz: 1ec60427e83e48970da97868e150f42796caeb0c4db320e6da67574aee28832e2d4c7fd540ecbdda3da3c6349e078d3a7038206ecd3c59934db58bc88fcc1a7e
-  data.tar.gz: '058769880aa90ff14e44c80e36e9db16c7eda9f0262c92112a025a16e208b5fcde83f79d2b011f82d3f8802abc7eff4155fdb146b629cfdb5557db89ee87b5f7'
+  metadata.gz: 36cf6c62ac032457150a59a4a1e1e8208752e01a44b3372b87b9ef4c8573523159cd34337fd784fb733fba89b0ad871883e569d0f141b115c18c6fcbc95245da
+  data.tar.gz: 985112bbfc1157644a3213b08fe4f4ca0375d5c76b0f58c4670083b8751a2134280a9e50fc50a4886320d61bdca227f207deac779de37b2fc58dd3cc86927a9b

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 Nothing yet
 
+## [0.2.7] - 2024-07-18
+### Added
+- Added parent_component configuration for field components (#160)
+- Added Ruby 3.3 support (#164)
+- Add `lookup_chain` customizability (#162)
+
+### Removed
+- Drop Ruby 2.7 support (#164)
+- Drop Rails 6.0 support (#164)
+
+## [0.2.6] - 2023-10-11
+### Added
+- Support for Rails 7.1 (#151)
+- Add `element_proc` option to `CollectionCheckBoxesComponent` and `CollectionRadioButtonsComponent` to customize the way the elements will be shown (#142)
+
 ## [0.2.5] - 2023-05-01
 ### Changed
 - Split `Form::Builder` into modules, to allow including only some modules instead of inheriting the whole class (#134)
@@ -99,7 +114,9 @@ Nothing yet
 - Add CHANGELOG (#50)
 - Add CI (#2)
 
-[Unreleased]: https://github.com/pantographe/view_component-form/compare/v0.2.5...HEAD
+[Unreleased]: https://github.com/pantographe/view_component-form/compare/v0.2.7...HEAD
+[0.2.7]: https://github.com/pantographe/view_component-form/compare/v0.2.6...v0.2.7
+[0.2.6]: https://github.com/pantographe/view_component-form/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/pantographe/view_component-form/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/pantographe/view_component-form/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/pantographe/view_component-form/compare/v0.2.2...v0.2.3

data/README.md

@@ -1,8 +1,6 @@
 # ViewComponent::Form
 
-**ViewComponent::Form** provides a `FormBuilder` with the same interface as [`ActionView::Helpers::FormBuilder`](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html), but using [ViewComponent](https://github.com/github/view_component)s for rendering the fields. It's a starting point for writing your own custom ViewComponents.
-
-:warning: **This is an early release: the API is subject to change until we reach `v1.0.0`.**
+**`ViewComponent::Form`** is a customizable form builder using the same interface as [`ActionView::Helpers::FormBuilder`](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) but with extensible [ViewComponent](https://github.com/github/view_component) components.
 
 Development of this gem is sponsored by:
 
@@ -10,34 +8,81 @@ Development of this gem is sponsored by:
 
 ## Compatibility
 
+> [!WARNING] > **This is an early release, and the API is subject to change until `v1.0.0`.**
+
 This gem is tested on:
-- Rails 6.0+ (with or without ActionText)
-- Ruby 2.7+
+
+- Rails 6.1+ (with or without ActionText)
+- Ruby 3.0+
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```shell
+bundle add view_component-form
+```
+
+### Configuration
 
 ```ruby
-gem 'view_component-form'
+# config/initializers/vcf.rb
+
+ViewComponent::Form.configure do |config|
+  config.parent_component = 'ApplicationFormComponent'
+end
 ```
 
-And then execute:
+| Attribute                   | Purpose                                               | Default                 |
+| --------------------------- | ----------------------------------------------------- | ----------------------- |
+| `parent_component` (string) | Parent class for all `ViewComponent::Form` components | `"ViewComponent::Base"` |
+
+#### Configuring component lookup
+
+`ViewComponent::Form` will automatically infer the component class with a `Component` suffix. You can customize the lookup using the `lookup_chain`:
+
+```rb
+# config/initializers/vcf.rb
+
+ViewComponent::Form.configure do |config|
+  without_component_suffix = lambda do |component_name, namespaces: []|
+    namespaces.lazy.map do |namespace|
+      "#{namespace}::#{component_name.to_s.camelize}".safe_constantize
+    end.find(&:itself)
+  end
+
+  config.lookup_chain.prepend(without_component_suffix)
+end
+```
 
-    $ bundle install
+`ViewComponent::Form` will iterate through the `lookup_chain` until a value is returned. By using `prepend` we can fallback on the default `ViewComponent::Form` lookup.
 
 ## Usage
 
-Add a `builder` param to your `form_for`, `form_with`, `fields_for` or `fields`:
+Add your own form builder.
+
+```shell
+bin/rails generate vcf:builder FormBuilder
+      create  app/helpers/form_builder.rb
+```
+
+To use the form builder:
+
+- add a `builder` param to your `form_for`, `form_with`, `fields_for` or `fields`:
 
 ```diff
 - <%= form_for @user do |f| %>
-+ <%= form_for @user, builder: ViewComponent::Form::Builder do |f| %>
++ <%= form_for @user, builder: FormBuilder do |f| %>
 ```
 
-You can also define a default FormBuilder at the controller level using [default_form_builder](https://api.rubyonrails.org/classes/ActionController/FormBuilder.html#method-i-default_form_builder).
+- or; set it as a default in your controller using [default_form_builder](https://api.rubyonrails.org/classes/ActionController/FormBuilder.html#method-i-default_form_builder).
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  default_form_builder FormBuilder
+end
+```
 
-Then call your helpers as usual:
+Then use ActionView form builder helpers as you would normally:
 
 ```erb
 <%# app/views/users/_form.html.erb %>
@@ -62,141 +107,67 @@ Then call your helpers as usual:
 <% end %>
 ```
 
-It should work out of the box, but does nothing particularly interesting for now.
-
-```html
-<form class="edit_user" id="edit_user_1" action="/users/1" accept-charset="UTF-8" method="post">
-  <input type="hidden" name="_method" value="patch" />
-  <input type="hidden" name="authenticity_token" value="[...]" />
-
-  <label for="user_first_name">First name</label>
-  <input type="text" value="John" name="user[first_name]" id="user_first_name" />
-
-  <label for="user_last_name">Last name</label>
-  <input type="text" value="Doe" name="user[last_name]" id="user_last_name" />
-
-  <label for="user_email">E-mail</label>
-  <input type="email" value="john.doe@example.com" name="user[email]" id="user_email" />
-
-  <label for="user_password">Password</label>
-  <input type="password" name="user[password]" id="user_password" aria-describedby="user_password_description" />
-  <div id="user_password_description">
-    <div>The password should be at least 8 characters long</div>
-  </div>
-</form>
-```
-
-The `ViewComponent::Form::*` components are included in the gem.
-
-### Customizing the `FormBuilder` and the components
-
-First, generate your own `FormBuilder`:
-
-```console
-bin/rails generate vcf:builder CustomFormBuilder
-
-      create  app/helpers/custom_form_builder.rb
-```
+### Customizing built-in components
 
-This allows you to pick the namespace your components will be loaded from.
+The `ViewComponent::Form::Builder` will use the provided `namespace` to find any components you've customized.
 
-```rb
-# app/helpers/custom_form_builder.rb
-class CustomFormBuilder < ViewComponent::Form::Builder
-  # Set the namespace you want to use for your own components
-  namespace "Custom::Form"
+```ruby
+# app/helpers/form_builder.rb
+class FormBuilder < ViewComponent::Form::Builder
+  namespace Form
 end
 ```
 
-Use the generator options to change the default namespace or the path where the file will be created:
-
-```console
-bin/rails generate vcf:builder AnotherCustomFormBuilder --namespace AnotherCustom::Form --path app/forms
-
-      create  app/forms/another_custom_form_builder.rb
-```
+Let's customize the `text_field` helper by generating a new [ViewComponent](https://github.com/github/view_component) in the namespace defined within the builder.
 
-```rb
-# app/forms/another_custom_form_builder.rb
-class AnotherCustomFormBuilder < ViewComponent::Form::Builder
-  # Set the namespace you want to use for your own components
-  namespace "AnotherCustom::Form"
-end
+```shell
+bin/rails generate component Form::TextField --parent ViewComponent::Form::TextFieldComponent --inline
 ```
 
-Another approach is to include only some modules instead of inheriting from the whole class:
-
-```rb
-# app/forms/modular_custom_form_builder.rb
-class ModularCustomFormBuilder < ActionView::Helpers::FormBuilder
-  # Provides `render_component` method and namespace management
-  include ViewComponent::Form::Renderer
-
-  # Exposes a `validation_context` to your components
-  include ViewComponent::Form::ValidationContext
-
-  # All standard Rails form helpers
-  include ViewComponent::Form::Helpers::Rails
-
-  # Backports of Rails 7 form helpers (can be removed if you're running Rails >= 7)
-  # include ViewComponent::Form::Helpers::Rails7Backports
-
-  # Additional form helpers provided by ViewComponent::Form
-  # include ViewComponent::Form::Helpers::Custom
-
-  # Set the namespace you want to use for your own components
-  namespace "AnotherCustom::Form"
+```ruby
+# app/components/form/text_field_component.rb
+class Form::TextFieldComponent < ViewComponent::Form::TextFieldComponent
+  def html_class
+    class_names("custom-text-field", "has-error": method_errors?)
+  end
 end
 ```
 
-Now let's generate your own components to customize their rendering. We can use the standard view_component generator:
-
-```console
-bin/rails generate component Custom::Form::TextField --inline --parent ViewComponent::Form::TextFieldComponent
-
-      invoke  test_unit
-      create  test/components/custom/form/text_field_component_test.rb
-      create  app/components/custom/form/text_field_component.rb
-```
-
-:warning: The `--parent` option is available since ViewComponent [`v2.41.0`](https://viewcomponent.org/CHANGELOG.html#2410). If you're using a previous version, you can always edit the generated `Custom::Form::CustomTextFieldComponent` class to make it inherit from `ViewComponent::Form::TextFieldComponent`.
+In this case we're leveraging the [`#class_names`](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-class_names) helper to:
 
-Change your forms to use your new builder:
+- always add the `custom-text-field` class;
+- add the `has-error` class if there is an error on the attribute (using `ViewComponent::Form::FieldComponent#method_errors?`).
 
-```diff
-- <%= form_for @user, builder: ViewComponent::Form::Builder do |f| %>
-+ <%= form_for @user, builder: CustomFormBuilder do |f| %>
-```
+### Adding your own custom helpers and components
 
-You can then customize the behavior of your `Custom::Form::CustomTextFieldComponent`:
+Add the helper method to your `ViewComponent::Form::Builder`
 
 ```rb
-# app/components/custom/form/text_field_component.rb
+# app/helpers/form_builder.rb
+class FormBuilder < ViewComponent::Form::Builder
+  def year_field(method, options = {})
+    render_component(:year_field, @object_name, method, objectify_options(options))
+  end
 
-class Admin::Form::TextFieldComponent < ViewComponent::Form::TextFieldComponent
-  def html_class
-    class_names("custom-text-field", "has-error": method_errors?)
+  def money_field(method, currencies = [], options = {})
+    render_component(:money_field, @object_name, method, currencies, objectify_options(options))
   end
 end
 ```
 
-In this case we leverage the [`#class_names`](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-class_names) helper to:
-- always add the `custom-text-field` class;
-- add the `has-error` class if there is an error on the attribute (using `ViewComponent::Form::FieldComponent#method_errors?`).
+Add your component which can optionally inherit from:
 
-The rendered form field will now look like this:
+- `ViewComponent::Form::FieldComponent` (suggested when adding a field because of helpers)
+- `ViewComponent::Form::BaseComponent`
+- or any of the `ViewComponent::Form::*Component` such as `ViewComponent::Form::TextFieldComponent`
 
-```html
-<input class="custom-text-field" type="text" value="John" name="user[first_name]" id="user_first_name">
+```rb
+# app/components/form/year_field_component.rb
+class Form::YearFieldComponent < ViewComponent::Form::FieldComponent # or ViewComponent::Form::BaseComponent
+end
 ```
 
-You can use the same approach to inject options, wrap the input in a `<div>`, etc.
-
-We'll add more use cases to the documentation soon.
-
-### Building your own components
-
-When building your own ViewComponents for using in forms, it's recommended to inherit from `ViewComponent::Form::FieldComponent`, so you get access to the following helpers:
+When inheriting from `ViewComponent::Form::FieldComponent`, you get access to the following helpers:
 
 #### `#label_text`
 
@@ -239,16 +210,27 @@ en:
 Renders:
 
 ```html
-<form class="edit_user" id="edit_user_1" action="/users/1" accept-charset="UTF-8" method="post">
+<form
+  class="edit_user"
+  id="edit_user_1"
+  action="/users/1"
+  accept-charset="UTF-8"
+  method="post"
+>
   <!-- ... -->
   <label>
     Your first name<br />
-    <input type="text" value="John" name="user[first_name]" id="user_first_name" />
+    <input
+      type="text"
+      value="John"
+      name="user[first_name]"
+      id="user_first_name"
+    />
   </label>
 </form>
 ```
 
-#### Validations
+### Validations
 
 Let's consider the following model for the examples below.
 
@@ -339,6 +321,25 @@ def length_validator
 end
 ```
 
+### Setting up your own base component class
+
+1. Setup some base component from which the form components will inherit from
+
+```rb
+class ApplicationFormComponent < ViewComponent::Base
+end
+```
+
+2. Configure the parent component class
+
+```rb
+# config/initializers/vcf.rb
+
+ViewComponent::Form.configure do |config|
+  config.parent_component = 'ApplicationFormComponent'
+end
+```
+
 ### Using your form components without a backing model
 
 If you want to ensure that your fields display consistently across your app, you'll need to lean on Rails' own helpers. You may be used to using form tag helpers such as `text_field_tag` to generate tags, or even writing out plain HTML tags. These can't be integrated with a form builder, so they won't offer you the benefits of this gem.
@@ -413,7 +414,7 @@ For more complex components, we recommend the [`rspec-html-matchers` gem](https:
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, run `bin/release x.x.x`, which will update the `version.rb` file, open the changelog for edition, create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/app/components/concerns/view_component/form/element_proc.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    module ElementProc
+      attr_reader :element_proc
+
+      def initialize(*args, **kwargs)
+        super
+        set_element_proc!
+      end
+
+      protected
+
+      def set_element_proc!
+        options_element_proc = options.delete(:element_proc)
+        html_options_element_proc = html_options.delete(:element_proc)
+
+        if options_element_proc && html_options_element_proc
+          raise ArgumentError, "#{self.class.name} received :element_proc twice, expected only once"
+        end
+
+        @element_proc = options_element_proc || html_options_element_proc
+      end
+    end
+  end
+end

data/app/components/view_component/form/base_component.rb

@@ -2,7 +2,7 @@
 
 module ViewComponent
   module Form
-    class BaseComponent < ViewComponent::Base
+    class BaseComponent < ViewComponent::Form.configuration.parent_component.constantize
       class << self
         attr_accessor :default_options
       end

data/app/components/view_component/form/collection_check_boxes_component.rb

@@ -3,6 +3,8 @@
 module ViewComponent
   module Form
     class CollectionCheckBoxesComponent < FieldComponent
+      include ElementProc
+
       attr_reader :collection, :value_method, :text_method, :html_options
 
       def initialize( # rubocop:disable Metrics/ParameterLists
@@ -36,7 +38,7 @@ module ViewComponent
           options,
           html_options,
           &content
-        ).render
+        ).render(&element_proc)
       end
 
       protected

data/app/components/view_component/form/collection_radio_buttons_component.rb

@@ -3,6 +3,8 @@
 module ViewComponent
   module Form
     class CollectionRadioButtonsComponent < FieldComponent
+      include ElementProc
+
       attr_reader :collection, :value_method, :text_method, :html_options
 
       def initialize( # rubocop:disable Metrics/ParameterLists
@@ -36,7 +38,7 @@ module ViewComponent
           options,
           html_options,
           &content
-        ).render
+        ).render(&element_proc)
       end
 
       protected

data/app/components/view_component/form/field_component.rb

@@ -71,13 +71,13 @@ module ViewComponent
       end
 
       def optional?(context: validation_context)
-        return nil if object.nil?
+        return false if object.nil?
 
         !required?(context: context)
       end
 
       def required?(context: validation_context)
-        return nil if object.nil?
+        return false if object.nil?
 
         validators(context: context).any?(ActiveModel::Validations::PresenceValidator)
       end

data/lib/view_component/form/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class Configuration
+      attr_accessor :parent_component, :lookup_chain
+
+      def initialize
+        @parent_component = "ViewComponent::Base"
+        @lookup_chain = [
+          lambda do |component_name, namespaces: []|
+            namespaces.lazy.map do |namespace|
+              "#{namespace}::#{component_name.to_s.camelize}Component".safe_constantize
+            end.find(&:itself)
+          end
+        ]
+      end
+    end
+  end
+end

data/lib/view_component/form/engine.rb

@@ -6,6 +6,7 @@ module ViewComponent
     class Engine < ::Rails::Engine
       config.autoload_once_paths = %W[
         #{root}/app/components
+        #{root}/app/components/concerns
         #{root}/app/lib
       ]
     end

data/lib/view_component/form/helpers/rails.rb

@@ -46,7 +46,7 @@ module ViewComponent
             :datetime_local_field, @object_name, method, objectify_options(options)
           )
         end
-        alias datetime_locale_field datetime_field
+        alias datetime_local_field datetime_field
 
         def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
           render_component(

data/lib/view_component/form/renderer.rb

@@ -52,9 +52,9 @@ module ViewComponent
 
       def component_klass(component_name)
         @__component_klass_cache[component_name] ||= begin
-          component_klass = self.class.lookup_namespaces.filter_map do |namespace|
-            "#{namespace}::#{component_name.to_s.camelize}Component".safe_constantize || false
-          end.first
+          component_klass = ViewComponent::Form.configuration.lookup_chain.lazy.map do |lookup|
+            lookup.call(component_name, namespaces: lookup_namespaces)
+          end.find(&:itself)
 
           unless component_klass.is_a?(Class) && component_klass < ViewComponent::Base
             raise NotImplementedComponentError, "Component named #{component_name} doesn't exist " \

data/lib/view_component/form/version.rb

@@ -2,6 +2,6 @@
 
 module ViewComponent
   module Form
-    VERSION = "0.2.5"
+    VERSION = "0.2.7"
   end
 end

data/lib/view_component/form.rb

@@ -5,6 +5,15 @@ require "zeitwerk"
 
 module ViewComponent
   module Form
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component-form
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - Pantographe
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-01 00:00:00.000000000 Z
+date: 2024-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview
@@ -16,40 +16,40 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: 6.1.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: 6.1.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: 6.1.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: 6.1.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +94,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/components/concerns/view_component/form/element_proc.rb
 - app/components/view_component/form/base_component.rb
 - app/components/view_component/form/button_component.rb
 - app/components/view_component/form/check_box_component.rb
@@ -135,6 +136,7 @@ files:
 - lib/view_component/form.rb
 - lib/view_component/form/builder.rb
 - lib/view_component/form/class_names_helper.rb
+- lib/view_component/form/configuration.rb
 - lib/view_component/form/engine.rb
 - lib/view_component/form/helpers/custom.rb
 - lib/view_component/form/helpers/rails.rb
@@ -160,14 +162,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.5.14
 signing_key:
 specification_version: 4
 summary: Rails FormBuilder for ViewComponent