Make `JS.t()` a public data structure, or json serializable

[rhcarvalho]

Thank you for the PR.

@steffend

You’ll still need to do write it like the following, but you can implement Jason.Encoder by just delegating to to_string and then omit the extra to_string call.

push_event(socket, "do-something", %{data: to_string(JS.add_class("foo"))})

I wouldn’t mind the to_string, but on second thought I realized:

1. The Jason.Encoder implementation would need to assume to_string returns safe JSON to pass it as is instead of encoding as a JSON string; or
2. JavaScript code would need to decode the payload string and then parse it as JSON to turn it into a valid JS command, once again assuming a JS command is valid JSON.

In this case, @LostKobrakai’s suggestion seems like a better contract. JS.to_json would naturally appear in HexDocs at the right context (module docs), be more discoverable through search, and imply JSON compatibility.

---

Copying from Animating list items with LiveView streams - #6 by rhcarvalho to bring a concise use case as example, both Elixir and JavaScript side:

@rhcarvalho

A more generic listener could even exec any set of JS commands stored in an attribute (or sent along the event payload):

window.addEventListener("phx:exec", event => {
  const el = document.querySelector(event.detail.selector);
  if (!el) return;
  liveSocket.execJS(el, event.detail.js || el.getAttribute(event.detail.attr));
});

On the server side:

<div
  id={@id}
  data-phx-show={JS.transition({"ease-out duration-200", "opacity-0 scale-95", "opacity-100 scale-100"})}
>...</div>

    socket
    |> push_event("exec", %{
      "selector" => "#urls-#{url.id}",
      "attr" => "data-phx-show"
    })

Or (see Make JS.t() a public data structure, or json serializable):

    socket
    |> push_event("exec", %{
      "selector" => "#urls-#{url.id}",
      "js" =>
        JS.transition({"ease-out duration-200", "opacity-0 scale-95", "opacity-100 scale-100"}).ops
        |> JSON.encode!()
    })

So, @steffend, if we write JS.transition(...) |> to_string() we’d end up with a string in the JS event handler, not a deeply nested list which is a valid JS command. Either JS code would need to call JSON.parse(payload_str), or server code needs to assume the result from to_string is valid JSON as-is (which would be undocumented behavior).