phoenix_live_view

1.1.2

1.2.7 1.2.6 1.2.5 1.2.4 1.2.3 1.2.2 1.2.1 1.2.0 1.2.0-rc.3 1.2.0-rc.2 1.2.0-rc.1 1.2.0-rc.0 1.1.32 1.1.31 1.1.30 1.1.29 1.1.28 1.1.27 1.1.26 1.1.25 1.1.24 1.1.23 1.1.22 1.1.21 1.1.20 1.1.19 1.1.18 1.1.17 1.1.16 1.1.15 1.1.14 1.1.13 1.1.12 1.1.11 1.1.10 1.1.9 1.1.8 1.1.7 1.1.6 retired 1.1.5 1.1.4 1.1.3 1.1.2 1.1.1 1.1.0 1.1.0-rc.4 1.1.0-rc.3 1.1.0-rc.2 1.1.0-rc.1 1.1.0-rc.0 1.0.18 1.0.17 1.0.16 1.0.15 1.0.14 1.0.13 1.0.12 1.0.11 1.0.10 1.0.9 1.0.8 retired 1.0.7 1.0.6 retired 1.0.5 1.0.4 1.0.3 1.0.2 1.0.1 1.0.0 1.0.0-rc.9 1.0.0-rc.8 1.0.0-rc.7 1.0.0-rc.6 1.0.0-rc.5 1.0.0-rc.4 1.0.0-rc.3 1.0.0-rc.2 1.0.0-rc.1 1.0.0-rc.0 0.20.17 0.20.16 0.20.15 0.20.14 0.20.13 0.20.12 0.20.11 0.20.10 0.20.9 0.20.8 0.20.7 0.20.6 0.20.5 0.20.4 0.20.3 0.20.2 0.20.1 0.20.0 0.19.5 0.19.4 0.19.3 0.19.2 0.19.1 0.19.0 0.18.18 0.18.17 0.18.16 0.18.15 0.18.14 0.18.13 0.18.12 0.18.11 0.18.10 0.18.9 0.18.8 0.18.7 0.18.6 0.18.5 0.18.4 0.18.3 0.18.2 0.18.1 0.18.0 0.17.14 0.17.13 0.17.12 0.17.11 0.17.10 0.17.9 0.17.8 0.17.7 0.17.6 0.17.5 0.17.4 0.17.3 0.17.2 0.17.1 0.17.0 0.16.4 0.16.3 0.16.2 0.16.1 0.16.0 0.15.7 0.15.6 0.15.5 0.15.4 0.15.3 0.15.2 0.15.1 0.15.0 0.14.8 0.14.7 0.14.6 0.14.5 0.14.4 0.14.3 0.14.2 0.14.1 0.14.0 0.13.3 0.13.2 0.13.1 0.13.0 0.12.1 0.12.0 0.11.1 0.11.0 0.10.0 0.9.0 0.8.1 0.8.0 0.7.1 0.7.0 0.6.0 0.6.0-dev 0.5.2 0.5.1 0.5.0 0.4.1 0.4.0 0.3.1 0.3.0 0.2.1 0.2.0 0.1.1 0.1.0

Rich, real-time user experiences with server-rendered HTML

HexDocs

Current section

Files

Jump to

Readme 186 Versions 9 Dependencies Dependants 1 Advisory Files Activity

phoenix_live_view assets js phoenix_live_view element_ref.js

Raw

assets/js/phoenix_live_view/element_ref.js

import {
  PHX_REF_LOADING,
  PHX_REF_LOCK,
  PHX_REF_SRC,
  PHX_PENDING_REFS,
  PHX_EVENT_CLASSES,
  PHX_DISABLED,
  PHX_READONLY,
  PHX_DISABLE_WITH_RESTORE,
} from "./constants";

import DOM from "./dom";

export default class ElementRef {
  static onUnlock(el, callback) {
    if (!DOM.isLocked(el) && !el.closest(`[${PHX_REF_LOCK}]`)) {
      return callback();
    }
    const closestLock = el.closest(`[${PHX_REF_LOCK}]`);
    const ref = closestLock
      .closest(`[${PHX_REF_LOCK}]`)
      .getAttribute(PHX_REF_LOCK);
    closestLock.addEventListener(
      `phx:undo-lock:${ref}`,
      () => {
        callback();
      },
      { once: true },
    );
  }

  constructor(el) {
    this.el = el;
    this.loadingRef = el.hasAttribute(PHX_REF_LOADING)
      ? parseInt(el.getAttribute(PHX_REF_LOADING), 10)
      : null;
    this.lockRef = el.hasAttribute(PHX_REF_LOCK)
      ? parseInt(el.getAttribute(PHX_REF_LOCK), 10)
      : null;
  }

  // public

  maybeUndo(ref, phxEvent, eachCloneCallback) {
    if (!this.isWithin(ref)) {
      // we cannot undo the lock / loading now, as there is a newer one already set;
      // we need to store the original ref we tried to send the undo event later
      DOM.updatePrivate(this.el, PHX_PENDING_REFS, [], (pendingRefs) => {
        pendingRefs.push(ref);
        return pendingRefs;
      });
      return;
    }

    // undo locks and apply clones
    this.undoLocks(ref, phxEvent, eachCloneCallback);

    // undo loading states
    this.undoLoading(ref, phxEvent);

    // ensure undo events are fired for pending refs that
    // are resolved by the current ref, otherwise we'd leak event listeners
    DOM.updatePrivate(this.el, PHX_PENDING_REFS, [], (pendingRefs) => {
      return pendingRefs.filter((pendingRef) => {
        let opts = {
          detail: { ref: pendingRef, event: phxEvent },
          bubbles: true,
          cancelable: false,
        };
        if (this.loadingRef && this.loadingRef > pendingRef) {
          this.el.dispatchEvent(
            new CustomEvent(`phx:undo-loading:${pendingRef}`, opts),
          );
        }
        if (this.lockRef && this.lockRef > pendingRef) {
          this.el.dispatchEvent(
            new CustomEvent(`phx:undo-lock:${pendingRef}`, opts),
          );
        }
        return pendingRef > ref;
      });
    });

    // clean up if fully resolved
    if (this.isFullyResolvedBy(ref)) {
      this.el.removeAttribute(PHX_REF_SRC);
    }
  }

  // private

  isWithin(ref) {
    return !(
      this.loadingRef !== null &&
      this.loadingRef > ref &&
      this.lockRef !== null &&
      this.lockRef > ref
    );
  }

  // Check for cloned PHX_REF_LOCK element that has been morphed behind
  // the scenes while this element was locked in the DOM.
  // When we apply the cloned tree to the active DOM element, we must
  //
  //   1. execute pending mounted hooks for nodes now in the DOM
  //   2. undo any ref inside the cloned tree that has since been ack'd
  undoLocks(ref, phxEvent, eachCloneCallback) {
    if (!this.isLockUndoneBy(ref)) {
      return;
    }

    const clonedTree = DOM.private(this.el, PHX_REF_LOCK);
    if (clonedTree) {
      eachCloneCallback(clonedTree);
      DOM.deletePrivate(this.el, PHX_REF_LOCK);
    }
    this.el.removeAttribute(PHX_REF_LOCK);

    const opts = {
      detail: { ref: ref, event: phxEvent },
      bubbles: true,
      cancelable: false,
    };
    this.el.dispatchEvent(
      new CustomEvent(`phx:undo-lock:${this.lockRef}`, opts),
    );
  }

  undoLoading(ref, phxEvent) {
    if (!this.isLoadingUndoneBy(ref)) {
      if (
        this.canUndoLoading(ref) &&
        this.el.classList.contains("phx-submit-loading")
      ) {
        this.el.classList.remove("phx-change-loading");
      }
      return;
    }

    if (this.canUndoLoading(ref)) {
      this.el.removeAttribute(PHX_REF_LOADING);
      const disabledVal = this.el.getAttribute(PHX_DISABLED);
      const readOnlyVal = this.el.getAttribute(PHX_READONLY);
      // restore inputs
      if (readOnlyVal !== null) {
        this.el.readOnly = readOnlyVal === "true" ? true : false;
        this.el.removeAttribute(PHX_READONLY);
      }
      if (disabledVal !== null) {
        this.el.disabled = disabledVal === "true" ? true : false;
        this.el.removeAttribute(PHX_DISABLED);
      }
      // restore disables
      const disableRestore = this.el.getAttribute(PHX_DISABLE_WITH_RESTORE);
      if (disableRestore !== null) {
        this.el.innerText = disableRestore;
        this.el.removeAttribute(PHX_DISABLE_WITH_RESTORE);
      }

      const opts = {
        detail: { ref: ref, event: phxEvent },
        bubbles: true,
        cancelable: false,
      };
      this.el.dispatchEvent(
        new CustomEvent(`phx:undo-loading:${this.loadingRef}`, opts),
      );
    }

    // remove classes
    PHX_EVENT_CLASSES.forEach((name) => {
      if (name !== "phx-submit-loading" || this.canUndoLoading(ref)) {
        DOM.removeClass(this.el, name);
      }
    });
  }

  isLoadingUndoneBy(ref) {
    return this.loadingRef === null ? false : this.loadingRef <= ref;
  }
  isLockUndoneBy(ref) {
    return this.lockRef === null ? false : this.lockRef <= ref;
  }

  isFullyResolvedBy(ref) {
    return (
      (this.loadingRef === null || this.loadingRef <= ref) &&
      (this.lockRef === null || this.lockRef <= ref)
    );
  }

  // only remove the phx-submit-loading class if we are not locked
  canUndoLoading(ref) {
    return this.lockRef === null || this.lockRef <= ref;
  }
}

Operator	Description	Example
name:	Match package name. Supports * wildcards and repo/package form	name:phx* or name:hexpm/phoenix
description:	Full-text search of package descriptions	description:auth
depends:	Packages depending on a given package. Supports repo:package form	depends:ecto or depends:hexpm:ecto
build_tool:	Filter by build tool	build_tool:mix
updated_after:	Packages updated after an ISO8601 datetime	updated_after:2025-01-01T00:00:00Z
extra:	Match custom metadata (key,value). Nested keys are separated by commas	extra:license,MIT