@antelopejs/dms-mailing 0.6.1 → 0.7.0

package/frontend-vue/app/components/TemplateGallery.vue

@@ -1,4 +1,8 @@
 <script setup lang="ts">
+// Imported rather than resolved by name: every module component is a lazy
+// chunk, and the grid would first render its "new template" tile alone,
+// then move it as the cards arrive.
+import TemplateCard from './TemplateCard.vue'
 import { useTemplateCategories } from '../composables/useTemplateCategories'
 import { useEventListener } from '@vueuse/core'
 import {
@@ -50,7 +54,8 @@ const props = defineProps<TemplateGalleryProps>()
 const { t } = useI18n()
 const overlays = useTemplateDrawer()
 
-const { categories } = useTemplateCategories()
+const { categories, isAnswered: areCategoriesAnswered } =
+	useTemplateCategories()
 const overview = useTemplatesOverview()
 const total = useTemplateTotal()
 
@@ -121,8 +126,20 @@ const search = computed(() => searchTermOf(props.context.query))
 const narrowed = computed(() => isNarrowed(props.context.query))
 const hasNoItems = computed(() => !props.context.items.length)
 
+/**
+ * The cards draw their category group and their figures from reads of their
+ * own: until both answered (a client navigation reads them in the browser),
+ * the cards would come under "Uncategorised", then move to their group.
+ */
+const areCardsReady = computed(
+	() =>
+		(!isGrouped.value || areCategoriesAnswered.value) &&
+		Boolean(overview.data.value || overview.error.value),
+)
+
 const STATE_RULES: StateRule[] = [
 	['loading', () => props.context.loading && hasNoItems.value],
+	['loading', () => !hasNoItems.value && !areCardsReady.value],
 	[
 		'loading',
 		() => hasNoItems.value && !narrowed.value && templateCount.value === null,
@@ -218,24 +235,47 @@ useEventListener(
 
 <template>
 	<div class="flex flex-col gap-6 p-4">
-		<div
+		<!-- Laid out as a group of cards: the heading, the thumbnail and the
+		     card's three lines at their own heights (a zero-width space keeps a
+		     text line's height), so the cards replace it without moving. -->
+		<section
 			v-if="state === 'loading'"
-			class="grid grid-cols-[repeat(auto-fill,minmax(272px,1fr))] gap-4"
+			class="flex flex-col gap-3"
 			aria-busy="true"
+			data-gallery-skeleton
 		>
-			<DmsCard
-				v-for="index in SKELETON_CARDS"
-				:key="index"
-				:padded="false"
-				class="overflow-hidden"
-			>
-				<USkeleton class="h-[172px] w-full rounded-none" />
-				<div class="flex flex-col gap-2 p-3.5">
-					<USkeleton class="h-3 w-3/5" />
-					<USkeleton class="h-2.5 w-2/5" />
-				</div>
-			</DmsCard>
-		</div>
+			<div v-if="isGrouped" class="flex items-center gap-2 text-[13px]">
+				<USkeleton class="size-4" />
+				<USkeleton class="h-3 w-24" />
+				&#8203;
+			</div>
+			<div class="grid grid-cols-[repeat(auto-fill,minmax(272px,1fr))] gap-4">
+				<DmsCard
+					v-for="index in SKELETON_CARDS"
+					:key="index"
+					:padded="false"
+					class="flex flex-col overflow-hidden"
+				>
+					<USkeleton class="h-[172px] w-full rounded-none" />
+					<div
+						class="border-default flex flex-1 flex-col gap-1.5 border-t px-3.5 pb-3 pt-3"
+					>
+						<div class="flex h-6 items-center">
+							<USkeleton class="h-3.5 w-3/5" />
+						</div>
+						<div class="flex h-[18px] items-center">
+							<USkeleton class="h-2.5 w-2/5" />
+						</div>
+						<div
+							class="border-default mt-1 flex items-center gap-3 border-t pt-2 font-mono text-[11.5px]"
+						>
+							<USkeleton class="h-2.5 w-1/2" />
+							&#8203;
+						</div>
+					</div>
+				</DmsCard>
+			</div>
+		</section>
 
 		<MailingStarterGallery
 			v-else-if="state === 'first_run'"
@@ -308,7 +348,7 @@ useEventListener(
 					<span class="bg-(--ui-border) ml-2 h-px flex-1" />
 				</div>
 				<div class="grid grid-cols-[repeat(auto-fill,minmax(272px,1fr))] gap-4">
-					<MailingTemplateCard
+					<TemplateCard
 						v-for="template in group.items"
 						:key="template._id"
 						:template="template"

package/frontend-vue/app/components/TemplatePreviewFrame.vue

@@ -27,7 +27,12 @@ interface TemplatePreviewFrameProps {
 	width: number
 	scale?: number
 	refreshKey?: number
-	/** Fetches only once the frame scrolls into view (galleries). */
+	/**
+	 * Fetches only once the frame scrolls into view (galleries). The frame then
+	 * waits on a blank sheet rather than a skeleton: the gallery's own skeleton
+	 * covers its first load, and a thumbnail starting to load as it scrolls into
+	 * view would bring a skeleton back.
+	 */
 	lazy?: boolean
 	/** Accessible name of the frame. */
 	label?: string
@@ -61,14 +66,15 @@ const props = withDefaults(defineProps<TemplatePreviewFrameProps>(), {
 const emit = defineEmits<{ resolved: [PreviewResponse] }>()
 
 const api = useMailingApi()
-const { locale: uiLocale } = useI18n()
+const { t, locale: uiLocale } = useI18n()
 
 const readStarterPreview = useStarterPreviewRead(
 	() => props.starterId,
 	() => props.locale ?? uiLocale.value,
 )
 const fetchedHtml = ref('')
-const loading = ref(false)
+/** The last read failed: the frame shows its fallback, not a skeleton for ever. */
+const hasFailed = ref(false)
 const height = ref(FALLBACK_HEIGHT)
 const frame = ref<HTMLIFrameElement | null>(null)
 const box = ref<HTMLElement | null>(null)
@@ -87,6 +93,19 @@ function withoutScroll(html: string): string {
 
 const shownHtml = computed(() => withoutScroll(props.html ?? fetchedHtml.value))
 
+const hasSource = computed(
+	() =>
+		props.html !== undefined || Boolean(props.starterId || props.templateId),
+)
+/**
+ * Waiting for the HTML: from the first render (a server render, the debounce
+ * and a lazy frame not yet in view included), so the placeholder holds its
+ * place without a gap between it and the content.
+ */
+const isWaiting = computed(
+	() => !shownHtml.value && hasSource.value && !hasFailed.value,
+)
+
 useIntersectionObserver(box, ([entry]) => {
 	if (entry?.isIntersecting) isVisible.value = true
 })
@@ -110,15 +129,14 @@ async function fetchTemplate(templateId: string): Promise<void> {
 async function load(): Promise<void> {
 	if (props.html !== undefined || !isVisible.value) return
 	if (!props.starterId && !props.templateId) return
-	loading.value = true
 	try {
 		await (props.starterId
 			? fetchStarter()
 			: fetchTemplate(props.templateId as string))
+		hasFailed.value = false
 	} catch {
 		fetchedHtml.value = ''
-	} finally {
-		loading.value = false
+		hasFailed.value = true
 	}
 }
 
@@ -172,12 +190,10 @@ const frameStyle = computed(() => ({
 
 <template>
 	<div ref="box" class="relative overflow-hidden" :style="boxStyle">
-		<USkeleton
-			v-if="!shownHtml && (loading || !isVisible)"
-			class="absolute inset-0 size-full"
-		/>
+		<!-- Rendered only with HTML: an empty frame loads too, and measuring it
+		     would shrink the box to a few pixels. -->
 		<iframe
-			v-show="shownHtml"
+			v-if="shownHtml"
 			ref="frame"
 			:srcdoc="shownHtml"
 			sandbox="allow-same-origin"
@@ -191,5 +207,19 @@ const frameStyle = computed(() => ({
 			:style="frameStyle"
 			@load="measure"
 		/>
+		<div
+			v-else-if="isWaiting && lazy"
+			class="absolute inset-0 bg-white"
+			data-preview-placeholder
+		/>
+		<USkeleton v-else-if="isWaiting" class="absolute inset-0 size-full" />
+		<div
+			v-else-if="hasFailed"
+			class="bg-elevated text-dimmed absolute inset-0 flex flex-col items-center justify-center gap-1.5 text-[12px]"
+			data-preview-fallback
+		>
+			<UIcon name="i-ph-image-broken" class="size-5" aria-hidden="true" />
+			{{ t('dms_mailing.common.preview_unavailable') }}
+		</div>
 	</div>
 </template>

package/frontend-vue/app/components/editor/EditorTemplatePane.vue

@@ -2,7 +2,6 @@
 import { computed, ref, watch } from 'vue'
 import type { TemplateDetails } from '../../composables/useMailingApi'
 import { useEditorContext } from '../../composables/useEditorContext'
-import { useLocalizedDefaults } from '../../composables/useLocalizedDefaults'
 
 const KEY = 'dms_mailing.editor.template_tab'
 const NO_CATEGORY = '__none__'
@@ -10,7 +9,6 @@ const NO_CATEGORY = '__none__'
 const { t } = useI18n()
 const toast = useToast()
 const { editor, session, actions, templateId } = useEditorContext()
-const localized = useLocalizedDefaults()
 
 const template = computed(() => session.state.template)
 const name = ref(template.value.name)
@@ -22,7 +20,7 @@ watch(
 
 const categoryItems = computed(() => [
 	{ value: NO_CATEGORY, label: t(`${KEY}.no_category`), icon: 'i-ph-minus' },
-	...localized.categories(session.state.categories).map((category) => ({
+	...session.state.categories.map((category) => ({
 		value: category.id,
 		label: category.label,
 		icon: category.icon,

package/frontend-vue/app/components/editor/EditorTitle.vue

@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { useEditorContext } from '../../composables/useEditorContext'
-import { useLocalizedDefaults } from '../../composables/useLocalizedDefaults'
 import { TEMPLATES_PATH } from '../../utils/pages'
 import type { StatusKey } from '../../utils/lifecycle'
 
@@ -14,7 +13,6 @@ const STATUS_TONES: Record<StatusKey, string> = {
 const SEPARATOR = ' · '
 
 const { t } = useI18n()
-const localized = useLocalizedDefaults()
 const { editor, session } = useEditorContext()
 
 const template = computed(() => session.state.template)
@@ -38,11 +36,7 @@ const statusLabel = computed(() => {
 const categoryLabel = computed(() => {
 	const id = template.value.category
 	if (!id) return t('dms_mailing.editor.toolbar.uncategorised')
-	return (
-		localized
-			.categories(session.state.categories)
-			.find((entry) => entry.id === id)?.label ?? id
-	)
+	return session.state.categories.find((entry) => entry.id === id)?.label ?? id
 })
 </script>
 

package/frontend-vue/app/composables/useLocalizedDefaults.ts

@@ -1,17 +1,15 @@
-import type { StarterSummary, TemplateCategory } from '../types/mailing'
-import { localizeCategories, type OptionalTranslate } from '../utils/categories'
-import { localizeStarters } from '../utils/starters'
+import type { StarterSummary } from '../types/mailing'
+import { localizeStarters, type OptionalTranslate } from '../utils/starters'
 
 /**
- * What the module ships by default (starters, the first categories) named in
- * the interface's language, without touching what is stored.
+ * The starters the module ships, named in the interface's language. Template
+ * names and category labels are localized fields the server reads in the
+ * interface's language.
  */
 export function useLocalizedDefaults() {
 	const { t, te } = useI18n()
 	const translate: OptionalTranslate = (key) => (te(key) ? t(key) : undefined)
 	return {
-		categories: (list: TemplateCategory[]) =>
-			localizeCategories(list, translate),
 		starters: (list: StarterSummary[]) => localizeStarters(list, translate),
 	}
 }

package/frontend-vue/app/composables/useMailingApi.ts

@@ -192,14 +192,14 @@ export function useMailingApi() {
 	return {
 		webhookTest: () =>
 			post<WebhookTestResult>(mailingPath('settings', 'webhook-test'), {}),
+		/** Renames in the interface's language, the other languages kept. */
 		saveTemplateDetails: (id: string, details: TemplateDetails) =>
-			$authFetch<unknown>(mailingPath('tables', 'templates', 'edit'), {
+			$authFetch<unknown>(mailingPath('templates', id, 'details'), {
 				method: 'PUT',
-				query: { id },
 				body: details,
 			}),
 		createTemplate: (input: CreateTemplateInput) =>
-			post<string[]>(mailingPath('tables', 'templates', 'new'), input),
+			post<TemplateRow>(mailingPath('tables', 'templates', 'new'), input),
 		saveContent: (id: string, input: SaveContentInput) =>
 			$authFetch<SavedResponse>(mailingPath('templates', id, 'content'), {
 				method: 'POST',

package/frontend-vue/app/composables/useMailingReads.ts

@@ -30,7 +30,7 @@ import type {
  * `useMailingApi`.
  */
 
-/** The e-mail provider the page header names; nothing read while `enabled` is false. */
+/** The e-mail provider the page toolbar names; nothing read while `enabled` is false. */
 export function useProviderInfo(
 	enabled: MaybeRefOrGetter<boolean>,
 ): ApiDataResult<ProviderInfo> {
@@ -66,7 +66,7 @@ export function useCategoryUsage(): ApiDataResult<CategoryUsageResponse> {
 	)
 }
 
-/** The tenant's template categories, as stored. */
+/** The tenant's template categories, labelled in the interface's language. */
 export function useStoredCategories(): ApiDataResult<CategoriesResponse> {
 	return useApiData<CategoriesResponse>(mailingPath('templates', 'categories'))
 }

package/frontend-vue/app/composables/useTemplateCategories.ts

@@ -1,16 +1,17 @@
-import { useLocalizedDefaults } from './useLocalizedDefaults'
 import { useStoredCategories } from './useMailingReads'
 
 /**
- * The tenant's template categories, named in the interface's language: one
- * read the components showing them share (a table's category cells, the
- * gallery), none when it failed.
+ * The tenant's template categories, labelled in the interface's language by
+ * the server: one read the components showing them share (a table's category
+ * cells, the gallery), none when it failed.
+ * `isAnswered` turns true once the read has answered, with the categories or
+ * a failure.
  */
 export function useTemplateCategories() {
-	const localized = useLocalizedDefaults()
 	const { data, error } = useStoredCategories()
 	const categories = computed(() =>
-		localized.categories(error.value ? [] : (data.value?.categories ?? [])),
+		error.value ? [] : (data.value?.categories ?? []),
 	)
-	return { categories }
+	const isAnswered = computed(() => Boolean(data.value || error.value))
+	return { categories, isAnswered }
 }

package/frontend-vue/app/types/mailing.ts

@@ -271,12 +271,26 @@ export const SEND_STATUSES: SendStatus[] = [
 /** What a provider reports: a suppressed send never reached one. */
 export type SendEventType = Exclude<SendStatus, 'suppressed'>
 
+/** A text written once per language: `{ en: 'Orders', fr: 'Commandes' }`. */
+export type LocalizedText = Record<string, string>
+
+/** A template category as one reader sees it: its label in their language. */
 export interface TemplateCategory {
 	id: string
 	label: string
 	icon: string
 }
 
+/**
+ * A template category as the settings store it, read and written whole by
+ * the settings form: its label in every language.
+ */
+export interface StoredCategory {
+	id: string
+	label: LocalizedText
+	icon: string
+}
+
 export interface TemplateRow {
 	_id: string
 	slug: string
@@ -521,6 +535,10 @@ export interface FunnelStep {
 	rate: number | null
 	/** `false` when nothing reports the events this step counts. */
 	isMeasured?: boolean
+	/** The count over the comparison window; absent with the comparison off. */
+	previousCount?: number
+	/** The change of the count, in percent; absent from an empty comparison. */
+	delta?: number
 }
 
 export interface ProviderInfo {

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

@@ -1,8 +1,33 @@
-import type { TemplateCategory } from '../types/mailing'
+import type {
+	LocalizedText,
+	StoredCategory,
+	TemplateCategory,
+} from '../types/mailing'
 
 const ID_SEPARATOR = '-'
 
-export function serializeCategories(categories: TemplateCategory[]): string {
+/** The language a localized label falls back to, as the server reads it. */
+export const FALLBACK_LOCALE = 'en'
+
+/** A label in `locale`, else in the fallback language. */
+export function labelIn(label: LocalizedText, locale: string): string {
+	return label[locale] ?? label[FALLBACK_LOCALE] ?? ''
+}
+
+/**
+ * `label` with `value` written in `locale`: the other languages are kept,
+ * and the fallback one gets the value while it has none, so a category
+ * added in another language still reads in every language.
+ */
+export function withLabelIn(
+	label: LocalizedText,
+	locale: string,
+	value: string,
+): LocalizedText {
+	return { [FALLBACK_LOCALE]: value, ...label, [locale]: value }
+}
+
+export function serializeCategories(categories: StoredCategory[]): string {
 	return JSON.stringify(categories)
 }
 
@@ -34,7 +59,9 @@ const ICON_PREFIX = 'i-ph-'
  * The icon a new category starts with: the first one of the picker no
  * category uses yet, so a new row never looks like an existing one.
  */
-export function newCategoryIcon(categories: TemplateCategory[]): string {
+export function newCategoryIcon(
+	categories: Pick<TemplateCategory, 'icon'>[],
+): string {
 	const used = new Set(categories.map((category) => category.icon))
 	return CATEGORY_ICONS.find((icon) => !used.has(icon)) ?? DEFAULT_CATEGORY_ICON
 }
@@ -47,12 +74,30 @@ export function iconName(icon: string): string {
 }
 
 /**
- * A row of the categories editor. `isNew` rows were added in this edit: their
- * id follows the label until the form is saved, then stays fixed for good.
+ * A row of the categories editor: `label` is the text of the language being
+ * edited, `labels` what the row stores in every language. `isNew` rows were
+ * added in this edit: their id follows the label until the form is saved,
+ * then stays fixed for good.
  */
 export interface EditableCategory extends TemplateCategory {
 	key: string
 	isNew: boolean
+	labels: LocalizedText
+}
+
+/** The rows of `categories`, each label shown in `locale`. */
+export function toEditableRows(
+	categories: StoredCategory[],
+	locale: string,
+	keyOf: () => string,
+): EditableCategory[] {
+	return categories.map((category) => ({
+		...category,
+		label: labelIn(category.label, locale),
+		labels: category.label,
+		key: keyOf(),
+		isNew: false,
+	}))
 }
 
 const UNIQUE_SUFFIX_START = 2
@@ -69,11 +114,13 @@ export function uniqueId(base: string, taken: Set<string>): string {
 /**
  * The categories an edit stores, one per row in its order: saved rows keep
  * their id, new rows get one derived from their label, unique among the
- * others. A row without a label is sent too, for the server to name it.
+ * others. Each label is written in `locale`, its other languages kept. A row
+ * without a label is sent too, for the server to name it.
  */
 export function toStoredCategories(
 	rows: EditableCategory[],
-): TemplateCategory[] {
+	locale: string,
+): StoredCategory[] {
 	const taken = new Set(rows.filter((row) => !row.isNew).map((row) => row.id))
 	return rows.map((row) => {
 		const id = row.isNew
@@ -82,7 +129,7 @@ export function toStoredCategories(
 		taken.add(id)
 		return {
 			id,
-			label: row.label.trim(),
+			label: withLabelIn(row.labels, locale, row.label.trim()),
 			icon: row.icon || DEFAULT_CATEGORY_ICON,
 		}
 	})
@@ -92,12 +139,12 @@ export function toStoredCategories(
  * A category as the editor hands it to the form: a kept one, or one removed
  * whose templates move to `moveTo` once the form is saved.
  */
-export interface CategoryEntry extends TemplateCategory {
+export interface CategoryEntry extends StoredCategory {
 	moveTo?: string
 }
 
 /** The kept categories of a list, without the removed ones it moves away. */
-export function keptCategories(entries: CategoryEntry[]): TemplateCategory[] {
+export function keptCategories(entries: CategoryEntry[]): StoredCategory[] {
 	return entries.filter((entry) => entry.moveTo === undefined)
 }
 
@@ -115,7 +162,7 @@ export function categoryMoves(entries: CategoryEntry[]): Map<string, string> {
  * whose templates move elsewhere, still under its own id.
  */
 export function withMoves(
-	categories: TemplateCategory[],
+	categories: StoredCategory[],
 	removed: CategoryEntry[],
 ): CategoryEntry[] {
 	return [...categories, ...removed.filter((entry) => entry.moveTo)]
@@ -200,41 +247,3 @@ export function toStoredCategory(
 ): string | null {
 	return value || null
 }
-
-/** Answers the text of an i18n key, or nothing when the catalog lacks it. */
-export type OptionalTranslate = (key: string) => string | undefined
-
-/** The labels the backend's `DEFAULT_CATEGORIES` (`src/types/settings.ts`) ship with. */
-const DEFAULT_CATEGORY_LABELS: Record<string, string> = {
-	orders: 'Orders',
-	account: 'Account & access',
-	billing: 'Billing',
-	marketing: 'Marketing',
-	forms: 'Forms',
-}
-const DEFAULT_CATEGORY_KEY_PREFIX = 'dms_mailing.categories.defaults'
-
-/** The i18n key of a shipped category nobody renamed; absent otherwise. */
-export function defaultCategoryLabelKey(
-	category: TemplateCategory,
-): string | undefined {
-	return DEFAULT_CATEGORY_LABELS[category.id] === category.label
-		? `${DEFAULT_CATEGORY_KEY_PREFIX}.${category.id}`
-		: undefined
-}
-
-/**
- * The categories as the interface shows them: a shipped one still under its
- * original English label reads in the interface's language, a label someone
- * wrote stays as written. Nothing stored changes.
- */
-export function localizeCategories(
-	categories: TemplateCategory[],
-	translate: OptionalTranslate,
-): TemplateCategory[] {
-	return categories.map((category) => {
-		const key = defaultCategoryLabelKey(category)
-		const label = key ? translate(key) : undefined
-		return label ? { ...category, label } : category
-	})
-}

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

@@ -72,3 +72,28 @@ export function formatRate(rate: number | null, locale: string): string {
 		maximumFractionDigits: RATE_DECIMALS,
 	}).format(rate / PERCENT)
 }
+
+/** Whether the steps carry a comparison window: none does with it off. */
+export const isCompared = (steps: FunnelStepReading[]): boolean =>
+	steps.some((step) => step.previousCount !== undefined)
+
+const DELTA_ARROWS: Record<number, string> = { 1: '▲ ', 0: '', [-1]: '▼ ' }
+
+/**
+ * A step's change as the card prints it ("▲ 12 %"); a dash when none can be
+ * stated, against a step the comparison window never reached.
+ */
+export function formatDelta(delta: number | undefined, locale: string): string {
+	if (delta === undefined) return ABSENT_RATE
+	return `${DELTA_ARROWS[Math.sign(delta)] ?? ''}${formatRate(Math.abs(delta), locale)}`
+}
+
+type DeltaTone = 'success' | 'error' | 'neutral'
+
+/** Growth is good down the funnel, bad for the leak out of it. */
+export function deltaTone(step: FunnelStepReading): DeltaTone {
+	if (!step.delta) return 'neutral'
+	const isGrowing = step.delta > 0
+	const isLeak = step.id === FUNNEL_LEAK_STEP
+	return isGrowing !== isLeak ? 'success' : 'error'
+}

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

@@ -1,7 +1,5 @@
 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 = {
@@ -10,11 +8,6 @@ export const CLOCK_FORMAT: Intl.DateTimeFormatOptions = {
 	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,

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

@@ -1,5 +1,7 @@
 import type { StarterSummary } from '../types/mailing'
-import type { OptionalTranslate } from './categories'
+
+/** Answers the text of an i18n key, or nothing when the catalog lacks it. */
+export type OptionalTranslate = (key: string) => string | undefined
 
 const STARTER_NAME_KEY_PREFIX = 'dms_mailing.starters.names'
 

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

@@ -93,11 +93,16 @@ export function splitTokens(text: string): TextPart[] {
 	return splitRawSegments(text).map(({ kind, value }) => ({ kind, value }))
 }
 
+/**
+ * A test value as the data holds it. Amounts and dates are written for the
+ * recipient's locale by the engine alone (`src/engine/formats.ts`): the
+ * preview and the sends show them formatted, the paper shows them raw.
+ */
 function formatValue(value: unknown): string {
 	return value instanceof Date ? value.toISOString() : String(value)
 }
 
-/** Reads one token path in `data`, formatted like the engine prints it. */
+/** Reads one token path in `data`, as the paper shows it. */
 export function resolveToken(
 	path: string,
 	data: Record<string, unknown>,