ViewComponent best practices?

[phil-janeapp]

Hey team! 👋

We're using ViewComponent and Primer (not necessarily basing everything completely on Primer but definitely taking a lot of cues from it). I've been struggling to find a comprehensive list of best practices and am curious if you have a list of guidelines. I'm aware of the list on the ViewComponent website but am also considering some other items, such as:

1. When do you decide what should go in a slot vs. as an argument? I've been leaning towards "if it's content then it belongs in a slot", or "if you would render a list of these then what differs between each?" but I can see that Primer components don't necessarily follow that pattern.
2. Best practices around passing through content to sub-components. Ex: You have a CTA component that renders a Textbox inside it. How do you make it simple to pass a title and description through to the Textbox without necessarily exposing the implementation details that the CTA is rendering that Textbox?

Thank you! ❤️

[camertron]

Hi @phil-janeapp, thanks for asking about this! Glad to hear Primer is useful to you 😄 The ViewComponent website doesn't really talk about specific, in-the-weeds component development, so this is probably the right place to have that conversation.

When do you decide what should go in a slot vs. as an argument?

Great question! IMO there are a couple of things to consider:

1. Markup. Does the option need to accept markup? If so, then it should probably (read: definitely) be a slot. By opting for a slot, you can benefit from all of Rails' HTML sanitization functionality. If you don't use a slot, you'll have to rely on the component's users passing in HTML-safe strings. Of course, non-sanitized slot content can be provided by chaining with_content off the slot method, but hopefully you'll discover any issues arising from that during testing.
2. Sub-components. Slots really shine when you need to render a sub-component, eg. a list item inside a list.
3. API preference. If the option doesn't need to accept markup or render a sub-component, then often it boils down to API preference. Does it "feel" nicer to define an argument or a slot? Up to you.
4. Future needs. If the option might grow in complexity or accept markup in the future, it might be a good idea to use a slot. In my experience, it's easier to convert an argument to a slot than it is to convert a slot to an argument.

Best practices around passing through content to sub-components.

Another great question. In my experience, there are two ways to handle this:

1. System arguments. In a bunch of places in primer_view_components (PVC), we accept system arguments hashes for sub components. You can also accept regular 'ol keyword arguments in CTAComponent and pass them on to your Textbox component, although that's more manual work. In either case, you can massage the arguments as necessary before passing them on to the child component.

   # app/components/cta_component.rb
   class CTAComponent < ApplicationComponent
     def initialize(textbox_arguments:)
       @textbox_arguments = textbox_arguments
     end
   end

   <%# app/components/cta_component.html.erb %>
   <%= render(TextboxComponent.new(**@textbox_arguments)) %>

2. Sub-component rendered via slot. Consider adding a slot for the sub-component. This isn't always possible or desirable, but could be a good way to go. If you're looking to avoid making consumers of your component fill in the slot for every usage, you could consider conditionally rendering the slot if it's defined, falling back to some default:

   <%# Assuming `renders_one :textbox` in the .rb file %>
   <% if textbox? %>
     <%= textbox %>
   <% else %>
     <%= render(TextboxComponent.new(default: "argument")) %>
   <% end %>

[phil-janeapp]

Thanks @camertron!

The "if it accepts HTML it needs to be a slot" is the practice we've definitely leaned towards, and thanks for the additional thoughts around both that question and the question about passing arguments through to sub-components 🙂

From a bigger-picture perspective, do you think it makes sense to provide (either as part of PVC or on the main VC repo) some "generally accepted best practices"?

I know it's not always a great idea to prescribe exactly how things should be done, but I'd be willing to bet there's more developers out there who wouldn't mind some additional guidance from teams who have been using VC for a while and learned some lessons the hard way.

[joelhawksley]

From a bigger-picture perspective, do you think it makes sense to provide (either as part of PVC or on the main VC repo) some "generally accepted best practices"?

@phil-janeapp that was the goal we had in mind with publishing the existing guidance on the VC website. I was cautious of presenting that document as general best practices at the time I wrote it, but I think it's worth revisiting to see if the community would accept it as general guidance.

Would you be up for opening an issue or PR suggesting that reframing? If we made it more general, we could probably include more guidance, including something along the lines of what you've discussed with @camertron here ❤️

[phil-janeapp]

@joelhawksley As I need to be writing this sort of documentation internally for our team anyway, I'll certainly take a try at it 😄

[phil-janeapp]

@joelhawksley I've opened a PR on the main VC repo. Happy to continue the discussion there 🙂