view_component-form 0.1.3 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c0eb4e8d777e0554258f10fd65506812b1ffdb89ea8927f4411a39e8369ec51
-  data.tar.gz: f337c5f45fbf26c7b0f1e1062412a5be2be51bc8489e4f8ba99dd31210041f2c
+  metadata.gz: d0ed0226343359de2defe0706095e30208f85b2921126058b9072c682242ed16
+  data.tar.gz: 44fda6fd050fcc85d147105b2aa61a958a60faf2cb24d17cc95e7187f1e3e346
 SHA512:
-  metadata.gz: dd36ae659c3cfe4f951a8a9a0c0491aed016f8e21f982388c1e08f899000e9bbd40b6f53cdef0ed2fea6236e6bdfd2d7b29a41533d63a73ee730bd16b39e4464
-  data.tar.gz: fc4ad61d7bab99c6da63f708dc044e6457bae391484dc1776672330fa1748554f4cd5b554e06a2b89a25c29fc4419d6a1cf9b5d689a7ba0f7fc4d73a2b392d7e
+  metadata.gz: bb8c4782353f49a18f4ff0c6146f33dbb7d3e937028ff1f078c8d34d1a986d45e8a5f0ef357e41e022d7a68cd4d8f8d8bde49ff4772a0eb0b9a14a41d505b43d
+  data.tar.gz: d2b136b58916cc9d401a3267f7d198c8803a86d3c9cbfd57dcb75c41d809e71fc3b605b628460f1406a45c1bcbceb49d6eb1ef9ef069ff5bc7d78562b11a132d

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 Nothing yet
 
+## [0.2.2] - 2022-03-23
+### Changed
+- Improve conditional ActionText support (#118)
+
+## [0.2.1] - 2022-03-17
+### Added
+- Conditional ActionText support (#117)
+
+### Fixed
+- Fix broken gem initialization due to missing ViewComponent::Form constant (#114)
+- Initialize empty WeekdaySelectComponent if Rails < 7 to fix Zeitwerk error (#115)
+
+## [0.2.0] - 2022-03-02
+### Added
+- Test BuilderGenerator with generator\_spec (#64)
+- Add HintComponent and ErrorMessageComponent (#98)
+- Add `validation_context` option to `Form::Builder` (#101)
+- Add `validators` helper to `FieldComponent` (#101)
+- Add `optional?` and `required?` helpers to `FieldComponent` (#101)
+- Add `label_text` helper (#103)
+- Add `field_id` helper, backported from Rails 7.0 (#104)
+- Add `weekday_select` helper (#105)
+- Add README section about supported helpers (#106)
+- Setup zeitwerk (#107)
+- Add documentation for tests (#108)
+
 ## [0.1.3] - 2022-01-11
 ### Fixed
 - Update dependencies for Rails 7.0.0 (#96)
@@ -51,7 +77,10 @@ Nothing yet
 - Add CHANGELOG (#50)
 - Add CI (#2)
 
-[Unreleased]: https://github.com/pantographe/view_component-form/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/pantographe/view_component-form/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/pantographe/view_component-form/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/pantographe/view_component-form/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/pantographe/view_component-form/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/pantographe/view_component-form/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/pantographe/view_component-form/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/pantographe/view_component-form/compare/v0.1.0...v0.1.1

data/README.md

@@ -7,7 +7,7 @@
 ## Compatibility
 
 This gem is tested on:
-- Rails 6.0+
+- Rails 6.0+ (with or without ActionText)
 - Ruby 2.7+
 
 ## Installation
@@ -48,7 +48,13 @@ Then call your helpers as usual:
   <%= f.email_field :email %>       <%# renders a ViewComponent::Form::EmailFieldComponent %>
 
   <%= f.label :password %>          <%# renders a ViewComponent::Form::LabelComponent %>
-  <%= f.password_field :password %> <%# renders a ViewComponent::Form::PasswordFieldComponent %>
+  <%= f.password_field :password, aria: { describedby: f.field_id(:password, :description) } %>
+                                    <%# renders a ViewComponent::Form::PasswordFieldComponent %>
+  <div id="<%= f.field_id(:title, :description) %>">
+    <%= f.hint :password, 'The password should be at least 8 characters long' %>
+                                      <%# renders a ViewComponent::Form::HintComponent %>
+    <%= f.error_message :password %>  <%# renders a ViewComponent::Form::ErrorMessageComponent %>
+  </div>
 <% end %>
 ```
 
@@ -69,7 +75,10 @@ It should work out of the box, but does nothing particularly interesting for now
   <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" />
+  <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>
 ```
 
@@ -156,6 +165,151 @@ You can use the same approach to inject options, wrap the input in a `<div>`, et
 
 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:
+
+#### `#label_text`
+
+Returns the translated text for the label of the field (looking up for `helpers.label.OBJECT.METHOD_NAME`), or humanized version of the method name if not available.
+
+```rb
+# app/components/custom/form/group_component.rb
+class Custom::Form::GroupComponent < ViewComponent::Form::FieldComponent
+end
+```
+
+```erb
+<%# app/components/custom/form/group_component.html.erb %>
+<div class="custom-form-group">
+  <label>
+    <%= label_text %><br />
+    <%= content %>
+  </label>
+</div>
+```
+
+```erb
+<%# app/views/users/_form.html.erb %>
+<%= form_for @user do |f| %>
+  <%= f.group :first_name do %>
+    <%= f.text_field :first_name %>
+  <% end %>
+<% end %>
+```
+
+```yml
+# config/locales/en.yml
+en:
+  helpers:
+    label:
+      user:
+        first_name: Your first name
+```
+
+Renders:
+
+```html
+<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" />
+  </label>
+</form>
+```
+
+#### Validations
+
+Let's consider the following model for the examples below.
+
+```rb
+# app/models/user.rb
+class User < ActiveRecord::Base
+  validates :first_name, presence: true, length: { minimum: 2, maximum: 255 }
+end
+```
+
+##### Accessing validations with `#validators`
+
+Returns all validators for the method name.
+
+```rb
+# app/components/custom/form/group_component.rb
+class Custom::Form::GroupComponent < ViewComponent::Form::FieldComponent
+  private
+
+  def validation_hint
+    if length_validator
+      "between #{length_validator.options[:minimum]} and #{length_validator.options[:maximum]} chars"
+    end
+  end
+
+  def length_validator
+    validators.find { |v| v.is_a?(ActiveModel::Validations::LengthValidator) }
+  end
+end
+```
+
+```erb
+<%# app/components/custom/form/group_component.html.erb %>
+<div class="custom-form-group">
+  <label>
+    <%= label_text %> (<%= validation_hint %>)<br />
+    <%= content %>
+  </label>
+</div>
+```
+
+##### Using `#required?` and `#optional?`
+
+```erb
+<%# app/components/custom/form/group_component.html.erb %>
+<div class="custom-form-group">
+  <label>
+    <%= label_text %><%= " (required)" if required? %><br />
+    <%= content %>
+  </label>
+</div>
+```
+
+##### Validation contexts
+
+When using [validation contexts](https://guides.rubyonrails.org/active_record_validations.html#on), you can specify a context to the helpers above.
+
+```rb
+# app/models/user.rb
+class User < ActiveRecord::Base
+  validates :first_name, presence: true, length: { minimum: 2, maximum: 255 }
+  validates :email, presence: true, on: :registration
+end
+```
+
+```erb
+<%# app/views/users/_form_.html.erb %>
+<%= form_with model: @user,
+              builder: ViewComponent::Form::Builder,
+              validation_context: :registration do |f| %>
+  <%= f.group :email do %>
+    <%= f.email_field :email %>
+  <% end %>
+<% end %>
+```
+
+In this case, `ViewComponent::Form::Builder` accepts a `validation_context` option and passes it as a default value to the `#validators`, `#required?` and `#optional?` helpers.
+
+Alternatively, you can pass the context to the helpers:
+
+```erb
+<%= "(required)" if required?(context: :registration) %>
+```
+
+```rb
+def length_validator
+  validators(context: :registration).find { |v| v.is_a?(ActiveModel::Validations::LengthValidator) }
+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.
@@ -167,6 +321,65 @@ You'll most likely want to use either:
 
 [`fields_for`](https://api.rubyonrails.org/v6.1.4/classes/ActionView/Helpers/FormHelper.html#method-i-fields_for) may also be of interest. To make consistent use of `view_component-form`, you'll want to be using these three helpers to build your forms wherever possible.
 
+## Supported helpers
+
+The following helpers are currently supported by `ViewComponent::Form`.
+
+### `ActionView::Helpers::FormBuilder`
+
+**Supported:** `button` `check_box` `collection_check_boxes` `collection_radio_buttons` `collection_select` `color_field` `date_field` `date_select` `datetime_field` `datetime_local_field` `datetime_select` `email_field` `fields` `fields_for` `file_field` `field_id` `grouped_collection_select` `hidden_field` `month_field` `number_field` `password_field` `phone_field` `radio_button` `range_field` `search_field` `select` `submit` `telephone_field` `text_area` `text_field` `time_field` `time_select` `time_zone_select` `to_model` `to_partial_path` `url_field` `week_field` `weekday_select`
+
+**Partially supported:** `label` (blocks not supported) `rich_text_area` (untested)
+
+**Unsupported for now:** `field_name`
+
+### Specific to `ViewComponent::Form`
+
+**Supported:** `error_message` `hint`
+
+## Testing your components
+
+### RSpec
+
+#### Configuration
+
+This assumes your already have read and configured [tests for `view_component`](https://viewcomponent.org/guide/testing.html#rspec-configuration).
+
+```rb
+# spec/rails_helper.rb
+require "view_component/test_helpers"
+require "view_component/form/test_helpers"
+require "capybara/rspec"
+
+RSpec.configure do |config|
+  config.include ViewComponent::TestHelpers, type: :component
+  config.include ViewComponent::Form::TestHelpers, type: :component
+  config.include Capybara::RSpecMatchers, type: :component
+end
+```
+
+#### Example
+
+```rb
+# spec/components/form/text_field_component_spec.rb
+RSpec.describe Form::TextFieldComponent, type: :component do
+  let(:object)  { User.new } # replace with a model of your choice
+  let(:form)    { form_with(object) }
+  let(:options) { {} }
+
+  let(:component) { render_inline(described_class.new(form, object_name, :first_name, options)) }
+
+  context "with simple args" do
+    it do
+      expect(component.to_html)
+        .to have_tag("input", with: { name: "user[first_name]", id: "user_first_name", type: "text" })
+    end
+  end
+end
+```
+
+For more complex components, we recommend the [`rspec-html-matchers` gem](https://github.com/kucaahbe/rspec-html-matchers).
+
 ## Development
 
 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.

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

@@ -7,10 +7,7 @@ module ViewComponent
         attr_accessor :default_options
       end
 
-      if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new("6.1")
-        require "view_component/form/class_names_helper"
-        include ClassNamesHelper
-      end
+      include ClassNamesHelper if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new("6.1")
 
       attr_reader :form, :object_name, :options
 

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class ErrorMessageComponent < FieldComponent
+      class_attribute :tag, instance_reader: false, instance_writer: false, instance_accessor: false,
+                            instance_predicate: false
+
+      self.tag = :div
+
+      def call
+        tag.public_send(self.class.tag, messages, **options)
+      end
+
+      def render?
+        method_errors?
+      end
+
+      def messages
+        safe_join(method_errors, tag.br)
+      end
+    end
+  end
+end

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

@@ -8,6 +8,8 @@ module ViewComponent
 
       attr_reader :method_name
 
+      delegate :validation_context, to: :form
+
       def initialize(form, object_name, method_name, options = {})
         # See: https://github.com/rails/rails/blob/83217025a171593547d1268651b446d3533e2019/actionview/lib/action_view/helpers/tags/base.rb#L13
         @method_name = method_name.to_s.dup
@@ -60,6 +62,36 @@ module ViewComponent
         end
       end
 
+      # From https://github.com/rails/rails/blob/497ab719d04a2d505f4d6a76c9d359b3d7f8e502/actionview/lib/action_view/helpers/tags/label.rb#L18-L27
+      def label_text
+        content ||= ActionView::Helpers::Tags::Translator.new(object, object_name, method_name,
+                                                              scope: "helpers.label").translate
+        content ||= method_name.humanize
+        content
+      end
+
+      def optional?(context: validation_context)
+        return nil if object.nil?
+
+        !required?(context: context)
+      end
+
+      def required?(context: validation_context)
+        return nil if object.nil?
+
+        validators(context: context).any?(ActiveModel::Validations::PresenceValidator)
+      end
+
+      def validators(context: validation_context)
+        method_validators.select do |validator|
+          if context.nil?
+            validator.options[:on].blank?
+          else
+            Array(validator.options[:on]).include?(context&.to_sym)
+          end
+        end
+      end
+
       private
 
       def singular_association_method_name
@@ -69,6 +101,14 @@ module ViewComponent
       def collection_association_method_name
         @collection_association_method_name ||= method_name.to_s.sub(/_ids$/, "").pluralize.to_sym
       end
+
+      def method_validators
+        @method_validators ||= if object.nil?
+                                 []
+                               else
+                                 object.class.validators_on(method_name)
+                               end
+      end
     end
   end
 end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class HintComponent < FieldComponent
+      class_attribute :tag, instance_reader: false, instance_writer: false, instance_accessor: false,
+                            instance_predicate: false
+      attr_reader :attribute_content
+
+      self.tag = :div
+
+      def initialize(form, object_name, method_name, content_or_options = nil, options = nil)
+        options ||= {}
+
+        content_is_options = content_or_options.is_a?(Hash)
+        if content_is_options
+          options.merge! content_or_options
+          @attribute_content = nil
+        else
+          @attribute_content = content_or_options
+        end
+
+        super(form, object_name, method_name, options)
+      end
+
+      def call
+        content_or_options = content.presence || attribute_content.presence
+
+        tag.public_send(self.class.tag, content_or_options, **options)
+      end
+
+      def render?
+        content.present? || attribute_content.present?
+      end
+    end
+  end
+end

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

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-module ViewComponent
-  module Form
-    class RichTextAreaComponent < FieldComponent
-      self.tag_klass = ActionView::Helpers::Tags::ActionText
+if defined?(ActionView::Helpers::Tags::ActionText)
+  module ViewComponent
+    module Form
+      class RichTextAreaComponent < FieldComponent
+        self.tag_klass = ActionView::Helpers::Tags::ActionText
+      end
     end
   end
 end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class WeekdaySelectComponent < FieldComponent
+      attr_reader :html_options
+
+      def initialize(form, object_name, method_name, options = {}, html_options = {})
+        @html_options = html_options
+
+        super(form, object_name, method_name, options)
+
+        set_html_options!
+      end
+
+      def call # rubocop:disable Metrics/MethodLength
+        if Rails::VERSION::MAJOR >= 7 # rubocop:disable Style/GuardClause
+          ActionView::Helpers::Tags::WeekdaySelect.new(
+            object_name,
+            method_name,
+            @view_context,
+            options,
+            html_options
+          ).render
+        else
+          raise NotImplementedError, "#{self.class} is only available in Rails >= 7"
+        end
+      end
+
+      protected
+
+      def set_html_options!
+        @html_options[:class] = class_names(html_options[:class], html_class)
+        @html_options.delete(:class) if @html_options[:class].blank?
+      end
+    end
+  end
+end

data/lib/generators/vcf/builder/builder_generator.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "rails/generators"
-
 module Vcf
   module Generators
     class BuilderGenerator < Rails::Generators::NamedBase

data/lib/generators/vcf/builder/templates/builder.rb.erb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class <%= class_name %> < ViewComponent::Form::Builder
   # Set the namespace you want to use for your own components
   namespace "<%= components_namespace %>"

data/lib/view_component/form/builder.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "action_view"
-
 module ViewComponent
   module Form
     class Builder < ActionView::Helpers::FormBuilder
@@ -29,10 +27,14 @@ module ViewComponent
         end
       end
 
+      attr_reader :validation_context
+
       def initialize(*)
         @__component_klass_cache = {}
 
         super
+
+        @validation_context = options[:validation_context]
       end
 
       (field_helpers - %i[
@@ -189,6 +191,33 @@ module ViewComponent
         end
       end
 
+      def error_message(method, options = {})
+        render_component(:error_message, @object_name, method, objectify_options(options))
+      end
+
+      def hint(method, text = nil, options = {}, &block)
+        render_component(:hint, @object_name, method, text, objectify_options(options), &block)
+      end
+
+      # Backport field_id from Rails 7.0
+      if Rails::VERSION::MAJOR < 7
+        def field_id(method_name, *suffixes, namespace: @options[:namespace], index: @index)
+          object_name = object_name.model_name.singular if object_name.respond_to?(:model_name)
+
+          sanitized_object_name = object_name.to_s.gsub(/\]\[|[^-a-zA-Z0-9:.]/, "_").delete_suffix("_")
+
+          sanitized_method_name = method_name.to_s.delete_suffix("?")
+
+          [
+            namespace,
+            sanitized_object_name.presence,
+            (index unless sanitized_object_name.empty?),
+            sanitized_method_name,
+            *suffixes
+          ].tap(&:compact!).join("_")
+        end
+      end
+
       private
 
       def render_component(component_name, *args, &block)

data/lib/view_component/form/engine.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "rails/engine"
-
 module ViewComponent
   module Form
     # :nodoc:

data/lib/view_component/form/version.rb

@@ -2,6 +2,6 @@
 
 module ViewComponent
   module Form
-    VERSION = "0.1.3"
+    VERSION = "0.2.2"
   end
 end

data/lib/view_component/form.rb

@@ -1,5 +1,17 @@
 # frozen_string_literal: true
 
-require_relative "form/version"
+require "view_component"
+require "zeitwerk"
+
+module ViewComponent
+  module Form
+  end
+end
+
+loader = Zeitwerk::Loader.for_gem
+form = "#{__dir__}/form.rb"
+loader.ignore(form)
+loader.push_dir("#{__dir__}/form", namespace: ViewComponent::Form)
+loader.setup
+
 require_relative "form/engine"
-require_relative "form/builder"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component-form
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.2
 platform: ruby
 authors:
 - Pantographe
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-11 00:00:00.000000000 Z
+date: 2022-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview
@@ -70,6 +70,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
 description: Rails FormBuilder for ViewComponent
 email:
 - oss@pantographe.studio
@@ -92,9 +106,11 @@ files:
 - app/components/view_component/form/datetime_local_field_component.rb
 - app/components/view_component/form/datetime_select_component.rb
 - app/components/view_component/form/email_field_component.rb
+- app/components/view_component/form/error_message_component.rb
 - app/components/view_component/form/field_component.rb
 - app/components/view_component/form/file_field_component.rb
 - app/components/view_component/form/grouped_collection_select_component.rb
+- app/components/view_component/form/hint_component.rb
 - app/components/view_component/form/label_component.rb
 - app/components/view_component/form/month_field_component.rb
 - app/components/view_component/form/number_field_component.rb
@@ -113,6 +129,7 @@ files:
 - app/components/view_component/form/time_zone_select_component.rb
 - app/components/view_component/form/url_field_component.rb
 - app/components/view_component/form/week_field_component.rb
+- app/components/view_component/form/weekday_select_component.rb
 - lib/generators/vcf/builder/builder_generator.rb
 - lib/generators/vcf/builder/templates/builder.rb.erb
 - lib/view_component/form.rb