@antelopejs/dms-marketing 0.6.0 → 0.7.0

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

@@ -1,32 +1,23 @@
 <script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, provide, ref, watch } from 'vue'
+import { provide, watch } from 'vue'
 import { useDmsRoute, useDmsRouter, useI18n } from '#dms/frontend-module'
-import {
-  MARKETING_CONTEXT_KEY,
-  type ContextWebsite,
-} from '../composables/useMarketingContext'
-import { useMarketingApi } from '../composables/useMarketingApi'
-import { useMarketingContextRead } from '../composables/useMarketingReads'
-import { useMarketingNow } from '../composables/useMarketingNow'
+import { MARKETING_CONTEXT_KEY } from '../composables/useMarketingContext'
+import { useContextWebsite } from '../composables/useContextWebsite'
 import { installLink } from '../composables/useMarketingRoutes'
-import { formatRelativeTime, initials, utcDayStart } from '../utils/format'
-import { MAX_PERIOD_DAYS, MS_PER_DAY, PERIOD_SCOPE } from '../constants'
 
 /**
- * The context bar of every analytics page and the gate in front of its blocks.
+ * The gate in front of the blocks of every analytics page. The page's
+ * toolbar (`marketingToolbar()`, declared by the page) picks the website and
+ * the period; this gate renders the blocks once the URL names the website.
  *
  * The page URL is the context: a reload, a copied link or Back opens on what
  * it names, and each tab keeps its own. The period is the DMS
- * `PeriodSelector` in the bar, publishing under `periodScope`, the scope every
- * block of the page binds to: it keeps the period in the URL
- * (`?<scope>.period=…&<scope>.compare=…`, `<scope>.from`/`.to` for a custom
- * range) and the user's last choice. The website is this bar's own
- * (`?website=`): the blocks read it through a `{{query.website}}` token, so a
- * switch reads them again.
- *
- * What the URL leaves out comes from the reader's last explicit pick: the
- * selector's remembered period and the website saved server-side. Only a pick
- * in the bar writes the website, so opening a link never moves another tab.
+ * `PeriodSelector` of the toolbar, publishing under the scope every block of
+ * the page binds to. The website is the module's own (`?website=`): the
+ * blocks read it through a `{{query.website}}` token, so a switch reads them
+ * again. What the URL leaves out comes from the reader's last explicit pick:
+ * the website saved server-side. Only a pick writes the website, so opening a
+ * link never moves another tab.
  *
  * Its children render once the URL names one of the tenant's websites; with
  * no website at all the first-run hero takes their place, and with
@@ -35,152 +26,49 @@ import { MAX_PERIOD_DAYS, MS_PER_DAY, PERIOD_SCOPE } from '../constants'
  * URL naming no website (or one the tenant does not have) is redirected to
  * the one saved, and the page renders on it.
  */
-const props = withDefaults(
-  defineProps<{
-    periodScope?: string
-    waitingGuide?: boolean
-    componentId?: string
-    pageId?: string
-  }>(),
-  {
-    periodScope: PERIOD_SCOPE,
-    waitingGuide: false,
-    componentId: undefined,
-    pageId: undefined,
-  },
-)
-
-const PRESETS = [
-  'today',
-  'last-7-days',
-  'last-30-days',
-  'last-90-days',
-  'custom',
-]
-const COMPARISONS = ['previous-period', 'previous-year', 'none']
-const CLOCK_TICK_MS = 15_000
-/**
- * How often the blocks of a period reaching today and the websites' last
- * events are read again (the pages' `live` option caps the blocks alike).
- */
-const LIVE_REFRESH_MS = 60_000
-/** A website is live while its last event is this recent. */
-const LIVE_WINDOW_MS = 30 * 60 * 1000
+// The gate comes first under the page toolbar. The DMS page stack sets its
+// items 24px apart (space-y-6); `-mt-2` keeps the 16px the analytics pages
+// had when the bar was drawn in this gate (gap-4).
+const props = withDefaults(defineProps<{ waitingGuide?: boolean }>(), {
+  waitingGuide: false,
+})
 
-const { t, locale } = useI18n()
-const api = useMarketingApi()
-const toast = useToast()
+const { t } = useI18n()
 const route = useDmsRoute()
 const router = useDmsRouter()
-
-const presetLabels = computed(() =>
-  Object.fromEntries(
-    PRESETS.map((preset) => [
-      preset,
-      t(`page.marketing.context.presets.${preset}`),
-    ]),
-  ),
-)
-
-const comparisonLabels = computed(() =>
-  Object.fromEntries(
-    COMPARISONS.map((comparison) => [
-      comparison,
-      t(`page.marketing.context.comparisons.${comparison}`),
-    ]),
-  ),
-)
-
-// The minute's activity of every website: read on the bar's own clock.
-const contextRead = useMarketingContextRead({
-  refreshInterval: LIVE_REFRESH_MS,
-})
-const context = contextRead.data
-/**
- * The context could not be read, and none is shown: a failed re-read (the
- * minute's activity, a retry) keeps the bar as it is.
- */
-const failed = computed(
-  () =>
-    !!contextRead.error.value &&
-    contextRead.status.value !== 'pending' &&
-    !context.value,
-)
-const switching = ref(false)
-
-const websites = computed(() => context.value?.websites ?? [])
-/** The URL's website, while it is one of the tenant's. */
-const linkedId = computed(() => {
-  const id = route.query.website
-  return typeof id === 'string' && websites.value.some((site) => site.id === id)
-    ? id
-    : null
-})
-const selectedId = computed(
-  () => linkedId.value ?? context.value?.selectedId ?? null,
-)
-const selected = computed<ContextWebsite | null>(
-  () => websites.value.find((site) => site.id === selectedId.value) ?? null,
-)
-
-/** The websites and their last events again; a failure keeps the bar as is. */
-const reload = (): Promise<void> => contextRead.refresh()
-
-async function select(id: string): Promise<void> {
-  if (id === selectedId.value) {
-    return
-  }
-  switching.value = true
-  try {
-    // Saved first, as the website of the pages opened without one; the bar
-    // and the blocks follow the URL once it names it. A pick is a history
-    // entry, so Back takes it back.
-    context.value = await api.selectContextWebsite(id)
-    await router.push({ query: { ...route.query, website: id } })
-  } catch {
-    toast.add({
-      color: 'error',
-      title: t('page.marketing.context.switch_error'),
-    })
-    await reload()
-  } finally {
-    switching.value = false
-  }
-}
+const {
+  context,
+  failed,
+  websites,
+  linkedId,
+  selectedId,
+  selected,
+  select,
+  reload,
+  ready,
+} = useContextWebsite()
 
 // The URL names no website, or one the tenant does not have: fill in the
 // saved one, without a history entry (a server render redirects to it).
 // Watched with the query too, so a block rewriting the URL for its own state
 // (the heatmap path) keeps it. Set up once the context is read.
-await contextRead
-watch(
-  [selectedId, () => route.query],
-  ([id]) => {
-    if (id && route.query.website !== id) {
-      void router.replace({ query: { ...route.query, website: id } })
-    }
-  },
-  { immediate: true },
-)
-
-// --- Period --------------------------------------------------------------------
-
-const period = usePeriodScope(props.periodScope)
-
-// Read once the bar shows the selector: the scope registers with it, and a
-// read before has the DMS warn about a missing scope.
-const range = computed(() => (selected.value ? period.value?.range : null))
-
-/** A custom range longer than the routes read: only its last days are shown. */
-const cutHint = computed(() => {
-  if (!range.value) {
-    return ''
+await ready
+function linkSelected(id: string | null): Promise<unknown> | undefined {
+  if (id && route.query.website !== id) {
+    return router.replace({ query: { ...route.query, website: id } })
   }
-  const { from, to } = range.value
-  const days = Math.round((to.getTime() - from.getTime()) / MS_PER_DAY)
-  return days > MAX_PERIOD_DAYS
-    ? t('page.marketing.context.range_cut', { days: MAX_PERIOD_DAYS })
-    : ''
+}
+// A navigation in the browser waits for the URL to name the website: the
+// page then opens on its blocks, not on the gate's placeholder first. The
+// blocks then set up while the page's suspense is still pending, so one that
+// holds the navigation for its data (a fetched banner) is drawn with the page.
+// Vite's SSR flag: the DMS builds with Vite alone, where Nuxt's client flag
+// is undefined (see tests/build-flags.test.ts).
+if (!import.meta.env.SSR) {
+  await linkSelected(selectedId.value)
+}
+watch([selectedId, () => route.query], ([id]) => void linkSelected(id), {
+  immediate: true,
 })
 
 provide(MARKETING_CONTEXT_KEY, {
@@ -189,226 +77,10 @@ provide(MARKETING_CONTEXT_KEY, {
   select,
   reload,
 })
-
-// --- Clock -------------------------------------------------------------------
-// A period reaching today follows the clock: its blocks read again every
-// minute, through the page's live gate. The selector itself moves a day
-// preset on at midnight.
-
-const now = useMarketingNow(CLOCK_TICK_MS)
-
-/** The period covers the present: its counts are still moving. */
-const reachesToday = computed(
-  () => !!range.value && range.value.to.getTime() >= now.value,
-)
-
-/** Refresh: every block reads again, and the bar. */
-function refresh(): void {
-  refreshPageBlocks()
-  void reload()
-}
-
-/** A period reaching today: its blocks read again, through the live gate. */
-function liveRefresh(): void {
-  if (reachesToday.value && linkedId.value) {
-    refreshLivePageBlocks()
-  }
-}
-
-let live: ReturnType<typeof setInterval> | null = null
-onMounted(() => {
-  live = setInterval(liveRefresh, LIVE_REFRESH_MS)
-})
-onBeforeUnmount(() => {
-  if (live) {
-    clearInterval(live)
-  }
-})
-
-// --- Bar ---------------------------------------------------------------------
-
-/** `live` only while events are recent; a quiet site is `idle`. */
-type DisplayState = ContextWebsite['state'] | 'idle'
-
-const STATE_TONES: Record<DisplayState, string> = {
-  live: 'bg-success',
-  idle: 'bg-(--ui-text-muted)',
-  imported: 'bg-info',
-  waiting: 'bg-warning',
-  paused: 'bg-(--ui-text-dimmed)',
-}
-
-function displayState(site: ContextWebsite): DisplayState {
-  if (
-    site.state === 'live' &&
-    (site.lastActivityAt === null ||
-      now.value - site.lastActivityAt > LIVE_WINDOW_MS)
-  ) {
-    return 'idle'
-  }
-  return site.state
-}
-
-function stateLine(site: ContextWebsite): string {
-  const state = displayState(site)
-  if (
-    (state === 'live' || state === 'idle' || state === 'imported') &&
-    site.lastActivityAt
-  ) {
-    return t(`page.marketing.context.${state}`, {
-      ago: formatRelativeTime(site.lastActivityAt, now.value, locale.value),
-    })
-  }
-  return t(`page.marketing.context.state.${site.state}`)
-}
-
-const websiteItems = computed(() => [
-  websites.value.map((site) => ({
-    label: site.name,
-    description: site.domain,
-    type: 'checkbox' as const,
-    checked: site.id === selectedId.value,
-    slot: 'website' as const,
-    site,
-    onSelect: () => void select(site.id),
-  })),
-  [
-    {
-      label: t('page.marketing.context.add_website'),
-      icon: 'i-ph-plus',
-      to: installLink(),
-    },
-  ],
-])
-
-/**
- * The statistics are kept per UTC day: where the reader's midnight is not
- * UTC's, the bar says when their days really start.
- */
-const utcHint = computed(() => {
-  // The reader's zone: the browser's, which a server render reads from its
-  // cookie.
-  const time = utcDayStart(now.value, locale.value, readerTimeZone())
-  return time ? t('page.marketing.context.utc_days', { time }) : ''
-})
 </script>
 
 <template>
-  <div class="flex flex-col gap-4">
-    <div
-      class="dms-card flex flex-wrap items-center gap-x-4 gap-y-2 px-3 py-2"
-      role="toolbar"
-      :aria-label="t('page.marketing.context.label')"
-    >
-      <USkeleton v-if="!context && !failed" class="h-7 w-72" />
-      <template v-else-if="selected">
-        <UDropdownMenu :items="websiteItems" :content="{ align: 'start' }">
-          <UButton
-            color="neutral"
-            variant="outline"
-            size="sm"
-            trailing-icon="i-ph-caret-up-down"
-            :loading="switching"
-            :aria-label="t('page.marketing.context.switch_website')"
-          >
-            <span
-              class="grid size-5 place-items-center rounded bg-primary/15 font-mono text-[10px] font-semibold text-(--ui-color-primary-800) dark:text-primary"
-            >
-              {{ initials(selected.name) }}
-            </span>
-            <span class="font-semibold">{{ selected.name }}</span>
-          </UButton>
-          <template #website="{ item }">
-            <span
-              class="grid size-6 shrink-0 place-items-center rounded bg-primary/15 font-mono text-[10px] font-semibold text-(--ui-color-primary-800) dark:text-primary"
-            >
-              {{ initials(item.site.name) }}
-            </span>
-            <span class="min-w-0 flex-1 text-left">
-              <span class="block truncate text-sm font-medium text-highlighted">
-                {{ item.site.name }}
-              </span>
-              <span
-                class="flex min-w-0 items-center gap-1.5 text-xs text-dimmed"
-              >
-                <span
-                  class="size-1.5 shrink-0 rounded-full"
-                  :class="STATE_TONES[displayState(item.site)]"
-                  aria-hidden="true"
-                />
-                <span class="truncate font-mono">{{ item.site.domain }}</span>
-                <span class="shrink-0">· {{ stateLine(item.site) }}</span>
-              </span>
-            </span>
-            <UIcon
-              v-if="item.checked"
-              name="i-ph-check"
-              class="size-4 shrink-0 text-primary"
-            />
-          </template>
-        </UDropdownMenu>
-
-        <span class="flex items-center gap-2 font-mono text-xs text-muted">
-          <span
-            class="size-2 rounded-full"
-            :class="STATE_TONES[displayState(selected)]"
-            aria-hidden="true"
-          />
-          {{ stateLine(selected) }}
-        </span>
-
-        <span class="hidden h-5 w-px bg-(--ui-border) md:block" />
-
-        <div class="flex flex-wrap items-center gap-2">
-          <DmsPeriodSelector
-            :id="periodScope"
-            :component-id="`${componentId ?? 'marketing-context'}-period`"
-            :page-id="pageId"
-            variant="segmented"
-            size="xs"
-            align="left"
-            default-preset="last-30-days"
-            default-comparison="previous-period"
-            :presets="PRESETS"
-            :comparisons="COMPARISONS"
-            :preset-labels="presetLabels"
-            :comparison-labels="comparisonLabels"
-            show-range-label
-          />
-          <span
-            v-if="cutHint"
-            class="flex items-center gap-1 text-xs text-warning"
-            role="status"
-          >
-            <UIcon name="i-ph-warning" class="size-3.5 shrink-0" />
-            {{ cutHint }}
-          </span>
-          <UTooltip v-if="utcHint" :text="utcHint">
-            <span
-              class="cursor-help rounded border border-default px-1 font-mono text-[10px] text-dimmed"
-              tabindex="0"
-              :aria-label="utcHint"
-            >
-              UTC
-            </span>
-          </UTooltip>
-        </div>
-
-        <UButton
-          class="ms-auto"
-          icon="i-ph-arrow-clockwise"
-          color="neutral"
-          variant="ghost"
-          size="xs"
-          :aria-label="t('page.marketing.context.refresh')"
-          @click="refresh"
-        />
-      </template>
-      <span v-else-if="!failed" class="text-sm text-muted">
-        {{ t('page.marketing.context.no_website') }}
-      </span>
-    </div>
-
+  <div class="-mt-2 flex flex-col gap-4">
     <DmsEmptyState
       v-if="failed"
       variant="error"
@@ -431,7 +103,9 @@ const utcHint = computed(() => {
     <DmsMarketingFirstRun v-else-if="context && websites.length === 0" />
 
     <DmsEmptyState
-      v-else-if="waitingGuide && linkedId && selected?.state === 'waiting'"
+      v-else-if="
+        props.waitingGuide && linkedId && selected?.state === 'waiting'
+      "
       icon="i-ph-plugs"
       :title="
         t('page.marketing.context.waiting_guide.title', { name: selected.name })

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

@@ -5,6 +5,7 @@ import { parseExperimentValue } from '../composables/useExperiment'
 import { parseFunnelStepsValue } from '../composables/useFunnelSteps'
 import { useLatestRequest } from '../composables/useLatestRequest'
 import {
+  saveFunnel,
   useMarketingApi,
   type MarketingExperiment,
   type MarketingFunnelPreview,
@@ -23,7 +24,9 @@ import {
   funnelsLink,
 } from '../composables/useMarketingRoutes'
 import { useContextLink } from '../composables/useContextLink'
+import { useCopyDraft } from '../composables/useCopyDraft'
 import {
+  DEFAULT_WINDOW_HOURS,
   draftIssues,
   isWindowHours,
   MAX_EXPERIMENT_KEY_LENGTH,
@@ -37,6 +40,8 @@ import {
   templateSteps,
   localizedSnippetComments,
   variationSnippet,
+  WINDOW_PRESET_HOURS,
+  withRequestedSplit,
   type DraftField,
   type FunnelDraftValues,
   type StepValue,
@@ -46,8 +51,8 @@ import { normalizeFunnelStepPath } from '../utils/step-path'
 import { fractionDigits } from '../constants'
 
 /**
- * The funnel builder (`?id=` to edit, `?from=` to start from a copy of a
- * funnel, `?split=1` to open the A/B section, `?steps=` to start from a
+ * The funnel builder (`?id=` to edit, `?copy=` to start from a copy of a
+ * funnel, `?split=1` to open the A/B section switched on, `?steps=` to start from a
  * template). Steps are picked from the pages and events the site already
  * tracks, with their counts; the preview scores the draft over the last 30
  * days while it is edited. Follows the DMS form contract — unsaved changes
@@ -72,9 +77,6 @@ interface VariationDraft {
   weight: number | string
 }
 
-// A funnel is matched within one session, which ends after 30 minutes
-// without activity: a window of days would change nothing (FB-11).
-const WINDOW_PRESETS = [1, 24]
 const PREVIEW_DEBOUNCE_MS = 450
 const SUGGESTIONS_SHOWN = 6
 const MINIMUM_DETECTABLE_LIFT = 0.2
@@ -109,7 +111,7 @@ const uid = () => nextUid++
 const name = ref('')
 const websiteId = ref<string>('')
 const steps = ref<StepDraft[]>([{ uid: uid(), kind: 'url', value: '' }])
-const windowHours = ref<number | string>(24)
+const windowHours = ref<number | string>(DEFAULT_WINDOW_HOURS)
 const splitEnabled = ref(route.query.split === '1')
 const experimentKey = ref('')
 const variations = ref<VariationDraft[]>([
@@ -153,7 +155,10 @@ function applyValues(next: FunnelDraftValues): void {
 }
 
 const { dirty, baseline, markClean } = useFormDirty(values)
-const { confirmLeave } = useUnsavedChanges({ dirty })
+// A Duplicate opens dirty (the copy is a change to save), but an untouched
+// copy holds nothing to lose: only edits to it hold the leave.
+const copy = useCopyDraft({ values, dirty, markClean })
+const { confirmLeave } = useUnsavedChanges({ dirty: copy.unsaved })
 
 // Errors land under their field: the client's checks on a save attempt, and
 // the server's — its codes name the field they belong to.
@@ -240,14 +245,11 @@ function objectiveOf(draft: FunnelDraftValues): string {
 
 async function loadExisting(): Promise<void> {
   const { draft, experiment } = await fetchDefinition()
-  applyValues(draft)
+  applyValues(withRequestedSplit(draft, route.query.split))
   original.value = experiment
   savedObjective.value = objectiveOf(draft)
 }
 
-/** The copy a Duplicate opened on, what Discard returns to. */
-const copied = ref<FunnelDraftValues | null>(null)
-
 /** Duplicate: the copy is a new draft, unsaved until the user saves it — its
  * experiment key must change, keys being unique per site. */
 async function loadCopy(): Promise<void> {
@@ -260,7 +262,7 @@ async function loadCopy(): Promise<void> {
     ),
     experimentKey: '',
   })
-  copied.value = values()
+  copy.open()
 }
 
 // The builder sits outside the context bar: it reads the website list itself,
@@ -575,7 +577,7 @@ function moveStep(index: number, offset: number): void {
 }
 
 const windowItems = computed(() =>
-  WINDOW_PRESETS.map((hours) => ({
+  WINDOW_PRESET_HOURS.map((hours) => ({
     value: hours,
     label: t(`page.marketing.builder.window_presets.${hours}`),
   })),
@@ -722,12 +724,10 @@ async function save(): Promise<void> {
       conversionWindowHours: windowHours.value as number,
       experiment: experimentPayload(),
     }
-    const id = isEdit ? funnelId : (await api.createFunnel(input))[0]
-    if (isEdit) {
-      await api.updateFunnel(funnelId, input)
-    }
-    // Clean before leaving, or the leave guard would ask.
-    markClean()
+    const id = await saveFunnel(api, input, funnelId)
+    // Clean before leaving, or the leave guard would ask: a saved copy is
+    // no copy any more.
+    copy.settle()
     toast.add({
       color: 'success',
       title: t('page.marketing.builder.saved'),
@@ -742,13 +742,19 @@ async function save(): Promise<void> {
   }
 }
 
-/** Back to what the page opened on: the copy itself for a Duplicate, which
- * stays a change to save. */
+/** Back to what the page opened on. A Duplicate opened on its copy, which
+ * stays a change to save: discarding it drops the copy and leaves, with
+ * nothing left to hold the navigation. */
 function discard(): void {
   clearStepError()
   clearVariationError()
   fieldErrors.clear()
-  applyValues(copied.value ?? baseline.value)
+  if (copy.isCopy.value) {
+    copy.settle()
+    void router.push(backLink.value)
+    return
+  }
+  applyValues(baseline.value)
 }
 
 /** A link out of the builder, on the website and period it was opened from. */

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

@@ -171,12 +171,21 @@ const kpis = computed(() => [
   },
 ])
 
+/** The changes are measured against the same days a year before. */
+const isPreviousYear = computed(
+  () => props.results.comparison === 'previous-year',
+)
+
 function trend(delta: number | null, unit: 'percent' | 'points') {
   if (delta === null) {
     return {}
   }
   return {
-    detail: `${formatSignedDelta(delta, unit, locale.value)} · ${t('page.marketing.context.vs_previous_short')}`,
+    detail: `${formatSignedDelta(delta, unit, locale.value)} · ${t(
+      isPreviousYear.value
+        ? 'page.marketing.context.vs_previous_year_short'
+        : 'page.marketing.context.vs_previous_short',
+    )}`,
     detailTone:
       Math.abs(delta) < 0.05
         ? ('neutral' as const)
@@ -284,7 +293,11 @@ const coverageDate = computed(() =>
           ? t('page.marketing.funnels.coverage.period_title', {
               date: coverageDate,
             })
-          : t('page.marketing.funnels.coverage.previous_title')
+          : t(
+              isPreviousYear
+                ? 'page.marketing.funnels.coverage.previous_year_title'
+                : 'page.marketing.funnels.coverage.previous_title',
+            )
       "
       :description="
         t('page.marketing.funnels.coverage.description', {

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

@@ -12,6 +12,7 @@ import {
   funnelsLink,
 } from '../composables/useMarketingRoutes'
 import { useContextLink } from '../composables/useContextLink'
+import { useRecordCrumb } from '../composables/useRecordCrumb'
 import { formatShortDate } from '../utils/format'
 import { MS_PER_DAY, fractionDigits } from '../constants'
 
@@ -75,6 +76,8 @@ const status = computed<MarketingExperimentStatus | null>(
   () => experiment.value?.status ?? null,
 )
 const isSplit = computed(() => experiment.value !== null)
+// The breadcrumb names the funnel, not only the page ("Funnel").
+useRecordCrumb(() => funnel.value?.name)
 const notFound = computed(
   () => !current.value && apiErrorStatus(error.value) === HTTP_NOT_FOUND,
 )