@antelopejs/dms-marketing 0.6.0 → 0.7.0

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

@@ -91,7 +91,22 @@ function stepsKey(steps: MarketingFunnelStep[]): string {
         />
       </template>
     </DmsEmptyState>
+    <!-- The blank start comes first: the templates loading after it never
+         move it. -->
     <div class="mt-6 grid gap-3 md:grid-cols-3">
+      <button
+        type="button"
+        class="flex flex-col items-start gap-2 rounded-xl border border-dashed border-default p-4 text-left transition-colors hover:border-primary"
+        @click="startFrom(null)"
+      >
+        <DmsEyebrow :label="t('page.marketing.funnels.empty.blank')" />
+        <span class="text-sm font-semibold text-highlighted">
+          {{ t('page.marketing.funnels.empty.scratch') }}
+        </span>
+        <span class="text-xs text-muted">
+          {{ t('page.marketing.funnels.empty.scratch_description') }}
+        </span>
+      </button>
       <template v-if="templates === null && !waiting">
         <USkeleton v-for="index in 2" :key="index" class="h-32 rounded-xl" />
       </template>
@@ -132,19 +147,6 @@ function stepsKey(steps: MarketingFunnelStep[]): string {
           }}
         </span>
       </button>
-      <button
-        type="button"
-        class="flex flex-col items-start gap-2 rounded-xl border border-dashed border-default p-4 text-left transition-colors hover:border-primary"
-        @click="startFrom(null)"
-      >
-        <DmsEyebrow :label="t('page.marketing.funnels.empty.blank')" />
-        <span class="text-sm font-semibold text-highlighted">
-          {{ t('page.marketing.funnels.empty.scratch') }}
-        </span>
-        <span class="text-xs text-muted">
-          {{ t('page.marketing.funnels.empty.scratch_description') }}
-        </span>
-      </button>
     </div>
   </section>
 </template>

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

@@ -371,7 +371,7 @@ const stepTwoState = computed(() =>
               <span class="font-mono">{{ website.domain }}</span>
               {{ t('page.marketing.install.and_subdomains') }}
               <DmsAutoLink
-                :to="websitesLink()"
+                :to="websitesLink(website.id)"
                 class="text-primary hover:underline"
               >
                 {{ t('page.marketing.common.edit') }}

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

@@ -16,12 +16,13 @@ import {
   usePageSnapshot,
   type PagePreviewRequest,
 } from '../composables/useMarketingReads'
-import { funnelLink, settingsLink } from '../composables/useMarketingRoutes'
-import { formatNumber, formatShortDate } from '../utils/format'
 import {
-  heatmapDataLabel,
-  heatmapResetImpact,
-} from '../utils/heatmap'
+  funnelLink,
+  settingsLink,
+  websitesLink,
+} from '../composables/useMarketingRoutes'
+import { formatNumber, formatShortDate } from '../utils/format'
+import { heatmapDataLabel, heatmapResetImpact } from '../utils/heatmap'
 import { heatLegendGradient } from '../utils/heatmapPalette'
 import {
   DEFAULT_RENDER_HEIGHT,
@@ -32,7 +33,13 @@ import {
   type AnchorBox,
   type AnchorRequest,
 } from '../composables/useSnapshotFrame'
+import {
+  confirmSnapshotChange,
+  snapshotOptionItems,
+} from '../utils/snapshot-options'
 import { rewriteViewportUnits } from '../utils/snapshotViewportUnits'
+import { anchorDrift } from '../utils/anchor-drift'
+import { dismissDrift, driftDismissed } from '../utils/drift-dismissals'
 
 /**
  * Click and scroll-depth overlays of one tracked page, over a snapshot of
@@ -82,8 +89,25 @@ const props = defineProps<{
   pageviews?: number
   /** Funnels with a page step on this path. */
   usedIn?: MarketingFunnelListItem[]
+  /**
+   * Height the card fills, toolbar to bottom, the snapshot scrolling inside
+   * it whatever its length (see PagesExplorer). Null or absent: the card
+   * grows with the snapshot, as when it is stacked under the list.
+   */
+  height?: number | null
+  /**
+   * Another workspace's dashboard, or `all` (see PagesExplorer): the page is
+   * read there, read-only — no reset, no snapshot option — and its capture
+   * comes masked from the backend. Absent or empty: the website's own.
+   */
+  workspace?: string
+  /** Whether any site of that scope keeps snapshots. */
+  workspaceSnapshots?: boolean
 }>()
 
+/** Read past the viewer's workspace (see `workspace`). */
+const foreign = computed(() => !!props.workspace)
+
 /** The site's snapshot options were saved here, as the backend answered
  * them; the parent owns the row. */
 const emit = defineEmits<{
@@ -129,7 +153,8 @@ const PROBE_VIEWPORT_HEIGHT = 900
 const PANE_HEIGHT = 620
 /** Overflow beyond the chosen layout width worth telling the operator about. */
 const OVERFLOW_TOLERANCE = 1.05
-const SNAPSHOT_BYTE_CAP = 1024 * 1024
+/** The upload cap of a backend that does not say its own. */
+const DEFAULT_SNAPSHOT_BYTE_CAP = 1024 * 1024
 const LIGHT_CANVAS = '#ffffff'
 const DARK_CANVAS = '#111111'
 
@@ -145,6 +170,7 @@ const previewRequest: PagePreviewRequest = {
   websiteId: () => props.website?._id,
   path: () => props.path,
   period: () => props.period,
+  workspace: () => props.workspace,
 }
 const heatmapRead = usePageHeatmap(previewRequest)
 const heatmap = computed(() =>
@@ -265,8 +291,10 @@ const layout = computed<MarketingSnapshotLayout>(
       ?.layout ?? 'desktop',
 )
 
-const snapshotsEnabled = computed(
-  () => props.website?.snapshotsEnabled ?? false,
+const snapshotsEnabled = computed(() =>
+  foreign.value
+    ? props.workspaceSnapshots === true
+    : (props.website?.snapshotsEnabled ?? false),
 )
 
 // Not fetched while the site has snapshots off: the option's banner is the
@@ -277,6 +305,7 @@ const snapshotRead = usePageSnapshot({
   layout,
   enabled: snapshotsEnabled,
   maskText: () => props.website?.snapshotMaskText === true,
+  workspace: () => props.workspace,
 })
 const isSnapshotAsked = computed(
   () => snapshotsEnabled.value && !!props.website?._id && !!props.path,
@@ -322,11 +351,37 @@ function mebibytes(bytes: number): string {
 
 const savingOptions = ref(false)
 
+const countSiteHeatmap = useHeatmapCountRead(() => props.website?._id ?? '')
+
+/**
+ * Whether the change may go ahead: it deletes the site's snapshots and
+ * changes what later captures keep, so it is asked first — with the count
+ * when there are some (see asksBeforeSnapshotChange). Declining leaves the
+ * website as it is, and the menu's checkbox with it.
+ */
+function confirmSnapshotDiscard(
+  website: MarketingWebsite,
+  patch: MarketingWebsitePatch,
+): Promise<boolean> {
+  return confirmSnapshotChange(website, patch, {
+    count: async () => {
+      savingOptions.value = true
+      try {
+        return (await countSiteHeatmap()).snapshots
+      } finally {
+        savingOptions.value = false
+      }
+    },
+    confirm,
+    t,
+  })
+}
+
 async function updateSnapshotOptions(
   patch: MarketingWebsitePatch,
 ): Promise<void> {
   const website = props.website
-  if (!website) {
+  if (!website || !(await confirmSnapshotDiscard(website, patch))) {
     return
   }
   savingOptions.value = true
@@ -345,7 +400,7 @@ async function updateSnapshotOptions(
 // --- Frame geometry ---------------------------------------------------------
 
 const frame = ref<HTMLIFrameElement | null>(null)
-const { measuredWidth, measuredHeight, tier, measureAnchors } =
+const { measuredWidth, measuredHeight, tier, measureAnchors, missingAnchors } =
   useSnapshotFrame(frame)
 
 const frameKey = computed(() =>
@@ -417,6 +472,9 @@ const overlayWidth = computed(() =>
  * fraction, never a blank one.
  */
 const anchorBoxes = ref(new Map<string, AnchorBox>())
+/** Keys of the anchors the snapshot has no element for; null until the
+ *  frame has been measured. */
+const missingAnchorKeys = ref<Set<string> | null>(null)
 
 function anchorKey(anchor: AnchorRequest): string {
   return `${anchor.selector}\0${anchor.nth}`
@@ -467,6 +525,7 @@ async function refreshAnchorBoxes(): Promise<void> {
     if (anchorBoxes.value.size > 0) {
       anchorBoxes.value = new Map()
     }
+    missingAnchorKeys.value = null
     return
   }
   await nextTick()
@@ -479,8 +538,23 @@ async function refreshAnchorBoxes(): Promise<void> {
     resolved.set(anchorKey(box), box)
   }
   anchorBoxes.value = resolved
+  missingAnchorKeys.value = new Set(
+    missingAnchors(requestedAnchors.value).map(anchorKey),
+  )
 }
 
+/**
+ * Clicks aiming at elements this snapshot does not have: drawn at their
+ * document fraction, and past a threshold a sign the page changed since it
+ * was captured (see anchorDrift).
+ */
+const drift = computed(() => {
+  const missing = missingAnchorKeys.value
+  return missing
+    ? anchorDrift(points.value, (anchor) => missing.has(anchorKey(anchor)))
+    : null
+})
+
 watch(
   [requestedAnchors, tier, renderHeight, overlayWidth],
   () => void refreshAnchorBoxes(),
@@ -547,20 +621,26 @@ const scrolledHeight = computed(() =>
   Math.round(renderHeight.value * scale.value),
 )
 
+const filled = computed(() => !!props.height)
+
 /**
- * The pane grows with the page, up to the window's height: a short capture
- * leaves no empty band below it, and a long one scrolls inside a pane that
- * still fits the screen. The border is counted, or a 2px scroll would remain.
+ * Given a height, the pane takes what the card leaves it, the same for
+ * every snapshot: a long page scrolls inside it, a short one ends on the
+ * end-of-page band. Without one, the pane grows with the page up to the
+ * window's height. The border is counted, or a 2px scroll would remain.
  */
-const paneStyle = computed(() => ({
-  height: `${scrolledHeight.value + 2}px`,
-  maxHeight: 'calc(100dvh - 8rem)',
-  minHeight: '12rem',
-}))
+const paneStyle = computed(() =>
+  filled.value
+    ? { height: '100%' }
+    : {
+        height: `${scrolledHeight.value + 2}px`,
+        maxHeight: 'calc(100dvh - 8rem)',
+        minHeight: '12rem',
+      },
+)
 
 // --- Emptiness, explained ---------------------------------------------------
 
-
 /** Silence has shared causes (collection off, no view sampled) before the
  *  per-overlay one; both overlays explain themselves through this. */
 function captureEmptyReason(fallbackKey: string): string {
@@ -668,10 +748,40 @@ interface StatusStrip {
   neutral?: boolean
   icon: string
   title: string
-  description: string
+  description?: string
+  /** The explanation, behind an info button instead of under the title: a
+   * strip that must stay one line above the snapshot. */
+  details?: string
   action?: StripAction
+  /** A second, quieter action: the setting behind the strip, where it lives. */
+  secondary?: StripAction
+  /** Closes the strip; the next one that applies, if any, takes its place. */
+  dismiss?: () => void
 }
 
+/** Where the site's snapshot switch lives: the Websites page's settings,
+ * scrolled to it. The menu's toggles are only a shortcut to it. */
+const snapshotSettingsLink = computed(() =>
+  props.website && !foreign.value
+    ? websitesLink(props.website._id, 'snapshots')
+    : '',
+)
+
+function snapshotSettingsAction(): StripAction | undefined {
+  return snapshotSettingsLink.value
+    ? {
+        label: t('page.marketing.pages.preview.snapshot_settings'),
+        to: snapshotSettingsLink.value,
+      }
+    : undefined
+}
+
+/** The drift strip was closed on this page this session (see
+ * drift-dismissals). */
+const driftDismissedHere = computed(
+  () => !!props.website && driftDismissed(props.website._id, props.path),
+)
+
 /**
  * Highest priority first: one strip says what needs attention, instead of
  * every applicable alert stacked above the page. The numbers in the header
@@ -697,10 +807,14 @@ const statusStrip = computed<StatusStrip | null>(() => {
           icon: 'i-ph-camera-slash',
           title: t('page.marketing.pages.preview.snapshots_off'),
           description: t('page.marketing.pages.preview.snapshots_off_hint'),
-          action: {
-            label: t('page.marketing.pages.preview.enable_snapshots'),
-            run: () => void updateSnapshotOptions({ snapshotsEnabled: true }),
-          },
+          action: foreign.value
+            ? undefined
+            : {
+                label: t('page.marketing.pages.preview.enable_snapshots'),
+                run: () =>
+                  void updateSnapshotOptions({ snapshotsEnabled: true }),
+              },
+          secondary: snapshotSettingsAction(),
         }
       : null,
     noSnapshotYet.value
@@ -714,6 +828,7 @@ const statusStrip = computed<StatusStrip | null>(() => {
               : t('page.marketing.pages.preview.no_snapshot_hint_rate', {
                   rate: props.sampleRateLabel,
                 }),
+          secondary: snapshotSettingsAction(),
         }
       : null,
     snapshot.value && tooHeavy.value
@@ -723,8 +838,44 @@ const statusStrip = computed<StatusStrip | null>(() => {
           title: t('page.marketing.pages.preview.too_heavy'),
           description: t('page.marketing.pages.preview.too_heavy_hint', {
             size: mebibytes(snapshot.value.bytes),
-            limit: mebibytes(SNAPSHOT_BYTE_CAP),
+            limit: mebibytes(
+              snapshot.value.maxBytes ?? DEFAULT_SNAPSHOT_BYTE_CAP,
+            ),
+          }),
+          secondary: snapshotSettingsAction(),
+        }
+      : null,
+    overlayMode.value === 'clicks' &&
+    drift.value?.significant &&
+    !driftDismissedHere.value
+      ? {
+          tone: 'warning',
+          icon: 'i-ph-git-diff',
+          title: t('page.marketing.pages.preview.drift', {
+            share: String(
+              formatPercentage(drift.value.share, locale.value, {
+                maximumFractionDigits: 0,
+              }),
+            ),
+          }),
+          // One line: the share and the way out. Why, and what the reset
+          // does, wait behind the info button.
+          details: t('page.marketing.pages.preview.drift_hint', {
+            date: snapshot.value
+              ? formatShortDate(snapshot.value.capturedAt, locale.value)
+              : '',
           }),
+          action: foreign.value
+            ? undefined
+            : {
+                label: t('page.marketing.pages.reset.page_button'),
+                run: () => void resetPageHeatmap(),
+              },
+          dismiss: () => {
+            if (props.website) {
+              dismissDrift(props.website._id, props.path)
+            }
+          },
         }
       : null,
     truncatedState.value
@@ -788,13 +939,23 @@ const statusLine = computed(() => {
   })
 })
 
-const maskLine = computed(() =>
-  t(
+/** Where the snapshot was taken: origin and path, as stored. */
+const capturedUrl = computed(() =>
+  snapshot.value
+    ? (snapshot.value.url ?? `${snapshot.value.origin}${props.path}`)
+    : '',
+)
+
+const maskLine = computed(() => {
+  if (snapshot.value?.masked || foreign.value) {
+    return t('page.marketing.pages.preview.workspace_masked')
+  }
+  return t(
     props.website?.snapshotMaskText
       ? 'page.marketing.pages.preview.all_masked'
       : 'page.marketing.pages.preview.fields_masked',
-  ),
-)
+  )
+})
 
 // --- Most clicked -----------------------------------------------------------
 
@@ -926,45 +1087,53 @@ watch(
   { flush: 'post' },
 )
 
-const moreItems = computed(() => [
+// Another workspace's page is read-only: its options and reset are its own.
+const moreItems = computed(() =>
   [
-    {
-      type: 'checkbox' as const,
-      label: t('page.marketing.pages.preview.snapshots_enabled'),
-      checked: snapshotsEnabled.value,
-      onUpdateChecked: (value: boolean): void =>
-        void updateSnapshotOptions({ snapshotsEnabled: value }),
-    },
-    {
-      type: 'checkbox' as const,
-      label: t('page.marketing.pages.preview.mask_text'),
-      checked: props.website?.snapshotMaskText === true,
-      disabled: !snapshotsEnabled.value,
-      onUpdateChecked: (value: boolean): void =>
-        void updateSnapshotOptions({ snapshotMaskText: value }),
-    },
-  ],
-  ...(externalUrl.value
-    ? [
-        [
-          {
-            label: t('page.marketing.pages.preview.open_in_tab'),
-            icon: 'i-ph-arrow-square-out',
-            to: externalUrl.value,
-            target: '_blank',
-          },
-        ],
-      ]
-    : []),
-  [
-    {
-      label: t('page.marketing.pages.reset.page_button'),
-      icon: 'i-ph-eraser',
-      color: 'error' as const,
-      onSelect: () => void resetPageHeatmap(),
-    },
-  ],
-])
+    [
+      ...(foreign.value
+        ? []
+        : snapshotOptionItems(
+            props.website,
+            (patch) => void updateSnapshotOptions(patch),
+            t,
+          )),
+      ...(snapshotSettingsLink.value
+        ? [
+            {
+              label: t('page.marketing.pages.preview.snapshot_settings'),
+              icon: 'i-ph-gear-six',
+              to: snapshotSettingsLink.value,
+            },
+          ]
+        : []),
+    ],
+    ...(externalUrl.value
+      ? [
+          [
+            {
+              label: t('page.marketing.pages.preview.open_in_tab'),
+              icon: 'i-ph-arrow-square-out',
+              to: externalUrl.value,
+              target: '_blank',
+            },
+          ],
+        ]
+      : []),
+    ...(foreign.value
+      ? []
+      : [
+          [
+            {
+              label: t('page.marketing.pages.reset.page_button'),
+              icon: 'i-ph-eraser',
+              color: 'error' as const,
+              onSelect: () => void resetPageHeatmap(),
+            },
+          ],
+        ]),
+  ].filter((group) => group.length > 0),
+)
 
 // --- Surface ----------------------------------------------------------------
 
@@ -1018,7 +1187,10 @@ const surfaceEmpty = computed(() => {
 </script>
 
 <template>
-  <section class="dms-card flex min-w-0 flex-col overflow-hidden p-0">
+  <section
+    class="dms-card flex min-w-0 flex-col overflow-hidden p-0"
+    :style="filled ? { height: `${props.height}px` } : undefined"
+  >
     <!-- Toolbar -->
     <header
       class="flex flex-wrap items-center justify-between gap-3 border-b border-default px-4 py-3"
@@ -1078,7 +1250,11 @@ const surfaceEmpty = computed(() => {
             :aria-label="t('page.marketing.pages.preview.layout')"
           />
         </span>
-        <UDropdownMenu :items="moreItems" :content="{ align: 'end' }">
+        <UDropdownMenu
+          v-if="moreItems.length > 0"
+          :items="moreItems"
+          :content="{ align: 'end' }"
+        >
           <UButton
             icon="i-ph-dots-three"
             size="xs"
@@ -1099,9 +1275,29 @@ const surfaceEmpty = computed(() => {
         :icon="statusStrip.icon"
         :title="statusStrip.title"
         :description="statusStrip.description"
+        :dismissible="!!statusStrip.dismiss"
+        @dismiss="statusStrip.dismiss?.()"
       >
-        <template v-if="statusStrip.action" #actions>
+        <template v-if="statusStrip.details" #description>
+          <UPopover :content="{ align: 'start' }">
+            <UButton
+              icon="i-ph-info"
+              size="xs"
+              color="neutral"
+              variant="ghost"
+              class="-my-1 align-middle"
+              :aria-label="t('page.marketing.pages.preview.strip_details')"
+            />
+            <template #content>
+              <p class="max-w-sm p-3 text-xs leading-relaxed text-muted">
+                {{ statusStrip.details }}
+              </p>
+            </template>
+          </UPopover>
+        </template>
+        <template v-if="statusStrip.action || statusStrip.secondary" #actions>
           <UButton
+            v-if="statusStrip.action"
             size="xs"
             color="neutral"
             variant="outline"
@@ -1110,6 +1306,15 @@ const surfaceEmpty = computed(() => {
             :to="statusStrip.action.to"
             @click="statusStrip.action.run?.()"
           />
+          <UButton
+            v-if="statusStrip.secondary"
+            size="xs"
+            color="neutral"
+            variant="ghost"
+            :label="statusStrip.secondary.label"
+            :to="statusStrip.secondary.to"
+            @click="statusStrip.secondary.run?.()"
+          />
         </template>
       </DmsBanner>
     </div>
@@ -1121,23 +1326,63 @@ const surfaceEmpty = computed(() => {
         <UIcon name="i-ph-camera" class="size-3.5 text-success" />
         {{ statusLine }}
       </span>
+      <span
+        class="min-w-0 truncate font-mono text-dimmed"
+        :title="t('page.marketing.pages.preview.captured_from_hint')"
+      >
+        {{
+          t('page.marketing.pages.preview.captured_from', { url: capturedUrl })
+        }}
+      </span>
       <span class="text-dimmed">· {{ maskLine }}</span>
+      <UButton
+        v-if="snapshotSettingsLink"
+        :to="snapshotSettingsLink"
+        size="xs"
+        color="neutral"
+        variant="link"
+        icon="i-ph-gear-six"
+        class="ms-auto"
+        :label="t('page.marketing.pages.preview.snapshot_settings')"
+      />
+    </p>
+    <!-- The status line's place while the capture is read, at its height (a
+         text-xs line): arriving in a free row, it pushed the pane down. -->
+    <p
+      v-else-if="!snapshotSettled"
+      class="flex items-center border-b border-default px-4 py-2"
+      aria-hidden="true"
+    >
+      <USkeleton class="h-4 w-72 max-w-full" />
     </p>
 
-    <div class="grid min-h-0 xl:grid-cols-[minmax(0,1fr)_15rem]">
-      <div class="min-w-0 p-3">
+    <div
+      class="grid min-h-0 xl:grid-cols-[minmax(0,1fr)_15rem]"
+      :class="filled ? 'flex-1 xl:grid-rows-[minmax(0,1fr)]' : ''"
+    >
+      <div class="flex min-h-0 min-w-0 flex-col p-3">
         <USkeleton
           v-if="surface === 'loading'"
           class="w-full rounded-lg"
-          :style="{ height: `${PANE_HEIGHT}px` }"
+          :class="filled ? 'min-h-0 flex-1' : ''"
+          :style="filled ? undefined : { height: `${PANE_HEIGHT}px` }"
         />
 
         <!-- Kept mounted across refetches: tearing it down would re-render the
              snapshot — and re-measure it — on every period change. -->
-        <div v-else-if="surface === 'frame'" class="relative">
+        <div
+          v-else-if="surface === 'frame'"
+          class="relative"
+          :class="filled ? 'min-h-0 flex-1' : ''"
+        >
           <div
             ref="container"
             class="overflow-x-hidden overflow-y-scroll rounded-lg border border-default bg-elevated"
+            :class="
+              filled
+                ? 'bg-[repeating-linear-gradient(135deg,transparent_0_8px,var(--ui-border)_8px_9px)]'
+                : ''
+            "
             :style="paneStyle"
           >
             <!-- A layout narrower than the pane keeps its width, centred. -->
@@ -1220,6 +1465,16 @@ const surfaceEmpty = computed(() => {
                 :fold-ratio="scrollFoldRatio"
               />
             </div>
+            <!-- Where the captured page stops: whatever of the pane is left
+                 below is not page, and must not read as a blank part of it. -->
+            <p
+              v-if="filled"
+              class="mx-auto flex items-center justify-center gap-1.5 border-t border-dashed border-accented py-2 text-[11px] text-dimmed"
+              :style="{ width: `${surfaceWidth}px` }"
+            >
+              <UIcon name="i-ph-arrow-line-down" class="size-3.5" />
+              {{ t('page.marketing.pages.preview.end_of_page') }}
+            </p>
           </div>
 
           <!-- Outside the scrollport on purpose: inside, it is laid out at the
@@ -1261,6 +1516,7 @@ const surfaceEmpty = computed(() => {
 
       <aside
         class="flex flex-col gap-4 border-t border-default p-4 xl:border-t-0 xl:border-l"
+        :class="filled ? 'min-h-0 overflow-y-auto' : ''"
       >
         <template v-if="overlayMode === 'clicks'">
           <div class="flex flex-col gap-1.5">