cable_ready 5.0.0.pre9 → 5.0.0.rc1

data/app/assets/javascripts/cable_ready.umd.js

@@ -3,47 +3,49 @@
   factory(global.CableReady = {}, global.morphdom));
 })(this, (function(exports, morphdom) {
   "use strict";
-  function _interopDefaultLegacy(e) {
-    return e && typeof e === "object" && "default" in e ? e : {
-      default: e
-    };
-  }
-  var morphdom__default = _interopDefaultLegacy(morphdom);
   var name = "cable_ready";
-  var version = "5.0.0-pre9";
+  var version = "5.0.0-rc1";
   var description = "CableReady helps you create great real-time user experiences by making it simple to trigger client-side DOM changes from server-side Ruby.";
   var keywords = [ "ruby", "rails", "websockets", "actioncable", "cable", "ssr", "stimulus_reflex", "client-side", "dom" ];
-  var homepage = "https://cableready.stimulusreflex.com/";
-  var bugs = {
-    url: "https://github.com/stimulusreflex/cable_ready/issues"
-  };
-  var repository = {
-    type: "git",
-    url: "git+https://github.com:stimulusreflex/cable_ready.git"
-  };
+  var homepage = "https://cableready.stimulusreflex.com";
+  var bugs = "https://github.com/stimulusreflex/cable_ready/issues";
+  var repository = "https://github.com/stimulusreflex/cable_ready";
   var license = "MIT";
   var author = "Nathan Hopkins <natehop@gmail.com>";
-  var main = "./dist/cable_ready.umd.min.js";
-  var module = "./dist/cable_ready.min.js";
+  var contributors = [ "Andrew Mason <andrewmcodes@protonmail.com>", "Julian Rubisch <julian@julianrubisch.at>", "Marco Roth <marco.roth@intergga.ch>", "Nathan Hopkins <natehop@gmail.com>" ];
+  var main = "./dist/cable_ready.js";
+  var module = "./dist/cable_ready.js";
+  var browser = "./dist/cable_ready.js";
+  var unpkg = "./dist/cable_ready.umd.js";
+  var umd = "./dist/cable_ready.umd.js";
   var files = [ "dist/*", "javascript/*" ];
   var scripts = {
-    lint: "yarn run prettier-standard:check",
-    format: "yarn run prettier-standard:format",
-    "prettier-standard:check": "yarn run prettier-standard --check ./javascript/**/*.js rollup.config.js",
-    "prettier-standard:format": "yarn run prettier-standard ./javascript/**/*.js rollup.config.js",
+    lint: "yarn run format --check",
+    format: "yarn run prettier-standard ./javascript/**/*.js rollup.config.mjs",
     build: "yarn rollup -c",
-    watch: "yarn rollup -wc"
+    watch: "yarn rollup -wc",
+    test: "web-test-runner javascript/test/**/*.test.js",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs && cp ./docs/_redirects ./docs/.vitepress/dist",
+    "docs:preview": "vitepress preview docs"
   };
   var dependencies = {
-    morphdom: "^2.6.1"
+    morphdom: "2.6.1"
   };
   var devDependencies = {
-    "@rollup/plugin-commonjs": "^21.0.3",
-    "@rollup/plugin-json": "^4.1.0",
-    "@rollup/plugin-node-resolve": "^13.1.3",
+    "@open-wc/testing": "^3.1.7",
+    "@rollup/plugin-json": "^6.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.1",
+    "@rollup/plugin-terser": "^0.4.0",
+    "@web/dev-server-esbuild": "^0.3.3",
+    "@web/dev-server-rollup": "^0.3.21",
+    "@web/test-runner": "^0.15.1",
     "prettier-standard": "^16.4.1",
-    rollup: "^2.70.1",
-    "rollup-plugin-terser": "^7.0.2"
+    rollup: "^3.19.1",
+    sinon: "^15.0.2",
+    vite: "^4.1.4",
+    vitepress: "^1.0.0-alpha.56",
+    "vitepress-plugin-search": "^1.0.4-alpha.19"
   };
   var packageInfo = {
     name: name,
@@ -55,8 +57,13 @@
     repository: repository,
     license: license,
     author: author,
+    contributors: contributors,
     main: main,
     module: module,
+    browser: browser,
+    import: "./dist/cable_ready.js",
+    unpkg: unpkg,
+    umd: umd,
     files: files,
     scripts: scripts,
     dependencies: dependencies,
@@ -101,49 +108,132 @@
       activeElement = element;
     }
   };
-  const isTextInput = element => inputTags[element.tagName] && textInputTypes[element.type];
-  const assignFocus = selector => {
+  // Indicates if the passed element is considered a text input.
+  
+    const isTextInput = element => inputTags[element.tagName] && textInputTypes[element.type];
+  // Assigns focus to the appropriate element... preferring the explicitly passed selector
+  
+  // * selector - a CSS selector for the element that should have focus
+  
+    const assignFocus = selector => {
     const element = selector && selector.nodeType === Node.ELEMENT_NODE ? selector : document.querySelector(selector);
     const focusElement = element || ActiveElement.element;
     if (focusElement && focusElement.focus) focusElement.focus();
   };
-  const dispatch = (element, name, detail = {}) => {
+  // Dispatches an event on the passed element
+  
+  // * element - the element
+  // * name - the name of the event
+  // * detail - the event detail
+  
+    const dispatch = (element, name, detail = {}) => {
     const init = {
       bubbles: true,
       cancelable: true,
       detail: detail
     };
-    const evt = new CustomEvent(name, init);
-    element.dispatchEvent(evt);
+    const event = new CustomEvent(name, init);
+    element.dispatchEvent(event);
     if (window.jQuery) window.jQuery(element).trigger(name, detail);
   };
-  const xpathToElement = xpath => document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
-  const getClassNames = names => Array(names).flat();
+  // Accepts an xPath query and returns the element found at that position in the DOM
+  
+    const xpathToElement = xpath => document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+  // Accepts an xPath query and returns all matching elements in the DOM
+  
+    const xpathToElementArray = (xpath, reverse = false) => {
+    const snapshotList = document.evaluate(xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+    const snapshots = [];
+    for (let i = 0; i < snapshotList.snapshotLength; i++) {
+      snapshots.push(snapshotList.snapshotItem(i));
+    }
+    return reverse ? snapshots.reverse() : snapshots;
+  };
+  // Return an array with the class names to be used
+  
+  // * names - could be a string or an array of strings for multiple classes.
+  
+    const getClassNames = names => Array.from(names).flat()
+  // Perform operation for either the first or all of the elements returned by CSS selector
+  
+  // * operation - the instruction payload from perform
+  // * callback - the operation function to run for each element
+  
+  ;
   const processElements = (operation, callback) => {
     Array.from(operation.selectAll ? operation.element : [ operation.element ]).forEach(callback);
   };
-  const kebabize = str => str.split("").map(((letter, idx) => letter.toUpperCase() === letter ? `${idx !== 0 ? "-" : ""}${letter.toLowerCase()}` : letter)).join("");
-  const operate = (operation, callback) => {
+  // convert string to kebab-case
+  // most other implementations (lodash) are focused on camelCase to kebab-case
+  // instead, this uses word token boundaries to produce readable URL slugs and keys
+  // this implementation will not support Emoji or other non-ASCII characters
+  
+    const kebabize = createCompounder((function(result, word, index) {
+    return result + (index ? "-" : "") + word.toLowerCase();
+  }));
+  function createCompounder(callback) {
+    return function(str) {
+      return words(str).reduce(callback, "");
+    };
+  }
+  const words = str => {
+    str = str == null ? "" : str;
+    return str.match(/([A-Z]{2,}|[0-9]+|[A-Z]?[a-z]+|[A-Z])/g) || [];
+  };
+  // Provide a standardized pipeline of checks and modifications to all operations based on provided options
+  // Currently skips execution if cancelled and implements an optional delay
+  
+    const operate = (operation, callback) => {
     if (!operation.cancel) {
       operation.delay ? setTimeout(callback, operation.delay) : callback();
       return true;
     }
     return false;
   };
-  const before = (target, operation) => dispatch(target, `cable-ready:before-${kebabize(operation.operation)}`, operation);
+  // Dispatch life-cycle events with standardized naming
+    const before = (target, operation) => dispatch(target, `cable-ready:before-${kebabize(operation.operation)}`, operation);
   const after = (target, operation) => dispatch(target, `cable-ready:after-${kebabize(operation.operation)}`, operation);
-  function debounce(func, timeout) {
+  function debounce(fn, delay = 250) {
     let timer;
     return (...args) => {
-      clearTimeout(timer);
-      timer = setTimeout((() => func.apply(this, args)), timeout);
+      const callback = () => fn.apply(this, args);
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(callback, delay);
     };
   }
   function handleErrors(response) {
     if (!response.ok) throw Error(response.statusText);
     return response;
   }
-  async function graciouslyFetch(url, additionalHeaders) {
+  function safeScalar(val) {
+    if (val !== undefined && ![ "string", "number", "boolean" ].includes(typeof val)) console.warn(`Operation expects a string, number or boolean, but got ${val} (${typeof val})`);
+    return val != null ? val : "";
+  }
+  function safeString(str) {
+    if (str !== undefined && typeof str !== "string") console.warn(`Operation expects a string, but got ${str} (${typeof str})`);
+    return str != null ? String(str) : "";
+  }
+  function safeArray(arr) {
+    if (arr !== undefined && !Array.isArray(arr)) console.warn(`Operation expects an array, but got ${arr} (${typeof arr})`);
+    return arr != null ? Array.from(arr) : [];
+  }
+  function safeObject(obj) {
+    if (obj !== undefined && typeof obj !== "object") console.warn(`Operation expects an object, but got ${obj} (${typeof obj})`);
+    return obj != null ? Object(obj) : {};
+  }
+  function safeStringOrArray(elem) {
+    if (elem !== undefined && !Array.isArray(elem) && typeof elem !== "string") console.warn(`Operation expects an Array or a String, but got ${elem} (${typeof elem})`);
+    return elem == null ? "" : Array.isArray(elem) ? Array.from(elem) : String(elem);
+  }
+  function fragmentToString(fragment) {
+    return (new XMLSerializer).serializeToString(fragment);
+  }
+  // A proxy method to wrap a fetch call in error handling
+  
+  // * url - the URL to fetch
+  // * additionalHeaders - an object of additional headers passed to fetch
+  
+    async function graciouslyFetch(url, additionalHeaders) {
     try {
       const response = await fetch(url, {
         headers: {
@@ -158,29 +248,44 @@
       console.error(`Could not fetch ${url}`);
     }
   }
-  var utils = Object.freeze({
+  var utils =  Object.freeze({
     __proto__: null,
-    isTextInput: isTextInput,
+    after: after,
     assignFocus: assignFocus,
-    dispatch: dispatch,
-    xpathToElement: xpathToElement,
-    getClassNames: getClassNames,
-    processElements: processElements,
-    operate: operate,
     before: before,
-    after: after,
     debounce: debounce,
-    handleErrors: handleErrors,
+    dispatch: dispatch,
+    fragmentToString: fragmentToString,
+    getClassNames: getClassNames,
     graciouslyFetch: graciouslyFetch,
-    kebabize: kebabize
+    handleErrors: handleErrors,
+    isTextInput: isTextInput,
+    kebabize: kebabize,
+    operate: operate,
+    processElements: processElements,
+    safeArray: safeArray,
+    safeObject: safeObject,
+    safeScalar: safeScalar,
+    safeString: safeString,
+    safeStringOrArray: safeStringOrArray,
+    xpathToElement: xpathToElement,
+    xpathToElementArray: xpathToElementArray
   });
-  const shouldMorph = operation => (fromEl, toEl) => !shouldMorphCallbacks.map((callback => typeof callback === "function" ? callback(operation, fromEl, toEl) : true)).includes(false);
+  // Indicates whether or not we should morph an element via onBeforeElUpdated callback
+  // SEE: https://github.com/patrick-steele-idem/morphdom#morphdomfromnode-tonode-options--node
+  
+    const shouldMorph = operation => (fromEl, toEl) => !shouldMorphCallbacks.map((callback => typeof callback === "function" ? callback(operation, fromEl, toEl) : true)).includes(false)
+  // Execute any pluggable functions that modify elements after morphing via onElUpdated callback
+  
+  ;
   const didMorph = operation => el => {
     didMorphCallbacks.forEach((callback => {
       if (typeof callback === "function") callback(operation, el);
     }));
   };
   const verifyNotMutable = (detail, fromEl, toEl) => {
+    // Skip nodes that are equal:
+    // https://github.com/patrick-steele-idem/morphdom#can-i-make-morphdom-blaze-through-the-dom-tree-even-faster-yes
     if (!mutableTags[fromEl.tagName] && fromEl.isEqualNode(toEl)) return false;
     return true;
   };
@@ -192,7 +297,8 @@
     const {permanentAttributeName: permanentAttributeName} = detail;
     if (!permanentAttributeName) return true;
     const permanent = fromEl.closest(`[${permanentAttributeName}]`);
-    if (!permanent && fromEl === ActiveElement.element && isTextInput(fromEl)) {
+    // only morph attributes on the active non-permanent text input
+        if (!permanent && fromEl === ActiveElement.element && isTextInput(fromEl)) {
       const ignore = {
         value: true
       };
@@ -205,23 +311,24 @@
   };
   const shouldMorphCallbacks = [ verifyNotMutable, verifyNotPermanent, verifyNotContentEditable ];
   const didMorphCallbacks = [];
-  var morph_callbacks = Object.freeze({
+  var morph_callbacks =  Object.freeze({
     __proto__: null,
-    shouldMorphCallbacks: shouldMorphCallbacks,
+    didMorph: didMorph,
     didMorphCallbacks: didMorphCallbacks,
     shouldMorph: shouldMorph,
-    didMorph: didMorph,
-    verifyNotMutable: verifyNotMutable,
+    shouldMorphCallbacks: shouldMorphCallbacks,
     verifyNotContentEditable: verifyNotContentEditable,
+    verifyNotMutable: verifyNotMutable,
     verifyNotPermanent: verifyNotPermanent
   });
   var Operations = {
+    // DOM Mutations
     append: operation => {
       processElements(operation, (element => {
         before(element, operation);
         operate(operation, (() => {
           const {html: html, focusSelector: focusSelector} = operation;
-          element.insertAdjacentHTML("beforeend", html || "");
+          element.insertAdjacentHTML("beforeend", safeScalar(html));
           assignFocus(focusSelector);
         }));
         after(element, operation);
@@ -246,7 +353,7 @@
         before(element, operation);
         operate(operation, (() => {
           const {html: html, focusSelector: focusSelector} = operation;
-          element.innerHTML = html || "";
+          element.innerHTML = safeScalar(html);
           assignFocus(focusSelector);
         }));
         after(element, operation);
@@ -257,7 +364,7 @@
         before(element, operation);
         operate(operation, (() => {
           const {html: html, position: position, focusSelector: focusSelector} = operation;
-          element.insertAdjacentHTML(position || "beforeend", html || "");
+          element.insertAdjacentHTML(position || "beforeend", safeScalar(html));
           assignFocus(focusSelector);
         }));
         after(element, operation);
@@ -268,44 +375,23 @@
         before(element, operation);
         operate(operation, (() => {
           const {text: text, position: position, focusSelector: focusSelector} = operation;
-          element.insertAdjacentText(position || "beforeend", text || "");
+          element.insertAdjacentText(position || "beforeend", safeScalar(text));
           assignFocus(focusSelector);
         }));
         after(element, operation);
       }));
     },
-    morph: operation => {
-      processElements(operation, (element => {
-        const {html: html} = operation;
-        const template = document.createElement("template");
-        template.innerHTML = String(html).trim();
-        operation.content = template.content;
-        const parent = element.parentElement;
-        const ordinal = Array.from(parent.children).indexOf(element);
-        before(element, operation);
-        operate(operation, (() => {
-          const {childrenOnly: childrenOnly, focusSelector: focusSelector} = operation;
-          morphdom__default["default"](element, childrenOnly ? template.content : template.innerHTML, {
-            childrenOnly: !!childrenOnly,
-            onBeforeElUpdated: shouldMorph(operation),
-            onElUpdated: didMorph(operation)
-          });
-          assignFocus(focusSelector);
-        }));
-        after(parent.children[ordinal], operation);
-      }));
-    },
     outerHtml: operation => {
       processElements(operation, (element => {
         const parent = element.parentElement;
-        const ordinal = Array.from(parent.children).indexOf(element);
+        const idx = parent && Array.from(parent.children).indexOf(element);
         before(element, operation);
         operate(operation, (() => {
           const {html: html, focusSelector: focusSelector} = operation;
-          element.outerHTML = html || "";
+          element.outerHTML = safeScalar(html);
           assignFocus(focusSelector);
         }));
-        after(parent.children[ordinal], operation);
+        after(parent ? parent.children[idx] : document.documentElement, operation);
       }));
     },
     prepend: operation => {
@@ -313,7 +399,7 @@
         before(element, operation);
         operate(operation, (() => {
           const {html: html, focusSelector: focusSelector} = operation;
-          element.insertAdjacentHTML("afterbegin", html || "");
+          element.insertAdjacentHTML("afterbegin", safeScalar(html));
           assignFocus(focusSelector);
         }));
         after(element, operation);
@@ -333,14 +419,14 @@
     replace: operation => {
       processElements(operation, (element => {
         const parent = element.parentElement;
-        const ordinal = Array.from(parent.children).indexOf(element);
+        const idx = parent && Array.from(parent.children).indexOf(element);
         before(element, operation);
         operate(operation, (() => {
           const {html: html, focusSelector: focusSelector} = operation;
-          element.outerHTML = html || "";
+          element.outerHTML = safeScalar(html);
           assignFocus(focusSelector);
         }));
-        after(parent.children[ordinal], operation);
+        after(parent ? parent.children[idx] : document.documentElement, operation);
       }));
     },
     textContent: operation => {
@@ -348,18 +434,19 @@
         before(element, operation);
         operate(operation, (() => {
           const {text: text, focusSelector: focusSelector} = operation;
-          element.textContent = text != null ? text : "";
+          element.textContent = safeScalar(text);
           assignFocus(focusSelector);
         }));
         after(element, operation);
       }));
     },
+    // Element Property Mutations
     addCssClass: operation => {
       processElements(operation, (element => {
         before(element, operation);
         operate(operation, (() => {
           const {name: name} = operation;
-          element.classList.add(...getClassNames(name || ""));
+          element.classList.add(...getClassNames([ safeStringOrArray(name) ]));
         }));
         after(element, operation);
       }));
@@ -369,7 +456,7 @@
         before(element, operation);
         operate(operation, (() => {
           const {name: name} = operation;
-          element.removeAttribute(name);
+          element.removeAttribute(safeString(name));
         }));
         after(element, operation);
       }));
@@ -379,7 +466,8 @@
         before(element, operation);
         operate(operation, (() => {
           const {name: name} = operation;
-          element.classList.remove(...getClassNames(name));
+          element.classList.remove(...getClassNames([ safeStringOrArray(name) ]));
+          if (element.classList.length === 0) element.removeAttribute("class");
         }));
         after(element, operation);
       }));
@@ -389,7 +477,7 @@
         before(element, operation);
         operate(operation, (() => {
           const {name: name, value: value} = operation;
-          element.setAttribute(name, value || "");
+          element.setAttribute(safeString(name), safeScalar(value));
         }));
         after(element, operation);
       }));
@@ -399,7 +487,7 @@
         before(element, operation);
         operate(operation, (() => {
           const {name: name, value: value} = operation;
-          element.dataset[name] = value || "";
+          element.dataset[safeString(name)] = safeScalar(value);
         }));
         after(element, operation);
       }));
@@ -409,7 +497,7 @@
         before(element, operation);
         operate(operation, (() => {
           const {name: name, value: value} = operation;
-          if (name in element) element[name] = value || "";
+          if (name in element) element[safeString(name)] = safeScalar(value);
         }));
         after(element, operation);
       }));
@@ -419,7 +507,7 @@
         before(element, operation);
         operate(operation, (() => {
           const {name: name, value: value} = operation;
-          element.style[name] = value || "";
+          element.style[safeString(name)] = safeScalar(value);
         }));
         after(element, operation);
       }));
@@ -429,7 +517,7 @@
         before(element, operation);
         operate(operation, (() => {
           const {styles: styles} = operation;
-          for (let [name, value] of Object.entries(styles)) element.style[name] = value || "";
+          for (let [name, value] of Object.entries(styles)) element.style[safeString(name)] = safeScalar(value);
         }));
         after(element, operation);
       }));
@@ -439,17 +527,18 @@
         before(element, operation);
         operate(operation, (() => {
           const {value: value} = operation;
-          element.value = value || "";
+          element.value = safeScalar(value);
         }));
         after(element, operation);
       }));
     },
+    // DOM Events and Meta-Operations
     dispatchEvent: operation => {
       processElements(operation, (element => {
         before(element, operation);
         operate(operation, (() => {
           const {name: name, detail: detail} = operation;
-          dispatch(element, name, detail);
+          dispatch(element, safeString(name), safeObject(detail));
         }));
         after(element, operation);
       }));
@@ -461,13 +550,22 @@
         let meta = document.head.querySelector(`meta[name='${name}']`);
         if (!meta) {
           meta = document.createElement("meta");
-          meta.name = name;
+          meta.name = safeString(name);
           document.head.appendChild(meta);
         }
-        meta.content = content;
+        meta.content = safeScalar(content);
+      }));
+      after(document, operation);
+    },
+    setTitle: operation => {
+      before(document, operation);
+      operate(operation, (() => {
+        const {title: title} = operation;
+        document.title = safeScalar(title);
       }));
       after(document, operation);
     },
+    // Browser Manipulations
     clearStorage: operation => {
       before(document, operation);
       operate(operation, (() => {
@@ -489,22 +587,28 @@
       before(window, operation);
       operate(operation, (() => {
         const {state: state, title: title, url: url} = operation;
-        history.pushState(state || {}, title || "", url);
+        history.pushState(safeObject(state), safeString(title), safeString(url));
       }));
       after(window, operation);
     },
     redirectTo: operation => {
       before(window, operation);
       operate(operation, (() => {
-        let {url: url, action: action} = operation;
+        let {url: url, action: action, turbo: turbo} = operation;
         action = action || "advance";
-        if (window.Turbo) window.Turbo.visit(url, {
-          action: action
-        });
-        if (window.Turbolinks) window.Turbolinks.visit(url, {
-          action: action
-        });
-        if (!window.Turbo && !window.Turbolinks) window.location.href = url;
+        url = safeString(url);
+        if (turbo === undefined) turbo = true;
+        if (turbo) {
+          if (window.Turbo) window.Turbo.visit(url, {
+            action: action
+          });
+          if (window.Turbolinks) window.Turbolinks.visit(url, {
+            action: action
+          });
+          if (!window.Turbo && !window.Turbolinks) window.location.href = url;
+        } else {
+          window.location.href = url;
+        }
       }));
       after(window, operation);
     },
@@ -520,7 +624,7 @@
       operate(operation, (() => {
         const {key: key, type: type} = operation;
         const storage = type === "session" ? sessionStorage : localStorage;
-        storage.removeItem(key);
+        storage.removeItem(safeString(key));
       }));
       after(document, operation);
     },
@@ -528,7 +632,7 @@
       before(window, operation);
       operate(operation, (() => {
         const {state: state, title: title, url: url} = operation;
-        history.replaceState(state || {}, title || "", url);
+        history.replaceState(safeObject(state), safeString(title), safeString(url));
       }));
       after(window, operation);
     },
@@ -544,7 +648,7 @@
       before(document, operation);
       operate(operation, (() => {
         const {cookie: cookie} = operation;
-        document.cookie = cookie || "";
+        document.cookie = safeScalar(cookie);
       }));
       after(document, operation);
     },
@@ -561,15 +665,16 @@
       operate(operation, (() => {
         const {key: key, value: value, type: type} = operation;
         const storage = type === "session" ? sessionStorage : localStorage;
-        storage.setItem(key, value || "");
+        storage.setItem(safeString(key), safeScalar(value));
       }));
       after(document, operation);
     },
+    // Notifications
     consoleLog: operation => {
       before(document, operation);
       operate(operation, (() => {
         const {message: message, level: level} = operation;
-        level && [ "warn", "info", "error" ].includes(level) ? console[level](message || "") : console.log(message || "");
+        level && [ "warn", "info", "error" ].includes(level) ? console[level](message) : console.log(message);
       }));
       after(document, operation);
     },
@@ -577,7 +682,7 @@
       before(document, operation);
       operate(operation, (() => {
         const {data: data, columns: columns} = operation;
-        console.table(data, columns || []);
+        console.table(data, safeArray(columns));
       }));
       after(document, operation);
     },
@@ -587,10 +692,32 @@
         const {title: title, options: options} = operation;
         Notification.requestPermission().then((result => {
           operation.permission = result;
-          if (result === "granted") new Notification(title || "", options);
+          if (result === "granted") new Notification(safeString(title), safeObject(options));
         }));
       }));
       after(document, operation);
+    },
+    // Morph operations
+    morph: operation => {
+      processElements(operation, (element => {
+        const {html: html} = operation;
+        const template = document.createElement("template");
+        template.innerHTML = String(safeScalar(html)).trim();
+        operation.content = template.content;
+        const parent = element.parentElement;
+        const idx = parent && Array.from(parent.children).indexOf(element);
+        before(element, operation);
+        operate(operation, (() => {
+          const {childrenOnly: childrenOnly, focusSelector: focusSelector} = operation;
+          morphdom(element, childrenOnly ? template.content : template.innerHTML, {
+            childrenOnly: !!childrenOnly,
+            onBeforeElUpdated: shouldMorph(operation),
+            onElUpdated: didMorph(operation)
+          });
+          assignFocus(focusSelector);
+        }));
+        after(parent ? parent.children[idx] : document.documentElement, operation);
+      }));
     }
   };
   let operations = Operations;
@@ -613,8 +740,17 @@
       return operations;
     }
   };
+  let missingElement = "warn";
+  var MissingElement$1 = {
+    get behavior() {
+      return missingElement;
+    },
+    set(value) {
+      if ([ "warn", "ignore", "event", "exception" ].includes(value)) missingElement = value; else console.warn("Invalid 'onMissingElement' option. Defaulting to 'warn'.");
+    }
+  };
   const perform = (operations, options = {
-    emitMissingElementWarnings: true
+    onMissingElement: MissingElement$1.behavior
   }) => {
     const batches = {};
     operations.forEach((operation => {
@@ -624,11 +760,15 @@
       const name = operation.operation;
       try {
         if (operation.selector) {
-          operation.element = operation.xpath ? xpathToElement(operation.selector) : document[operation.selectAll ? "querySelectorAll" : "querySelector"](operation.selector);
+          if (operation.xpath) {
+            operation.element = operation.selectAll ? xpathToElementArray(operation.selector) : xpathToElement(operation.selector);
+          } else {
+            operation.element = operation.selectAll ? document.querySelectorAll(operation.selector) : document.querySelector(operation.selector);
+          }
         } else {
           operation.element = document;
         }
-        if (operation.element || options.emitMissingElementWarnings) {
+        if (operation.element || options.onMissingElement !== "ignore") {
           ActiveElement.set(document.activeElement);
           const cableReadyOperation = OperationStore.all[name];
           if (cableReadyOperation) {
@@ -645,13 +785,30 @@
           console.error(`CableReady detected an error in ${name || "operation"}: ${e.message}. If you need to support older browsers make sure you've included the corresponding polyfills. https://docs.stimulusreflex.com/setup#polyfills-for-ie11.`);
           console.error(e);
         } else {
-          console.warn(`CableReady ${name || "operation"} failed due to missing DOM element for selector: '${operation.selector}'`);
+          const warning = `CableReady ${name || ""} operation failed due to missing DOM element for selector: '${operation.selector}'`;
+          switch (options.onMissingElement) {
+           case "ignore":
+            break;
+
+           case "event":
+            dispatch(document, "cable-ready:missing-element", {
+              warning: warning,
+              operation: operation
+            });
+            break;
+
+           case "exception":
+            throw warning;
+
+           default:
+            console.warn(warning);
+          }
         }
       }
     }));
   };
   const performAsync = (operations, options = {
-    emitMissingElementWarnings: true
+    onMissingElement: MissingElement$1.behavior
   }) => new Promise(((resolve, reject) => {
     try {
       resolve(perform(operations, options));
@@ -659,6 +816,33 @@
       reject(err);
     }
   }));
+  class SubscribingElement extends HTMLElement {
+    static get tagName() {
+      throw new Error("Implement the tagName() getter in the inheriting class");
+    }
+    static define() {
+      if (!customElements.get(this.tagName)) {
+        customElements.define(this.tagName, this);
+      }
+    }
+    disconnectedCallback() {
+      if (this.channel) this.channel.unsubscribe();
+    }
+    createSubscription(consumer, channel, receivedCallback) {
+      this.channel = consumer.subscriptions.create({
+        channel: channel,
+        identifier: this.identifier
+      }, {
+        received: receivedCallback
+      });
+    }
+    get preview() {
+      return document.documentElement.hasAttribute("data-turbolinks-preview") || document.documentElement.hasAttribute("data-turbo-preview");
+    }
+    get identifier() {
+      return this.getAttribute("identifier");
+    }
+  }
   let consumer;
   const BACKOFF = [ 25, 50, 75, 100, 200, 250, 500, 800, 1e3, 2e3 ];
   const wait = ms => new Promise((resolve => setTimeout(resolve, ms)));
@@ -681,41 +865,98 @@
       return await getConsumerWithRetry();
     }
   };
-  class SubscribingElement extends HTMLElement {
-    disconnectedCallback() {
-      if (this.channel) this.channel.unsubscribe();
-    }
-    createSubscription(consumer, channel, receivedCallback) {
-      this.channel = consumer.subscriptions.create({
-        channel: channel,
-        identifier: this.identifier
-      }, {
-        received: receivedCallback
-      });
-    }
-    get preview() {
-      return document.documentElement.hasAttribute("data-turbolinks-preview") || document.documentElement.hasAttribute("data-turbo-preview");
-    }
-    get identifier() {
-      return this.getAttribute("identifier");
-    }
-  }
   class StreamFromElement extends SubscribingElement {
+    static get tagName() {
+      return "cable-ready-stream-from";
+    }
     async connectedCallback() {
       if (this.preview) return;
       const consumer = await CableConsumer.getConsumer();
       if (consumer) {
-        this.createSubscription(consumer, "CableReady::Stream", this.performOperations);
+        this.createSubscription(consumer, "CableReady::Stream", this.performOperations.bind(this));
       } else {
-        console.error("The `stream_from` helper cannot connect without an ActionCable consumer.\nPlease run `rails generate cable_ready:helpers` to fix this.");
+        console.error("The `cable_ready_stream_from` helper cannot connect. You must initialize CableReady with an Action Cable consumer.");
       }
     }
     performOperations(data) {
-      if (data.cableReady) perform(data.operations);
+      if (data.cableReady) perform(data.operations, {
+        onMissingElement: this.onMissingElement
+      });
+    }
+    get onMissingElement() {
+      const value = this.getAttribute("missing") || MissingElement$1.behavior;
+      // stream_from does not support raising exceptions on missing elements because there's no way to catch them
+            if ([ "warn", "ignore", "event" ].includes(value)) return value; else {
+        console.warn("Invalid 'missing' attribute. Defaulting to 'warn'.");
+        return "warn";
+      }
     }
   }
+  let debugging = false;
+  var Debug = {
+    get enabled() {
+      return debugging;
+    },
+    get disabled() {
+      return !debugging;
+    },
+    get value() {
+      return debugging;
+    },
+    set(value) {
+      debugging = !!value;
+    },
+    set debug(value) {
+      debugging = !!value;
+    }
+  };
+  const request = (data, blocks) => {
+    if (Debug.disabled) return;
+    console.log(`↑ Updatable request affecting ${blocks.length} element(s): `, {
+      elements: blocks.map((b => b.element)),
+      identifiers: blocks.map((b => b.element.getAttribute("identifier"))),
+      data: data
+    });
+  };
+  const cancel = (timestamp, reason) => {
+    if (Debug.disabled) return;
+    const duration = new Date - timestamp;
+    console.log(`❌ Updatable request canceled after ${duration}ms: ${reason}`);
+  };
+  const response = (timestamp, element, urls) => {
+    if (Debug.disabled) return;
+    const duration = new Date - timestamp;
+    console.log(`↓ Updatable response: All URLs fetched in ${duration}ms`, {
+      element: element,
+      urls: urls
+    });
+  };
+  const morphStart = (timestamp, element) => {
+    if (Debug.disabled) return;
+    const duration = new Date - timestamp;
+    console.log(`↻ Updatable morph: starting after ${duration}ms`, {
+      element: element
+    });
+  };
+  const morphEnd = (timestamp, element) => {
+    if (Debug.disabled) return;
+    const duration = new Date - timestamp;
+    console.log(`↺ Updatable morph: completed after ${duration}ms`, {
+      element: element
+    });
+  };
+  var Log = {
+    request: request,
+    cancel: cancel,
+    response: response,
+    morphStart: morphStart,
+    morphEnd: morphEnd
+  };
   const template = `\n<style>\n  :host {\n    display: block;\n  }\n</style>\n<slot></slot>\n`;
   class UpdatesForElement extends SubscribingElement {
+    static get tagName() {
+      return "cable-ready-updates-for";
+    }
     constructor() {
       super();
       const shadowRoot = this.attachShadow({
@@ -730,14 +971,26 @@
       if (consumer) {
         this.createSubscription(consumer, "CableReady::Stream", this.update);
       } else {
-        console.error("The `updates-for` helper cannot connect without an ActionCable consumer.\nPlease run `rails generate cable_ready:helpers` to fix this.");
+        console.error("The `cable_ready_updates_for` helper cannot connect. You must initialize CableReady with an Action Cable consumer.");
       }
     }
     async update(data) {
-      const blocks = Array.from(document.querySelectorAll(this.query), (element => new Block(element)));
-      if (blocks[0].element !== this) return;
-      ActiveElement.set(document.activeElement);
-      this.html = {};
+      this.lastUpdateTimestamp = new Date;
+      const blocks = Array.from(document.querySelectorAll(this.query), (element => new Block(element))).filter((block => block.shouldUpdate(data)));
+      Log.request(data, blocks);
+      if (blocks.length === 0) {
+        Log.cancel(this.lastUpdateTimestamp, "All elements filtered out");
+        return;
+      }
+      // first <cable-ready-updates-for> element in the DOM *at any given moment* updates all of the others
+            if (blocks[0].element !== this) {
+        Log.cancel(this.lastUpdateTimestamp, "Update already requested");
+        return;
+      }
+      // hold a reference to the active element so that it can be restored after the morph
+            ActiveElement.set(document.activeElement);
+      // store all retrieved HTML in an object keyed by URL to minimize fetch calls
+            this.html = {};
       const uniqueUrls = [ ...new Set(blocks.map((block => block.url))) ];
       await Promise.all(uniqueUrls.map((async url => {
         if (!this.html.hasOwnProperty(url)) {
@@ -747,14 +1000,17 @@
           this.html[url] = await response.text();
         }
       })));
-      this.index = {};
+      Log.response(this.lastUpdateTimestamp, this, uniqueUrls);
+      // track current block index for each URL; referred to as fragments
+            this.index = {};
       blocks.forEach((block => {
+        // if the block's URL is not in the index, initialize it to 0; otherwise, increment it
         this.index.hasOwnProperty(block.url) ? this.index[block.url]++ : this.index[block.url] = 0;
-        block.process(data, this.html, this.index);
+        block.process(data, this.html, this.index, this.lastUpdateTimestamp);
       }));
     }
     get query() {
-      return `updates-for[identifier="${this.identifier}"]`;
+      return `${this.tagName}[identifier="${this.identifier}"]`;
     }
     get identifier() {
       return this.getAttribute("identifier");
@@ -767,8 +1023,7 @@
     constructor(element) {
       this.element = element;
     }
-    async process(data, html, index) {
-      if (!this.shouldUpdate(data)) return;
+    async process(data, html, index, startTimestamp) {
       const blockIndex = index[this.url];
       const template = document.createElement("template");
       this.element.setAttribute("updating", "updating");
@@ -785,7 +1040,8 @@
         permanentAttributeName: "data-ignore-updates"
       };
       dispatch(this.element, "cable-ready:before-update", operation);
-      morphdom__default["default"](this.element, fragments[blockIndex], {
+      Log.morphStart(startTimestamp, this.element);
+      morphdom(this.element, fragments[blockIndex], {
         childrenOnly: true,
         onBeforeElUpdated: shouldMorph(operation),
         onElUpdated: _ => {
@@ -794,6 +1050,7 @@
           assignFocus(operation.focusSelector);
         }
       });
+      Log.morphEnd(startTimestamp, this.element);
     }
     async resolveTurboFrames(documentFragment) {
       const reloadingTurboFrames = [ ...documentFragment.querySelectorAll('turbo-frame[src]:not([loading="lazy"])') ];
@@ -804,19 +1061,26 @@
         });
         const frameTemplate = document.createElement("template");
         frameTemplate.innerHTML = await frameResponse.text();
-        await this.resolveTurboFrames(frameTemplate.content);
-        documentFragment.querySelector(`turbo-frame#${frame.id}`).innerHTML = String(frameTemplate.content.querySelector(`turbo-frame#${frame.id}`).innerHTML).trim();
+        // recurse here to get all nested eager loaded frames
+                await this.resolveTurboFrames(frameTemplate.content);
+        const selector = `turbo-frame#${frame.id}`;
+        const frameContent = frameTemplate.content.querySelector(selector);
+        const content = frameContent ? frameContent.innerHTML.trim() : "";
+        documentFragment.querySelector(selector).innerHTML = content;
         resolve();
       })))));
     }
     shouldUpdate(data) {
+      // if everything that could prevent an update is false, update this block
       return !this.ignoresInnerUpdates && this.hasChangesSelectedForUpdate(data);
     }
     hasChangesSelectedForUpdate(data) {
+      // if there's an only attribute, only update if at least one of the attributes changed is in the allow list
       const only = this.element.getAttribute("only");
       return !(only && data.changed && !only.split(" ").some((attribute => data.changed.includes(attribute))));
     }
     get ignoresInnerUpdates() {
+      // don't update during a Reflex or Turbolinks redraw
       return this.element.hasAttribute("ignore-inner-updates") && this.element.hasAttribute("performing-inner-update");
     }
     get url() {
@@ -846,35 +1110,51 @@
         recursiveUnmarkUpdatesForElements(event.target);
       }));
     }));
+    document.addEventListener("turbo-boost:command:start", (event => {
+      recursiveMarkUpdatesForElements(event.target);
+    }));
+    document.addEventListener("turbo-boost:command:finish", (event => {
+      setTimeout((() => {
+        recursiveUnmarkUpdatesForElements(event.target);
+      }));
+    }));
+    document.addEventListener("turbo-boost:command:error", (event => {
+      setTimeout((() => {
+        recursiveUnmarkUpdatesForElements(event.target);
+      }));
+    }));
   };
   const recursiveMarkUpdatesForElements = leaf => {
-    const closestUpdatesFor = leaf && leaf.parentElement.closest("updates-for");
+    const closestUpdatesFor = leaf && leaf.parentElement && leaf.parentElement.closest("cable-ready-updates-for");
     if (closestUpdatesFor) {
       closestUpdatesFor.setAttribute("performing-inner-update", "");
       recursiveMarkUpdatesForElements(closestUpdatesFor);
     }
   };
   const recursiveUnmarkUpdatesForElements = leaf => {
-    const closestUpdatesFor = leaf && leaf.parentElement.closest("updates-for");
+    const closestUpdatesFor = leaf && leaf.parentElement && leaf.parentElement.closest("cable-ready-updates-for");
     if (closestUpdatesFor) {
       closestUpdatesFor.removeAttribute("performing-inner-update");
       recursiveUnmarkUpdatesForElements(closestUpdatesFor);
     }
   };
-  const initialize = (initializeOptions = {}) => {
-    const {consumer: consumer} = initializeOptions;
+  const defineElements = () => {
     registerInnerUpdates();
+    StreamFromElement.define();
+    UpdatesForElement.define();
+  };
+  const initialize = (initializeOptions = {}) => {
+    const {consumer: consumer, onMissingElement: onMissingElement, debug: debug} = initializeOptions;
+    Debug.set(!!debug);
     if (consumer) {
       CableConsumer.setConsumer(consumer);
     } else {
       console.error("CableReady requires a reference to your Action Cable `consumer` for its helpers to function.\nEnsure that you have imported the `CableReady` package as well as `consumer` from your `channels` folder, then call `CableReady.initialize({ consumer })`.");
     }
-    if (!customElements.get("stream-from")) {
-      customElements.define("stream-from", StreamFromElement);
-    }
-    if (!customElements.get("updates-for")) {
-      customElements.define("updates-for", UpdatesForElement);
+    if (onMissingElement) {
+      MissingElement.set(onMissingElement);
     }
+    defineElements();
   };
   const global = {
     perform: perform,
@@ -903,7 +1183,7 @@
   exports.SubscribingElement = SubscribingElement;
   exports.UpdatesForElement = UpdatesForElement;
   exports.Utils = utils;
-  exports["default"] = global;
+  exports.default = global;
   Object.defineProperty(exports, "__esModule", {
     value: true
   });