Support custom Action Options

[seanpdoyle]

As a follow-up to hotwired/stimulus#535 and
hotwired/stimulus#546, add support for declaring custom action
modifiers in the same style as :prevent, :stop, and :self.

Take, for example, the toggle event. It's dispatched whenever a
<details> element toggles either open or closed. If an application
were able to declare a custom open modifier, it could choose to route
toggle events denoted with :open only when the <details open>.
Inversely, they could choose to route toggle events denoted with
:!open only when the <details> does not have [open].

Similarly, the same kind of customization could apply to custom events.
For example, the turbo:submit-end fires after a <form>
element submits, but does not distinguish between success or failure. A
:success modifier could skip events with an unsuccessful HTTP response
code.

Preview of changes to the Actions documentation page:

You can register your own action options with the Application.registerActionOption method.

For example, consider that a <details> element will dispatch a toggle
event whenever it's toggled. A custom :open action option would help
to route events whenever the element is toggled open:

import { Application } from "@hotwired/stimulus"

const application = Application.start()

application.registerActionOption("open", ({ event }) => {
  if (event.type == "toggle") {
    return event.target.open == true
  } else {
    return true
  }
})

Similarly, a custom :!open action option could route events whenever the
element is toggled closed. Declaring the action descriptor option with a !
prefix will yield a value argument set to false in the callback:

import { Application } from "@hotwired/stimulus"

const application = Application.start()

application.registerActionOption("open", ({ event, value }) => {
  if (event.type == "toggle") {
    return event.target.open == value
  } else {
    return true
  }
})

In order to prevent the event from being routed to the controller action, the
registerActionOption callback function must return false. Otherwise, to
route the event to the controller action, return true.

The callback accepts a single object argument with the following keys:

Name	Description
name	String: The option's name ("open" in the example above)
value	Boolean: The value of the option (:open would yield true, :!open would yield false)
event	Event: The event instance
element	Element: The element where the action descriptor is declared

[dhh]

Love it! And I actually love the two examples you're giving enough that I think they're worth adding as defaults too.

[seb-jean]

Thank you for this PR.

How could we do with a dialog element to add a custom :open action?