view_component-form 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b8b8e714bdbf45731abe0cf2081fc829c0564cd50097040e45e46beb368f2190
+  data.tar.gz: 184b04a2a168ecf53dcb7ff3385ef4b1889b42afe32f409236efaf708a96387c
+SHA512:
+  metadata.gz: 83ffb7cea594f39a75418673f041d7c4f3ce006db5d306615b2e40575c57bab98c5619c9cc1dd71c122280fe963f88281f0b3c589be8b20a703f0aae4859a0ae
+  data.tar.gz: 19bbe58b645bb23ed625bdc3c240cdfa17d51e8481386b33e96c1d8583ef88dc622a92ade574cd551d1a97502674dffd969d7ae8bf877c82cd6c9f71d12124b4

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `FormBuilder`: add `.namespace` method to allow local lookup of components (#54)
+- Add basic `ViewComponent::Form::Builder` that can be used in place of Rails' `ActionView::Helpers::FormBuilder` (#1)
+- Add all standard FormBuilder helpers provided by Rails, implemented as ViewComponents (#4)
+- Add a custom FormBuilder generator (#34)
+- Add CHANGELOG (#50)
+- Add CI (#2)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Pantographe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+# 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`.**
+
+## Compatibility
+
+This gem is tested on:
+- Rails 6.0+
+- Ruby 2.7+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'view_component-form'
+```
+
+And then execute:
+
+    $ bundle install
+
+## Usage
+
+Add a `builder` param to your `form_for` of `form_with`:
+
+```diff
+- <%= form_for @user do |f| %>
++ <%= form_for @user, builder: ViewComponent::Form::Builder 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).
+
+Then call your helpers as usual:
+
+```erb
+<%# app/views/users/_form.html.erb %>
+<%= form_for @user, builder: ViewComponent::Form::Builder do |f| %>
+  <%= f.label :first_name %>        <%# renders a ViewComponent::Form::LabelComponent %>
+  <%= f.text_field :first_name %>   <%# renders a ViewComponent::Form::TextFieldComponent %>
+
+  <%= f.label :last_name %>         <%# renders a ViewComponent::Form::LabelComponent %>
+  <%= f.text_field :last_name %>    <%# renders a ViewComponent::Form::TextFieldComponent %>
+
+  <%= f.label :email %>             <%# renders a ViewComponent::Form::LabelComponent %>
+  <%= 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 %>
+<% 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" />
+</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  lib/custom_form_builder.rb
+```
+
+This allows you to pick the namespace your components will be loaded from.
+
+```rb
+# lib/custom_form_builder.rb
+class CustomFormBuilder < ViewComponent::Form::Builder
+  # Set the namespace you want to use for your own components
+  namespace Form
+end
+```
+
+You can change the default namespace and path:
+
+```console
+bin/rails generate vcf:builder AnotherCustomFormBuilder --namespace Forms::Components --path app/forms
+
+      create  app/forms/another_custom_form_builder.rb
+```
+
+```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 Forms::Components
+end
+```
+
+:warning: **Everything below this line describes the future usage and is subject to change. It does not work yet as the gem is still under heavy development.**
+
+Now let's generate your own components to customize the rendering.
+
+```console
+bin/rails generate vcf:component Form::TextField
+
+      invoke  test_unit
+      create  test/components/form/text_field_component_test.rb
+      create  app/components/form/text_field_component.rb
+      create  app/components/form/text_field_component.html.erb
+```
+
+Change your forms to use your new builder:
+
+```diff
+- <%= form_for @user, builder: ViewComponent::Form::Builder do |f| %>
++ <%= form_for @user, builder: CustomFormBuilder do |f| %>
+```
+
+You can then customize the behavior of your `Form::TextFieldComponent`:
+
+```rb
+# app/components/form/text_field_component.rb
+
+module Form
+  class TextFieldComponent < ViewComponent::Form::TextFieldComponent
+    def html_class
+      class_names("text-field", "border-error": method_errors?)
+    end
+  end
+end
+```
+
+The generated form field with now have your class names:
+
+```html
+<input class="text-field" type="text" value="John" name="user[first_name]" id="user_first_name">
+```
+
+## 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.
+
+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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pantographe/view_component-form. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/pantographe/view_component-form/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ViewComponent::Form project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/pantographe/view_component-form/blob/master/CODE_OF_CONDUCT.md).

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class BaseComponent < ViewComponent::Base
+      class << self
+        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
+
+      attr_reader :form, :object_name, :options
+
+      delegate :object, to: :form
+      delegate :errors, to: :object, prefix: true
+
+      def initialize(form, object_name, options = {})
+        @form = form
+
+        # See: https://github.com/rails/rails/blob/83217025a171593547d1268651b446d3533e2019/actionview/lib/action_view/helpers/tags/base.rb#L13
+        @object_name = object_name.to_s.dup
+        @options     = options
+
+        super()
+      end
+
+      def object_errors?
+        object.errors.any?
+      end
+
+      def html_class
+        nil
+      end
+
+      protected
+
+      def before_render
+        super
+
+        combine_options!
+      end
+
+      def combine_options!
+        @options = (self.class.default_options.deep_dup || {}).deep_merge(options).tap do |opts|
+          opts[:class] = class_names(options[:class], html_class) if (html_class || options[:class]).present?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class ButtonComponent < BaseComponent
+      attr_reader :value
+
+      def initialize(form, value, options = {})
+        @value = value
+
+        super(form, nil, options)
+      end
+
+      def call
+        button_tag(content || value, options)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class CheckBoxComponent < FieldComponent
+      attr_reader :checked_value, :unchecked_value
+
+      def initialize(form, object_name, method_name, checked_value, unchecked_value, options = {}) # rubocop:disable Metrics/ParameterLists
+        @checked_value   = checked_value
+        @unchecked_value = unchecked_value
+
+        super(form, object_name, method_name, options)
+      end
+
+      def call
+        ActionView::Helpers::Tags::CheckBox.new(
+          object_name,
+          method_name,
+          @view_context,
+          checked_value,
+          unchecked_value,
+          options
+        ).render
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class CollectionCheckBoxesComponent < FieldComponent
+      attr_reader :collection, :value_method, :text_method, :html_options
+
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        form,
+        object_name,
+        method_name,
+        collection,
+        value_method,
+        text_method,
+        options = {},
+        html_options = {}
+      )
+        @collection = collection
+        @value_method = value_method
+        @text_method = text_method
+        @html_options = html_options
+
+        super(form, object_name, method_name, options)
+
+        set_html_options!
+      end
+
+      def call # rubocop:disable Metrics/MethodLength
+        ActionView::Helpers::Tags::CollectionCheckBoxes.new(
+          object_name,
+          method_name,
+          @view_context,
+          collection,
+          value_method,
+          text_method,
+          options,
+          html_options,
+          &content
+        ).render
+      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/app/components/view_component/form/collection_radio_buttons_component.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class CollectionRadioButtonsComponent < FieldComponent
+      attr_reader :collection, :value_method, :text_method, :html_options
+
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        form,
+        object_name,
+        method_name,
+        collection,
+        value_method,
+        text_method,
+        options = {},
+        html_options = {}
+      )
+        @collection = collection
+        @value_method = value_method
+        @text_method = text_method
+        @html_options = html_options
+
+        super(form, object_name, method_name, options)
+
+        set_html_options!
+      end
+
+      def call # rubocop:disable Metrics/MethodLength
+        ActionView::Helpers::Tags::CollectionRadioButtons.new(
+          object_name,
+          method_name,
+          @view_context,
+          collection,
+          value_method,
+          text_method,
+          options,
+          html_options,
+          &content
+        ).render
+      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/app/components/view_component/form/collection_select_component.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Form
+    class CollectionSelectComponent < FieldComponent
+      attr_reader :collection, :value_method, :text_method, :html_options
+
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        form,
+        object_name,
+        method_name,
+        collection,
+        value_method,
+        text_method,
+        options = {},
+        html_options = {}
+      )
+        @collection = collection
+        @value_method = value_method
+        @text_method = text_method
+        @html_options = html_options
+
+        super(form, object_name, method_name, options)
+
+        set_html_options!
+      end
+
+      def call
+        ActionView::Helpers::Tags::CollectionSelect.new(
+          object_name,
+          method_name,
+          @view_context,
+          collection,
+          value_method,
+          text_method,
+          options,
+          html_options
+        ).render
+      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