phoenix_live_view 1.2.0-rc.3 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # Phoenix LiveView
 
-[![Actions Status](https://github.com/phoenixframework/phoenix_live_view/workflows/CI/badge.svg)](https://github.com/phoenixframework/phoenix_live_view/actions?query=workflow%3ACI) [![Hex.pm](https://img.shields.io/hexpm/v/phoenix_live_view.svg)](https://hex.pm/packages/phoenix_live_view) [![Documentation](https://img.shields.io/badge/documentation-gray)](https://hexdocs.pm/phoenix_live_view)
+[![Actions Status](https://github.com/phoenixframework/phoenix_live_view/workflows/CI/badge.svg)](https://github.com/phoenixframework/phoenix_live_view/actions?query=workflow%3ACI) [![Hex.pm](https://img.shields.io/hexpm/v/phoenix_live_view.svg)](https://hex.pm/packages/phoenix_live_view) [![Documentation](https://img.shields.io/badge/documentation-gray)](https://phoenix-live-view.hexdocs.pm)
 
 Phoenix LiveView enables rich, real-time user experiences with server-rendered HTML.
 
@@ -34,7 +34,7 @@ model while keeping your code closer to your data (and ultimately your source of
 
   * **Diffs over the wire:** Instead of sending "HTML over the wire", LiveView knows exactly which parts of your templates change, sending minimal diffs over the wire after the initial render, reducing latency and bandwidth usage. The client leverages this information and optimizes the browser with 5-10x faster updates, compared to solutions that replace whole HTML fragments.
 
-  * **Live form validation:** LiveView supports real-time form validation out of the box. Create rich user interfaces with features like uploads, nested inputs, and [specialized recovery](https://hexdocs.pm/phoenix_live_view/form-bindings.html#recovery-following-crashes-or-disconnects).
+  * **Live form validation:** LiveView supports real-time form validation out of the box. Create rich user interfaces with features like uploads, nested inputs, and [specialized recovery](https://phoenix-live-view.hexdocs.pm/form-bindings.html#recovery-following-crashes-or-disconnects).
 
   * **File uploads:** Real-time file uploads with progress indicators and image previews. Process your uploads on the fly or submit them to your desired cloud service.
 
@@ -52,9 +52,9 @@ model while keeping your code closer to your data (and ultimately your source of
 
 ## Learning
 
-Check our [comprehensive docs](https://hexdocs.pm/phoenix_live_view) to get started.
+Check our [comprehensive docs](https://phoenix-live-view.hexdocs.pm) to get started.
 
-The Phoenix framework documentation also keeps a list of [community resources](https://hexdocs.pm/phoenix/community.html), including books, videos, and other materials, and some include LiveView too.
+The Phoenix framework documentation also keeps a list of [community resources](https://phoenix.hexdocs.pm/community.html), including books, videos, and other materials, and some include LiveView too.
 
 Also follow these announcements from the Phoenix team on LiveView for more examples and rationale:
 
@@ -103,7 +103,7 @@ which provides quick times for "First Meaningful Paint", in addition to
 helping search and indexing engines.
 
 Then LiveView uses a persistent connection between client and server.
-This allows LiveView applications to react faster to user events as
+This allows LiveView applications to react faster to user events, as
 there is less work to be done and less data to be sent compared to
 stateless requests that have to authenticate, decode, load, and encode
 data on every request.

package/assets/js/phoenix_live_view/README.md

@@ -1,3 +1,3 @@
 ## LiveView JavaScript Client
 
-This is the documentation for the LiveView JavaScript client. It is a more low-level API documentation for advanced users. For a higher-level overview, [see the page on JavaScript interoperability](https://hexdocs.pm/phoenix_live_view/js-interop.html) instead.
+This is the documentation for the LiveView JavaScript client. It is a more low-level API documentation for advanced users. For a higher-level overview, [see the page on JavaScript interoperability](https://phoenix-live-view.hexdocs.pm/js-interop.html) instead.

package/assets/js/phoenix_live_view/dom.ts

@@ -411,7 +411,9 @@ const DOM = {
             // we also clear the throttle timeout to prevent the callback
             // from being called again after the timeout fires
             clearTimeout(this.private(el, THROTTLED));
-            this.triggerCycle(el, DEBOUNCE_TRIGGER);
+            if (asyncFilter()) {
+              this.triggerCycle(el, DEBOUNCE_TRIGGER);
+            }
           });
         }
     }

package/assets/js/phoenix_live_view/dom_patch.ts

@@ -792,7 +792,7 @@ export default class DOMPatch {
   private transitionPendingRemoves() {
     const { pendingRemoves, liveSocket } = this;
     if (pendingRemoves.length > 0) {
-      liveSocket.transitionRemoves(pendingRemoves, () => {
+      liveSocket.transitionRemoves(pendingRemoves, this.view, () => {
         pendingRemoves.forEach((el) => {
           const child = DOM.firstPhxChild(el);
           if (child) {

package/assets/js/phoenix_live_view/index.ts

@@ -1,9 +1,9 @@
 /*
  * This is the documentation for the LiveView JavaScript client.
  * It is a more low-level API documentation for advanced users.
- * For a higher-level overview, [see the page on JavaScript interoperability](https://hexdocs.pm/phoenix_live_view/js-interop.html) instead.
+ * For a higher-level overview, [see the page on JavaScript interoperability](https://phoenix-live-view.hexdocs.pm/js-interop.html) instead.
  *
- * The main documentation can be found at `https://hexdocs.pm/phoenix_live_view`.
+ * The main documentation can be found at `https://phoenix-live-view.hexdocs.pm`.
  *
  * @packageDocumentation
  */

package/assets/js/phoenix_live_view/live_socket.ts

@@ -92,7 +92,7 @@ export interface LiveSocketOptions {
   /**
    * Callbacks for LiveView hooks.
    *
-   * See [Client hooks via `phx-hook`](https://hexdocs.pm/phoenix_live_view/js-interop.html#client-hooks-via-phx-hook) for more information.
+   * See [Client hooks via `phx-hook`](https://phoenix-live-view.hexdocs.pm/js-interop.html#client-hooks-via-phx-hook) for more information.
    */
   hooks?: HooksOptions;
   /** Callbacks for LiveView uploaders. */
@@ -425,7 +425,7 @@ export default class LiveSocket {
    * Enables debugging.
    *
    * When debugging is enabled, the LiveView client will log debug information to the console.
-   * See [Debugging client events](https://hexdocs.pm/phoenix_live_view/js-interop.html#debugging-client-events) for more information.
+   * See [Debugging client events](https://phoenix-live-view.hexdocs.pm/js-interop.html#debugging-client-events) for more information.
    */
   enableDebug(): void {
     this.sessionStorage.setItem(PHX_LV_DEBUG, "true");
@@ -458,7 +458,7 @@ export default class LiveSocket {
    * Enables latency simulation.
    *
    * When latency simulation is enabled, the LiveView client will add a delay to requests and responses from the server.
-   * See [Simulating Latency](https://hexdocs.pm/phoenix_live_view/js-interop.html#simulating-latency) for more information.
+   * See [Simulating Latency](https://phoenix-live-view.hexdocs.pm/js-interop.html#simulating-latency) for more information.
    */
   enableLatencySim(upperBoundMs: number): void {
     this.enableDebug();
@@ -547,7 +547,7 @@ export default class LiveSocket {
   /**
    * Executes an encoded JS command, targeting the given element.
    *
-   * See [`Phoenix.LiveView.JS`](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.JS.html) for more information.
+   * See [`Phoenix.LiveView.JS`](https://phoenix-live-view.hexdocs.pm/Phoenix.LiveView.JS.html) for more information.
    */
   execJS(
     el: Element,
@@ -562,7 +562,7 @@ export default class LiveSocket {
    * Returns an object with methods to manipulate the DOM and execute JavaScript.
    * The applied changes integrate with server DOM patching.
    *
-   * See [JavaScript interoperability](https://hexdocs.pm/phoenix_live_view/js-interop.html) for more information.
+   * See [JavaScript interoperability](https://phoenix-live-view.hexdocs.pm/js-interop.html) for more information.
    */
   js(): LiveSocketJSCommands {
     return jsCommands(this, "js");
@@ -823,12 +823,15 @@ export default class LiveSocket {
     ).filter((el) => !DOM.isChildOfAny(el, stickies));
 
     const newMainEl = DOM.cloneNode(this.outgoingMainEl, "");
-    this.main.showLoader(this.loaderTimeout);
-    this.main.destroy();
+    const oldMainView = this.main;
+    oldMainView.showLoader(this.loaderTimeout);
+    oldMainView.destroy();
 
     this.main = this.newRootView(newMainEl, flash, liveReferer);
     this.main.setRedirect(href);
-    this.transitionRemoves(removeEls);
+    // the old view is destroyed at this point; pass it explicitly so the
+    // phx-remove commands execute in the context of the outgoing view
+    this.transitionRemoves(removeEls, oldMainView);
     this.main.join((joinCount, onDone) => {
       if (joinCount === 1 && this.commitPendingLink(linkRef)) {
         this.requestDOMUpdate(() => {
@@ -845,7 +848,7 @@ export default class LiveSocket {
   }
 
   /** @internal */
-  transitionRemoves(elements, callback?) {
+  transitionRemoves(elements, view: View, callback?) {
     const removeAttr = this.binding("remove");
     const silenceEvents = (e) => {
       e.preventDefault();
@@ -857,7 +860,8 @@ export default class LiveSocket {
       for (const event of this.boundEventNames) {
         el.addEventListener(event, silenceEvents, true);
       }
-      this.execJS(el, el.getAttribute(removeAttr), "remove");
+      const e = new CustomEvent("phx:exec", { detail: { sourceElement: el } });
+      JS.exec(e, "remove", el.getAttribute(removeAttr), view, el);
     });
     // remove the silenced listeners when transitions are done in case the element is re-used
     // and call caller's callback as soon as we are done with transitions
@@ -885,12 +889,15 @@ export default class LiveSocket {
 
   /** @internal */
   owner(childEl: Element, callback?: (view: View) => any) {
-    let view: View;
+    let view: View | undefined;
     const viewEl = DOM.closestViewEl(childEl);
     if (viewEl) {
-      // it can happen that we find a view that is already destroyed;
-      // in that case we DO NOT want to fallback to the main element
-      view = this.getViewByEl(viewEl);
+      // resolve the view by element identity instead of id; during live
+      // navigation the new view is registered under the same id while the
+      // old DOM is still attached, and events from the old DOM must not be
+      // routed to the new view. A destroyed view removes its element binding,
+      // in which case we DO NOT want to fallback to the main element
+      view = DOM.private(viewEl, "view");
     } else {
       if (!childEl.isConnected) {
         // if the element is not part of the DOM any more

package/assets/js/phoenix_live_view/view.ts

@@ -408,6 +408,7 @@ export default class View {
     if (container) {
       const [tag, attrs] = container;
       this.el = DOM.replaceRootContainer(this.el, tag, attrs);
+      DOM.putPrivate(this.el, "view", this);
     }
     this.childJoins = 0;
     this.joinPending = true;
@@ -516,7 +517,10 @@ export default class View {
     if (!el) {
       throw new Error("unable to find root element for view");
     }
+    // child views are initially bound to an element inside the join HTML
+    // fragment (see onJoinComplete), so the binding must move to the real el
     this.el = el;
+    DOM.putPrivate(this.el, "view", this);
     this.el.setAttribute(PHX_ROOT_ID, this.root.id);
   }
 
@@ -746,6 +750,7 @@ export default class View {
     });
 
     // because we work with a template element, we must manually copy the attributes
+    // and bind the template root to this view,
     // otherwise the owner / target helpers don't work properly
     const rootEl = template.content.firstElementChild!;
     rootEl.id = this.id;
@@ -753,6 +758,7 @@ export default class View {
     rootEl.setAttribute(PHX_SESSION, this.getSession());
     rootEl.setAttribute(PHX_STATIC, this.getStatic() ?? "");
     this.parent && rootEl.setAttribute(PHX_PARENT_ID, this.parent.id);
+    DOM.putPrivate(rootEl, "view", this);
 
     // we go over all form elements in the new HTML for the LV
     // and look for old forms in the `formsForRecovery` object;
@@ -1152,6 +1158,10 @@ export default class View {
   }
 
   onJoinError(resp) {
+    if (resp.events) {
+      this.liveSocket.dispatchEvents(resp.events);
+    }
+
     if (resp.reason === "reload") {
       this.log("error", () => [
         `failed mount with ${resp.status}. Falling back to page reload`,

package/assets/js/phoenix_live_view/view_hook.ts

@@ -84,10 +84,12 @@ export interface HookInterface<E extends HTMLElement = HTMLElement> {
    * Use the {@link pushEvent | promise-returning version} to handle errors.
    *
    * @param event - The event name.
-   * @param payload - The payload to send to the server. Defaults to an empty object.
+   * @param payload - The payload to send to the server. Must be a serializable
+   * value (typically JSON-serializable, depends on the Socket configuration).
+   * Defaults to an empty object.
    * @param onReply - A callback to handle the server's reply.
    */
-  pushEvent(event: string, payload: any, onReply: OnReply): void;
+  pushEvent(event: string, payload: unknown, onReply: OnReply): void;
   /**
    * Pushes an event to the server and returns a Promise that resolves with the server's reply.
    *
@@ -95,10 +97,12 @@ export interface HookInterface<E extends HTMLElement = HTMLElement> {
    * such as a disconnected state, timeout, or the server rejecting the event.
    *
    * @param event - The event name.
-   * @param [payload] - The payload to send to the server. Defaults to an empty object.
+   * @param [payload] - The payload to send to the server. Must be a serializable
+   * value (typically JSON-serializable, depends on the Socket configuration).
+   * Defaults to an empty object.
    * @returns A promise that fulfills or rejects with the server's reply.
    */
-  pushEvent(event: string, payload?: any): Promise<any>;
+  pushEvent(event: string, payload?: unknown): Promise<any>;
 
   /**
    * Pushes a targeted event to the server and invokes a callback with the server's reply.
@@ -115,13 +119,15 @@ export interface HookInterface<E extends HTMLElement = HTMLElement> {
    *
    * @param selectorOrTarget - The selector, element, or CID to target.
    * @param event - The event name.
-   * @param payload - The payload to send to the server. Defaults to an empty object.
+   * @param payload - The payload to send to the server. Must be a serializable
+   * value (typically JSON-serializable, depends on the Socket configuration).
+   * Defaults to an empty object.
    * @param onReply - A callback to handle the server's reply.
    */
   pushEventTo(
     selectorOrTarget: PhxTarget,
     event: string,
-    payload: object,
+    payload: unknown,
     onReply: OnReply,
   ): void;
   /**
@@ -142,13 +148,15 @@ export interface HookInterface<E extends HTMLElement = HTMLElement> {
    *
    * @param selectorOrTarget - The selector, element, or CID to target.
    * @param event - The event name.
-   * @param [payload] - The payload to send to the server. Defaults to an empty object.
+   * @param [payload] - The payload to send to the server. Must be a serializable
+   * value (typically JSON-serializable, depends on the Socket configuration).
+   * Defaults to an empty object.
    * @returns A promise that resolves when the event has been handled by all targets.
    */
   pushEventTo(
     selectorOrTarget: PhxTarget,
     event: string,
-    payload?: object,
+    payload?: unknown,
   ): Promise<PromiseSettledResult<{ reply: any; ref: number }>[]>;
 
   /**
@@ -445,11 +453,11 @@ export class ViewHook<E extends HTMLElement = HTMLElement>
     };
   }
 
-  pushEvent(event: string, payload: any, onReply: OnReply): void;
-  pushEvent(event: string, payload?: any): Promise<any>;
+  pushEvent(event: string, payload: unknown, onReply: OnReply): void;
+  pushEvent(event: string, payload?: unknown): Promise<any>;
   pushEvent(
     event: string,
-    payload?: any,
+    payload?: unknown,
     onReply?: OnReply,
   ): Promise<any> | void {
     const promise = this.__view().pushHookEvent(
@@ -471,18 +479,18 @@ export class ViewHook<E extends HTMLElement = HTMLElement>
   pushEventTo(
     selectorOrTarget: PhxTarget,
     event: string,
-    payload: object,
+    payload: unknown,
     onReply: OnReply,
   ): void;
   pushEventTo(
     selectorOrTarget: PhxTarget,
     event: string,
-    payload?: object,
+    payload?: unknown,
   ): Promise<PromiseSettledResult<{ reply: any; ref: number }>[]>;
   pushEventTo(
     selectorOrTarget: PhxTarget,
     event: string,
-    payload?: object,
+    payload?: unknown,
     onReply?: OnReply,
   ): Promise<PromiseSettledResult<{ reply: any; ref: number }>[]> | void {
     if (onReply === undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phoenix_live_view",
-  "version": "1.2.0-rc.3",
+  "version": "1.2.1",
   "description": "The Phoenix LiveView JavaScript client.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "@babel/preset-env": "7.27.2",
     "@babel/preset-typescript": "^7.27.1",
     "@eslint/js": "^9.29.0",
-    "@playwright/test": "^1.59.1",
+    "@playwright/test": "^1.60.0",
     "@types/jest": "^30.0.0",
     "@types/phoenix": "^1.6.6",
     "css.escape": "^1.5.1",

package/priv/static/phoenix_live_view.cjs.js

@@ -671,7 +671,9 @@ var DOM = {
         if (this.once(el, "bind-debounce")) {
           el.addEventListener("blur", () => {
             clearTimeout(this.private(el, THROTTLED));
-            this.triggerCycle(el, DEBOUNCE_TRIGGER);
+            if (asyncFilter()) {
+              this.triggerCycle(el, DEBOUNCE_TRIGGER);
+            }
           });
         }
     }
@@ -2825,7 +2827,7 @@ var DOMPatch = class {
   transitionPendingRemoves() {
     const { pendingRemoves, liveSocket } = this;
     if (pendingRemoves.length > 0) {
-      liveSocket.transitionRemoves(pendingRemoves, () => {
+      liveSocket.transitionRemoves(pendingRemoves, this.view, () => {
         pendingRemoves.forEach((el) => {
           const child = dom_default.firstPhxChild(el);
           if (child) {
@@ -4453,6 +4455,7 @@ var View = class _View {
     if (container) {
       const [tag, attrs] = container;
       this.el = dom_default.replaceRootContainer(this.el, tag, attrs);
+      dom_default.putPrivate(this.el, "view", this);
     }
     this.childJoins = 0;
     this.joinPending = true;
@@ -4539,6 +4542,7 @@ var View = class _View {
       throw new Error("unable to find root element for view");
     }
     this.el = el;
+    dom_default.putPrivate(this.el, "view", this);
     this.el.setAttribute(PHX_ROOT_ID, this.root.id);
   }
   // this is invoked for dead and live views, so we must filter by
@@ -4727,6 +4731,7 @@ var View = class _View {
     rootEl.setAttribute(PHX_SESSION, this.getSession());
     rootEl.setAttribute(PHX_STATIC, this.getStatic() ?? "");
     this.parent && rootEl.setAttribute(PHX_PARENT_ID, this.parent.id);
+    dom_default.putPrivate(rootEl, "view", this);
     const formsToRecover = (
       // we go over all forms in the new DOM; because this is only the HTML for the current
       // view, we can be sure that all forms are owned by this view:
@@ -5021,6 +5026,9 @@ var View = class _View {
     });
   }
   onJoinError(resp) {
+    if (resp.events) {
+      this.liveSocket.dispatchEvents(resp.events);
+    }
     if (resp.reason === "reload") {
       this.log("error", () => [
         `failed mount with ${resp.status}. Falling back to page reload`,
@@ -6086,7 +6094,7 @@ var LiveSocket = class {
    * Returns the version of the LiveView client.
    */
   version() {
-    return "1.2.0-rc.3";
+    return "1.2.1";
   }
   /**
    * Returns true if profiling is enabled. See {@link enableProfiling} and {@link disableProfiling}.
@@ -6110,7 +6118,7 @@ var LiveSocket = class {
    * Enables debugging.
    *
    * When debugging is enabled, the LiveView client will log debug information to the console.
-   * See [Debugging client events](https://hexdocs.pm/phoenix_live_view/js-interop.html#debugging-client-events) for more information.
+   * See [Debugging client events](https://phoenix-live-view.hexdocs.pm/js-interop.html#debugging-client-events) for more information.
    */
   enableDebug() {
     this.sessionStorage.setItem(PHX_LV_DEBUG, "true");
@@ -6139,7 +6147,7 @@ var LiveSocket = class {
    * Enables latency simulation.
    *
    * When latency simulation is enabled, the LiveView client will add a delay to requests and responses from the server.
-   * See [Simulating Latency](https://hexdocs.pm/phoenix_live_view/js-interop.html#simulating-latency) for more information.
+   * See [Simulating Latency](https://phoenix-live-view.hexdocs.pm/js-interop.html#simulating-latency) for more information.
    */
   enableLatencySim(upperBoundMs) {
     this.enableDebug();
@@ -6214,7 +6222,7 @@ var LiveSocket = class {
   /**
    * Executes an encoded JS command, targeting the given element.
    *
-   * See [`Phoenix.LiveView.JS`](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.JS.html) for more information.
+   * See [`Phoenix.LiveView.JS`](https://phoenix-live-view.hexdocs.pm/Phoenix.LiveView.JS.html) for more information.
    */
   execJS(el, encodedJS, eventType = null) {
     const e = new CustomEvent("phx:exec", { detail: { sourceElement: el } });
@@ -6224,7 +6232,7 @@ var LiveSocket = class {
    * Returns an object with methods to manipulate the DOM and execute JavaScript.
    * The applied changes integrate with server DOM patching.
    *
-   * See [JavaScript interoperability](https://hexdocs.pm/phoenix_live_view/js-interop.html) for more information.
+   * See [JavaScript interoperability](https://phoenix-live-view.hexdocs.pm/js-interop.html) for more information.
    */
   js() {
     return js_commands_default(this, "js");
@@ -6439,11 +6447,12 @@ var LiveSocket = class {
       `[${this.binding("remove")}]`
     ).filter((el) => !dom_default.isChildOfAny(el, stickies));
     const newMainEl = dom_default.cloneNode(this.outgoingMainEl, "");
-    this.main.showLoader(this.loaderTimeout);
-    this.main.destroy();
+    const oldMainView = this.main;
+    oldMainView.showLoader(this.loaderTimeout);
+    oldMainView.destroy();
     this.main = this.newRootView(newMainEl, flash, liveReferer);
     this.main.setRedirect(href);
-    this.transitionRemoves(removeEls);
+    this.transitionRemoves(removeEls, oldMainView);
     this.main.join((joinCount, onDone) => {
       if (joinCount === 1 && this.commitPendingLink(linkRef)) {
         this.requestDOMUpdate(() => {
@@ -6458,7 +6467,7 @@ var LiveSocket = class {
     });
   }
   /** @internal */
-  transitionRemoves(elements, callback) {
+  transitionRemoves(elements, view, callback) {
     const removeAttr = this.binding("remove");
     const silenceEvents = (e) => {
       e.preventDefault();
@@ -6468,7 +6477,8 @@ var LiveSocket = class {
       for (const event of this.boundEventNames) {
         el.addEventListener(event, silenceEvents, true);
       }
-      this.execJS(el, el.getAttribute(removeAttr), "remove");
+      const e = new CustomEvent("phx:exec", { detail: { sourceElement: el } });
+      js_default.exec(e, "remove", el.getAttribute(removeAttr), view, el);
     });
     this.requestDOMUpdate(() => {
       elements.forEach((el) => {
@@ -6494,7 +6504,7 @@ var LiveSocket = class {
     let view;
     const viewEl = dom_default.closestViewEl(childEl);
     if (viewEl) {
-      view = this.getViewByEl(viewEl);
+      view = dom_default.private(viewEl, "view");
     } else {
       if (!childEl.isConnected) {
         return null;