@gemx-dev/clarity-visualize 3.5.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @gemx-dev/clarity-visualize
+
+## 3.5.1
+
+### Patch Changes
+
+- [#29](https://github.com/ducky0209/gemx-sdk/pull/29) [`2a1dd3c`](https://github.com/ducky0209/gemx-sdk/commit/2a1dd3c561324a22f8d8af2611536ce36f1976ff) Thanks [@ducky0209](https://github.com/ducky0209)! - Feat: add package @gemx-dev/clarity-visualize

package/README.md

@@ -0,0 +1,26 @@
+# Clarity
+Clarity is an open-source behavioral analytics library written in typescript, with two key goals: privacy & performance. 
+
+It helps you understand how users view and use your website across all modern devices and browsers. Understanding how users navigate, interact and browse your website can provide new insights about your users. Empathizing with your users and seeing where features fail or succeed can help improve your product, grow revenue and improve user retention.
+
+This package takes the decoded data from [clarity-decode](https://github.com/microsoft/clarity/tree/master/packages/clarity-decode) and turns it into pixel-perfect session replay, exactly how the user saw it.
+
+We encourage the community to join us in building the best behavioral analytics library, that puts privacy first and prioritizes performance. 
+
+## Examples
+Here are some example sessions on popular websites visualized to demonstrate the telemetry captured:
+1. CNN (Web)
+</br><a href="https://thumbs.gfycat.com/AggressiveLankyAbyssiniangroundhornbill-size_restricted.gif"><img src="https://thumbs.gfycat.com/AggressiveLankyAbyssiniangroundhornbill-size_restricted.gif" title="Clarity - CNN Example"/></a>
+
+2. Cook with Manali (Mobile)
+</br><a href="https://thumbs.gfycat.com/CoolDependableAdamsstaghornedbeetle-size_restricted.gif"><img src="https://thumbs.gfycat.com/CoolDependableAdamsstaghornedbeetle-size_restricted.gif" title="Clarity - Cook With Manali Example"/></a> 
+
+## Privacy Notice
+Clarity handles sensitive data with care. By default sensitive content on the page is masked before uploading to the server.
+
+## Improving Clarity
+If you haven't already done so, start contributing by following instructions **[here](https://github.com/microsoft/clarity/blob/master/CONTRIBUTING.md)**.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+Happy coding!

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@gemx-dev/clarity-visualize",
+  "version": "3.5.1",
+  "description": "An analytics library that uses web page interactions to generate aggregated insights",
+  "author": "Microsoft Corp.",
+  "license": "MIT",
+  "main": "build/clarity.visualize.js",
+  "module": "build/clarity.visualize.module.js",
+  "unpkg": "build/clarity.visualize.min.js",
+  "types": "types/index.d.ts",
+  "keywords": [
+    "clarity",
+    "Microsoft",
+    "interactions",
+    "cursor",
+    "pointer",
+    "instrumentation",
+    "analytics",
+    "visualization"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/clarity.git",
+    "directory": "packages/clarity-visualize"
+  },
+  "bugs": {
+    "url": "https://github.com/Microsoft/clarity/issues"
+  },
+  "dependencies": {
+    "clarity-decode": "^0.8.38"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^24.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-terser": "^0.4.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "rollup-plugin-string-import": "^1.2.5",
+    "del-cli": "^5.0.0",
+    "husky": "^8.0.0",
+    "lint-staged": "^13.1.0",
+    "rollup": "^3.0.0",
+    "ts-node": "^10.1.0",
+    "tslint": "^6.1.3",
+    "typescript": "^4.3.5"
+  },
+  "scripts": {
+    "build": "yarn build:clean && yarn build:main",
+    "build:main": "rollup -c rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "build:clean": "del-cli build/*",
+    "tslint": "tslint --project ./",
+    "tslint:fix": "tslint --fix --project ./ --force"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*.ts": [
+      "tslint --format codeFrame"
+    ]
+  }
+}

package/rollup.config.ts

@@ -0,0 +1,79 @@
+import commonjs from "@rollup/plugin-commonjs";
+import resolve from "@rollup/plugin-node-resolve";
+import terser from "@rollup/plugin-terser";
+import typescript from "@rollup/plugin-typescript";
+import { importAsString } from 'rollup-plugin-string-import';
+import { readFileSync } from "fs";
+
+const pkg = JSON.parse(readFileSync("./package.json", "utf-8"));
+
+function wrapWithBackground(svg){
+  return `background: url("data:image/svg+xml,${svg}") no-repeat center center;`;
+}
+
+function regexEncode(svg){
+  svg = svg.replace(/>\s{1,}</g, `><`);
+  svg = svg.replace(/\s{2,}/g, ` `);
+  return svg.replace(/[\r\n%#()<>?[\\\]^`{|}]/g, encodeURIComponent)
+}
+
+function doublesToSingles(svg){
+  return svg.replace(/"/g, "'")
+}
+
+function preprocessFile(content: string, fileName: string): string {
+  if (fileName.endsWith(".css")) {
+    // remove comments/newlines
+    return content.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, "").replace(/\r\n/g, "");
+  }
+  else if (fileName.endsWith(".svg")) {
+    // removes comments/newlines while also encoding the svg and adding some scaffolding to import it
+    return wrapWithBackground(regexEncode(doublesToSingles(content)));
+  }
+  return "";
+}
+
+export default [
+  {
+    input: "src/index.ts",
+    output: [
+      { file: pkg.main, format: "cjs", exports: "named" },
+      { file: pkg.module, format: "es", exports: "named" }
+    ],
+    plugins: [
+      resolve(),
+      importAsString({ 
+        include: ["**/*.css", "**/*.svg"],
+        transform: preprocessFile,
+      }),
+      typescript(),
+      commonjs({ include: ["node_modules/**"] })
+    ],
+    onwarn(message, warn) {
+      if (message.code === 'NON_EXISTENT_EXPORT') { return; }
+      if (message.code === 'CIRCULAR_DEPENDENCY') { return; }
+      if (message.code === 'SOURCEMAP_ERROR') { return; }
+      warn(message);
+    }
+  },
+  {
+    input: "src/global.ts",
+    output: [ { file: pkg.unpkg, format: "iife", exports: "named" } ],
+    plugins: [
+      resolve(),      
+      importAsString({ 
+        include: ["**/*.css", "**/*.svg"],
+        transform: preprocessFile,
+      }),
+      typescript(),
+      terser({output: {comments: false}}),
+      commonjs({ include: ["node_modules/**"] })
+    ],
+    onwarn(message, warn) {
+      if (message.code === 'NON_EXISTENT_EXPORT') { return; }
+      if (message.code === 'CIRCULAR_DEPENDENCY') { return; }
+      if (message.code === 'SOURCEMAP_ERROR') { return; }
+      warn(message);
+    }
+  }
+];

package/src/clarity.ts

@@ -0,0 +1,3 @@
+import { Visualizer } from "./visualizer";
+
+export const { state, dom, get, html, time, clickmap, clearmap, scrollmap, merge, setup, render } = new Visualizer();

package/src/data.ts

@@ -0,0 +1,103 @@
+import { Data, Layout } from "clarity-js";
+import type { Data as DecodedData, Layout as DecodedLayout } from "clarity-decode";
+import { PlaybackState, RegionState } from "@clarity-types/visualize";
+
+export class DataHelper {
+    regionMap = {};
+    regions: { [key: string]:  RegionState} = {};
+    metrics: {[key: number]: number} = {};
+    lean = false;
+    state: PlaybackState;
+
+    constructor(state: PlaybackState) {
+        this.state = state;
+    }
+
+    static METRIC_MAP = {
+        [Data.Metric.TotalBytes]: { name: "Total Bytes", unit: "KB" },
+        [Data.Metric.TotalCost]: { name: "Total Cost", unit: "ms" },
+        [Data.Metric.LayoutCost]: { name: "Layout Cost", unit: "ms" },
+        [Data.Metric.LargestPaint]: { name: "LCP", unit: "s" },
+        [Data.Metric.CumulativeLayoutShift]: { name: "CLS", unit: "cls" },
+        [Data.Metric.LongTaskCount]: { name: "Long Tasks" },
+        [Data.Metric.CartTotal]: { name: "Cart Total", unit: "html-price" },
+        [Data.Metric.ProductPrice]: { name: "Product Price", unit: "ld-price" },
+        [Data.Metric.ThreadBlockedTime]: { name: "Thread Blocked", unit: "ms" },
+        [Data.Dimension.InteractionNextPaint]: { name: "INP", unit: "ms" }
+    };
+
+    public reset = (): void => {
+        this.metrics = {};
+        this.lean = false;
+        this.regions = {};
+        this.regionMap = {};
+    }
+
+    public metric = (event: DecodedData.MetricEvent): void => {
+        if (this.state.options.metadata) { 
+            let metricMarkup = [];
+            let regionMarkup = [];
+            // Copy over metrics for future reference
+            for (let m in event.data) {
+                const eventType = typeof event.data[m]; 
+                if (eventType === "number" || (event.event === Data.Event.Dimension && m === Data.Dimension.InteractionNextPaint.toString())) {
+                    if (!(m in this.metrics)) { this.metrics[m] = 0; }
+                    let key = parseInt(m, 10);
+                    let value =  eventType === "object" ? Number(event.data[m]?.[0]) : event.data[m];
+                    if (m in DataHelper.METRIC_MAP && (DataHelper.METRIC_MAP[m].unit === "html-price" ||DataHelper.METRIC_MAP[m].unit === "ld-price")) { 
+                        this.metrics[m] = value;
+                    } else { this.metrics[m] += value; }
+                    this.lean = key === Data.Metric.Playback && value === 0 ? true : this.lean;
+                }
+            }
+
+            for (let entry in this.metrics) {
+                if (entry in DataHelper.METRIC_MAP) {
+                    let m = this.metrics[entry];
+                    let map = DataHelper.METRIC_MAP[entry];
+                    let unit = "unit" in map ? map.unit : Data.Constant.Empty;
+                    metricMarkup.push(`<li><h2>${this.value(m, unit)}<span>${this.key(unit)}</span></h2>${map.name}</li>`);
+                }
+            }
+
+            // Append region information to metadata
+            for (let name in this.regions) {
+                let r = this.regions[name];
+                let className = (r.visibility === Layout.RegionVisibility.Visible ? "visible" : (r.interaction === Layout.InteractionState.Clicked ? "clicked" : Data.Constant.Empty));
+                regionMarkup.push(`<span class="${className}">${name}</span>`);
+            }
+
+            this.state.options.metadata.innerHTML = `<ul>${metricMarkup.join(Data.Constant.Empty)}</ul><div>${regionMarkup.join(Data.Constant.Empty)}</div>`;
+        }
+    }
+
+    public region(event: DecodedLayout.RegionEvent): void {
+        let data = event.data;
+        for (let r of data) {
+            if (!(r.name in this.regions)) { 
+                this.regions[r.name] = { interaction: r.interaction , visibility: r.visibility }
+            }
+            this.regionMap[r.id] = r.name;
+        }
+    }
+
+    private key = (unit: string): string => {
+        switch (unit) {
+            case "html-price": 
+            case "ld-price": 
+            case "cls":
+                return Data.Constant.Empty;
+            default: return unit;
+        }
+    }
+
+    private value = (num: number, unit: string): number => {
+        switch (unit) {
+            case "KB": return Math.round(num / 1024);
+            case "s": return Math.round(num / 10) / 100;
+            case "cls": return num / 1000;
+            case "html-price": return num / 100;
+            default: return num;
+        }
+    }
+}

package/src/enrich.ts

@@ -0,0 +1,80 @@
+import { helper, Layout } from "clarity-js";
+import { Layout as DecodedLayout } from "clarity-decode";
+import { NodeData } from "@clarity-types/visualize";
+
+export class EnrichHelper {
+        
+    children: { [key: number]: number[] };
+    nodes: { [key: number]: NodeData };
+    
+    constructor() {
+        this.reset();
+    }
+
+    public reset = (): void => {
+        this.children = {};
+        this.nodes = {};
+        helper.selector.reset();
+    }
+
+    public selectors = (event: DecodedLayout.DomEvent): DecodedLayout.DomEvent => {
+        event.data.forEach && event.data.forEach(d => {
+            let parent = this.nodes[d.parent];
+            let children = this.children[d.parent] || [];
+            let node = this.nodes[d.id] || { tag: d.tag, parent: d.parent, previous: d.previous };
+            let attributes = d.attributes || {};
+
+            /* Track parent-child relationship for this element */
+            if (node.parent !== d.parent) {
+                let childIndex = d.previous === null ? 0 : children.indexOf(d.previous) + 1;
+                children.splice(childIndex, 0, d.id);
+
+                // Stop tracking this node from children of previous parent
+                if (node.parent !== d.parent) {
+                    let exParent = this.children[node.parent];
+                    let nodeIndex = exParent ? exParent.indexOf(d.id) : -1;
+                    if (nodeIndex >= 0) {
+                        this.children[node.parent].splice(nodeIndex, 1);
+                    }
+                }
+                node.parent = d.parent;
+            } else if (children.indexOf(d.id) < 0) { children.push(d.id); }
+
+            /* Get current position */
+            node.position = this.position(d.id, d.tag, node, children, children.map(c => this.nodes[c]));
+
+            /* For backward compatibility, continue populating current selector and hash like before in addition to beta selector and hash */
+            let input: Layout.SelectorInput = { id: d.id, tag: d.tag, prefix: parent ? [parent.alpha, parent.beta] : null, position: node.position, attributes };
+
+            // Get stable selector
+            // We intentionally use "null" value for empty selectors to keep parity with v0.6.25 and before.
+            let selectorAlpha = helper.selector.get(input, Layout.Selector.Alpha);
+            d.selectorAlpha = selectorAlpha.length > 0 ? selectorAlpha : null;
+            d.hashAlpha = selectorAlpha.length > 0 ? helper.hash(d.selectorAlpha) : null;
+            
+            // Get beta selector
+            let selectorBeta = helper.selector.get(input, Layout.Selector.Beta);
+            d.selectorBeta = selectorBeta.length > 0 ? selectorBeta : null;
+            d.hashBeta = selectorBeta.length > 0 ? helper.hash(d.selectorBeta) : null;
+
+            /* Track state for future reference */
+            node.alpha = selectorAlpha;
+            node.beta = selectorBeta;
+            this.nodes[d.id] = node;
+            if (d.parent) { this.children[d.parent] = children; }                             
+        });
+        return event;
+    }
+    
+    private position = (id: number, tag: string, child: NodeData, children: number[], siblings: NodeData[]): number => {
+        child.position = 1;
+        let idx = children ? children.indexOf(id) : -1;
+        while (idx-- > 0) {
+            if (tag === siblings[idx].tag) {
+                child.position = siblings[idx].position + 1;
+                break;
+            }
+        }
+        return child.position;
+    }
+}

package/src/global.ts

@@ -0,0 +1,9 @@
+import * as visualize from "@src/clarity";
+
+// Expose clarity variable globally to allow access to public interface in a browser
+if (typeof window !== "undefined") {
+    if ((window as any).clarity === undefined || (window as any).clarity === null) {
+        (window as any).clarity = {};
+    }
+    (window as any).clarity.visualize = visualize;
+}