[bensheldon]

This is the second of the PRs I described in #2722: an explicit way to declare that a component receives the _counter / _iteration parameters when rendered as a collection. If/when #2722 merges, I will resolve any conflicts with this PR.

Today, whether a component receives them depends on ViewComponent introspecting its initialize signature. This PR adds an explicit declaration as an alternative to introspection.

My end goal is for the explicit declaration to become the only way to opt into the collection _counter/_iteration feature, with introspection deprecated in a follow-up if/when this PR is accepted.

What it does

Adds counter: and iteration: options to with_collection_parameter, and makes the parameter name optional:

class ProductComponent < ViewComponent::Base
  with_collection_parameter counter: true, iteration: true

  def initialize(product:, product_counter:, product_iteration:)
    ...
  end
end

with_collection_parameter :item, counter: true    # with a custom parameter name
with_collection_parameter counter: false          # never pass it

• counter: and iteration: each take true (always pass), false (never pass), or nil (the default, which keeps today's signature-based behavior so this is backwards compatible).
• Only the arguments you pass are changed, so with_collection_parameter counter: true after with_collection_parameter :item keeps :item.
• Subclasses inherit the settings, the same way they already inherit the collection parameter name.

Other details

• The collections guide now shows the declaration in the counter and iteration examples.
• These options only control which arguments are passed. The missing-collection-parameter and reserved-content checks still read the signature.

[joelhawksley]

@bensheldon to be honest, I'm on the fence about this one. While I can see the argument for adding explicit options here, I have two reservations:

1. This moves us away from convention and toward configuration. I think opting-in via the signature is elegant (and greatly appreciate your PR to improve signature introspection!)
2. I am not a fan of how this approach adds API surface area and exposes more VC internals.

With that in mind, I'm going to close the PR for now. If you have specific cases that do not with with the improved introspection, I'd accept them as evidence for this change.

[bensheldon]

@joelhawksley no worries! that makes sense.

Just to document the issues with method signature detection:

• the arguments have to be explicitly defined. It's not possible to use **options. <-- probably not important.
• there are still some cache invalidation bugs, even with Fix collection counter and iteration detection when forwarded through anonymous arguments #2722. a prepend that changes the method signature doesn't invalidate and calling with_collection_parameter doesn't necessarily invalidate. <-- Imma just propose a fix for that right now.