@antelopejs/dms-mailing 0.3.3 → 0.4.0

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

@@ -0,0 +1,185 @@
+import type { TemplateRow, TemplateStatus } from '../types/mailing'
+
+export type LifecycleAction = 'unpublish' | 'archive' | 'restore'
+
+export interface LifecycleButton {
+	action: LifecycleAction
+	icon: string
+}
+
+const BUTTONS: Record<LifecycleAction, LifecycleButton> = {
+	unpublish: { action: 'unpublish', icon: 'i-ph-eye-slash' },
+	archive: { action: 'archive', icon: 'i-ph-archive' },
+	restore: { action: 'restore', icon: 'i-ph-arrow-u-up-left' },
+}
+
+const TRANSITIONS: Record<TemplateStatus, LifecycleAction[]> = {
+	draft: ['archive'],
+	live: ['unpublish', 'archive'],
+	archived: ['restore'],
+}
+
+export function lifecycleActions(status: TemplateStatus): LifecycleButton[] {
+	return (TRANSITIONS[status] ?? []).map((action) => BUTTONS[action])
+}
+
+/** What an action stamps on the template besides its status, at `now`. */
+const STAMPS: Partial<
+	Record<LifecycleAction, (now: Date) => Partial<TemplateRow>>
+> = {
+	unpublish: (now) => ({ unpublishedAt: now.toISOString() }),
+}
+
+/**
+ * The template once `action` went through: its new status and the moments
+ * the editor's notice dates, as the server recorded them.
+ */
+export function afterLifecycle(
+	template: TemplateRow,
+	action: LifecycleAction,
+	status: TemplateStatus,
+	now = new Date(),
+): TemplateRow {
+	return { ...template, ...STAMPS[action]?.(now), status }
+}
+
+/** Publishing is refused from `archived`; restore the template first. */
+export function canPublish(status: TemplateStatus): boolean {
+	return status !== 'archived'
+}
+
+/** Where the draft's autosave stands. */
+export type SaveStatus = 'idle' | 'saving' | 'error' | 'conflict'
+
+/** What decides whether "Publish changes" (and ⌘↵) can run. */
+export interface PublishableInput {
+	status: TemplateStatus
+	changeCount: number
+	dirty: number
+}
+
+/**
+ * Whether publishing would do anything: a live template needs a change; a
+ * draft or unpublished one goes live; an archived one must be restored first.
+ */
+export function isPublishable(input: PublishableInput): boolean {
+	if (!canPublish(input.status)) return false
+	if (input.status !== 'live') return true
+	return input.changeCount > 0 || input.dirty > 0
+}
+
+/** The status a template reads as: a draft that was once live is unpublished. */
+export type StatusKey = TemplateStatus | 'unpublished'
+
+export function statusKeyOf(
+	status: TemplateStatus,
+	version: number,
+): StatusKey {
+	return status === 'draft' && version > 0 ? 'unpublished' : status
+}
+
+export type NoticeKind =
+	| 'conflict'
+	| 'save_error'
+	| 'unpublished'
+	| 'live_changes'
+	| 'live_clean'
+	| 'never_published'
+
+export type NoticeAction =
+	'compare' | 'discard' | 'reload' | 'overwrite' | 'retry' | 'republish'
+
+export type NoticeTone = 'primary' | 'warning' | 'error'
+
+/** The band under the toolbar: what it says, its tone and its actions. */
+export interface EditorNotice {
+	kind: NoticeKind
+	tone: NoticeTone
+	actions: NoticeAction[]
+}
+
+export interface NoticeInput {
+	status: TemplateStatus
+	version: number
+	changeCount: number
+	saveStatus: SaveStatus
+}
+
+const DRAFT_ACTIONS: NoticeAction[] = ['compare', 'discard']
+
+const SAVE_NOTICES: Partial<Record<SaveStatus, EditorNotice>> = {
+	conflict: {
+		kind: 'conflict',
+		tone: 'error',
+		actions: ['reload', 'overwrite'],
+	},
+	error: { kind: 'save_error', tone: 'error', actions: ['retry'] },
+}
+
+function contentNotice(input: NoticeInput): EditorNotice | null {
+	const draftActions = input.changeCount > 0 ? DRAFT_ACTIONS : []
+	if (input.version === 0)
+		return input.changeCount > 0
+			? { kind: 'never_published', tone: 'primary', actions: [] }
+			: null
+	if (input.status === 'live')
+		return input.changeCount > 0
+			? { kind: 'live_changes', tone: 'primary', actions: draftActions }
+			: { kind: 'live_clean', tone: 'primary', actions: [] }
+	if (input.status === 'draft')
+		return {
+			kind: 'unpublished',
+			tone: 'warning',
+			actions: [...draftActions, 'republish'],
+		}
+	return null
+}
+
+/**
+ * Which notice the editor shows: a draft that could not be saved first, then
+ * the template's reading — nothing published yet, live, or unpublished.
+ */
+export function noticeFor(input: NoticeInput): EditorNotice | null {
+	return SAVE_NOTICES[input.saveStatus] ?? contentNotice(input)
+}
+
+/** The moment a notice dates: the unpublish, else the last publication. */
+export function noticeMomentOf(
+	kind: NoticeKind,
+	template: Pick<TemplateRow, 'publishedAt' | 'unpublishedAt' | 'updatedAt'>,
+): string | null | undefined {
+	if (kind !== 'unpublished') return template.publishedAt
+	return template.unpublishedAt ?? template.updatedAt
+}
+
+const DATE_FORMAT: Intl.DateTimeFormatOptions = {
+	month: 'short',
+	day: 'numeric',
+}
+const TIME_FORMAT: Intl.DateTimeFormatOptions = {
+	hour: '2-digit',
+	minute: '2-digit',
+	hour12: false,
+}
+
+/** A publication moment, split for "published Sep 29 at 09:14". */
+export interface PublishedMoment {
+	date: string
+	time: string
+}
+
+export function publishedMoment(
+	iso: string | null | undefined,
+	locale: string,
+): PublishedMoment | null {
+	if (!iso) return null
+	const date = new Date(iso)
+	if (Number.isNaN(date.getTime())) return null
+	return {
+		date: date.toLocaleDateString(locale, DATE_FORMAT),
+		time: date.toLocaleTimeString(locale, TIME_FORMAT),
+	}
+}
+
+/** The subject length mail clients show in full; past it, a warning tint. */
+export const SUBJECT_RECOMMENDED_LENGTH = 60

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

@@ -5,8 +5,19 @@ export interface LocalePresence {
 
 const LOCALE_LIST_SEPARATOR = ','
 
+/** Base look of a locale chip, on a card, in a table cell or a review box. */
+export const LOCALE_CHIP_CLASS =
+	'inline-flex h-[18px] items-center rounded px-1.5 font-mono text-[10.5px] font-semibold uppercase leading-none'
+
+/** A locale the template carries. */
+export const LOCALE_CHIP_PRESENT_CLASS = 'bg-elevated text-toned'
+
+/** A workspace locale the template lacks: its recipients get the fallback. */
+export const LOCALE_CHIP_MISSING_CLASS =
+	'text-warning border-warning/60 border border-dashed'
+
 /** Reads the `locales` column, whose format is a comma-separated code list. */
-export function parseLocaleList(value: string | undefined): string[] {
+export function parseLocaleList(value: string | undefined | null): string[] {
 	return (value ?? '')
 		.split(LOCALE_LIST_SEPARATOR)
 		.map((code) => code.trim())
@@ -32,10 +43,104 @@ export function localeCoverage(
  * locale is missing.
  */
 export function localeBadges(
-	stored: string | undefined,
+	stored: string | undefined | null,
+	codes: string[],
+): LocalePresence[] {
+	const present = parseLocaleList(stored)
+	if (!present.length) return []
+	return localeCoverage(present, codes)
+}
+
+/**
+ * Chips for a list of codes: the workspace ones in the workspace order, then
+ * any the template carries that the workspace no longer offers.
+ */
+export function localeChips(
+	stored: string | undefined | null,
 	codes: string[],
 ): LocalePresence[] {
 	const present = parseLocaleList(stored)
 	if (!present.length) return []
+	const extra = present.filter((code) => !codes.includes(code))
+	return [
+		...localeCoverage(present, codes),
+		...extra.map((code) => ({ code, present: true })),
+	]
+}
+
+/** The workspace locales `present` lacks. */
+export function missingLocales(present: string[], codes: string[]): string[] {
 	return localeCoverage(present, codes)
+		.filter((entry) => !entry.present)
+		.map((entry) => entry.code)
+}
+
+export function localeChipClass(present: boolean): string {
+	return `${LOCALE_CHIP_CLASS} ${present ? LOCALE_CHIP_PRESENT_CLASS : LOCALE_CHIP_MISSING_CLASS}`
+}
+
+const DEFAULT_FALLBACK_LOCALE = 'en'
+const LOCALE_PART_SEPARATOR = /[-_]/
+
+/** The base language of a locale code: "fr-BE" and "FR" both read "fr". */
+export function localeLanguage(code: string): string {
+	const [language = code] = code.split(LOCALE_PART_SEPARATOR)
+	return language.toLowerCase()
+}
+
+/**
+ * The locale a send renders, as the server picks it: the requested one
+ * (regardless of case, or by its base language), else the tenant fallback,
+ * else English, else the first locale the content carries.
+ */
+export function pickLocale(
+	available: string[],
+	wanted: string | undefined,
+	fallback: string,
+): string {
+	const byCode = new Map(available.map((code) => [code.toLowerCase(), code]))
+	const requested = wanted ? [wanted, localeLanguage(wanted)] : []
+	const candidates = [
+		...requested,
+		fallback,
+		DEFAULT_FALLBACK_LOCALE,
+		available[0],
+	]
+	const match = candidates
+		.map((code) => (code ? byCode.get(code.toLowerCase()) : undefined))
+		.find((code): code is string => Boolean(code))
+	return match ?? DEFAULT_FALLBACK_LOCALE
+}
+
+const LANGUAGE_NAMES: Intl.DisplayNamesOptions = { type: 'language' }
+
+/**
+ * A language named in the interface's language, capitalised like a label
+ * ("Anglais" for `en` in French); absent when the runtime does not know it.
+ */
+export function languageName(
+	code: string,
+	uiLocale: string,
+): string | undefined {
+	try {
+		const name = new Intl.DisplayNames([uiLocale], LANGUAGE_NAMES).of(code)
+		if (!name || name.toLowerCase() === code.toLowerCase()) return undefined
+		return name.charAt(0).toLocaleUpperCase(uiLocale) + name.slice(1)
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * A locale as a picker lists it, in the interface's language: "French (FR)".
+ * `fallbackName` stands in for a language the runtime cannot name.
+ */
+export function languageLabel(
+	code: string,
+	uiLocale: string,
+	fallbackName?: string,
+): string {
+	const upper = code.toUpperCase()
+	const name = languageName(code, uiLocale) ?? fallbackName
+	return name ? `${name} (${upper})` : upper
 }

package/frontend-vue/app/utils/overview-setup.ts

@@ -0,0 +1,83 @@
+import { SETTINGS_PATH, TEMPLATES_PATH } from './pages'
+
+export type SetupStepId = 'provider' | 'sender' | 'publish' | 'test'
+
+export type SetupStepState = 'done' | 'current' | 'todo'
+
+/** What `GET /metrics/setup` answers. */
+export interface SetupFacts {
+	isProviderConnected: boolean
+	isSenderSet: boolean
+	liveTemplateCount: number
+	hasTestSend: boolean
+}
+
+export interface SetupStepDefinition {
+	id: SetupStepId
+	/**
+	 * Where the step is done; absent when it is not done in the app (the
+	 * provider is set in the project's configuration).
+	 */
+	to?: string
+	isDone: (facts: SetupFacts) => boolean
+}
+
+export interface SetupStep {
+	id: SetupStepId
+	number: number
+	to?: string
+	state: SetupStepState
+}
+
+/** A settings form section, by the id the DMS form gives its anchor. */
+const SETTINGS_SECTION = `${SETTINGS_PATH}#dms-form-content-section-`
+
+export const SETUP_STEPS: SetupStepDefinition[] = [
+	{
+		id: 'provider',
+		isDone: (facts) => facts.isProviderConnected,
+	},
+	{
+		id: 'sender',
+		to: `${SETTINGS_SECTION}sender`,
+		isDone: (facts) => facts.isSenderSet,
+	},
+	{
+		id: 'publish',
+		to: TEMPLATES_PATH,
+		isDone: (facts) => facts.liveTemplateCount > 0,
+	},
+	{
+		id: 'test',
+		to: TEMPLATES_PATH,
+		isDone: (facts) => facts.hasTestSend,
+	},
+]
+
+/**
+ * The first-run checklist: each step done or not from what the workspace
+ * holds, the first one left marked current.
+ */
+export function setupSteps(facts: SetupFacts): SetupStep[] {
+	const done = SETUP_STEPS.map((step) => step.isDone(facts))
+	const current = done.indexOf(false)
+	return SETUP_STEPS.map((step, index) => ({
+		id: step.id,
+		number: index + 1,
+		to: step.to,
+		state: done[index] ? 'done' : index === current ? 'current' : 'todo',
+	}))
+}
+
+/**
+ * The dashboard only makes sense once e-mail can leave and a template is live:
+ * a draft alone sends nothing.
+ */
+export function needsSetup(facts: SetupFacts): boolean {
+	return !facts.isProviderConnected || facts.liveTemplateCount === 0
+}
+
+/** Every step of the checklist is done: nothing left to resume. */
+export function isSetupComplete(facts: SetupFacts): boolean {
+	return SETUP_STEPS.every((step) => step.isDone(facts))
+}

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

@@ -0,0 +1,5 @@
+/** The module's pages, as `navigateDms` and links reach them. */
+export const TEMPLATES_PATH = '/modules/mailing/templates'
+export const SENDS_PATH = '/modules/mailing/sends'
+export const SETTINGS_PATH = '/modules/mailing/settings'
+export const SUPPRESSIONS_PATH = '/modules/mailing/suppressions'

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

@@ -2,15 +2,37 @@ import type { Block, LocaleContent, TemplateContent } from '../types/mailing'
 import { splitTokens } from './tokens'
 
 const TOKEN_FIELDS = ['text', 'value', 'href', 'label', 'alt', 'imageUrl']
+const PATH_SEPARATOR = '.'
+const ARRAY_SUFFIX = '[]'
+const RESERVED_SEGMENTS = ['__proto__', 'constructor', 'prototype']
+
+export const UNSUBSCRIBE_URL_PATH = 'unsubscribeUrl'
+export const PREFERENCES_URL_PATH = 'preferencesUrl'
+
+/**
+ * The footer links' URLs, passed by the caller at send time. The content
+ * declares them itself (`utils/system-variables.ts`), so they never show as
+ * undeclared; the backend keeps them out of `detectedVariables` the same way.
+ */
+export const SYSTEM_PATHS = [UNSUBSCRIBE_URL_PATH, PREFERENCES_URL_PATH]
+
+/**
+ * A path cut after each separator ("order." + "number"): where a narrow
+ * column may wrap it, rather than in the middle of a name.
+ */
+export function pathBreakSegments(path: string): string[] {
+	return path
+		.split(PATH_SEPARATOR)
+		.map((segment, index, segments) =>
+			index < segments.length - 1 ? `${segment}${PATH_SEPARATOR}` : segment,
+		)
+}
 
 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)
+		return typeof value === 'string' ? textPaths(value) : []
 	})
 }
 
@@ -46,13 +68,8 @@ export function collectPaths(
 	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[] {
+/** The variable paths a text references through `{{path}}` tokens. */
+export function textPaths(text: string): string[] {
 	return splitTokens(text)
 		.filter((part) => part.kind === 'token')
 		.map((part) => part.value)
@@ -69,10 +86,6 @@ function pathsInLocale(locale: LocaleContent): string[] {
 /**
  * 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'>,
@@ -82,3 +95,26 @@ export function collectContentPaths(
 		...new Set(paths.filter((path) => path && !SYSTEM_PATHS.includes(path))),
 	].sort()
 }
+
+function readSegment(current: unknown, segment: string): unknown {
+	if (current === null || typeof current !== 'object') return undefined
+	if (RESERVED_SEGMENTS.includes(segment)) return undefined
+	return (current as Record<string, unknown>)[segment]
+}
+
+/**
+ * Reads `path` (`order.total`, `order.lines[]`) in `data`, the way the backend
+ * engine does; `undefined` when any segment is missing.
+ */
+export function readPath(data: unknown, path: string): unknown {
+	const trimmed = path.trim()
+	const normalized = trimmed.endsWith(ARRAY_SUFFIX)
+		? trimmed.slice(0, -ARRAY_SUFFIX.length)
+		: trimmed
+	return normalized.split(PATH_SEPARATOR).reduce<unknown>(readSegment, data)
+}
+
+/** Whether `value` counts as provided: neither `undefined` nor `null`. */
+export function isPresent(value: unknown): boolean {
+	return value !== undefined && value !== null
+}

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

@@ -1,23 +1,63 @@
-/**
- * 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
+const MINUTE_MS = 60_000
+const DAY_MS = 86_400_000
+const PRESET_KEY_SEPARATOR = /-/g
+const KEY_SEPARATOR = '_'
+
+/** Hour and minute on a 24-hour clock, the way the cards stamp "updated 14:32". */
+export const CLOCK_FORMAT: Intl.DateTimeFormatOptions = {
+	hour: '2-digit',
+	minute: '2-digit',
+	hourCycle: 'h23',
+}
+
+/** The i18n key of a preset's short segmented label ("24H", "7D"…). */
+export function presetShortLabelKey(preset: string): string {
+	return `dms_mailing.period.short.${preset.replace(PRESET_KEY_SEPARATOR, KEY_SEPARATOR)}`
+}
+
+/** Whole minutes elapsed since `iso`; 0 for a missing or future date. */
+export function minutesSince(
+	iso: string | null | undefined,
+	now: Date,
+): number {
+	if (!iso) return 0
+	const elapsed = now.getTime() - new Date(iso).getTime()
+	return elapsed > 0 ? Math.floor(elapsed / MINUTE_MS) : 0
+}
+
+/** Formats a date as HH:MM in `locale`. */
+export function formatClock(value: Date | string, locale: string): string {
+	return new Date(value).toLocaleTimeString(locale, CLOCK_FORMAT)
+}
+
+/** Whether `at` falls within the next 24 hours: "tonight" rather than a date. */
+export function isWithinADay(at: Date | string, now: Date): boolean {
+	const delay = new Date(at).getTime() - now.getTime()
+	return delay >= 0 && delay < DAY_MS
+}
+
+/** Retention presets of the settings form, in days. */
+export const RETENTION_PRESETS = [30, 90, 365]
+export const RETENTION_CUSTOM = 'custom'
+export const MIN_RETENTION_DAYS = 1
+export const MAX_RETENTION_DAYS = 3650
+
+export type RetentionChoice = string
+
+/** The segment a retention shows: its preset, else "custom". */
+export function retentionChoice(
+	days: number | null | undefined,
+): RetentionChoice {
+	return days && RETENTION_PRESETS.includes(days)
+		? String(days)
+		: RETENTION_CUSTOM
+}
+
+/** A typed retention brought back between 1 day and 10 years, whole days. */
+export function clampRetention(days: number): number {
+	if (!Number.isFinite(days)) return MIN_RETENTION_DAYS
+	return Math.min(
+		MAX_RETENTION_DAYS,
+		Math.max(MIN_RETENTION_DAYS, Math.round(days)),
+	)
 }