call should take ERB

[boardfish]

#1249's in, which puts all generator options under the generate namespace 🎉 But there's a comment in there that has me reflecting on how to think about the relationship between data we render and the components themselves. One thing I did as part of that PR to allow us more flexibility with how the API docs are generated was to use ViewComponent itself to do that. I wrote this component, which is then given data in the docs:build Rake task and rendered to a string. But @joelhawksley suggested that the data could've instead been rendered by a component and passed to a slot:

The sections are Structs, which tend to be a good start to help avoid primitive obsession. and allows us to sort the data on the way in.

module ViewComponent
   class DocsBuilderComponent < Base
     class Section < Struct.new(:heading, :methods, :show_types, keyword_init: true)
       def initialize(heading: nil, methods: [], show_types: true)
         methods.sort_by! { |method| method[:name] }
         super
       end
     end
  end
end

At the point that I wrote this, it wasn't intuitive for me to go from that Struct to a ViewComponent, and following that, a slot. It didn't occur to me that those sections are only for use in the "view layer" in this problem (outputting to a text file), and that it'd naturally follow for a Section to be a component.

But I also wasn't in much of a hurry to do so. The view code for the component is as follows:

---
 layout: default
 title: API
 nav_order: 3
 ---

 <!-- Warning: AUTO-GENERATED file, don't edit. Add code comments to your Ruby instead <3 -->

 # API

 <% @sections.each do |section| %>
 ## <%= section.heading %>

 <% section.methods.each do |method| %>
 ### <%== render ViewComponent::DocsBuilderComponent::MethodDoc.new(method) %>

 <% end %>
 <% end %>

All the complexity of the would-be SectionComponent is right here in the DocsBuilderComponent's template. It'd otherwise be two separate files if I were to write an ERB template file. I started writing this discussion thinking the moral of the story would be "if you think you need a new class for some data, don't start with a Struct, start with ViewComponent::Base", but I'm second-guessing that already.

Having mulled this over for a little while, I'm wondering if there'd be a way for call to take an ERB heredoc, similar to how this works:

module ViewComponent
   class DocsBuilderComponent < Base
     class Section < ViewComponent::Base
       def initialize(heading: nil, methods: [], show_types: true)
         @heading = heading
         @show_types = show_types
         @methods = methods.sort_by! { |method| method[:name] }
         super
       end

       def call
         erb = <<~ERB
           ## <%= @heading %>

           <% @methods.each do |method| %>
           ### <%=  render ViewComponent::DocsBuilderComponent::MethodDoc.new(method)  %>

           <% end %>
         ERB
         ERB.new(erb).result(view_context.send(:binding))
       end
     end
  end
end

This has a few perks:

• It'd be useful for cases like these where spacing is important
• It'd be useful for cases where we're not just generating content tags with the tag helper as we would in standard HTML, like the above
• t'd make it easier to write more complex HTML in #call
• It'd make it easier to move the view code out to a document template without needing to rewrite it
• It might have performance benefits over tag helpers
• Syntax highlighters may support it
• It may feel more natural for cases like these where one component is composed of "private" subcomponents (i.e. you'd write them in the same file/namespace because you'd rather not expose them)

It's also got drawbacks:

• It could be argued that since call is often constructed of method calls and string interpolation in pure Ruby, we hold it to the same standards as other methods right now, and might think differently of it with this style
• It doesn't have exact parity with ActionView for ERB syntax, but the binding does provide everything that should be accessible, right down to helpers.
• It puts ERB and pure Ruby in the same file, which might feel uncomfortable for some.

What do folks think of this?

[camertron]

Hey @boardfish, sorry we've taken a long time to respond.

I think putting ERB into Ruby files is a great idea 😄 That's the sort of approach to templating Rux advocates for and what JSX does too. While I would personally prefer to see a transpilation step or even template language support built into Ruby, that's probably a long way off.

I wonder if it makes sense to stop at just supporting inline ERB. What about HAML, Slim, etc? We could have method suffixes like call_erb, call_haml, etc that could automatically invoke the correct template handler.

My only real concern is that people might think they should write all their components this way, which IMHO is a mistake for larger components. It can get pretty overwhelming to look at a 1000+ line render() function in React/JSX, for example.

[boardfish]

Thanks for the feedback! I think it validates hacking on this a little and seeing what can happen. On that last point, I think we could leverage linter rules to encourage folks not to make their call methods longer than some maximum, but I do agree that making this option available at all opens up that possibility.