@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/frontend-vue/tests/footer-block.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h, provide, ref } from 'vue'
+import FooterBlockView from '../app/components/blocks/Footer.vue'
+import type { FooterBlock } from '../app/types/mailing'
+import { TOKEN_DATA_KEY } from '../app/utils/tokens'
+import type { TokenData } from '../app/utils/tokens'
+import { mount, slotStub, stubNuxtGlobals } from './helpers/nuxt-globals'
+import type { Mounted } from './helpers/nuxt-globals'
+
+const TokenTextStub = defineComponent({
+	props: { text: { type: String, default: '' } },
+	setup: (props) => () => h('span', props.text),
+})
+
+const footer = (overrides: Partial<FooterBlock> = {}): FooterBlock => ({
+	id: 'f',
+	type: 'footer',
+	text: 'Acme SA',
+	unsubscribeLabel: 'Unsubscribe',
+	preferencesLabel: 'Preferences',
+	visibleIf: null,
+	...overrides,
+})
+
+/** The footer on a canvas whose Data mode provides `data`. */
+const onCanvas = (block: FooterBlock, data: TokenData = null) =>
+	defineComponent({
+		setup() {
+			provide(TOKEN_DATA_KEY, ref(data))
+			return () => h(FooterBlockView, { block })
+		},
+	})
+
+let mounted: Mounted | null = null
+
+const render = (block: FooterBlock, data: TokenData = null): HTMLElement => {
+	mounted = mount(
+		onCanvas(block, data),
+		{},
+		{
+			MailingTokenText: TokenTextStub,
+			UIcon: slotStub('UIcon'),
+		},
+	)
+	return mounted.host
+}
+
+describe('Footer block on the canvas', () => {
+	beforeEach(() => stubNuxtGlobals())
+	afterEach(() => {
+		mounted?.unmount()
+		mounted = null
+		vi.unstubAllGlobals()
+	})
+
+	it('greys the links whose URL only arrives at send time', () => {
+		const host = render(footer())
+		const links = [...host.querySelectorAll('span.underline')]
+		expect(links.map((link) => link.textContent?.trim())).toEqual([
+			'Unsubscribe',
+			'Preferences',
+		])
+		expect(links[0]?.className).toContain('text-gray-400')
+		expect(links[0]?.getAttribute('title')).toBe(
+			'dms_mailing.editor.footer.url_at_send path=unsubscribeUrl',
+		)
+		expect(host.textContent).toContain(
+			'dms_mailing.editor.footer.url_at_send_hint',
+		)
+	})
+
+	it('shows a link as sent when the test data carries its URL', () => {
+		const host = render(footer({ preferencesLabel: '' }), {
+			unsubscribeUrl: 'https://u.test',
+		})
+		const links = [...host.querySelectorAll('span.underline')]
+		expect(links).toHaveLength(1)
+		expect(links[0]?.className).not.toContain('text-gray-300')
+		expect(host.textContent).not.toContain('url_at_send_hint')
+	})
+
+	it('says so when the footer has neither text nor link', () => {
+		const host = render(
+			footer({ text: '', unsubscribeLabel: '', preferencesLabel: '' }),
+		)
+		expect(host.textContent).toContain('dms_mailing.editor.footer.empty')
+	})
+})

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

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h, ref, type Ref } from 'vue'
+import FunnelCard from '../app/components/FunnelCard.vue'
+import { flush, mount, slotStub, stubNuxtGlobals } from './helpers/nuxt-globals'
+
+interface EmptyStateAction {
+	label: string
+	onClick: () => void
+}
+
+const EmptyStateStub = defineComponent({
+	props: {
+		title: { type: String, default: '' },
+		actions: { type: Array, default: () => [] },
+	},
+	setup: (props) => () =>
+		h('div', { 'data-empty-state': '' }, [
+			props.title,
+			...(props.actions as EmptyStateAction[]).map((action) =>
+				h('button', { onClick: action.onClick }, action.label),
+			),
+		]),
+})
+
+const GLOBALS = {
+	DmsCard: slotStub('DmsCard'),
+	DmsSegmented: slotStub('DmsSegmented'),
+	DmsMeter: slotStub('DmsMeter'),
+	DmsEmptyState: EmptyStateStub,
+	USkeleton: slotStub('USkeleton'),
+	UIcon: slotStub('UIcon'),
+}
+
+interface ChartFetchOptions {
+	fetchUrl: string
+	routeParams: () => Record<string, string>
+	periodScope: string
+	realtimeTopic: string
+}
+
+interface ChartFetchStub {
+	data: Ref<unknown>
+	isLoading: Ref<boolean>
+	error: Ref<unknown>
+	refresh: ReturnType<typeof vi.fn>
+	options?: ChartFetchOptions
+}
+
+let chart: ChartFetchStub
+
+const funnelStep = (id: string, count: number, isMeasured = true) => ({
+	id,
+	label: `$dms_mailing.funnel.${id}`,
+	count,
+	rate: count ? 100 : null,
+	isMeasured,
+})
+
+beforeEach(() => {
+	stubNuxtGlobals()
+	chart = {
+		data: ref(null),
+		isLoading: ref(false),
+		error: ref(null),
+		refresh: vi.fn(),
+	}
+	vi.stubGlobal('useChartFetch', (options: ChartFetchOptions) => {
+		chart.options = options
+		return chart
+	})
+})
+
+afterEach(() => {
+	vi.unstubAllGlobals()
+	document.body.innerHTML = ''
+})
+
+describe('FunnelCard', () => {
+	it('reads the funnel of the overview period, again on each sent e-mail', () => {
+		mount(FunnelCard, {}, GLOBALS)
+		expect(chart.options?.fetchUrl).toContain('/metrics/funnel?kind=')
+		expect(chart.options?.periodScope).toBe('mailing-overview')
+		expect(chart.options?.realtimeTopic).toBe('mailing:sends')
+		expect(chart.options?.routeParams()).toEqual({ kind: 'all' })
+	})
+
+	it('says the funnel failed to load and offers a retry', async () => {
+		chart.error.value = new Error('500')
+		const { host } = mount(FunnelCard, {}, GLOBALS)
+		await flush()
+
+		const empty = host.querySelector('[data-empty-state]')
+		expect(empty?.textContent).toContain('dms_mailing.funnel_card.error_title')
+		expect(host.textContent).not.toContain('dms_mailing.funnel_card.no_drop')
+
+		empty?.querySelector('button')?.click()
+		expect(chart.refresh).toHaveBeenCalledTimes(1)
+	})
+
+	it('writes "not tracked" in place of the figures nothing measures', async () => {
+		chart.data.value = {
+			steps: [
+				funnelStep('sent', 32),
+				funnelStep('delivered', 0, false),
+				funnelStep('opened', 0, false),
+				funnelStep('clicked', 0, false),
+				funnelStep('unsubscribed', 0),
+			],
+		}
+		const { host } = mount(FunnelCard, {}, GLOBALS)
+		await flush()
+
+		expect(host.querySelectorAll('[data-funnel-untracked]')).toHaveLength(3)
+		expect(host.textContent).toContain('dms_mailing.funnel_card.untracked')
+	})
+})

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

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import {
+	biggestDrop,
+	formatRate,
+	funnelTakeaway,
+	type FunnelStepReading,
+} from '../app/utils/funnel'
+
+const step = (
+	id: string,
+	count: number,
+	isMeasured = true,
+): FunnelStepReading => ({
+	id,
+	label: `$dms_mailing.funnel.${id}`,
+	count,
+	rate: 0,
+	isMeasured,
+})
+
+describe('biggestDrop', () => {
+	it('names the steps with the biggest fall, leaving the leak out', () => {
+		const drop = biggestDrop([
+			step('sent', 18420),
+			step('delivered', 18162),
+			step('opened', 7483),
+			step('clicked', 1235),
+			step('unsubscribed', 37),
+		])
+		expect(drop?.from.id).toBe('delivered')
+		expect(drop?.to.id).toBe('opened')
+		expect(drop?.points).toBeCloseTo(57.97, 1)
+	})
+
+	it('answers null when nothing was sent or nothing is lost', () => {
+		expect(biggestDrop([step('sent', 0), step('delivered', 0)])).toBeNull()
+		expect(biggestDrop([step('sent', 5), step('delivered', 5)])).toBeNull()
+		expect(biggestDrop([])).toBeNull()
+	})
+
+	// A provider that reports nothing leaves "delivered" at 0: that is not a
+	// leak between sent and delivered.
+	it('never blames a step nothing measures', () => {
+		expect(
+			biggestDrop([
+				step('sent', 32),
+				step('delivered', 0, false),
+				step('opened', 0, false),
+				step('clicked', 0, false),
+				step('unsubscribed', 0),
+			]),
+		).toBeNull()
+	})
+})
+
+describe('funnelTakeaway', () => {
+	it('tells an empty period, an unmeasured funnel and a funnel without loss apart', () => {
+		expect(funnelTakeaway([])).toBe('empty')
+		expect(funnelTakeaway([step('sent', 0), step('delivered', 0)])).toBe(
+			'empty',
+		)
+		expect(funnelTakeaway([step('sent', 4), step('delivered', 0, false)])).toBe(
+			'untracked',
+		)
+		expect(funnelTakeaway([step('sent', 4), step('delivered', 4)])).toBe(
+			'no_loss',
+		)
+		expect(funnelTakeaway([step('sent', 4), step('delivered', 2)])).toBe('drop')
+	})
+})
+
+describe('formatRate', () => {
+	it('prints one decimal at most', () => {
+		expect(formatRate(98.6, 'en-GB')).toBe('98.6%')
+		expect(formatRate(100, 'en-GB')).toBe('100%')
+	})
+
+	it('prints a dash for a rate without a base', () => {
+		expect(formatRate(null, 'en-GB')).toBe('—')
+	})
+})

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

@@ -1,5 +1,16 @@
 import { describe, expect, it } from 'vitest'
-import { UNCATEGORISED_GROUP_ID, groupByCategory } from '../app/utils/gallery'
+import {
+	UNCATEGORISED_GROUP_ID,
+	firstName,
+	formatCardDate,
+	formatCardSince,
+	groupByCategory,
+	isAttentionView,
+	isNarrowed,
+	matchesSearch,
+	searchTermOf,
+	userFilterKeys,
+} from '../app/utils/gallery'
 
 const CATEGORIES = [
 	{ id: 'orders', label: 'Orders', icon: 'i-ph-package' },
@@ -10,6 +21,7 @@ const rows = [
 	{ _id: '2', category: 'orders' },
 	{ _id: '3', category: 'unknown' },
 	{ _id: '4' },
+	{ _id: '5', category: null },
 ]
 
 describe('groupByCategory', () => {
@@ -20,7 +32,7 @@ describe('groupByCategory', () => {
 			'billing',
 			UNCATEGORISED_GROUP_ID,
 		])
-		expect(groups[2]?.items.map((row) => row._id)).toEqual(['3', '4'])
+		expect(groups[2]?.items.map((row) => row._id)).toEqual(['3', '4', '5'])
 	})
 
 	it('labels the trailing group with what the caller translated', () => {
@@ -37,3 +49,113 @@ describe('groupByCategory', () => {
 		expect(groups.map((group) => group.category.id)).toEqual(['orders'])
 	})
 })
+
+describe('table query helpers', () => {
+	it('reads the trimmed search term', () => {
+		expect(searchTermOf({ search: '  refund ' })).toBe('refund')
+		expect(searchTermOf({ search: undefined })).toBe('')
+		expect(searchTermOf(undefined)).toBe('')
+	})
+
+	it('tells user filters from the status tab', () => {
+		const query = {
+			filter_status: 'is:draft',
+			filter_category: 'is:billing',
+			sortKey: 'updatedAt',
+		}
+		expect(userFilterKeys(query)).toEqual(['filter_category'])
+		expect(isNarrowed(query)).toBe(true)
+		expect(isNarrowed({ filter_status: 'is_not:archived' })).toBe(false)
+		expect(isNarrowed({ search: 'x' })).toBe(true)
+	})
+
+	it('tells the attention tab, which is no user filter either', () => {
+		const query = { filter_needsAttention: 'is:true' }
+		expect(isAttentionView(query)).toBe(true)
+		expect(isAttentionView({ filter_status: 'is:live' })).toBe(false)
+		expect(isNarrowed(query)).toBe(false)
+	})
+})
+
+describe('formatCardDate', () => {
+	const now = new Date('2026-10-07T12:00:00Z')
+
+	it('reads recent edits as relative time', () => {
+		expect(formatCardDate('2026-10-07T10:00:00Z', now, 'en')).toBe('2 hr. ago')
+		expect(formatCardDate('2026-10-07T11:55:00Z', now, 'en')).toBe('5 min. ago')
+		expect(formatCardDate('2026-10-07T10:00:00Z', now, 'fr')).toMatch(
+			/^il y a 2\sh$/,
+		)
+	})
+
+	it('reads older ones as a short date', () => {
+		expect(formatCardDate('2026-09-27T09:00:00Z', now, 'en')).toBe('Sep 27')
+	})
+
+	it('answers nothing for an unreadable date', () => {
+		expect(formatCardDate('', now, 'en')).toBe('')
+		expect(formatCardDate('nope', now, 'en')).toBe('')
+	})
+})
+
+describe('matchesSearch', () => {
+	it('finds the term in any field, whatever its case', () => {
+		const row = { name: 'Order confirmation', slug: 'order' }
+		expect(matchesSearch(row, ' ORDER ', ['name', 'slug'])).toBe(true)
+		expect(matchesSearch(row, 'refund', ['name', 'slug'])).toBe(false)
+		expect(matchesSearch(row, '', [])).toBe(true)
+	})
+})
+
+describe('firstName', () => {
+	it('keeps the first word of a name', () => {
+		expect(firstName('Hugo Bernard')).toBe('Hugo')
+		expect(firstName('')).toBe('')
+		expect(firstName(undefined)).toBe('')
+	})
+})
+
+describe('formatCardDate with words around the date', () => {
+	const now = new Date('2026-10-07T12:00:00Z')
+	const onDate = (date: string) => `le ${date}`
+	it('dresses an absolute date only', () => {
+		expect(formatCardDate('2026-09-27T09:00:00Z', now, 'en', onDate)).toBe(
+			'le Sep 27',
+		)
+		expect(formatCardDate('2026-10-07T11:55:00Z', now, 'en', onDate)).toBe(
+			'5 min. ago',
+		)
+		expect(formatCardDate('', now, 'en', onDate)).toBe('')
+	})
+})
+
+describe('formatCardSince', () => {
+	const now = new Date('2026-10-07T12:00:00Z')
+
+	it('reads a recent start as a duration, without "ago"', () => {
+		expect(formatCardSince('2026-10-07T11:00:00Z', now, 'en')).toEqual({
+			kind: 'duration',
+			text: '1 hr',
+		})
+		expect(
+			formatCardSince('2026-10-07T11:55:00Z', now, 'fr')?.text.replace(
+				/\s/g,
+				' ',
+			),
+		).toBe('5 min')
+		expect(
+			formatCardSince('2026-10-07T11:00:00Z', now, 'fr')?.text.replace(
+				/\s/g,
+				' ',
+			),
+		).toBe('1 h')
+	})
+
+	it('reads an older start as a date', () => {
+		expect(formatCardSince('2026-09-27T10:00:00Z', now, 'en')).toEqual({
+			kind: 'date',
+			text: 'Sep 27',
+		})
+		expect(formatCardSince('bad', now, 'en')).toBe(null)
+	})
+})

package/frontend-vue/tests/helpers/nuxt-globals.ts

@@ -0,0 +1,232 @@
+import { vi } from 'vitest'
+import {
+	computed,
+	createApp,
+	defineComponent,
+	h,
+	nextTick,
+	onMounted,
+	reactive,
+	ref,
+	watch,
+	type Component,
+} from 'vue'
+
+export interface OverlayCall {
+	title: string
+	component: unknown
+	componentOptions?: Record<string, unknown>
+	direction?: string
+}
+
+export interface NuxtStubs {
+	modalCalls: OverlayCall[]
+	drawerCalls: OverlayCall[]
+	toasts: Record<string, unknown>[]
+	navigations: unknown[]
+	confirmations: Record<string, unknown>[]
+}
+
+/** Interpolates `{name}` params so assertions can read the rendered text. */
+export function translate(key: string, params?: unknown): string {
+	if (!params || typeof params !== 'object') return key
+	const values = Object.entries(params as Record<string, unknown>)
+	return `${key}${values.map(([name, value]) => ` ${name}=${String(value)}`).join('')}`
+}
+
+/**
+ * Stubs the globals the DMS auto-imports in the app (Vue's API, the i18n,
+ * containers, toasts, navigation), and records what the components ask of them.
+ */
+export function stubNuxtGlobals(email = 'camille@acme.com'): NuxtStubs {
+	const stubs: NuxtStubs = {
+		modalCalls: [],
+		drawerCalls: [],
+		toasts: [],
+		navigations: [],
+		confirmations: [],
+	}
+	const handle = () => ({
+		result: Promise.resolve(undefined),
+		patch: () => undefined,
+		close: () => undefined,
+	})
+	Object.entries({
+		computed,
+		onMounted,
+		reactive,
+		ref,
+		watch,
+		h,
+		nextTick,
+	}).forEach(([name, value]) => vi.stubGlobal(name, value))
+	vi.stubGlobal('useI18n', () => ({
+		t: translate,
+		te: () => false,
+		locale: ref('en'),
+	}))
+	vi.stubGlobal('useTranslation', () => ({
+		processApiMessage: (message: unknown) => String(message),
+		processI18n: (message: string) => message,
+	}))
+	vi.stubGlobal('useToast', () => ({
+		add: (toast: Record<string, unknown>) => stubs.toasts.push(toast),
+	}))
+	vi.stubGlobal('useUniqueLocales', () => ({
+		uniqueLocales: ref([
+			{ code: 'en', name: 'English' },
+			{ code: 'fr', name: 'Français' },
+			{ code: 'de', name: 'Deutsch' },
+		]),
+	}))
+	vi.stubGlobal('useCurrentUser', () => ({ user: ref({ email }) }))
+	vi.stubGlobal('resolveComponent', (name: string) => ({ name }))
+	vi.stubGlobal('useModal', () => ({
+		open: (call: OverlayCall) => {
+			stubs.modalCalls.push(call)
+			return handle()
+		},
+	}))
+	vi.stubGlobal('useDrawer', () => ({
+		open: (call: OverlayCall) => {
+			stubs.drawerCalls.push(call)
+			return handle()
+		},
+	}))
+	vi.stubGlobal('useConfirm', () => ({
+		confirm: async (options: Record<string, unknown>) => {
+			stubs.confirmations.push(options)
+			return true
+		},
+	}))
+	vi.stubGlobal('navigateDms', async (route: unknown) => {
+		stubs.navigations.push(route)
+	})
+	return stubs
+}
+
+/** A stand-in for a global component that renders every slot it gets. */
+export function slotStub(name: string): Component {
+	return defineComponent({
+		name,
+		inheritAttrs: false,
+		setup:
+			(_, { slots, attrs }) =>
+			() =>
+				h(
+					'div',
+					{ 'data-stub': name, ...attrs },
+					Object.values(slots).flatMap((slot) => slot?.() ?? []),
+				),
+	})
+}
+
+export interface Mounted {
+	host: HTMLElement
+	unmount: () => void
+}
+
+/** Mounts a component with stand-ins for the given global components. */
+export function mount(
+	component: Component,
+	props: Record<string, unknown>,
+	globals: Record<string, Component> = {},
+): Mounted {
+	const host = document.createElement('div')
+	document.body.appendChild(host)
+	const app = createApp(component, props)
+	Object.entries(globals).forEach(([name, value]) => app.component(name, value))
+	app.config.warnHandler = () => undefined
+	app.mount(host)
+	return {
+		host,
+		unmount: () => {
+			app.unmount()
+			host.remove()
+		},
+	}
+}
+
+/** Lets pending promises and the re-render they cause settle. */
+export async function flush(): Promise<void> {
+	for (let pass = 0; pass < 5; pass += 1) {
+		await Promise.resolve()
+		await nextTick()
+	}
+}
+
+/** `UInput`: a native input bound to `modelValue`. */
+export const InputStub = defineComponent({
+	props: { modelValue: { type: [String, Number], default: '' } },
+	emits: ['update:modelValue'],
+	setup:
+		(props, { emit, attrs }) =>
+		() =>
+			h('input', {
+				...attrs,
+				value: props.modelValue,
+				onInput: (event: Event) =>
+					emit('update:modelValue', (event.target as HTMLInputElement).value),
+			}),
+})
+
+/** `UCheckbox`: a native checkbox bound to `modelValue`. */
+export const CheckboxStub = defineComponent({
+	props: { modelValue: Boolean, label: { type: String, default: '' } },
+	emits: ['update:modelValue'],
+	setup:
+		(props, { emit, attrs }) =>
+		() =>
+			h('label', [
+				h('input', {
+					...attrs,
+					type: 'checkbox',
+					checked: props.modelValue,
+					onChange: (event: Event) =>
+						emit(
+							'update:modelValue',
+							(event.target as HTMLInputElement).checked,
+						),
+				}),
+				props.label,
+			]),
+})
+
+/** `DmsInputTags`: a text input that adds the typed address on change. */
+export const TagsStub = defineComponent({
+	props: { modelValue: { type: Array, default: () => [] } },
+	emits: ['update:modelValue'],
+	setup:
+		(props, { emit }) =>
+		() =>
+			h('input', {
+				'data-tags': (props.modelValue as string[]).join(','),
+				onChange: (event: Event) =>
+					emit('update:modelValue', [
+						...(props.modelValue as string[]),
+						(event.target as HTMLInputElement).value,
+					]),
+			}),
+})
+
+/** Global stand-ins every form test mounts with. */
+export const FORM_STUBS: Record<string, Component> = {
+	UInput: InputStub,
+	DmsInputText: InputStub,
+	DmsInputEmail: InputStub,
+	UCheckbox: CheckboxStub,
+	DmsCheckbox: CheckboxStub,
+	DmsInputTags: TagsStub,
+	UFormField: slotStub('UFormField'),
+	DmsFieldRow: slotStub('DmsFieldRow'),
+	UFieldGroup: slotStub('UFieldGroup'),
+}
+
+/** Types into a native input and lets Vue react. */
+export async function typeInto(input: Element, value: string): Promise<void> {
+	const field = input as HTMLInputElement
+	field.value = value
+	field.dispatchEvent(new Event('input'))
+	field.dispatchEvent(new Event('change'))
+	await flush()
+}