@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/frontend-vue/app/utils/blocks/tree.ts

@@ -1,6 +1,11 @@
-import type { Block, IfBlock } from '../../types/mailing'
+import type {
+	Block,
+	BlockType,
+	FooterBlock,
+	IfBlock,
+} from '../../types/mailing'
 import { deepClone } from '../clone'
-import { newBlockId } from './factory'
+import { footerLabelsFor, newBlockId } from './factory'
 
 const isIf = (block: Block): block is IfBlock => block.type === 'if'
 
@@ -72,3 +77,110 @@ export function removeBlock(blocks: Block[], id: string): boolean {
 export function insertBlock(list: Block[], index: number, block: Block): void {
 	list.splice(index, 0, block)
 }
+
+/** Every block of the tree, depth first, branches in place. */
+export function flattenBlocks(blocks: Block[]): Block[] {
+	return blocks.flatMap((block) => [
+		block,
+		...branchesOf(block).flatMap(flattenBlocks),
+	])
+}
+
+/** Where a block sits in the whole tree, 1-based ("block 3 of 12"). */
+export interface BlockPosition {
+	index: number
+	total: number
+}
+
+export function blockPosition(
+	blocks: Block[],
+	id: string,
+): BlockPosition | null {
+	const flat = flattenBlocks(blocks)
+	const index = flat.findIndex((block) => block.id === id)
+	return index < 0 ? null : { index: index + 1, total: flat.length }
+}
+
+/** A list of the tree and the index a new block goes to in it. */
+export interface InsertionPoint {
+	list: Block[]
+	index: number
+}
+
+/** The block type that closes an e-mail: new blocks go above it. */
+const CLOSING_TYPE: BlockType = 'footer'
+
+function endOfBody(blocks: Block[], type?: BlockType): number {
+	const isClosed = blocks.at(-1)?.type === CLOSING_TYPE
+	return isClosed && type !== CLOSING_TYPE ? blocks.length - 1 : blocks.length
+}
+
+/**
+ * Where a block added "under the selected one" lands: right after it in its
+ * own list or, when nothing is selected, at the end of the root list but
+ * above the closing footer (a new footer still goes last).
+ */
+export function insertionAfter(
+	blocks: Block[],
+	id: string | null,
+	type?: BlockType,
+): InsertionPoint {
+	const list = id ? findParentList(blocks, id) : null
+	if (!list) return { list: blocks, index: endOfBody(blocks, type) }
+	return { list, index: list.findIndex((block) => block.id === id) + 1 }
+}
+
+function parentOf(blocks: Block[], list: Block[]): Block | null {
+	return (
+		flattenBlocks(blocks).find((block) => branchesOf(block).includes(list)) ??
+		null
+	)
+}
+
+/**
+ * The block to select once `id` is gone: the next one in its list, else the
+ * previous one, else the condition holding it.
+ */
+export function neighbourOf(blocks: Block[], id: string): string | null {
+	const list = findParentList(blocks, id)
+	if (!list) return null
+	const index = list.findIndex((block) => block.id === id)
+	const sibling = list[index + 1] ?? list[index - 1]
+	return sibling?.id ?? parentOf(blocks, list)?.id ?? null
+}
+
+/** How many blocks each branch of a condition holds (then, else). */
+export interface BranchCounts {
+	then: number
+	else: number | null
+}
+
+export function branchCounts(block: IfBlock): BranchCounts {
+	return {
+		then: block.children.length,
+		else: block.elseChildren ? block.elseChildren.length : null,
+	}
+}
+
+const isFooter = (block: Block): block is FooterBlock => block.type === 'footer'
+
+/**
+ * Rewrites the footer labels a locale copy still has at the source locale's
+ * defaults into the target locale's; labels someone typed are kept.
+ */
+export function localizeFooters(
+	blocks: Block[],
+	from: string,
+	to: string,
+): void {
+	const source = footerLabelsFor(from)
+	const target = footerLabelsFor(to)
+	flattenBlocks(blocks)
+		.filter(isFooter)
+		.forEach((footer) => {
+			if (footer.unsubscribeLabel === source.unsubscribe)
+				footer.unsubscribeLabel = target.unsubscribe
+			if (footer.preferencesLabel === source.preferences)
+				footer.preferencesLabel = target.preferences
+		})
+}

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

@@ -2,26 +2,163 @@ import type { TemplateCategory } from '../types/mailing'
 
 const ID_SEPARATOR = '-'
 
+export function serializeCategories(categories: TemplateCategory[]): string {
+	return JSON.stringify(categories)
+}
+
+/** The icons the categories editor offers ("Pick an icon"). */
+export const CATEGORY_ICONS = [
+	'i-ph-package',
+	'i-ph-lock',
+	'i-ph-user-circle',
+	'i-ph-key',
+	'i-ph-file-text',
+	'i-ph-newspaper',
+	'i-ph-sparkle',
+	'i-ph-textbox',
+	'i-ph-truck',
+	'i-ph-shopping-cart',
+	'i-ph-bell',
+	'i-ph-megaphone',
+	'i-ph-gift',
+	'i-ph-users',
+	'i-ph-calendar',
+	'i-ph-chat-circle',
+]
+
+export const DEFAULT_CATEGORY_ICON = 'i-ph-folder'
+
+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 {
+	const used = new Set(categories.map((category) => category.icon))
+	return CATEGORY_ICONS.find((icon) => !used.has(icon)) ?? DEFAULT_CATEGORY_ICON
+}
+
+/** The i18n key part naming an icon (`megaphone` for `i-ph-megaphone`). */
+export function iconName(icon: string): string {
+	return icon.startsWith(ICON_PREFIX)
+		? icon.slice(ICON_PREFIX.length).replace(/-/g, '_')
+		: icon
+}
+
+/**
+ * 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.
+ */
+export interface EditableCategory extends TemplateCategory {
+	key: string
+	isNew: boolean
+}
+
+const UNIQUE_SUFFIX_START = 2
+const FALLBACK_ID_BASE = 'category'
+
+/** `base`, or `base-2`, `base-3`… the first one `taken` does not hold. */
+export function uniqueId(base: string, taken: Set<string>): string {
+	if (!taken.has(base)) return base
+	let suffix = UNIQUE_SUFFIX_START
+	while (taken.has(`${base}${ID_SEPARATOR}${suffix}`)) suffix++
+	return `${base}${ID_SEPARATOR}${suffix}`
+}
+
 /**
- * Reads the category list off the settings form field, which stores it either
- * as the array or as the JSON string the DMS round-trips. Never throws: this
- * runs while rendering the field.
+ * 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.
  */
-export function parseCategories(
-	value: TemplateCategory[] | string | null | undefined,
+export function toStoredCategories(
+	rows: EditableCategory[],
 ): TemplateCategory[] {
-	if (Array.isArray(value)) return value
-	if (!value) return []
-	try {
-		const parsed: unknown = JSON.parse(value)
-		return Array.isArray(parsed) ? (parsed as TemplateCategory[]) : []
-	} catch {
-		return []
-	}
+	const taken = new Set(rows.filter((row) => !row.isNew).map((row) => row.id))
+	return rows.map((row) => {
+		const id = row.isNew
+			? uniqueId(slugifyId(row.label) || FALLBACK_ID_BASE, taken)
+			: row.id
+		taken.add(id)
+		return {
+			id,
+			label: row.label.trim(),
+			icon: row.icon || DEFAULT_CATEGORY_ICON,
+		}
+	})
 }
 
-export function serializeCategories(categories: TemplateCategory[]): string {
-	return JSON.stringify(categories)
+/**
+ * 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 {
+	moveTo?: string
+}
+
+/** The kept categories of a list, without the removed ones it moves away. */
+export function keptCategories(entries: CategoryEntry[]): TemplateCategory[] {
+	return entries.filter((entry) => entry.moveTo === undefined)
+}
+
+/** Where the templates of each removed category go, by its id. */
+export function categoryMoves(entries: CategoryEntry[]): Map<string, string> {
+	return new Map(
+		entries.flatMap((entry) =>
+			entry.moveTo === undefined ? [] : [[entry.id, entry.moveTo] as const],
+		),
+	)
+}
+
+/**
+ * What the editor hands the form: the kept categories, then each removed one
+ * whose templates move elsewhere, still under its own id.
+ */
+export function withMoves(
+	categories: TemplateCategory[],
+	removed: CategoryEntry[],
+): CategoryEntry[] {
+	return [...categories, ...removed.filter((entry) => entry.moveTo)]
+}
+
+/**
+ * The moves of `removed` once `id` is removed too and its templates go to
+ * `target`: a move into `id` follows it to `target`, or is dropped when
+ * `target` is none (those templates end uncategorised either way).
+ */
+export function redirectMoves(
+	removed: CategoryEntry[],
+	id: string,
+	target: string,
+): CategoryEntry[] {
+	return removed
+		.map((entry) =>
+			entry.moveTo === id ? { ...entry, moveTo: target } : entry,
+		)
+		.filter((entry) => entry.moveTo)
+}
+
+/** Rows after a move, and where the moved row now sits. */
+export interface MovedRows<T> {
+	rows: T[]
+	index: number
+}
+
+/**
+ * `rows` with the row at `index` moved by `offset` (-1 up, 1 down), and its
+ * new index; unchanged at either end.
+ */
+export function moveRow<T>(
+	rows: T[],
+	index: number,
+	offset: number,
+): MovedRows<T> {
+	const target = index + offset
+	if (target < 0 || target >= rows.length) return { rows, index }
+	const moved = [...rows]
+	const [row] = moved.splice(index, 1)
+	moved.splice(target, 0, row as T)
+	return { rows: moved, index: target }
 }
 
 /**
@@ -52,3 +189,52 @@ export function toCategoryOption(value: string | null | undefined): string {
 export function fromCategoryOption(value: string): string {
 	return value === NO_CATEGORY ? '' : value
 }
+
+/**
+ * The category an edit stores. "No category" is sent as `null` rather than
+ * omitted: from interface-data-api 0.2.0 on, the edit route leaves an absent
+ * key unchanged, so only an explicit `null` clears it.
+ */
+export function toStoredCategory(
+	value: string | null | undefined,
+): 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/changes.ts

@@ -0,0 +1,152 @@
+import type {
+	Block,
+	TemplateChange,
+	TemplateChangeKind,
+	TemplateContent,
+} from '../types/mailing'
+import { blockLabelKey } from './blocks/factory'
+import { findBlock } from './blocks/tree'
+
+/** One line of the publish review: "EN · Paragraph changed". */
+export interface ChangeLine {
+	key: string
+	icon: string
+	text: string
+	/** The text customers receive today, when the change rewrote one. */
+	before?: string
+	/** The draft's text in its place. */
+	after?: string
+}
+
+export type ChangeTranslator = (
+	key: string,
+	params?: Record<string, string>,
+) => string
+
+/** Contents a change can name its block from: the draft, then the live one. */
+export interface ChangeSources {
+	draft: TemplateContent
+	published: TemplateContent | null
+}
+
+const CHANGE_KEY_PREFIX = 'dms_mailing.editor.changes'
+const LOCALE_SEPARATOR = ' · '
+const DETAIL_SEPARATOR = ' '
+
+const CHANGE_ICONS: Record<TemplateChangeKind, string> = {
+	locale_added: 'i-ph-plus-circle',
+	locale_removed: 'i-ph-minus-circle',
+	subject: 'i-ph-pencil-simple',
+	preheader: 'i-ph-pencil-simple',
+	block_added: 'i-ph-plus-circle',
+	block_removed: 'i-ph-minus-circle',
+	block_changed: 'i-ph-pencil-simple',
+	blocks_reordered: 'i-ph-arrows-down-up',
+	variable_added: 'i-ph-brackets-curly',
+	variable_removed: 'i-ph-brackets-curly',
+	variable_changed: 'i-ph-brackets-curly',
+}
+
+function blockIn(
+	content: TemplateContent | null,
+	change: TemplateChange,
+): Block | null {
+	const blocks = content?.locales[change.locale]?.blocks
+	return blocks && change.blockId ? findBlock(blocks, change.blockId) : null
+}
+
+function blockOf(change: TemplateChange, sources: ChangeSources): Block | null {
+	return blockIn(sources.draft, change) ?? blockIn(sources.published, change)
+}
+
+/** The fields a reader recognises a block by, in the order they are tried. */
+const TEXT_FIELDS = ['text', 'label', 'alt'] as const
+
+function textOf(block: Block | null): string | undefined {
+	if (!block) return undefined
+	const fields = block as unknown as Record<string, unknown>
+	const field = TEXT_FIELDS.find((name) => typeof fields[name] === 'string')
+	return field ? (fields[field] as string) : undefined
+}
+
+type EnvelopeKind = Extract<TemplateChangeKind, 'subject' | 'preheader'>
+
+const ENVELOPE_KINDS: TemplateChangeKind[] = ['subject', 'preheader']
+
+function textsOf(
+	change: TemplateChange,
+	sources: ChangeSources,
+): Pick<ChangeLine, 'before' | 'after'> {
+	if (ENVELOPE_KINDS.includes(change.kind)) {
+		const field = change.kind as EnvelopeKind
+		return {
+			before: sources.published?.locales[change.locale]?.[field],
+			after: sources.draft.locales[change.locale]?.[field],
+		}
+	}
+	if (change.kind !== 'block_changed') return {}
+	return {
+		before: textOf(blockIn(sources.published, change)),
+		after: textOf(blockIn(sources.draft, change)),
+	}
+}
+
+/** Before / after texts worth showing: both known and actually different. */
+function rewriteOf(
+	change: TemplateChange,
+	sources: ChangeSources,
+): Pick<ChangeLine, 'before' | 'after'> {
+	const { before, after } = textsOf(change, sources)
+	if (before === undefined || after === undefined || before === after) return {}
+	return { before, after }
+}
+
+function blockName(
+	change: TemplateChange,
+	sources: ChangeSources,
+	t: ChangeTranslator,
+): string {
+	if (!change.blockType) return ''
+	const label = t(blockLabelKey(change.blockType))
+	const block = blockOf(change, sources)
+	return block?.type === 'if'
+		? `${label}${DETAIL_SEPARATOR}${block.condition.path}`
+		: label
+}
+
+/** "EN · " for a change of the content; nothing for a declaration's. */
+function scopeOf(change: TemplateChange): string {
+	return change.locale
+		? `${change.locale.toUpperCase()}${LOCALE_SEPARATOR}`
+		: ''
+}
+
+/** Contents to name blocks from when only the change list is known. */
+export const NO_SOURCES: ChangeSources = {
+	draft: { locales: {} },
+	published: null,
+}
+
+/**
+ * The publish review's reading of the server's change list, one line per
+ * change, prefixed with its locale (a variable declaration has none).
+ */
+export function describeChanges(
+	changes: TemplateChange[],
+	sources: ChangeSources,
+	t: ChangeTranslator,
+): ChangeLine[] {
+	return changes.map((change, index) => {
+		const sentence = t(`${CHANGE_KEY_PREFIX}.${change.kind}`, {
+			block: blockName(change, sources, t),
+			variable: change.variable ?? '',
+		})
+		const subject = change.blockId ?? change.variable ?? index
+		return {
+			key: `${change.locale}-${change.kind}-${subject}`,
+			icon: CHANGE_ICONS[change.kind],
+			text: `${scopeOf(change)}${sentence}`,
+			...rewriteOf(change, sources),
+		}
+	})
+}

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

@@ -1,4 +1,5 @@
 import type { Condition, ConditionOperator } from '../types/mailing'
+import { readPath } from './paths'
 
 export const OPERATORS: ConditionOperator[] = [
 	'truthy',
@@ -18,25 +19,6 @@ export const OPERATORS_WITH_VALUE: ConditionOperator[] = [
 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(
@@ -48,3 +30,27 @@ export function describeCondition(
 		return `${condition.path} ${label}`
 	return `${condition.path} ${label} ${condition.value || EMPTY_VALUE_PLACEHOLDER}`
 }
+
+type Evaluator = (actual: unknown, expected: string) => boolean
+
+const EVALUATORS: Record<ConditionOperator, Evaluator> = {
+	truthy: (actual) => Boolean(actual),
+	falsy: (actual) => !actual,
+	eq: (actual, expected) => String(actual) === expected,
+	ne: (actual, expected) => String(actual) !== expected,
+	gt: (actual, expected) => Number(actual) > Number(expected),
+	lt: (actual, expected) => Number(actual) < Number(expected),
+}
+
+/**
+ * Evaluates a condition against a data set exactly like the backend engine
+ * (`src/engine/conditions.ts`), so the editor's Data mode shows the branch a
+ * real send takes.
+ */
+export function evaluateCondition(
+	condition: Condition,
+	data: Record<string, unknown>,
+): boolean {
+	const evaluate = EVALUATORS[condition.operator]
+	return evaluate(readPath(data, condition.path), condition.value)
+}