Updates based on feedback

assets/js/phoenix_live_view/dom.js

@@ -767,7 +767,6 @@ let DOM = {
     }
   },
 
-
   /**
    * Get the stashed result for the element's private "sticky" operation matching given name; if not found, return default value
    * @param {HTMLElement} el 
@@ -797,7 +796,7 @@ let DOM = {
   },
 
   /**
-   * Store a named "sticky" operation and it's result to the element's private data
+   * Store a named "sticky" operation and its result to the element's private data
    * @param {HTMLElement} el 
    * @param {string} name 
    * @param {function} op 

assets/js/phoenix_live_view/dom_patch.js

@@ -58,7 +58,7 @@ export default class DOMPatch {
    * @param {HTMLElement} container 
    * @param {string} id 
    * @param {string} html 
-   * @param {Stream[]} streams 
+   * @param {Set<Stream>} streams 
    * @param {string|number|null} [targetCID] 
    */
   constructor(view, container, id, html, streams, targetCID){

assets/js/phoenix_live_view/js.js

@@ -88,7 +88,7 @@ let JS = {
   },
 
   /**
-   * Push an event over livesocket
+   * Push an event over LiveSocket
    * @private
    * @param {string} eventType 
    * @param {string} phxEvent 

assets/js/phoenix_live_view/live_socket.js

@@ -728,7 +728,7 @@ export default class LiveSocket {
   }
 
   /**
-   * Blue the active element after tracking it for potential future focus
+   * Blur the active element after tracking it for potential future focus
    * restore.
    */
   blurActiveElement(){
@@ -1020,7 +1020,7 @@ export default class LiveSocket {
   /**
    * Dispatch event on window
    * @param {string} event 
-   * @param {{[key:string]: any}} [payload] 
+   * @param {any} [payload] 
    */
   dispatchEvent(event, payload = {}){
     DOM.dispatchEvent(window, `phx:${event}`, {detail: payload})

assets/js/phoenix_live_view/live_uploader.js

@@ -60,7 +60,8 @@ export default class LiveUploader {
   }
 
   /**
-   * 
+   * Create entry data for all active file uploads in input element, mapped to
+   * the input's upload ref
    * @param {HTMLInputElement} inputEl 
    * @returns {object} map of file refs to array of entries
    */

assets/js/phoenix_live_view/rendered.js

@@ -202,7 +202,7 @@ export default class Rendered {
 
   /**
    * Extract component IDs from diff
-   * @param {{[key: string]: any}} diff 
+   * @param {RenderedDiffNode} diff 
    * @returns {number[]} list of all CIDs parsed to ints
    */
   componentCIDs(diff){ return Object.keys(diff[COMPONENTS] || {}).map(i => parseInt(i)) }
@@ -356,7 +356,7 @@ export default class Rendered {
   /**
    * Get stripped HTML for component with ID
    * @param {string} cid 
-   * @returns {[strippedHTML: string, streams: string | Set<any>]}
+   * @returns {[strippedHTML: string, streams: Set<Stream>]}
    */
   componentToString(cid){
     let [str, streams] = this.recursiveCIDToString(this.rendered[COMPONENTS], cid, null)

assets/js/phoenix_live_view/view.js

@@ -55,7 +55,7 @@ import Rendered from "./rendered"
 import ViewHook from "./view_hook"
 import JS from "./js"
 
-/** @typedef {import('./rendered').RenderedDiff} RenderedDiff */
+/** @typedef {import('./rendered').RenderedDiffNode} RenderedDiffNode */
 
 /**
  * URL-safe encoding of data in the given form element
@@ -117,6 +117,7 @@ export default class View {
     this.ref = 0
     this.childJoins = 0
     this.loaderTimer = null
+    /** @type {{diff: RenderedDiffNode, events: [event: string, payload: any]}[]} */
     this.pendingDiffs = []
     this.pruningCIDs = []
     this.redirect = false
@@ -127,7 +128,9 @@ export default class View {
     this.joinCallback = function(onDone){ onDone && onDone() }
     this.stopCallback = function(){ }
     this.pendingJoinOps = this.parent ? null : []
+    /** @type {{[key:string]: ViewHook}} */
     this.viewHooks = {}
+    /** @type {{[key:Element]: LiveUploader}} */
     this.uploaders = {}
 
     /** @type {Array<[el: HTMLFormElement, ref: number, opts: object, cb: () => void]>} */
@@ -334,8 +337,8 @@ export default class View {
   /**
    * Apply the given raw diff
    * @param {"mount"|"update"} type 
-   * @param {RenderedDiff} rawDiff - The LiveView diff wire protocol
-   * @param {({diff: RenderedDiff, reply: number|null, events: any[]}) => void} callback 
+   * @param {RenderedDiffNode} rawDiff - The LiveView diff wire protocol
+   * @param {({diff: RenderedDiffNode, reply: number|null, events: any[]}) => void} callback 
    */
   applyDiff(type, rawDiff, callback){
     this.log(type, () => ["", clone(rawDiff)])
@@ -346,7 +349,7 @@ export default class View {
 
   /**
    * Handle successful channel join
-   * @param {{rendered: RenderedDiff, container?: [string, object]}} resp 
+   * @param {{rendered: RenderedDiffNode, container?: [string, object]}} resp 
    */
   onJoin(resp){
     let {rendered, container} = resp
@@ -396,8 +399,8 @@ export default class View {
    * @param {object} resp 
    * @param {any} resp.live_patch
    * @param {string} html 
-   * @param {any[]} streams 
-   * @param {any[]} events 
+   * @param {Set<Stream>} streams 
+   * @param {[event: string, payload: any][]} events 
    */
   onJoinComplete({live_patch}, html, streams, events){
     // In order to provide a better experience, we want to join
@@ -458,8 +461,8 @@ export default class View {
    * Apply initial patch after socket join completes
    * @param {{kind: "push"|"replace", to: string}} [live_patch] 
    * @param {string} html 
-   * @param {Stream[]} streams 
-   * @param {any[]} events 
+   * @param {Set<Stream>} streams 
+   * @param {[event: string, payload: any][]} events 
    */
   applyJoinPatch(live_patch, html, streams, events){
     this.attachTrueDocEl()
@@ -594,7 +597,7 @@ export default class View {
   }
 
   /**
-   * Call jioinChild
+   * For all children elements, join their views 
    */
   joinNewChildren(){
     DOM.findPhxChildren(this.el, this.id).forEach(el => this.joinChild(el))
@@ -633,7 +636,7 @@ export default class View {
   }
 
   /**
-   * Looks up a child
+   * Ensure a child view for given element exists and was joined
    * @param {HTMLElement} el 
    * @returns {boolean} true if child did
    */
@@ -648,8 +651,16 @@ export default class View {
     }
   }
 
+  /**
+   * Is join still pending?
+   * @returns {boolean}
+   */
   isJoinPending(){ return this.joinPending }
 
+  /**
+   * Notify parents up the chain of join if all children are joined
+   * @param {View} _child 
+   */
   ackJoin(_child){
     this.childJoins--
 
@@ -662,6 +673,9 @@ export default class View {
     }
   }
 
+  /**
+   * Execute pending join callbacks once all children complete joins
+   */
   onAllChildJoinsComplete(){
     this.joinCallback(() => {
       this.pendingJoinOps.forEach(([view, op]) => {
@@ -671,6 +685,12 @@ export default class View {
     })
   }
 
+  /**
+   * Update DOM for a diff and collection of events
+   * @param {RenderedDiffNode} diff 
+   * @param {[event: string, payload: any][]} events 
+   * @returns {void}
+   */
   update(diff, events){
     if(this.isJoinPending() || (this.liveSocket.hasPendingLink() && this.root.isMain())){
       return this.pendingDiffs.push({diff, events})
@@ -702,10 +722,10 @@ export default class View {
   }
 
   /**
-   * 
-   * @param {*} diff 
+   * Render container element for a diff
+   * @param {RenderedDiffNode} diff 
    * @param {string} kind 
-   * @returns {[string, object]}
+   * @returns {[string, Set<Stream>]}
    */
   renderContainer(diff, kind){
     return this.liveSocket.time(`toString diff (${kind})`, () => {
@@ -718,6 +738,12 @@ export default class View {
     })
   }
 
+  /**
+   * Render a DOM patch for component
+   * @param {RenderedDiffNode} diff 
+   * @param {string|number} cid 
+   * @returns {boolean} were children added?
+   */
   componentPatch(diff, cid){
     if(isEmpty(diff)) return false
     let [html, streams] = this.rendered.componentToString(cid)
@@ -726,6 +752,11 @@ export default class View {
     return childrenAdded
   }
 
+  /**
+   * Lookup ViewHook by Element ID
+   * @param {Element} el 
+   * @returns {ViewHook|undefined}
+   */
   getHook(el){ return this.viewHooks[ViewHook.elementID(el)] }
 
   /**