@antelopejs/dms-marketing 0.3.2 → 0.4.0

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

@@ -0,0 +1,82 @@
+import { formatNumber } from './format'
+
+/** The `t` of useI18n, as far as these helpers call it. */
+type Translate = (
+  key: string,
+  named?: Record<string, unknown>,
+  plural?: number,
+) => string
+
+/** Base for reading a typed path the way the backend reads a tracked URL. */
+const RELATIVE_URL_BASE = 'http://relative.invalid'
+
+/**
+ * A typed or pasted path reduced the way the tracker stores it: pathname
+ * only, with its leading slash — `demo/pricing`, `/demo/pricing?x=1#top` and
+ * `https://site.example/demo/pricing` all read `/demo/pricing`.
+ */
+export function normalizePagePath(typed: string): string | undefined {
+  const trimmed = typed.trim()
+  if (!trimmed) {
+    return undefined
+  }
+  try {
+    return new URL(trimmed, RELATIVE_URL_BASE).pathname
+  } catch {
+    return undefined
+  }
+}
+
+/** What a heatmap reset deletes or deleted. */
+export interface HeatmapDataCounts {
+  events: number
+  snapshots: number
+}
+
+/** "18 events and 1 snapshot", "18 events", or "nothing". */
+export function heatmapDataLabel(
+  counts: HeatmapDataCounts,
+  t: Translate,
+  locale: string,
+): string {
+  const events = t(
+    'page.marketing.pages.reset.events',
+    { count: formatNumber(counts.events, locale) },
+    counts.events,
+  )
+  if (counts.snapshots === 0) {
+    return events
+  }
+  return t('page.marketing.pages.reset.and', {
+    first: events,
+    second: t(
+      'page.marketing.pages.reset.snapshots',
+      { count: formatNumber(counts.snapshots, locale) },
+      counts.snapshots,
+    ),
+  })
+}
+
+/** The impact list of a reset dialog, counted when the counts are known. */
+export function heatmapResetImpact(
+  counts: HeatmapDataCounts | null,
+  t: Translate,
+  locale: string,
+) {
+  return [
+    {
+      icon: 'i-ph-cursor-click',
+      label: t('page.marketing.pages.reset.impact_events'),
+      count: counts ? formatNumber(counts.events, locale) : undefined,
+    },
+    {
+      icon: 'i-ph-camera',
+      label: t('page.marketing.pages.reset.impact_snapshots'),
+      count: counts ? formatNumber(counts.snapshots, locale) : undefined,
+    },
+    {
+      icon: 'i-ph-check',
+      label: t('page.marketing.pages.reset.impact_kept'),
+    },
+  ]
+}

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

@@ -39,3 +39,13 @@ export function heatColorAt(fraction: number, alpha: number): string {
     Math.round(low[1][index]! + (high[1][index]! - low[1][index]!) * mix)
   return heatRgba([channel(0), channel(1), channel(2)], alpha)
 }
+
+/** The ramp as a CSS gradient, for a legend that matches what is drawn:
+ * `reversed` runs it from hot to cold. */
+export function heatLegendGradient(reversed = false): string {
+  const stops = HEAT_STOPS.map(([stop, rgb]) => {
+    const at = reversed ? 1 - stop : stop
+    return `${heatRgba(rgb, 1)} ${Math.round(at * 100)}%`
+  })
+  return `linear-gradient(to right, ${(reversed ? stops.reverse() : stops).join(', ')})`
+}

package/frontend-vue/app/utils/host-conflict.ts

@@ -0,0 +1,48 @@
+/**
+ * A host another website of the workspace already declares: the API answers
+ * 409 `{ field, message: duplicate_host, values: [host, site] }`. The DMS
+ * shows the message alone, so the forms name the site themselves.
+ */
+
+const HTTP_CONFLICT = 409
+const DUPLICATE_HOST = '$page.marketing.errors.duplicate_host'
+/** The fields a host is declared in. */
+const HOST_FIELDS = ['domain', 'extraDomains'] as const
+
+export interface HostConflict {
+  /** `domain` or `extraDomains`: the field that declares the host. */
+  field: (typeof HOST_FIELDS)[number]
+  host: string
+  /** The name of the website that declares it. */
+  site: string
+}
+
+type Translate = (key: string, params?: Record<string, unknown>) => string
+
+/**
+ * The confirmation before "Allow this host": a refused host is only what a
+ * beacon claimed, and anyone can send one naming any host.
+ */
+export function allowHostConfirmation(t: Translate, host: string) {
+  const prefix = 'page.marketing.install.allow_confirm'
+  return {
+    title: t(`${prefix}.title`, { host }),
+    description: t(`${prefix}.description`),
+    confirmLabel: t(`${prefix}.confirm`),
+    cancelLabel: t(`${prefix}.cancel`),
+    color: 'warning' as const,
+    icon: 'i-ph-warning',
+  }
+}
+
+export function hostConflictOf(error: unknown): HostConflict | null {
+  if (apiErrorStatus(error) !== HTTP_CONFLICT) {
+    return null
+  }
+  const [entry] = resolveFieldErrors(error, { fields: HOST_FIELDS }).fields
+  const [host, site] = entry?.values ?? []
+  if (entry?.message !== DUPLICATE_HOST || !host || !site) {
+    return null
+  }
+  return { field: entry.field as HostConflict['field'], host, site }
+}

package/frontend-vue/app/utils/sample-size.ts

@@ -0,0 +1,17 @@
+/** z for a two-sided 95% test and for 80% power, the usual A/B defaults. */
+const Z_ALPHA = 1.96
+const Z_POWER = 0.8416
+
+/**
+ * Sessions each arm needs before a relative lift of `lift` on a conversion
+ * rate of `rate` can be told from noise (two-proportion test, 95% / 80%).
+ */
+export function sampleSizePerArm(rate: number, lift: number): number {
+  const p1 = rate
+  const p2 = Math.min(rate * (1 + lift), 1)
+  const variance = p1 * (1 - p1) + p2 * (1 - p2)
+  const effect = (p2 - p1) ** 2
+  return effect > 0
+    ? ((Z_ALPHA + Z_POWER) ** 2 * variance) / effect
+    : Number.POSITIVE_INFINITY
+}

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

@@ -20,12 +20,17 @@ export interface SnapshotViewport {
   height: number
 }
 
-const VIEWPORT_UNIT = /(-?(?:\d+\.?\d*|\.\d+))(dvh|svh|lvh|vh|vmin|vmax)(?![\w-])/g
+const VIEWPORT_UNIT =
+  /(-?(?:\d+\.?\d*|\.\d+))(dvh|svh|lvh|vh|vmin|vmax)(?![\w-])/g
 const DECLARATION_VALUE = /((?<!\\):)([^;{}]*)/g
 const STYLE_BLOCK = /(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi
 const STYLE_ATTRIBUTE = /(\sstyle=")([^"]*)(")/gi
 
-function pixelsOf(amount: string, unit: string, viewport: SnapshotViewport): number {
+function pixelsOf(
+  amount: string,
+  unit: string,
+  viewport: SnapshotViewport,
+): number {
   const base = unit.endsWith('vh')
     ? viewport.height
     : unit === 'vmin'
@@ -37,18 +42,23 @@ function pixelsOf(amount: string, unit: string, viewport: SnapshotViewport): num
 function rewriteValue(value: string, viewport: SnapshotViewport): string {
   return value.replace(
     VIEWPORT_UNIT,
-    (_match, amount: string, unit: string) => `${pixelsOf(amount, unit, viewport)}px`,
+    (_match, amount: string, unit: string) =>
+      `${pixelsOf(amount, unit, viewport)}px`,
   )
 }
 
 function rewriteDeclarations(css: string, viewport: SnapshotViewport): string {
   return css.replace(
     DECLARATION_VALUE,
-    (_match, colon: string, value: string) => colon + rewriteValue(value, viewport),
+    (_match, colon: string, value: string) =>
+      colon + rewriteValue(value, viewport),
   )
 }
 
-export function rewriteViewportUnits(html: string, viewport: SnapshotViewport): string {
+export function rewriteViewportUnits(
+  html: string,
+  viewport: SnapshotViewport,
+): string {
   return html
     .replace(
       STYLE_BLOCK,

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

@@ -0,0 +1,53 @@
+/**
+ * The tag a site pastes to load the tracker, in the shapes the install guide
+ * offers. Built from the API origin the dashboard talks to, which is where the
+ * tracker and the collect endpoint live.
+ */
+export type SnippetFlavor = 'html' | 'nuxt' | 'gtm'
+
+// Split so a bundler or a linter never reads a real closing tag here.
+const CLOSING_TAG = '</' + 'script>'
+
+export function trackerUrl(apiOrigin: string): string {
+  return `${apiOrigin.replace(/\/$/, '')}/api/marketing/tracker.js`
+}
+
+const BUILDERS: Record<
+  SnippetFlavor,
+  (src: string, websiteId: string) => string
+> = {
+  html: (src, websiteId) =>
+    `<script defer src="${src}"\n        data-website-id="${websiteId}">${CLOSING_TAG}`,
+  nuxt: (src, websiteId) =>
+    [
+      '// nuxt.config.ts',
+      'export default defineNuxtConfig({',
+      '  app: {',
+      '    head: {',
+      `      script: [{ src: "${src}", defer: true, "data-website-id": "${websiteId}" }],`,
+      '    },',
+      '  },',
+      '})',
+    ].join('\n'),
+  gtm: (src, websiteId) =>
+    [
+      '<!-- Custom HTML tag, fired on All Pages -->',
+      '<script>',
+      '  (function () {',
+      '    var s = document.createElement("script");',
+      `    s.src = "${src}";`,
+      '    s.defer = true;',
+      `    s.setAttribute("data-website-id", "${websiteId}");`,
+      '    document.head.appendChild(s);',
+      '  })();',
+      CLOSING_TAG,
+    ].join('\n'),
+}
+
+export function trackerSnippet(
+  flavor: SnippetFlavor,
+  apiOrigin: string,
+  websiteId: string,
+): string {
+  return BUILDERS[flavor](trackerUrl(apiOrigin), websiteId)
+}

package/frontend-vue/app/utils/step-path.ts

@@ -0,0 +1,32 @@
+/**
+ * A page step the way the server stores and matches it (mirror of
+ * `src/services/funnels/step-path.ts`): a pasted URL, a host glued to the
+ * path, a query string, a fragment or a trailing slash come down to the path;
+ * a final `*` stays, as a prefix wildcard. The builder shows the result under
+ * the step when it differs from what was typed.
+ */
+
+const STEP_PATH_BASE = 'http://step.invalid'
+const STEP_SCHEME_PATTERN = /^[a-z][a-z\d+.-]*:\/\//i
+const STEP_BARE_HOST_PATTERN = /^[^/\s?#]+\.[^/\s?#]+\//
+
+export function normalizeFunnelStepPath(raw: string): string {
+  const value = raw.trim()
+  const prefix = value.endsWith('*')
+  const body = prefix ? value.slice(0, -1) : value
+  const absolute = STEP_SCHEME_PATTERN.test(body)
+    ? body
+    : STEP_BARE_HOST_PATTERN.test(body)
+      ? `https://${body}`
+      : `${STEP_PATH_BASE}${body.startsWith('/') ? '' : '/'}${body}`
+  let path: string
+  try {
+    path = new URL(absolute).pathname
+  } catch {
+    return value
+  }
+  if (prefix) {
+    return `${path}*`
+  }
+  return path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path
+}

package/frontend-vue/dms.frontend.ts

@@ -9,12 +9,13 @@ interface VueModule {
 /**
  * Every component of this module is addressed by name from the backend: the
  * pages declare `CustomComponent('DmsMarketing<Name>')` and the DataTypes
- * resolve their inputs the same way. Registering the whole directory under
- * that prefix keeps the two sides in sync without a manual list.
+ * resolve their inputs the same way. Registering the whole directory behind
+ * the module's prefix keeps the two sides in sync without a manual list.
  */
 const components = import.meta.glob<VueModule>('./app/components/**/*.vue')
 
 const frontendModule: DmsFrontendModule = {
+  componentPrefix: 'DmsMarketing',
   setup(sdk) {
     for (const [path, loader] of Object.entries(components).sort()) {
       const name = path
@@ -22,7 +23,7 @@ const frontendModule: DmsFrontendModule = {
         .at(-1)!
         .replace(/\.vue$/, '')
       sdk.registerComponent(
-        `DmsMarketing${name}`,
+        name,
         defineAsyncComponent(async () => (await loader()).default),
       )
     }