@stacksjs/stx/dist/heatmap.d.ts

A performant UI Framework. Powered by Bun.

import type { CustomDirective, StxOptions } from './types';
/**
 * Generate heatmap tracking script based on configuration
 */
export declare function generateHeatmapScript(options: StxOptions): string;
/**
 * Inject heatmap script into HTML
 * Scripts are injected just before </body> for optimal loading
 */
export declare function injectHeatmap(html: string, options: StxOptions): string;
/**
 * Create a heatmap aggregator instance
 */
export declare function createHeatmapAggregator(): HeatmapAggregator;
/**
 * Default heatmap configuration
 */
export declare const defaultHeatmapConfig: HeatmapConfig;
/**
 * Custom @heatmap directive for explicit placement
 */
export declare const heatmapDirective: CustomDirective;
/**
 * Heatmap Module
 *
 * Privacy-compliant heatmap tracking library that tracks user interactions
 * without collecting personally identifiable information (PII).
 *
 * ## Features
 * - Mouse movement tracking
 * - Click tracking
 * - Scroll depth tracking
 * - Privacy compliant (no PII, no cookies by default)
 * - Configurable sampling rates
 * - Export data for analysis
 *
 * ## Configuration
 *
 * Heatmap can be configured in `stx.config.ts`:
 * ```typescript
 * export default {
 *   heatmap: {
 *     enabled: true,
 *     trackMouse: true,
 *     trackClicks: true,
 *     trackScroll: true,
 *     samplingRate: 100, // Track every 100ms
 *     honorDnt: true,
 *     endpoint: '/api/heatmap'
 *   }
 * }
 * ```
 */
/**
 * Heatmap tracking configuration
 */
export declare interface HeatmapConfig {
  enabled: boolean
  trackMouse?: boolean
  trackClicks?: boolean
  trackScroll?: boolean
  samplingRate?: number
  honorDnt?: boolean
  endpoint?: string
  batchSize?: number
  maxDataPoints?: number
  sessionTimeout?: number
  persistData?: boolean
  storagePrefix?: string
  captureAttributes?: string[]
  ignoreSelectors?: string[]
  zones?: HeatmapZone[]
  debugOverlay?: boolean
  minViewportWidth?: number
  maxViewportWidth?: number
}
/**
 * Zone definition for grouped tracking
 */
export declare interface HeatmapZone {
  id: string
  selector: string
  label?: string
}
/**
 * Heatmap data point
 */
export declare interface HeatmapDataPoint {
  x: number
  y: number
  type: 'move' | 'click' | 'scroll'
  t: number
  el?: string
  zone?: string
  depth?: number
  attrs?: Record<string, string>
}
/**
 * Heatmap session data
 */
export declare interface HeatmapSession {
  sid: string
  page: string
  vw: number
  vh: number
  points: HeatmapDataPoint[]
  started: number
  lastActivity: number
}
/**
 * Server-side heatmap data aggregator
 * For processing collected heatmap data into visualizations
 */
export declare class HeatmapAggregator {
  private sessions: Map<string, HeatmapSession>;
  addSession(data: HeatmapSession): void;
  getPageData(page: string): HeatmapDataPoint[];
  getClickData(page: string): HeatmapDataPoint[];
  getMovementData(page: string): HeatmapDataPoint[];
  getScrollData(page: string): { depth: number, count: number }[];
  getZoneStats(page: string): Map<string, { clicks: number, hovers: number }>;
  generateGridData(page: string, gridSize?: number): { x: number, y: number, intensity: number }[][];
  exportJSON(): string;
  clear(): void;
}