Multiple calls to content-area

[jonspalmer]

In #15 we got into a detailed discussion of the use cases for multiple calls to content areas. Breaking that conversation off into a separate issue so we can continue the discussion.

Prior conversation:
#15 (comment)
#15 (comment)
#15 (comment)

[jonspalmer]

I'm going to start from here:

Why isn't the solution in your NavComponent to do this which doesn't require passing arguments:

That's an easy one to answer - because the consumer of the component shouldn't need to know the internals of how the component is rendered to use it! That's very error prone, hard to refactor/enhance and can get quite complicated when you get Stimulus involved.

Let's make it real-world complicated so you can see why you wouldn't do this. Below is a reusable timeline component. We use something like this in multiple ways - a history of project updates, a list of recent user comments, a team's onboarding of new users, etc. Each of these is backed by a list of many different models or polymorphic lists, so we can't tie the TimelineComponent to any particular model.

Using your method without arguments, the TimelineComponent consumers would have to do this:

<%= render(TimelineComponent.new(option1: X, option2: Y) do |c| %>
  <% activities.each_with_index do |activity, index| %>
    <% c.with(:item) do %>
      <div class="timeline-item">
        <div class="timeline-icon">
          <%= fa_icon(activity.icon) %>
        </div>
        <div class="vertical-line"></div>
        <div class="activity-description" 
             data-target="timeline.item" 
             data-index="<%= index %>"
        >
          <%= activity.name %>- <%= time_ago_in_words(activity.created_at) %>
        </div>
      </div>
    <% end %>
  <% end %>
<% end %>

That unnecessarily exposes a TON about internals of the TimelineComponent to the consumer, when all the component needs beyond the yield input is the icon.

By allowing with to take in arguments, you get this instead:

<%= render(TimelineComponent.new) do |c| %>
  <% activities.each do |activity| %>
    <% c.with(:item, icon: activity.icon) do %>
      <%= activity.name %> - <%= time_ago_in_words(activity.created_at) %>
    <% end %>
  <% end %>
<% end %>

I hope that example speaks for itself! The consumer doesn't need to care at all about how the timeline renders, just what input it takes.

Now imagine that this TimelineComponent came from a third party gem. Knowing all of the internals of how it works would be a mess!

@bbugh I hadn't thought through the use cases of multiple content-areas fully. I can see now why you're want to 'template' the items around them so as to not leak the details of the implementation.

However, the combination fo suppling the multiple content-area plus arguments to with feels like a strange API that is hard to document. I think I would expect that problem to be solved like this:

class TimelineComponent < ViewComponent
  attr_reader :items

  # @param [Array<Hash>] items 
  def initialize(items:)
    @items = items
  end
end

<!-- timeline_component.html.erb -->
<div class="timeline">
  ...
  <% items.each_with_index do |item, index| %>
    <div class="timeline-item">
        <div class="timeline-icon">
          <%= fa_icon(item[:icon]) %>
        </div>
        <div class="vertical-line"></div>
        <div class="timeline-item-description" 
             data-target="timeline.item" 
             data-index="<%= index %>"
        >
          item[:description]
        </div>
      </div>
  <% end %>
  ...
</div>

Get's used line this:

class ActivitiesTimelineComponent < ViewComponent
  attr_reader :activities

  def initialize(activities:)
    @activities = activities
  end

  def timeline_items
    @timeline_items ||= activities.map do |activity|
      {
        icon: activity.icon,
        description: "#{activity.name} -#{time_ago_in_words(activity.created_at)}"
      }
    end    
end

<!-- activities_timeline_component.html.erb -->
<%= render(TimelineComponent.new(items: activities_timeline) %>

It's not required to have the ActivitiesTimelineComponent. The logic of constructing the timeline_items could live in a controller etc. Personally I'd probably have it with an eye towards encapsulation/testability and to keep controllers thin/dumb.

IMO the above setup is easier to grok and easier to test with a clear API on TimelineComponent where you hand in the items vs repeat calls to with(:item).

I suspect I'm missing some part of the use case I'd love to continue the conversation to nail it down.

[bbugh]

Thanks for continuing the conversation @jonspalmer!

It's hard to talk about this multi-content area issue separate from the other ones I was discussing, because they are all involved with solving the same root problem.

The proposals are 1) with available to loops, 2) with taking in arguments, and 3) #285 with being able to pass back arguments to the block (which I would have mentioned as a problem in my feedback comment if there wasn't already an issue for it.)

The goal of these proposals is to solve a flaw in existing front end component libraries, which ViewComponent currently shares. That flaw is that there's no solution for when you need a tightly-coupled mini-component that doesn't deserve it's own separate file, testing, resources, etc.

Because React and Vue don't support this, everything that that takes args or is part of a loop has to be a component, no matter how small and simple. In our big Vue app, we have a lot of components with 3 lines of HTML and a couple handfuls with a single line. It's a big waste of cognitive space, testing, and complexity. There's no reason at all to have these files to be standalone, separate components, except for a shortcoming in the library design.

With a few small changes, ViewComponent can solve these problems which would simplify a LOT of code and REALLY help for large projects. Ruby's dynamic nature with blocks ought to make this easy. with is really close already, so that's why I'm advocating for changing it, but we're not attached to the particular solution, just in solving the problem elegantly.

There's prior art for a Ruby version in elemental_components. If you haven't read this part of elemental_component's README that I linked earlier, I highly recommend doing so because I think it probably does a better job of explaining the problem I'm trying to re-explain. 🙂 In my opinion, ViewComponent has a better overall API (and the support of Github/Rails) so it's a better choice of libraries in the near and long term.

I can think of three solutions to consider for this problem:

1. Force every sub-section to be a separate component for loops and/or arguments, no matter how simple it is (The React/Vue Way).
2. Force component consumers to understand and write internal HTML like the verbose TimelineComponent example above (The Nobody-Wants-This Way).
3. Expose an API that allows you achieve simple "component-like" behavior when a full Component is too heavy-handed (The Proposed Way).

Currently, ViewComponent has implemented #⁠1. We (and I believe some other commenters in the feedback issue) are proposing to also support #⁠3.

---

I hope that the above explanation gives enough context to get on the same page and discuss viable solutions.

As for your suggestion about ActivitiesTimelineComponent and making child components for each data list, I don't think that's a good answer for this problem. We'd end up with a 100+ child components that only differed by a single data method, which would be a testing, previewing and code coverage nightmare. At that point, we'd be better off writing helpers because they'd be easier to test, and in my humble opinion if a helper is the best choice, then there's something wrong with the other choices. 😎

There are other limitations with that suggestion, like: What if the description should have HTML? What about reading other instance variables from the controller (like the current user)? What about using other components? What about third party libraries that offer reusable components, do you write custom wrapper components for every one of those too? Yikes!

If that's not clear enough, here's an even more complex example that wouldn't work with the "child components have the data" idea. There's some extra information from the controller and it needs to render another component.

<%= render(TimelineComponent.new) do |c| %>
  <% c.with(:header) do %>
    Recent Activity for <%= @project.name %>
  <% end %>

  <% @activities.each do |activity| %>
    <% c.with(:item, icon: activity.icon) do %>
      <!-- use a value from the controller -->
      <span class="activity-user <%= 'highlight' if activity.user == current_user %>">
        <%= activity.user.name %>
      </span>
      - 
      <span class="text-muted">
        <!-- renders another component that has some javascript -->
        <%= render(RelativeTimeComponent.new(activity.created_at, update_interval: 60.seconds)) %>
      </span>
    <% end %>
  <% end %>
<% end %>

<!-- timeline_component.html.erb -->
<div class="timeline" data-controller="timeline">
  <div class="timeline-header">
    <%= header %>
  </div>
  <!-- this is really simple! doesn't need to be another component! --> 
  <% items.each_with_index do |item, args, index| %>
    <div class="timeline-item">
      <div class="timeline-icon">
        <%= fa_icon(args[:icon]) %>
      </div>
      <div class="vertical-line"></div>
      <div class="activity-description" data-target="timeline.item" data-index="<%= index %>">
        <%= item %>
      </div>
    </div>
  <% end %>
</div>

[jonspalmer]

@bbugh Got it super helpful context. I agree the various feature sets are interrelated.

I see the need for a version of 3 that you're proposing. The need to render HTML drives us towards support it via some version of the with syntax.

Sidetrack comment

As a total aside the "reading other instance variables" is, IMO and experience, not a great pattern. I've learned too many times that putting logic in the view like this is fragile and hard to test. For example: activity.user == current_user in the erb exposes a dependency on current_user that is non-obvious and harder to test well. Instead I would want activities to have a boolean property like 'active?` I would typically wrap the activities in some other data structure that I can test. i.e.

class ActivitiesDecorator < SimpleDelegator
  def initialize(activity, current_user)
    super(activity)
    @current_user = current_user
  end

  def active?
    activity.user == @current_user
  end
end

and then somewhere when preparing the data I'd do

decorated_activities = activities.map { |a| ActivitiesDecorator.new(a, current_user)

and hand decorated_activities to TimelineComponent etc. etc.
That said nothing we implement here is going to stop you doing it either way.

I digress.....back to the point at hand.

What should the API be?

We've shared some ideas about what the API might be and elemental_components has some ideas there too. However, there are a bunch of cases to consider that need careful examination.

Design Goals

1. API should be simple, clear, natural but flexible
2. For the simple use case of providing html content for an area ideally we have the same API as today
3. Easily testable

Use Cases

1. Provide the "content block" for an area
2. Provide arguments other than the "content block" for an area
3. Pass a set of arguments to the "content block"
4. Multiple use of a content area. There are two flavors:
   1. A single "content block" from one call to with that the component calls multiple times with different passed arguments
   2. Multiple "content blocks" from multiple calls to with that the component iterates over.
5. Combinations of the above

1. Provide the "content block" for an area - Today's API

The existing API allows you to provide strings or html content for a content area. Because it was easy to support but not driven by any real world use cases there are actually three ways to provide content.

class ModalComponent < ViewComponent::Base
  with_content_areas :header, :body
end

<!-- app/components/modal_component.html.erb -->
<div class="modal">
  <div class="header"><%= header %></div>
  <div class="body"><%= body %></div>
</div>

content as constructor argument

<%= render(ModalComponent.new, header: "Hello Jane") do |component| %>
  <!-- body -->
  ...
<% end %>

content as non-block with argument

<%= render(ModalComponent.new) do |component| %>
  <% component.with(:header, "Hello Jane") %>
  <!-- body -->
  ...
<% end %>

content as return of with block

<%= render(ModalComponent.new) do |component| %>
  <% component.with(:header) do %>
    Hello Jane
  <% end %>
  <!-- body -->
  ...
<% end %>

We don't have to support each of these patterns going forward but it might be nice to try.

2. Provide arguments other than the "content block" for an area

Expand on the ModalContent example above. Rather than just 'content' for the header we now want the header to support an icon and a color.

class ModalComponent < ViewComponent::Base
  with_content_areas :header, :body
end

<!-- app/components/modal_component.html.erb -->
<div class="modal">
  <div class="header" style="color: "<%= header.color %>">
    <%= image_tag(header.icon) %>
    <%= header.content %>
  </div>
  <div class="body"><%= body %></div>
</div>

We can still support each of the three previous patterns:

content as constructor argument

<%= render(ModalComponent.new, header: {color: "red", icon: "start.png", content: "Hello Jane"}) do |component| %>
  <!-- body -->
  ...
<% end %>

content as non-block with argument

<%= render(ModalComponent.new) do |component| %>
  <% component.with(:header, color: "red", icon: "start.png", content: "Hello Jane") %>
  <!-- body -->
  ...
<% end %>

content as return of with block

<%= render(ModalComponent.new) do |component| %>
  <% component.with(:header, color: "red", icon: "start.png") do %>
    Hello Jane
  <% end %>
  <!-- body -->
  ...
<% end %>

This feel natural and not hugely hard to arrange/code. We'd need some careful coding around providing a string vs keyword args as the second argument to with.

Open question: Should the API for the component view be an object with properties or a hash?

<!-- app/components/modal_component.html.erb -->
<div class="modal">
  <div class="header" style="color: "<%= header.color %>">
    <%= image_tag(header.icon) %>
    <%= header.content %>
  </div>
  <div class="body"><%= body %></div>
</div>

vs.

<!-- app/components/modal_component.html.erb -->
<div class="modal">
  <div class="header" style="color: "<%= header[:color] %>">
    <%= image_tag(header[:icon]) %>
    <%= header[:content] %>
  </div>
  <div class="body"><%= body %></div>
</div>

A hash would be slightly simpler to implement an object would be more ergonomically friendly (especially when combined with 3 below).

Note that elemental_components uses an object (I haven't looked how). However, they also force you to declare the attributes of the elements so they can probably make efficient use of predefined structs or the like. I don't we want the paperwork for the developer to have to declare their attributes.

3. Pass a set of arguments to the "content block"

This only makes sense when using the block syntax:

class EditorComponent < ViewComponent::Base
  with_content_areas :editor, :buttons
end

<!-- app/components/editor_component.html.erb -->
<div class="form">
  <%= form_for ... do |f| %>
    <div class="header">...</div>
    <div class="editor">
      <%= editor(f) %>
    </div>
    <div class="footer">
      <%= buttons(f) %>
    </div>
  <% end %>
</div>

Used like this:

<%= render(EditorComponent.new) do |component| %>
  <% component.with(:editor) do |f| %>
    <%= f.text_field :name %>
    <%= f.date_field :date_of_birth %>
  <% end %>
  <% component.with(:buttons) do |f| %>
    <%= f.submit :save %>
  <% end %>
<% end %>

This seem to work well and meet the design goals. This idea has an implementation in #323.

4. Multiple use of a content area

A single "content block" called multiple times

This only makes sense when using the block syntax. A component likely has some data that it iterates over passing each element of the array to the content block via the mechanism 3.

Suppose we have a TimelineComponent that takes a list of items and expects a single content-area for description.

class TimelineComponent < ViewComponent::Base
  with_content_areas :description, :header

  def initialize(items:)
    @items = items
  end
end

<!-- app/components/timeline_component.html.erb -->
<div class="timeline">
  <div class="timeline-header">
    <%= header %>
  </div>
  <% items.each do |item| %>
    <div class="timeline-item">
      <div class="timeline-icon">
        <%= fa_icon(item) %>
      </div>
      <div class="item-description">
        <%= description(item) %>
      </div>
    </div>
  <% end %>
</div>

Used like this:

<%= render(TimelineComponent.new(items: activities) do |c| %>
  <% c.with(:header) do %>
    Recent Activity for <%= @project.name %>
  <% end %>
  <% c.with(:item) do |activity|  %>
      <span class="activity-user">
        <%= activity.user.name %>
      </span>
      <span class="activity-date">
        <%= activity.created_at %>
      </span>
  <% end %>
<% end %>

Multiple "content blocks" from multiple calls to with that the component iterates over.

This only makes sense when using the block syntax. It also likely makes sense when the calls to with have very different content and isn't being called in a loop

Suppose we have a TabsComponent. Each tab consists of a header, a color and the content of the tab to show when its header is clicked

class TabComponent < ViewComponent::Base
  with_content_areas tab: {multiple: true}
end

<!-- app/components/tab_component.html.erb -->
<div class="tabs">
  <!-- some Stimulus JS magic to make the tab content show/hide on clicking the right header -->
  <ul class="tabs-headers">
    <% tabs.each do |tab| %>
      <li style="border-bottom: 1px solid <%= tab.color %>><%= tab.header %> </li>
    <% end %>
  </ul>
  <% tabs.each do |tab| %>
    <div class="tab-content"> <!-- plus some data attributes for Stimulus -->
      <%= tab.content %>
    </div>  
  <% end %>
</div>

Used like this:

<%= render(TabComponent.new do |c| %>
  <% c.with(:tab, color: "red", header: "Cities") do   %>
      <!-- html content about cities -->
  <% end %>
  <% c.with(:tab, color: "green", header: "States") do   %>
      <!-- html content about states -->
  <% end %>
  <% c.with(:tab, color: "blue", header: "Countries") do   %>
      <!-- html content about countries -->
  <% end %>
<% end %>

Open question: How do we trigger "multiple" mode?

We likely need some way to signal that with can be called more than once and make the plural version of the area available. Elemental_components uses multiple: true. Is that enough?

Open question: Do we need the set of arguments to be defined statically?

1. What happens if some calls to the content block supply arguments but others don't?
2. How do we avoid surprised for the component view so that it can iterate over consistent structures?
3. How do we achieve both the above but still have a 'simple' API if you don't want to pass args?

5. Combinations of the above

I'm tired 😫. Use your imagination 😄 .

@bbugh, @joelhawksley and others I'd love your thoughts on the above. Phew I'm out.

[joelhawksley]

@jonspalmer @bbugh thank you for digging into this question in such detail. I'm excited to see where we end up!

Do we need the set of arguments to be defined statically?

The only way I can think of this being palatable would be to allow for "internal" components, where an internal component is defined inside of another component, and thus can have its own initializer, which brings me to:

How do we achieve both the above but still have a 'simple' API if you don't want to pass args?

This is one reason I like the idea of using hashes for these arguments. It allows developers to use Hash#fetch for graceful fallbacks.

We likely need some way to signal that with can be called more than once and make the plural version of the area available.

Could we leverage Rails' built-in support for inflections to pull this off? I'd love to avoid the multiple: true syntax if possible. No big deal if we need to use it though.

@jonspalmer I'm wondering if we should consider deprecating the non-block syntax for content areas. I don't know how useful it is, and if it was getting in the way of accomplishing our goals here I'd be OK with removing it.

I'm also wondering if we'd want to consider removing the with syntax and moving to having the content areas be methods on the component:

<%= render(TimelineComponent.new(items: activities) do |c| %>
  <% c.header centered: true do %>
    Header
  <% end %>
  <% c.section size: "large" do %>
    Section 1
  <% end %>
  <% c.section size: "large" do %>
    Section 2
  <% end %>
  <% c.footer do %>
    Footer
  <% end %>
<% end %>

example shamelessly adapted from https://github.com/jensljungblad/elemental_components

If we went this route, we could implement this new API without worrying about supporting these changes in the with syntax.

@jensljungblad I'd love your input here, as you've clearly put a lot of thought into building a similar API for elemental_components. What do you think?

[jonspalmer]

Do we need the set of arguments to be defined statically?

The only way I can think of this being palatable would be to allow for "internal" components, where an internal component is defined inside of another component, and thus can have its own initializer, which brings me to:

This i my sense too. When I look at the examples I documented above I think "boy you know want looks a lot like passing a set of arguments and a block to a content area? Another ViewComponent".

How do we achieve both the above but still have a 'simple' API if you don't want to pass args?

This is one reason I like the idea of using hashes for these arguments. It allows developers to use Hash#fetch for graceful fallbacks.

I can buy that argument. 👍

We likely need some way to signal that with can be called more than once and make the plural version of the area available.

Could we leverage Rails' built-in support for inflections to pull this off? I'd love to avoid the multiple: true syntax if possible. No big deal if we need to use it though.

I'm sure we can use the inflections for the implementation. The need for a static declaration might be

1. Would we want to always create the plural versions of the methods (which might be a weird bug for someone not expecting it)
2. Do we need to support switching behavior. Today if you call a content area twice the second call replaces the first. I don't know if we have a use case driven need for that.
3. We can't reply on multiple calls to the area to trigger array behavior. The consumer in the components view is going to expect an array. If the content area is only called once its going to expect an array with one value, not the raw value.

@jonspalmer I'm wondering if we should consider deprecating the non-block syntax for content areas. I don't know how useful it is, and if it was getting in the way of accomplishing our goals here I'd be OK with removing it.

Yup I'm ok removing it. I think we can leave it in the with but remove the version where content-areas are also attr_readers and so can be set from the constructor.

I'm also wondering if we'd want to consider removing the with syntax and moving to having the content areas be methods on the component:
....
example shamelessly adapted from https://github.com/jensljungblad/elemental_components

If we went this route, we could implement this new API without worrying about supporting these changes in the with syntax.

I like this. I'd need to look to see how elemental_components does it. Somehow we need to solve the name overload for the getter/setter of the area but its clearly solvable.

I suspect one thing we have to give up to support all of this is the 'simple' version of retrieving the content area. I think we're going to end up with the components view always doing footer.content to get the result of the block vs just being able to use footer. This is a huge simplification for a consistent API whether the content-area is called with attributes or not. I suspect it must be a breaking change.

[bbugh]

I'm three novels behind! I better write another one...

@jonspalmer I think you summed up the different scenarios and the patterns very well.

This is one reason I like the idea of using hashes for these arguments. It allows developers to use Hash#fetch for graceful fallbacks.

I personally prefer the header.icon version over the header[:icon] version. It seems more Rails-y to me, since there's precedent with Rails templates almost exclusively using locals and instance variables. As for fetch, you can easily provide a default with <%= header.icon || 'default' %>.

The only way I can think of this being palatable would be to allow for "internal" components, where an internal component is defined inside of another component, and thus can have its own initializer

When I look at the examples I documented above I think "boy you know want looks a lot like passing a set of arguments and a block to a content area? Another ViewComponent".

I was inspired by this and wrote a bunch about how it might work, then realized at the end that I don't think this solves one of the main weaknesses. In my opinion, one of the key goals of this issue is to avoid having a bunch of tiny child components like this, wherever you put them:

class CardHeaderComponent < ViewComponent
  def initialize(icon:)
    @icon = icon
  end
end

<!-- card_header_component.html.erb -->
<header class="my:big list-of tailwind-classes">
  <%= content || "Default header" %>
</header>

We have a lot of these in our Vue client, and not one of them is useful outside of their parent class.

React's solution is equally pointless, but you can at least put the all of the micro comonents into the same file as the parent:

export const Header = ({icon, children}) => 
  <header className={'tailwind classes ' + icon}>{ children }</header>

export const Card = (...) => ...

So, unless I misunderstood and you meant something like "invisible ViewComponents used by the internal rendering system", I'm not sure how well that would work.

I'm also wondering if we'd want to consider removing the with syntax and moving to having the content areas be methods on the component:

I think that's a cool idea too. What if they're actual methods on the component?

class CardComponent < ViewComponent
  content_areas :header, :footer
  
  # OR defining them individually allows for present or future configuration options,
  # which could be really useful.
  content_area :item, type: :list, some_other_field_option: :maybe

  # OR another method just for lists, if content areas never need configuration?
  content_list :item
  
  # you could override them if you need to provide for options
  def item(icon: 'SCREAM') 
    # Q: does super call method_missing if parent doesn't implement?
    super(icon: icon.downcase) 
  end
end

<!-- using card as a consumer -->
<%= render(CardComponent.new) do |c| %>
  <% c.header(icon: 'fas fa-calculator') do %>
    This is going to be a great header
  <% end %>

  <% 1.upto(10) do |i| %>
    <% c.item do |f| %>
      <%= f.input_tag "favorite_fruit_#{i}" %>
    <% end %>
  <% end %>
<% end %>

I hope this all made sense! My brain is tired from a lot of heavy system work the last few days.

[joelhawksley]

Wow GitHub has threading, where'd that come from?

We're trying out the beta of Discussions 😄

You end up with a bunch of tiny extra files for tightly-coupled micro-components.

Forgive me for not providing a complete example! I was just mocking a component up while pairing with my colleague @jonrohan:

# app/components/list_group_component.rb

class ListGroupComponent < ViewComponent::Base
  content_area_class Header
    attr_reader :class_names

    def initialize(class_names:)
      @class_names = "list-group-header #{class_names}"
    end
  end

  collection_content_area_class Item
    attr_reader :disabled

    def initialize(disabled: false)
      @disabled = disabled
    end
  end

  content_area_class Footer
    attr_reader :class_names

    def initialize(class_names:)
      @class_names = "list-group-footer #{class_names}"
    end
  end
end

# app/components/list_group_component.html.erb

<div class="list-group">
  <div class="<%= header.class_names %>">
    <%= header.content %>
  </div>

  <% items.each do |item| %>
    <div class="list-group-item" disabled="<%= item.disabled %>">
      <%= item.content %>
    </div>
  <% end %>

  <div class="<%= footer.class_names %>">
    <%= footer.content %>
  </div>
</div>

# app/views/demo/index.html.erb

<%= render ListGroupComponent.new do |component| %>
  <% component.header(class_names: "mt-3") do %>
    My List Group
  <% end %>
  <% component.item do %>
    My First Item
  <% end %>
  <% component.item do %>
    My Second Item
  <% end %>
  <% component.item(disabled: true) do %>
    My Disabled Item
  <% end %>
  <% component.footer(class_names: "color-blue") %>
    My List Group Footer
  <% end %>
<% end %>

[jonspalmer]

@joelhawksley I love this latest example. Very clean.
I'm curious about the syntax are content_area_class and collection_content_area_class actually declaring new classes?

I think my comment was, as @bbugh is pointing out, on a slightly different track. I was reacting more to the idea of nester attributes/validation that is supported in ElementalComponents. IMO those kinds of use cases we you have nested are likely complex enough that a sub component or two is the right design. My spidey sense are telling me that there is overlap between content areas and ViewComponents having an API natural enough to write a Rails (+Stimulus) version fo something like ReactSelect. But maybe all the later needs is component composition.

[joelhawksley]

I'm curious about the syntax are content_area_class and collection_content_area_class actually declaring new classes?

My thinking is yes, so we can use the initializer behavior native to Ruby. I'd love to avoid going too far in the direction of a DSL like elemental_components which, while elegant, feels a little abstract to me.

Then again, maybe we're already past that threshold here 😅

What do you think @bbugh?

[bbugh]

More novels! Nobody will be able to say we didn't thoroughly talk this through.

We're trying out the beta of Discussions 😄

Nice. I wonder if that explains why I got re-sent a bunch of notification emails for everybody's comments from both threads I've participated in. 🤪

Forgive me for not providing a complete example! I was just mocking a component up while pairing with my colleague @jonrohan:

Thanks for the sample code, what you were saying before does make more sense. I think using classes like that is making the API more complex than necessary, though. I keep thinking "It's Just Ruby" functions and blocks, this "should be" easy!.

Technically speaking, We only need to capture the block context and return it when those methods are called. With method_missing you can simplify this a lot and not worry about classes at all, while still getting the same behavior. All of the NoMethodError and ArgumentError's work the way you'd expect, and it's Just Ruby functions and blocks.

I've been thinking about how to do this and finally got some time tonight to write it. This is functional code that illustrates the CardComponent method-based version I shared here: #325 (comment). Hold on to your socks.

If you try the code out (you just need the SimpleCallableViewComponent) I think you'll find that this feels like a very idiomatic Ruby/Rails solution.

class SimpleCallableViewComponent < ViewComponent::Base
  def self.with_content_areas(*areas)
    super
    # Delete the attr_readers that with_content_areas created
    areas.each { |a| remove_method(a) }
  end

  def respond_to_missing?(mthd)
    content_areas.include?(mthd) || super
  end

  def method_missing(mthd, *_args, **options, &block)
    unless content_areas.include?(mthd)
      super
    end

    if block_given?
      content = view_context.capture(&block)
    end

    object = nil
    if options.present? || content.present?
      locals = options.merge(content: content)
      object = Struct.new(*locals.keys, keyword_init: true).new(locals)
    end
    define_singleton_method(mthd) { object }
    object
  end
end

class ExampleComponent < SimpleCallableViewComponent
  with_content_areas :header, :footer
  attr_reader :title

  def initialize(title:)
    @title = title
  end

  def footer(icon: nil, classes: [])
    super
  end
end

And now for usage - it's exactly like a Rails partial. Want to make content areas required? Easy, just don't check for nil. Here, header is required and will fail as expected, but footer is optional:

<!-- example_component.html.erb -->
<div class="card" style="border: 4px solid green; margin: 10px">
  <div class="card-header">
    <%= header.content %>
  </div>
  <div class="card-body">
    <%= content %>
  </div>
  <% if footer %>
    <div class="card-footer <%= footer.classes.join(" ") %>">
      <%= footer.content %>
    </div>
  <% end %>
</div>

From both the user and the component creator's perspective, it works just like any other function and block. If you call header with any arguments you get a "too many arguments" error in the right place. If you call footer with the wrong arguments, you get an "unknown keyword" argument in the right place. Etc.

It does not support passing positional arguments to the template, but neither does the Rails render command, so I don't think it matters.

Want to combine optional and required keyword arguments? Bazam, it's just Ruby! Here they must enter icon argument:

def footer(icon:, classes: [])
  super
end

Want to validate your arguments? Bazam, it's just Ruby! Strings only!

def footer(name:)
  raise "Not a string" unless name.is_a?(String)
  super
end

What about deciding later that you internally want to use a FooterComponent instead of just the struct object? Easy! Just return the component you want instead of calling super. Future proof, and the down-stream consumers don't even have to care that it's a component now, it just keeps working.

class FooterComponent < SimpleCallableViewComponent
  attr_reader :classes, :icon

  def initialize(classes: [], icon:"")
    @classes = classes
    @icon = icon
  end
end

class ExampleComponent < SimpleCallableViewComponent
  def footer(**options, &block)
    FooterComponent.new(**options, &block)
  end
end

This does result in the template trying to call the private content method and I didn't come up with a solution for that, but it seems easily solvable. I've been thinking about how to adapt it to allow for lists and I don't think it will be hard either. I tested pretty thoroughly and I think it's mostly complete minus a few other error checks.

If I get some time, I will PR this over the weekend for testing.

[jensljungblad]

@joelhawksley In response to your latest example!

The content_area_class Header looks to be doing something similar to the element declaration I use. What is content_area_class meant to do that class doesn't? Also, do you need to refer to these classes from somewhere, or could they be anonymous?

[jensljungblad]

@joelhawksley @jonspalmer Hi! I feel like I need to catch up on some reading here. But yes, it looks like you're going through almost the exact same thing I went through a couple of years ago. Asking the same questions and thinking about the same trade-offs :) I'm happy to explain my thought process and the API I ended up with. I'd be happy to have elemental_components merged into view_component and hopefully Rails one day.

I'll try and reply later this week!

In the meantime, https://github.com/jensljungblad/elemental_components#elements tries to sum up some of my thoughts on these topics.

[jensljungblad]

There's obviously a lot going on in this discussion, so I'm just going to jump in. I'll explain a bit what I was inspired by, and how I arrived at the API. I'll try and answer some of the questions I've seen asked here throughout.

I wish I had my notes for this project but they are unfortunately on the other side of the Atlantic. I'll do my best to remember :)

Inspirations

I've been a proponent for component based design for a long while, I usually like to link to http://bradfrost.com/ who I think did a lot of good work early on trying to push these ideas. Initially my idea for the Ruby library was to try and go beyond very generic libraries like React in favor of something a little bit more opinionated, making certain design concepts first-class citizens, if you will. It never really got there but you can see some remnants of those early ideas in the API.

I've worked a lot with the http://getbem.com methodology, but also OOCSS and other more utility class approaches. The elements in my API actually come from the BEM concept:

A part of a block that has no standalone meaning and is semantically tied to its block.

(Originally my components were named blocks, and modifiers were first-class citizens. Eventually I opted for a more generic API.)

I tend to think about two different types of components. I'm sure there are some good names out there but I ended up referring to them as domain components and building block components.

• Building block components are generic components, probably part of a design system, and usually requires taking content areas as arguments. Bottom line, they need to be flexible. Things like CardComponent etc.
• Domain components typically only need to take a data structure (such as a Rails model) as an argument, and that's it. It is often composed out of building block components, but never the other way around. These could be things like a CommentComponent etc.

It's interesting to note that almost all of the complicated component needs, such as multiple content areas, repeating content areas etc, are for these building block components. This is another concept that I toyed with having as a first-class citizen.

I see you've already talked a bit about my comments reg. React. So just to clarify, the thing I've seen ab(used) a lot in React with regards to building block components, is the following pattern:

<Card>
  <CardHeader>Hey!</CardHeader>
</Card>

Basically turning what really is internal subcomponents into regular components. There is no difference between Card and CardHeader in this example, and I don't buy into that. The internal subcomponent, to quote BEM, "has no standalone meaning".

You cannot inject HTML content into a private subcomponent (or subcomponents) in React, in an elegant way. At least not that I've seen. Mind you I've been out of the front-end business for a couple of years so maybe it's gotten better :) This always bothered me and I feel Ruby/Rails should be able to do better. I actually really enjoyed the API I eventually ended up with, compared to what I had to work with in React-land.

The API: how it evolved and how it works under the hood

In the very first version, this is what the API looked like:

class PanelComponent < Components::Component
  attribute :header
  attribute :body
end

<% # app/components/panel/_panel.html.erb %>

<div class="Panel">
  <div class="Panel-header">
    <%= panel.header %>
  </div>
  <div class="Panel-body">
    <%= panel.body %>
  </div>
</div>

 <%= component :panel, header: "Header", body: "Body" %>

<%= component :panel, header: "Header" do |attributes| %>
  <% attributes[:body] = capture do %>
    <ul>
      <li>...</li>
    </ul>
  <% end %>
<% end %>

As you can see I made no distinction between attributes/elements at this point, but left it up to the user to make use of the capture helper. The block yielded the attributes hash, with the declared attributes, that could be modified before being sent to the component.

The next iteration changed things up a bit by yielding the component instead of the attributes hash:

<%= component "panel" do |c| %>
  <% c.header do %>
    Captured header
  <% end %>
<% end %>

This is similar to how Rails constructs forms, using FormBuilders. I considered having a ComponentBuilder that would be yielded but never had go that far. It was fine to instantiate the component immediately, yield it, then allow it to be modified by the block.

There was still no distinction between attributes/elements. The #header method was generated via the attribute(:header) declaration.

I toyed with different APIs for this, such as c.capture(:header), c.content_for(:header) etc, which sounded Rails-y and which would have avoided the need to declare the #header method at all.

I knew I wanted to be able to pass attributes to these subcomponents though. This from the fact that it is a common pattern in CSS, BEM, Bootstrap etc to have modifiers both on the top level component and its subcomponents:

<div class="card card--wide">
  <div class="card__header card__header--large">
  </div>
</div>

So the question became how to pass these down. Now that I had the yielded component, it felt very natural to just pass them to that method:

<%= component "panel", wide: true do |c| %>
  <% c.header(large: true) do %>
    Captured header
  <% end %>
<% end %>

This led to a problem though. There was now a difference between "simple" attributes and these new attributes that could in turn take attributes. Before all of these were valid:

<%= component :panel, header: "Header", body: "Body" %>

<%= component :panel, header: "Header" do |c| %>
  <% c.body = "Some body" %>
<% end %>

<%= component :panel, header: "Header" do |c| %>
  <% c.body do %>
    Captured body
  <% end %>
<% end %>

But because of the requirement that I wanted to pass arguments to these subsections, I had to rethink. The distinction between attributes and elements was born:

• Components have attributes, elements
• Attributes are simple values
• Elements have attributes and yielded content

The API for declaring them was initially

class Card < Components::Component
  has_one :header
  has_many :sections do
    attribute :size
  end
  has_one :body
end

This is actually very similar to the content_area_class example that @joelhawksley posted. What these methods did was to create (anonymous) classes inheriting from an Element base class, which in turn included an Attributes module that was also used by the base Component class.

Alright, great. One thing that bugged me was that I still didn't support this very simple scenario:

<%= component "alert" do %>
  Some content, without an element
<% end %>

The reason for that being that I didn't have the concept of content blocks for the top level component. It always yielded the component itself to the block, and you had to use it to assign content:

<%= component "alert" do |c| %>
  <% c.body do %>
    Some content, without an element
  <% end %>
<% end %>

The solution to the problem was the same thing @jonspalmer observed:

When I look at the examples I documented above I think "boy you know want looks a lot like passing a set of arguments and a block to a content area? Another ViewComponent".

Which is pretty much exactly what I did:

class Element
  has_attributes
  has_elements
  has_content
end

class Component < Element
  def render; end
end

This turned the top level component into an element, meaning it had attributes + elements + a single content variable, and this was now possible:

<%= component "alert" do %>
  Some content, without an element
<% end %>

It also meant elements could be nested. I don't necessarily think that is a good design practice (two levels maybe, three is getting silly) but it made the API neat and consistent.

I glossed over repeating elements, which was happening in parallel. The need came from a few of our design system components. Yet again it was the building block components that wanted special treatment... We had several components which could contain one or many <section>s, or <li>s. The initial implementation used has_one and has_many, mostly because I didn't know what to call what I eventually ended up calling elements. (They actually went from: element -> content_block -> unnamed -> element!) I experimented with just detecting if the method was called repeatedly, then converting it to an array, but that felt a bit wonky, plus then I couldn't generate the pluralized name for the method, which was one of those things that just made it nicer and fit better with Rails.

Questions

@jonspalmer Note that elemental_components uses an object (I haven't looked how). However, they also force you to declare the attributes of the elements so they can probably make efficient use of predefined structs or the like. I don't we want the paperwork for the developer to have to declare their attributes.

Correct, elements are objects with defined attributes. I too experimented with hashes instead of objects: jensljungblad/elemental_components#20, jensljungblad/elemental_components#19. I toyed with the idea of precompiling everything (helper methods included) into a hash and pass that to the template. That would have allowed completely different rendering systems as well.

The designers I worked with tended to prefer header.icon over header[:icon] though.

@joelhawksley I'm also wondering if we'd want to consider removing the with syntax and moving to having the content areas be methods on the component
@jonspalmer I like this. I'd need to look to see how elemental_components does it. Somehow we need to solve the name overload for the getter/setter of the area but its clearly solvable.

I think I answered this above, let me know if it's still unclear.

@jonspalmer I suspect one thing we have to give up to support all of this is the 'simple' version of retrieving the content area. I think we're going to end up with the components view always doing footer.content to get the result of the block vs just being able to use footer.

I actually had this going for the longest time, by leveraging the fact that #to_s gets called automatically I you <%= an object. Since my footer is an object, the base Element class implemented a def to_s; @content; end. This was eventually removed, I forget why! It's a bit strange, but kind of neat.

Sorry for adding another novel to the list!

[bbugh]

After playing with a bunch of different solutions this weekend, I came to the conclusion that it probably will require a DSL. I imagine I'm just re-treading the same path that @jensljungblad already tread. 🤪