@antelopejs/dms-mailing 0.2.2

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

@@ -0,0 +1,50 @@
+import type { Condition, ConditionOperator } from '../types/mailing'
+
+export const OPERATORS: ConditionOperator[] = [
+	'truthy',
+	'falsy',
+	'eq',
+	'ne',
+	'gt',
+	'lt',
+]
+export const OPERATORS_WITH_VALUE: ConditionOperator[] = [
+	'eq',
+	'ne',
+	'gt',
+	'lt',
+]
+
+const OPERATOR_LABEL_PREFIX = 'dms_mailing.editor.operators'
+const EMPTY_VALUE_PLACEHOLDER = '…'
+
+const quote = (value: string): string =>
+	value !== '' && !Number.isNaN(Number(value)) ? value : `"${value}"`
+
+type ConditionCompiler = (condition: Condition) => string
+
+const COMPILERS: Record<ConditionOperator, ConditionCompiler> = {
+	truthy: (condition) => `{{#if ${condition.path}}}`,
+	falsy: (condition) => `{{#unless ${condition.path}}}`,
+	eq: (condition) => `{{#if (eq ${condition.path} ${quote(condition.value)})}}`,
+	ne: (condition) =>
+		`{{#unless (eq ${condition.path} ${quote(condition.value)})}}`,
+	gt: (condition) => `{{#if (gt ${condition.path} ${quote(condition.value)})}}`,
+	lt: (condition) => `{{#if (lt ${condition.path} ${quote(condition.value)})}}`,
+}
+
+export function compileCondition(condition: Condition): string {
+	return COMPILERS[condition.operator](condition)
+}
+
+export type OperatorTranslator = (key: string) => string
+
+export function describeCondition(
+	condition: Condition,
+	t: OperatorTranslator,
+): string {
+	const label = t(`${OPERATOR_LABEL_PREFIX}.${condition.operator}`)
+	if (!OPERATORS_WITH_VALUE.includes(condition.operator))
+		return `${condition.path} ${label}`
+	return `${condition.path} ${label} ${condition.value || EMPTY_VALUE_PLACEHOLDER}`
+}

package/frontend-vue/app/utils/editor-route.ts

@@ -0,0 +1,18 @@
+export const EDITOR_PATH = '/modules/mailing/editor'
+
+export interface EditorRouteQuery extends Record<string, string | undefined> {
+	id: string
+	locale?: string
+}
+
+export interface EditorRoute {
+	path: string
+	query: EditorRouteQuery
+}
+
+export function editorRoute(templateId: string, locale?: string): EditorRoute {
+	return {
+		path: EDITOR_PATH,
+		query: locale ? { id: templateId, locale } : { id: templateId },
+	}
+}

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

@@ -0,0 +1,41 @@
+import type { TemplateCategory } from '../types/mailing'
+
+export interface CategoryGroup<T> {
+	category: TemplateCategory
+	items: T[]
+}
+
+export interface CategorizedRow {
+	category?: string
+}
+
+export const UNCATEGORISED_GROUP_ID = 'uncategorised'
+
+const UNCATEGORISED_ICON = 'i-ph-folder-dashed'
+
+/**
+ * Groups template rows by the categories declared in the settings, keeping the
+ * declared order. Rows with no category, or one the settings no longer declare,
+ * land in a trailing group the caller labels — it is the only heading here that
+ * needs translating. Empty groups are dropped.
+ */
+export function groupByCategory<T extends CategorizedRow>(
+	rows: T[],
+	categories: TemplateCategory[],
+	uncategorisedLabel: string,
+): CategoryGroup<T>[] {
+	const known = categories.map((category) => ({
+		category,
+		items: rows.filter((row) => row.category === category.id),
+	}))
+	const knownIds = new Set(categories.map((category) => category.id))
+	const uncategorised = {
+		category: {
+			id: UNCATEGORISED_GROUP_ID,
+			label: uncategorisedLabel,
+			icon: UNCATEGORISED_ICON,
+		},
+		items: rows.filter((row) => !row.category || !knownIds.has(row.category)),
+	}
+	return [...known, uncategorised].filter((group) => group.items.length > 0)
+}

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

@@ -0,0 +1,41 @@
+export interface LocalePresence {
+	code: string
+	present: boolean
+}
+
+const LOCALE_LIST_SEPARATOR = ','
+
+/** Reads the `locales` column, whose format is a comma-separated code list. */
+export function parseLocaleList(value: string | undefined): string[] {
+	return (value ?? '')
+		.split(LOCALE_LIST_SEPARATOR)
+		.map((code) => code.trim())
+		.filter(Boolean)
+}
+
+/**
+ * Coverage of `codes` (the locales the tenant offers, in its own order) by
+ * `present` (the locales something actually has).
+ */
+export function localeCoverage(
+	present: string[],
+	codes: string[],
+): LocalePresence[] {
+	const owned = new Set(present)
+	return codes.map((code) => ({ code, present: owned.has(code) }))
+}
+
+/**
+ * Badge list for a template row. A row written before the `locales` column
+ * existed carries no information, which is not the same as "no locale": it
+ * answers an empty list so the card shows nothing rather than claiming every
+ * locale is missing.
+ */
+export function localeBadges(
+	stored: string | undefined,
+	codes: string[],
+): LocalePresence[] {
+	const present = parseLocaleList(stored)
+	if (!present.length) return []
+	return localeCoverage(present, codes)
+}

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

@@ -0,0 +1,84 @@
+import type { Block, LocaleContent, TemplateContent } from '../types/mailing'
+import { splitTokens } from './tokens'
+
+const TOKEN_FIELDS = ['text', 'value', 'href', 'label', 'alt', 'imageUrl']
+
+function tokenPaths(block: Block): string[] {
+	const record = block as unknown as Record<string, unknown>
+	return TOKEN_FIELDS.flatMap((key) => {
+		const value = record[key]
+		if (typeof value !== 'string') return []
+		return splitTokens(value)
+			.filter((part) => part.kind === 'token')
+			.map((part) => part.value)
+	})
+}
+
+function branchPaths(block: Block): string[] {
+	if (block.type === 'if') {
+		return [
+			block.condition.path,
+			...pathsInBlocks(block.children),
+			...pathsInBlocks(block.elseChildren ?? []),
+		]
+	}
+	return block.type === 'list' ? [block.source] : []
+}
+
+export function pathsInBlocks(blocks: Block[]): string[] {
+	return blocks.flatMap((block) => [
+		...tokenPaths(block),
+		...(block.visibleIf ? [block.visibleIf.path] : []),
+		...branchPaths(block),
+	])
+}
+
+export function collectPaths(
+	declared: string[],
+	blocks: Block[],
+	current?: string,
+): string[] {
+	const all = [
+		...declared,
+		...pathsInBlocks(blocks),
+		...(current ? [current] : []),
+	]
+	return [...new Set(all.filter(Boolean))].sort()
+}
+
+/**
+ * Paths the runtime fills in itself, so an author never declares them. The
+ * backend drops these before answering; this list mirrors it.
+ */
+const SYSTEM_PATHS = ['unsubscribeUrl', 'preferencesUrl']
+
+function textPaths(text: string): string[] {
+	return splitTokens(text)
+		.filter((part) => part.kind === 'token')
+		.map((part) => part.value)
+}
+
+function pathsInLocale(locale: LocaleContent): string[] {
+	return [
+		...textPaths(locale.subject),
+		...textPaths(locale.preheader),
+		...pathsInBlocks(locale.blocks),
+	]
+}
+
+/**
+ * Every variable path the content references, across all of its locales — the
+ * live equivalent of what the backend returns as `detectedVariables`.
+ *
+ * The panel needs this because the server's list only refreshes on save: until
+ * then a path wired into a display condition reads as unused, which is exactly
+ * the moment an author looks at it.
+ */
+export function collectContentPaths(
+	content: Pick<TemplateContent, 'locales'>,
+): string[] {
+	const paths = Object.values(content.locales ?? {}).flatMap(pathsInLocale)
+	return [
+		...new Set(paths.filter((path) => path && !SYSTEM_PATHS.includes(path))),
+	].sort()
+}

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

@@ -0,0 +1,23 @@
+/**
+ * The DMS period selector owns the window: `PeriodState` and its `PeriodRange`
+ * come from the host layer and reach us through the workspace auto-imports.
+ * Declaring a second `PeriodRange` here put two entries of the same name in
+ * that registry, and the host's won -- ours was silently ignored.
+ */
+export type PeriodLike = Pick<PeriodState, 'range' | 'compareRange'>
+
+/**
+ * Serialises a period-selector state into the from/to (+ comparison) query the
+ * mailing metrics routes read.
+ */
+export function periodQuery(period: PeriodLike): Record<string, string> {
+	const query: Record<string, string> = {
+		from: period.range.from.toISOString(),
+		to: period.range.to.toISOString(),
+	}
+	if (period.compareRange) {
+		query.compareFrom = period.compareRange.from.toISOString()
+		query.compareTo = period.compareRange.to.toISOString()
+	}
+	return query
+}

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

@@ -0,0 +1,10 @@
+export function parseTestData(source: string): Record<string, unknown> | null {
+	try {
+		const parsed: unknown = JSON.parse(source)
+		if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+			return null
+		return parsed as Record<string, unknown>
+	} catch {
+		return null
+	}
+}

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

@@ -0,0 +1,68 @@
+import type { SendEventRow, SendStatus } from '../types/mailing'
+
+export type TimelineTone =
+	'neutral' | 'success' | 'primary' | 'error' | 'warning'
+
+export interface TimelineMeta {
+	icon: string
+	tone: TimelineTone
+}
+
+export interface TimelineItem {
+	id: string
+	type: SendStatus
+	icon: string
+	tone: TimelineTone
+	description: string
+	at: string
+}
+
+export const TIMELINE_META: Record<SendStatus, TimelineMeta> = {
+	queued: { icon: 'i-ph-clock', tone: 'neutral' },
+	sent: { icon: 'i-ph-paper-plane-tilt', tone: 'primary' },
+	delivered: { icon: 'i-ph-check', tone: 'success' },
+	opened: { icon: 'i-ph-eye', tone: 'primary' },
+	clicked: { icon: 'i-ph-cursor-click', tone: 'primary' },
+	bounced: { icon: 'i-ph-warning', tone: 'error' },
+	spam: { icon: 'i-ph-prohibit', tone: 'warning' },
+	failed: { icon: 'i-ph-warning', tone: 'error' },
+	unsubscribed: { icon: 'i-ph-user-minus', tone: 'warning' },
+}
+
+const DESCRIPTION_KEYS = ['reason', 'url', 'userAgent']
+
+interface EventDetails {
+	[key: string]: unknown
+}
+
+function parseDetails(raw: string): EventDetails {
+	try {
+		const parsed: unknown = raw ? JSON.parse(raw) : {}
+		return typeof parsed === 'object' && parsed !== null
+			? (parsed as EventDetails)
+			: {}
+	} catch {
+		return {}
+	}
+}
+
+function describe(details: EventDetails): string {
+	const key = DESCRIPTION_KEYS.find((candidate) => details[candidate])
+	return key ? String(details[key]) : ''
+}
+
+/**
+ * Orders a send's events oldest-first and resolves the icon, tone and one-line
+ * description each row shows.
+ */
+export function buildTimeline(events: SendEventRow[]): TimelineItem[] {
+	return [...events]
+		.sort((a, b) => new Date(a.at).getTime() - new Date(b.at).getTime())
+		.map((event) => ({
+			id: event._id,
+			type: event.type,
+			at: event.at,
+			description: describe(parseDetails(event.json_details)),
+			...TIMELINE_META[event.type],
+		}))
+}

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

@@ -0,0 +1,24 @@
+export type TextPartKind = 'text' | 'token'
+
+export interface TextPart {
+	kind: TextPartKind
+	value: string
+}
+
+const TOKEN_SPLIT = /(\{\{[^}]+\}\})/g
+const TOKEN_OPEN = '{{'
+const TOKEN_MARKER_LENGTH = 2
+
+export function splitTokens(text: string): TextPart[] {
+	return text
+		.split(TOKEN_SPLIT)
+		.filter(Boolean)
+		.map((part) =>
+			part.startsWith(TOKEN_OPEN)
+				? {
+						kind: 'token' as const,
+						value: part.slice(TOKEN_MARKER_LENGTH, -TOKEN_MARKER_LENGTH).trim(),
+					}
+				: { kind: 'text' as const, value: part },
+		)
+}

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

@@ -0,0 +1,48 @@
+import type { VariableDefinition, VariableType } from '../types/mailing'
+
+/**
+ * `declared` — the content uses it and someone typed it;
+ * `detected` — the content uses it, nobody declared it;
+ * `unused` — declared but the content no longer references it.
+ */
+export type VariableUsage = 'declared' | 'detected' | 'unused'
+
+export interface MergedVariable {
+	path: string
+	type: VariableType
+	required: boolean
+	usage: VariableUsage
+}
+
+const DEFAULT_TYPE: VariableType = 'string'
+
+/**
+ * One list for the variables panel: every path the content references, in the
+ * order it was detected, enriched by its declaration when there is one, then
+ * the declarations the content has stopped using.
+ */
+export function mergeVariables(
+	detected: string[],
+	declared: VariableDefinition[],
+): MergedVariable[] {
+	const byPath = new Map(declared.map((entry) => [entry.path, entry]))
+	const used = detected.map((path) => {
+		const declaration = byPath.get(path)
+		return {
+			path,
+			type: declaration?.type ?? DEFAULT_TYPE,
+			required: declaration?.required ?? false,
+			usage: declaration ? ('declared' as const) : ('detected' as const),
+		}
+	})
+	const seen = new Set(detected)
+	const unused = declared
+		.filter((entry) => !seen.has(entry.path))
+		.map((entry) => ({
+			path: entry.path,
+			type: entry.type,
+			required: entry.required,
+			usage: 'unused' as const,
+		}))
+	return [...used, ...unused]
+}

package/frontend-vue/dms.email.ts

@@ -0,0 +1,9 @@
+import type { Component } from 'vue'
+
+interface EmailModule {
+	default: Component
+}
+
+export const serverEmailTemplates = import.meta.glob<EmailModule>(
+	'./app/emails/*.vue',
+)

package/frontend-vue/dms.frontend.ts

@@ -0,0 +1,29 @@
+import { defineAsyncComponent, type Component } from 'vue'
+import type { DmsFrontendModule } from '#dms/frontend-module'
+import templateGallery from './app/plugins/template-gallery-display.client'
+
+interface VueModule {
+	default: Component
+}
+
+const components = import.meta.glob<VueModule>('./app/components/**/*.vue')
+
+const frontendModule: DmsFrontendModule = {
+	setup(sdk) {
+		Object.entries(components)
+			.sort()
+			.forEach(([path, loader]) => {
+				const name = path
+					.split('/')
+					.at(-1)!
+					.replace(/\.vue$/, '')
+				const prefix = path.includes('/components/blocks/')
+					? 'DmsMailingBlock'
+					: 'DmsMailing'
+				sdk.registerComponent(`${prefix}${name}`, defineAsyncComponent(loader))
+			})
+		sdk.registerPlugin(templateGallery, { clientOnly: true })
+	},
+}
+
+export default frontendModule

package/frontend-vue/eslint.config.mjs

@@ -0,0 +1,13 @@
+import vue from 'eslint-plugin-vue'
+import ts from 'typescript-eslint'
+
+export default [
+	{ ignores: ['node_modules/**'] },
+	...vue.configs['flat/essential'],
+	{
+		files: ['**/*.ts', '**/*.vue'],
+		languageOptions: { parserOptions: { parser: ts.parser } },
+		rules: { 'vue/multi-word-component-names': 'off' },
+	},
+	{ files: ['**/*.ts'], languageOptions: { parser: ts.parser } },
+]