feat(core dom): Add dom.element_uuid to get/set an uuid to a DOM node.

Author: thet

src/core/dom.js

@@ -529,6 +529,34 @@ const escape_css_id = (id) => {
     return `#${CSS.escape(id.split("#")[1])}`;
 };
 
+/**
+ * Get a universally unique id (uuid) for a DOM element.
+ *
+ * This method returns a uuid for the given element. On the first call it will
+ * generate a uuid and store it on the element.
+ *
+ * @param {Node} el - The DOM node to get the uuid for.
+ * @returns {String} - The uuid.
+ */
+const element_uuid = (el) => {
+    if (!get_data(el, "uuid", false)) {
+        let uuid;
+        if (window.crypto.randomUUID) {
+            // Create a real UUID
+            // window.crypto.randomUUID does only exist in browsers with secure
+            // context.
+            // See: https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID
+            uuid = window.crypto.randomUUID();
+        } else {
+            // Create a sufficiently unique ID
+            const array = new Uint32Array(4);
+            uuid = window.crypto.getRandomValues(array).join("");
+        }
+        set_data(el, "uuid", uuid);
+    }
+    return get_data(el, "uuid");
+};
+
 const dom = {
     toNodeArray: toNodeArray,
     querySelectorAllAndMe: querySelectorAllAndMe,
@@ -556,6 +584,7 @@ const dom = {
     template: template,
     get_visible_ratio: get_visible_ratio,
     escape_css_id: escape_css_id,
+    element_uuid: element_uuid,
     add_event_listener: events.add_event_listener, // BBB export. TODO: Remove in an upcoming version.
     remove_event_listener: events.remove_event_listener, // BBB export. TODO: Remove in an upcoming version.
 };

src/core/dom.test.js

@@ -874,3 +874,32 @@ describe("escape_css_id", function () {
         expect(dom.escape_css_id("#-1-2-3")).toBe("#-\\31 -2-3");
     });
 });
+
+describe("element_uuid", function () {
+    it("returns a UUIDv4 for an element", function () {
+        const el = document.createElement("div");
+        const uuid = dom.element_uuid(el);
+        expect(uuid).toMatch(
+            /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+        );
+
+        // The UUID isn't created anew when called again.
+        expect(dom.element_uuid(el)).toBe(uuid);
+    });
+
+    it("returns a sufficiently unique id for an element", function () {
+        // Mock window.crypto.randomUUID not existing, like in browser with
+        // non-secure context.
+        const orig_randomUUID = window.crypto.randomUUID;
+        window.crypto.randomUUID = undefined;
+
+        const el = document.createElement("div");
+        const uuid = dom.element_uuid(el);
+        expect(uuid).toMatch(/^[0-9]*$/);
+
+        // The UUID isn't created anew when called again.
+        expect(dom.element_uuid(el)).toBe(uuid);
+
+        window.crypto.randomUUID = orig_randomUUID;
+    });
+});

src/setup-tests.js

@@ -22,3 +22,7 @@ dom.is_visible = (el) => {
 
 // polyfill css.escape for jsdom
 import("css.escape");
+
+// NodeJS polyfill for window.crypto.randomUUID
+import crypto from "crypto";
+window.crypto.randomUUID = () => crypto.randomUUID();