lustre-labs / lustre

An Elm-inspired framework for building HTML templates, single page applications, and server-rendered components in Gleam!
https://hexdocs.pm/lustre
MIT License
727 stars 52 forks source link

DOCS: Clarify how to access the JSON payload from `effect.event` #143

Closed greymour closed 2 weeks ago

greymour commented 2 weeks ago

While working with effect.event I couldn't remember how to access the JSON encoded payload from the emitted event (I had been smoking a LOT of weed so my recollection was... not what it normally is (I am Canadian, this is perfectly legal)), and the docs don't explicitly state that you can access the payload on the event's detail property; this is in contrast to the documentation for event.emit, which explicitly states this.

For smooth-brained individuals such as myself, I recommend updating the effect.event docs to the following:

/// Emit a custom event from a component as an effect. Parents can listen to these
/// events in their `view` function like any other HTML event.
///
/// You *probably* don't need to use this type of effect if you're not making use
/// of Lustre's components, but in rare cases it may be useful to emit custom
/// events from the DOM node that your Lustre application is mounted to.
///
/// Like `event.emit`, any JSON-serialisable payload can be attached as additional data for any event listeners to
/// decode. This data will be on the event’s `detail` property.
hayleigh-dot-dev commented 2 weeks ago

I've updated the documentation and now this function is @internal and not publicly documented. Users should go through event.emit if they need this effect now! This was actually never really planned as part of the public api it just was because of how gleam worked before the @internal attribute, thanks for pointing it out.