@antelopejs/dms-mailing 0.3.3 → 0.4.0

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

@@ -0,0 +1,120 @@
+import type { VariableDefinition, VariableType } from '../types/mailing'
+
+const TOKEN_OPEN = '{{'
+const TOKEN_CLOSE = '}}'
+const PATH_CHARACTERS = /^[A-Za-z0-9_.[\]]*$/
+const PATH_CHARACTER = /[A-Za-z0-9_.[\]]/
+const MAX_SUGGESTIONS = 8
+
+/** An open `{{` the caret is typing a path after. */
+export interface TokenQuery {
+	/** Index of the `{{`. */
+	start: number
+	query: string
+}
+
+/**
+ * The token being typed at `caret`: a `{{` before it, not yet closed, followed
+ * only by path characters. `null` when the caret is not inside one.
+ */
+export function tokenQueryAt(text: string, caret: number): TokenQuery | null {
+	const before = text.slice(0, caret)
+	const start = before.lastIndexOf(TOKEN_OPEN)
+	if (start < 0) return null
+	const typed = before.slice(start + TOKEN_OPEN.length)
+	const query = typed.trimStart()
+	if (typed.includes(TOKEN_CLOSE) || !PATH_CHARACTERS.test(query)) return null
+	return { start, query }
+}
+
+export type SuggestionStatus = 'declared' | 'undeclared' | 'system'
+
+export interface PathSuggestion {
+	path: string
+	type: VariableType | null
+	status: SuggestionStatus
+}
+
+/** What the autocomplete offers: declared paths, used ones, system ones. */
+export interface SuggestionSources {
+	variables: VariableDefinition[]
+	detected: string[]
+	system: string[]
+}
+
+function allSuggestions(sources: SuggestionSources): PathSuggestion[] {
+	const declared = new Set(sources.variables.map((variable) => variable.path))
+	return [
+		...sources.variables.map((variable) => ({
+			path: variable.path,
+			type: variable.type,
+			status: 'declared' as const,
+		})),
+		...sources.detected
+			.filter((path) => !declared.has(path) && !sources.system.includes(path))
+			.map((path) => ({ path, type: null, status: 'undeclared' as const })),
+		...sources.system.map((path) => ({
+			path,
+			type: null,
+			status: 'system' as const,
+		})),
+	]
+}
+
+/**
+ * The paths matching `query`: those starting with it first, then those
+ * containing it, each group in source order; at most eight.
+ */
+export function suggestPaths(
+	query: string,
+	sources: SuggestionSources,
+): PathSuggestion[] {
+	const needle = query.toLowerCase()
+	const matching = allSuggestions(sources).filter((entry) =>
+		entry.path.toLowerCase().includes(needle),
+	)
+	const starts = matching.filter((entry) =>
+		entry.path.toLowerCase().startsWith(needle),
+	)
+	const rest = matching.filter((entry) => !starts.includes(entry))
+	return [...starts, ...rest].slice(0, MAX_SUGGESTIONS)
+}
+
+/** A text after an insertion, and where the caret goes. */
+export interface TextEdit {
+	text: string
+	caret: number
+}
+
+/**
+ * Replaces the token being typed (from its `{{` through the path characters
+ * after the caret and a closing `}}` if there is one) with `{{path}}`.
+ */
+export function insertSuggestion(
+	text: string,
+	query: TokenQuery,
+	caret: number,
+	path: string,
+): TextEdit {
+	let end = caret
+	while (end < text.length && PATH_CHARACTER.test(text.charAt(end))) end += 1
+	if (text.startsWith(TOKEN_CLOSE, end)) end += TOKEN_CLOSE.length
+	const token = `${TOKEN_OPEN}${path}${TOKEN_CLOSE}`
+	return {
+		text: `${text.slice(0, query.start)}${token}${text.slice(end)}`,
+		caret: query.start + token.length,
+	}
+}
+
+/** Inserts `{{path}}` at the caret (a click in the Variables tab). */
+export function insertTokenAt(
+	text: string,
+	caret: number,
+	path: string,
+): TextEdit {
+	const token = `${TOKEN_OPEN}${path}${TOKEN_CLOSE}`
+	return {
+		text: `${text.slice(0, caret)}${token}${text.slice(caret)}`,
+		caret: caret + token.length,
+	}
+}

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

@@ -1,14 +1,14 @@
 import type { BlockType } from '../../types/mailing'
 
 export const BLOCK_COMPONENT_NAMES: Record<BlockType, string> = {
-	hero: 'DmsMailingBlockHero',
-	heading: 'DmsMailingBlockHeading',
-	paragraph: 'DmsMailingBlockParagraph',
-	code: 'DmsMailingBlockCode',
-	list: 'DmsMailingBlockList',
-	total: 'DmsMailingBlockTotal',
-	button: 'DmsMailingBlockButton',
-	if: 'DmsMailingEditorIfBlock',
-	divider: 'DmsMailingBlockDivider',
-	footer: 'DmsMailingBlockFooter',
+	hero: 'MailingBlockHero',
+	heading: 'MailingBlockHeading',
+	paragraph: 'MailingBlockParagraph',
+	code: 'MailingBlockCode',
+	list: 'MailingBlockList',
+	total: 'MailingBlockTotal',
+	button: 'MailingBlockButton',
+	if: 'MailingEditorIfBlock',
+	divider: 'MailingBlockDivider',
+	footer: 'MailingBlockFooter',
 }

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

@@ -1,5 +1,5 @@
 import type { Block } from '../../types/mailing'
-import type { PaletteEntry } from './factory'
+import type { BlockContext, PaletteEntry } from './factory'
 import { createBlock } from './factory'
 
 export const DRAG_GROUP = { name: 'mailing-blocks' }
@@ -10,6 +10,10 @@ export const PALETTE_GROUP = {
 }
 export const DRAG_HANDLE = '.mailing-drag-handle'
 
-export function cloneFromPalette(entry: PaletteEntry): Block {
-	return createBlock(entry.type)
+/** The block a tile dropped on the canvas becomes, shaped by its template. */
+export function cloneFromPalette(
+	entry: PaletteEntry,
+	context: BlockContext = {},
+): Block {
+	return createBlock(entry.type, context)
 }

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

@@ -1,25 +1,82 @@
-import type { Block, BlockType } from '../../types/mailing'
+import type {
+	Block,
+	BlockType,
+	VariableDefinition,
+	VariableType,
+} from '../../types/mailing'
+import { hasFooterLinksByDefault } from '../system-variables'
 
 export interface PaletteEntry {
 	type: BlockType
 	icon: string
+	/** The tile spans both columns of the palette grid. */
+	isWide?: boolean
 }
 
+/** The icon that stands for each block type, in the palette and the outline. */
+export const BLOCK_ICONS: Record<BlockType, string> = {
+	heading: 'i-ph-text-h',
+	paragraph: 'i-ph-text-align-left',
+	hero: 'i-ph-image',
+	button: 'i-ph-cursor-click',
+	list: 'i-ph-list-bullets',
+	total: 'i-ph-receipt',
+	code: 'i-ph-hash',
+	divider: 'i-ph-minus',
+	footer: 'i-ph-rows',
+	if: 'i-ph-git-branch',
+}
+
+const entry = (type: BlockType, isWide = false): PaletteEntry => ({
+	type,
+	icon: BLOCK_ICONS[type],
+	isWide,
+})
+
 export const BLOCK_PALETTE: PaletteEntry[] = [
-	{ type: 'heading', icon: 'i-ph-text-h' },
-	{ type: 'paragraph', icon: 'i-ph-text-align-left' },
-	{ type: 'button', icon: 'i-ph-cursor-click' },
-	{ type: 'hero', icon: 'i-ph-image' },
-	{ type: 'list', icon: 'i-ph-table' },
-	{ type: 'total', icon: 'i-ph-sigma' },
-	{ type: 'code', icon: 'i-ph-lock-key' },
-	{ type: 'divider', icon: 'i-ph-minus' },
-	{ type: 'footer', icon: 'i-ph-list-dashes' },
+	entry('heading'),
+	entry('paragraph'),
+	entry('hero'),
+	entry('button'),
+	entry('list'),
+	entry('total'),
+	entry('code'),
+	entry('divider'),
+	entry('footer', true),
 ]
 
-export const LOGIC_PALETTE: PaletteEntry[] = [
-	{ type: 'if', icon: 'i-ph-git-branch' },
-]
+export const LOGIC_PALETTE: PaletteEntry[] = [entry('if', true)]
+
+const BLOCK_LABEL_PREFIX = 'dms_mailing.blocks'
+const PALETTE_LABEL_PREFIX = 'dms_mailing.editor.palette.tiles'
+const PALETTE_SPECIFIC_LABELS: BlockType[] = ['footer', 'if']
+
+/** The i18n key naming a block type (outline, inspector, canvas tag). */
+export function blockLabelKey(type: BlockType): string {
+	return `${BLOCK_LABEL_PREFIX}.${type}`
+}
+
+/** The i18n key of a palette tile, longer than the block name for some. */
+export function paletteLabelKey(type: BlockType): string {
+	return PALETTE_SPECIFIC_LABELS.includes(type)
+		? `${PALETTE_LABEL_PREFIX}.${type}`
+		: blockLabelKey(type)
+}
+
+/** Keeps the tiles whose label or type contains `query`, case-insensitively. */
+export function filterPalette(
+	entries: PaletteEntry[],
+	query: string,
+	labelOf: (entry: PaletteEntry) => string,
+): PaletteEntry[] {
+	const needle = query.trim().toLowerCase()
+	if (!needle) return entries
+	return entries.filter(
+		(candidate) =>
+			labelOf(candidate).toLowerCase().includes(needle) ||
+			candidate.type.includes(needle),
+	)
+}
 
 const ID_RADIX = 36
 const ID_LENGTH = 6
@@ -33,68 +90,172 @@ export function newBlockId(type: BlockType): string {
 	return `${type}_${random.padEnd(ID_LENGTH, ID_PADDING)}`
 }
 
-type BlockBuilder = (id: string) => Block
+/**
+ * What a new block may borrow from the template it lands in: the locale its
+ * labels are written in, and the variables a list or a condition can point at.
+ */
+export interface BlockContext {
+	locale?: string
+	variables?: VariableDefinition[]
+	detected?: string[]
+	/** The template's category: a transactional footer has no links. */
+	category?: string | null
+}
+
+export interface FooterLabels {
+	unsubscribe: string
+	preferences: string
+}
+
+/**
+ * The words a new block starts with. They land in the e-mail itself, so they
+ * follow the language of the locale being edited, not the interface's.
+ */
+export interface BlockPlaceholders extends FooterLabels {
+	heading: string
+	paragraph: string
+	button: string
+	total: string
+}
+
+/** The footer labels mirror the backend's `blankContent` footer. */
+const BLOCK_PLACEHOLDERS: Record<string, BlockPlaceholders> = {
+	en: {
+		heading: 'New heading',
+		paragraph: 'Paragraph text…',
+		button: 'Button',
+		total: 'Total',
+		unsubscribe: 'Unsubscribe',
+		preferences: 'Preferences',
+	},
+	fr: {
+		heading: 'Nouveau titre',
+		paragraph: 'Votre texte…',
+		button: 'Bouton',
+		total: 'Total',
+		unsubscribe: 'Se désinscrire',
+		preferences: 'Préférences',
+	},
+}
+/** A footer without unsubscribe and preferences links. */
+const NO_FOOTER_LINKS: FooterLabels = { unsubscribe: '', preferences: '' }
+const DEFAULT_PLACEHOLDER_LANGUAGE = 'en'
+const LANGUAGE_SEPARATOR = /[-_]/
+
+/** The starting words of a locale (`fr`, `fr-BE`…), English otherwise. */
+export function placeholdersFor(locale?: string): BlockPlaceholders {
+	const language = (locale ?? '').split(LANGUAGE_SEPARATOR)[0] ?? ''
+	return (BLOCK_PLACEHOLDERS[language] ??
+		BLOCK_PLACEHOLDERS[DEFAULT_PLACEHOLDER_LANGUAGE]) as BlockPlaceholders
+}
+
+/** The default footer labels of a locale (`fr`, `fr-BE`…), English otherwise. */
+export function footerLabelsFor(locale?: string): FooterLabels {
+	const { unsubscribe, preferences } = placeholdersFor(locale)
+	return { unsubscribe, preferences }
+}
+
+/** Paths a block points at when the template has no fitting variable yet. */
+const PLACEHOLDER_LIST_SOURCE = 'items'
+const PLACEHOLDER_CONDITION_PATH = 'condition'
+const LIST_TYPE: VariableType = 'array'
+const CONDITION_TYPE: VariableType = 'boolean'
+
+function declaredOfType(
+	context: BlockContext,
+	type: VariableType,
+): string | undefined {
+	return context.variables?.find((variable) => variable.type === type)?.path
+}
+
+function listSource(context: BlockContext): string {
+	return declaredOfType(context, LIST_TYPE) ?? PLACEHOLDER_LIST_SOURCE
+}
+
+function conditionPath(context: BlockContext): string {
+	return (
+		declaredOfType(context, CONDITION_TYPE) ??
+		context.variables?.[0]?.path ??
+		context.detected?.[0] ??
+		PLACEHOLDER_CONDITION_PATH
+	)
+}
+
+type BlockBuilder = (id: string, context: BlockContext) => Block
 
 const BUILDERS: Record<BlockType, BlockBuilder> = {
 	hero: (id) => ({ id, type: 'hero', imageUrl: '', alt: '', visibleIf: null }),
-	heading: (id) => ({
+	heading: (id, context) => ({
 		id,
 		type: 'heading',
-		text: 'New heading',
+		text: placeholdersFor(context.locale).heading,
 		align: 'left',
 		size: DEFAULT_HEADING_SIZE,
 		visibleIf: null,
 	}),
-	paragraph: (id) => ({
+	paragraph: (id, context) => ({
 		id,
 		type: 'paragraph',
-		text: 'Paragraph text…',
+		text: placeholdersFor(context.locale).paragraph,
 		align: 'left',
 		visibleIf: null,
 	}),
-	code: (id) => ({ id, type: 'code', text: '{{code}}', visibleIf: null }),
-	list: (id) => ({
+	code: (id) => ({ id, type: 'code', text: '', visibleIf: null }),
+	list: (id, context) => ({
 		id,
 		type: 'list',
-		source: 'order.lines',
+		source: listSource(context),
 		labelPath: 'label',
 		valuePath: 'total',
 		visibleIf: null,
 	}),
-	total: (id) => ({
+	total: (id, context) => ({
 		id,
 		type: 'total',
-		label: 'Total',
-		value: '{{order.total}}',
+		label: placeholdersFor(context.locale).total,
+		value: '',
 		visibleIf: null,
 	}),
-	button: (id) => ({
+	button: (id, context) => ({
 		id,
 		type: 'button',
-		text: 'Button',
+		text: placeholdersFor(context.locale).button,
 		href: 'https://',
 		align: 'left',
 		visibleIf: null,
 	}),
-	if: (id) => ({
+	if: (id, context) => ({
 		id,
 		type: 'if',
-		condition: { path: 'contact.isPro', operator: 'truthy', value: '' },
+		condition: { path: conditionPath(context), operator: 'truthy', value: '' },
 		children: [],
 		elseChildren: null,
 		visibleIf: null,
 	}),
 	divider: (id) => ({ id, type: 'divider', visibleIf: null }),
-	footer: (id) => ({
-		id,
-		type: 'footer',
-		text: '',
-		unsubscribeLabel: 'Unsubscribe',
-		preferencesLabel: 'Preferences',
-		visibleIf: null,
-	}),
+	footer: (id, context) => {
+		const labels = hasFooterLinksByDefault(context.category)
+			? footerLabelsFor(context.locale)
+			: NO_FOOTER_LINKS
+		return {
+			id,
+			type: 'footer',
+			text: '',
+			unsubscribeLabel: labels.unsubscribe,
+			preferencesLabel: labels.preferences,
+			visibleIf: null,
+		}
+	},
 }
 
-export function createBlock(type: BlockType): Block {
-	return BUILDERS[type](newBlockId(type))
+/**
+ * A new block of `type`. Its content stays neutral: no invented `{{token}}`;
+ * a list or a condition points at a declared variable of the right type when
+ * the template has one, the starting words speak the locale's language.
+ */
+export function createBlock(
+	type: BlockType,
+	context: BlockContext = {},
+): Block {
+	return BUILDERS[type](newBlockId(type), context)
 }

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

@@ -1,12 +1,24 @@
 import type { BlockType } from '../../types/mailing'
 
-export type FieldKind = 'text' | 'textarea' | 'url' | 'align' | 'size'
+/**
+ * `tokens` multi-line text with `{{` autocomplete, `token` the one-line
+ * version, `text` plain text, `path` a variable path, `align` the alignment
+ * switch, `size` the heading size slider.
+ */
+export type FieldKind = 'tokens' | 'token' | 'text' | 'path' | 'align' | 'size'
 
 export interface BlockField {
 	key: string
 	kind: FieldKind
 	label: string
 	help?: string
+	/** The backend refuses the content while this field is empty. */
+	isRequired?: boolean
+}
+
+interface FieldOptions {
+	help?: string
+	isRequired?: boolean
 }
 
 const LABEL_PREFIX = 'dms_mailing.editor.block_settings'
@@ -14,45 +26,53 @@ const LABEL_PREFIX = 'dms_mailing.editor.block_settings'
 const snakeCase = (key: string): string =>
 	key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
 
-const field = (key: string, kind: FieldKind, help?: string): BlockField => ({
+const field = (
+	key: string,
+	kind: FieldKind,
+	options: FieldOptions = {},
+): BlockField => ({
 	key,
 	kind,
 	label: `${LABEL_PREFIX}.${snakeCase(key)}`,
-	help,
+	...options,
 })
 
+const REQUIRED: FieldOptions = { isRequired: true }
+
 const FIELDS: Record<BlockType, BlockField[]> = {
-	hero: [field('imageUrl', 'url'), field('alt', 'text')],
+	hero: [field('imageUrl', 'token'), field('alt', 'token')],
 	heading: [
-		field('text', 'textarea', 'insert_hint'),
+		field('text', 'tokens'),
 		field('align', 'align'),
 		field('size', 'size'),
 	],
-	paragraph: [
-		field('text', 'textarea', 'insert_hint'),
-		field('align', 'align'),
-	],
-	code: [field('text', 'text')],
+	paragraph: [field('text', 'tokens'), field('align', 'align')],
+	code: [field('text', 'token')],
 	list: [
-		field('source', 'text', 'source_help'),
-		field('labelPath', 'text'),
-		field('valuePath', 'text'),
+		field('source', 'path', { help: 'source_help', isRequired: true }),
+		field('labelPath', 'text', REQUIRED),
+		field('valuePath', 'text', REQUIRED),
 	],
-	total: [field('label', 'text'), field('value', 'text')],
+	total: [field('label', 'token'), field('value', 'token')],
 	button: [
-		field('text', 'text'),
-		field('href', 'url'),
+		field('text', 'token'),
+		field('href', 'token'),
 		field('align', 'align'),
 	],
 	if: [],
 	divider: [],
 	footer: [
-		field('text', 'textarea'),
-		field('unsubscribeLabel', 'text'),
-		field('preferencesLabel', 'text'),
+		field('text', 'tokens'),
+		field('unsubscribeLabel', 'text', { help: 'unsubscribe_label_help' }),
+		field('preferencesLabel', 'text', { help: 'preferences_label_help' }),
 	],
 }
 
 export function fieldsFor(type: BlockType): BlockField[] {
 	return FIELDS[type]
 }
+
+/** Whether `value` may be written to the content for `field`. */
+export function isFieldValueValid(field: BlockField, value: string): boolean {
+	return !field.isRequired || value.trim() !== ''
+}

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

@@ -2,4 +2,5 @@ export * from './components'
 export * from './dnd'
 export * from './factory'
 export * from './fields'
+export * from './outline'
 export * from './tree'

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

@@ -0,0 +1,91 @@
+import type { Block, BlockType } from '../../types/mailing'
+import { BLOCK_ICONS } from './factory'
+
+export type OutlineRowKind = 'block' | 'else'
+
+/** One row of the Outline tab: a block, or the ELSE marker of a condition. */
+export interface OutlineRow {
+	key: string
+	kind: OutlineRowKind
+	blockId: string
+	type: BlockType
+	icon: string
+	depth: number
+	summary: string
+}
+
+const SUMMARY_LENGTH = 18
+const ELLIPSIS = '…'
+const ELSE_ICON = 'i-ph-arrow-elbow-down-right'
+const ELSE_KEY_SUFFIX = ':else'
+
+type Summarizer = (block: Block) => string
+
+const field =
+	(key: string): Summarizer =>
+	(block) => {
+		const value = (block as unknown as Record<string, unknown>)[key]
+		return typeof value === 'string' ? value : ''
+	}
+
+const SUMMARIZERS: Record<BlockType, Summarizer> = {
+	hero: (block) => field('alt')(block) || field('imageUrl')(block),
+	heading: field('text'),
+	paragraph: field('text'),
+	code: field('text'),
+	list: field('source'),
+	total: field('value'),
+	button: field('text'),
+	if: (block) => (block.type === 'if' ? block.condition.path : ''),
+	divider: () => '',
+	footer: field('text'),
+}
+
+/** A short, single-line reading of a block's content. */
+export function summarizeBlock(block: Block): string {
+	const text = SUMMARIZERS[block.type](block).replace(/\s+/g, ' ').trim()
+	return text.length > SUMMARY_LENGTH
+		? `${text.slice(0, SUMMARY_LENGTH).trimEnd()}${ELLIPSIS}`
+		: text
+}
+
+function blockRow(block: Block, depth: number): OutlineRow {
+	return {
+		key: block.id,
+		kind: 'block',
+		blockId: block.id,
+		type: block.type,
+		icon: BLOCK_ICONS[block.type],
+		depth,
+		summary: summarizeBlock(block),
+	}
+}
+
+function elseRow(block: Block, depth: number): OutlineRow {
+	return {
+		key: `${block.id}${ELSE_KEY_SUFFIX}`,
+		kind: 'else',
+		blockId: block.id,
+		type: block.type,
+		icon: ELSE_ICON,
+		depth,
+		summary: '',
+	}
+}
+
+function rowsOf(block: Block, depth: number): OutlineRow[] {
+	if (block.type !== 'if') return [blockRow(block, depth)]
+	const branches = buildOutline(block.children, depth + 1)
+	if (!block.elseChildren) return [blockRow(block, depth), ...branches]
+	return [
+		blockRow(block, depth),
+		...branches,
+		elseRow(block, depth + 1),
+		...buildOutline(block.elseChildren, depth + 1),
+	]
+}
+
+/** The block tree as indented rows, condition branches nested. */
+export function buildOutline(blocks: Block[], depth = 0): OutlineRow[] {
+	return blocks.flatMap((block) => rowsOf(block, depth))
+}