@antelopejs/dms-marketing 0.4.0 → 0.5.0

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

@@ -1,24 +1,19 @@
 <script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { computed, onMounted, ref, watch } from 'vue'
 import {
   useDmsRoute,
   useDmsRouter,
   useDmsRuntimeConfig,
   useI18n,
 } from '#dms/frontend-module'
-import {
-  useMarketingApi,
-  type MarketingConnectionStatus,
-} from '../composables/useMarketingApi'
+import { useMarketingApi } from '../composables/useMarketingApi'
+import { useWebsiteConnection } from '../composables/useMarketingReads'
 import {
   installLink,
   overviewLink,
   websitesLink,
 } from '../composables/useMarketingRoutes'
-import {
-  allowHostConfirmation,
-  hostConflictOf,
-} from '../utils/host-conflict'
+import { allowHostConfirmation, hostConflictOf } from '../utils/host-conflict'
 import { trackerSnippet } from '../utils/snippet'
 
 /**
@@ -57,12 +52,20 @@ const fieldErrors = useFieldErrors({
 const websiteId = ref(
   typeof route.query.website === 'string' ? route.query.website : '',
 )
-const status = ref<MarketingConnectionStatus | null>(null)
-const failed = ref(false)
-/** The `?website=` names no site of the workspace (deleted, mistyped). */
-const missing = ref(false)
 /** Server time "Check again" waits from; null: since the site's creation. */
 const recheckSince = ref<number | null>(null)
+/** The check's polling period: `POLL_MS` while it waits for a pageview, 0 (stopped) otherwise. */
+const pollInterval = ref(0)
+const connection = useWebsiteConnection(websiteId, recheckSince, {
+  refreshInterval: pollInterval,
+})
+const status = connection.data
+/** The `?website=` names no site of the workspace (deleted, mistyped). */
+const missing = computed(
+  () => apiErrorStatus(connection.error.value) === HTTP_NOT_FOUND,
+)
+/** The last check failed; the next one is on its way. */
+const failed = computed(() => !!connection.error.value && !missing.value)
 
 // --- Step 1 ----------------------------------------------------------------------
 
@@ -95,7 +98,6 @@ async function createWebsite(): Promise<void> {
     await api.selectContextWebsite(created._id)
     websiteId.value = created._id
     await router.replace(installLink(created._id))
-    await poll()
   } catch (error) {
     const conflict = hostConflictOf(error)
     if (conflict) {
@@ -115,47 +117,27 @@ async function createWebsite(): Promise<void> {
 
 // --- Step 3: connection check ---------------------------------------------------
 
-let timer: ReturnType<typeof setTimeout> | null = null
-
-function stopPolling(): void {
-  if (timer) {
-    clearTimeout(timer)
-    timer = null
-  }
-}
-
-async function poll(): Promise<void> {
-  stopPolling()
-  if (!websiteId.value) {
-    return
-  }
-  try {
-    status.value = await api.getConnection(
-      websiteId.value,
-      recheckSince.value ?? undefined,
-    )
-    failed.value = false
-  } catch (error) {
-    if (apiErrorStatus(error) === HTTP_NOT_FOUND) {
-      missing.value = true
-      status.value = null
-      return
-    }
-    failed.value = true
-  }
-  if (!status.value?.visit) {
-    timer = setTimeout(() => void poll(), POLL_MS)
-  }
-}
+/** No pageview yet, and the site is there: the check polls. */
+const isWaiting = computed(
+  () => !!websiteId.value && !missing.value && !status.value?.visit,
+)
+// The check polls while it waits, and stops once a pageview arrived or the
+// site is gone.
+watch(
+  isWaiting,
+  (waiting) => {
+    pollInterval.value = waiting ? POLL_MS : 0
+  },
+  { immediate: true },
+)
 
 /** Waits for a pageview sent from now on, to re-verify an installed tag. */
-async function checkAgain(): Promise<void> {
+function checkAgain(): void {
   if (!status.value) {
     return
   }
   recheckSince.value = status.value.checkedAt
   status.value = { ...status.value, visit: null }
-  await poll()
 }
 
 const apiOrigin = ref('')
@@ -164,9 +146,7 @@ onMounted(() => {
   apiOrigin.value = String(
     (config.public as { dms?: { baseURL?: string } }).dms?.baseURL ?? '',
   )
-  void poll()
 })
-onBeforeUnmount(stopPolling)
 
 watch(
   () => route.query.website,
@@ -174,10 +154,8 @@ watch(
     const next = typeof value === 'string' ? value : ''
     if (next !== websiteId.value) {
       websiteId.value = next
-      status.value = null
-      missing.value = false
       recheckSince.value = null
-      void poll()
+      connection.clear()
     }
   },
 )
@@ -201,7 +179,8 @@ async function allow(hostname: string): Promise<void> {
       color: 'success',
       title: t('page.marketing.install.allowed', { host: hostname }),
     })
-    await poll()
+    // The refused host leaves the check before its button comes back.
+    await refreshPageBlocks()
   } catch (error) {
     const conflict = hostConflictOf(error)
     if (conflict) {
@@ -232,7 +211,7 @@ async function resumeTracking(): Promise<void> {
       color: 'success',
       title: t('page.marketing.websites.resumed'),
     })
-    await poll()
+    await refreshPageBlocks()
   } catch (error) {
     fieldErrors.toastError(error, {
       toastTitle: 'page.marketing.websites.save_error',
@@ -638,7 +617,9 @@ const stepTwoState = computed(() =>
                   />
                 </span>
                 <span class="min-w-0 flex-1">
-                  <span class="block font-semibold break-words text-highlighted">
+                  <span
+                    class="block font-semibold break-words text-highlighted"
+                  >
                     {{
                       t(
                         recheckSince === null
@@ -677,7 +658,9 @@ const stepTwoState = computed(() =>
               >
                 <DmsIconWell icon="i-ph-prohibit" tone="error" />
                 <span class="min-w-0 flex-1">
-                  <span class="block font-semibold break-words text-highlighted">
+                  <span
+                    class="block font-semibold break-words text-highlighted"
+                  >
                     {{
                       t(
                         'page.marketing.install.refused',

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

@@ -1,18 +1,21 @@
 <script setup lang="ts">
 import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
 import { useI18n } from '#dms/frontend-module'
-import { useLatestRequest } from '../composables/useLatestRequest'
 import {
   useMarketingApi,
   type MarketingPeriod,
-  type MarketingHeatmap,
-  type MarketingPageSnapshotResponse,
-  type MarketingScrollDepth,
   type MarketingSnapshotLayout,
   type MarketingWebsite,
   type MarketingWebsitePatch,
   type MarketingFunnelListItem,
 } from '../composables/useMarketingApi'
+import {
+  useHeatmapCountRead,
+  usePageHeatmap,
+  usePageScrollDepth,
+  usePageSnapshot,
+  type PagePreviewRequest,
+} from '../composables/useMarketingReads'
 import { funnelLink, settingsLink } from '../composables/useMarketingRoutes'
 import { formatNumber, formatShortDate } from '../utils/format'
 import {
@@ -77,17 +80,14 @@ const props = defineProps<{
   trackerEnabled: boolean
   /** Pageviews of this path over the window, for the sampling hint. */
   pageviews?: number
-  /** Bumped by the parent when it resets clicks out from under this view. */
-  refreshToken?: number
   /** Funnels with a page step on this path. */
   usedIn?: MarketingFunnelListItem[]
 }>()
 
-/** The site's snapshot options were changed here; the parent owns the row. */
+/** The site's snapshot options were saved here, as the backend answered
+ * them; the parent owns the row. */
 const emit = defineEmits<{
-  'website-updated': []
-  /** The page lost its clicks: the inventory counts them too. */
-  'heatmap-reset': []
+  'website-updated': [website: MarketingWebsite]
 }>()
 
 interface LayoutPreset {
@@ -138,19 +138,20 @@ const { t, locale } = useI18n()
 
 // --- Heatmap ----------------------------------------------------------------
 
-// Path, site and period all retrigger a load and the answers can land out of
-// order: a slow answer for the page the user just left would otherwise repaint
-// over the one on screen — see useLatestRequest.
-const {
-  data: heatmap,
-  loading,
-  failed,
-  run: loadHeatmap,
-} = useLatestRequest<MarketingHeatmap>(() =>
-  props.website && props.path && !import.meta.env.SSR
-    ? api.getHeatmap(props.website._id, props.path, props.period)
-    : null,
+// Path, site and period all read again, and a newer read replaces one still
+// in flight: a slow answer for the page the user just left never repaints
+// over the one on screen. Drawn in the browser only.
+const previewRequest: PagePreviewRequest = {
+  websiteId: () => props.website?._id,
+  path: () => props.path,
+  period: () => props.period,
+}
+const heatmapRead = usePageHeatmap(previewRequest)
+const heatmap = computed(() =>
+  heatmapRead.error.value ? null : heatmapRead.data.value,
 )
+const loading = computed(() => heatmapRead.pending.value)
+const failed = computed(() => !!heatmapRead.error.value && !loading.value)
 
 const points = computed(() => heatmap.value?.points ?? [])
 const maxWeight = computed(() => heatmap.value?.maxWeight ?? 0)
@@ -163,30 +164,13 @@ const overlayMode = ref<'clicks' | 'scroll'>('clicks')
 // Read with the clicks, not when its overlay opens: every sampled view
 // reports one depth, so its count is the page's sampled views the header
 // and the empty states speak of.
-const {
-  data: scrollDepth,
-  loading: loadingScroll,
-  failed: scrollFailed,
-  run: loadScrollDepth,
-} = useLatestRequest<MarketingScrollDepth>(() =>
-  props.website && props.path && !import.meta.env.SSR
-    ? api.getScrollDepth(props.website._id, props.path, props.period)
-    : null,
+const scrollRead = usePageScrollDepth(previewRequest)
+const scrollDepth = computed(() =>
+  scrollRead.error.value ? null : scrollRead.data.value,
 )
-
-watch(
-  () => [
-    props.website?._id,
-    props.path,
-    props.period?.range?.from.getTime(),
-    props.period?.range?.to.getTime(),
-    props.refreshToken,
-  ],
-  () => {
-    void loadHeatmap()
-    void loadScrollDepth()
-  },
-  { immediate: true },
+const loadingScroll = computed(() => scrollRead.pending.value)
+const scrollFailed = computed(
+  () => !!scrollRead.error.value && !loadingScroll.value,
 )
 
 const scrollViews = computed(() => scrollDepth.value?.views ?? 0)
@@ -221,8 +205,13 @@ const { confirm } = useConfirm()
 const toast = useToast()
 const resetting = ref(false)
 
+const countPageHeatmap = useHeatmapCountRead(
+  () => props.website?._id ?? '',
+  () => props.path,
+)
+
 /** Deletes the clicks, scrolls and snapshots of the page (every period),
- *  counted by the server before asking, then refetches both overlays. */
+ *  counted by the server before asking; the page's reads follow. */
 async function resetPageHeatmap() {
   const website = props.website
   if (!website) {
@@ -230,8 +219,7 @@ async function resetPageHeatmap() {
   }
   const path = props.path
   resetting.value = true
-  const counts = await api
-    .countHeatmap(website._id, path)
+  const counts = await countPageHeatmap()
     .catch(() => null)
     .finally(() => (resetting.value = false))
   await confirm({
@@ -258,8 +246,8 @@ async function resetPageHeatmap() {
             what: heatmapDataLabel(deleted, t, locale.value),
           }),
         })
-        emit('heatmap-reset')
-        await Promise.all([loadHeatmap(), loadScrollDepth(), loadSnapshot()])
+        // The preview shows the emptied page before the button comes back.
+        await refreshPageBlocks()
       } finally {
         resetting.value = false
       }
@@ -283,29 +271,26 @@ const snapshotsEnabled = computed(
 
 // Not fetched while the site has snapshots off: the option's banner is the
 // whole story then, and a leftover capture must not contradict it.
-const {
-  data: snapshotResponse,
-  settled: snapshotSettled,
-  run: loadSnapshot,
-} = useLatestRequest<MarketingPageSnapshotResponse>(() =>
-  props.website && snapshotsEnabled.value && props.path && !import.meta.env.SSR
-    ? api.getSnapshot(props.website._id, props.path, layout.value)
-    : null,
+const snapshotRead = usePageSnapshot({
+  websiteId: () => props.website?._id,
+  path: () => props.path,
+  layout,
+  enabled: snapshotsEnabled,
+})
+const isSnapshotAsked = computed(
+  () => snapshotsEnabled.value && !!props.website?._id && !!props.path,
 )
-
-watch(
-  () => [
-    props.website?._id,
-    snapshotsEnabled.value,
-    props.path,
-    layout.value,
-    props.refreshToken,
-  ],
-  () => void loadSnapshot(),
-  { immediate: true },
+/** A capture was asked and answered, or there is none to ask for. */
+const snapshotSettled = computed(
+  () =>
+    !isSnapshotAsked.value ||
+    snapshotRead.status.value === 'success' ||
+    snapshotRead.status.value === 'error',
 )
 
-const snapshot = computed(() => snapshotResponse.value?.snapshot ?? null)
+const snapshot = computed(() =>
+  snapshotRead.error.value ? null : (snapshotRead.data.value?.snapshot ?? null),
+)
 
 const backdrop = computed(() => snapshot.value?.html ?? null)
 
@@ -345,8 +330,7 @@ async function updateSnapshotOptions(
   }
   savingOptions.value = true
   try {
-    await api.updateWebsite(website._id, patch)
-    emit('website-updated')
+    emit('website-updated', await api.updateWebsite(website._id, patch))
   } catch {
     toast.add({
       color: 'error',
@@ -627,10 +611,10 @@ const activeLoading = computed(() =>
 
 function retryActive(): void {
   if (overlayMode.value === 'clicks') {
-    void loadHeatmap()
+    void heatmapRead.refresh()
     return
   }
-  void loadScrollDepth()
+  void scrollRead.refresh()
 }
 
 const truncatedState = computed(() => {
@@ -947,7 +931,7 @@ const moreItems = computed(() => [
       type: 'checkbox' as const,
       label: t('page.marketing.pages.preview.snapshots_enabled'),
       checked: snapshotsEnabled.value,
-      onUpdateChecked: (value: boolean) =>
+      onUpdateChecked: (value: boolean): void =>
         void updateSnapshotOptions({ snapshotsEnabled: value }),
     },
     {
@@ -955,7 +939,7 @@ const moreItems = computed(() => [
       label: t('page.marketing.pages.preview.mask_text'),
       checked: props.website?.snapshotMaskText === true,
       disabled: !snapshotsEnabled.value,
-      onUpdateChecked: (value: boolean) =>
+      onUpdateChecked: (value: boolean): void =>
         void updateSnapshotOptions({ snapshotMaskText: value }),
     },
   ],

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

@@ -1,15 +1,19 @@
 <script setup lang="ts">
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import { useDmsRoute, useDmsRouter, useI18n } from '#dms/frontend-module'
-import { useLatestRequest } from '../composables/useLatestRequest'
 import {
   useMarketingApi,
-  type MarketingFunnelListItem,
-  type MarketingPages,
   type MarketingPageEntry,
+  type MarketingPages,
   type MarketingPagesSort,
   type MarketingWebsite,
 } from '../composables/useMarketingApi'
+import {
+  useHeatmapCountRead,
+  usePageInventory,
+  useWebsiteFunnels,
+  useWebsites,
+} from '../composables/useMarketingReads'
 import { useMarketingContext } from '../composables/useMarketingContext'
 import { installLink } from '../composables/useMarketingRoutes'
 import { PERIOD_SCOPE } from '../constants'
@@ -55,78 +59,83 @@ const { confirm } = useConfirm()
 const websiteId = computed(() => context.selected.value?.id ?? '')
 const period = usePeriodScope(props.periodScope)
 /** The days read: a comparison change alone reads nothing again. */
-const periodDays = computed(() => {
-  const range = period.value?.range
-  return range ? `${range.from.toISOString()}|${range.to.toISOString()}` : ''
-})
+const pagesPeriod = computed(() =>
+  period.value
+    ? {
+        ...period.value,
+        comparison: 'none' as const,
+        compareRange: null,
+      }
+    : null,
+)
 
 const queryPath = () =>
   typeof route.query.path === 'string' ? route.query.path : ''
 const selectedPath = ref<string | undefined>(queryPath() || undefined)
 const search = ref('')
+/** The search the list is read with, once the box holds still. */
+const searchedTerm = ref('')
 const sort = ref<MarketingPagesSort>('views')
 
 // The full row: the context carries the id, the preview needs the snapshot options.
-const website = ref<MarketingWebsite | null>(null)
-
-async function loadWebsite(): Promise<void> {
-  const list = await api.listWebsites()
-  website.value = list.find((site) => site._id === websiteId.value) ?? null
-}
-
-const {
-  data: inventory,
-  loading,
-  settled,
-  failed,
-  run: loadPages,
-} = useLatestRequest<MarketingPages>(() =>
-  websiteId.value && !import.meta.env.SSR
-    ? api.listPages(
-        websiteId.value,
-        period.value,
-        search.value.trim(),
-        sort.value,
-      )
-    : null,
+const websitesRead = useWebsites()
+const website = computed(
+  () =>
+    websitesRead.data.value?.find((site) => site._id === websiteId.value) ??
+    null,
 )
 
-const funnels = ref<MarketingFunnelListItem[]>([])
-
-async function loadFunnels(): Promise<void> {
-  try {
-    funnels.value = (await api.listFunnels(websiteId.value)).results
-  } catch {
-    funnels.value = []
+/** A site as its update answered it, in place: the list is not read again. */
+function putWebsite(saved: MarketingWebsite): void {
+  const sites = websitesRead.data.value
+  if (sites) {
+    websitesRead.data.value = sites.map((site) =>
+      site._id === saved._id ? saved : site,
+    )
   }
 }
 
-watch(
-  [websiteId, context.refreshToken],
-  ([id], previous) => {
-    if (previous?.[0] !== undefined && id !== previous[0]) {
-      selectedPath.value = undefined
-    }
-    if (id) {
-      void loadWebsite()
-      void loadFunnels()
-    }
-  },
-  { immediate: true },
+const inventoryRead = usePageInventory({
+  websiteId,
+  period: pagesPeriod,
+  search: searchedTerm,
+  sort,
+})
+const inventory = computed(() =>
+  inventoryRead.error.value ? null : inventoryRead.data.value,
 )
+const loading = computed(() => inventoryRead.status.value === 'pending')
+/** A list is on screen (the previous one while another loads), or failed. */
+const settled = computed(
+  () =>
+    inventoryRead.data.value !== null ||
+    inventoryRead.status.value === 'success' ||
+    inventoryRead.status.value === 'error',
+)
+const failed = computed(
+  () => !!inventoryRead.error.value && inventoryRead.status.value !== 'pending',
+)
+const loadPages = (): Promise<void> => inventoryRead.refresh()
 
-watch(
-  [websiteId, periodDays, context.refreshToken, sort],
-  () => void loadPages(),
-  { immediate: true },
+const funnelsRead = useWebsiteFunnels(websiteId)
+const countSiteHeatmap = useHeatmapCountRead(websiteId)
+const funnels = computed(() =>
+  funnelsRead.error.value ? [] : (funnelsRead.data.value ?? []),
 )
 
+watch(websiteId, () => {
+  selectedPath.value = undefined
+})
+
 let searchTimer: ReturnType<typeof setTimeout> | null = null
-watch(search, () => {
+watch(search, (value) => {
   if (searchTimer) {
     clearTimeout(searchTimer)
   }
-  searchTimer = setTimeout(() => void loadPages(), SEARCH_DEBOUNCE_MS)
+  searchTimer = setTimeout(
+    () => (searchedTerm.value = value.trim()),
+    SEARCH_DEBOUNCE_MS,
+  )
 })
 onBeforeUnmount(() => searchTimer && clearTimeout(searchTimer))
 
@@ -170,13 +179,15 @@ watch(queryPath, (path) => {
 })
 
 // A first impression that shows the feature: the first page with clicks,
-// else the first page.
-watch(inventory, (data) => {
+// else the first page. In the browser: the list a server render hands over
+// is chosen from once mounted.
+function selectFirst(data: MarketingPages | null): void {
   if (!selectedPath.value && data?.pages.length) {
     const withClicks = data.pages.find((page) => page.clicks > 0)
     selectPath((withClicks ?? data.pages[0])?.path, 'replace')
   }
-})
+}
+watch(inventory, selectFirst)
 
 const previewWrapper = ref<HTMLElement | null>(null)
 
@@ -220,12 +231,13 @@ const usedIn = computed(() =>
   ),
 )
 
-const refreshToken = ref(0)
-
-// Client-only: the server renders no session, so its markup (an empty list)
-// would not match the client's and hydration would misplace the preview.
+// The preview draws in the browser only (frames, canvases): a server render
+// holds its place.
 const mounted = ref(false)
-onMounted(() => (mounted.value = true))
+onMounted(() => {
+  mounted.value = true
+  selectFirst(inventory.value)
+})
 
 const countLabel = computed(() => {
   const listed = pages.value.length
@@ -245,7 +257,7 @@ async function resetSite(): Promise<void> {
   if (!site) {
     return
   }
-  const counts = await api.countHeatmap(site._id).catch(() => null)
+  const counts = await countSiteHeatmap().catch(() => null)
   await confirm({
     title: t('page.marketing.pages.reset.site_title', { name: site.name }),
     description: t('page.marketing.pages.reset.site_description'),
@@ -270,7 +282,8 @@ async function resetSite(): Promise<void> {
           what: heatmapDataLabel(deleted, t, locale.value),
         }),
       })
-      refreshToken.value++
+      // The dialog closes once the pages show the emptied counts.
+      await refreshPageBlocks()
     },
   })
 }
@@ -323,18 +336,7 @@ const moreItems = computed(() => [
         :description="t('page.marketing.pages.tracking_off.description')"
       />
 
-      <div
-        v-if="!mounted"
-        class="grid items-start gap-4 xl:grid-cols-[22rem_minmax(0,1fr)]"
-        aria-hidden="true"
-      >
-        <USkeleton class="h-[32rem] rounded-xl" />
-        <USkeleton class="h-[32rem] rounded-xl" />
-      </div>
-      <div
-        v-else
-        class="grid items-start gap-4 xl:grid-cols-[22rem_minmax(0,1fr)]"
-      >
+      <div class="grid items-start gap-4 xl:grid-cols-[22rem_minmax(0,1fr)]">
         <section
           class="dms-card flex min-w-0 flex-col overflow-hidden p-0 xl:sticky xl:top-4"
         >
@@ -516,21 +518,25 @@ const moreItems = computed(() => [
         </section>
 
         <div
-          v-if="selectedPath && website"
+          v-if="(selectedPath && website) || (!mounted && pages.length > 0)"
           ref="previewWrapper"
           class="min-w-0 scroll-mt-4"
         >
+          <USkeleton
+            v-if="!mounted || !selectedPath || !website"
+            class="h-[32rem] rounded-xl"
+            aria-hidden="true"
+          />
           <DmsMarketingPagePreview
+            v-else
             :website="website"
             :path="selectedPath"
             :period="period"
             :sample-rate-label="sampleRateLabel"
             :tracker-enabled="trackerEnabled"
             :pageviews="selectedPage?.pageviews"
-            :refresh-token="refreshToken + context.refreshToken.value"
             :used-in="usedIn"
-            @website-updated="loadWebsite"
-            @heatmap-reset="loadPages"
+            @website-updated="putWebsite"
           />
         </div>
         <DmsEmptyState