Getting started

Use the provided generator to create a component:

script/make_component my_component_name

To declare a dependency on an npm package, pass js to the generator:

bundle exec thor component_generator my_component_name --js=some-npm-package-name

This command uses the component_generator.thor template to create the necessary starter files, and insert the component into various locations, such as the docs.rake and nav.yaml arrays, which is used to generate documentation.

Slots / Nested Components

Slots can be used to create nested components with strict rules:

renders_one :action, lambda { |tag: :div, classes: "", attributes: {}|
  render(Ariadne::BaseComponent.new(tag: tag, classes: classes, attributes: attributes))
}

<%= render(Ariadne::FlashComponent.new) do |component| %>
  This is a flash message with actions!
  <% component.action do %>
    <%= render(Ariadne::ButtonComponent.new(size: :sm)) { "Take action" } %>
  <% end %>
<% end %>

Please see the ViewComponent documentation for more information.

Tag considerations

Components and slots should restrict which HTML tags they will render. For example, an Image component should never be rendered as an <h1>.

Consider which HTML tags make sense. Components typically fall under one of the following patterns:

1) Fixed tag that cannot be updated by the consumer:

@tag = :h1

2) Allowed list of tags that are set with the tag: argument using the fetch_or_raise helper.

# warn that advised tag is not being used
@tag = check_incoming_tag(TAG_DEFAULT, tag)

# strict list of tags
@tag = fetch_or_raise(TAG_OPTIONS, tag)