docs: /reference/rocket does not document how to invoke a registered action from outside the element (dispatchRocketAction)

[sei-shigeo]

Docs: /reference/rocket does not document how to invoke a registered action from outside the element

Summary

/reference/rocket documents how to register a local action via action(name, fn) and how to call it from inside the rendered markup (e.g. data-on:click="@copy()"), but it does not document how an external script or button calls a registered action on a Rocket element.

The bundle exposes a dispatchRocketAction(name, ...args) method on each Rocket custom element instance, but there is no reference page describing this API.

Current state of the docs

The Setup Context helpers table on /reference/rocket lists action(name, fn) as:

"Registers a local action callable from rendered markup."

There is no example of a button outside the component invoking action, nor any mention of dispatchRocketAction or the customElements.whenDefined(...) pattern needed when calling before the element has upgraded.

What the bundle actually exposes (v1.0.1)

Searching the v1.0.1 Pro bundle for dispatchRocketAction yields:

class x extends HTMLElement {
  // ...
  dispatchRocketAction(f, h, S, R, ...k) {
    let T = this.#g.get(f);
    if (T) return T({ host: this, props: this.#r, state: this.#i, el: h, evt: S }, ...k);
    // bubbles to parent Rocket, falls back to global action, throws Error("Undefined Rocket action: ...")
  }
}

So the only supported way to call a registered action from outside is:

document.querySelector('my-component').dispatchRocketAction('reset')

And before the element has upgraded:

customElements.whenDefined('my-component').then(() => {
  document.querySelector('my-component').dispatchRocketAction('reset')
})

Suggested doc additions on /reference/rocket

1. After the action(name, fn) row in the Setup Context table, add a sub-section titled "Invoking actions from outside the component" with the dispatchRocketAction example above.
2. Note the upgrade-timing pitfall: calling dispatchRocketAction before customElements.define has registered the tag throws TypeError: dispatchRocketAction is not a function. Show the whenDefined recipe.
3. Cross-link from the /examples/rocket_* examples that rely on external action invocation (e.g. file-list / counter resets in third-party demos).

Context

This came up while implementing a Rocket component in a learning project; the data-on:click="@actionName()" style is well-documented, but external invocation took several rounds of bundle inspection to figure out. Memory of the pattern is now in our project notes, but it would be helpful for newcomers if it were on the reference page.

[bencroker]

Actions defined in Rocket components are local to the components, meaning that they should never be called from outside. Follow the “props down, events up” approach and let the component handle prop changes accordingly. Or, if it makes more sense, add an event listener to the component that triggers a local action.