@stacksjs/ts-analytics 0.1.6

package/src/dashboard/components/heatmap/PageHeatmap.stx

@@ -0,0 +1,264 @@
+<script>
+/**
+ * PageHeatmap Component
+ *
+ * Main container for page heatmap visualization with iframe/screenshot
+ * and overlay controls.
+ */
+export const siteId = $props.siteId
+export const pageUrl = $props.pageUrl
+export const apiEndpoint = $props.apiEndpoint || ''
+export const screenshotUrl = $props.screenshotUrl
+export const initialStartDate = $props.initialStartDate
+export const initialEndDate = $props.initialEndDate
+
+// Use window.apiPath if available, otherwise define a local one
+const apiPath = window.apiPath || ((path) => {
+  const urlParams = new URLSearchParams(window.location.search)
+  const USE_STEALTH = urlParams.get('stealth') !== 'false'
+  if (!USE_STEALTH) return path
+  const STEALTH_MAP = { sites: 'projects', heatmap: 'touch' }
+  let result = path.replace('/api/sites/', '/api/p/')
+  Object.keys(STEALTH_MAP).forEach(k => {
+    result = result.replace(new RegExp(`/${k}(?=/|\\?|$)`, 'g'), `/${STEALTH_MAP[k]}`)
+  })
+  return result
+})
+
+// State
+let viewMode = 'click'
+let deviceFilter = 'all'
+let startDate = initialStartDate || new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10)
+let endDate = initialEndDate || new Date().toISOString().slice(0, 10)
+let loading = false
+let error = null
+
+// Heatmap data
+let clickData = []
+let topElements = []
+let totalClicks = 0
+let scrollData = []
+let avgScrollDepth = 0
+let totalScrollSessions = 0
+
+// Container dimensions
+let containerWidth = 800
+let containerHeight = 600
+
+const apiBaseUrl = apiPath(`${apiEndpoint}/api/sites/${siteId}/heatmap`)
+
+// Fetch click heatmap data
+export async function fetchClickData() {
+  loading = true
+  error = null
+
+  try {
+    const params = new URLSearchParams({
+      path: pageUrl,
+      startDate: new Date(startDate).toISOString(),
+      endDate: new Date(endDate).toISOString(),
+      device: deviceFilter,
+    })
+
+    const response = await fetch(`${apiBaseUrl}/clicks?${params}`)
+    if (!response.ok) throw new Error('Failed to fetch click data')
+
+    const data = await response.json()
+    clickData = data.clicks || []
+    topElements = data.topElements || []
+    totalClicks = data.totalClicks || 0
+  } catch (err) {
+    error = err.message || 'Unknown error'
+    console.error('Heatmap fetch error:', err)
+  } finally {
+    loading = false
+  }
+}
+
+// Fetch scroll heatmap data
+export async function fetchScrollData() {
+  loading = true
+  error = null
+
+  try {
+    const params = new URLSearchParams({
+      path: pageUrl,
+      startDate: new Date(startDate).toISOString(),
+      endDate: new Date(endDate).toISOString(),
+      device: deviceFilter,
+    })
+
+    const response = await fetch(`${apiBaseUrl}/scroll?${params}`)
+    if (!response.ok) throw new Error('Failed to fetch scroll data')
+
+    const data = await response.json()
+    scrollData = data.scrollDepths || []
+    avgScrollDepth = data.avgMaxDepth || 0
+    totalScrollSessions = data.totalSessions || 0
+  } catch (err) {
+    error = err.message || 'Unknown error'
+    console.error('Scroll data fetch error:', err)
+  } finally {
+    loading = false
+  }
+}
+
+// Fetch data based on view mode
+export async function fetchData() {
+  if (viewMode === 'click') {
+    await fetchClickData()
+  } else if (viewMode === 'scroll') {
+    await fetchScrollData()
+  }
+}
+
+// Handle view mode change
+export function handleViewModeChange(mode) {
+  viewMode = mode
+  fetchData()
+}
+
+// Handle device filter change
+export function handleDeviceChange(device) {
+  deviceFilter = device
+  fetchData()
+}
+
+// Handle date range change
+export function handleDateRangeChange(range) {
+  startDate = range.start.toISOString().slice(0, 10)
+  endDate = range.end.toISOString().slice(0, 10)
+  fetchData()
+}
+
+// Handle element highlight
+export function handleHighlight(selector) {
+  console.log('Highlight:', selector)
+}
+
+// Handle element click
+export function handleElementClick(element) {
+  console.log('Element clicked:', element)
+}
+
+// Handle refresh
+export function handleRefresh() {
+  fetchData()
+}
+
+// Initialize
+if (typeof window !== 'undefined') {
+  setTimeout(fetchData, 0)
+}
+
+export { viewMode, deviceFilter, startDate, endDate, loading, error, clickData, topElements, totalClicks, scrollData, avgScrollDepth, totalScrollSessions, containerWidth, containerHeight }
+</script>
+
+<div class="page-heatmap flex flex-col gap-4 h-full">
+  <!-- Header -->
+  <div class="flex justify-between items-center">
+    <div class="flex flex-col gap-1">
+      <h2 class="text-xl font-semibold text-gray-900">Page Heatmap</h2>
+      <span class="text-sm text-gray-500 font-mono">{{ pageUrl }}</span>
+    </div>
+  </div>
+
+  <!-- Controls -->
+  @include('heatmap/HeatmapControls', {
+    viewMode: viewMode,
+    deviceFilter: deviceFilter,
+    startDate: startDate,
+    endDate: endDate,
+    loading: loading,
+    onViewModeChange: handleViewModeChange,
+    onDeviceChange: handleDeviceChange,
+    onDateRangeChange: handleDateRangeChange,
+    onRefresh: handleRefresh
+  })
+
+  <!-- Error state -->
+  @if(error)
+    <div class="flex items-center gap-3 px-4 py-3 bg-red-50 border border-red-200 rounded-lg text-red-600 text-sm">
+      <Icon name="alert-circle" size="20" class="flex-shrink-0" />
+      <span>{{ error }}</span>
+      <button type="button" class="ml-auto px-3 py-1 text-xs font-medium text-red-600 bg-white border border-red-200 rounded hover:bg-red-50" @click="fetchData">
+        Retry
+      </button>
+    </div>
+  @endif
+
+  <!-- Main content -->
+  <div class="grid grid-cols-1 lg:grid-cols-[1fr_320px] gap-6 flex-1 min-h-0">
+    <!-- Visualization area -->
+    <div class="flex flex-col gap-4 bg-white rounded-lg border border-gray-200 p-4 overflow-hidden">
+      <!-- Click heatmap view -->
+      @if(viewMode === 'click')
+        <div class="relative flex-1 min-h-[400px] border border-gray-200 rounded-md overflow-hidden bg-gray-50">
+          <!-- Page iframe or screenshot -->
+          @if(!screenshotUrl)
+            <iframe
+              src="{{ pageUrl }}"
+              class="w-full h-full border-none pointer-events-none"
+              sandbox="allow-same-origin"
+              loading="lazy"
+            />
+          @else
+            <img
+              src="{{ screenshotUrl }}"
+              alt="Screenshot of {{ pageUrl }}"
+              class="w-full h-full object-cover object-top"
+            />
+          @endif
+
+          <!-- Heatmap overlay -->
+          @include('heatmap/ClickHeatmap', {
+            clicks: clickData,
+            width: containerWidth,
+            height: containerHeight,
+            loading: loading
+          })
+        </div>
+
+        <!-- Legend -->
+        <div class="flex justify-between items-center pt-3 border-t border-gray-200">
+          @include('heatmap/HeatmapLegend', {
+            showValues: true,
+            maxValue: totalClicks
+          })
+          <span class="text-xs text-gray-500">{{ totalClicks.toLocaleString() }} total clicks</span>
+        </div>
+
+      @elseif(viewMode === 'scroll')
+        <!-- Scroll heatmap view -->
+        @include('heatmap/ScrollHeatmap', {
+          data: scrollData,
+          avgMaxDepth: avgScrollDepth,
+          totalSessions: totalScrollSessions,
+          height: containerHeight,
+          loading: loading
+        })
+
+      @else
+        <!-- Movement heatmap view (placeholder) -->
+        <div class="flex flex-col items-center justify-center h-full text-gray-500 text-center">
+          <Icon name="trending-up" size="48" class="mb-4 opacity-50" />
+          <h3 class="text-base font-semibold text-gray-600 mb-2">Movement Tracking</h3>
+          <p class="text-sm">Mouse movement heatmaps coming soon</p>
+        </div>
+      @endif
+    </div>
+
+    <!-- Sidebar -->
+    @if(viewMode === 'click')
+      <div class="flex flex-col gap-4 min-h-0 overflow-y-auto lg:max-h-none max-h-[300px]">
+        @include('heatmap/ElementClickList', {
+          elements: topElements,
+          loading: loading,
+          maxItems: 15,
+          onHighlight: handleHighlight,
+          onClick: handleElementClick
+        })
+      </div>
+    @endif
+  </div>
+</div>

package/src/dashboard/components/heatmap/ScrollHeatmap.stx

@@ -0,0 +1,127 @@
+<script>
+/**
+ * ScrollHeatmap Component
+ *
+ * Visualizes scroll depth as horizontal bands showing reach percentage.
+ */
+export const data = $props.data || []
+export const avgMaxDepth = $props.avgMaxDepth || 0
+export const totalSessions = $props.totalSessions || 0
+export const height = $props.height || 400
+export const loading = $props.loading || false
+
+// Generate color based on reach percentage
+export function getColor(percentage) {
+  if (percentage >= 80) return '#10b981' // Green - high engagement
+  if (percentage >= 60) return '#34d399' // Light green
+  if (percentage >= 40) return '#fbbf24' // Yellow - medium engagement
+  if (percentage >= 20) return '#f97316' // Orange
+  return '#ef4444' // Red - low engagement
+}
+
+export function formatTime(ms) {
+  if (ms < 1000) return `${ms}ms`
+  const seconds = Math.floor(ms / 1000)
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  const remainingSeconds = seconds % 60
+  return `${minutes}m ${remainingSeconds}s`
+}
+
+// Create depth buckets from 0 to 100 in increments of 10
+const depthBuckets = []
+for (let depth = 0; depth <= 90; depth += 10) {
+  const dataPoint = data.find(d => d.depth === depth)
+  depthBuckets.push({
+    depth,
+    label: `${depth}%`,
+    reachPercentage: dataPoint?.reachPercentage ?? (depth === 0 ? 100 : 0),
+    avgTimeMs: dataPoint?.avgTimeMs ?? 0,
+    sessions: dataPoint?.sessions ?? 0,
+  })
+}
+
+export { depthBuckets }
+</script>
+
+<div class="scroll-heatmap bg-white rounded-lg border border-gray-200 p-6 relative">
+  <!-- Loading state -->
+  @if(loading)
+    <div class="absolute inset-0 flex items-center justify-center bg-white/80 z-10">
+      <div class="w-8 h-8 border-2 border-gray-200 border-t-indigo-600 rounded-full animate-spin" />
+    </div>
+  @endif
+
+  <!-- Summary stats -->
+  <div class="flex gap-8 mb-6">
+    <div class="flex flex-col">
+      <span class="text-2xl font-bold text-gray-900">{{ avgMaxDepth }}%</span>
+      <span class="text-xs text-gray-500">Avg. Scroll Depth</span>
+    </div>
+    <div class="flex flex-col">
+      <span class="text-2xl font-bold text-gray-900">{{ totalSessions.toLocaleString() }}</span>
+      <span class="text-xs text-gray-500">Total Sessions</span>
+    </div>
+  </div>
+
+  <!-- Scroll visualization -->
+  <div class="flex gap-8" style="height: {{ height }}px">
+    <!-- Page representation -->
+    <div class="w-[120px] flex-shrink-0">
+      <div class="h-full border-2 border-gray-300 rounded-md overflow-hidden bg-gray-50">
+        <div class="p-2 border-b border-gray-200 bg-white">
+          <div class="h-1.5 bg-gray-300 rounded mb-1" />
+          <div class="h-1.5 w-3/5 bg-gray-300 rounded" />
+        </div>
+        <div class="flex flex-col h-[calc(100%-2.5rem)]">
+          @each(bucket in depthBuckets)
+            <div
+              class="flex-1 flex items-center justify-center border-b border-dashed border-black/10 last:border-b-0"
+              style="background-color: {{ getColor(bucket.reachPercentage) }}; opacity: {{ bucket.reachPercentage / 100 }}"
+            >
+              <span class="text-[10px] font-semibold text-black/60">{{ bucket.label }}</span>
+            </div>
+          @endeach
+        </div>
+      </div>
+    </div>
+
+    <!-- Data column -->
+    <div class="flex-1">
+      <div class="flex flex-col h-full">
+        @each(bucket in depthBuckets)
+          <div class="flex-1 flex items-center gap-3">
+            <div class="flex-1 h-6 bg-gray-100 rounded overflow-hidden">
+              <div
+                class="h-full rounded transition-all duration-300"
+                style="width: {{ bucket.reachPercentage }}%; background-color: {{ getColor(bucket.reachPercentage) }}"
+              />
+            </div>
+            <div class="flex items-center gap-2 w-24 flex-shrink-0">
+              <span class="text-sm font-semibold text-gray-900 w-10">{{ bucket.reachPercentage }}%</span>
+              @if(bucket.avgTimeMs > 0)
+                <span class="text-xs text-gray-500">{{ formatTime(bucket.avgTimeMs) }}</span>
+              @endif
+            </div>
+          </div>
+        @endeach
+      </div>
+    </div>
+  </div>
+
+  <!-- Legend -->
+  <div class="flex justify-center gap-6 mt-6 pt-4 border-t border-gray-200">
+    <div class="flex items-center gap-1.5 text-xs text-gray-500">
+      <span class="w-3 h-3 rounded-sm" style="background: #10b981" />
+      <span>80%+ reach</span>
+    </div>
+    <div class="flex items-center gap-1.5 text-xs text-gray-500">
+      <span class="w-3 h-3 rounded-sm" style="background: #fbbf24" />
+      <span>40-60% reach</span>
+    </div>
+    <div class="flex items-center gap-1.5 text-xs text-gray-500">
+      <span class="w-3 h-3 rounded-sm" style="background: #ef4444" />
+      <span>&lt;20% reach</span>
+    </div>
+  </div>
+</div>

package/src/dashboard/components/heatmap/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Heatmap Components
+ *
+ * STX components for visualizing user interaction heatmaps.
+ */
+
+export { default as PageHeatmap } from './PageHeatmap.stx'
+export { default as ClickHeatmap } from './ClickHeatmap.stx'
+export { default as ScrollHeatmap } from './ScrollHeatmap.stx'
+export { default as HeatmapControls } from './HeatmapControls.stx'
+export { default as HeatmapLegend } from './HeatmapLegend.stx'
+export { default as ElementClickList } from './ElementClickList.stx'

package/src/dashboard/components/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Analytics Dashboard Components
+ *
+ * stx components for displaying analytics data.
+ * These are .stx files that need to be processed by the stx framework.
+ * Total: 31 components
+ *
+ * Components are exported as string identifiers pointing to the component files.
+ * The stx framework uses these to resolve and render the components at runtime.
+ */
+
+// Component name constants - use these when referencing components in stx templates
+export const AlertCard = 'AlertCard'
+export const AnalyticsDashboard = 'AnalyticsDashboard'
+export const AnimatedNumber = 'AnimatedNumber'
+export const BarChart = 'BarChart'
+export const BrowserBreakdown = 'BrowserBreakdown'
+export const CampaignBreakdown = 'CampaignBreakdown'
+export const CountryList = 'CountryList'
+export const DataTable = 'DataTable'
+export const DateRangePicker = 'DateRangePicker'
+export const DeviceBreakdown = 'DeviceBreakdown'
+export const DonutChart = 'DonutChart'
+export const EmptyState = 'EmptyState'
+export const EngagementMetrics = 'EngagementMetrics'
+export const FilterBar = 'FilterBar'
+export const FullAnalyticsDashboard = 'FullAnalyticsDashboard'
+export const FunnelChart = 'FunnelChart'
+export const GoalsPanel = 'GoalsPanel'
+export const HeatmapChart = 'HeatmapChart'
+export const LiveActivityFeed = 'LiveActivityFeed'
+export const MetricComparison = 'MetricComparison'
+export const MiniStats = 'MiniStats'
+export const OSBreakdown = 'OSBreakdown'
+export const PageDetailCard = 'PageDetailCard'
+export const ProgressRing = 'ProgressRing'
+export const RealtimeCounter = 'RealtimeCounter'
+export const SparklineChart = 'SparklineChart'
+export const StatCard = 'StatCard'
+export const ThemeSwitcher = 'ThemeSwitcher'
+export const TimeSeriesChart = 'TimeSeriesChart'
+export const TopList = 'TopList'
+export const TrendIndicator = 'TrendIndicator'
+
+// Component registry for dynamic component resolution
+export const componentRegistry: Record<string, string> = {
+  AlertCard: './AlertCard.stx',
+  AnalyticsDashboard: './AnalyticsDashboard.stx',
+  AnimatedNumber: './AnimatedNumber.stx',
+  BarChart: './BarChart.stx',
+  BrowserBreakdown: './BrowserBreakdown.stx',
+  CampaignBreakdown: './CampaignBreakdown.stx',
+  CountryList: './CountryList.stx',
+  DataTable: './DataTable.stx',
+  DateRangePicker: './DateRangePicker.stx',
+  DeviceBreakdown: './DeviceBreakdown.stx',
+  DonutChart: './DonutChart.stx',
+  EmptyState: './EmptyState.stx',
+  EngagementMetrics: './EngagementMetrics.stx',
+  FilterBar: './FilterBar.stx',
+  FullAnalyticsDashboard: './FullAnalyticsDashboard.stx',
+  FunnelChart: './FunnelChart.stx',
+  GoalsPanel: './GoalsPanel.stx',
+  HeatmapChart: './HeatmapChart.stx',
+  LiveActivityFeed: './LiveActivityFeed.stx',
+  MetricComparison: './MetricComparison.stx',
+  MiniStats: './MiniStats.stx',
+  OSBreakdown: './OSBreakdown.stx',
+  PageDetailCard: './PageDetailCard.stx',
+  ProgressRing: './ProgressRing.stx',
+  RealtimeCounter: './RealtimeCounter.stx',
+  SparklineChart: './SparklineChart.stx',
+  StatCard: './StatCard.stx',
+  ThemeSwitcher: './ThemeSwitcher.stx',
+  TimeSeriesChart: './TimeSeriesChart.stx',
+  TopList: './TopList.stx',
+  TrendIndicator: './TrendIndicator.stx',
+}
+
+// List of all component names
+export const allComponents: string[] = Object.keys(componentRegistry)
+
+// Function to get component file path
+export function getComponentPath(name: string): string | undefined {
+  return componentRegistry[name]
+}