Support pushing JS commands via events (#4060)

* Add JS.to_encodable/1 function for pushing JS commands via events

The new `JS.to_encodable/1` function transforms the
`Phoenix.LiveView.JS` struct into an opaque JSON-serializable value,
such that it can be transmitted outside of HEEx templates.

See discussion https://elixirforum.com/t/make-js-t-a-public-data-structure-or-json-serializable/53870?u=rhcarvalho.

* Conditionally implement Jason.Encoder and JSON.Encoder for Phoenix.LiveView.JS

Makes it more convenient to use JS commands in `push_event` payloads.

* Reword `JS.to_encodable/1` doc

- No need to link to hexdocs.pm, ExDoc will do that automatically
- Use the same wording as Phoenix, "JSON library" instead of "JSON encoder"
- More concise wording

* Add to_encodable/1 tests

* Add Jason.Encoder and JSON.Encoder tests

* Simplify js.exec test

1. Remove done callback, which is meant to be used with
   callbacks/asynchronous code.

https://jestjs.io/docs/asynchronous#callbacks

2. Use jest.runAllTimers(), reflecting typical usage when we don't care
   about intermediate timer states.

https://jestjs.io/docs/jest-object#jestrunalltimers
https://jestjs.io/docs/jest-object#jestadvancetimersbytimemstorun

* Add JS test coverage for execJS, js().exec and hook.js().exec

* Conditionally define JSON.Encoder test

To avoid warnings on older Elixir versions where JSON.Encoder is not
available.

When the JSON module is not available, we define a skipped test with
the same name for visibility in test reports.

Author: rhcarvalho

assets/js/phoenix_live_view/index.ts

@@ -12,7 +12,7 @@ import { ViewHook } from "./view_hook";
 import View from "./view";
 import { logError } from "./utils";
 
-import type { LiveSocketJSCommands } from "./js_commands";
+import type { EncodedJS, LiveSocketJSCommands } from "./js_commands";
 import type { Hook, HooksOptions } from "./view_hook";
 import type { Socket as PhoenixSocket } from "phoenix";
 
@@ -266,7 +266,11 @@ export interface LiveSocketInstanceInterface {
    *
    * See [`Phoenix.LiveView.JS`](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.JS.html) for more information.
    */
-  execJS(el: HTMLElement, encodedJS: string, eventType?: string | null): void;
+  execJS(
+    el: HTMLElement,
+    encodedJS: EncodedJS,
+    eventType?: string | null,
+  ): void;
   /**
    * Returns an object with methods to manipulate the DOM and execute JavaScript.
    * The applied changes integrate with server DOM patching.

assets/js/phoenix_live_view/js.js

@@ -11,8 +11,9 @@ const JS = {
       null,
       { callback: defaults && defaults.callback },
     ];
-    const commands =
-      phxEvent.charAt(0) === "["
+    const commands = Array.isArray(phxEvent)
+      ? phxEvent
+      : typeof phxEvent === "string" && phxEvent.startsWith("[")
         ? JSON.parse(phxEvent)
         : [[defaultKind, defaultArgs]];
 

assets/js/phoenix_live_view/js_commands.ts

@@ -1,6 +1,15 @@
 import JS from "./js";
 import LiveSocket from "./live_socket";
 
+/**
+ * An encoded JS command. Use functions in the `Phoenix.LiveView.JS` module on
+ * the server to create and compose JS commands.
+ *
+ * The underlying primitive type is considered opaque, and may change in future
+ * versions.
+ */
+export type EncodedJS = string | Array<any>;
+
 type Transition = string | string[];
 
 // Base options for commands involving transitions and timing
@@ -76,13 +85,13 @@ type NavigationOpts = {
  */
 interface AllJSCommands {
   /**
-   * Executes encoded JavaScript in the context of the element.
+   * Executes an encoded JS command in the context of an element.
    * This version is for general use via liveSocket.js().
    *
-   * @param el - The element in whose context to execute the JavaScript.
-   * @param encodedJS - The encoded JavaScript string to execute.
+   * @param el - The element in whose context to execute the JS command.
+   * @param encodedJS - The encoded JS command with operations to execute.
    */
-  exec(el: HTMLElement, encodedJS: string): void;
+  exec(el: HTMLElement, encodedJS: EncodedJS): void;
 
   /**
    * Shows an element.
@@ -382,9 +391,9 @@ export type LiveSocketJSCommands = AllJSCommands;
  */
 export interface HookJSCommands extends Omit<AllJSCommands, "exec"> {
   /**
-   * Executes encoded JavaScript in the context of the hook's element.
+   * Executes a JS command in the context of the hook's element.
    *
-   * @param {string} encodedJS - The encoded JavaScript string to execute.
+   * @param encodedJS - The encoded JS command with operations to execute.
    */
-  exec(encodedJS: string): void;
+  exec(encodedJS: EncodedJS): void;
 }

assets/js/phoenix_live_view/view_hook.ts

@@ -1,4 +1,4 @@
-import jsCommands, { HookJSCommands } from "./js_commands";
+import jsCommands, { EncodedJS, HookJSCommands } from "./js_commands";
 import DOM from "./dom";
 import LiveSocket from "./live_socket";
 import View from "./view";
@@ -380,7 +380,7 @@ export class ViewHook<E extends HTMLElement = HTMLElement>
   js(): HookJSCommands {
     return {
       ...jsCommands(this.__view().liveSocket, "hook"),
-      exec: (encodedJS: string) => {
+      exec: (encodedJS: EncodedJS) => {
         this.__view().liveSocket.execJS(this.el, encodedJS, "hook");
       },
     };

assets/test/js_test.ts

@@ -38,13 +38,20 @@ describe("JS", () => {
       js = hook.js();
     });
 
-    test("exec", (done) => {
+    test("exec", () => {
       simulateVisibility(modal);
       expect(modal.style.display).toBe("");
       js.exec('[["toggle", {"to": "#modal"}]]');
-      jest.advanceTimersByTime(100);
+      jest.runAllTimers();
+      expect(modal.style.display).toBe("none");
+    });
+
+    test("exec with command array", () => {
+      simulateVisibility(modal);
+      expect(modal.style.display).toBe("");
+      js.exec([["toggle", { to: "#modal" }]]);
+      jest.runAllTimers();
       expect(modal.style.display).toBe("none");
-      done();
     });
 
     test("show and hide", (done) => {
@@ -1147,6 +1154,19 @@ describe("JS", () => {
       JS.exec(event, "exec", click.getAttribute("phx-click"), view, click);
     });
 
+    test("with command array", (done) => {
+      const view = setupView(`
+      <div id="modal" phx-remove='[["push", {"event": "clicked"}]]'>modal</div>
+      `);
+      const modal = document.querySelector("#modal")!;
+      view.pushEvent = (eventType, sourceEl, targetCtx, event, _meta) => {
+        expect(eventType).toBe("exec");
+        expect(event).toBe("clicked");
+        done();
+      };
+      JS.exec(event, "exec", [["exec", { attr: "phx-remove" }]], view, modal);
+    });
+
     test("with no selector", () => {
       const view = setupView(`
       <div

assets/test/live_socket_test.ts

@@ -241,6 +241,58 @@ describe("LiveSocket", () => {
     // liveSocket constructor reads nav history position from sessionStorage
     expect(getItemCalls).toEqual(2);
   });
+
+  describe("execJS", () => {
+    let view, liveSocket;
+
+    beforeEach(() => {
+      global.document.body.innerHTML = "";
+      prepareLiveViewDOM(global.document);
+      jest.useFakeTimers();
+
+      liveSocket = new LiveSocket("/live", Socket);
+      view = simulateJoinedView(
+        document.getElementById("container1"),
+        liveSocket,
+      );
+    });
+
+    afterEach(() => {
+      liveSocket && liveSocket.destroyAllViews();
+      liveSocket = null;
+      jest.useRealTimers();
+    });
+
+    afterAll(() => {
+      global.document.body.innerHTML = "";
+    });
+
+    test("accepts JSON-encoded command string", () => {
+      const el = document.createElement("div");
+      el.setAttribute("id", "test-exec");
+      el.setAttribute(
+        "data-test",
+        '[["toggle_attr", {"attr": ["open", "true"]}]]',
+      );
+      view.el.appendChild(el);
+
+      expect(el.getAttribute("open")).toBeNull();
+      liveSocket.execJS(el, el.getAttribute("data-test"));
+      jest.runAllTimers();
+      expect(el.getAttribute("open")).toEqual("true");
+    });
+
+    test("accepts command array", () => {
+      const el = document.createElement("div");
+      el.setAttribute("id", "test-exec-array");
+      view.el.appendChild(el);
+
+      expect(el.getAttribute("open")).toBeNull();
+      liveSocket.execJS(el, [["toggle_attr", { attr: ["open", "true"] }]]);
+      jest.runAllTimers();
+      expect(el.getAttribute("open")).toEqual("true");
+    });
+  });
 });
 
 describe("liveSocket.js()", () => {
@@ -284,6 +336,17 @@ describe("liveSocket.js()", () => {
     expect(el.getAttribute("open")).toEqual("true");
   });
 
+  test("exec with command array", () => {
+    const el = document.createElement("div");
+    el.setAttribute("id", "test-exec-array");
+    view.el.appendChild(el);
+
+    expect(el.getAttribute("open")).toBeNull();
+    js.exec(el, [["toggle_attr", { attr: ["open", "true"] }]]);
+    jest.runAllTimers();
+    expect(el.getAttribute("open")).toEqual("true");
+  });
+
   test("show and hide", (done) => {
     const el = document.createElement("div");
     el.setAttribute("id", "test-visibility");

guides/client/js-interop.md

@@ -34,8 +34,8 @@ The `liveSocket` instance exposes the following methods:
 - `disableDebug()` -  turns off debug logging
 - `enableLatencySim(milliseconds)` - turns on latency simulation, see [Simulating latency](#simulating-latency)
 - `disableLatencySim()` - turns off latency simulation
-- `execJS(el, encodedJS)` - executes encoded JavaScript in the context of the element
-- `js()` - returns an object with methods to manipulate the DOM and execute JavaScript. The applied changes integrate with server DOM patching. See [JS commands](#js-commands).
+- `execJS(el, encodedJS)` - executes encoded JS command in the context of the element
+- `js()` - returns an object with methods to manipulate the DOM and execute JS commands. The applied changes integrate with server DOM patching. See [JS commands](#js-commands).
 
 ## Debugging client events
 
@@ -477,5 +477,5 @@ The command interface returned by `js()` above offers the following functions:
 - `push(el, type, opts = {})` - pushes an event to the server. To target a LiveComponent by its ID, pass a separate `target` in the options. Options: `target`, `loading`, `page_loading`, `value`. For more details, see `Phoenix.LiveView.JS.push/1`.
 - `navigate(href, opts = {})` - sends a navigation event to the server and updates the browser's pushState history. Options: `replace`. For more details, see `Phoenix.LiveView.JS.navigate/1`.
 - `patch(href, opts = {})` - sends a patch event to the server and updates the browser's pushState history. Options: `replace`. For more details, see `Phoenix.LiveView.JS.patch/1`.
-- `exec(encodedJS)` - *only via Client hook `this.js()`*: executes encoded JavaScript in the context of the hook's root node. The encoded JS command should be constructed via `Phoenix.LiveView.JS` and is usually stored as an HTML attribute. Example: `this.js().exec(this.el.getAttribute('phx-remove'))`.
-- `exec(el, encodedJS)` - *only via `liveSocket.js()`*: executes encoded JavaScript in the context of any element.
+- `exec(encodedJS)` - *only via Client hook `this.js()`*: executes encoded JS command in the context of the hook's root node. The encoded JS command should be constructed via `Phoenix.LiveView.JS` and is usually stored as an HTML attribute. Example: `this.js().exec(this.el.getAttribute('phx-remove'))`.
+- `exec(el, encodedJS)` - *only via `liveSocket.js()`*: executes encoded JS command in the context of any element.

lib/phoenix_live_view/js.ex

@@ -218,10 +218,120 @@ defmodule Phoenix.LiveView.JS do
 
   defimpl Phoenix.HTML.Safe, for: Phoenix.LiveView.JS do
     def to_iodata(%Phoenix.LiveView.JS{} = js) do
-      Phoenix.HTML.Engine.html_escape(Phoenix.json_library().encode!(js.ops))
+      js
+      |> JS.to_encodable()
+      |> Phoenix.json_library().encode!()
+      |> Phoenix.HTML.Engine.html_escape()
     end
   end
 
+  if Code.ensure_loaded?(Jason.Encoder) do
+    defimpl Jason.Encoder, for: Phoenix.LiveView.JS do
+      def encode(%Phoenix.LiveView.JS{} = js, opts) do
+        Jason.Encode.list(JS.to_encodable(js), opts)
+      end
+    end
+  end
+
+  if Code.ensure_loaded?(JSON.Encoder) do
+    defimpl JSON.Encoder, for: Phoenix.LiveView.JS do
+      def encode(%Phoenix.LiveView.JS{} = js, encoder) do
+        JSON.Encoder.encode(JS.to_encodable(js), encoder)
+      end
+    end
+  end
+
+  @doc ~S"""
+  Returns a JSON-encodable opaque intermediate representation of the JS command.
+
+  Most of the time you will not need to call this function directly, as
+  JS commands are automatically encoded where they are typically used: in
+  [HEEx templates](assigns-eex.md) or within the payload of
+  `Phoenix.LiveView.push_event/3`.
+
+  This function is useful when you use a custom JSON library. JS commands
+  implement the `Jason.Encoder` and `JSON.Encoder` protocols, such that they
+  are automatically encoded when you use either of those JSON libraries.
+
+  ## Examples
+
+  On the server, dynamically compute some JS commands and push them to the
+  client:
+
+  ```elixir
+  socket
+  |> push_event("myapp:exec_js", %{
+    to: "#items-#{item.id}",
+    js: js_commands_for(item) |> JS.to_encodable()
+  })
+  ```
+
+  > #### Automatic encoding {: .tip}
+  >
+  > Note that you don't need to call `to_encodable/1` if you are using `Jason` or
+  > `JSON`, instead you can pass the JS commands directly:
+  >
+  > ```elixir
+  > socket
+  > |> push_event("myapp:exec_js", %{
+  >   to: "#items-#{item.id}",
+  >   js: JS.show()
+  > })
+  > ```
+
+  On the client, handle the event and execute the commands:
+
+  ```javascript
+  window.addEventListener("phx:myapp:exec_js", e => {
+    const {to, js} = e.detail;
+    const el = document.querySelector(to);
+    if (el && js) {
+      window.liveSocket.execJS(el, js);
+    }
+  });
+  ```
+
+  The common case, though, is having the JS commands stored in an HTML attribute
+  (`phx-*` or `data-*`), such that client-side JavaScript can refer to them
+  later. For example, in a LiveView template:
+
+  ```heex
+  <div id={"items-#{item.id}"} data-js={JS.show()}>
+    Hello!
+  </div>
+  ```
+
+  Now the server can push an event that refers to the `data-js` attribute:
+
+  ```elixir
+  socket
+  |> push_event("myapp:exec_attr", %{
+    to: "#items-#{item.id}",
+    attr: "data-js"
+  })
+  ```
+
+  Finally, on the client, you can read and execute the commands:
+
+  ```javascript
+  window.addEventListener("phx:myapp:exec_attr", e => {
+    const {to, attr} = e.detail;
+    const el = document.querySelector(to);
+    const js = el && attr && el.getAttribute(attr);
+    if (el && js) {
+      window.liveSocket.execJS(el, js);
+    }
+  });
+  ```
+
+  Note how in the code above we didn't need to encode JS commands explicitly,
+  nor to pass them in the event payload, thanks to rendering them in the
+  template.
+
+  """
+  @spec to_encodable(js :: JS.t()) :: internal()
+  def to_encodable(%JS{} = js), do: js.ops
+
   @doc """
   Pushes an event to the server.