@antelopejs/dms-marketing 0.2.2

package/frontend-vue/app/components/PagesView.vue

@@ -0,0 +1,378 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import {
+  useDmsRoute,
+  useDmsRouter,
+  useI18n,
+} from '#dms/frontend-module'
+import { useChildId } from '../composables/useChildId'
+import { useLatestRequest } from '../composables/useLatestRequest'
+import {
+  useMarketingApi,
+  type MarketingPages,
+} from '../composables/useMarketingApi'
+import {
+  MARKETING_PERIOD_PRESETS,
+  ndToPreset,
+  useMarketingPeriod,
+} from '../composables/useMarketingPeriod'
+import { funnelsLink, pagesLink } from '../composables/useMarketingRoutes'
+import { useMarketingWebsites } from '../composables/useMarketingWebsites'
+
+/**
+ * Tracked pages of a site: the inventory on the left, the clicks and scroll
+ * depth of the selected page on the right.
+ *
+ * The surface is deliberately keyed on nothing but a website id and a bare
+ * pathname the tracker itself reported — no route registry, no sitemap, no
+ * build manifest, no framework convention. That is what makes it hold for any
+ * tracked site, whatever it is built with.
+ *
+ * The search box is also a path field, and that is not a fallback: a day keeps
+ * at most MAX_ENTRIES_PER_TOP_MAP paths and older days keep counters only, so
+ * a page can be missing from the inventory while its clicks are perfectly
+ * queryable — the backend matches the path exactly either way.
+ */
+const PERIOD_SCOPE = 'dms-marketing-pages'
+const SEARCH_DEBOUNCE_MS = 300
+
+// Declared, not inherited as attributes: the DMS page renderer hands every
+// component its identity, and an undeclared prop lands on the root element.
+const props = withDefaults(
+  defineProps<{ componentId?: string, pageId?: string }>(),
+  { componentId: 'marketing-pages', pageId: 'marketing' },
+)
+
+const childId = useChildId(() => props.componentId)
+
+const api = useMarketingApi()
+const { t } = useI18n()
+const route = useDmsRoute()
+const router = useDmsRouter()
+
+const queryParam = (key: string): string => {
+  const value = route.query[key]
+  return typeof value === 'string' ? value : ''
+}
+
+// Read once: the selector seeds its preset at init and never reactively, so a
+// deep link's window has to be resolved before it renders.
+const initialPreset = ndToPreset(queryParam('period'))
+
+const {
+  websites,
+  items: websiteItems,
+  selectedId: selectedWebsiteId,
+  selected: selectedWebsite,
+  loading: loadingWebsites,
+  failed: websitesFailed,
+  load: loadWebsites,
+  create: createWebsite,
+} = useMarketingWebsites(queryParam('website'))
+
+// `undefined`, not null: this is what DmsMasterDetail's model is typed on.
+const selectedPath = ref<string | undefined>(queryParam('path') || undefined)
+const search = ref('')
+
+const period = useMarketingPeriod(PERIOD_SCOPE)
+
+let searchTimer: ReturnType<typeof setTimeout> | null = null
+
+const {
+  data: inventory,
+  loading: loadingPages,
+  failed: pagesFailed,
+  run: loadPages,
+} = useLatestRequest<MarketingPages>(() =>
+  // Server-side there is no session to authenticate with: the fetch belongs to
+  // the client, like every other read here.
+  selectedWebsiteId.value && !import.meta.env.SSR
+    ? api.listPages(selectedWebsiteId.value, period.value, search.value.trim())
+    : null,
+)
+
+const pages = computed(() => inventory.value?.pages ?? [])
+const truncated = computed(() => inventory.value?.truncated ?? false)
+const sampleRate = computed(() => inventory.value?.heatmapSampleRate ?? 0)
+const trackerEnabled = computed(() => inventory.value?.trackerEnabled ?? true)
+
+// Two failures, two flags: the inventory fetch clears its own error on every
+// attempt, and must not clear the one that says the site list never loaded.
+const failed = computed(() => websitesFailed.value || pagesFailed.value)
+
+// Land on something rather than on an empty pane, but never override a path
+// that was linked to or typed. Watching the answer rather than writing from
+// the fetch keeps superseded ones out: only the newest ever reaches here.
+watch(inventory, (data) => {
+  if (!selectedPath.value) {
+    selectedPath.value = data?.pages[0]?.path
+  }
+})
+
+/**
+ * Retry entry point. Both fetches, in order, because either can be the one
+ * that failed: on a deep link the inventory runs even when the site list did
+ * not, and reloading the list alone leaves the selection unchanged, so the
+ * watcher never fires and the inventory is never retried.
+ */
+async function reload() {
+  if (websites.value.length === 0) {
+    await loadWebsites()
+  }
+  await loadPages()
+}
+
+onMounted(loadWebsites)
+
+// The watcher owns every inventory fetch, including the first: seeding it from
+// onMounted as well would issue the initial request twice on a bare link, and
+// not at all on a link that already names the site the list would have picked.
+watch([selectedWebsiteId, period], ([websiteId], previous) => {
+  // Switching site invalidates the path — the same URL on another site is
+  // another page, and usually does not exist there. Only a real site-to-site
+  // change may clear: the immediate run hands multi-source watchers an EMPTY
+  // previous array (truthy — `previous &&` does not guard it), and the site
+  // list resolving undefined → id is not a switch either. Both carry a linked
+  // path that must survive.
+  const previousWebsiteId = previous?.[0]
+  if (previousWebsiteId !== undefined && websiteId !== previousWebsiteId) {
+    selectedPath.value = undefined
+  }
+  void loadPages()
+}, { immediate: true })
+
+watch(search, () => {
+  if (searchTimer) {
+    clearTimeout(searchTimer)
+  }
+  searchTimer = setTimeout(() => void loadPages(), SEARCH_DEBOUNCE_MS)
+})
+
+onBeforeUnmount(() => {
+  if (searchTimer) {
+    clearTimeout(searchTimer)
+  }
+})
+
+/** Enter inspects what was typed, whether or not the inventory lists it. */
+function inspectTyped(): void {
+  const typed = search.value.trim()
+  if (!typed.startsWith('/')) {
+    return
+  }
+  selectedPath.value = typed
+}
+
+// State lives in the URL so a heatmap can be linked to. Query-only navigation
+// does not remount the page, so this is free.
+watch([selectedWebsiteId, selectedPath, period], () => {
+  void router.replace(
+    pagesLink({
+      website: selectedWebsiteId.value,
+      path: selectedPath.value,
+      period: period.value,
+    }),
+  )
+})
+
+const pageviewsBySelected = computed(
+  () => pages.value.find(page => page.path === selectedPath.value)?.pageviews,
+)
+
+const listItems = computed(() =>
+  pages.value.map((page) => {
+    // Sampled PAGE LOADS, not clicks: the tracker draws once per page load,
+    // so this says whether a heatmap can exist at all — a click estimate here
+    // would contradict the real count shown beside it in the detail pane.
+    const sampled = Math.round(page.pageviews * sampleRate.value)
+    // Two counts, two plural choices: one message could only ever inflect on
+    // one of them, and the two rarely agree.
+    return {
+      value: page.path,
+      label: page.path,
+      sublabel: [
+        t('page.marketing.pages.row_hint.views', { count: page.pageviews }, page.pageviews),
+        t('page.marketing.pages.row_hint.sampled', { count: sampled }, sampled),
+      ].join(' · '),
+    }
+  }),
+)
+
+// --- Site-wide reset --------------------------------------------------------
+
+const { confirm } = useConfirm()
+const toast = useToast()
+const resettingHeatmaps = ref(false)
+
+/**
+ * The detail pane refetches on this bump: a site-wide reset changes none of
+ * the keys it watches (site, path, period), so without it the pane would keep
+ * showing clicks that no longer exist. The inventory needs no reload — its
+ * pageview counts come from the rollup, which a click purge never touches.
+ */
+const heatmapRefreshToken = ref(0)
+
+async function resetSiteHeatmaps() {
+  const site = selectedWebsite.value
+  if (!site) {
+    return
+  }
+  const confirmed = await confirm({
+    title: t('page.marketing.pages.reset.site_title'),
+    description: t('page.marketing.pages.reset.site_description', { name: site.name }),
+    confirmLabel: t('page.marketing.pages.reset.confirm'),
+    confirmColor: 'error',
+  })
+  if (!confirmed) {
+    return
+  }
+  resettingHeatmaps.value = true
+  try {
+    const { deleted } = await api.resetHeatmap(site._id)
+    toast.add({
+      color: 'success',
+      title: t('page.marketing.pages.reset.done', { count: deleted }, deleted),
+    })
+    heatmapRefreshToken.value++
+  }
+  catch {
+    toast.add({ color: 'error', title: t('page.marketing.pages.reset.error') })
+  }
+  finally {
+    resettingHeatmaps.value = false
+  }
+}
+</script>
+
+<template>
+  <div class="space-y-6 p-6">
+    <div class="flex flex-wrap items-center justify-between gap-4">
+      <div>
+        <h1 class="text-xl font-semibold">{{ t('page.marketing.pages.title') }}</h1>
+        <p class="text-sm text-muted">{{ t('page.marketing.pages.subtitle') }}</p>
+      </div>
+      <div class="flex flex-wrap items-center gap-3">
+        <USelect
+          v-if="websites.length > 1"
+          v-model="selectedWebsiteId"
+          :items="websiteItems"
+          class="w-56"
+        />
+        <UInput
+          v-model="search"
+          icon="i-ph-magnifying-glass"
+          class="w-64"
+          :placeholder="t('page.marketing.pages.search_placeholder')"
+          @keyup.enter="inspectTyped"
+        />
+        <DmsPeriodSelector
+          :id="PERIOD_SCOPE"
+          :component-id="childId('period')"
+          :page-id="props.pageId"
+          :default-preset="initialPreset"
+          :presets="MARKETING_PERIOD_PRESETS"
+          :comparisons="['none']"
+          :show-range-label="false"
+        />
+        <UButton
+          v-if="selectedWebsiteId"
+          icon="i-ph-funnel"
+          color="neutral"
+          variant="ghost"
+          size="sm"
+          :to="funnelsLink({ website: selectedWebsiteId })"
+          :label="t('page.marketing.pages.to_funnels')"
+        />
+        <UButton
+          v-if="selectedWebsiteId"
+          icon="i-ph-eraser"
+          color="neutral"
+          variant="ghost"
+          size="sm"
+          :loading="resettingHeatmaps"
+          :label="t('page.marketing.pages.reset.site_button')"
+          @click="resetSiteHeatmaps"
+        />
+      </div>
+    </div>
+
+    <UAlert
+      v-if="!trackerEnabled"
+      icon="i-ph-plugs"
+      color="warning"
+      variant="subtle"
+      :title="t('page.marketing.pages.tracking_off.title')"
+      :description="t('page.marketing.pages.tracking_off.description')"
+    />
+
+    <div v-if="failed" class="flex flex-col items-start gap-3">
+      <UAlert
+        color="error"
+        variant="subtle"
+        icon="i-ph-warning-circle"
+        :title="t('page.marketing.pages.error')"
+        :description="t('page.marketing.pages.error_hint')"
+      />
+      <UButton
+        icon="i-ph-arrow-clockwise"
+        :label="t('page.marketing.pages.retry')"
+        color="neutral"
+        variant="subtle"
+        size="sm"
+        @click="reload"
+      />
+    </div>
+
+    <USkeleton v-else-if="loadingWebsites" class="h-96 w-full" />
+
+    <DmsMarketingNoWebsiteState
+      v-else-if="websites.length === 0"
+      icon="i-ph-globe"
+      :title="t('page.marketing.pages.no_website.title')"
+      :description="t('page.marketing.pages.no_website.description')"
+      @create="createWebsite"
+    />
+
+    <template v-else>
+      <UAlert
+        v-if="truncated"
+        icon="i-ph-list"
+        color="neutral"
+        variant="subtle"
+        :title="t('page.marketing.pages.list_truncated')"
+        :description="t('page.marketing.pages.list_truncated_hint')"
+      />
+
+      <!-- An empty inventory is not an empty surface: a typed path is
+           inspectable whether or not the rollup ever listed it. -->
+      <UAlert
+        v-if="!loadingPages && pages.length === 0 && !selectedPath"
+        icon="i-ph-cursor-click"
+        :title="t('page.marketing.pages.no_pages.title')"
+        :description="t('page.marketing.pages.no_pages.description')"
+      />
+
+      <DmsMasterDetail
+        v-else
+        v-model="selectedPath"
+        :items="listItems"
+        :list-label="t('page.marketing.pages.inventory')"
+      >
+        <DmsMarketingPagePreview
+          v-if="selectedPath"
+          :website="selectedWebsite"
+          :path="selectedPath"
+          :period="period"
+          :sample-rate="sampleRate"
+          :tracker-enabled="trackerEnabled"
+          :pageviews="pageviewsBySelected"
+          :refresh-token="heatmapRefreshToken"
+          @website-updated="loadWebsites"
+        />
+        <div v-else class="p-8 text-center text-sm text-muted">
+          {{ t('page.marketing.pages.select_hint') }}
+        </div>
+      </DmsMasterDetail>
+    </template>
+  </div>
+</template>

package/frontend-vue/app/components/ScrollDepthOverlay.vue

@@ -0,0 +1,158 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { useI18n } from '#dms/frontend-module'
+import { heatColorAt } from '../utils/heatmapPalette'
+
+/**
+ * Scroll-depth overlay of one tracked page: a vertical gradient of how many
+ * measured views saw each band of the page, reach marks at fixed shares, and
+ * a readout following the pointer.
+ *
+ * Drawn in the pane's scaled space as a sibling of the scaled surface, not
+ * inside it: depth only varies vertically, so fractions of the pane's height
+ * are fractions of the document — and the labels keep their font size at
+ * every zoom instead of shrinking with the page.
+ *
+ * `foldRatio` is where depth 0 sits. A recorded depth is a fraction of the
+ * visitor's *scrollable range*, whose zero already has the first viewport on
+ * screen; the probe viewport stands in for visitor viewports this surface
+ * cannot know. Bands are trustworthy, pixels are not. Above the fold the
+ * shade is flat — every measured view starts there.
+ */
+const props = defineProps<{
+  /** reached[d] = views whose max depth is ≥ d percent, d = 0..100. */
+  reached: number[]
+  /** Views that scrolled at all — the denominator of every share shown. */
+  views: number
+  /** Height of the overlay in the pane's own pixels (already scaled). */
+  height: number
+  /** 0-1 fraction of the height where depth 0 sits (the first viewport). */
+  foldRatio: number
+}>()
+
+const DEPTH_SCALE = 100
+/** Gradient resolution; the distribution is monotonic, so 5% steps lose
+ * nothing a reader could see. */
+const GRADIENT_STEP = 5
+const OVERLAY_ALPHA = 0.35
+/** Shares worth a labelled line — the "50% of visitors stop here" reading. */
+const REACH_MARKS = [75, 50, 25]
+
+const { t } = useI18n()
+
+function reachAt(depth: number): number {
+  if (props.views <= 0) {
+    return 0
+  }
+  const clamped = Math.min(Math.max(depth, 0), DEPTH_SCALE)
+  return (props.reached[clamped] ?? 0) / props.views
+}
+
+/** Depth percent → 0-1 fraction of the drawn height. */
+function yRatio(depth: number): number {
+  return props.foldRatio + (depth / DEPTH_SCALE) * (1 - props.foldRatio)
+}
+
+const gradient = computed(() => {
+  const colorFor = (fraction: number) => heatColorAt(fraction, OVERLAY_ALPHA)
+  const stops = [`${colorFor(1)} 0%`]
+  for (let depth = 0; depth <= DEPTH_SCALE; depth += GRADIENT_STEP) {
+    stops.push(`${colorFor(reachAt(depth))} ${(yRatio(depth) * 100).toFixed(2)}%`)
+  }
+  return `linear-gradient(to bottom, ${stops.join(', ')})`
+})
+
+/** Deepest point at least `percent`% of the measured views got to. */
+function depthReachedBy(percent: number): number {
+  for (let depth = DEPTH_SCALE; depth >= 0; depth--) {
+    if (reachAt(depth) >= percent / DEPTH_SCALE) {
+      return depth
+    }
+  }
+  return 0
+}
+
+const marks = computed(() => {
+  const placed: Array<{ percent: number, y: number }> = []
+  for (const percent of REACH_MARKS) {
+    const y = yRatio(depthReachedBy(percent)) * props.height
+    // Collapsed shares (everyone stops at one depth) would stack identical
+    // lines; the strongest claim wins.
+    if (placed.every(mark => Math.abs(mark.y - y) > 1)) {
+      placed.push({ percent, y })
+    }
+  }
+  return placed
+})
+
+const foldY = computed(() => props.foldRatio * props.height)
+const showFold = computed(() => props.foldRatio > 0 && props.foldRatio < 1)
+
+const hover = ref<{ y: number, percent: number } | null>(null)
+
+function onPointerMove(event: PointerEvent): void {
+  const rect = (event.currentTarget as HTMLElement).getBoundingClientRect()
+  if (rect.height <= 0 || props.foldRatio >= 1) {
+    return
+  }
+  const ratio = Math.min(Math.max((event.clientY - rect.top) / rect.height, 0), 1)
+  const depth = ratio <= props.foldRatio
+    ? 0
+    : Math.round(((ratio - props.foldRatio) / (1 - props.foldRatio)) * DEPTH_SCALE)
+  hover.value = {
+    y: ratio * props.height,
+    percent: Math.round(reachAt(depth) * 100),
+  }
+}
+</script>
+
+<template>
+  <div
+    class="absolute inset-0"
+    @pointermove="onPointerMove"
+    @pointerleave="hover = null"
+  >
+    <div class="pointer-events-none absolute inset-0" :style="{ background: gradient }" />
+
+    <div
+      v-if="showFold"
+      class="pointer-events-none absolute inset-x-0"
+      :style="{ top: `${foldY}px`, borderTop: '1px solid rgba(255, 255, 255, 0.55)' }"
+    >
+      <span
+        class="absolute left-2 top-0 -translate-y-1/2 rounded-full bg-default/90 px-2 py-0.5 text-xs text-muted shadow"
+      >
+        {{ t('page.marketing.pages.scroll.fold_line') }}
+      </span>
+    </div>
+
+    <div
+      v-for="mark in marks"
+      :key="mark.percent"
+      class="pointer-events-none absolute inset-x-0"
+      :style="{
+        top: `${mark.y}px`,
+        borderTop: '2px dashed rgba(255, 255, 255, 0.85)',
+        filter: 'drop-shadow(0 1px 1px rgba(0, 0, 0, 0.4))',
+      }"
+    >
+      <span
+        class="absolute right-2 top-0 -translate-y-1/2 rounded-full bg-default/90 px-2 py-0.5 text-xs font-medium text-highlighted shadow"
+      >
+        {{ t('page.marketing.pages.scroll.reach_line', { percent: mark.percent }) }}
+      </span>
+    </div>
+
+    <div
+      v-if="hover"
+      class="pointer-events-none absolute inset-x-0"
+      :style="{ top: `${hover.y}px`, borderTop: '1px solid rgba(255, 255, 255, 0.95)' }"
+    >
+      <span
+        class="absolute left-2 top-0 -translate-y-1/2 rounded-full bg-default/90 px-2 py-0.5 text-xs font-medium text-highlighted shadow"
+      >
+        {{ t('page.marketing.pages.scroll.reach_line', { percent: hover.percent }) }}
+      </span>
+    </div>
+  </div>
+</template>

package/frontend-vue/app/components/TextKpiCard.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+/**
+ * The stat-variant DmsKpiCard look for a value that is not a plain number:
+ * dms-ui's card only formats numeric values (number / currency / percent),
+ * and a session duration reads as "1m 32s", which is none of them. Classes
+ * are copied from KpiCard's stat variant so the card sits in the same row
+ * without a seam.
+ */
+defineProps<{ title: string, value: string, icon: string }>()
+</script>
+
+<template>
+  <DmsCard :padded="false" class="p-4 sm:p-5">
+    <div class="flex items-start justify-between gap-3">
+      <div class="min-w-0 flex-1">
+        <p class="text-dimmed truncate font-mono text-[10px] font-medium uppercase tracking-widest">
+          {{ title }}
+        </p>
+        <p class="mt-1 text-2xl font-semibold tracking-tight tabular-nums">
+          {{ value }}
+        </p>
+      </div>
+      <div class="text-dimmed flex shrink-0 items-center justify-center">
+        <UIcon :name="icon" class="size-4" aria-hidden="true" />
+      </div>
+    </div>
+  </DmsCard>
+</template>