view_component 2.8.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ac6dfbc2cb2fb7bbad0aac55de41cfbdc782dac0eb14f1e4b18784e15db02a9
-  data.tar.gz: 294bd6faac8d95b0db842ab67139e141117058148c24d503647960e31c19ef21
+  metadata.gz: 8661a26312dc3649e30ee17fbc94f6fd73be410067f8a7fac8b6aaefc4338d11
+  data.tar.gz: 1024034624c49bb65bfe1fc3466886ffa60cd9699a58c7427ea6dbedb9baa03b
 SHA512:
-  metadata.gz: 4d2da7f6d4ff599ea9b92408dc632eecb7629d7bf7cda9484eab20b0f02dd1a78ba3669fc5f9107f2b6388d2f5634258a14b806d58327c716a8339b819ef8aa7
-  data.tar.gz: 50b86ff9e697608ae063352c8a55430763b5762016c3512dfa103f5df7a2fbb4875a993e319783f2e1e077c4ca157152a4314d3a106b0fc0a84186926044f917
+  metadata.gz: 24ddc5373c2fbb7cd81ef4f4077ea66a30ea797fbb9d4c444135d3d8590b5151596fddc18f5bc5e1f18fec65ca87572858513409385489524c11c1929cff3567
+  data.tar.gz: cf63eb464e88e02310cb55f9c6c779c31622174777dbd1f39a24d0e9ac40407c555ac51012c5ea8c06bdeccac7aab880475c02c678c3fbff9ef22f5ca6cf797e

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # master
 
+# 2.12.0
+
+* Implement Slots as potential successor to Content Areas.
+
+    *Jens Ljungblad, Brian Bugh, Jon Palmer, Joel Hawksley*
+
+# 2.11.1
+
+* Fix kwarg warnings in Ruby 2.7.
+
+    *Joel Hawksley*
+
+# 2.11.0
+
+* Ensure Rails configuration is available within components.
+
+    *Trevor Broaddus*
+
+* Fix bug where global Rails helpers are inaccessible from nested components. Before, `helpers` was pointing to parent component.
+
+    *Franco Sebregondi*
+
+# 2.10.0
+
+* Raise an `ArgumentError` with a helpful message when Ruby cannot parse a component class.
+
+    *Max Beizer*
+
+# 2.9.0
+
+* Cache components per-request in development, preventing unnecessary recompilation during a single request.
+
+    *Felipe Sateler*
+
 # 2.8.0
 
 * Add `before_render`, deprecating `before_render_check`.

data/README.md

@@ -160,6 +160,133 @@ Returning:
 </div>
 ```
 
+#### Slots (experimental)
+
+_Slots are currently under development as a successor to Content Areas. The Slot APIs should be considered unfinished and subject to breaking changes in non-major releases of ViewComponent._
+
+Slots enable multiple blocks of content to be passed to a single ViewComponent.
+
+Slots exist in two forms: normal slots and collection slots.
+
+Normal slots can be rendered once per component. They expose an accessor with the name of the slot that returns an instance of `ViewComponent::Slot`, etc.
+
+Collection slots can be rendered multiple times. They expose an accessor with the pluralized name of the slot (`#rows`), which is an Array of `ViewComponent::Slot` instances.
+
+To learn more about the design of the Slots API, see https://github.com/github/view_component/pull/348.
+
+##### Defining Slots
+
+Slots are defined by the `with_slot` macro:
+
+`with_slot :header`
+
+To define a collection slot, add `collection: true`:
+
+`with_slot :row, collection: true`
+
+To define a slot with a custom class, pass `class_name`:
+
+`with_slot :body, class_name: 'BodySlot`
+
+Slot classes should be subclasses of `ViewComponent::Slot`.
+
+##### Example ViewComponent with Slots
+
+`# box_component.rb`
+```ruby
+class BoxComponent < ViewComponent::Base
+  include ViewComponent::Slotable
+
+  with_slot :body, :footer
+  with_slot :header, class_name: "Header"
+  with_slot :row, collection: true, class_name: "Row"
+
+  class Header < ViewComponent::Slot
+    def initialize(class_names: "")
+      @class_names = class_names
+    end
+
+    def class_names
+      "Box-header #{@class_names}"
+    end
+  end
+
+  class Row < ViewComponent::Slot
+    def initialize(theme: :gray)
+      @theme = theme
+    end
+
+    def theme_class_name
+      case @theme
+      when :gray
+        "Box-row--gray"
+      when :hover_gray
+        "Box-row--hover-gray"
+      when :yellow
+        "Box-row--yellow"
+      when :blue
+        "Box-row--blue"
+      when :hover_blue
+        "Box-row--hover-blue"
+      else
+        "Box-row--gray"
+      end
+    end
+  end
+end
+```
+
+`# box_component.html.erb`
+```erb
+<div class="Box">
+  <% if header %>
+    <div class="<%= header.class_names %>">
+      <%= header.content %>
+    </div>
+  <% end %>
+  <% if body %>
+    <div class="Box-body">
+      <%= body.content %>
+    </div>
+  <% end %>
+  <% if rows.any? %>
+    <ul>
+      <% rows.each do |row| %>
+        <li class="Box-row <%= row.theme_class_name %>">
+          <%= row.content %>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+  <% if footer %>
+    <div class="Box-footer">
+      <%= footer %>
+    </div>
+  <% end %>
+</div>
+```
+
+`# index.html.erb`
+```erb
+<%= render(BoxComponent.new) do |component| %>
+  <% component.slot(:header, class_names: "my-class-name") do %>
+    This is my header!
+  <% end %>
+  <% component.slot(:body) do %>
+    This is the body.
+  <% end %>
+  <% component.slot(:row) do %>
+    Row one
+  <% end %>
+  <% component.slot(:row, theme: :yellow) do %>
+    Yellow row
+  <% end %>
+  <% component.slot(:footer) do %>
+    This is the footer.
+  <% end %>
+<% end %>
+```
+
 ### Inline Component
 
 ViewComponents can render without a template file, by defining a `call` method:
@@ -731,6 +858,8 @@ ViewComponent is far from a novel idea! Popular implementations of view componen
 ## Resources
 
 - [Encapsulating Views, RailsConf 2020](https://youtu.be/YVYRus_2KZM)
+- [Rethinking the View Layer with Components, Ruby Rogues Podcast](https://devchat.tv/ruby-rogues/rr-461-rethinking-the-view-layer-with-components-with-joel-hawksley/)
+- [ViewComponents in Action with Andrew Mason, Ruby on Rails Podcast](https://5by5.tv/rubyonrails/320)
 - [ViewComponent at GitHub with Joel Hawksley](https://the-ruby-blend.fireside.fm/9)
 - [Components, HAML vs ERB, and Design Systems](https://the-ruby-blend.fireside.fm/4)
 - [Choosing the Right Tech Stack with Dave Paola](https://5by5.tv/rubyonrails/307)
@@ -778,10 +907,15 @@ ViewComponent is built by:
 |@blakewilliams|@seanpdoyle|@tclem|@nashby|@jaredcwhite|
 |Boston, MA|New York, NY|San Francisco, CA|Minsk|Portland, OR|
 
-|<img src="https://avatars.githubusercontent.com/simonrand?s=256" alt="simonrand" width="128" />|<img src="https://avatars.githubusercontent.com/fugufish?s=256" alt="fugufish" width="128" />|<img src="https://avatars.githubusercontent.com/cover?s=256" alt="cover" width="128" />|<img src="https://avatars.githubusercontent.com/franks921?s=256" alt="franks921" width="128" />|
-|:---:|:---:|:---:|:---:|
-|@simonrand|@fugufish|@cover|@franks921|
-|Dublin, Ireland|Salt Lake City, Utah|Barcelona|South Africa|
+|<img src="https://avatars.githubusercontent.com/simonrand?s=256" alt="simonrand" width="128" />|<img src="https://avatars.githubusercontent.com/fugufish?s=256" alt="fugufish" width="128" />|<img src="https://avatars.githubusercontent.com/cover?s=256" alt="cover" width="128" />|<img src="https://avatars.githubusercontent.com/franks921?s=256" alt="franks921" width="128" />|<img src="https://avatars.githubusercontent.com/fsateler?s=256" alt="fsateler" width="128" />|
+|:---:|:---:|:---:|:---:|:---:|
+|@simonrand|@fugufish|@cover|@franks921|@fsateler|
+|Dublin, Ireland|Salt Lake City, Utah|Barcelona|South Africa|Chile|
+
+|<img src="https://avatars.githubusercontent.com/maxbeizer?s=256" alt="maxbeizer" width="128" />|<img src="https://avatars.githubusercontent.com/franco?s=256" alt="franco" width="128" />|<img src="https://avatars.githubusercontent.com/tbroad-ramsey?s=256" alt="tbroad-ramsey" width="128" />|<img src="https://avatars.githubusercontent.com/jensljungblad?s=256" alt="jensljungblad" width="128" />|<img src="https://avatars.githubusercontent.com/bbugh?s=256" alt="bbugh" width="128" />|
+|:---:|:---:|:---:|:---:|:---:|
+|@maxbeizer|@franco|@tbroad-ramsey|@jensljungblad|@bbugh|
+|Nashville, TN|Switzerland|Spring Hill, TN|New York, NY|Austin, TX|
 
 ## License
 

data/lib/view_component/base.rb

@@ -3,7 +3,9 @@
 require "action_view"
 require "active_support/configurable"
 require "view_component/collection"
+require "view_component/compile_cache"
 require "view_component/previewable"
+require "view_component/slotable"
 
 module ViewComponent
   class Base < ActionView::Base
@@ -11,11 +13,15 @@ module ViewComponent
     include ViewComponent::Previewable
 
     # For CSRF authenticity tokens in forms
-    delegate :form_authenticity_token, :protect_against_forgery?, to: :helpers
+    delegate :form_authenticity_token, :protect_against_forgery?, :config, to: :helpers
 
     class_attribute :content_areas
     self.content_areas = [] # class_attribute:default doesn't work until Rails 5.2
 
+    # Hash of registered Slots
+    class_attribute :slots
+    self.slots = {}
+
     # Entrypoint for rendering components.
     #
     # view_context: ActionView context from calling view
@@ -105,9 +111,9 @@ module ViewComponent
       @controller ||= view_context.controller
     end
 
-    # Provides a proxy to access helper methods
+    # Provides a proxy to access helper methods from the context of the current controller
     def helpers
-      @helpers ||= view_context
+      @helpers ||= controller.view_context
     end
 
     # Removes the first part of the path and the extension.
@@ -160,8 +166,8 @@ module ViewComponent
       attr_accessor :source_location
 
       # Render a component collection.
-      def with_collection(*args)
-        Collection.new(self, *args)
+      def with_collection(collection, **args)
+        Collection.new(self, collection, **args)
       end
 
       # Provide identifier for ActionView template annotations
@@ -180,6 +186,10 @@ module ViewComponent
         # has been re-defined by the consuming application, likely in ApplicationComponent.
         child.source_location = caller_locations(1, 10).reject { |l| l.label == "inherited" }[0].absolute_path
 
+        # Clone slot configuration into child class
+        # see #test_slots_pollution
+        child.slots = self.slots.clone
+
         super
       end
 
@@ -192,9 +202,7 @@ module ViewComponent
       end
 
       def compiled?
-        @compiled ||= false
-
-        @compiled && ActionView::Base.cache_template_loading
+        CompileCache.compiled?(self)
       end
 
       # Compile templates to instance methods, assuming they haven't been compiled already.
@@ -270,7 +278,7 @@ module ViewComponent
           RUBY
         end
 
-        @compiled = true
+        CompileCache.register self
       end
 
       # we'll eventually want to update this to support other types
@@ -308,7 +316,16 @@ module ViewComponent
         parameter = validate_default ? collection_parameter : provided_collection_parameter
 
         return unless parameter
-        return if instance_method(:initialize).parameters.map(&:last).include?(parameter)
+        return if initialize_parameters.map(&:last).include?(parameter)
+
+        # If Ruby cannot parse the component class, then the initalize
+        # parameters will be empty and ViewComponent will not be able to render
+        # the component.
+        if initialize_parameters.empty?
+          raise ArgumentError.new(
+            "#{self} initializer is empty or invalid."
+          )
+        end
 
         raise ArgumentError.new(
           "#{self} initializer must accept " \
@@ -318,6 +335,10 @@ module ViewComponent
 
       private
 
+      def initialize_parameters
+        instance_method(:initialize).parameters
+      end
+
       def provided_collection_parameter
         @provided_collection_parameter ||= nil
       end

data/lib/view_component/collection.rb

@@ -9,7 +9,7 @@ module ViewComponent
       @component.validate_collection_parameter!(validate_default: true)
 
       @collection.map do |item|
-        content = @component.new(component_options(item, iterator)).render_in(view_context, &block)
+        content = @component.new(**component_options(item, iterator)).render_in(view_context, &block)
         iterator.iterate!
         content
       end.join.html_safe

data/lib/view_component/compile_cache.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  # Keeps track of which templates have already been compiled
+  # This is not part of the public API
+  module CompileCache
+    mattr_accessor :cache, instance_reader: false, instance_accessor: false do
+      Set.new
+    end
+    module_function
+
+    def register(klass)
+      cache << klass
+    end
+
+    def compiled?(klass)
+      cache.include? klass
+    end
+
+    def invalidate!
+      cache.clear
+    end
+  end
+end

data/lib/view_component/engine.rb

@@ -69,6 +69,10 @@ module ViewComponent
           get "#{options.preview_route}/*path", to: "view_components#previews", as: :preview_view_component, internal: true
         end
       end
+
+      app.executor.to_run :before do
+        CompileCache.invalidate! unless ActionView::Base.cache_template_loading
+      end
     end
   end
 end

data/lib/view_component/slot.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  class Slot
+    attr_accessor :content
+  end
+end

data/lib/view_component/slotable.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+require "view_component/slot"
+
+module ViewComponent
+  module Slotable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # support initializing slots as:
+      #
+      # with_slot(
+      #   :header,
+      #   collection: true|false,
+      #   class_name: "Header" # class name string, used to instantiate Slot
+      # )
+      def with_slot(*slot_names, collection: false, class_name: nil)
+        slot_names.each do |slot_name|
+          # Ensure slot_name is not already declared
+          if self.slots.key?(slot_name)
+            raise ArgumentError.new("#{slot_name} slot declared multiple times")
+          end
+
+          # Ensure slot name is not :content
+          if slot_name == :content
+            raise ArgumentError.new ":content is a reserved slot name. Please use another name, such as ':body'"
+          end
+
+          # Set the name of the method used to access the Slot(s)
+          accessor_name =
+            if collection
+              # If Slot is a collection, set the accessor
+              # name to the pluralized form of the slot name
+              # For example: :tab => :tabs
+              ActiveSupport::Inflector.pluralize(slot_name)
+            else
+              slot_name
+            end
+
+          instance_variable_name = "@#{accessor_name}"
+
+          # If the slot is a collection, define an accesor that defaults to an empty array
+          if collection
+            class_eval <<-RUBY
+              def #{accessor_name}
+                #{instance_variable_name} ||= []
+              end
+            RUBY
+          else
+            attr_reader accessor_name
+          end
+
+          # Default class_name to ViewComponent::Slot
+          class_name = "ViewComponent::Slot" unless class_name.present?
+
+          # Register the slot on the component
+          self.slots[slot_name] = {
+            class_name: class_name,
+            instance_variable_name: instance_variable_name,
+            collection: collection
+          }
+        end
+      end
+    end
+
+    # Build a Slot instance on a component,
+    # exposing it for use inside the
+    # component template.
+    #
+    # slot: Name of Slot, in symbol form
+    # **args: Arguments to be passed to Slot initializer
+    #
+    # For example:
+    # <%= render(SlotsComponent.new) do |component| %>
+    #   <% component.slot(:footer, class_names: "footer-class") do %>
+    #     <p>This is my footer!</p>
+    #   <% end %>
+    # <% end %>
+    #
+    def slot(slot_name, **args, &block)
+      # Raise ArgumentError if `slot` does not exist
+      unless slots.keys.include?(slot_name)
+        raise ArgumentError.new "Unknown slot '#{slot_name}' - expected one of '#{slots.keys}'"
+      end
+
+      slot = slots[slot_name]
+
+      # The class name of the Slot, such as Header
+      slot_class = self.class.const_get(slot[:class_name])
+
+      unless slot_class <= ViewComponent::Slot
+        raise ArgumentError.new "#{slot[:class_name]} must inherit from ViewComponent::Slot"
+      end
+
+      # Instantiate Slot class, accommodating Slots that don't accept arguments
+      slot_instance = args.present? ? slot_class.new(args) : slot_class.new
+
+      # Capture block and assign to slot_instance#content
+      slot_instance.content = view_context.capture(&block) if block_given?
+
+      if slot[:collection]
+        # Initialize instance variable as an empty array
+        # if slot is a collection and has yet to be initialized
+        unless instance_variable_defined?(slot[:instance_variable_name])
+          instance_variable_set(slot[:instance_variable_name], [])
+        end
+
+        # Append Slot instance to collection accessor Array
+        instance_variable_get(slot[:instance_variable_name]) << slot_instance
+      else
+         # Assign the Slot instance to the slot accessor
+        instance_variable_set(slot[:instance_variable_name], slot_instance)
+      end
+
+      # Return nil, as this method should not output anything to the view itself.
+      nil
+    end
+  end
+end

data/lib/view_component/version.rb

@@ -3,7 +3,7 @@
 module ViewComponent
   module VERSION
     MAJOR = 2
-    MINOR = 8
+    MINOR = 12
     PATCH = 0
 
     STRING = [MAJOR, MINOR, PATCH].join(".")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component
 version: !ruby/object:Gem::Version
-  version: 2.8.0
+  version: 2.12.0
 platform: ruby
 authors:
 - GitHub Open Source
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-08 00:00:00.000000000 Z
+date: 2020-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -200,12 +200,15 @@ files:
 - lib/view_component.rb
 - lib/view_component/base.rb
 - lib/view_component/collection.rb
+- lib/view_component/compile_cache.rb
 - lib/view_component/engine.rb
 - lib/view_component/preview.rb
 - lib/view_component/previewable.rb
 - lib/view_component/render_monkey_patch.rb
 - lib/view_component/render_to_string_monkey_patch.rb
 - lib/view_component/rendering_monkey_patch.rb
+- lib/view_component/slot.rb
+- lib/view_component/slotable.rb
 - lib/view_component/template_error.rb
 - lib/view_component/test_case.rb
 - lib/view_component/test_helpers.rb