clarity-js 0.6.23

package/src/data/variable.ts

@@ -0,0 +1,46 @@
+import { Constant, Event, VariableData } from "@clarity-types/data";
+import * as core from "@src/core";
+import encode from "./encode";
+
+export let data: VariableData = null;
+
+export function start(): void {
+    reset();
+}
+
+export function set(variable: string, value: string | string[]): void {
+    let values = typeof value === Constant.String ? [value as string] : value as string[];
+    log(variable, values);
+}
+
+export function identify(userId: string, sessionId: string = null, pageId: string = null): void {
+    log(Constant.UserId, [userId]);
+    log(Constant.SessionId, [sessionId]);
+    log(Constant.PageId, [pageId]);
+}
+
+function log(variable: string, value: string[]): void {
+    if (core.active() &&
+        variable &&
+        value &&
+        typeof variable === Constant.String &&
+        variable.length < 255) {
+        let validValues = variable in data ? data[variable] : [];
+        for (let i = 0; i < value.length; i++) {
+            if (typeof value[i] === Constant.String && value[i].length < 255) { validValues.push(value[i]); }
+        }
+        data[variable] = validValues;
+    }
+}
+
+export function compute(): void {
+    encode(Event.Variable);
+}
+
+export function reset(): void {
+    data = {};
+}
+
+export function stop(): void {
+    reset();
+}

package/src/diagnostic/encode.ts

@@ -0,0 +1,40 @@
+import { Event, Token } from "@clarity-types/data";
+import { time } from "@src/core/time";
+import { queue } from "@src/data/upload";
+import * as image from "@src/diagnostic/image";
+import * as internal from "@src/diagnostic/internal";
+import * as script from "@src/diagnostic/script";
+import { metadata } from "@src/layout/target";
+
+export default async function (type: Event): Promise<void> {
+    let tokens: Token[] = [time(), type];
+
+    switch (type) {
+        case Event.ScriptError:
+            tokens.push(script.data.message);
+            tokens.push(script.data.line);
+            tokens.push(script.data.column);
+            tokens.push(script.data.stack);
+            tokens.push(script.data.source);
+            queue(tokens);
+            break;
+        case Event.ImageError:
+            if (image.data) {
+                let imageTarget = metadata(image.data.target as Node, type);
+                tokens.push(image.data.source);
+                tokens.push(imageTarget.id);
+                queue(tokens);
+            }
+            break;
+        case Event.Log:
+            if (internal.data) {
+                tokens.push(internal.data.code);
+                tokens.push(internal.data.name);
+                tokens.push(internal.data.message);
+                tokens.push(internal.data.stack);
+                tokens.push(internal.data.severity);
+                queue(tokens, false);
+            }
+            break;
+    }
+}

package/src/diagnostic/image.ts

@@ -0,0 +1,23 @@
+import { Event } from "@clarity-types/data";
+import { ImageErrorData } from "@clarity-types/diagnostic";
+import { bind } from "@src/core/event";
+import { schedule } from "@src/core/task";
+import encode from "./encode";
+
+export let data: ImageErrorData;
+
+export function start(): void {
+    bind(document, "error", handler, true);
+}
+
+function handler(error: ErrorEvent): void {
+    let element = error.target as HTMLElement;
+    if (element && element.tagName === "IMG") {
+        data = { source: (element as HTMLImageElement).src, target: element };
+        schedule(encode.bind(this, Event.ImageError));
+    }
+}
+
+export function stop(): void {
+    data = null;
+}

package/src/diagnostic/index.ts

@@ -0,0 +1,14 @@
+import * as image from "./image";
+import * as internal from "./internal";
+import * as script from "./script";
+
+export function start(): void {
+    script.start();
+    image.start();
+    internal.start();
+}
+
+export function stop(): void {
+    image.stop();
+    internal.stop();
+}

package/src/diagnostic/internal.ts

@@ -0,0 +1,41 @@
+import { Code, Constant, Event, Severity } from "@clarity-types/data";
+import { LogData } from "@clarity-types/diagnostic";
+import config from "@src/core/config";
+import { bind } from "@src/core/event";
+import encode from "./encode";
+
+let history: { [key: number]: string[] } = {};
+export let data: LogData;
+
+export function start(): void {
+    history = {};
+    bind(document, "securitypolicyviolation", csp);
+}
+
+export function log(code: Code, severity: Severity, name: string = null, message: string = null, stack: string = null): void {
+    let key = name ? `${name}|${message}`: "";
+    // While rare, it's possible for code to fail repeatedly during the lifetime of the same page
+    // In those cases, we only want to log the failure once and not spam logs with redundant information.
+    if (code in history && history[code].indexOf(key) >= 0) { return; }
+
+    data = { code, name, message, stack, severity };
+
+    // Maintain history of errors in memory to avoid sending redundant information
+    if (code in history) { history[code].push(key); } else { history[code] = [key]; }
+
+    encode(Event.Log);
+}
+
+function csp(e: SecurityPolicyViolationEvent): void {
+    let upload = config.upload as string;
+    let parts = upload ? upload.substr(0, upload.indexOf("/", Constant.HTTPS.length)).split(Constant.Dot) : []; // Look for first "/" starting after initial "https://" string
+    let domain = parts.length >= 2 ? parts.splice(-2).join(Constant.Dot) : null;
+    // Capture content security policy violation only if disposition value is not explicitly set to "report"
+    if (domain && e.blockedURI && e.blockedURI.indexOf(domain) >= 0 && e["disposition"] !== Constant.Report) {
+        log(Code.ContentSecurityPolicy, Severity.Warning, e.blockedURI);
+    }
+}
+
+export function stop(): void {
+    history = {};
+}

package/src/diagnostic/script.ts

@@ -0,0 +1,45 @@
+import { Constant, Event, Setting } from "@clarity-types/data";
+import { ScriptErrorData } from "@clarity-types/diagnostic";
+import { bind } from "@src/core/event";
+import * as box from "@src/layout/box";
+import encode from "./encode";
+
+let history: { [key: string]: number } = {};
+export let data: ScriptErrorData;
+
+export function start(): void {
+    bind(window, "error", handler);
+    history = {};
+}
+
+function handler(error: ErrorEvent): boolean {
+    let e = error["error"] || error;
+    // While rare, it's possible for code to fail repeatedly during the lifetime of the same page
+    // In those cases, we only want to log the failure first few times and not spam logs with redundant information.
+    if (!(e.message in history)) { history[e.message] = 0; }
+    if (history[e.message]++ >= Setting.ScriptErrorLimit) { return true; }
+
+    // Send back information only if the handled error has valid information
+    if (e && e.message) {
+        data = {
+            message: e.message,
+            line: error["lineno"],
+            column: error["colno"],
+            stack: e.stack,
+            source: error["filename"]
+        };
+
+        // In certain cases, ResizeObserver could lead to flood of benign errors - especially when video element is involved.
+        // Reference Chromium issue: https://bugs.chromium.org/p/chromium/issues/detail?id=809574
+        // Even though it doesn't impact user experience, or show up in console, it can still flood error reporting through on error
+        // To mitigate that, we turn off Clarity's ResizeObserver on getting the first instance of this error
+        if (e.message.indexOf(Constant.ResizeObserver) >= 0) {
+            box.stop();
+            return false;
+        }
+
+        encode(Event.ScriptError);
+    }
+
+    return true;
+}

package/src/global.ts

@@ -0,0 +1,22 @@
+import * as clarity from "@src/clarity";
+
+// Expose clarity in a browser environment
+// To be efficient about queuing up operations while Clarity is wiring up, we expose clarity.*(args) => clarity(*, args);
+// This allows us to reprocess any calls that we missed once Clarity is available on the page
+// Once Clarity script bundle is loaded on the page, we also initialize a "v" property that holds current version
+// We use the presence or absence of "v" to determine if we are attempting to run a duplicate instance
+(function(): void {
+    if (typeof window !== "undefined") {
+        const w = window as any;
+        const c = 'clarity';
+        
+        // Do not execute or reset global "clarity" variable if a version of Clarity is already running on the page
+        if (w[c] && w[c].v) { return console.warn("Error CL001: Multiple Clarity tags detected."); }
+        
+        // Re-wire global "clarity" variable to map it to current instance of Clarity
+        const queue = w[c] ? (w[c].q || []) : [];
+        w[c] = function(method: string, ...args: any[]): void { return clarity[method](...args); }
+        w[c].v = clarity.version;
+        while (queue.length > 0) { w[c](...queue.shift()); }
+    }
+})();

package/src/index.ts

@@ -0,0 +1,8 @@
+import * as clarity from "./clarity";
+import hash from "./core/hash";
+import selector from "./layout/selector";
+
+const helper = { hash, selector }
+const version = clarity.version;
+
+export { clarity, version, helper };

package/src/interaction/click.ts

@@ -0,0 +1,140 @@
+import { BooleanFlag, Constant, Event, Setting } from "@clarity-types/data";
+import { BrowsingContext, ClickState } from "@clarity-types/interaction";
+import { Box } from "@clarity-types/layout";
+import { bind } from "@src/core/event";
+import { schedule } from "@src/core/task";
+import { time } from "@src/core/time";
+import { iframe } from "@src/layout/dom";
+import offset from "@src/layout/offset";
+import { link, target } from "@src/layout/target";
+import encode from "./encode";
+
+const UserInputTags = ["input", "textarea", "radio", "button", "canvas"];
+export let state: ClickState[] = [];
+
+export function start(): void {
+    reset();
+}
+
+export function observe(root: Node): void {
+    bind(root, "click", handler.bind(this, Event.Click, root), true);
+}
+
+function handler(event: Event, root: Node, evt: MouseEvent): void {
+    let frame = iframe(root);
+    let d = frame ? 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;
+    }
+
+    let t = target(evt);
+    // Find nearest anchor tag (<a/>) parent if current target node is part of one
+    // If present, we use the returned link element to populate text and link properties below
+    let a = link(t);
+
+    // Get layout rectangle for the target element
+    let l = layout(t as Element);
+
+    // Reference: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail
+    // This property helps differentiate between a keyboard navigation vs. pointer click
+    // In case of a keyboard navigation, we use center of target element as (x,y)
+    if (evt.detail === 0 && l) {
+        x = Math.round(l.x + (l.w / 2));
+        y = Math.round(l.y + (l.h / 2));
+    }
+
+    let eX = l ? Math.max(Math.floor(((x - l.x) / l.w) * Setting.ClickPrecision), 0) : 0;
+    let eY = l ? Math.max(Math.floor(((y - l.y) / l.h) * Setting.ClickPrecision), 0) : 0;
+
+    // Check for null values before processing this event
+    if (x !== null && y !== null) {
+        state.push({
+            time: time(), event, data: {
+                target: t,
+                x,
+                y,
+                eX,
+                eY,
+                button: evt.button,
+                reaction: reaction(t),
+                context: context(a),
+                text: text(t),
+                link: a ? a.href : null,
+                hash: null
+            }
+        });
+        schedule(encode.bind(this, event));
+    }
+}
+
+function text(element: Node): string {
+    let output = null;
+    if (element) {
+        // Grab text using "textContent" for most HTMLElements, however, use "value" for HTMLInputElements and "alt" for HTMLImageElement.
+        let t = element.textContent || (element as HTMLInputElement).value || (element as HTMLImageElement).alt;
+        if (t) {
+            // Trim any spaces at the beginning or at the end of string
+            // Also, replace multiple occurrence of space characters with a single white space
+            // Finally, send only first few characters as specified by the Setting
+            output = t.trim().replace(/\s+/g, Constant.Space).substr(0, Setting.ClickText);
+        }
+    }
+    return output;
+}
+
+function reaction(element: Node): BooleanFlag {
+    if (element.nodeType === Node.ELEMENT_NODE) {
+        let tag = (element as HTMLElement).tagName.toLowerCase();
+        if (UserInputTags.indexOf(tag) >= 0) {
+            return BooleanFlag.False;
+        }
+    }
+    return BooleanFlag.True;
+}
+
+function layout(element: Element): Box {
+    let box: Box = null;
+    let de = document.documentElement;
+    if (typeof element.getBoundingClientRect === "function") {
+        // getBoundingClientRect returns rectangle relative positioning to viewport
+        let rect = element.getBoundingClientRect();
+
+        if (rect && rect.width > 0 && rect.height > 0) {
+            // Add viewport's scroll position to rectangle to get position relative to document origin
+            // Also: using Math.floor() instead of Math.round() because in Edge,
+            // getBoundingClientRect returns partial pixel values (e.g. 162.5px) and Chrome already
+            // floors the value (e.g. 162px). This keeps consistent behavior across browsers.
+            box = {
+                x: Math.floor(rect.left + ("pageXOffset" in window ? window.pageXOffset : de.scrollLeft)),
+                y: Math.floor(rect.top + ("pageYOffset" in window ? window.pageYOffset : de.scrollTop)),
+                w: Math.floor(rect.width),
+                h: Math.floor(rect.height)
+            };
+        }
+    }
+    return box;
+}
+
+function context(a: HTMLAnchorElement): BrowsingContext {
+    if (a && a.hasAttribute(Constant.Target)) {
+        switch (a.getAttribute(Constant.Target)) {
+            case Constant.Blank: return BrowsingContext.Blank;
+            case Constant.Parent: return BrowsingContext.Parent;
+            case Constant.Top: return BrowsingContext.Top;
+        }
+    }
+    return BrowsingContext.Self;
+}
+
+export function reset(): void {
+    state = [];
+}
+
+export function stop(): void {
+    reset();
+}

package/src/interaction/encode.ts

@@ -0,0 +1,140 @@
+import { Event, Token } from "@clarity-types/data";
+import 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 click from "./click";
+import * as input from "./input";
+import * as pointer from "./pointer";
+import * as resize from "./resize";
+import * as scroll from "./scroll";
+import * as selection from "./selection";
+import * as timeline from "./timeline";
+import * as unload from "./unload";
+import * as visibility from "./visibility";
+
+export default async function (type: Event): Promise<void> {
+    let t = 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 i = 0; i < pointer.state.length; i++) {
+                let entry = pointer.state[i];
+                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);
+                    queue(tokens);
+                    baseline.track(entry.event, entry.data.x, entry.data.y);
+                }
+            }
+            pointer.reset();
+            break;
+        case Event.Click:
+            for (let i = 0; i < click.state.length; i++) {
+                let entry = click.state[i];
+                let cTarget = metadata(entry.data.target as Node, entry.event);
+                tokens = [entry.time, entry.event];
+                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(entry.data.text, "click", cTarget.privacy));
+                tokens.push(entry.data.link);
+                tokens.push(cTarget.hash);
+                queue(tokens);
+                timeline.track(entry.time, entry.event, cTarget.hash, entry.data.x, entry.data.y, entry.data.reaction, entry.data.context);
+            }
+            click.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);
+            unload.reset();
+            queue(tokens);
+            break;
+        case Event.Input:
+            for (let i = 0; i < input.state.length; i++) {
+                let entry = input.state[i];
+                let iTarget = metadata(entry.data.target as Node, entry.event);
+                tokens = [entry.time, entry.event];
+                tokens.push(iTarget.id);
+                tokens.push(entry.data.value);
+                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 i = 0; i < scroll.state.length; i++) {
+                let entry = scroll.state[i];
+                let sTarget = metadata(entry.data.target as Node, entry.event);
+                if (sTarget.id > 0) {
+                    tokens = [entry.time, entry.event];
+                    tokens.push(sTarget.id);
+                    tokens.push(entry.data.x);
+                    tokens.push(entry.data.y);
+                    queue(tokens);
+                    baseline.track(entry.event, entry.data.x, entry.data.y);
+                }
+            }
+            scroll.reset();
+            break;
+        case Event.Timeline:
+            for (let i = 0; i < timeline.updates.length; i++) {
+                let entry = timeline.updates[i];
+                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;
+    }
+}

package/src/interaction/index.ts

@@ -0,0 +1,45 @@
+import * as click from "@src/interaction/click";
+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 timeline from "@src/interaction/timeline";
+import * as unload from "@src/interaction/unload";
+import * as visibility from "@src/interaction/visibility";
+
+export function start(): void {
+    timeline.start();
+    click.start();
+    pointer.start();
+    input.start();
+    resize.start();
+    visibility.start();
+    scroll.start();
+    selection.start();
+    unload.start();
+}
+
+export function stop(): void {
+    timeline.stop();
+    click.stop();
+    pointer.stop();
+    input.stop();
+    resize.stop();
+    visibility.stop();
+    scroll.stop();
+    selection.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);
+        pointer.observe(root);
+        input.observe(root);
+        selection.observe(root);
+    }
+}

package/src/interaction/input.ts

@@ -0,0 +1,64 @@
+import { Event } from "@clarity-types/data";
+import { InputData, InputState, Setting } from "@clarity-types/interaction";
+import { bind } from "@src/core/event";
+import scrub from "@src/core/scrub";
+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;
+        switch (input.type) {
+            case "radio":
+            case "checkbox":
+                v = input.checked ? "true" : "false";
+                break;
+            case "range":
+                v = input.value;
+                break;
+            default:
+                v = scrub(input.value, "input", value.metadata.privacy);
+                break;
+        }
+
+        let data: InputData = { target: input, value: v };
+
+        // 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(), event: Event.Input, data });
+
+        clearTimeout(timeout);
+        timeout = setTimeout(process, Setting.LookAhead, Event.Input);
+    }
+}
+
+function process(event: Event): void {
+    schedule(encode.bind(this, event));
+}
+
+export function reset(): void {
+    state = [];
+}
+
+export function stop(): void {
+    clearTimeout(timeout);
+    reset();
+}