@gemx-dev/clarity-js 0.8.39

package/src/interaction/encode.ts

@@ -0,0 +1,207 @@
+import { Constant, Event, Token } from "@clarity-types/data";
+import * as scrub from "@src/core/scrub";
+import { time } from "@src/core/time";
+import * as baseline from "@src/data/baseline";
+import { queue } from "@src/data/upload";
+import { metadata } from "@src/layout/target";
+import * as change from "@src/interaction/change";
+import * as click from "@src/interaction/click";
+import * as clipboard from "@src/interaction/clipboard";
+import * as input from "@src/interaction/input";
+import * as pointer from "@src/interaction/pointer";
+import * as resize from "@src/interaction/resize";
+import * as scroll from "@src/interaction/scroll";
+import * as selection from "@src/interaction/selection";
+import * as submit from "@src/interaction/submit";
+import * as timeline from "@src/interaction/timeline";
+import * as unload from "@src/interaction/unload";
+import * as visibility from "@src/interaction/visibility";
+import * as focus from "@src/interaction/focus";
+
+export default async function (type: Event, ts: number = null): Promise<void> {
+    let t = ts || time();
+    let tokens: Token[] = [t, type];
+    switch (type) {
+        case Event.MouseDown:
+        case Event.MouseUp:
+        case Event.MouseMove:
+        case Event.MouseWheel:
+        case Event.DoubleClick:
+        case Event.TouchStart:
+        case Event.TouchEnd:
+        case Event.TouchMove:
+        case Event.TouchCancel:
+            for (let entry of pointer.state) {
+                let pTarget = metadata(entry.data.target as Node, entry.event);
+                if (pTarget.id > 0) {
+                    tokens = [entry.time, entry.event];
+                    tokens.push(pTarget.id);
+                    tokens.push(entry.data.x);
+                    tokens.push(entry.data.y);
+                    if (entry.data.id !== undefined) { 
+                        tokens.push(entry.data.id); 
+
+                        if (entry.data.isPrimary !== undefined) {
+                            tokens.push(entry.data.isPrimary.toString());
+                        }
+                    }
+                    queue(tokens);
+                    if (entry.data.isPrimary === undefined || entry.data.isPrimary) {
+                        baseline.track(entry.event, entry.data.x, entry.data.y, entry.time);
+                    }
+                }
+            }
+            pointer.reset();
+            break;
+        case Event.Click:
+        case Event.ContextMenu:
+            for (let entry of click.state) {
+                let cTarget = metadata(entry.data.target as Node, entry.event, entry.data.text);
+                tokens = [entry.time, entry.event];
+                let cHash = cTarget.hash ? cTarget.hash.join(Constant.Dot) : Constant.Empty;
+                tokens.push(cTarget.id);
+                tokens.push(entry.data.x);
+                tokens.push(entry.data.y);
+                tokens.push(entry.data.eX);
+                tokens.push(entry.data.eY);
+                tokens.push(entry.data.button);
+                tokens.push(entry.data.reaction);
+                tokens.push(entry.data.context);
+                tokens.push(scrub.text(entry.data.text, "click", cTarget.privacy));
+                tokens.push(scrub.url(entry.data.link));
+                tokens.push(cHash);
+                tokens.push(entry.data.trust);
+                tokens.push(entry.data.isFullText);
+                tokens.push(entry.data.w);
+                tokens.push(entry.data.h);
+                queue(tokens);
+                timeline.track(entry.time, entry.event, cHash, entry.data.x, entry.data.y, entry.data.reaction, entry.data.context);
+            }
+            click.reset();
+            break;
+        case Event.Clipboard:
+            for (let entry of clipboard.state) {
+                tokens = [entry.time, entry.event];
+                let target = metadata(entry.data.target as Node, entry.event);
+                if (target.id > 0) {
+                    tokens.push(target.id);
+                    tokens.push(entry.data.action);
+                    queue(tokens);
+                }
+            }
+            clipboard.reset();
+            break;
+        case Event.Resize:
+            let r = resize.data;
+            tokens.push(r.width);
+            tokens.push(r.height);
+            baseline.track(type, r.width, r.height);
+            resize.reset();
+            queue(tokens);
+            break;
+        case Event.Unload:
+            let u = unload.data;
+            tokens.push(u.name);
+            tokens.push(u.persisted);
+            unload.reset();
+            queue(tokens);
+            break;
+        case Event.Input:
+            for (let entry of input.state) {
+                let iTarget = metadata(entry.data.target as Node, entry.event, entry.data.value);
+                tokens = [entry.time, entry.event];
+                tokens.push(iTarget.id);
+                tokens.push(scrub.text(entry.data.value, "input", iTarget.privacy, false, entry.data.type));
+                tokens.push(entry.data.trust);
+                queue(tokens);
+            }
+            input.reset();
+            break;
+        case Event.Selection:
+            let s = selection.data;
+            if (s) {
+                let startTarget = metadata(s.start as Node, type);
+                let endTarget = metadata(s.end as Node, type);
+                tokens.push(startTarget.id);
+                tokens.push(s.startOffset);
+                tokens.push(endTarget.id);
+                tokens.push(s.endOffset);
+                selection.reset();
+                queue(tokens);
+            }
+            break;
+        case Event.Scroll:
+            for (let entry of scroll.state) {
+                let sTarget = metadata(entry.data.target as Node, entry.event);
+                const top = metadata(entry.data.top as Node, entry.event);
+                const bottom = metadata(entry.data.bottom as Node, entry.event);
+                const sTopHash = top?.hash ? top.hash.join(Constant.Dot) : Constant.Empty;
+                const sBottomHash = bottom?.hash ? bottom.hash.join(Constant.Dot) : Constant.Empty;
+                if (sTarget.id > 0) {
+                    tokens = [entry.time, entry.event];
+                    tokens.push(sTarget.id);
+                    tokens.push(entry.data.x);
+                    tokens.push(entry.data.y);
+                    tokens.push(sTopHash);
+                    tokens.push(sBottomHash);
+                    queue(tokens);
+                    baseline.track(entry.event, entry.data.x, entry.data.y, entry.time);
+                }
+            }
+            scroll.reset();
+            break;
+        case Event.Change:
+            for (let entry of change.state) {
+                tokens = [entry.time, entry.event];
+                let target = metadata(entry.data.target as Node, entry.event);
+                if (target.id > 0) {
+                    tokens = [entry.time, entry.event];
+                    tokens.push(target.id);
+                    tokens.push(entry.data.type);
+                    tokens.push(scrub.text(entry.data.value, "change", target.privacy));
+                    tokens.push(scrub.text(entry.data.checksum, "checksum", target.privacy));
+                    queue(tokens);
+                }
+            }
+            change.reset();
+            break;
+        case Event.Submit:
+            for (let entry of submit.state) {
+                tokens = [entry.time, entry.event];
+                let target = metadata(entry.data.target as Node, entry.event);
+                if (target.id > 0) {
+                    tokens.push(target.id);
+                    queue(tokens);
+                }
+            }
+            submit.reset();
+            break;
+        case Event.Timeline:
+            for (let entry of timeline.updates) {
+                tokens = [entry.time, entry.event];
+                tokens.push(entry.data.type);
+                tokens.push(entry.data.hash);
+                tokens.push(entry.data.x);
+                tokens.push(entry.data.y);
+                tokens.push(entry.data.reaction);
+                tokens.push(entry.data.context);
+                queue(tokens, false);
+            }
+            timeline.reset();
+            break;
+        case Event.Visibility:
+            let v = visibility.data;
+            tokens.push(v.visible);
+            queue(tokens);
+            baseline.visibility(t, v.visible);
+            visibility.reset();
+            break;
+        case Event.Focus: {
+            let f = focus.data;
+            tokens.push(f.focused);
+            queue(tokens, false);
+            focus.reset();
+            break;
+        }
+    }
+}

package/src/interaction/focus.ts

@@ -0,0 +1,25 @@
+import { BooleanFlag, Event } from "@clarity-types/data";
+import { FocusData } from "@clarity-types/interaction";
+import { bind } from "@src/core/event";
+import encode from "./encode";
+
+export let data: FocusData;
+
+export function start(): void {
+  bind(window, "focus", () => compute(BooleanFlag.True));
+  bind(window, "blur", () => compute(BooleanFlag.False));
+}
+
+export function stop(): void {
+  reset();
+}
+
+export function reset(): void {
+  data = null;
+}
+
+function compute(focus: BooleanFlag): void {
+  data = { focused: focus };
+
+  encode(Event.Focus);
+}

package/src/interaction/index.ts

@@ -0,0 +1,60 @@
+import * as change from "@src/interaction/change";
+import * as click from "@src/interaction/click";
+import * as clipboard from "@src/interaction/clipboard";
+import * as input from "@src/interaction/input";
+import * as pointer from "@src/interaction/pointer";
+import * as resize from "@src/interaction/resize";
+import * as scroll from "@src/interaction/scroll";
+import * as selection from "@src/interaction/selection";
+import * as submit from "@src/interaction/submit";
+import * as timeline from "@src/interaction/timeline";
+import * as unload from "@src/interaction/unload";
+import * as visibility from "@src/interaction/visibility";
+import * as focus from "@src/interaction/focus";
+
+export function start(): void {
+    timeline.start();
+    click.start();
+    clipboard.start();
+    pointer.start();
+    input.start();
+    resize.start();
+    visibility.start();
+    focus.start();
+    scroll.start();
+    selection.start();
+    change.start();
+    submit.start();
+    unload.start();
+}
+
+export function stop(): void {
+    timeline.stop();
+    click.stop();
+    clipboard.stop();
+    pointer.stop();
+    input.stop();
+    resize.stop();
+    visibility.stop();
+    focus.stop();
+    scroll.stop();
+    selection.stop();
+    change.stop();
+    submit.stop();
+    unload.stop()
+}
+
+export function observe(root: Node): void {
+    scroll.observe(root);
+    // Only monitor following interactions if the root node is a document
+    // In case of shadow DOM, following events automatically bubble up to the parent document.
+    if (root.nodeType === Node.DOCUMENT_NODE) {
+        click.observe(root);
+        clipboard.observe(root);
+        pointer.observe(root);
+        input.observe(root);
+        selection.observe(root);
+        change.observe(root);
+        submit.observe(root);
+    }
+}

package/src/interaction/input.ts

@@ -0,0 +1,58 @@
+import { BooleanFlag, Event } from "@clarity-types/data";
+import { InputData, InputState, Setting } from "@clarity-types/interaction";
+import { bind } from "@src/core/event";
+import { schedule } from "@src/core/task";
+import { time } from "@src/core/time";
+import { clearTimeout, setTimeout } from "@src/core/timeout";
+import { get } from "@src/layout/dom";
+import encode from "./encode";
+import { target } from "@src/layout/target";
+
+let timeout: number = null;
+export let state: InputState[] = [];
+
+export function start(): void {
+    reset();
+}
+
+export function observe(root: Node): void {
+    bind(root, "input", recompute, true);
+}
+
+function recompute(evt: UIEvent): void {
+    let input = target(evt) as HTMLInputElement;
+    let value = get(input);
+    if (input && input.type && value) {
+        let v = input.value;
+        let t = input.type;
+        switch (input.type) {
+            case "radio":
+            case "checkbox":
+                v = input.checked ? "true" : "false";
+                break;
+        }
+
+        let data: InputData = { target: input, value: v, type: t, trust: evt.isTrusted ? BooleanFlag.True : BooleanFlag.False };
+
+        // If last entry in the queue is for the same target node as the current one, remove it so we can later swap it with current data.
+        if (state.length > 0 && (state[state.length - 1].data.target === data.target)) { state.pop(); }
+
+        state.push({ time: time(evt), event: Event.Input, data });
+
+        clearTimeout(timeout);
+        timeout = setTimeout(process, Setting.InputLookAhead, Event.Input);
+    }
+}
+
+function process(event: Event): void {
+    schedule(encode.bind(this, event));
+}
+
+export function reset(): void {
+    state = [];
+}
+
+export function stop(): void {
+    clearTimeout(timeout);
+    reset();
+}

package/src/interaction/pointer.ts

@@ -0,0 +1,137 @@
+import { Event } from "@clarity-types/data";
+import { PointerState, Setting } from "@clarity-types/interaction";
+import { bind } from "@src/core/event";
+import { schedule } from "@src/core/task";
+import { time } from "@src/core/time";
+import { clearTimeout, setTimeout } from "@src/core/timeout";
+import { iframe } from "@src/layout/dom";
+import { offset } from "@src/layout/offset";
+import { target } from "@src/layout/target";
+import encode from "./encode";
+
+export let state: PointerState[] = [];
+let timeout: number = null;
+let hasPrimaryTouch = false;
+let primaryTouchId = 0;
+const activeTouchPointIds = new Set<number>();
+
+export function start(): void {
+    reset();
+}
+
+export function observe(root: Node): void {
+    bind(root, "mousedown", mouse.bind(this, Event.MouseDown, root), true);
+    bind(root, "mouseup", mouse.bind(this, Event.MouseUp, root), true);
+    bind(root, "mousemove", mouse.bind(this, Event.MouseMove, root), true);
+    bind(root, "wheel", mouse.bind(this, Event.MouseWheel, root), true);
+    bind(root, "dblclick", mouse.bind(this, Event.DoubleClick, root), true);
+    bind(root, "touchstart", touch.bind(this, Event.TouchStart, root), true);
+    bind(root, "touchend", touch.bind(this, Event.TouchEnd, root), true);
+    bind(root, "touchmove", touch.bind(this, Event.TouchMove, root), true);
+    bind(root, "touchcancel", touch.bind(this, Event.TouchCancel, root), true);
+}
+
+function mouse(event: Event, root: Node, evt: MouseEvent): void {
+    let frame = iframe(root);
+    let d = frame && frame.contentDocument ? frame.contentDocument.documentElement : document.documentElement;
+    let x = "pageX" in evt ? Math.round(evt.pageX) : ("clientX" in evt ? Math.round(evt["clientX"] + d.scrollLeft) : null);
+    let y = "pageY" in evt ? Math.round(evt.pageY) : ("clientY" in evt ? Math.round(evt["clientY"] + d.scrollTop) : null);
+    // In case of iframe, we adjust (x,y) to be relative to top parent's origin
+    if (frame) {
+        let distance = offset(frame);
+        x = x ? x + Math.round(distance.x) : x;
+        y = y ? y + Math.round(distance.y) : y;
+    }
+
+    // Check for null values before processing this event
+    if (x !== null && y !== null) { handler({ time: time(evt), event, data: { target: target(evt), x, y } }); }
+}
+
+function touch(event: Event, root: Node, evt: TouchEvent): void {
+    let frame = iframe(root);
+    let d = frame && frame.contentDocument ? frame.contentDocument.documentElement : document.documentElement;
+    let touches = evt.changedTouches;
+
+    let t = time(evt);
+    if (touches) {
+        for (let i = 0; i < touches.length; i++) {
+            let entry = touches[i];
+            let x = "clientX" in entry ? Math.round(entry["clientX"] + d.scrollLeft) : null;
+            let y = "clientY" in entry ? Math.round(entry["clientY"] + d.scrollTop) : null;
+            x = x && frame ? x + Math.round(frame.offsetLeft) : x;
+            y = y && frame ? y + Math.round(frame.offsetTop) : y;
+
+            // We cannot rely on identifier to determine primary touch as its value doesn't always start with 0.
+            // Safari/Webkit uses the address of the UITouch object as the identifier value for each touch point.
+            const id = "identifier" in entry ? entry["identifier"] : undefined;
+
+            switch(event) {
+                case Event.TouchStart:
+                    if (activeTouchPointIds.size === 0) {
+                        // Track presence of primary touch separately to handle scenarios when same id is repeated
+                        hasPrimaryTouch = true;  
+                        primaryTouchId = id;
+                    }
+                    activeTouchPointIds.add(id);
+                    break;
+                case Event.TouchEnd:
+                case Event.TouchCancel:
+                    activeTouchPointIds.delete(id);
+                    break;
+            }
+            const isPrimary = hasPrimaryTouch && primaryTouchId === id;
+
+            // Check for null values before processing this event
+            if (x !== null && y !== null) { handler({ time: t, event, data: { target: target(evt), x, y, id, isPrimary } }); }
+
+            // Reset primary touch point id once touch event ends
+            if (event === Event.TouchCancel || event === Event.TouchEnd) {
+                if (primaryTouchId === id) { hasPrimaryTouch = false; }
+            }
+        }
+    }
+}
+
+function handler(current: PointerState): void {
+    switch (current.event) {
+        case Event.MouseMove:
+        case Event.MouseWheel:
+        case Event.TouchMove:
+            let length = state.length;
+            let last = length > 1 ? state[length - 2] : null;
+            if (last && similar(last, current)) { state.pop(); }
+            state.push(current);
+
+            clearTimeout(timeout);
+            timeout = setTimeout(process, Setting.LookAhead, current.event);
+            break;
+        default:
+            state.push(current);
+            process(current.event);
+            break;
+    }
+}
+
+function process(event: Event): void {
+    schedule(encode.bind(this, event));
+}
+
+export function reset(): void {
+    state = [];
+}
+
+function similar(last: PointerState, current: PointerState): boolean {
+    let dx = last.data.x - current.data.x;
+    let dy = last.data.y - current.data.y;
+    let distance = Math.sqrt(dx * dx + dy * dy);
+    let gap = current.time - last.time;
+    let match = current.data.target === last.data.target;
+    let sameId = current.data.id !== undefined ? current.data.id === last.data.id : true;
+    return current.event === last.event && match && distance < Setting.Distance && gap < Setting.PointerInterval && sameId;
+}
+
+export function stop(): void {
+    clearTimeout(timeout);
+    // Send out any pending pointer events in the pipeline
+    if (state.length > 0) { process(state[state.length - 1].event); }
+}

package/src/interaction/resize.ts

@@ -0,0 +1,50 @@
+import { Event } from "@clarity-types/data";
+import { ResizeData, Setting } from "@clarity-types/interaction";
+import { clearTimeout, setTimeout } from "@src/core/timeout";
+import { bind } from "@src/core/event";
+import throttle from "@src/core/throttle";
+import encode from "./encode";
+import { schedule } from "@src/core/task";
+
+export let data: ResizeData;
+let timeout: number = null;
+let initialStateLogged = false;
+
+const throttledRecompute = throttle(recompute, Setting.LookAhead);
+
+export function start(): void {
+    initialStateLogged = false;
+    bind(window, "resize", throttledRecompute);
+    recompute();
+}
+
+function recompute(): void {
+    let de = document.documentElement;
+    // window.innerWidth includes width of the scrollbar and is not a true representation of the viewport width.
+    // Therefore, when possible, use documentElement's clientWidth property.
+    data = {
+        width: de && "clientWidth" in de ? Math.min(de.clientWidth, window.innerWidth) : window.innerWidth,
+        height: de && "clientHeight" in de ? Math.min(de.clientHeight, window.innerHeight) : window.innerHeight,
+    };
+    if (initialStateLogged) {
+        clearTimeout(timeout);
+        timeout = setTimeout(process, Setting.LookAhead, Event.Resize);
+    } else {
+        encode(Event.Resize);
+        initialStateLogged = true;
+    }
+}
+
+function process(event: Event): void {
+    schedule(encode.bind(this, event));
+}
+
+export function reset(): void {
+    data = null;
+    clearTimeout(timeout);
+    throttledRecompute.cleanup();
+}
+
+export function stop(): void {
+    reset();
+}

package/src/interaction/scroll.ts

@@ -0,0 +1,129 @@
+import { Constant, Dimension, Event } from "@clarity-types/data";
+import { ScrollState, Setting } from "@clarity-types/interaction";
+import { bind } from "@src/core/event";
+import { schedule } from "@src/core/task";
+import { time } from "@src/core/time";
+import { clearTimeout, setTimeout } from "@src/core/timeout";
+import throttle from "@src/core/throttle";
+import { iframe } from "@src/layout/dom";
+import { target, metadata } from "@src/layout/target";
+import encode from "./encode";
+import * as dimension from "@src/data/dimension";
+
+export let state: ScrollState[] = [];
+let initialTop: Node = null;
+let initialBottom: Node = null;
+let timeout: number = null;
+
+export function start(): void {
+    state = [];
+    recompute();
+}
+
+export function observe(root: Node): void {
+    let frame = iframe(root);
+    let node = frame ? frame.contentWindow : (root === document ? window : root);
+    bind(node, "scroll", throttledRecompute, true);
+}
+
+function recompute(event: UIEvent = null): void {
+    let w = window as Window;
+    let de = document.documentElement;
+    let element = event ? target(event) : de;
+
+    // In some edge cases, it's possible for target to be null.
+    // In those cases, we cannot proceed with scroll event instrumentation.
+    if (!element) { return; }
+
+    // If the target is a Document node, then identify corresponding documentElement and window for this document
+    if (element && element.nodeType === Node.DOCUMENT_NODE) {
+        let frame = iframe(element);
+        w = frame ? frame.contentWindow : w;
+        element = de = (element as Document).documentElement;
+    }
+
+    // Edge doesn't support scrollTop position on document.documentElement.
+    // For cross browser compatibility, looking up pageYOffset on window if the scroll is on document.
+    // And, if for some reason that is not available, fall back to looking up scrollTop on document.documentElement.
+    let x = element === de && "pageXOffset" in w ? Math.round(w.pageXOffset) : Math.round((element as HTMLElement).scrollLeft);
+    let y = element === de && "pageYOffset" in w ? Math.round(w.pageYOffset) : Math.round((element as HTMLElement).scrollTop);
+    const width = window.innerWidth;
+    const height = window.innerHeight;
+    const xPosition = width / 3;
+    const yOffset = width > height ? height * 0.15 : height * 0.2;
+    const startYPosition = yOffset;
+    const endYPosition = height - yOffset;
+    const top = getPositionNode(xPosition, startYPosition);
+    const bottom = getPositionNode(xPosition, endYPosition);
+
+    let current: ScrollState = { time: time(event), event: Event.Scroll, data: {target: element, x, y, top, bottom} };
+
+    // We don't send any scroll events if this is the first event and the current position is top (0,0)
+    if ((event === null && x === 0 && y === 0) || (x === null || y === null)) {
+        initialTop = top;
+        initialBottom = bottom;
+        return;
+    }
+
+    let length = state.length;
+    let last = length > 1 ? state[length - 2] : null;
+    if (last && similar(last, current)) { state.pop(); }
+    state.push(current);
+
+    clearTimeout(timeout);
+    timeout = setTimeout(process, Setting.LookAhead, Event.Scroll);
+}
+
+const throttledRecompute = throttle(recompute, Setting.Throttle);
+
+function getPositionNode(x: number, y: number): Node {
+    let node: Node;
+    if ("caretPositionFromPoint" in document) {
+        node = (document as any).caretPositionFromPoint(x, y)?.offsetNode;
+    } else if ("caretRangeFromPoint" in document) {
+        node = (document as any).caretRangeFromPoint(x, y)?.startContainer;
+    }
+    if (!node) {
+        node = document.elementFromPoint(x, y) as Node;
+    }
+    if (node && node.nodeType === Node.TEXT_NODE) {
+        node = node.parentNode;
+    }
+
+    return node;
+}
+
+export function reset(): void {
+    state = [];
+    initialTop = null;
+    initialBottom = null;
+}
+
+function process(event: Event): void {
+    schedule(encode.bind(this, event));
+}
+
+function similar(last: ScrollState, current: ScrollState): boolean {
+    let dx = last.data.x - current.data.x;
+    let dy = last.data.y - current.data.y;
+    return (dx * dx + dy * dy < Setting.Distance * Setting.Distance) && (current.time - last.time < Setting.ScrollInterval);
+}
+
+export function compute(): void {
+    if (initialTop) {
+        const top = metadata(initialTop, null);
+        dimension.log(Dimension.InitialScrollTop, top?.hash?.join(Constant.Dot));
+    }
+    if (initialBottom) {
+        const bottom = metadata(initialBottom, null);
+        dimension.log(Dimension.InitialScrollBottom, bottom?.hash?.join(Constant.Dot));
+    }
+}
+
+export function stop(): void {
+    clearTimeout(timeout);
+    throttledRecompute.cleanup();
+    state = [];
+    initialTop = null;
+    initialBottom = null;
+}