phoenix_live_view 1.2.0-rc.2 → 1.2.0

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

@@ -0,0 +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://phoenix-live-view.hexdocs.pm/js-interop.html) instead.

package/assets/js/phoenix_live_view/{aria.js → aria.ts}

@@ -1,13 +1,16 @@
 const ARIA = {
-  anyOf(instance, classes) {
-    return classes.find((name) => instance instanceof name);
+  anyOf(
+    instance: unknown,
+    classes: (new (...args: any[]) => unknown)[],
+  ): boolean {
+    return classes.some((name) => instance instanceof name);
   },
 
-  isFocusable(el, interactiveOnly) {
+  isFocusable(el: Element, interactiveOnly = false): boolean {
     return (
       (el instanceof HTMLAnchorElement && el.rel !== "ignore") ||
       (el instanceof HTMLAreaElement && el.href !== undefined) ||
-      (!el.disabled &&
+      (!("disabled" in el && el.disabled) &&
         this.anyOf(el, [
           HTMLInputElement,
           HTMLSelectElement,
@@ -15,17 +18,19 @@ const ARIA = {
           HTMLButtonElement,
         ])) ||
       el instanceof HTMLIFrameElement ||
-      (el.tabIndex >= 0 && el.getAttribute("aria-hidden") !== "true") ||
+      (el instanceof HTMLElement &&
+        el.tabIndex >= 0 &&
+        el.getAttribute("aria-hidden") !== "true") ||
       (!interactiveOnly &&
         el.getAttribute("tabindex") !== null &&
         el.getAttribute("aria-hidden") !== "true")
     );
   },
 
-  attemptFocus(el, interactiveOnly) {
+  attemptFocus(el: Element, interactiveOnly = false): boolean {
     if (this.isFocusable(el, interactiveOnly)) {
       try {
-        el.focus();
+        (el as HTMLElement).focus();
       } catch {
         // that's fine
       }
@@ -33,7 +38,7 @@ const ARIA = {
     return !!document.activeElement && document.activeElement.isSameNode(el);
   },
 
-  focusFirstInteractive(el) {
+  focusFirstInteractive(el: Element): boolean {
     let child = el.firstElementChild;
     while (child) {
       if (this.attemptFocus(child, true) || this.focusFirstInteractive(child)) {
@@ -41,9 +46,10 @@ const ARIA = {
       }
       child = child.nextElementSibling;
     }
+    return false;
   },
 
-  focusFirst(el) {
+  focusFirst(el: Element): boolean {
     let child = el.firstElementChild;
     while (child) {
       if (this.attemptFocus(child) || this.focusFirst(child)) {
@@ -51,9 +57,10 @@ const ARIA = {
       }
       child = child.nextElementSibling;
     }
+    return false;
   },
 
-  focusLast(el) {
+  focusLast(el: Element): boolean {
     let child = el.lastElementChild;
     while (child) {
       if (this.attemptFocus(child) || this.focusLast(child)) {
@@ -61,6 +68,7 @@ const ARIA = {
       }
       child = child.previousElementSibling;
     }
+    return false;
   },
 };
 export default ARIA;

package/assets/js/phoenix_live_view/{browser.js → browser.ts}

@@ -30,7 +30,11 @@ const Browser = {
     );
   },
 
-  pushState(kind, meta, to) {
+  pushState(
+    kind: "replace" | "push",
+    meta: { type: string; scroll?: number; id?: string; position?: number },
+    to?: string,
+  ) {
     if (this.canPushState()) {
       if (to !== window.location.href) {
         if (meta.type == "redirect" && meta.scroll) {
@@ -57,32 +61,32 @@ const Browser = {
           }
         });
       }
-    } else {
+    } else if (to) {
       this.redirect(to);
     }
   },
 
-  setCookie(name, value, maxAgeSeconds) {
+  setCookie(name: string, value: string | number, maxAgeSeconds?: number) {
     const expires =
       typeof maxAgeSeconds === "number" ? ` max-age=${maxAgeSeconds};` : "";
     document.cookie = `${name}=${value};${expires} path=/`;
   },
 
-  getCookie(name) {
+  getCookie(name: string) {
     return document.cookie.replace(
       new RegExp(`(?:(?:^|.*;\s*)${name}\s*\=\s*([^;]*).*$)|^.*$`),
       "$1",
     );
   },
 
-  deleteCookie(name) {
+  deleteCookie(name: string) {
     document.cookie = `${name}=; max-age=-1; path=/`;
   },
 
   redirect(
-    toURL,
-    flash,
-    navigate = (url) => {
+    toURL: string,
+    flash: string | null = null,
+    navigate: (url: string) => void = (url) => {
       window.location.href = url;
     },
   ) {

package/assets/js/phoenix_live_view/{dom.js → dom.ts}

@@ -28,11 +28,31 @@ import {
 
 import { logError } from "./utils";
 
+export type FormInputLike = HTMLElement & {
+  readonly form?: HTMLFormElement | null;
+  readonly type?: string;
+  readonly validity?: ValidityState;
+  readonly name?: string;
+};
+
+export type QueryableNode = Element | Document | DocumentFragment;
+
 const DOM = {
   byId(id) {
     return document.getElementById(id) || logError(`no id found for ${id}`);
   },
 
+  elementFromTarget(target: EventTarget): Element | null {
+    if (!(target instanceof Node)) {
+      return null;
+    }
+    if (target.nodeType === Node.ELEMENT_NODE) {
+      return target as Element;
+    } else {
+      return target.parentElement;
+    }
+  },
+
   removeClass(el, className) {
     el.classList.remove(className);
     if (el.classList.length === 0) {
@@ -40,7 +60,11 @@ const DOM = {
     }
   },
 
-  all(node, query, callback) {
+  all(
+    node: QueryableNode | null,
+    query: string,
+    callback?: (el: Element) => void,
+  ): Element[] {
     if (!node) {
       return [];
     }
@@ -57,7 +81,7 @@ const DOM = {
     return template.content.childElementCount;
   },
 
-  isUploadInput(el) {
+  isUploadInput(el): el is HTMLInputElement {
     return el.type === "file" && el.getAttribute(PHX_UPLOAD_REF) !== null;
   },
 
@@ -65,7 +89,7 @@ const DOM = {
     return inputEl.hasAttribute("data-phx-auto-upload");
   },
 
-  findUploadInputs(node) {
+  findUploadInputs(node): HTMLInputElement[] {
     const formId = node.id;
     const inputsOutsideForm = this.all(
       document,
@@ -73,16 +97,33 @@ const DOM = {
     );
     return this.all(node, `input[type="file"][${PHX_UPLOAD_REF}]`).concat(
       inputsOutsideForm,
-    );
+    ) as HTMLInputElement[];
   },
 
-  findComponentNodeList(viewId, cid, doc = document) {
-    return this.all(
-      doc,
+  findComponent(
+    viewId: string,
+    cid: string | number,
+    doc: QueryableNode = document,
+  ): Element | null {
+    return doc.querySelector(
       `[${PHX_VIEW_REF}="${viewId}"][${PHX_COMPONENT}="${cid}"]`,
     );
   },
 
+  getComponent(
+    viewId: string,
+    cid: number,
+    doc: QueryableNode = document,
+  ): Element {
+    const el = this.findComponent(viewId, cid, doc);
+    if (!el) {
+      throw new Error(
+        `no component found matching viewId ${viewId} and cid ${cid}`,
+      );
+    }
+    return el;
+  },
+
   isPhxDestroyed(node) {
     return node.id && DOM.private(node, "destroyed") ? true : false;
   },
@@ -208,7 +249,7 @@ const DOM = {
       ).forEach((parent) => {
         parentCids.add(cid);
         this.all(parent, `[${PHX_VIEW_REF}="${viewId}"][${PHX_COMPONENT}]`)
-          .map((el) => parseInt(el.getAttribute(PHX_COMPONENT)))
+          .map((el) => parseInt(el.getAttribute(PHX_COMPONENT)!))
           .forEach((childCID) => childrenCids.add(childCID));
       });
     });
@@ -376,7 +417,7 @@ const DOM = {
     }
   },
 
-  triggerCycle(el, key, currentCycle) {
+  triggerCycle(el, key, currentCycle?) {
     const [cycle, trigger] = this.private(el, key);
     if (!currentCycle) {
       currentCycle = cycle;
@@ -470,7 +511,7 @@ const DOM = {
     return this.isPhxChild(el) ? el : this.all(el, `[${PHX_PARENT_ID}]`)[0];
   },
 
-  isPortalTemplate(el) {
+  isPortalTemplate(el): el is HTMLTemplateElement {
     return el.tagName === "TEMPLATE" && el.hasAttribute(PHX_PORTAL);
   },
 
@@ -491,7 +532,7 @@ const DOM = {
     return null;
   },
 
-  dispatchEvent(target, name, opts = {}) {
+  dispatchEvent(target, name, opts: { bubbles?: boolean; detail?: any } = {}) {
     let defaultBubble = true;
     const isUploadTarget =
       target.nodeName === "INPUT" && target.type === "file";
@@ -524,7 +565,11 @@ const DOM = {
   // merge attributes from source to target
   // if an element is ignored, we only merge data attributes
   // including removing data attributes that are no longer in the source
-  mergeAttrs(target, source, opts = {}) {
+  mergeAttrs(
+    target,
+    source,
+    opts: { exclude?: string[]; isIgnored?: boolean } = {},
+  ) {
     const exclude = new Set(opts.exclude || []);
     const isIgnored = opts.isIgnored;
     const sourceAttrs = source.attributes;
@@ -588,7 +633,7 @@ const DOM = {
     }
   },
 
-  hasSelectionRange(el) {
+  hasSelectionRange(el): el is HTMLInputElement | HTMLTextAreaElement {
     return (
       el.setSelectionRange && (el.type === "text" || el.type === "textarea")
     );
@@ -611,21 +656,41 @@ const DOM = {
     }
   },
 
-  isFormInput(el) {
-    if (el.localName && customElements.get(el.localName)) {
-      // Custom Elements may be form associated. This allows them
-      // to participate within a form's lifecycle, including form
-      // validity and form submissions.
-      // The spec for Form Associated custom elements requires the
-      // custom element's class to contain a static boolean value of `formAssociated`
-      // which identifies this class as allowed to associate to a form.
-      // See https://html.spec.whatwg.org/dev/custom-elements.html#custom-elements-face-example
-      // for details.
-      return customElements.get(el.localName)[`formAssociated`];
-    }
+  /**
+   * Returns true if the element is an input that can be focused and edited by the user,
+   * so we can skip patching it if it has focus.
+   */
+  isEditableInput(el: Element | EventTarget | null): el is FormInputLike {
+    return (
+      this.isFormAssociated(el) &&
+      !(el instanceof HTMLButtonElement) &&
+      !(el instanceof HTMLInputElement && el.type === "button")
+    );
+  },
 
+  isFormAssociated(el: Element | EventTarget | null): el is FormInputLike {
+    if (!(el instanceof HTMLElement)) return false;
+    if (el.localName) {
+      const customEl = customElements.get(el.localName);
+      if (customEl) {
+        // Custom Elements may be form associated. This allows them
+        // to participate within a form's lifecycle, including form
+        // validity and form submissions.
+        // The spec for Form Associated custom elements requires the
+        // custom element's class to contain a static boolean value of `formAssociated`
+        // which identifies this class as allowed to associate to a form.
+        // See https://html.spec.whatwg.org/dev/custom-elements.html#custom-elements-face-example
+        // for details.
+        return (
+          (customEl as { formAssociated?: boolean }).formAssociated === true
+        );
+      }
+    }
     return (
-      /^(?:input|select|textarea)$/i.test(el.tagName) && el.type !== "button"
+      el instanceof HTMLInputElement ||
+      el instanceof HTMLSelectElement ||
+      el instanceof HTMLTextAreaElement ||
+      el instanceof HTMLButtonElement
     );
   },
 
@@ -650,21 +715,22 @@ const DOM = {
     );
   },
 
-  cleanChildNodes(container, phxUpdate) {
+  cleanChildNodes(container: Element, phxUpdate: string) {
     if (
       DOM.isPhxUpdate(container, phxUpdate, ["append", "prepend", PHX_STREAM])
     ) {
-      const toRemove = [];
+      const toRemove: Array<ChildNode> = [];
       container.childNodes.forEach((childNode) => {
-        if (!childNode.id) {
+        if (!("id" in childNode) || !childNode.id) {
           // Skip warning if it's an empty text node (e.g. a new-line)
           const isEmptyTextNode =
             childNode.nodeType === Node.TEXT_NODE &&
+            childNode.nodeValue &&
             childNode.nodeValue.trim() === "";
           if (!isEmptyTextNode && childNode.nodeType !== Node.COMMENT_NODE) {
             logError(
               "only HTML element tags with an id are allowed inside containers with phx-update.\n\n" +
-                `removing illegal node: "${(childNode.outerHTML || childNode.nodeValue).trim()}"\n\n`,
+                `removing illegal node: "${(("outerHTML" in childNode && (childNode.outerHTML as string)) || childNode.nodeValue || "").trim()}"\n\n`,
             );
           }
           toRemove.push(childNode);
@@ -674,7 +740,11 @@ const DOM = {
     }
   },
 
-  replaceRootContainer(container, tagName, attrs) {
+  replaceRootContainer(
+    container: Element,
+    tagName: string,
+    attrs: Record<string, string>,
+  ) {
     const retainedAttrs = new Set([
       "id",
       PHX_SESSION,
@@ -697,9 +767,12 @@ const DOM = {
       Object.keys(attrs).forEach((attr) =>
         newContainer.setAttribute(attr, attrs[attr]),
       );
-      retainedAttrs.forEach((attr) =>
-        newContainer.setAttribute(attr, container.getAttribute(attr)),
-      );
+      retainedAttrs.forEach((attr) => {
+        const value = container.getAttribute(attr);
+        if (value !== null) {
+          newContainer.setAttribute(attr, value);
+        }
+      });
       newContainer.innerHTML = container.innerHTML;
       container.replaceWith(newContainer);
       return newContainer;