phoenix_live_view 1.2.0-rc.1 → 1.2.0-rc.3

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://hexdocs.pm/phoenix_live_view/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;