amber_component 0.0.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45f702b26ec801eb7f67fa45e14c4fac035ff31d9ad6602418b7faa15c8e6004
-  data.tar.gz: 404f922961c15d865144d8f284511f0b93718bc85f93a1fea1c1b013aa6d815f
+  metadata.gz: d81663eb6f3cd153cb0a277a0114f8cce4e2140f40685f23a688a60c8ce86226
+  data.tar.gz: 32abb3383e052466435f318e1f8c4010adfa5f3d7e93e588e7e2842ff7cd59e6
 SHA512:
-  metadata.gz: 17df8b345dade33fb27c5167b9ee7d17788b2092ecbff5aeb2f6fbeb12a6dd91813e7c2aa9c52b42aafea6e5965869630960b64c1d3da5be3365d4e3f8702148
-  data.tar.gz: ec46b84d953e9efcc4ae0a36e68f0a733bfd8e76f518eee3cae2c33a655df3be9ec592b09cd8ade8b88707934e55004d03c62c2a48a2152690edd86910b4cd2e
+  metadata.gz: 4a3df277a91914b6a148cc72c1b3981f78c420e773b408c8555a8915424d11667c804f113c2a1fd76bce751083607086ab660f1634855fcec686bc433b875c12
+  data.tar.gz: 330efd82e1589a4804f72f4dcb1df1f9a9b90696ce2dfb542c69b91dd1b0a5b7797736c9fa8ce461f73ff7bb16a3966a8ed00b8340c6d047d289acde976240cc

data/CONTRIBUTING.md

@@ -72,9 +72,9 @@ $ gem install ffi -- --with-cflags="-fdeclspec"
 
 > Gem::Ext::BuildError: ERROR: Failed to build gem native extension.
 >
->    current directory: /Users/mateuszdrewniak/.rvm/gems/ruby-3.1.0@dupa/gems/puma-5.6.2/ext/puma_http11
+>    current directory: ~/.rvm/gems/ruby-3.1.0@dupa/gems/puma-5.6.2/ext/puma_http11
 >
-> /Users/mateuszdrewniak/.rvm/rubies/ruby-3.1.0/bin/ruby -I /Users/mateuszdrewniak/.rvm/rubies/ruby-3.1.0/lib/ruby/3.1.0 -r ./siteconf20220219-40641-4uxhq6.rb extconf.rb --with-cflags\=-Wno-error\=implicit-function-declaration
+> ~/.rvm/rubies/ruby-3.1.0/bin/ruby -I ~/.rvm/rubies/ruby-3.1.0/lib/ruby/3.1.0 -r ./siteconf20220219-40641-4uxhq6.rb extconf.rb --with-cflags\=-Wno-error\=implicit-function-declaration
 >
 > checking for BIO_read() in -lcrypto... *** extconf.rb failed ***
 >

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    amber_component (0.0.4)
+    amber_component (1.0.0)
       actionview (>= 6)
       activemodel (>= 6)
       activesupport (>= 6)
@@ -67,10 +67,10 @@ GEM
     method_source (1.0.0)
     mini_portile2 (2.8.0)
     minitest (5.16.2)
-    nokogiri (1.13.8)
+    nokogiri (1.13.9)
       mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
-    nokogiri (1.13.8-arm64-darwin)
+    nokogiri (1.13.9-arm64-darwin)
       racc (~> 1.4)
     parallel (1.22.1)
     parser (3.1.2.1)
@@ -94,21 +94,21 @@ GEM
     rainbow (3.1.1)
     rake (13.0.6)
     rchardet (1.8.0)
-    regexp_parser (2.5.0)
+    regexp_parser (2.6.0)
     reverse_markdown (2.1.1)
       nokogiri
     rexml (3.2.5)
-    rubocop (1.36.0)
+    rubocop (1.38.0)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.1.2.1)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.20.1, < 2.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.21.0)
+    rubocop-ast (1.23.0)
       parser (>= 3.1.1.0)
     ruby-progressbar (1.11.0)
     ruby2_keywords (0.0.5)
@@ -124,7 +124,7 @@ GEM
       simplecov (~> 0.19)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
-    solargraph (0.46.0)
+    solargraph (0.47.2)
       backport (~> 1.2)
       benchmark
       bundler (>= 1.17.2)
@@ -172,4 +172,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.3.14
+   2.3.7

data/README.md

@@ -9,13 +9,13 @@
 
 # AmberComponent
 
-AmberComponent is a simple component library which seamlessly hooks into your Rails project and allows you to create simple backend components. They work like mini controllers which are bound with their view.
+AmberComponent is a simple component library which seamlessly hooks into your Rails project and allows you to create simple backend components. They work like mini controllers which are bound with their view and stylesheet.
 
 Created by [Garbus Beach](https://github.com/garbusbeach) and [Mateusz Drewniak](https://github.com/Verseth).
 
 ## Getting started
 
-You can read a lot more about AmberComponent in its [official docs](https://ambercomponent.com). 
+You can read a lot more about AmberComponent in its [official docs](https://ambercomponent.com).
 
 ## Installation
 
@@ -27,14 +27,434 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install amber_component
 
+If you're using a Rails application there's an installation generator that you should run:
+
+```sh
+$ bin/rails generate amber_component:install
+```
+
 ## Usage
 
-If you're using a Rails application there's an installation generator that you should run:
+## Components
+
+Components are located under `app/components`.
+
+Every component consists of:
+- a Ruby file which defines its properties, encapsulates logic and may implement helper methods (like a controller)
+- a view/template file (html.erb, haml, slim etc.)
+- a style file (css, scss, sass etc.)
+
+An individual component which implements a button may look like this.
+
+```ruby
+# app/components/button_component.rb
+
+class ButtonComponent < AmberComponent::Base
+  prop :label, required: true
+end
+```
+
+```html
+<!-- app/components/button_component/view.html.erb -->
+
+<div class="button_component">
+    <%= label %>
+</div>
+```
+
+```scss
+// app/components/button_component/style.scss
+
+.button_component {
+    background-color: indigo;
+    border-radius: 1rem;
+    transition-duration: 500ms;
+
+    &:hover {
+        background-color: blue;
+    }
+}
+```
+
+You can render this component in other components or in a Rails view.
+
+```html
+<!-- app/controller/foo/index.html.erb -->
+
+<h1>We're inside FooController</h1>
+
+<!-- using a helper method -->
+<%= button_component label: 'Click me!' %>
+<!-- calling a method on the component class -->
+<%= ButtonComponent.call label: 'Click me!' %>
+```
+
+Or even directly in Ruby
+
+```ruby
+# Calling a method on the component class. Outputs an HTML string.
+ButtonComponent.call label: 'Click me!'
+#=> '<div class="button_component">Click me!</div>'
+```
+
+### Rails helpers inside component templates
+
+Component views/template files can make use
+of all ActionView helpers and Rails route helpers.
+
+This makes component views very flexible and convenient.
+
+```erb
+<!-- app/components/login_form_component/view.html.erb -->
+
+<%= form_with url: sign_up_path, class: "login_form_component" do |f| %>
+  <%= f.label :first_name %>
+  <%= f.text_field :first_name %>
+
+  <%= f.label :last_name %>
+  <%= f.text_field :last_name %>
+
+  <%= f.label :email, "Email Address" %>
+  <%= f.text_field :email %>
+
+  <%= f.label :password %>
+  <%= f.password_field :password %>
+
+  <%= f.label :password_confirmation, "Confirm Password" %>
+  <%= f.password_field :password_confirmation %>
+
+  <%= f.submit "Create account" %>
+<% end %>
+```
+
+### Component properties
+
+There is a neat prop DSL.
+
+```ruby
+# app/components/comment_component.rb
+
+class CommentComponent < ApplicationComponent
+    # will raise an error when not present
+    prop :body, required: true
+    # will raise an error when an object of a different
+    # class is received (uses `is_a?`)
+    prop :author, type: User, allow_nil: true
+    # the default value
+    prop :date, default: -> { DateTime.now }
+end
+```
+
+Props can be passed as keyword arguments
+to the `::call` method of the component class
+or the helper method.
+
+```ruby
+CommentComponent.call body: 'Foo bar', author: User.first
+# only in views and other components
+comment_component body: 'Foo bar', author: User.first
+```
+
+### Overriding prop getters and setters
+
+Getters and setters for properties are
+defined in a module which means that you can override them and call them with `super`.
+
+```ruby
+# app/components/priority_icon_component.rb
+
+class PriorityIconComponent < ApplicationComponent
+    PriorityStruct = Struct.new :icon, :color
+
+    PRIORITY_MAP = {
+        low: PriorityStruct.new('fa-solid fa-chevrons-down', 'green'),
+        medium: PriorityStruct.new('fa-solid fa-chevron-up', 'yellow'),
+        high: PriorityStruct.new('fa-solid fa-chevrons-up', 'red')
+    }
+
+    prop :severity, default: -> { :low }
+
+    def severity=(val)
+      # super will call the original
+      # implementation of the setter
+      super(PRIORITY_MAP[val])
+    end
+end
+```
+
+```html
+<!-- app/components/priority_icon_component/view.html.erb -->
+
+<i style="color: <%= severity&.color %>;" class="<%= severity&.icon %>"></i>
+```
+
+### Helper methods
+
+Defining helper methods which are available
+in the template is extremely easy.
+
+Just define a method on the component class.
+
+```ruby
+# app/components/comment_component.rb
+
+class CommentComponent < ApplicationComponent
+    # you can also include helper modules
+    include SomeHelper
+
+    prop :body, required: true
+    prop :author, type: Author, allow_nil: true
+    prop :date, default: -> { DateTime.now }
+
+    private
+
+    def humanized_date
+        date.strftime '%Y-%m-%d %H:%M'
+    end
+
+    def author_name
+        author&.name || 'Unknown'
+    end
+
+    def author_avatar
+        author&.avatar_url || User.placeholder_avatar_url
+    end
+end
+```
+
+```html
+<!-- app/components/comment_component/view.html.erb -->
+
+<div class="comment_component">
+    <div class="comment_header">
+        <img src="<%= author_avatar %>" alt="<%= author_name %> avatar">
+
+        <div><%= author_name %></div>
+        <div class="comment_date"><%= humanized_date %></div>
+    </div>
+
+    <div class="comment_content">
+        <%= body %>
+    </div>
+</div>
+```
+
+### Nested components
+
+It's possible to nest components or provide
+custom HTML to a component.
+
+This works similarly to React's `props.children`.
+
+To render the passed nested content call `yield.html_safe` somewhere inside the template/view.
+
+```ruby
+# app/components/modal_component.rb
+
+class ModalComponent < ApplicationComponent
+    prop :id, required: true
+    prop :title, required: true
+end
+```
+
+```html
+<!-- app/components/modal/view.html.erb -->
+
+<div id="<%= id %>" class="modal_component">
+    <div class="model_header">
+        <%= title %>
+    </div>
+
+    <div class="modal_body">
+        <!-- nested content will be rendered here -->
+        <%= yield.html_safe %>
+    </div>
+
+    <div class="modal_footer">
+        <div class="modal_close_button"></div>
+    </div>
+<div>
+```
+
+You can pass a body to this modal by passing
+a block.
+
+```erb
+<!-- app/controller/tasks/show.html.erb -->
+
+<%= ModalComponent.call id: 'update-task-modal' title: 'Update the task' do %>
+    <!-- You can provide HTML and render other components -->
+    <h2>This is your task!</h2>
+    <%= form_with model: @task do |f| %>
+        <%= f.text_field :name %>
+        <%= f.text_area :description %>
+        <%= f.submit %>
+    <% end %>
+    <%= OtherComponent.call some: 'prop' %>
+<% end %>
+```
+
+Note that this will raise an error when no block/nested content is provided.
+
+In order to render nested content
+only when it is present (will work without nested content)
+you can use `yield.html_safe if block_given?`
+
+In general `block_given?` will return `true` when a block/nested content is present, otherwise `false`.
+You can use it to render content conditionally based on
+whether nested content is present.
+
+### Components with namespaces
+
+Components may be defined inside multiple modules/namespaces.
+
+```ruby
+# app/components/sign_up/button_component.rb
+
+class SignUp::ButtonComponent < AmberComponent::Base
+  prop :label, required: true
+end
+```
+
+```html
+<!-- app/components/sign_up/button_component/view.html.erb -->
+
+<div class="sign_up_button_component">
+    <%= label %>
+</div>
+```
+
+```scss
+// app/components/sign_up/button_component/style.scss
+
+.sign_up_button_component {
+    background-color: indigo;
+    border-radius: 1rem;
+    transition-duration: 500ms;
+
+    &:hover {
+        background-color: blue;
+    }
+}
+```
+
+You can render such a component by calling the `::call` method
+on its class, or by using the helper method defined on its parent module.
+
+```ruby
+SignUp::ButtonComponent.call label: 'Sign up!'
+SignUp.button_component label: 'Sign up!'
+```
+
+### Generating Components
+
+You an generate new components by running
 
 ```sh
-$ rails generate amber_component:install
+$ bin/rails generate component foo_bar
 ```
 
+or
+
+```sh
+$ bin/rails generate component FooBar
+```
+
+This will generate a new component in `app/components/foo_bar_component.rb` along with a view, stylesheet and test file.
+
+### Testing Components
+
+### Rails
+
+After setting up this gem with the rails generator
+`rails generate amber_component:install` a new abstract
+test class will be available called `ApplicationComponentTestCase`.
+
+It provides a handful of helper methods to make it
+easier to inspect the rendered HTML.
+
+A simple test file may look like this:
+
+```ruby
+# test/components/foo_component_test.rb
+
+require 'test_helper'
+
+class FooComponentTest < ApplicationComponentTestCase
+    test 'render correct HTML' do
+        # Specify what the assertions are supposed to
+        # check against.
+        #
+        # There can be multiple renders in one test
+        # but they override the previous one.
+        # So there is only one rendered component
+        # at any given time.
+        render do
+            FooComponent.call some: 'prop'
+        end
+
+        # Assertions on the rendered HTML
+
+        # Use a CSS selector
+        assert_selector ".foo_component span.my_class", text: 'Some Text'
+        # Check text
+        assert_text 'Amber Component is awesome!'
+    end
+end
+```
+
+A full list of available assertions can be found [here](https://rubydoc.info/github/jnicklas/capybara/Capybara/Node/Matchers).
+
+### Non Rails
+
+There is a test case class for minitest. You can
+access it by requiring `'amber_component/minitest_test_case'`.
+
+It has the same assertion methods as the Rails test case class.
+It requires [capybara](https://github.com/teamcapybara/capybara) to be installed and present in the Gemfile.
+
+A full list of available assertions can be found [here](https://rubydoc.info/github/jnicklas/capybara/Capybara/Node/Matchers).
+
+```ruby
+require 'amber_component/minitest_test_case'
+
+class FooComponentTest < AmberComponent::MinitestTestCase
+    def test_render_correct_html
+        # Specify what the assertions are supposed to
+        # check against.
+        #
+        # There can be multiple renders in one test
+        # but they override the previous one.
+        # So there is only one rendered component
+        # at any given time.
+        render do
+            FooComponent.call some: 'prop'
+        end
+
+        # Assertions on the rendered HTML
+
+        # Use a CSS selector
+        assert_selector ".foo_component span.my_class", text: 'Some Text'
+        # Check text
+        assert_text 'Amber Component is awesome!'
+    end
+end
+```
+
+There is also a helper module which provides all of these assertions
+under `'amber_component/test_helper'`.
+
+```ruby
+require 'amber_component/test_helper'
+
+class MyAbstractTestCase < ::Minitest::Test
+    include ::AmberComponent::TestHelper
+end
+```
+
+Note that this module has only been tested with minitest and rails test suites,
+so it may require overriding or implementing a few methods to work with other test suites.
+
 ## Contribute
 
 Do you want to contribute to AmberComponent? Open the issues page and check for the help wanted label! But before you start coding, please read our [Contributing Guide](https://github.com/amber-ruby/amber_component/blob/main/CONTRIBUTING.md).

data/lib/amber_component/minitest_test_case.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+module AmberComponent
+  # A base class for component tests with Minitest
+  class MinitestTestCase < ::Minitest::Test
+    include TestHelper
+  end
+end

data/lib/amber_component/props.rb

@@ -75,7 +75,7 @@ module ::AmberComponent
     module InstanceMethods
       private
 
-      # @param props [Hash{Symbol => Object}]
+      # @param kwargs [Hash{Symbol => Object}]
       def initialize(**kwargs)
         bind_props(kwargs)
       end

data/lib/amber_component/test_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AmberComponent
+  # Provides assertions for the rendered
+  # HTML of components.
+  module TestHelper
+    begin
+      require 'capybara/minitest'
+      include ::Capybara::Minitest::Assertions
+
+      def page
+        @page ||= ::Capybara::Node::Simple.new(@rendered_content)
+      end
+    rescue ::LoadError
+      nil
+    end
+
+    # @return [Nokogiri::HTML]
+    def document
+      ::Nokogiri::HTML.fragment(@rendered_content)
+    end
+    alias doc document
+    alias html document
+
+    # @param content [String]
+    # @return [Nokogiri::HTML]
+    def render(content = nil)
+      @page = nil
+      @rendered_content = content || yield
+      document
+    end
+    alias render_inline render
+  end
+end

data/lib/amber_component/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ::AmberComponent
-  VERSION = '0.0.4'
+  VERSION = '1.0.0'
 end

data/lib/generators/amber_component/install_generator.rb

@@ -13,11 +13,30 @@ module ::AmberComponent
       # copy rake tasks
       def copy_tasks
         copy_file 'application_component.rb', 'app/components/application_component.rb'
+        copy_file 'application_component_test_case.rb', 'test/application_component_test_case.rb'
+        append_file 'test/test_helper.rb', "require_relative 'application_component_test_case'"
 
-        inject_into_file 'app/assets/stylesheets/application.css', after: "*= require_tree .\n" do
+        require_components_css_in 'app/assets/stylesheets/application.css'
+        require_components_css_in 'app/assets/stylesheets/application.scss'
+        require_components_css_in 'app/assets/stylesheets/application.sass'
+        require_components_css_in 'app/assets/stylesheets/application.css.scss'
+        require_components_css_in 'app/assets/stylesheets/application.css.sass'
+        require_components_css_in 'app/assets/stylesheets/application.scss.sass'
+        require_components_css_in 'app/assets/stylesheets/application.sass.scss'
+      end
+
+      private
+
+      # @param file_name [String]
+      # @return [void]
+      def require_components_css_in(file_name)
+        return unless ::File.exist? file_name
+
+        inject_into_file file_name, after: "*= require_tree .\n" do
           " *= require_tree ./../../components\n"
         end
       end
+
     end
   end
 end

data/lib/generators/amber_component/templates/application_component_test_case.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'amber_component/test_helper'
+
+class ApplicationComponentTestCase < ::ActiveSupport::TestCase
+  include ::AmberComponent::TestHelper
+end