phoenix_live_view 1.1.30 → 1.2.0-rc.1

package/assets/js/phoenix_live_view/constants.js

@@ -85,6 +85,7 @@ export const PHX_LV_PID = "data-phx-pid";
 export const PHX_KEY = "key";
 export const PHX_PRIVATE = "phxPrivate";
 export const PHX_AUTO_RECOVER = "auto-recover";
+export const PHX_NO_UNUSED_FIELD = "no-unused-field";
 export const PHX_LV_DEBUG = "phx:live-socket:debug";
 export const PHX_LV_PROFILE = "phx:live-socket:profiling";
 export const PHX_LV_LATENCY_SIM = "phx:live-socket:latency-sim";

package/assets/js/phoenix_live_view/hooks.js

@@ -46,10 +46,8 @@ const Hooks = {
       this.inputEl = document.getElementById(
         this.el.getAttribute(PHX_UPLOAD_REF),
       );
-      LiveUploader.getEntryDataURL(this.inputEl, this.ref, (url) => {
-        this.url = url;
-        this.el.src = url;
-      });
+      this.url = LiveUploader.getEntryDataURL(this.inputEl, this.ref);
+      this.el.src = this.url;
     },
     destroyed() {
       URL.revokeObjectURL(this.url);
@@ -264,7 +262,7 @@ Hooks.InfiniteScroll = {
   updated() {
     // Check if the scroll container still exists
     // https://github.com/phoenixframework/phoenix_live_view/issues/4169.
-    if (this.scrollContainer && !this.scrollContainer.isConnected) {
+    if (!this.scrollContainer.isConnected) {
       this.destroyed();
       this.mounted();
     }

package/assets/js/phoenix_live_view/index.ts

@@ -12,9 +12,10 @@ 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";
+import LiveUploader from "./live_uploader";
 
 /**
  * Options for configuring the LiveSocket instance.
@@ -266,7 +267,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.
@@ -346,4 +351,32 @@ function createHook(el: HTMLElement, callbacks: Hook): ViewHook {
   return hook;
 }
 
-export { LiveSocket, isUsedInput, createHook, ViewHook, Hook, HooksOptions };
+/** Returns an object URL for the file matching the given upload ref,
+ * or `null` if no matching file is found.
+ *
+ * @param input - The file input element associated with the upload.
+ * @param uploadRef - The upload ref identifying the file entry.
+ *
+ * @example
+ *
+ * import { getFileURLForUpload } from "phoenix_live_view"
+ *
+ * let url = getFileURLForUpload(inputEl, uploadRef)
+ * if (url) { imgEl.src = url }
+ */
+function getFileURLForUpload(
+  input: HTMLElement,
+  uploadRef: string,
+): string | null {
+  return LiveUploader.getEntryDataURL(input, uploadRef);
+}
+
+export {
+  LiveSocket,
+  isUsedInput,
+  createHook,
+  ViewHook,
+  Hook,
+  HooksOptions,
+  getFileURLForUpload,
+};

package/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]];
 

package/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;
 }

package/assets/js/phoenix_live_view/live_socket.js

@@ -224,7 +224,7 @@ export default class LiveSocket {
 
   /**
    * @param {HTMLElement} el
-   * @param {string} encodedJS
+   * @param {import("./js_commands").EncodedJS} encodedJS
    * @param {string | null} [eventType]
    */
   execJS(el, encodedJS, eventType = null) {

package/assets/js/phoenix_live_view/live_uploader.js

@@ -22,11 +22,12 @@ export default class LiveUploader {
     }
   }
 
-  static getEntryDataURL(inputEl, ref, callback) {
+  static getEntryDataURL(inputEl, ref) {
     const file = this.activeFiles(inputEl).find(
       (file) => this.genFileRef(file) === ref,
     );
-    callback(URL.createObjectURL(file));
+    if (!file) return null;
+    return URL.createObjectURL(file);
   }
 
   static hasUploadsInProgress(formEl) {

package/assets/js/phoenix_live_view/view.js

@@ -38,6 +38,7 @@ import {
   PHX_VIEWPORT_BOTTOM,
   MAX_CHILD_JOIN_ATTEMPTS,
   PHX_LV_PID,
+  PHX_NO_UNUSED_FIELD,
   PHX_PORTAL,
   PHX_TELEPORTED_REF,
   PHX_TELEPORTED_SRC,
@@ -77,90 +78,6 @@ export const prependFormDataKey = (key, prefix) => {
   return baseKey;
 };
 
-const serializeForm = (form, opts, onlyNames = []) => {
-  const { submitter } = opts;
-
-  // We must inject the submitter in the order that it exists in the DOM
-  // relative to other inputs. For example, for checkbox groups, the order must be maintained.
-  let injectedElement;
-  if (submitter && submitter.name) {
-    const input = document.createElement("input");
-    input.type = "hidden";
-    // set the form attribute if the submitter has one;
-    // this can happen if the element is outside the actual form element
-    const formId = submitter.getAttribute("form");
-    if (formId) {
-      input.setAttribute("form", formId);
-    }
-    input.name = submitter.name;
-    input.value = submitter.value;
-    submitter.parentElement.insertBefore(input, submitter);
-    injectedElement = input;
-  }
-
-  const formData = new FormData(form);
-  const toRemove = [];
-
-  formData.forEach((val, key, _index) => {
-    if (val instanceof File) {
-      toRemove.push(key);
-    }
-  });
-
-  // Cleanup after building fileData
-  toRemove.forEach((key) => formData.delete(key));
-
-  const params = new URLSearchParams();
-
-  const { inputsUnused, onlyHiddenInputs } = Array.from(form.elements).reduce(
-    (acc, input) => {
-      const { inputsUnused, onlyHiddenInputs } = acc;
-      const key = input.name;
-      if (!key) {
-        return acc;
-      }
-
-      if (inputsUnused[key] === undefined) {
-        inputsUnused[key] = true;
-      }
-      if (onlyHiddenInputs[key] === undefined) {
-        onlyHiddenInputs[key] = true;
-      }
-
-      const isUsed =
-        DOM.private(input, PHX_HAS_FOCUSED) ||
-        DOM.private(input, PHX_HAS_SUBMITTED);
-      const isHidden = input.type === "hidden";
-      inputsUnused[key] = inputsUnused[key] && !isUsed;
-      onlyHiddenInputs[key] = onlyHiddenInputs[key] && isHidden;
-
-      return acc;
-    },
-    { inputsUnused: {}, onlyHiddenInputs: {} },
-  );
-
-  for (const [key, val] of formData.entries()) {
-    if (onlyNames.length === 0 || onlyNames.indexOf(key) >= 0) {
-      const isUnused = inputsUnused[key];
-      const hidden = onlyHiddenInputs[key];
-      if (isUnused && !(submitter && submitter.name == key) && !hidden) {
-        params.append(prependFormDataKey(key, "_unused_"), "");
-      }
-      if (typeof val === "string") {
-        params.append(key, val);
-      }
-    }
-  }
-
-  // remove the injected element again
-  // (it would be removed by the next dom patch anyway, but this is cleaner)
-  if (submitter && injectedElement) {
-    submitter.parentElement.removeChild(injectedElement);
-  }
-
-  return params.toString();
-};
-
 export default class View {
   static closestView(el) {
     const liveViewEl = el.closest(PHX_VIEW_SELECTOR);
@@ -1666,6 +1583,107 @@ export default class View {
     return meta;
   }
 
+  serializeForm(form, opts, onlyNames = []) {
+    const { submitter } = opts;
+
+    // We must inject the submitter in the order that it exists in the DOM
+    // relative to other inputs. For example, for checkbox groups, the order must be maintained.
+    let injectedElement;
+    if (submitter && submitter.name) {
+      const input = document.createElement("input");
+      input.type = "hidden";
+      // set the form attribute if the submitter has one;
+      // this can happen if the element is outside the actual form element
+      const formId = submitter.getAttribute("form");
+      if (formId) {
+        input.setAttribute("form", formId);
+      }
+      input.name = submitter.name;
+      input.value = submitter.value;
+      submitter.parentElement.insertBefore(input, submitter);
+      injectedElement = input;
+    }
+
+    const formData = new FormData(form);
+    const toRemove = [];
+
+    formData.forEach((val, key, _index) => {
+      if (val instanceof File) {
+        toRemove.push(key);
+      }
+    });
+
+    // Cleanup after building fileData
+    toRemove.forEach((key) => formData.delete(key));
+
+    const params = new URLSearchParams();
+
+    const { inputsUnused, onlyHiddenInputs } = Array.from(form.elements).reduce(
+      (acc, input) => {
+        const { inputsUnused, onlyHiddenInputs } = acc;
+        const key = input.name;
+        if (!key) {
+          return acc;
+        }
+
+        if (inputsUnused[key] === undefined) {
+          inputsUnused[key] = true;
+        }
+        if (onlyHiddenInputs[key] === undefined) {
+          onlyHiddenInputs[key] = true;
+        }
+
+        const inputSkipUnusedField = input.hasAttribute(
+          this.binding(PHX_NO_UNUSED_FIELD),
+        );
+
+        const isUsed =
+          DOM.private(input, PHX_HAS_FOCUSED) ||
+          DOM.private(input, PHX_HAS_SUBMITTED) ||
+          inputSkipUnusedField;
+
+        const isHidden = input.type === "hidden";
+        inputsUnused[key] = inputsUnused[key] && !isUsed;
+        onlyHiddenInputs[key] = onlyHiddenInputs[key] && isHidden;
+
+        return acc;
+      },
+      { inputsUnused: {}, onlyHiddenInputs: {} },
+    );
+
+    const formSkipUnusedFields = form.hasAttribute(
+      this.binding(PHX_NO_UNUSED_FIELD),
+    );
+
+    for (const [key, val] of formData.entries()) {
+      if (onlyNames.length === 0 || onlyNames.indexOf(key) >= 0) {
+        const isUnused = inputsUnused[key];
+        const hidden = onlyHiddenInputs[key];
+        const skipUnusedCheck = formSkipUnusedFields;
+
+        if (
+          !skipUnusedCheck &&
+          isUnused &&
+          !(submitter && submitter.name == key) &&
+          !hidden
+        ) {
+          params.append(prependFormDataKey(key, "_unused_"), "");
+        }
+        if (typeof val === "string") {
+          params.append(key, val);
+        }
+      }
+    }
+
+    // remove the injected element again
+    // (it would be removed by the next dom patch anyway, but this is cleaner)
+    if (submitter && injectedElement) {
+      submitter.parentElement.removeChild(injectedElement);
+    }
+
+    return params.toString();
+  }
+
   pushEvent(type, el, targetCtx, phxEvent, meta, opts = {}, onReply) {
     this.pushWithReply(
       (maybePayload) =>
@@ -1727,9 +1745,11 @@ export default class View {
       serializeOpts.submitter = inputEl;
     }
     if (inputEl.getAttribute(this.binding("change"))) {
-      formData = serializeForm(inputEl.form, serializeOpts, [inputEl.name]);
+      formData = this.serializeForm(inputEl.form, serializeOpts, [
+        inputEl.name,
+      ]);
     } else {
-      formData = serializeForm(inputEl.form, serializeOpts);
+      formData = this.serializeForm(inputEl.form, serializeOpts);
     }
     if (
       DOM.isUploadInput(inputEl) &&
@@ -1906,7 +1926,7 @@ export default class View {
           return this.undoRefs(ref, phxEvent);
         }
         const meta = this.extractMeta(formEl, {}, opts.value);
-        const formData = serializeForm(formEl, { submitter });
+        const formData = this.serializeForm(formEl, { submitter });
         this.pushWithReply(proxyRefGen, "event", {
           type: "form",
           event: phxEvent,
@@ -1924,7 +1944,7 @@ export default class View {
       )
     ) {
       const meta = this.extractMeta(formEl, {}, opts.value);
-      const formData = serializeForm(formEl, { submitter });
+      const formData = this.serializeForm(formEl, { submitter });
       this.pushWithReply(refGenerator, "event", {
         type: "form",
         event: phxEvent,

package/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";
@@ -395,7 +395,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");
       },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phoenix_live_view",
-  "version": "1.1.30",
+  "version": "1.2.0-rc.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.56.1",
+    "@playwright/test": "^1.59.1",
     "@types/jest": "^30.0.0",
     "@types/phoenix": "^1.6.6",
     "css.escape": "^1.5.1",