ahoy_analytics 0.1.0

data/app/frontend/pages/admin/analytics/lib/dialog-path.ts

@@ -0,0 +1,242 @@
+// Central helpers for building and parsing analytics dialog deep-links
+import { analyticsBasePath } from './base-path'
+
+export type SourcesMode = 'channels' | 'all' | 'utm-medium' | 'utm-source' | 'utm-campaign' | 'utm-content' | 'utm-term'
+
+export type DialogSegment =
+  | 'channels'
+  | 'sources'
+  | 'utm_mediums'
+  | 'utm_sources'
+  | 'utm_campaigns'
+  | 'utm_contents'
+  | 'utm_terms'
+  | 'pages'
+  | 'entry-pages'
+  | 'exit-pages'
+  | 'browsers'
+  | 'operating-systems'
+  | 'screen-sizes'
+  | 'countries'
+  | 'regions'
+  | 'cities'
+  | 'devices'
+  | 'locations'
+  | 'behaviors'
+
+const MODE_TO_SEGMENT: Record<SourcesMode, DialogSegment> = {
+  channels: 'channels',
+  all: 'sources',
+  'utm-medium': 'utm_mediums',
+  'utm-source': 'utm_sources',
+  'utm-campaign': 'utm_campaigns',
+  'utm-content': 'utm_contents',
+  'utm-term': 'utm_terms'
+}
+
+// Accepts underscore/hyphen and singular/plural variants
+const SEGMENT_NORMALIZE: Record<string, DialogSegment> = {
+  channels: 'channels',
+  sources: 'sources',
+  // mediums
+  'utm-medium': 'utm_mediums',
+  utm_medium: 'utm_mediums',
+  'utm-mediums': 'utm_mediums',
+  utm_mediums: 'utm_mediums',
+  // sources
+  'utm-source': 'utm_sources',
+  utm_source: 'utm_sources',
+  'utm-sources': 'utm_sources',
+  utm_sources: 'utm_sources',
+  // campaigns
+  'utm-campaign': 'utm_campaigns',
+  utm_campaign: 'utm_campaigns',
+  'utm-campaigns': 'utm_campaigns',
+  utm_campaigns: 'utm_campaigns',
+  // contents
+  'utm-content': 'utm_contents',
+  utm_content: 'utm_contents',
+  'utm-contents': 'utm_contents',
+  utm_contents: 'utm_contents',
+  // terms
+  'utm-term': 'utm_terms',
+  utm_term: 'utm_terms',
+  'utm-terms': 'utm_terms',
+  utm_terms: 'utm_terms',
+  // other panels
+  pages: 'pages',
+  'entry-pages': 'entry-pages',
+  entry_pages: 'entry-pages',
+  entry: 'entry-pages',
+  'exit-pages': 'exit-pages',
+  exit_pages: 'exit-pages',
+  exit: 'exit-pages',
+  // devices
+  browsers: 'browsers',
+  'operating-systems': 'operating-systems',
+  operating_systems: 'operating-systems',
+  'screen-sizes': 'screen-sizes',
+  screen_sizes: 'screen-sizes',
+  // locations
+  countries: 'countries',
+  regions: 'regions',
+  cities: 'cities',
+  devices: 'devices',
+  locations: 'locations',
+  behaviors: 'behaviors'
+}
+
+export function dialogSegmentForMode(mode: SourcesMode): DialogSegment {
+  return MODE_TO_SEGMENT[mode] || 'sources'
+}
+
+export type ParsedDialog =
+  | { type: 'segment'; segment: DialogSegment }
+  | { type: 'referrers'; source: string }
+  | { type: 'none' }
+
+export function parseDialogFromPath(pathname: string): ParsedDialog {
+  const base = analyticsBasePath()
+  const refPrefix = `${base}/_/referrers/`
+  if (pathname.startsWith(refPrefix)) {
+    const source = pathname.slice(refPrefix.length)
+    if (source) {
+      try {
+        return { type: 'referrers', source: decodeURIComponent(source) }
+      } catch {
+        return { type: 'referrers', source }
+      }
+    }
+  }
+
+  const segmentPrefix = `${base}/_/`
+  if (pathname.startsWith(segmentPrefix)) {
+    const raw = pathname.slice(segmentPrefix.length)
+    const seg = SEGMENT_NORMALIZE[raw]
+    if (seg) return { type: 'segment', segment: seg }
+  }
+
+  return { type: 'none' }
+}
+
+export function buildDialogPath(segment: DialogSegment, qs: string = ''): string {
+  const base = `${analyticsBasePath()}/_/${segment}`
+  return qs ? `${base}?${qs}` : base
+}
+
+export function buildReferrersPath(source: string, qs: string = ''): string {
+  const base = `${analyticsBasePath()}/_/referrers/${encodeURIComponent(source)}`
+  return qs ? `${base}?${qs}` : base
+}
+
+export function baseAnalyticsPath(qs: string = ''): string {
+  const base = analyticsBasePath()
+  return qs ? `${base}?${qs}` : base
+}
+
+// Map dialog segment back to the Sources panel mode
+export function modeForSegment(segment: DialogSegment): SourcesMode | null {
+  switch (segment) {
+    case 'channels':
+      return 'channels'
+    case 'sources':
+      return 'all'
+    case 'utm_mediums':
+      return 'utm-medium'
+    case 'utm_sources':
+      return 'utm-source'
+    case 'utm_campaigns':
+      return 'utm-campaign'
+    case 'utm_contents':
+      return 'utm-content'
+    case 'utm_terms':
+      return 'utm-term'
+    default:
+      return null
+  }
+}
+
+// Pages mapping helpers
+export type PagesMode = 'pages' | 'entry' | 'exit'
+
+export function pagesSegmentForMode(mode: PagesMode): DialogSegment {
+  switch (mode) {
+    case 'entry':
+      return 'entry-pages'
+    case 'exit':
+      return 'exit-pages'
+    case 'pages':
+    default:
+      return 'pages'
+  }
+}
+
+export function pagesModeForSegment(segment: DialogSegment): PagesMode | null {
+  switch (segment) {
+    case 'pages':
+      return 'pages'
+    case 'entry-pages':
+      return 'entry'
+    case 'exit-pages':
+      return 'exit'
+    default:
+      return null
+  }
+}
+
+// Devices mapping helpers
+export type DevicesMode = 'browsers' | 'operating-systems' | 'screen-sizes'
+
+export function devicesSegmentForMode(mode: DevicesMode): DialogSegment {
+  switch (mode) {
+    case 'operating-systems':
+      return 'operating-systems'
+    case 'screen-sizes':
+      return 'screen-sizes'
+    case 'browsers':
+    default:
+      return 'browsers'
+  }
+}
+
+export function devicesModeForSegment(segment: DialogSegment): DevicesMode | null {
+  switch (segment) {
+    case 'browsers':
+      return 'browsers'
+    case 'operating-systems':
+      return 'operating-systems'
+    case 'screen-sizes':
+      return 'screen-sizes'
+    default:
+      return null
+  }
+}
+
+// Locations mapping helpers
+export type LocationsMode = 'map' | 'countries' | 'regions' | 'cities'
+
+export function locationsSegmentForMode(mode: LocationsMode): DialogSegment {
+  switch (mode) {
+    case 'regions':
+      return 'regions'
+    case 'cities':
+      return 'cities'
+    case 'countries':
+    case 'map':
+    default:
+      return 'countries' // default dialog for locations
+  }
+}
+
+export function locationsModeForSegment(segment: DialogSegment): Exclude<LocationsMode, 'map'> | null {
+  switch (segment) {
+    case 'countries':
+      return 'countries'
+    case 'regions':
+      return 'regions'
+    case 'cities':
+      return 'cities'
+    default:
+      return null
+  }
+}

data/app/frontend/pages/admin/analytics/lib/number-formatter.ts

@@ -0,0 +1,100 @@
+// Number formatting utilities following Plausible's exact implementation
+// Source: plausible/assets/js/dashboard/util/number-formatter.ts
+
+const THOUSAND = 1000
+const HUNDRED_THOUSAND = 100000
+const MILLION = 1000000
+const HUNDRED_MILLION = 100000000
+const BILLION = 1000000000
+const HUNDRED_BILLION = 100000000000
+const TRILLION = 1000000000000
+
+const numberFormat = Intl.NumberFormat('en-US')
+
+/**
+ * Formats numbers in short form with k/M/B suffixes.
+ * Examples: 1234 → "1.2k", 1234567 → "1.2M"
+ */
+export function numberShortFormatter(num: number): string {
+  if (num >= THOUSAND && num < MILLION) {
+    const thousands = num / THOUSAND
+    if (thousands === Math.floor(thousands) || num >= HUNDRED_THOUSAND) {
+      return Math.floor(thousands) + 'k'
+    } else {
+      return Math.floor(thousands * 10) / 10 + 'k'
+    }
+  } else if (num >= MILLION && num < BILLION) {
+    const millions = num / MILLION
+    if (millions === Math.floor(millions) || num >= HUNDRED_MILLION) {
+      return Math.floor(millions) + 'M'
+    } else {
+      return Math.floor(millions * 10) / 10 + 'M'
+    }
+  } else if (num >= BILLION && num < TRILLION) {
+    const billions = num / BILLION
+    if (billions === Math.floor(billions) || num >= HUNDRED_BILLION) {
+      return Math.floor(billions) + 'B'
+    } else {
+      return Math.floor(billions * 10) / 10 + 'B'
+    }
+  } else {
+    return num.toString()
+  }
+}
+
+/**
+ * Formats numbers with thousand separators.
+ * Examples: 1234 → "1,234", 1234567 → "1,234,567"
+ */
+export function numberLongFormatter(num: number): string {
+  return numberFormat.format(num)
+}
+
+/**
+ * Wraps a formatter to handle null and undefined values.
+ * Returns "-" for null or undefined, otherwise applies the formatter.
+ */
+export function nullable<T>(
+  formatter: (num: T) => string
+): (num: T | null | undefined) => string {
+  return (num: T | null | undefined): string => {
+    if (num == null) {
+      return '-'
+    }
+    return formatter(num)
+  }
+}
+
+function pad(num: number, size: number): string {
+  return ('000' + num).slice(size * -1)
+}
+
+/**
+ * Formats duration in seconds to human-readable format.
+ * Examples: 65 → "1m 05s", 3665 → "1h 1m 5s"
+ */
+export function durationFormatter(duration: number): string {
+  const hours = Math.floor(duration / 60 / 60)
+  const minutes = Math.floor(duration / 60) % 60
+  const seconds = Math.floor(duration - minutes * 60 - hours * 60 * 60)
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${seconds}s`
+  } else if (minutes > 0) {
+    return `${minutes}m ${pad(seconds, 2)}s`
+  } else {
+    return `${seconds}s`
+  }
+}
+
+/**
+ * Formats percentage values.
+ * Backend returns decimals (0.45), we convert to whole numbers (45%)
+ * Example: 0.45 → "45%", 0.123 → "12.3%"
+ */
+export function percentageFormatter(value: number | null): string {
+  if (value == null || Number.isNaN(value as number)) return '-'
+  const num = Number(value)
+  // Accept both decimal fractions (0.0645) and percent values (6.45)
+  const pct = num <= 1 ? (Math.round(num * 1000) / 10) : (Math.round(num * 10) / 10)
+  return `${pct}%`
+}