@antelopejs/dms-mailing 0.3.4 → 0.4.0

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

@@ -0,0 +1,266 @@
+import type {
+	Block,
+	IfBlock,
+	LocaleContent,
+	TemplateContent,
+	VariableDefinition,
+} from '../types/mailing'
+import { flattenBlocks } from './blocks/tree'
+import { evaluateCondition } from './conditions'
+import { pickLocale } from './locales'
+import { isPresent, readPath } from './paths'
+import { splitTokens } from './tokens'
+
+export type EditorCheckState = 'ok' | 'warn' | 'info'
+
+/** A check before the i18n pass: its key and the values it interpolates. */
+export interface EditorCheck {
+	id: string
+	state: EditorCheckState
+	key: string
+	params: Record<string, string | number>
+}
+
+/** What the checks read: declarations, used paths, test data, blocks. */
+export interface CheckInput {
+	variables: VariableDefinition[]
+	detected: string[]
+	data: Record<string, unknown>
+	blocks: Block[]
+}
+
+const CHECK_KEY_PREFIX = 'dms_mailing.editor.checks'
+const WARNING_STATES: EditorCheckState[] = ['warn']
+
+const check = (
+	id: string,
+	state: EditorCheckState,
+	key: string,
+	params: Record<string, string | number> = {},
+): EditorCheck => ({ id, state, key: `${CHECK_KEY_PREFIX}.${key}`, params })
+
+/** Paths the content uses that no declaration covers. */
+export function undeclaredPaths(
+	detected: string[],
+	variables: VariableDefinition[],
+): string[] {
+	const declared = new Set(variables.map((variable) => variable.path))
+	return detected.filter((path) => !declared.has(path))
+}
+
+/** Required declarations the data set does not provide. */
+export function missingRequired(
+	variables: VariableDefinition[],
+	data: Record<string, unknown>,
+): string[] {
+	return variables
+		.filter((variable) => variable.required)
+		.map((variable) => variable.path)
+		.filter((path) => !isPresent(readPath(data, path)))
+}
+
+/** What the content checks read: the draft and the workspace locales. */
+export interface ContentCheckInput {
+	content: TemplateContent
+	/** The workspace locales, each of which recipients may ask for. */
+	locales: string[]
+	fallback: string
+}
+
+const FOOTER_TYPE = 'footer'
+
+const footerCount = (locale: LocaleContent): number =>
+	flattenBlocks(locale.blocks).filter((block) => block.type === FOOTER_TYPE)
+		.length
+
+/** A rule a locale's body breaks: the check key it reports under. */
+interface BodyRule {
+	key: string
+	isBroken: (locale: LocaleContent) => boolean
+}
+
+const BODY_RULES: BodyRule[] = [
+	{
+		key: 'no_blocks',
+		isBroken: (locale) =>
+			!locale.blocks.some((block) => block.type !== FOOTER_TYPE),
+	},
+	{ key: 'no_footer', isBroken: (locale) => footerCount(locale) === 0 },
+	{ key: 'many_footers', isBroken: (locale) => footerCount(locale) > 1 },
+	{
+		key: 'footer_not_last',
+		isBroken: (locale) =>
+			footerCount(locale) > 0 && locale.blocks.at(-1)?.type !== FOOTER_TYPE,
+	},
+]
+
+const localeEntries = (content: TemplateContent): [string, LocaleContent][] =>
+	Object.entries(content.locales)
+
+/** Locales a publish is refused for: a send would go out without a subject. */
+export function publishBlockers(content: TemplateContent): EditorCheck[] {
+	return localeEntries(content)
+		.filter(([, locale]) => !locale.subject.trim())
+		.map(([code]) =>
+			check(`subject-${code}`, 'warn', 'empty_subject', {
+				locale: code.toUpperCase(),
+			}),
+		)
+}
+
+function bodyChecks(content: TemplateContent): EditorCheck[] {
+	return localeEntries(content).flatMap(([code, locale]) =>
+		BODY_RULES.filter((rule) => rule.isBroken(locale)).map((rule) =>
+			check(`${rule.key}-${code}`, 'warn', rule.key, {
+				locale: code.toUpperCase(),
+			}),
+		),
+	)
+}
+
+/** Every text a locale shows: its envelope and each block's string fields. */
+function localeTexts(locale: LocaleContent): string[] {
+	const fields = flattenBlocks(locale.blocks).flatMap((block) =>
+		Object.values(block as unknown as Record<string, unknown>),
+	)
+	return [
+		locale.subject,
+		locale.preheader,
+		...fields.filter((value): value is string => typeof value === 'string'),
+	]
+}
+
+function tokensOf(locale: LocaleContent, kind: 'token' | 'invalid'): string[] {
+	return localeTexts(locale)
+		.flatMap(splitTokens)
+		.filter((part) => part.kind === kind)
+		.map((part) => part.value)
+}
+
+/** `{{…}}` look-alikes the engine leaves as typed: customers would see them. */
+function malformedTokenChecks(content: TemplateContent): EditorCheck[] {
+	return localeEntries(content).flatMap(([code, locale]) =>
+		[...new Set(tokensOf(locale, 'invalid'))].map((token) =>
+			check(`token-${code}-${token}`, 'warn', 'invalid_token', {
+				locale: code.toUpperCase(),
+				token,
+			}),
+		),
+	)
+}
+
+const isStructured = (value: unknown): boolean =>
+	value !== null && typeof value === 'object' && !(value instanceof Date)
+
+/** Tokens whose test value is an object or a list: they print as raw data. */
+function structuredTokenChecks(
+	content: TemplateContent,
+	data: Record<string, unknown>,
+): EditorCheck[] {
+	const paths = localeEntries(content).flatMap(([, locale]) =>
+		tokensOf(locale, 'token'),
+	)
+	return [...new Set(paths)]
+		.filter((path) => isStructured(readPath(data, path)))
+		.map((path) =>
+			check(`structured-${path}`, 'warn', 'token_not_text', { path }),
+		)
+}
+
+/** What the publish review warns about the content's `{{…}}` tokens. */
+export function tokenChecks(
+	content: TemplateContent,
+	data: Record<string, unknown>,
+): EditorCheck[] {
+	return [
+		...malformedTokenChecks(content),
+		...structuredTokenChecks(content, data),
+	]
+}
+
+function missingLocaleChecks(input: ContentCheckInput): EditorCheck[] {
+	const present = Object.keys(input.content.locales)
+	if (!present.length) return []
+	return input.locales
+		.filter((code) => !input.content.locales[code])
+		.map((code) =>
+			check(`locale-${code}`, 'warn', 'missing_locale', {
+				locale: code.toUpperCase(),
+				fallback: pickLocale(present, code, input.fallback).toUpperCase(),
+			}),
+		)
+}
+
+/** What the publish review warns about the draft's content itself. */
+export function contentChecks(input: ContentCheckInput): EditorCheck[] {
+	return [...bodyChecks(input.content), ...missingLocaleChecks(input)]
+}
+
+/** The failed checks the publish review warns about. */
+export function publishChecks(input: CheckInput): EditorCheck[] {
+	return [
+		...undeclaredPaths(input.detected, input.variables).map((path) =>
+			check(`undeclared-${path}`, 'warn', 'undeclared', { path }),
+		),
+		...missingRequired(input.variables, input.data).map((path) =>
+			check(`required-${path}`, 'warn', 'required_missing', { path }),
+		),
+	]
+}
+
+function requiredCheck(input: CheckInput): EditorCheck[] {
+	const required = input.variables.filter((variable) => variable.required)
+	if (!required.length) return []
+	const missing = missingRequired(input.variables, input.data)
+	if (!missing.length)
+		return [
+			check('required', 'ok', 'required_covered', { count: required.length }),
+		]
+	return missing
+		.filter((path) => !input.detected.includes(path))
+		.map((path) =>
+			check(`required-${path}`, 'warn', 'required_missing', { path }),
+		)
+}
+
+function coverageChecks(input: CheckInput): EditorCheck[] {
+	const undeclared = new Set(undeclaredPaths(input.detected, input.variables))
+	return input.detected
+		.filter((path) => !isPresent(readPath(input.data, path)))
+		.map((path) =>
+			check(
+				`missing-${path}`,
+				'warn',
+				undeclared.has(path) ? 'missing_undeclared' : 'missing',
+				{ path },
+			),
+		)
+}
+
+function conditionChecks(input: CheckInput): EditorCheck[] {
+	return flattenBlocks(input.blocks)
+		.filter((block): block is IfBlock => block.type === 'if')
+		.map((block) => {
+			const result = evaluateCondition(block.condition, input.data)
+			return check(
+				`condition-${block.id}`,
+				'info',
+				result ? 'condition_true' : 'condition_false',
+				{ path: block.condition.path },
+			)
+		})
+}
+
+/** The Test data tab's checks: coverage, then how each condition evaluates. */
+export function testDataChecks(input: CheckInput): EditorCheck[] {
+	return [
+		...requiredCheck(input),
+		...coverageChecks(input),
+		...conditionChecks(input),
+	]
+}
+
+/** How many checks need a look: the Test data tab's badge. */
+export function openIssueCount(checks: EditorCheck[]): number {
+	return checks.filter((entry) => WARNING_STATES.includes(entry.state)).length
+}

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

@@ -1,7 +1,14 @@
-export const EDITOR_PATH = '/modules/mailing/editor'
+import { TEMPLATES_PATH } from './pages'
+
+const PATH_SEPARATOR = '/'
+
+/**
+ * The DMS state key the breadcrumb reads the record label from (the same one
+ * the core's `usePageRecordLabel` writes).
+ */
+export const RECORD_LABEL_STATE_KEY = 'dms-page-record-label'
 
 export interface EditorRouteQuery extends Record<string, string | undefined> {
-	id: string
 	locale?: string
 }
 
@@ -10,9 +17,41 @@ export interface EditorRoute {
 	query: EditorRouteQuery
 }
 
+/** Where the editor of `templateId` lives, optionally on one locale. */
 export function editorRoute(templateId: string, locale?: string): EditorRoute {
 	return {
-		path: EDITOR_PATH,
-		query: locale ? { id: templateId, locale } : { id: templateId },
+		path: `${TEMPLATES_PATH}${PATH_SEPARATOR}${encodeURIComponent(templateId)}`,
+		query: locale ? { locale } : {},
 	}
 }
+
+export interface EditorRouteParams {
+	id?: string | number
+}
+
+/**
+ * The template id of the editor page: the `:id` route param the DMS hands the
+ * component, else the last segment of the current path.
+ */
+export function templateIdFrom(
+	params: EditorRouteParams | undefined,
+	path: string,
+): string {
+	if (params?.id !== undefined && params.id !== '') return String(params.id)
+	const last = path.split(PATH_SEPARATOR).filter(Boolean).at(-1) ?? ''
+	return decodeURIComponent(last)
+}
+
+/** The record label the breadcrumb ends with: the template's name. */
+export interface RecordLabel {
+	path: string
+	label: string
+}
+
+/** Builds the breadcrumb label for the page at `path`; no name clears it. */
+export function recordLabelFor(
+	path: string,
+	name: string | undefined,
+): RecordLabel | null {
+	return name ? { path, label: name } : null
+}

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

@@ -0,0 +1,74 @@
+import type { FunnelKind, FunnelStep } from '../types/mailing'
+
+/** The step that leaks out of the funnel rather than going down it. */
+export const FUNNEL_LEAK_STEP = 'unsubscribed'
+
+export const FUNNEL_KINDS: FunnelKind[] = ['all', 'transactional', 'marketing']
+
+/**
+ * A step as `GET /metrics/funnel` answers it: `rate` is `null` on an empty
+ * base, `isMeasured` false when nothing reports the events it counts.
+ */
+export interface FunnelStepReading extends Omit<FunnelStep, 'rate'> {
+	rate: number | null
+	isMeasured?: boolean
+}
+
+export interface FunnelDrop {
+	from: FunnelStepReading
+	to: FunnelStepReading
+	/** Share of the sends lost between the two steps, in points. */
+	points: number
+}
+
+/** What the card's footer says about the funnel. */
+export type FunnelTakeaway = 'empty' | 'untracked' | 'no_loss' | 'drop'
+
+const RATE_DECIMALS = 1
+const PERCENT = 100
+const ABSENT_RATE = '—'
+
+/** `false` only when the backend says nothing reports the step's events. */
+export const isMeasured = (step: FunnelStepReading): boolean =>
+	step.isMeasured !== false
+
+/**
+ * The biggest fall between two consecutive steps of the funnel (the leak and
+ * the unmeasured steps excluded), measured on the sends lost. `null` when
+ * nothing was sent or no step loses anything.
+ */
+export function biggestDrop(steps: FunnelStepReading[]): FunnelDrop | null {
+	const path = steps.filter(
+		(step) => step.id !== FUNNEL_LEAK_STEP && isMeasured(step),
+	)
+	const total = path[0]?.count ?? 0
+	if (!total) return null
+	const drops = path.slice(1).map((step, index) => {
+		const from = path[index] as FunnelStepReading
+		return {
+			from,
+			to: step,
+			points: ((from.count - step.count) / total) * PERCENT,
+		}
+	})
+	return drops.reduce<FunnelDrop | null>(
+		(best, drop) => (drop.points > (best?.points ?? 0) ? drop : best),
+		null,
+	)
+}
+
+/** Which sentence the footer writes: there may be no drop for three reasons. */
+export function funnelTakeaway(steps: FunnelStepReading[]): FunnelTakeaway {
+	if (!steps[0]?.count) return 'empty'
+	if (biggestDrop(steps)) return 'drop'
+	return steps.some((step) => !isMeasured(step)) ? 'untracked' : 'no_loss'
+}
+
+/** A funnel rate as the card prints it: one decimal, none when whole. */
+export function formatRate(rate: number | null, locale: string): string {
+	if (rate === null) return ABSENT_RATE
+	return new Intl.NumberFormat(locale, {
+		style: 'percent',
+		maximumFractionDigits: RATE_DECIMALS,
+	}).format(rate / PERCENT)
+}

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

@@ -6,7 +6,7 @@ export interface CategoryGroup<T> {
 }
 
 export interface CategorizedRow {
-	category?: string
+	category?: string | null
 }
 
 export const UNCATEGORISED_GROUP_ID = 'uncategorised'
@@ -39,3 +39,181 @@ export function groupByCategory<T extends CategorizedRow>(
 	}
 	return [...known, uncategorised].filter((group) => group.items.length > 0)
 }
+
+/** The slice of the DMS `TableViewDisplayPagination` the gallery reads. */
+export interface GalleryPagination {
+	pageIndex: number
+	pageSize: number
+	total: number
+	setPage: (index: number) => void
+	mode?: string
+	hasMore?: boolean
+	loadMore?: () => void
+}
+
+/** The slice of the DMS `TableViewDisplayActions` the gallery reads. */
+export interface GalleryActions<T> {
+	open: (item: T) => void
+}
+
+/** The slice of the TanStack table the gallery reaches for its reset. */
+export interface GalleryTable {
+	setGlobalFilter: (value: string) => void
+}
+
+/**
+ * The slice of the DMS `TableViewDisplayContext` the gallery display reads,
+ * declared structurally: the layer does not import from the dms-ui layer.
+ */
+export interface GalleryContext<T> {
+	items: T[]
+	loading: boolean
+	pagination: GalleryPagination
+	actions?: GalleryActions<T>
+	/** Active filters, search and sort of the table, without paging. */
+	query?: Record<string, unknown>
+	refresh: () => Promise<void> | void
+	table?: GalleryTable
+}
+
+const SEARCH_KEY = 'search'
+const FILTER_PREFIX = 'filter_'
+/** The "Needs attention" tab filters on this column. */
+const ATTENTION_FILTER_KEY = `${FILTER_PREFIX}needsAttention`
+/** The tabs filter on these columns: a tab is not a user filter. */
+const TAB_FILTER_KEYS = new Set([
+	`${FILTER_PREFIX}status`,
+	ATTENTION_FILTER_KEY,
+])
+
+/** The search typed in the table, trimmed; empty without one. */
+export function searchTermOf(
+	query: Record<string, unknown> | undefined,
+): string {
+	const value = query?.[SEARCH_KEY]
+	return typeof value === 'string' ? value.trim() : ''
+}
+
+/** The filters the user set (quick filters, filter rows), not the tab. */
+export function userFilterKeys(
+	query: Record<string, unknown> | undefined,
+): string[] {
+	return Object.keys(query ?? {}).filter(
+		(key) => key.startsWith(FILTER_PREFIX) && !TAB_FILTER_KEYS.has(key),
+	)
+}
+
+/** Whether the table shows its "Needs attention" tab. */
+export function isAttentionView(
+	query: Record<string, unknown> | undefined,
+): boolean {
+	return ATTENTION_FILTER_KEY in (query ?? {})
+}
+
+/** Whether a search or a filter narrows what the gallery lists. */
+export function isNarrowed(
+	query: Record<string, unknown> | undefined,
+): boolean {
+	return Boolean(searchTermOf(query)) || userFilterKeys(query).length > 0
+}
+
+/** Whether `row` holds `search`, whatever its case, in one of `fields`. */
+export function matchesSearch(
+	row: object,
+	search: string,
+	fields: string[],
+): boolean {
+	const term = search.trim().toLowerCase()
+	const cellOf = (field: string) =>
+		String((row as Record<string, unknown>)[field] ?? '').toLowerCase()
+	return !term || fields.some((field) => cellOf(field).includes(term))
+}
+
+const SORT_KEY = 'sortKey'
+
+/** The table's sort column; absent without one. */
+export function sortKeyOf(
+	query: Record<string, unknown> | undefined,
+): string | undefined {
+	const key = query?.[SORT_KEY]
+	return typeof key === 'string' && key ? key : undefined
+}
+
+const MS_PER_HOUR = 3_600_000
+const MS_PER_MINUTE = 60_000
+const HOURS_PER_DAY = 24
+
+/** Words a sentence puts around an absolute date ("le 27 sept." in French). */
+export type OnDate = (date: string) => string
+
+const bareDate: OnDate = (date) => date
+
+/**
+ * A date as a card reads it: "2 hr. ago" / "5 min. ago" within a day, "Sep 27"
+ * after. `onDate` dresses the absolute one only, so a sentence written around
+ * it ("Edited {date}") reads right in both cases. Empty for an unreadable date.
+ */
+export function formatCardDate(
+	date: string | null | undefined,
+	now: Date,
+	locale: string,
+	onDate: OnDate = bareDate,
+): string {
+	const time = date ? new Date(date).getTime() : Number.NaN
+	if (Number.isNaN(time)) return ''
+	const elapsed = Math.max(0, now.getTime() - time)
+	const relative = new Intl.RelativeTimeFormat(locale, {
+		numeric: 'auto',
+		style: 'short',
+	})
+	if (elapsed < MS_PER_HOUR) {
+		return relative.format(-Math.round(elapsed / MS_PER_MINUTE), 'minute')
+	}
+	if (elapsed < HOURS_PER_DAY * MS_PER_HOUR) {
+		return relative.format(-Math.round(elapsed / MS_PER_HOUR), 'hour')
+	}
+	return onDate(
+		new Intl.DateTimeFormat(locale, {
+			month: 'short',
+			day: '2-digit',
+		}).format(new Date(time)),
+	)
+}
+
+/**
+ * How long ago `date` was, the way "live since…" reads it: a duration within a
+ * day ("1 hr", "5 min"; "1 h" in French), the date after ("Sep 27"). `null`
+ * for an unreadable date.
+ */
+export interface CardSince {
+	kind: 'duration' | 'date'
+	text: string
+}
+
+export function formatCardSince(
+	date: string | null | undefined,
+	now: Date,
+	locale: string,
+): CardSince | null {
+	const time = date ? new Date(date).getTime() : Number.NaN
+	if (Number.isNaN(time)) return null
+	const elapsed = Math.max(0, now.getTime() - time)
+	if (elapsed >= HOURS_PER_DAY * MS_PER_HOUR)
+		return { kind: 'date', text: formatCardDate(date, now, locale) }
+	const isHours = elapsed >= MS_PER_HOUR
+	const amount = Math.max(
+		1,
+		Math.round(elapsed / (isHours ? MS_PER_HOUR : MS_PER_MINUTE)),
+	)
+	const text = new Intl.NumberFormat(locale, {
+		style: 'unit',
+		unit: isHours ? 'hour' : 'minute',
+		unitDisplay: 'short',
+	}).format(amount)
+	return { kind: 'duration', text }
+}
+
+/** The first word of a person's name ("Hugo Bernard" → "Hugo"). */
+export function firstName(fullName: string | null | undefined): string {
+	return (fullName ?? '').trim().split(/\s+/)[0] ?? ''
+}

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

@@ -0,0 +1,66 @@
+/** Undo / redo over serialized content snapshots. */
+export interface EditorHistory {
+	past: string[]
+	future: string[]
+	present: string
+	lastChangeAt: number
+}
+
+/** Snapshots kept behind the present one. */
+export const HISTORY_LIMIT = 50
+
+/** Changes closer than this merge into one step (a word typed, a drag). */
+export const HISTORY_COALESCE_MS = 700
+
+export function createHistory(snapshot: string): EditorHistory {
+	return { past: [], future: [], present: snapshot, lastChangeAt: 0 }
+}
+
+/** No change merges into a step closed with this timestamp. */
+const CLOSED_STEP = Number.NEGATIVE_INFINITY
+
+/**
+ * Records the content after a change. A change within the coalescing window
+ * of the previous one extends its step instead of opening a new one; the
+ * oldest steps fall off past the limit. A discrete change (a deletion, a
+ * move) always is a step of its own, so one undo reverts exactly it.
+ */
+export function recordChange(
+	history: EditorHistory,
+	snapshot: string,
+	now: number,
+	isDiscrete = false,
+): void {
+	if (snapshot === history.present) return
+	const isNewStep =
+		isDiscrete ||
+		now - history.lastChangeAt >= HISTORY_COALESCE_MS ||
+		history.past.length === 0
+	if (isNewStep) {
+		history.past.push(history.present)
+		if (history.past.length > HISTORY_LIMIT) history.past.shift()
+	}
+	history.present = snapshot
+	history.future = []
+	history.lastChangeAt = isDiscrete ? CLOSED_STEP : now
+}
+
+/** Steps back; the snapshot to restore, or `null` at the oldest one. */
+export function undoChange(history: EditorHistory): string | null {
+	const previous = history.past.pop()
+	if (previous === undefined) return null
+	history.future.push(history.present)
+	history.present = previous
+	history.lastChangeAt = 0
+	return previous
+}
+
+/** Steps forward again; `null` when nothing was undone. */
+export function redoChange(history: EditorHistory): string | null {
+	const next = history.future.pop()
+	if (next === undefined) return null
+	history.past.push(history.present)
+	history.present = next
+	history.lastChangeAt = 0
+	return next
+}