@antelopejs/dms-marketing 0.3.2 → 0.4.0

package/frontend-vue/package.json

@@ -6,6 +6,9 @@
   "main": "./dms.frontend.ts",
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.6.5",
+  "engines": {
+    "@antelopejs/dms-frontend": ">=0.5.2 <0.6.0"
+  },
   "scripts": {
     "dev": "pnpm --dir ../playground frontend:dev",
     "format": "prettier --write .",

package/frontend-vue/tests/drafts.test.ts

@@ -33,9 +33,9 @@ describe('parseExperimentValue', () => {
   })
 
   it('reads a value carrying no runs as a split that served no traffic', () => {
-    expect(
-      parseExperimentValue({ key: 'cta', variations: [] })?.runs,
-    ).toEqual([])
+    expect(parseExperimentValue({ key: 'cta', variations: [] })?.runs).toEqual(
+      [],
+    )
   })
 
   it('answers null on anything else', () => {

package/frontend-vue/tests/format.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+import {
+  displayName,
+  formatDuration,
+  formatSignedDelta,
+  initials,
+  percentChangeTrend,
+} from '../app/utils/format'
+import { sampleSizePerArm } from '../app/utils/sample-size'
+import { normalizeFunnelStepPath } from '../app/utils/step-path'
+import { trackerSnippet } from '../app/utils/snippet'
+
+describe('formatting', () => {
+  it('writes durations the way analytics tools do', () => {
+    expect(formatDuration(8)).toBe('8s')
+    expect(formatDuration(168)).toBe('2m 48s')
+    expect(formatDuration(3720)).toBe('1h 2m')
+  })
+
+  it('signs deltas after rounding, so a tiny change reads as flat', () => {
+    expect(formatSignedDelta(-2.34, 'points', 'en')).toBe('−2.3 pt')
+    expect(formatSignedDelta(8, 'seconds', 'en')).toBe('+8s')
+    expect(formatSignedDelta(0.04, 'number', 'en')).toBe('±0.0')
+  })
+
+  it('reads a change in percent that rounds to 0 % as flat', () => {
+    expect(percentChangeTrend(0.3)).toBe('flat')
+    expect(percentChangeTrend(-0.49)).toBe('flat')
+    expect(percentChangeTrend(0)).toBe('flat')
+    expect(percentChangeTrend(0.5)).toBe('up')
+    expect(percentChangeTrend(-12)).toBe('down')
+  })
+
+  it('shows a pasted page step as the path the server matches', () => {
+    expect(
+      normalizeFunnelStepPath('https://shop.acme.test/Sale/Chairs/?utm=x'),
+    ).toBe('/Sale/Chairs')
+    expect(normalizeFunnelStepPath('/blog/*')).toBe('/blog/*')
+    expect(normalizeFunnelStepPath('/')).toBe('/')
+  })
+
+  it('names websites by their initials', () => {
+    expect(initials('Acme shop')).toBe('AS')
+    expect(initials('docs')).toBe('DO')
+  })
+
+  it('falls back to the raw code on a malformed region', () => {
+    expect(displayName('FR', 'region', 'en')).toBe('France')
+    expect(displayName('not a code!', 'region', 'en')).toBe('not a code!')
+  })
+})
+
+describe('helpers', () => {
+  it('asks for more sessions on a rarer conversion', () => {
+    expect(sampleSizePerArm(0.03, 0.2)).toBeGreaterThan(
+      sampleSizePerArm(0.3, 0.2),
+    )
+  })
+
+  it('builds the tracker tag for every flavour', () => {
+    const html = trackerSnippet('html', 'https://dms.example.com/', 'site-1')
+    expect(html).toContain(
+      'src="https://dms.example.com/api/marketing/tracker.js"',
+    )
+    expect(html).toContain('data-website-id="site-1"')
+    expect(
+      trackerSnippet('gtm', 'https://dms.example.com', 'site-1'),
+    ).toContain('setAttribute("data-website-id", "site-1")')
+    expect(
+      trackerSnippet('nuxt', 'https://dms.example.com', 'site-1'),
+    ).toContain('"data-website-id": "site-1"')
+  })
+})

package/frontend-vue/tests/funnel-draft.test.ts

@@ -0,0 +1,194 @@
+import { describe, expect, it } from 'vitest'
+import {
+  draftIssues,
+  isExperimentKey,
+  splitSampleSize,
+  templateSteps,
+  variationSnippet,
+  type FunnelDraftValues,
+} from '../app/utils/funnel-draft'
+import { sampleSizePerArm } from '../app/utils/sample-size'
+
+function draft(overrides: Partial<FunnelDraftValues> = {}): FunnelDraftValues {
+  return {
+    name: 'Checkout',
+    websiteId: 'acme-shop',
+    steps: [{ kind: 'url', value: '/cart' }],
+    windowHours: 24,
+    split: false,
+    experimentKey: '',
+    variations: [
+      { key: 'control', weight: 1 },
+      { key: 'bold', weight: 1 },
+    ],
+    ...overrides,
+  }
+}
+
+describe('experiment keys', () => {
+  it('follow the server rule: a slug starting with a letter or a digit, 64 max', () => {
+    expect(isExperimentKey('hero-cta')).toBe(true)
+    expect(isExperimentKey('a_1')).toBe(true)
+    expect(isExperimentKey('-abc')).toBe(false)
+    expect(isExperimentKey('_abc')).toBe(false)
+    expect(isExperimentKey('Hero CTA')).toBe(false)
+    expect(isExperimentKey('')).toBe(false)
+    expect(isExperimentKey('a'.repeat(64))).toBe(true)
+    expect(isExperimentKey('a'.repeat(65))).toBe(false)
+  })
+})
+
+describe('template links', () => {
+  it('keep the valid steps and drop the rest, never throwing', () => {
+    expect(templateSteps('[{"kind":"custom"}]')).toEqual([])
+    expect(templateSteps('not json')).toEqual([])
+    expect(templateSteps('{"kind":"url","value":"/"}')).toEqual([])
+    expect(templateSteps(undefined)).toEqual([])
+    expect(
+      templateSteps(
+        JSON.stringify([
+          { kind: 'foo', value: '/a' },
+          { kind: 'url', value: ' /b ' },
+          { kind: 'url', value: `/${'x'.repeat(600)}` },
+          { kind: 'custom', value: 'signup' },
+        ]),
+      ),
+    ).toEqual([
+      { kind: 'url', value: '/b' },
+      { kind: 'custom', value: 'signup' },
+    ])
+  })
+
+  it('stop at the step limit', () => {
+    const many = Array.from({ length: 12 }, (_, i) => ({
+      kind: 'url',
+      value: `/p${i}`,
+    }))
+    expect(templateSteps(JSON.stringify(many))).toHaveLength(10)
+  })
+})
+
+describe('draft issues', () => {
+  it('are empty for a valid funnel', () => {
+    expect(draftIssues(draft(), false)).toEqual({})
+  })
+
+  it('name the field each refusal belongs to', () => {
+    const issues = draftIssues(
+      draft({
+        name: ' ',
+        websiteId: '',
+        steps: [{ kind: 'url', value: '' }],
+        windowHours: 1000,
+      }),
+      false,
+    )
+    expect(Object.keys(issues)).toEqual([
+      'name',
+      'websiteId',
+      'steps',
+      'conversionWindowHours',
+    ])
+  })
+
+  it('flag the step that is too long', () => {
+    const issues = draftIssues(
+      draft({
+        steps: [
+          { kind: 'url', value: '/a' },
+          { kind: 'url', value: `/${'x'.repeat(500)}` },
+        ],
+      }),
+      false,
+    )
+    expect(issues.steps).toMatchObject({ message: 'step_length', index: 1 })
+  })
+
+  it('refuse a window that is empty, fractional or out of bounds', () => {
+    for (const windowHours of ['', 0, 1.5, 721]) {
+      expect(draftIssues(draft({ windowHours }), false)).toHaveProperty(
+        'conversionWindowHours',
+      )
+    }
+    expect(draftIssues(draft({ windowHours: 720 }), false)).toEqual({})
+  })
+
+  it('check the split: key, arm keys, then weights', () => {
+    const split = { split: true, experimentKey: 'hero-cta' }
+    expect(draftIssues(draft(split), false)).toEqual({})
+    expect(
+      draftIssues(draft({ ...split, experimentKey: '-abc' }), false),
+    ).toHaveProperty('experiment')
+    expect(
+      draftIssues(
+        draft({
+          ...split,
+          variations: [
+            { key: 'a', weight: 1 },
+            { key: 'a', weight: 1 },
+          ],
+        }),
+        false,
+      ).variations,
+    ).toMatchObject({ message: 'variations', index: 1 })
+    for (const weights of [
+      [0, 0],
+      [-3, 1],
+      ['', 1],
+    ]) {
+      expect(
+        draftIssues(
+          draft({
+            ...split,
+            variations: [
+              { key: 'control', weight: weights[0]! },
+              { key: 'bold', weight: weights[1]! },
+            ],
+          }),
+          false,
+        ).variations,
+      ).toMatchObject({ message: 'weights' })
+    }
+  })
+
+  it('leave a started split alone: its key and arms are frozen', () => {
+    expect(
+      draftIssues(draft({ split: true, experimentKey: '-abc' }), true),
+    ).toEqual({})
+  })
+})
+
+describe('split sample size', () => {
+  it('is what the smallest arm needs, scaled to the whole traffic', () => {
+    const perArm = sampleSizePerArm(0.04, 0.2)
+    expect(splitSampleSize(0.04, 0.2, [1, 1])).toBeCloseTo(perArm * 2)
+    expect(splitSampleSize(0.04, 0.2, [1, 3])).toBeCloseTo(perArm * 4)
+    expect(splitSampleSize(0.04, 0.2, [1, 1, 1])).toBeCloseTo(perArm * 3)
+  })
+
+  it('ignores arms that receive no traffic, and needs two that do', () => {
+    const perArm = sampleSizePerArm(0.04, 0.2)
+    expect(splitSampleSize(0.04, 0.2, [1, 1, 0])).toBeCloseTo(perArm * 2)
+    expect(splitSampleSize(0.04, 0.2, [1, 0])).toBeNull()
+    expect(splitSampleSize(0, 0.2, [1, 1])).toBeNull()
+  })
+})
+
+describe('variation snippet', () => {
+  it('runs in a classic script: no top-level await', () => {
+    const code = variationSnippet('hero-cta', 'control', ['bold', 'quiet'])
+    expect(code).not.toMatch(/^\s*(const|let|var) .*= await/m)
+    expect(code).toContain('variation("hero-cta").then(')
+    expect(code).toContain('} else if (arm === "quiet") {')
+    expect(() => new Function(code)).not.toThrow()
+  })
+
+  it('writes its comments in the language it is given', () => {
+    const code = variationSnippet('hero-cta', 'control', ['bold'], {
+      show: (variation) => `afficher ${variation}`,
+      keep: (control) => `garder ${control}`,
+    })
+    expect(code).toContain('// afficher bold')
+    expect(code).toContain('// garder control')
+  })
+})

package/frontend-vue/tests/heatmap.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+import {
+  heatmapDataLabel,
+  normalizePagePath,
+} from '../app/utils/heatmap'
+
+/** A `t` that shows which key and which plural form were asked for. */
+function t(key: string, named: Record<string, unknown> = {}, plural?: number) {
+  const name = key.split('.').at(-1)
+  if (name === 'and') {
+    return `${named.first} + ${named.second}`
+  }
+  return `${named.count} ${name}${plural === 1 ? '' : '[n]'}`
+}
+
+describe('heatmap helpers', () => {
+  it('reduces a typed path the way the tracker stores it', () => {
+    expect(normalizePagePath('demo/pricing')).toBe('/demo/pricing')
+    expect(normalizePagePath(' /demo/pricing?x=1#top ')).toBe('/demo/pricing')
+    expect(normalizePagePath('https://shop.example/cart')).toBe('/cart')
+    expect(normalizePagePath('   ')).toBeUndefined()
+  })
+
+  it('names what a reset deletes, snapshots only when there are some', () => {
+    expect(heatmapDataLabel({ events: 1, snapshots: 0 }, t, 'en-GB')).toBe(
+      '1 events',
+    )
+    expect(heatmapDataLabel({ events: 18, snapshots: 1 }, t, 'en-GB')).toBe(
+      '18 events[n] + 1 snapshots',
+    )
+  })
+})

package/frontend-vue/tests/i18n.test.ts

@@ -46,6 +46,51 @@ function backendKeys(): string[] {
   return [...found].sort()
 }
 
+const COMPONENT_DIR = join(process.cwd(), 'app')
+// `t('page.marketing.a.b'` as the components call it; template-built keys
+// are resolved at runtime and cannot be checked here.
+const COMPONENT_KEY = /t\('(page\.marketing\.[\w.-]+)'/g
+
+function filesUnder(directory: string, extension: string): string[] {
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      return filesUnder(path, extension)
+    }
+    return entry.isFile() && path.endsWith(extension) ? [path] : []
+  })
+}
+
+function componentKeys(): string[] {
+  const found = new Set<string>()
+  for (const file of [
+    ...filesUnder(COMPONENT_DIR, '.vue'),
+    ...filesUnder(COMPONENT_DIR, '.ts'),
+  ]) {
+    for (const match of readFileSync(file, 'utf8').matchAll(COMPONENT_KEY)) {
+      found.add(match[1]!)
+    }
+  }
+  return [...found].sort()
+}
+
+// The second argument of MarketingBlock(name, key, …) and of blockMeta(key, …):
+// the key every block's permission title is read under.
+const BLOCK_KEY =
+  /(?:MarketingBlock\(\s*"\w+",\s*|blockMeta\(\s*)[`"]([\w${}.-]+)[`"]/g
+
+function blockKeys(): string[] {
+  const found = new Set<string>()
+  for (const file of typescriptFiles(join(BACKEND_SOURCE_DIR, 'pages'))) {
+    for (const match of readFileSync(file, 'utf8').matchAll(BLOCK_KEY)) {
+      if (!match[1]!.includes('$')) {
+        found.add(match[1]!)
+      }
+    }
+  }
+  return [...found].sort()
+}
+
 function resolveKey(root: unknown, key: string): unknown {
   return key
     .split('.')
@@ -65,22 +110,60 @@ describe('locales', () => {
 
   it('cover every namespace the surfaces use', () => {
     for (const namespace of [
+      'context',
       'overview',
+      'acquisition',
       'pages',
-      'campaigns',
       'funnels',
-      'settings',
+      'funnel',
+      'experiment',
+      'builder',
       'websites',
+      'install',
+      'settings',
+      'blocks',
       'errors',
     ]) {
       expect(en.page.marketing).toHaveProperty(namespace)
     }
   })
 
+  it('resolve every static key the components ask for', () => {
+    const keys = componentKeys()
+    expect(keys.length).toBeGreaterThan(0)
+    expect(
+      keys.filter((key) => typeof resolveKey(en, key) !== 'string'),
+    ).toEqual([])
+    expect(
+      keys.filter((key) => typeof resolveKey(fr, key) !== 'string'),
+    ).toEqual([])
+  })
+
+  it('name every block the pages declare', () => {
+    for (const key of backendKeys().filter((key) =>
+      key.startsWith('page.marketing.blocks.'),
+    )) {
+      expect(typeof resolveKey(en, key)).toBe('string')
+    }
+    expect(blockKeys().length).toBeGreaterThan(20)
+    for (const block of blockKeys()) {
+      expect(typeof resolveKey(en, `page.marketing.blocks.${block}.name`)).toBe(
+        'string',
+      )
+      expect(
+        typeof resolveKey(fr, `page.marketing.blocks.${block}.description`),
+      ).toBe('string')
+    }
+  })
+
   it('resolve every static key the backend emits', () => {
     const keys = backendKeys()
     expect(keys.length).toBeGreaterThan(0)
-    expect(keys.filter((key) => typeof resolveKey(en, key) !== 'string')).toEqual([])
-    expect(keys.filter((key) => typeof resolveKey(fr, key) !== 'string')).toEqual([])
+    expect(
+      keys.filter((key) => typeof resolveKey(en, key) !== 'string'),
+    ).toEqual([])
+    expect(
+      keys.filter((key) => typeof resolveKey(fr, key) !== 'string'),
+    ).toEqual([])
   })
 })

package/frontend-vue/tests/latest-request.test.ts

@@ -5,9 +5,12 @@ import { useLatestRequest } from '../app/composables/useLatestRequest'
 describe('useLatestRequest loading states', () => {
   it('is unsettled immediately and settles with the fetched path inventory', async () => {
     let resolve: ((value: { pages: { path: string }[] }) => void) | undefined
-    const request = useLatestRequest(() => new Promise((done) => {
-      resolve = done
-    }))
+    const request = useLatestRequest(
+      () =>
+        new Promise((done) => {
+          resolve = done
+        }),
+    )
 
     const pending = request.run()
     expect(request.settled.value).toBe(false)

package/frontend-vue/tests/locale-typography.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import en from '../i18n/locales/marketing-en-GB.json'
+import fr from '../i18n/locales/marketing-fr-FR.json'
+
+/**
+ * What vue-i18n and French typography expect of every message, checked on the
+ * files themselves so a new string cannot bring a broken one back.
+ */
+
+const NO_BREAK_SPACE = '\u00A0'
+const NARROW_NO_BREAK_SPACE = '\u202F'
+
+// `{count}` messages whose count is never 1: a fixed minimum, a list cap.
+const COUNT_NEVER_ONE = new Set([
+  'page.marketing.experiment.insufficient_description',
+  'page.marketing.pages.list_truncated',
+])
+
+// What intlify warns about as HTML in a message (`warnHtmlMessage`).
+const HTML_TAG = /<\/?[\w\s="/.':;#-]+>/
+// A `@` that is not the literal `{'@'}` starts a linked message.
+const BARE_AT = /@(?<!\{'@)/
+
+function messages(value: unknown, prefix = ''): [string, string][] {
+  if (typeof value === 'string') {
+    return [[prefix, value]]
+  }
+  return Object.entries(value as Record<string, unknown>).flatMap(
+    ([key, child]) => messages(child, prefix ? `${prefix}.${key}` : key),
+  )
+}
+
+const english = messages(en)
+const french = messages(fr)
+
+function offending(
+  list: [string, string][],
+  test: (text: string, key: string) => boolean,
+): string[] {
+  return list.filter(([key, text]) => test(text, key)).map(([key]) => key)
+}
+
+describe('locale messages', () => {
+  it('pair every English key with a French one', () => {
+    expect(french.map(([key]) => key).sort()).toEqual(
+      english.map(([key]) => key).sort(),
+    )
+  })
+
+  it('carry no HTML, which vue-i18n warns about', () => {
+    expect(
+      offending([...english, ...french], (text) => HTML_TAG.test(text)),
+    ).toEqual([])
+  })
+
+  it("escape every @ as {'@'}", () => {
+    expect(
+      offending([...english, ...french], (text) => BARE_AT.test(text)),
+    ).toEqual([])
+  })
+
+  it('give a count its singular and plural forms', () => {
+    const needsForms = (text: string, key: string) =>
+      text.includes('{count}') &&
+      !text.includes('|') &&
+      !COUNT_NEVER_ONE.has(key)
+    expect(offending(english, needsForms)).toEqual([])
+    expect(offending(french, needsForms)).toEqual([])
+  })
+
+  it('pluralise the same keys in both languages', () => {
+    const plural = new Map(
+      english.map(([key, text]) => [key, text.includes('|')]),
+    )
+    expect(
+      offending(french, (text, key) => text.includes('|') !== plural.get(key)),
+    ).toEqual([])
+  })
+})
+
+describe('French typography', () => {
+  it('keeps : ; ! ? % and » off the start of a line', () => {
+    expect(offending(french, (text) => / [:;!?%»]/.test(text))).toEqual([])
+    expect(offending(french, (text) => /« /.test(text))).toEqual([])
+  })
+
+  it('puts a narrow no-break space before ; ! ? % and a no-break space before :', () => {
+    expect(
+      offending(french, (text) =>
+        // "(%)": a unit in a field label.
+        new RegExp(`[^${NARROW_NO_BREAK_SPACE}(][;!?%]`).test(text),
+      ),
+    ).toEqual([])
+    expect(
+      offending(french, (text) =>
+        new RegExp(`[^${NO_BREAK_SPACE}]:`).test(text),
+      ),
+    ).toEqual([])
+  })
+
+  it('writes French quotes and straight apostrophes', () => {
+    expect(offending(french, (text) => /[“”’]/.test(text))).toEqual([])
+  })
+
+  it('leaves no English product words in French prose', () => {
+    expect(
+      offending(french, (text) =>
+        /\b(analytics|first-party|tracker|snippet|capture|tagu)/i.test(
+          // utm_* parameters are typed as they are; placeholders are code.
+          text.replace(/utm_\w+|\{\w+\}|\(first-party\)/g, ''),
+        ),
+      ),
+    ).toEqual([])
+  })
+})

package/frontend-vue/tests/registration.test.ts

@@ -2,21 +2,31 @@ import { expect, it, vi } from 'vitest'
 import frontendModule from '../dms.frontend'
 
 /**
- * The backend addresses this module's surfaces by component name — the pages
+ * The backend addresses this module's blocks by component name — the pages
  * through `CustomComponent('DmsMarketing…')`, the DataTypes through their
- * form components — so a name that stops being registered silently falls back
- * to the generic card renderer instead of failing.
+ * form components. The loader puts the module's `componentPrefix` in front of
+ * each registered name, so a name that stops being registered silently
+ * falls back to a bare `<div>` instead of failing.
  */
 const BACKEND_ADDRESSED = [
-  'DmsMarketingOverviewView',
-  'DmsMarketingPagesView',
-  'DmsMarketingCampaignsView',
-  'DmsMarketingFunnelsView',
-  'DmsMarketingFunnelStepsInput',
-  'DmsMarketingExperimentInput',
+  'Context',
+  'TopListTabs',
+  'ChannelsCard',
+  'PagesExplorer',
+  'FunnelTemplates',
+  'FunnelReport',
+  'FunnelBuilder',
+  'WebsitesGrid',
+  'InstallGuide',
+  'FunnelStepsInput',
+  'ExperimentInput',
 ]
 
-it('registers every component under the DmsMarketing prefix', async () => {
+it('declares the DmsMarketing prefix', () => {
+  expect(frontendModule.componentPrefix).toBe('DmsMarketing')
+})
+
+it('registers every backend-addressed component, once, without the prefix', async () => {
   const registerComponent = vi.fn()
   const registerPlugin = vi.fn()
   await frontendModule.setup({
@@ -36,7 +46,7 @@ it('registers every component under the DmsMarketing prefix', async () => {
   expect(names.length).toBeGreaterThan(0)
   expect(new Set(names).size).toBe(names.length)
   for (const name of names) {
-    expect(name.startsWith('DmsMarketing')).toBe(true)
+    expect(name.startsWith('DmsMarketing')).toBe(false)
   }
   for (const name of BACKEND_ADDRESSED) {
     expect(names).toContain(name)