Add JS.ignore_attributes (#3765)

* Add `JS.ignore_attributes`

Sometimes it is useful to ignore updates to specific attributes. One
famous example is the "new"-ish HTML `dialog` element that relies on
an `open` attribute to determine if it is open or closed. The same
applies to `details` elements. Importantly, when opened by a user, the
browser sets this attribute by itself and LiveView should not overwrite
it on patches, otherwise it would accidentally close it again.

Previously, the recommended way to handle such cases was to add a function
to the `onBeforeElUpdated` dom option of the `liveSocket`. This is
cumbersome though and especially for libraries leads to more friction, as
more steps are necessary to install them.

Now, one can use `JS.ignore_attributes` in instead, for example:

```heex
<details phx-mounted={JS.ignore_attributes(["open"])}>
  <summary>...</summary>
  ...
</details>
````

And then the details element will always retain the previous open state,
regardless of what the server does.

Relates to: #3741
Relates to: #2349
Relates to: #3574

* add test for wildcard

* accept single attribute

* fix precedence

* add ignoreAttributes to this.js()

Author: SteffenDE

assets/js/phoenix_live_view/js.js

@@ -142,6 +142,10 @@ let JS = {
     this.toggleAttr(el, attr, val1, val2)
   },
 
+  exec_ignore_attrs(e, eventType, phxEvent, view, sourceEl, el, {attrs}){
+    this.ignoreAttrs(el, attrs)
+  },
+
   exec_transition(e, eventType, phxEvent, view, sourceEl, el, {time, transition, blocking}){
     this.addOrRemoveClasses(el, [], [], transition, time, view, blocking)
   },
@@ -166,6 +170,23 @@ let JS = {
     this.setOrRemoveAttrs(el, [], [attr])
   },
 
+  ignoreAttrs(el, attrs){
+    DOM.putPrivate(el, "JS:ignore_attrs", {apply: (fromEl, toEl) => {
+      Array.from(fromEl.attributes).forEach(attr => {
+        if(attrs.some(toIgnore => attr.name == toIgnore || toIgnore.includes("*") && attr.name.match(toIgnore) != null)){
+          toEl.setAttribute(attr.name, attr.value)
+        }
+      })
+    }})
+  },
+
+  onBeforeElUpdated(fromEl, toEl){
+    const ignoreAttrs = DOM.private(fromEl, "JS:ignore_attrs")
+    if(ignoreAttrs){
+      ignoreAttrs.apply(fromEl, toEl)
+    }
+  },
+
   // utils for commands
 
   show(eventType, view, el, display, transition, time, blocking){

assets/js/phoenix_live_view/js_commands.js

@@ -230,6 +230,14 @@ export default (liveSocket, eventType) => {
     patch(href, opts = {}){
       let e = new CustomEvent("phx:exec")
       liveSocket.pushHistoryPatch(e, href, opts.replace ? "replace" : "push", null)
-    }
+    },
+
+    /**
+     * Mark attributes as ignored, skipping them when patching the DOM.
+     * 
+     * @param {HTMLElement} el - The element to toggle the attribute on.
+     * @param {Array<string>|string} attrs - The attribute name or names to ignore.
+     */
+    ignoreAttributes(el, attrs){ JS.ignoreAttrs(el, attrs) }
   }
 }

assets/js/phoenix_live_view/view.js

@@ -504,6 +504,8 @@ export default class View {
     patch.before("updated", (fromEl, toEl) => {
       let hook = this.triggerBeforeUpdateHook(fromEl, toEl)
       if(hook){ updatedHookIds.add(fromEl.id) }
+      // trigger JS specific update logic (for example for JS.ignore_attributes)
+      JS.onBeforeElUpdated(fromEl, toEl)
     })
 
     patch.after("updated", el => {

assets/test/view_test.js

@@ -727,6 +727,71 @@ describe("View + DOM", function(){
       expect(childIds()).toEqual([1])
     })
   })
+
+  describe("JS integration", () => {
+    test("ignore_attributes skips attributes on update", () => {
+      let liveSocket = new LiveSocket("/live", Socket)
+      let el = liveViewDOM()
+      let updateDiff = {
+        "0": " phx-mounted=\"[["ignore_attrs",{"attrs":["open"]}]]\"",
+        "1": "0",
+        "s": [
+          "<details",
+          ">\n    <summary>A</summary>\n    <span>",
+          "</span></details>"
+        ]
+      }
+
+      let view = simulateJoinedView(el, liveSocket)
+      view.applyDiff("update", updateDiff, ({diff, events}) => view.update(diff, events))
+
+      expect(view.el.firstChild.tagName).toBe("DETAILS")
+      expect(view.el.firstChild.open).toBe(false)
+      view.el.firstChild.open = true
+      view.el.firstChild.setAttribute("data-foo", "bar")
+
+      // now update, the HTML patch would normally reset the open attribute
+      view.applyDiff("update", {"1": "1"}, ({diff, events}) => view.update(diff, events))
+      // open is ignored, so it is kept as is
+      expect(view.el.firstChild.open).toBe(true)
+      // foo is not ignored, so it is reset
+      expect(view.el.firstChild.getAttribute("data-foo")).toBe(null)
+      expect(view.el.firstChild.textContent.replace(/\s+/g, "")).toEqual("A1")
+    })
+
+    test("ignore_attributes wildcard", () => {
+      let liveSocket = new LiveSocket("/live", Socket)
+      let el = liveViewDOM()
+      let updateDiff = {
+        "0": " phx-mounted=\"[[&quot;ignore_attrs&quot;,{&quot;attrs&quot;:[&quot;open&quot;,&quot;data-*&quot;]}]]\"",
+        "1": " data-foo=\"foo\" data-bar=\"bar\"",
+        "2": "0",
+        "s": [
+          "<details",
+          "",
+          ">\n    <summary>A</summary>\n    <span>",
+          "</span></details>"
+        ]
+      }
+
+      let view = simulateJoinedView(el, liveSocket)
+      view.applyDiff("update", updateDiff, ({diff, events}) => view.update(diff, events))
+
+      expect(view.el.firstChild.tagName).toBe("DETAILS")
+      expect(view.el.firstChild.open).toBe(false)
+      view.el.firstChild.open = true
+      view.el.firstChild.setAttribute("data-foo", "bar")
+      view.el.firstChild.setAttribute("data-other", "also kept")
+      // apply diff
+      view.applyDiff("update", {"1": "data-foo=\"foo\" data-bar=\"bar\" data-new=\"new\"", "2": "1"}, ({diff, events}) => view.update(diff, events))
+      expect(view.el.firstChild.open).toBe(true)
+      expect(view.el.firstChild.getAttribute("data-foo")).toBe("bar")
+      expect(view.el.firstChild.getAttribute("data-bar")).toBe("bar")
+      expect(view.el.firstChild.getAttribute("data-other")).toBe("also kept")
+      expect(view.el.firstChild.getAttribute("data-new")).toBe("new")
+      expect(view.el.firstChild.textContent.replace(/\s+/g, "")).toEqual("A1")
+    })
+  })
 })
 
 let submitBefore

lib/phoenix_live_view/js.ex

@@ -25,6 +25,7 @@ defmodule Phoenix.LiveView.JS do
     * `set_attribute` - Set an attribute on elements
     * `remove_attribute` - Remove an attribute from elements
     * `toggle_attribute` - Sets or removes element attribute based on attribute presence.
+    * `ignore_attributes` - Marks attributes as ignored, skipping them when patching the DOM.
     * `show` - Show elements, with optional transitions
     * `hide` - Hide elements, with optional transitions
     * `toggle` - Shows or hides elements based on visibility, with optional transitions
@@ -828,6 +829,56 @@ defmodule Phoenix.LiveView.JS do
     put_op(js, "toggle_attr", to: opts[:to], attr: [attr, val1, val2])
   end
 
+  @doc """
+  Mark attributes as ignored, skipping them when patching the DOM.
+
+  Accepts a single attribute name or a list of attribute names.
+  An asterisk `*` can be used as a wildcard.
+
+  Once set, the given attributes will not be patched across LiveView updates.
+  This includes attributes that are removed by the server.
+
+  If you need to "unmark" an attribute, you need to call `ignore_attributes/1` again
+  with an updated list of attributes.
+
+  This is mostly useful in combination with the `phx-mounted` binding, for example:
+
+  ```heex
+  <dialog phx-mounted={JS.ignore_attributes("open")}>
+    ...
+  </dialog>
+  ```
+
+  ## Options
+
+    * `:to` - An optional DOM selector to select the target element.
+      Defaults to the interacted element. See the `DOM selectors`
+      section for details.
+
+  ## Examples
+
+      JS.ignore_attributes(["open", "data-*"], to: "#my-dialog")
+
+  """
+
+  def ignore_attributes(attrs) when is_list(attrs) or is_binary(attrs),
+    do: ignore_attributes(%JS{}, attrs, [])
+
+  def ignore_attributes(attrs, opts) when (is_list(attrs) or is_binary(attrs)) and is_list(opts),
+    do: ignore_attributes(%JS{}, attrs, opts)
+
+  def ignore_attributes(%JS{} = js, attrs, opts)
+      when (is_list(attrs) or is_binary(attrs)) and is_list(opts) do
+    attrs =
+      case attrs do
+        attr when is_binary(attr) -> [attr]
+        attrs when is_list(attrs) -> attrs
+      end
+
+    opts = validate_keys(opts, :ignore_attributes, [:attrs, :to])
+    put_op(js, "ignore_attrs", to: opts[:to], attrs: attrs)
+  end
+
   @doc """
   Sends focus to a selector.
 

test/e2e/support/js_live.ex

@@ -5,7 +5,7 @@ defmodule Phoenix.LiveViewTest.E2E.JsLive do
 
   @impl Phoenix.LiveView
   def mount(_params, _session, socket) do
-    {:ok, socket}
+    {:ok, assign(socket, count: 0)}
   end
 
   @impl Phoenix.LiveView
@@ -36,6 +36,16 @@ defmodule Phoenix.LiveViewTest.E2E.JsLive do
     }>
       toggle modal
     </button>
+
+    <details phx-mounted={JS.ignore_attributes(["open"])}>
+      <summary>Details</summary>
+      <button phx-click="increment">{@count}</button>
+    </details>
     """
   end
+
+  @impl Phoenix.LiveView
+  def handle_event("increment", _params, socket) do
+    {:noreply, update(socket, :count, &(&1 + 1))}
+  end
 end

test/e2e/tests/js.spec.js

@@ -80,3 +80,15 @@ test("set and remove_attribute", async ({page}) => {
   await expect(page.locator("#my-modal")).not.toHaveAttribute("open")
   await expect(page.locator("#my-modal")).toBeHidden()
 })
+
+test("ignore_attributes", async ({page}) => {
+  await page.goto("/js")
+  await syncLV(page)
+  await expect(page.locator("details")).not.toHaveAttribute("open")
+  await page.locator("details").click()
+  await expect(page.locator("details")).toHaveAttribute("open")
+  // without ignore_attributes, the open attribute would be reset to false
+  await page.locator("details button").click()
+  await syncLV(page)
+  await expect(page.locator("details")).toHaveAttribute("open")
+})