@antelopejs/dms-marketing 0.3.3 → 0.4.1

package/frontend-vue/app/composables/useMarketingRoutes.ts

@@ -1,22 +1,21 @@
 /**
  * Links between the module's surfaces.
  *
- * The `/modules/marketing` prefix comes from the page being registered under
- * a DMS module, which also makes it platform-owner-only. Should the surfaces
- * ever move to a tenant-reachable category, this file is the only place that
- * has to know.
+ * The `/modules/marketing` prefix comes from the pages being registered under
+ * a DMS module. The context bar reads the website and the period from the
+ * page URL, the reader's saved ones standing in for what it leaves out: a
+ * link followed from an analytics page carries the page's own, or it would
+ * open on whatever another tab saved last: {@link withWebsite} for the
+ * website, the DMS `withPeriodQuery` for the period selector's keys.
  */
 
 const MODULE_BASE = '/modules/marketing'
 
-interface PagesLink {
-  website?: string | null
-  path?: string | null
-  period?: string | null
-}
-
 /** Query without the empty keys — a bare link must stay bare. */
-function withQuery(base: string, query: Record<string, string | null | undefined>): string {
+function withQuery(
+  base: string,
+  query: Record<string, string | null | undefined>,
+): string {
   const params = new URLSearchParams()
   for (const [key, value] of Object.entries(query)) {
     if (value) {
@@ -27,28 +26,82 @@ function withQuery(base: string, query: Record<string, string | null | undefined
   return suffix ? `${base}?${suffix}` : base
 }
 
-/** The tracked-pages surface, optionally on a given site, path and window. */
-export function pagesLink({ website, path, period }: PagesLink = {}) {
-  return withQuery(`${MODULE_BASE}/pages`, { website, path, period })
+/** The overview, on `website` when given. */
+export function overviewLink(website?: string | null): string {
+  return withQuery(`${MODULE_BASE}/overview`, { website })
+}
+
+/** Pages & heatmaps, optionally on a given path. */
+export function pagesLink(path?: string | null): string {
+  return withQuery(`${MODULE_BASE}/pages`, { path })
+}
+
+export function acquisitionLink(): string {
+  return `${MODULE_BASE}/acquisition`
+}
+
+export function funnelsLink(): string {
+  return `${MODULE_BASE}/funnels`
+}
+
+/** One funnel's report (an A/B test's when it carries one). */
+export function funnelLink(id: string): string {
+  return withQuery(`${MODULE_BASE}/funnel`, { id })
+}
+
+interface BuilderOptions {
+  /** Open with the A/B section switched on. */
+  split?: boolean
+  /** Prefill the steps of a new funnel (a template). */
+  steps?: { kind: 'url' | 'custom'; value: string }[]
+  /** Start a new funnel as a copy of this one (Duplicate). */
+  copy?: string
+}
+
+/** The builder: a new funnel, or the one `id` names. */
+export function funnelBuilderLink(
+  id?: string | null,
+  options: BuilderOptions = {},
+): string {
+  return withQuery(`${MODULE_BASE}/funnel-builder`, {
+    id,
+    split: options.split ? '1' : null,
+    steps: options.steps ? JSON.stringify(options.steps) : null,
+    copy: options.copy,
+  })
 }
 
-interface CampaignsLink {
-  website?: string | null
-  period?: string | null
+export function websitesLink(): string {
+  return `${MODULE_BASE}/websites`
 }
 
-/** The acquisition surface, optionally on a given site and window. */
-export function campaignsLink({ website, period }: CampaignsLink = {}) {
-  return withQuery(`${MODULE_BASE}/campaigns`, { website, period })
+/** The install guide: a new website, or the one `website` names. */
+export function installLink(website?: string | null): string {
+  return withQuery(`${MODULE_BASE}/install`, { website })
 }
 
-interface FunnelsLink {
-  website?: string | null
-  funnel?: string | null
-  period?: string | null
+export function settingsLink(): string {
+  return `${MODULE_BASE}/settings`
 }
 
-/** The funnels surface, optionally on a given site, funnel and window. */
-export function funnelsLink({ website, funnel, period }: FunnelsLink = {}) {
-  return withQuery(`${MODULE_BASE}/funnels`, { website, funnel, period })
+/**
+ * `link` on the website of the page it is followed from (`query`, that page's
+ * route query), unless the link names one itself. `useContextLink` adds the
+ * period through the DMS `withPeriodQuery`.
+ */
+export function withWebsite(
+  link: string,
+  query: Record<string, unknown>,
+): string {
+  const website = query.website
+  if (typeof website !== 'string' || !website) {
+    return link
+  }
+  const [path, search = ''] = link.split('?')
+  const params = new URLSearchParams(search)
+  if (params.has('website')) {
+    return link
+  }
+  params.set('website', website)
+  return `${path}?${params.toString()}`
 }

package/frontend-vue/app/composables/useSnapshotFrame.ts

@@ -46,6 +46,27 @@ export interface AnchorBox extends AnchorRequest {
   y: number
   width: number
   height: number
+  /** What the element reads, for the "Most clicked" list; empty on an image. */
+  text: string
+}
+
+const ANCHOR_TEXT_LENGTH = 40
+
+function readableText(element: Element): string {
+  const text = (element.textContent ?? '').replace(/\s+/g, ' ').trim()
+  // An image, an icon or a picture reads through its own alternative, or the
+  // one of the image inside it.
+  const label =
+    text ||
+    element.getAttribute('aria-label') ||
+    element.getAttribute('alt') ||
+    element.getAttribute('title') ||
+    element.querySelector('img[alt]')?.getAttribute('alt') ||
+    element.querySelector('svg title')?.textContent?.trim() ||
+    ''
+  return label.length > ANCHOR_TEXT_LENGTH
+    ? `${label.slice(0, ANCHOR_TEXT_LENGTH - 1)}…`
+    : label
 }
 
 export function useSnapshotFrame(frame: Ref<HTMLIFrameElement | null>) {
@@ -143,12 +164,12 @@ export function useSnapshotFrame(frame: Ref<HTMLIFrameElement | null>) {
       let matches: NodeListOf<Element>
       try {
         matches = doc.querySelectorAll(anchor.selector)
-      }
-      catch {
+      } catch {
         continue
       }
-      const box = matches[anchor.nth]?.getBoundingClientRect()
-      if (!box || box.width <= 0 || box.height <= 0) {
+      const element = matches[anchor.nth]
+      const box = element?.getBoundingClientRect()
+      if (!element || !box || box.width <= 0 || box.height <= 0) {
         continue
       }
       boxes.push({
@@ -157,6 +178,7 @@ export function useSnapshotFrame(frame: Ref<HTMLIFrameElement | null>) {
         y: box.top + view.scrollY,
         width: box.width,
         height: box.height,
+        text: readableText(element),
       })
     }
     return boxes

package/frontend-vue/app/constants.ts

@@ -8,3 +8,25 @@
  */
 
 export const MS_PER_DAY = 86_400_000
+
+/** A website's name and domain caps (MAX_NAME_LENGTH, MAX_DOMAIN_LENGTH on the server). */
+export const MAX_WEBSITE_NAME_LENGTH = 100
+export const MAX_WEBSITE_DOMAIN_LENGTH = 253
+
+/** Longest period the routes read (MAX_QUERY_PERIOD_DAYS on the server). */
+export const MAX_PERIOD_DAYS = 90
+
+/**
+ * The id of the context bar's period selector: the scope the analytics blocks
+ * bind to and the prefix of its keys in the page URL (`?marketing.period=`).
+ * MARKETING_PERIOD_SCOPE on the server.
+ */
+export const PERIOD_SCOPE = 'marketing'
+
+/**
+ * Exactly `digits` decimals, for the DMS `formatPercentage`: a rate keeps
+ * its width from one row to the next.
+ */
+export function fractionDigits(digits: number): Intl.NumberFormatOptions {
+  return { minimumFractionDigits: digits, maximumFractionDigits: digits }
+}

package/frontend-vue/app/plugins/funnel-steps-data-type.client.ts

@@ -21,7 +21,8 @@ const FunnelStepsDisplay = defineComponent({
   name: 'FunnelStepsDisplay',
   props: {
     modelValue: {
-      type: [Array, String] as unknown as () => FunnelStepDraft[] | string | null,
+      type: [Array, String] as unknown as () =>
+        FunnelStepDraft[] | string | null,
       default: null,
     },
   },

package/frontend-vue/app/utils/channels.ts

@@ -0,0 +1,37 @@
+/** Icon and bar colour of each acquisition channel, in one place. */
+export interface ChannelStyle {
+  icon: string
+  bar: string
+}
+
+const NEUTRAL_STYLE: ChannelStyle = {
+  icon: 'i-ph-question',
+  bar: 'bg-(--ui-border-accented)',
+}
+
+// A categorical palette: six hues told apart in both themes, none of them the
+// green and orange that mean "good" and "watch out" elsewhere in the module.
+const CHANNEL_STYLES: Record<string, ChannelStyle> = {
+  direct: { icon: 'i-ph-arrow-elbow-down-right', bar: 'bg-primary' },
+  organic: {
+    icon: 'i-ph-magnifying-glass',
+    bar: 'bg-blue-600 dark:bg-blue-400',
+  },
+  email: {
+    icon: 'i-ph-envelope-simple',
+    bar: 'bg-violet-600 dark:bg-violet-400',
+  },
+  referral: { icon: 'i-ph-link', bar: 'bg-amber-500 dark:bg-amber-300' },
+  social: {
+    icon: 'i-ph-share-network',
+    bar: 'bg-pink-600 dark:bg-pink-400',
+  },
+  paid: {
+    icon: 'i-ph-currency-eur',
+    bar: 'bg-slate-700 dark:bg-slate-300',
+  },
+}
+
+export function channelStyle(channel: string): ChannelStyle {
+  return CHANNEL_STYLES[channel] ?? NEUTRAL_STYLE
+}

package/frontend-vue/app/utils/format.ts

@@ -0,0 +1,132 @@
+/**
+ * Locale formatting shared by the module's blocks. Pure functions of their
+ * inputs, so the blocks stay thin and the rules stay testable.
+ */
+
+import { fractionDigits } from '../constants'
+
+const SECONDS_PER_MINUTE = 60
+const SECONDS_PER_HOUR = 3600
+const MS_PER_SECOND = 1000
+const INITIALS_LENGTH = 2
+
+export function formatNumber(
+  value: number,
+  locale: string,
+  digits = 0,
+): string {
+  return new Intl.NumberFormat(locale, {
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  }).format(value)
+}
+
+/** "2m 48s", the way analytics tools write a visit length. */
+export function formatDuration(seconds: number): string {
+  const total = Math.max(0, Math.round(seconds))
+  const hours = Math.floor(total / SECONDS_PER_HOUR)
+  const minutes = Math.floor((total % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE)
+  const rest = total % SECONDS_PER_MINUTE
+  if (hours > 0) {
+    return `${hours}h ${minutes}m`
+  }
+  return minutes > 0 ? `${minutes}m ${rest}s` : `${rest}s`
+}
+
+/**
+ * A change in percent under half a point rounds to "0 %": it reads as no
+ * change, whatever its sign.
+ */
+const FLAT_PERCENT_CHANGE = 0.5
+
+/** Which way a change in percent (+12.5 for +12.5 %) moved, flat when it rounds to 0 %. */
+export function percentChangeTrend(delta: number): 'up' | 'down' | 'flat' {
+  if (Math.abs(delta) < FLAT_PERCENT_CHANGE) {
+    return 'flat'
+  }
+  return delta > 0 ? 'up' : 'down'
+}
+
+/** Signed difference with its unit: "+8s", "−2.3 pt", "+0.1". */
+export function formatSignedDelta(
+  value: number,
+  unit: 'points' | 'seconds' | 'number' | 'percent',
+  locale: string,
+): string {
+  const rounded = Number(value.toFixed(unit === 'seconds' ? 0 : 1))
+  const sign = rounded > 0 ? '+' : rounded < 0 ? '−' : '±'
+  const magnitude = Math.abs(rounded)
+  const formatters: Record<typeof unit, () => string> = {
+    points: () => `${formatNumber(magnitude, locale, 1)} pt`,
+    seconds: () => formatDuration(magnitude),
+    number: () => formatNumber(magnitude, locale, 1),
+    percent: () =>
+      String(formatPercentage(magnitude / 100, locale, fractionDigits(1))),
+  }
+  return `${sign}${formatters[unit]()}`
+}
+
+const RELATIVE_STEPS: [Intl.RelativeTimeFormatUnit, number][] = [
+  ['second', SECONDS_PER_MINUTE],
+  ['minute', SECONDS_PER_MINUTE],
+  ['hour', 24],
+  ['day', 30],
+  ['month', 12],
+  ['year', Number.POSITIVE_INFINITY],
+]
+
+/** "12 seconds ago", "4 minutes ago" — the age of the last event. */
+export function formatRelativeTime(
+  at: number,
+  now: number,
+  locale: string,
+): string {
+  let value = Math.round((at - now) / MS_PER_SECOND)
+  const format = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
+  for (const [unit, size] of RELATIVE_STEPS) {
+    if (Math.abs(value) < size) {
+      return format.format(value, unit)
+    }
+    value = Math.round(value / size)
+  }
+  return format.format(value, 'year')
+}
+
+/** "Aug 31 – Sep 29, 2026", the resolved range of the period. */
+export function formatDateRange(from: Date, to: Date, locale: string): string {
+  return new Intl.DateTimeFormat(locale, {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  }).formatRange(from, to)
+}
+
+export function formatShortDate(at: number | Date, locale: string): string {
+  return new Intl.DateTimeFormat(locale, {
+    month: 'short',
+    day: 'numeric',
+  }).format(at)
+}
+
+/** "AS" for "Acme shop": the avatar of a website. */
+export function initials(name: string): string {
+  const words = name.trim().split(/\s+/).filter(Boolean)
+  const letters =
+    words.length > 1
+      ? words.slice(0, INITIALS_LENGTH).map((word) => word[0])
+      : [...(words[0] ?? '?')].slice(0, INITIALS_LENGTH)
+  return letters.join('').toUpperCase()
+}
+
+/** Region and language names, falling back to the raw code on a bad one. */
+export function displayName(
+  code: string,
+  type: 'region' | 'language',
+  locale: string,
+): string {
+  try {
+    return new Intl.DisplayNames([locale], { type }).of(code) ?? code
+  } catch {
+    return code
+  }
+}

package/frontend-vue/app/utils/funnel-draft.ts

@@ -0,0 +1,264 @@
+import { sampleSizePerArm } from './sample-size'
+
+/**
+ * The rules of a funnel draft, as the builder checks them before a save.
+ *
+ * They mirror the backend's (src/types/constants.ts, src/utils/funnel-steps-type.ts
+ * and src/utils/experiment-type.ts): what passes here passes there, so a
+ * refusal shows under its field before the request instead of after it.
+ */
+export const MAX_NAME_LENGTH = 100
+export const MAX_STEPS = 10
+export const MAX_STEP_VALUE_LENGTH = 500
+export const MAX_WINDOW_HOURS = 720
+export const MIN_VARIATIONS = 2
+export const MAX_VARIATIONS = 8
+export const MAX_EXPERIMENT_KEY_LENGTH = 64
+
+/** The slug page code passes to `dmsMarketing.variation(…)`, both for the
+ * experiment and its arms: it starts with a letter or a digit. */
+const EXPERIMENT_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
+
+export function isExperimentKey(key: string): boolean {
+  return (
+    key.length <= MAX_EXPERIMENT_KEY_LENGTH && EXPERIMENT_KEY_PATTERN.test(key)
+  )
+}
+
+export interface StepValue {
+  kind: 'url' | 'custom'
+  value: string
+}
+
+export interface VariationValue {
+  key: string
+  /** A number, or '' while its input is empty. */
+  weight: number | string
+}
+
+export interface FunnelDraftValues {
+  name: string
+  websiteId: string
+  steps: StepValue[]
+  windowHours: number | string
+  split: boolean
+  experimentKey: string
+  variations: VariationValue[]
+}
+
+/** The request body keys, which also name the fields the server's errors
+ * land on. `variations` has no key of its own: it is the experiment's arms. */
+export type DraftField =
+  | 'name'
+  | 'websiteId'
+  | 'steps'
+  | 'conversionWindowHours'
+  | 'experiment'
+  | 'variations'
+
+export interface DraftIssue {
+  /** i18n key of the message, under page.marketing.builder.errors. */
+  message: string
+  params?: Record<string, unknown>
+  /** The step or variation row the issue names. */
+  index?: number
+}
+
+function isStep(step: unknown): step is StepValue {
+  const candidate = step as Partial<StepValue> | null
+  return (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    (candidate.kind === 'url' || candidate.kind === 'custom') &&
+    typeof candidate.value === 'string'
+  )
+}
+
+/**
+ * The steps of a `?steps=` template link a funnel can hold. A link is typed
+ * or edited by hand: anything malformed is dropped, never thrown.
+ */
+export function templateSteps(raw: unknown): StepValue[] {
+  if (typeof raw !== 'string') {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (!Array.isArray(parsed)) {
+    return []
+  }
+  return parsed
+    .filter(isStep)
+    .map((step) => ({ kind: step.kind, value: step.value.trim() }))
+    .filter(
+      (step) => step.value !== '' && step.value.length <= MAX_STEP_VALUE_LENGTH,
+    )
+    .slice(0, MAX_STEPS)
+}
+
+/** Whether a window is an hour count the server stores as is. */
+export function isWindowHours(hours: number | string): hours is number {
+  return (
+    typeof hours === 'number' &&
+    Number.isInteger(hours) &&
+    hours >= 1 &&
+    hours <= MAX_WINDOW_HOURS
+  )
+}
+
+function isWeight(weight: number | string): weight is number {
+  return typeof weight === 'number' && Number.isFinite(weight) && weight >= 0
+}
+
+function stepIssue(steps: StepValue[]): DraftIssue | undefined {
+  const index = steps.findIndex(
+    (step) => step.value.trim().length > MAX_STEP_VALUE_LENGTH,
+  )
+  if (index >= 0) {
+    return {
+      message: 'step_length',
+      params: { index: index + 1, max: MAX_STEP_VALUE_LENGTH },
+      index,
+    }
+  }
+  if (!steps.some((step) => step.value.trim() !== '')) {
+    return { message: 'steps', index: 0 }
+  }
+  return undefined
+}
+
+function variationIssue(variations: VariationValue[]): DraftIssue | undefined {
+  const keys = variations.map((arm) => arm.key.trim())
+  const badKey = keys.findIndex(
+    (key, index) => !isExperimentKey(key) || keys.indexOf(key) !== index,
+  )
+  if (badKey >= 0) {
+    return {
+      message: 'variations',
+      params: { max: MAX_EXPERIMENT_KEY_LENGTH },
+      index: badKey,
+    }
+  }
+  const badWeight = variations.findIndex((arm) => !isWeight(arm.weight))
+  const total = variations.reduce(
+    (sum, arm) => sum + (isWeight(arm.weight) ? arm.weight : 0),
+    0,
+  )
+  if (badWeight >= 0 || total <= 0) {
+    return { message: 'weights', index: Math.max(badWeight, 0) }
+  }
+  return undefined
+}
+
+/**
+ * The first issue of each field, in the order the form shows them. A split
+ * that has started keeps its stored key and arms, so they are not checked.
+ */
+export function draftIssues(
+  draft: FunnelDraftValues,
+  frozen: boolean,
+): Partial<Record<DraftField, DraftIssue>> {
+  const issues: Partial<Record<DraftField, DraftIssue>> = {}
+  const name = draft.name.trim()
+  if (!name) {
+    issues.name = { message: 'name' }
+  } else if (name.length > MAX_NAME_LENGTH) {
+    issues.name = { message: 'name_length', params: { max: MAX_NAME_LENGTH } }
+  }
+  if (!draft.websiteId) {
+    issues.websiteId = { message: 'website' }
+  }
+  const steps = stepIssue(draft.steps)
+  if (steps) {
+    issues.steps = steps
+  }
+  if (!isWindowHours(draft.windowHours)) {
+    issues.conversionWindowHours = {
+      message: 'window',
+      params: { max: MAX_WINDOW_HOURS },
+    }
+  }
+  if (draft.split && !frozen) {
+    if (!isExperimentKey(draft.experimentKey.trim())) {
+      issues.experiment = {
+        message: 'key',
+        params: { max: MAX_EXPERIMENT_KEY_LENGTH },
+      }
+    }
+    const variations = variationIssue(draft.variations)
+    if (variations) {
+      issues.variations = variations
+    }
+  }
+  return issues
+}
+
+/**
+ * Entered sessions a split needs before a relative `lift` on `rate` can be
+ * told from noise: each arm needs `sampleSizePerArm`, and the arm with the
+ * smallest share of the traffic is the one that takes longest to get it.
+ * Null without two arms that receive traffic.
+ */
+export function splitSampleSize(
+  rate: number,
+  lift: number,
+  weights: (number | string)[],
+): number | null {
+  const served = weights.filter(
+    (weight): weight is number => isWeight(weight) && weight > 0,
+  )
+  if (rate <= 0 || served.length < MIN_VARIATIONS) {
+    return null
+  }
+  const total = served.reduce((sum, weight) => sum + weight, 0)
+  const smallestShare = Math.min(...served) / total
+  return sampleSizePerArm(rate, lift) / smallestShare
+}
+
+/** The comments of the snippet, in the reader's language. */
+export interface VariationSnippetComments {
+  show: (variation: string) => string
+  keep: (control: string) => string
+}
+
+const ENGLISH_COMMENTS: VariationSnippetComments = {
+  show: (variation) => `show ${variation}`,
+  keep: (control) => `null or "${control}": keep the current page`,
+}
+
+/** The snippet comments read from the locale files. */
+export function localizedSnippetComments(
+  t: (key: string, named: Record<string, unknown>) => string,
+): VariationSnippetComments {
+  return {
+    show: (variation) =>
+      t('page.marketing.experiment.code_show', { variation }),
+    keep: (control) => t('page.marketing.experiment.code_keep', { control }),
+  }
+}
+
+/**
+ * The lines page code needs to serve an arm. Promise-based rather than a
+ * top-level `await`, which a classic `<script>` refuses.
+ */
+export function variationSnippet(
+  key: string,
+  control: string,
+  challengers: string[],
+  comments: VariationSnippetComments = ENGLISH_COMMENTS,
+): string {
+  return [
+    `window.dmsMarketing?.variation("${key}").then((arm) => {`,
+    ...challengers.flatMap((challenger, index) => [
+      `  ${index === 0 ? 'if' : '} else if'} (arm === "${challenger}") {`,
+      `    // ${comments.show(challenger)}`,
+    ]),
+    '  }',
+    `  // ${comments.keep(control)}`,
+    '});',
+  ].join('\n')
+}