@gem-sdk/clarity-js 0.8.94

package/src/interaction/encode.ts

@@ -0,0 +1,217 @@
+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";
+import * as dom from "@src/layout/dom";
+
+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;
+                
+                const info = dom.get(entry.data.target as Node);
+                console.log(`[GemX - Interaction - Encode]`, info);
+                
+                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);
+                tokens.push(entry.data.tag);
+                tokens.push(entry.data.class);
+                tokens.push(entry.data.id);
+                tokens.push(entry.data.source);
+                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);
+                    tokens.push(entry.data.trust);
+                    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,66 @@
+import type { Module } from "@clarity-types/core";
+import config from "@src/core/config";
+
+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";
+import * as pageshow from "@src/interaction/pageshow";
+
+const GEMX: Module[] = [
+    timeline,
+    click,
+    resize,
+    visibility,
+    scroll,
+    pageshow,
+    unload,
+];
+
+const ALL: Module[] = [
+    timeline,
+    click,
+    clipboard,
+    pointer,
+    input,
+    resize,
+    visibility,
+    focus,
+    pageshow,
+    scroll,
+    selection,
+    change,
+    submit,
+    unload
+];
+
+const GEMX_OBSERVE = { allRoots: [scroll], documentOnly: [click] };
+const ALL_OBSERVE = { allRoots: [scroll], documentOnly: [click, clipboard, pointer, input, selection, change, submit] };
+
+let modules: Module[] = ALL;
+
+export function start(): void {
+    modules = config?.mode === "gemx" ? GEMX : ALL;
+    modules.forEach(m => m.start());
+}
+
+export function stop(): void {
+    modules.forEach(m => m.stop());
+}
+
+export function observe(root: Node): void {
+    const observeModules = config?.mode === "gemx" ? GEMX_OBSERVE : ALL_OBSERVE;
+    observeModules.allRoots.forEach(m => m.observe(root));
+    if (root.nodeType === Node.DOCUMENT_NODE) {
+        observeModules.documentOnly.forEach(m => m.observe(root));
+    }
+}

package/src/interaction/input.ts

@@ -0,0 +1,66 @@
+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);
+    bind(root, "keydown", enter, 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 enter(evt: KeyboardEvent): void {
+    if (evt.key === "Enter" && !evt.repeat && state.length > 0) {
+        clearTimeout(timeout);
+        process(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/pageshow.ts

@@ -0,0 +1,35 @@
+import { Constant } from "@clarity-types/core";
+import { Code, Severity } from "@clarity-types/data";
+import * as clarity from "@src/clarity";
+import api from "@src/core/api";
+import measure from "@src/core/measure";
+import * as internal from "@src/diagnostic/internal";
+
+let bound = false;
+
+export function start(): void {
+    // Only bind once - this listener must persist even when Clarity stops
+    // to detect when the page is restored from bfcache
+    if (!bound) {
+        try {
+            window[api(Constant.AddEventListener)]("pageshow", measure(handler) as EventListener, { capture: false, passive: true });
+            bound = true;
+        } catch {
+            /* do nothing */
+        }
+    }
+}
+
+function handler(evt: PageTransitionEvent): void {
+    // The persisted property indicates if the page was loaded from bfcache
+    if (evt && evt.persisted) {
+        // Restart Clarity since it was stopped when the page entered bfcache
+        clarity.start();
+        internal.log(Code.BFCache, Severity.Info);
+    }
+}
+
+export function stop(): void {
+    // Intentionally don't remove the listener or reset 'bound' flag
+    // We need the listener to persist to detect bfcache restoration
+}

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();
+}