Extra options passthrough for components

LoopComponent now supports an opt‑in mechanism that lets a component accept and forward arbitrary keyword options (e.g., HTML attributes) directly to its rendered tag.

What changed

• Unknown keyword options passed to a component constructor will now:
  • Raise a KeyError by default (same as before, explicit-by-default)
  • Be collected into extra_options if the component explicitly opts in
• Components opt in by calling use_extra_options in the class body.
• When opted in, any arguments that are not defined via Dry::Initializer are captured and exposed as extra_options for use in the template.

How to opt in

class LooposUi::Link < LoopComponent
  # define your normal options
  option :url, Types::String
  option :data, default: -> { {} }, type: Types::Hash
  # opt in to passthrough
  use_extra_options
end

How to use in templates

Inside the ERB template, you can forward the collected options to the tag. Basic usage:

<%= tag.a(href: url, data: data, **extra_options) do %%>
  <%= content || url %%>
<% end %%>

Recommended merge pattern

When forwarding extra_options, you may want to merge with component-generated attributes instead of letting extra_options override them. LoopComponent provides deep_merge_args which deep‑merges hashes and concatenates string leaf values (useful for class).

<%
  base_attrs = { class: classes, data: data }
  attrs = deep_merge_args(base_attrs, extra_options)
%%>
<%= tag.a(**attrs) do %%>
  <%= content || url %%>
<% end %%>

• class: strings are concatenated (e.g., component classes + user classes)
• data: hashes are deep‑merged
• Other keys: values from extra_options win where a deep merge is not applicable

Error behavior

• If a component does not call use_extra_options, any unknown keyword arguments will raise:

KeyError: Unknown keys for YourComponent: foo, bar

• If it does call use_extra_options, the same keys will be available in extra_options instead.

Examples in the codebase

• LooposUi::Link opts in and forwards attributes to <a> using **extra_options.
• LooposUi::MIcon opts in and forwards attributes to the chosen tag using **extra_options.

This pattern lets consumers add arbitrary HTML attributes (ARIA, rel, target, title, custom data-*, etc.) while keeping component options explicit and validated.