feat(core dom): Implement get_visible_ratio to calculate the visible ratio between an element and a container.

Author: thet

src/core/dom.js

@@ -368,6 +368,44 @@ const template = (template_string, template_variables = {}) => {
     return new Function("return `" + template_string + "`;").call(template_variables);
 };
 
+/**
+ * Get the visible ratio of an element compared to container.
+ * If no container is given, the viewport is used.
+ *
+ * Note: currently only vertical ratio is supported.
+ *
+ * @param {Node} el - The element to get the visible ratio from.
+ * @param {Node} [container] - The container to compare the element to.
+ * @returns {number} - The visible ratio of the element.
+ *                    0 means the element is not visible.
+ *                    1 means the element is fully visible.
+ */
+const get_visible_ratio = (el, container) => {
+    if (!el) {
+        return 0;
+    }
+
+    const rect = el.getBoundingClientRect();
+    const container_rect =
+        container !== window
+            ? container.getBoundingClientRect()
+            : {
+                  top: 0,
+                  bottom: window.innerHeight,
+              };
+
+    let visible_ratio = 0;
+    if (rect.top < container_rect.bottom && rect.bottom > container_rect.top) {
+        const rect_height = rect.bottom - rect.top;
+        const visible_height =
+            Math.min(rect.bottom, container_rect.bottom) -
+            Math.max(rect.top, container_rect.top);
+        visible_ratio = visible_height / rect_height;
+    }
+
+    return visible_ratio;
+};
+
 const dom = {
     toNodeArray: toNodeArray,
     querySelectorAllAndMe: querySelectorAllAndMe,
@@ -389,6 +427,7 @@ const dom = {
     set_data: set_data,
     delete_data: delete_data,
     template: template,
+    get_visible_ratio: get_visible_ratio,
     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

@@ -806,4 +806,53 @@ describe("core.dom tests", () => {
             done();
         });
     });
+
+    describe("get_visible_ratio", () => {
+        it("returns 0 if the element is not given", (done) => {
+            expect(dom.get_visible_ratio()).toBe(0);
+            done();
+        });
+
+        it("container = window, returns 0 if the element is not visible", (done) => {
+            const el = document.createElement("div");
+            jest.spyOn(el, "getBoundingClientRect").mockImplementation(() => {
+                return {
+                    top: 200,
+                    bottom: 300,
+                };
+            });
+            jest.replaceProperty(window, "innerHeight", 100);
+
+            expect(dom.get_visible_ratio(el, window)).toBe(0);
+            done();
+        });
+
+        it("container = window, returns 0.5 if the element is half-visible", (done) => {
+            const el = document.createElement("div");
+            jest.spyOn(el, "getBoundingClientRect").mockImplementation(() => {
+                return {
+                    top: 50,
+                    bottom: 150,
+                };
+            });
+            jest.replaceProperty(window, "innerHeight", 100);
+
+            expect(dom.get_visible_ratio(el, window)).toBe(0.5);
+            done();
+        });
+
+        it("container = window, returns 1 if the element is fully visible", (done) => {
+            const el = document.createElement("div");
+            jest.spyOn(el, "getBoundingClientRect").mockImplementation(() => {
+                return {
+                    top: 0,
+                    bottom: 100,
+                };
+            });
+            jest.replaceProperty(window, "innerHeight", 100);
+
+            expect(dom.get_visible_ratio(el, window)).toBe(1);
+            done();
+        });
+    });
 });