heatspot 0.2.1 → 0.2.3

package/README.md

@@ -5,7 +5,6 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-%233178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![license](https://img.shields.io/github/license/Davidhanson90/heatspot.svg)](LICENSE)
 [![verify](https://github.com/Davidhanson90/heatspot/actions/workflows/verify-main.yml/badge.svg)](https://github.com/Davidhanson90/heatspot/actions/workflows/verify-main.yml)
-[![publish](https://github.com/Davidhanson90/heatspot/actions/workflows/publish-npm.yml/badge.svg)](https://github.com/Davidhanson90/heatspot/actions/workflows/publish-npm.yml)
 
 `heatspot` is an ESM TypeScript library for capturing pointer heat data and rendering an embeddable heatmap web component.
 
@@ -62,9 +61,45 @@ Example with hidden toolbar:
 
 ### Example
 
-![example.jps](assets/example.jpg)
+![example.jpg](https://raw.githubusercontent.com/Davidhanson90/heatspot/main/assets/example.jpg)
 
-### 3. Optional tracking API
+### 3. Read heatmap data from a `<heat-spot>` element
+
+```ts
+const element = document.querySelector<HeatSpotElement>('heat-spot');
+
+const snapshot = element.getHeatmapData();
+
+console.log(snapshot);
+```
+
+Example data shape:
+
+```json
+{
+  "totalSamples": 42,
+  "trackedSince": 1741351200000,
+  "viewport": { "width": 960, "height": 540 },
+  "hotspots": [
+    {
+      "id": "hs-0",
+      "x": 418.2,
+      "y": 225.6,
+      "count": 18,
+      "intensity": 1
+    },
+    {
+      "id": "hs-1",
+      "x": 701.1,
+      "y": 392.8,
+      "count": 9,
+      "intensity": 0.5
+    }
+  ]
+}
+```
+
+### 4. Optional global tracking API
 
 ```ts
 import {
@@ -85,6 +120,33 @@ stopMouseTracking();
 resetMouseHeatmap();
 ```
 
+### 5. Export the heatmap visualization as an image
+
+```ts
+const element = document.querySelector<HeatSpotElement>("heat-spot");
+
+if (element) {
+  const imageDataUrl = element.getHeatmapImage();
+
+  if (imageDataUrl) {
+    console.log(imageDataUrl);
+    // Example prefix:
+    // data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
+
+    // Optional download example
+    const link = document.createElement("a");
+    link.href = imageDataUrl;
+    link.download = "heatmap.png";
+    link.click();
+  }
+}
+```
+
+`getHeatmapImage()` returns:
+
+- A `data:` URL string when the component has measurable dimensions.
+- `null` if the element has no measurable surface yet (for example, hidden or not laid out).
+
 ## Scripts
 
 - `npm run build` - compile library to `dist/`

package/dist/heatspot-element.d.ts

@@ -1,4 +1,5 @@
 import { LitElement } from "lit";
+import { type HeatmapSnapshot } from "./contracts/heatmap-contracts.js";
 export declare class HeatSpotElement extends LitElement {
     static properties: {
         heatmapVisible: {
@@ -15,6 +16,17 @@ export declare class HeatSpotElement extends LitElement {
     private readonly tracker;
     static styles: import("lit").CSSResult;
     constructor();
+    /**
+     * Returns the current tracked heatmap snapshot for this element instance.
+     */
+    getHeatmapData(): HeatmapSnapshot;
+    /**
+     * Renders the current heatmap visualization into an image data URL.
+     */
+    getHeatmapImage(options?: {
+        type?: string;
+        quality?: number;
+    }): string | null;
     /**
      * Stops frame rendering when element leaves the document.
      */

package/dist/heatspot-element.js

@@ -64,6 +64,36 @@ export class HeatSpotElement extends LitElement {
         this.heatmapVisible = false;
         this.toolbar = "simple";
     }
+    /**
+     * Returns the current tracked heatmap snapshot for this element instance.
+     */
+    getHeatmapData() {
+        return this.tracker.getSnapshot();
+    }
+    /**
+     * Renders the current heatmap visualization into an image data URL.
+     */
+    getHeatmapImage(options = {}) {
+        const surface = this.renderRoot.querySelector(".surface");
+        if (!surface) {
+            return null;
+        }
+        const width = Math.round(surface.clientWidth);
+        const height = Math.round(surface.clientHeight);
+        if (width <= 0 || height <= 0) {
+            return null;
+        }
+        const imageCanvas = document.createElement("canvas");
+        imageCanvas.width = width;
+        imageCanvas.height = height;
+        const context = imageCanvas.getContext("2d");
+        if (!context) {
+            return null;
+        }
+        const snapshot = this.tracker.getSnapshot();
+        renderHeatmapOverlay(context, width, height, snapshot.hotspots);
+        return imageCanvas.toDataURL(options.type ?? "image/png", options.quality);
+    }
     /**
      * Stops frame rendering when element leaves the document.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heatspot",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "A tiny ESM TypeScript library.",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,6 +37,10 @@
     "typescript",
     "esm"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Davidhanson90/heatspot.git"
+  },
   "author": "",
   "license": "MIT",
   "engines": {