feat(core dom): Add document_ready function which ensures callbacks to be run when or after the DOM has been loaded.

Author: thet

src/core/dom.js

@@ -1,4 +1,5 @@
 /* Utilities for DOM traversal or navigation */
+import events from "./events";
 import logging from "./logging";
 import create_uuid from "./uuid";
 
@@ -9,6 +10,30 @@ const DATA_STYLE_DISPLAY = "__patternslib__style__display";
 
 const INPUT_SELECTOR = "input, select, textarea, button";
 
+/**
+ * Wait for the document to be ready.
+ *
+ * @param {Function} fn - The function to call when the document is ready.
+ */
+const document_ready = (fn) => {
+    const event_id = create_uuid();
+
+    const _ready = () => {
+        if (document.readyState !== "loading") {
+            // Remove the event listener for this callback.
+            events.remove_event_listener(document, event_id);
+            // call on next available tick
+            setTimeout(fn, 1);
+        }
+    };
+
+    // Listen for the document to be ready and call _ready() when it is.
+    events.add_event_listener(document, "readystatechange", event_id, _ready);
+
+    // Also check the ready state immediately in case we missed the event.
+    _ready();
+};
+
 /**
  * Return an array of DOM nodes.
  *
@@ -575,6 +600,7 @@ const find_inputs = (el) => {
 };
 
 const dom = {
+    document_ready: document_ready,
     toNodeArray: toNodeArray,
     querySelectorAllAndMe: querySelectorAllAndMe,
     wrap: wrap,

src/core/dom.test.js

@@ -1,11 +1,91 @@
 import $ from "jquery";
 import dom from "./dom";
+import utils from "./utils";
 
 describe("core.dom tests", () => {
     // Tests from the core.dom module
 
     afterEach(() => {
         document.body.innerHTML = "";
+        jest.restoreAllMocks();
+    });
+
+    describe("document_ready", () => {
+        it("calls the callback, once the document is ready.", async () => {
+            let cnt = 0;
+            const counter = () => {
+                cnt++;
+            };
+
+            // Call document ready immediately. It should already call the
+            // callback, if ready. Which it isn't.
+            jest.spyOn(document, "readyState", "get").mockReturnValue("loading");
+            dom.document_ready(counter);
+            await utils.timeout(1);
+            expect(cnt).toBe(0);
+
+            // While readyState "loading" the callback should not be called.
+            document.dispatchEvent(new Event("readystatechange"));
+            await utils.timeout(1);
+            expect(cnt).toBe(0);
+
+            // While still loading the callback should still not be called.
+            document.dispatchEvent(new Event("readystatechange"));
+            await utils.timeout(1);
+            expect(cnt).toBe(0);
+
+            // Now it's the time.
+            jest.spyOn(document, "readyState", "get").mockReturnValue("complete");
+            document.dispatchEvent(new Event("readystatechange"));
+            await utils.timeout(1);
+            expect(cnt).toBe(1);
+
+            // But the callback is only called once and the event handler removed from the document.
+            document.dispatchEvent(new Event("readystatechange"));
+            await utils.timeout(1);
+            expect(cnt).toBe(1);
+        });
+
+        it("it will also fire on readyState interactive, not only complete.", async () => {
+            let cnt = 0;
+            const counter = () => {
+                cnt++;
+            };
+
+            // Call document ready immediately. It should already call the
+            // callback, if ready. Which it isn't.
+            jest.spyOn(document, "readyState", "get").mockReturnValue("loading");
+            dom.document_ready(counter);
+            await utils.timeout(1);
+            expect(cnt).toBe(0);
+
+            // When readyState interactive, the callback should be called.
+            jest.spyOn(document, "readyState", "get").mockReturnValue("interactive");
+            document.dispatchEvent(new Event("readystatechange"));
+            await utils.timeout(1);
+            expect(cnt).toBe(1);
+        });
+
+        it("the callback will be called immedeately if the ready state change has already happended.", async () => {
+            let cnt = 0;
+            const counter = () => {
+                cnt++;
+            };
+
+            // Call document ready immediately. It should already call the
+            // callback, if ready. Which it isn't.
+            jest.spyOn(document, "readyState", "get").mockReturnValue("complete");
+            dom.document_ready(counter);
+            await utils.timeout(1);
+            expect(cnt).toBe(1);
+
+            // But another state change would not call the callback, because
+            // the event listener is already de-registered.
+            jest.spyOn(document, "readyState", "get").mockReturnValue("interactive");
+            document.dispatchEvent(new Event("readystatechange"));
+            await utils.timeout(1);
+            expect(cnt).toBe(1);
+        });
     });
 
     describe("toNodeArray tests", () => {