@gem-sdk/clarity-js 0.8.94

package/src/interaction/scroll.ts

@@ -0,0 +1,134 @@
+import { BooleanFlag, 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 trustedCallback: (() => void) | null = null;
+
+export function onTrustedScroll(cb: () => void): void { trustedCallback = cb; }
+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);
+    const trust = event && event.isTrusted ? BooleanFlag.True : BooleanFlag.False;
+    if (event && event.isTrusted && trustedCallback) { trustedCallback(); }
+
+    let current: ScrollState = { time: time(event), event: Event.Scroll, data: {target: element, x, y, top, bottom, trust} };
+
+    // 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;
+}

package/src/interaction/selection.ts

@@ -0,0 +1,66 @@
+import { Event } from "@clarity-types/data";
+import { SelectionData, Setting } from "@clarity-types/interaction";
+import { bind } from "@src/core/event";
+import { schedule } from "@src/core/task";
+import { clearTimeout, setTimeout } from "@src/core/timeout";
+import encode from "./encode";
+
+export let data: SelectionData = null;
+let previous: Selection = null;
+let timeout: number = null;
+
+export function start(): void {
+    reset();
+}
+
+export function observe(root: Node): void {
+    bind(root, "selectstart", recompute.bind(this, root), true);
+    bind(root, "selectionchange", recompute.bind(this, root), true);
+}
+
+function recompute(root: Node): void {
+    let doc = root.nodeType === Node.DOCUMENT_NODE ? root as Document : document;
+    let current = doc.getSelection();
+
+    // Bail out if we don't have a valid selection
+    if (current === null) { return; }
+
+    // Bail out if we got a valid selection but not valid nodes
+    // In Edge, selectionchange gets fired even on interactions like right clicks and
+    // can result in null anchorNode and focusNode if there was no previous selection on page
+    // Also, ignore any selections that start and end at the exact same point
+    if ((current.anchorNode === null && current.focusNode === null) ||
+        (current.anchorNode === current.focusNode && current.anchorOffset === current.focusOffset)) {
+        return;
+    }
+    let startNode = data.start ? data.start : null;
+    if (previous !== null && data.start !== null && startNode !== current.anchorNode) {
+        clearTimeout(timeout);
+        process(Event.Selection);
+    }
+
+    data = {
+        start: current.anchorNode,
+        startOffset: current.anchorOffset,
+        end: current.focusNode,
+        endOffset: current.focusOffset
+    };
+    previous = current;
+
+    clearTimeout(timeout);
+    timeout = setTimeout(process, Setting.LookAhead, Event.Selection);
+}
+
+function process(event: Event): void {
+    schedule(encode.bind(this, event));
+}
+
+export function reset(): void {
+    previous = null;
+    data = { start: 0, startOffset: 0, end: 0, endOffset: 0 };
+}
+
+export function stop(): void {
+    reset();
+    clearTimeout(timeout);
+}

package/src/interaction/submit.ts

@@ -0,0 +1,30 @@
+import { Event } from "@clarity-types/data";
+import { SubmitState } from "@clarity-types/interaction";
+import { bind } from "@src/core/event";
+import { schedule } from "@src/core/task";
+import { time } from "@src/core/time";
+import encode from "./encode";
+import { target } from "@src/layout/target";
+
+export let state: SubmitState[] = [];
+
+export function start(): void {
+    reset();
+}
+
+export function observe(root: Node): void {
+    bind(root, "submit", recompute, true);
+}
+
+function recompute(evt: UIEvent): void {
+    state.push({ time: time(evt), event: Event.Submit, data: { target: target(evt) } });
+    schedule(encode.bind(this, Event.Submit));
+}
+
+export function reset(): void {
+    state = [];
+}
+
+export function stop(): void {
+    reset();
+}

package/src/interaction/timeline.ts

@@ -0,0 +1,69 @@
+import { BooleanFlag, Event } from "@clarity-types/data";
+import { BrowsingContext, Setting, TimelineState } from "@clarity-types/interaction";
+import * as baseline from "@src/data/baseline";
+import * as envelope from "@src/data/envelope";
+import encode from "@src/interaction/encode";
+
+let state: TimelineState[] = [];
+export let updates: TimelineState[] = [];
+
+export function start(): void {
+    state = [];
+    reset();
+}
+
+export function reset(): void {
+    updates = [];
+}
+
+export function track(time: number,
+    event: Event,
+    hash: string,
+    x: number,
+    y: number,
+    reaction: number = BooleanFlag.True,
+    context: number = BrowsingContext.Self): void {
+    state.push({
+        time,
+        event: Event.Timeline,
+        data: {
+            type: event,
+            hash,
+            x,
+            y,
+            reaction,
+            context
+        }
+    });
+
+    // Since timeline only keeps the data for configured time, we still want to continue tracking these values
+    // as part of the baseline. For instance, in a scenario where last scroll happened 5s ago.
+    // We would still need to capture the last scroll position as part of the baseline event, even when timeline will be empty.
+    baseline.track(event, x, y, time);
+}
+
+export function compute(): void {
+    if (!envelope.data) {
+        return;
+    }
+
+    const temp = [];
+    updates = [];
+    let max = (envelope.data.start || 0) + (envelope.data.duration || 0);
+    let min = Math.max(max - Setting.TimelineSpan, 0);
+
+    for (let s of state) {
+        if (s.time >= min) {
+            if (s.time <= max) { updates.push(s); }
+            temp.push(s);
+        }
+    }
+
+    state = temp; // Drop events less than the min time
+    encode(Event.Timeline);
+}
+
+export function stop(): void {
+    state = [];
+    reset();
+}

package/src/interaction/unload.ts

@@ -0,0 +1,32 @@
+import { BooleanFlag, Event } from "@clarity-types/data";
+import { UnloadData } from "@clarity-types/interaction";
+import * as clarity from "@src/clarity";
+import { bind } from "@src/core/event";
+import { time } from "@src/core/time";
+import encode from "./encode";
+import * as upload from "@src/data/upload";
+
+export let data: UnloadData;
+
+export function start(): void {
+    bind(window, "pagehide", recompute);
+    bind(window, "beforeunload", beforeUnload);
+}
+
+function beforeUnload(): void {
+    upload.flush('gemx-unload');
+}
+
+function recompute(evt: PageTransitionEvent): void {
+    data = { name: evt.type, persisted: evt.persisted ? BooleanFlag.True : BooleanFlag.False };
+    encode(Event.Unload, time(evt));
+    clarity.stop();
+}
+
+export function reset(): void {
+    data = null;
+}
+
+export function stop(): void {
+    reset();
+}

package/src/interaction/visibility.ts

@@ -0,0 +1,28 @@
+import { BooleanFlag, Event } from "@clarity-types/data";
+import { VisibilityData } from "@clarity-types/interaction";
+import { bind } from "@src/core/event";
+import { time } from "@src/core/time";
+import encode from "./encode";
+
+export let data: VisibilityData;
+
+export function start(): void {
+    bind(document, "visibilitychange", recompute);
+    recompute();
+}
+
+function recompute(evt: UIEvent = null): void {
+    if ("visibilityState" in document) {
+        const visible = document.visibilityState === "visible" ? BooleanFlag.True : BooleanFlag.False;
+        data = { visible };
+        encode(Event.Visibility, time(evt));
+    }
+}
+
+export function reset(): void {
+    data = null;
+}
+
+export function stop(): void {
+    reset();
+}

package/src/layout/animation.ts

@@ -0,0 +1,133 @@
+import { Event } from "@clarity-types/data";
+import { AnimationOperation, AnimationState } from "@clarity-types/layout";
+import { time } from "@src/core/time";
+import { shortid } from "@src/data/metadata";
+import encode from "@src/layout/encode";
+import { getId } from "@src/layout/dom";
+import * as core from "@src/core";
+
+export let state: AnimationState[] = [];
+let elementAnimate: (keyframes: Keyframe[] | PropertyIndexedKeyframes, options?: number | KeyframeAnimationOptions) => Animation = null;
+let animationPlay: () => void = null;
+let animationPause: () => void = null;
+let animationCommitStyles: () => void = null;
+let animationCancel: () => void = null;
+let animationFinish: () => void = null;
+const animationId = 'clarityAnimationId';
+const operationCount = 'clarityOperationCount';
+const maxOperations = 20;
+
+export function start(): void {
+    if (
+        window["Animation"] && 
+        window["Animation"].prototype && 
+        window["KeyframeEffect"] && 
+        window["KeyframeEffect"].prototype && 
+        window["KeyframeEffect"].prototype.getKeyframes &&
+        window["KeyframeEffect"].prototype.getTiming
+    ) {
+        reset();
+        overrideAnimationHelper(animationPlay, "play");
+        overrideAnimationHelper(animationPause, "pause");
+        overrideAnimationHelper(animationCommitStyles, "commitStyles");
+        overrideAnimationHelper(animationCancel, "cancel");
+        overrideAnimationHelper(animationFinish, "finish");
+        if (elementAnimate === null) {
+            elementAnimate = Element.prototype.animate;
+            Element.prototype.animate = function(): Animation {
+                var createdAnimation = elementAnimate.apply(this, arguments);
+                trackAnimationOperation(createdAnimation, "play");
+                return createdAnimation;
+            }
+        }
+        if (document.getAnimations) {
+            for (var animation of document.getAnimations()) {
+                if (animation.playState === "finished") {
+                    trackAnimationOperation(animation, "finish");
+                }
+                else if (animation.playState === "paused" || animation.playState === "idle") {
+                    trackAnimationOperation(animation, "pause");
+                }
+                else if (animation.playState === "running") {
+                    trackAnimationOperation(animation, "play");
+                }
+            }
+        }
+    }    
+}
+
+export function reset(): void {
+    state = [];
+}
+
+function track(time: number, id: string, operation: AnimationOperation, keyFrames?: string, timing?: string, targetId?: number, timeline?: string): void {
+    state.push({
+        time,
+        event: Event.Animation,
+        data: {
+            id,
+            operation,
+            keyFrames,
+            timing,
+            targetId,
+            timeline
+        }
+    });
+
+    encode(Event.Animation);
+}
+
+export function stop(): void {
+    reset();
+}
+
+function overrideAnimationHelper(functionToOverride: () => void, name: string) {
+    if (functionToOverride === null) {
+      functionToOverride = Animation.prototype[name];
+      Animation.prototype[name] = function(): void {
+        trackAnimationOperation(this, name);
+        return functionToOverride.apply(this, arguments);
+      }
+    }
+  }
+
+function trackAnimationOperation(animation: Animation, name: string) {
+    if (core.active()) {
+        let effect = <KeyframeEffect>animation.effect;
+        let target = effect?.target ? getId(effect.target) : null;
+        if (target !== null && effect.getKeyframes && effect.getTiming) {
+            if (!animation[animationId]) {
+                animation[animationId] = shortid();
+                animation[operationCount] = 0;
+                
+                let keyframes = effect.getKeyframes();
+                let timing = effect.getTiming();
+                track(time(), animation[animationId], AnimationOperation.Create, JSON.stringify(keyframes), JSON.stringify(timing), target);
+            }
+
+            if (animation[operationCount]++ < maxOperations)  {
+                let operation: AnimationOperation = null;
+                switch (name) {
+                    case "play":
+                        operation = AnimationOperation.Play;
+                        break;
+                    case "pause":
+                        operation = AnimationOperation.Pause;
+                        break;
+                    case "cancel":
+                        operation = AnimationOperation.Cancel;
+                        break;
+                    case "finish":
+                        operation = AnimationOperation.Finish;
+                        break;
+                    case "commitStyles":
+                        operation = AnimationOperation.CommitStyles;
+                        break;
+                }
+                if (operation) {
+                    track(time(), animation[animationId], operation);
+                }
+            }
+        }            
+    }
+}

package/src/layout/constants.ts

@@ -0,0 +1,13 @@
+/**
+ * Pre-computed arrays for better minification and performance
+ * These replace comma-separated strings that were previously split at runtime
+ */
+
+// Pre-computed mask arrays (replaces Mask.Text.split(), etc.)
+export const MaskTextList = ["address", "password", "contact"];
+export const MaskDisableList = ["radio", "checkbox", "range", "button", "reset", "submit"];
+export const MaskExcludeList = ["password", "secret", "pass", "social", "ssn", "code", "hidden"];
+export const MaskTagsList = ["INPUT", "SELECT", "TEXTAREA"];
+
+// Pre-computed exclude class names (replaces Constant.ExcludeClassNames.split())
+export const ExcludeClassNamesList = ["load", "active", "fixed", "visible", "focus", "show", "collaps", "animat"];

package/src/layout/custom.ts

@@ -0,0 +1,48 @@
+import { Event } from "@clarity-types/data";
+import { active } from "@src/core";
+import { schedule } from "@src/core/task";
+import encode from "@src/layout/encode";
+
+export const elements: string[] = [];
+
+const definedElements = new Set<string>();
+function register(tag: string) {
+    if (!definedElements.has(tag)) {
+        definedElements.add(tag);
+        elements.push(tag);
+        schedule(encode.bind(this, Event.CustomElement));
+    }
+}
+
+export function check(tag: string) {
+    if (window.customElements?.get && window.customElements.get(tag)) {
+        register(tag);
+    }
+}
+
+export function start() {
+    // Wrap in try-catch to handle Safari iOS where window properties or customElements.define may be readonly
+    try {
+        window.clarityOverrides = window.clarityOverrides || {};
+        if (window.customElements?.define && !window.clarityOverrides.define) {
+            window.clarityOverrides.define = window.customElements.define;
+            window.customElements.define = function () {
+                if (active()) {
+                    register(arguments[0]);
+                }
+                return window.clarityOverrides.define.apply(this, arguments);
+            };
+        }
+    } catch (e) {
+        // customElements.define or window properties are readonly in this environment (e.g., Safari iOS WKWebView)
+    }
+}
+
+export function reset() {
+    elements.length = 0;
+}
+
+export function stop() {
+    reset();
+    definedElements.clear();
+}

package/src/layout/discover.ts

@@ -0,0 +1,31 @@
+import { Priority, Timer } from "@clarity-types/core";
+import { Event, Metric } from "@clarity-types/data";
+import { Source } from "@clarity-types/layout";
+import measure from "@src/core/measure";
+import * as task from "@src/core/task";
+import { time } from "@src/core/time";
+import { id } from "@src/data/metadata";
+import * as doc from "@src/layout/document";
+import encode from "@src/layout/encode";
+import * as region from "@src/layout/region";
+import traverse from "@src/layout/traverse";
+import { checkDocumentStyles } from "@src/layout/style";
+import * as scroll from "@src/interaction/scroll";
+
+export function start(): void {
+    task.schedule(discover, Priority.High).then((): void => {
+        measure(doc.compute)();
+        measure(region.compute)();
+        measure(scroll.compute)();
+    });
+}
+
+async function discover(): Promise<void> {
+    let ts = time();
+    let timer: Timer = { id: id(), cost: Metric.LayoutCost };
+    task.start(timer);
+    await traverse(document, timer, Source.Discover, ts);
+    checkDocumentStyles(document, ts);
+    await encode(Event.Discover, timer, ts);
+    task.stop(timer);
+}

package/src/layout/document.ts

@@ -0,0 +1,46 @@
+import { Event } from "@clarity-types/data";
+import { DocumentData } from "@clarity-types/layout";
+import encode from "@src/layout/encode";
+
+export let data: DocumentData;
+
+export function reset(): void {
+    data = null;
+}
+
+export function start(): void {
+    reset();
+    compute();
+}
+
+export function compute(): void {
+    let body = document.body;
+    let d = document.documentElement;
+    let bodyClientWidth = body ? body.clientWidth : null;
+    let bodyScrollWidth = body ? body.scrollWidth : null;
+    let bodyOffsetWidth = body ? body.offsetWidth : null;
+    let documentClientWidth = d ? d.clientWidth : null;
+    let documentScrollWidth = d ? d.scrollWidth : null;
+    let documentOffsetWidth = d ? d.offsetWidth : null;
+    let width = Math.max(bodyClientWidth, bodyScrollWidth, bodyOffsetWidth,
+        documentClientWidth, documentScrollWidth, documentOffsetWidth);
+
+    let bodyClientHeight = body ? body.clientHeight : null;
+    let bodyScrollHeight = body ? body.scrollHeight : null;
+    let bodyOffsetHeight = body ? body.offsetHeight : null;
+    let documentClientHeight = d ? d.clientHeight : null;
+    let documentScrollHeight = d ? d.scrollHeight : null;
+    let documentOffsetHeight = d ? d.offsetHeight : null;
+    let height = Math.max(bodyClientHeight, bodyScrollHeight, bodyOffsetHeight,
+    documentClientHeight, documentScrollHeight, documentOffsetHeight);
+
+    // Check that width or height has changed from before, and also that width & height are not null values
+    if ((data === null || width !== data.width || height !== data.height) && width !== null && height !== null) {
+        data = { width, height };
+        encode(Event.Document);
+    }
+}
+
+export function stop(): void {
+    reset();
+}