heatspot 0.2.2 → 0.2.4

package/README.md

@@ -8,6 +8,28 @@
 
 `heatspot` is an ESM TypeScript library for capturing pointer heat data and rendering an embeddable heatmap web component.
 
+## Try the Demo
+
+Live demo:
+
+- [![heatspot demo](https://raw.githubusercontent.com/Davidhanson90/heatspot/main/assets/example.jpg)](https://davidhanson90.github.io/heatspot/)
+
+How to try it:
+
+1. Open the demo URL.
+2. Move your cursor around the demo area for a few seconds.
+3. Click the toggle icon in the top-left of the component to show the heat overlay.
+4. Continue interacting to see hotspots update in real time.
+
+To run the demo locally:
+
+```bash
+npm install
+npm start
+```
+
+Then open the local URL shown in your terminal (Vite default is usually `http://localhost:5173`).
+
 ## Features
 
 - ESM package output with TypeScript declarations
@@ -59,11 +81,43 @@ Example with hidden toolbar:
 </heat-spot>
 ```
 
-### Example
+### 3. Read heatmap data from a `<heat-spot>` element
 
-![example.jpg](https://raw.githubusercontent.com/Davidhanson90/heatspot/main/assets/example.jpg)
+```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
+    }
+  ]
+}
+```
 
-### 3. Optional tracking API
+### 4. Optional global tracking API
 
 ```ts
 import {
@@ -84,6 +138,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

@@ -40,14 +40,22 @@ export class HeatSpotElement extends LitElement {
       color: #ffffff;
       padding: 0;
       line-height: 1;
-      font-size: 0.92rem;
-      font-weight: 700;
       cursor: pointer;
       z-index: 10001;
+      opacity: 0.72;
+      transition: opacity 180ms ease;
+      display: grid;
+      place-items: center;
     }
 
     .toggle:hover {
-      background: rgba(2, 6, 23, 0.95);
+      opacity: 1;
+    }
+
+    .toggle-icon {
+      width: 0.95rem;
+      height: 0.95rem;
+      fill: currentColor;
     }
 
     .overlay {
@@ -64,6 +72,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.
      */
@@ -165,7 +203,17 @@ export class HeatSpotElement extends LitElement {
       ${this.toolbar === "hidden"
             ? null
             : html `<button class="toggle" @click=${this.toggleHeatmap} aria-label="Toggle heatmap">
-            ${this.heatmapVisible ? "x" : "*"}
+            <svg
+              class="toggle-icon"
+              viewBox="0 0 24 24"
+              role="img"
+              aria-label="Heatmap fire icon"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path
+                d="M12 2.5c.4 2.3-.2 3.9-1.3 5.3-1.2 1.5-2.6 2.9-2.6 5.3 0 2.2 1.8 4 3.9 4 .8 0 1.6-.2 2.2-.6-1.1-.4-1.9-1.5-1.9-2.8 0-1.9 1.6-3 2.7-4.4.8-1 .9-2.1.8-3.3 2.3 1.5 4.2 4 4.2 7.1 0 4.2-3.4 7.6-7.6 7.6S4.8 17.3 4.8 13.1c0-4.3 2.5-6.7 4.5-8.7C10.4 3.3 11.2 2.6 12 2.5z"
+              />
+            </svg>
           </button>`}
       ${this.heatmapVisible ? html `<canvas id="heatmap" class="overlay"></canvas>` : null}
     `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heatspot",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "A tiny ESM TypeScript library.",
   "type": "module",
   "main": "./dist/index.js",