@antelopejs/dms-mailing 0.4.1 → 0.5.1

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

@@ -0,0 +1,159 @@
+import { useSortable } from '@vueuse/integrations/useSortable'
+import { toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue'
+
+/** What a drop did to a list, as vuedraggable's `change` event said it. */
+export interface SortableListChange<Item> {
+	added?: { element: Item; newIndex: number }
+	removed?: { element: Item; oldIndex: number }
+	moved?: { element: Item; oldIndex: number; newIndex: number }
+}
+
+export interface SortableGroup {
+	name: string
+	/** `'clone'`: the list keeps its items and hands a copy to the other list. */
+	pull?: boolean | 'clone'
+	/** `false`: no item of another list lands here. */
+	put?: boolean
+}
+
+export interface SortableListOptions<Item> {
+	/** Lists sharing a group name exchange items. */
+	group?: string | SortableGroup
+	/** Read again whenever it changes. */
+	disabled?: MaybeRefOrGetter<boolean>
+	/** Only an item grabbed by an element matching this selector moves. */
+	handle?: string
+	/**
+	 * The children that are items, when the list element holds others (a
+	 * footer): the indexes SortableJS reports count these only.
+	 */
+	draggable?: string
+	/** `false`: the items cannot be reordered within the list. */
+	sort?: boolean
+	/** Class of the slot the dragged item will land in. */
+	ghostClass?: string
+	/** What another list receives in place of the dragged item. */
+	clone?: (item: Item) => unknown
+	onChange?: (change: SortableListChange<Item>) => void
+	/** After every drag, whatever it changed. */
+	onEnd?: () => void
+}
+
+/** What the list reads of SortableJS's events. */
+interface SortableEvent {
+	item: HTMLElement
+	clone: HTMLElement
+	oldIndex?: number
+	newIndex?: number
+	pullMode?: boolean | 'clone'
+}
+
+/**
+ * The options the list sets. SortableJS keeps its default only for an option
+ * absent from the object: a key set to `undefined` replaces it (an undefined
+ * `draggable` makes no child an item, so nothing drags).
+ */
+function defined<Options extends object>(options: Options): Partial<Options> {
+	return Object.fromEntries(
+		Object.entries(options).filter(([, value]) => value !== undefined),
+	) as Partial<Options>
+}
+
+/**
+ * The item being dragged, by group. A drop on another list only names the
+ * element, which belongs to the list it left: the list it lands in reads the
+ * item the other one stored when the drag started.
+ */
+const dragged = new Map<string, unknown>()
+
+/**
+ * Lets the user reorder the items of `list` rendered in `root`, or move them
+ * to another list of the same group: SortableJS, through VueUse's
+ * `useSortable`.
+ *
+ * SortableJS moves the dragged element in the DOM itself. Vue owns these
+ * elements, so each drop puts the element back where Vue rendered it and
+ * changes `list` in place instead, from which Vue renders the new order.
+ */
+export function useSortableList<Item>(
+	root: Ref<HTMLElement | null>,
+	list: () => Item[],
+	options: SortableListOptions<Item> = {},
+): void {
+	const groupName =
+		typeof options.group === 'string'
+			? options.group
+			: (options.group?.name ?? '')
+
+	/**
+	 * Where the dragged element stood: next to the node that followed it, not
+	 * at an index, as Vue removes an item by the markers around it.
+	 */
+	let origin: { parent: Node; next: Node | null } | undefined
+
+	function restore(item: HTMLElement): void {
+		if (origin) origin.parent.insertBefore(item, origin.next)
+	}
+
+	const { option } = useSortable(root, list, {
+		...defined({
+			group: options.group,
+			handle: options.handle,
+			draggable: options.draggable,
+			ghostClass: options.ghostClass,
+		}),
+		disabled: toValue(options.disabled) ?? false,
+		sort: options.sort ?? true,
+		onStart: (event: SortableEvent) => {
+			const { parentNode, nextSibling } = event.item
+			origin = parentNode
+				? { parent: parentNode, next: nextSibling }
+				: undefined
+			const element = list()[event.oldIndex ?? -1]
+			if (element === undefined) return
+			dragged.set(groupName, options.clone ? options.clone(element) : element)
+		},
+		onUpdate: (event: SortableEvent) => {
+			const { oldIndex, newIndex } = event
+			if (oldIndex === undefined || newIndex === undefined) return
+			restore(event.item)
+			const items = list()
+			const [element] = items.splice(oldIndex, 1)
+			if (element === undefined) return
+			items.splice(newIndex, 0, element)
+			options.onChange?.({ moved: { element, oldIndex, newIndex } })
+		},
+		onAdd: (event: SortableEvent) => {
+			const element = dragged.get(groupName) as Item | undefined
+			const { newIndex } = event
+			if (element === undefined || newIndex === undefined) return
+			// The element goes back to the list it left, below.
+			event.item.remove()
+			list().splice(newIndex, 0, element)
+			options.onChange?.({ added: { element, newIndex } })
+		},
+		onRemove: (event: SortableEvent) => {
+			restore(event.item)
+			// A copy left: the list keeps its item, and SortableJS's stand-in goes.
+			if (event.pullMode === 'clone') {
+				event.clone.remove()
+				return
+			}
+			const { oldIndex } = event
+			if (oldIndex === undefined) return
+			const [element] = list().splice(oldIndex, 1)
+			if (element === undefined) return
+			options.onChange?.({ removed: { element, oldIndex } })
+		},
+		onEnd: () => {
+			origin = undefined
+			dragged.delete(groupName)
+			options.onEnd?.()
+		},
+	})
+
+	watch(
+		() => toValue(options.disabled) ?? false,
+		(disabled) => option('disabled', disabled),
+	)
+}

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

@@ -1,35 +1,16 @@
 import { useLocalizedDefaults } from './useLocalizedDefaults'
-import { useMailingApi } from './useMailingApi'
-import type { TemplateCategory } from '../types/mailing'
+import { useStoredCategories } from './useMailingReads'
 
 /**
- * The request in flight: the components mounting together (a table's
- * category cells) share it, a later mount asks again since the settings may
- * have changed meanwhile.
+ * 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.
  */
-let pending: Promise<TemplateCategory[]> | null = null
-
-/** The tenant's template categories, loaded once mounted. */
 export function useTemplateCategories() {
-	const api = useMailingApi()
 	const localized = useLocalizedDefaults()
-	const stored = ref<TemplateCategory[]>([])
-	const categories = computed(() => localized.categories(stored.value))
-
-	function listCategories(): Promise<TemplateCategory[]> {
-		pending ??= api
-			.listCategories()
-			.then((response) => response.categories)
-			.catch(() => [])
-			.finally(() => {
-				pending = null
-			})
-		return pending
-	}
-
-	onMounted(async () => {
-		stored.value = await listCategories()
-	})
-
+	const { data, error } = useStoredCategories()
+	const categories = computed(() =>
+		localized.categories(error.value ? [] : (data.value?.categories ?? [])),
+	)
 	return { categories }
 }

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

@@ -9,6 +9,8 @@ export const PALETTE_GROUP = {
 	put: false,
 }
 export const DRAG_HANDLE = '.mailing-drag-handle'
+/** The blocks of a list, not the insert point that ends it. */
+export const DRAG_ITEM = '>[data-drag-item]'
 
 /** The block a tile dropped on the canvas becomes, shaped by its template. */
 export function cloneFromPalette(

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

@@ -148,16 +148,29 @@ export type OnDate = (date: string) => string
 
 const bareDate: OnDate = (date) => date
 
+/** How a card writes a date more than a day old ("Sep 27"). */
+export const CARD_DATE_FORMAT: Intl.DateTimeFormatOptions = {
+	month: 'short',
+	day: '2-digit',
+}
+
 /**
  * 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.
+ * `dateFormat` writes the absolute one: a component passes the DMS's regional
+ * one (`useRegionalFormat().dateTimeFormat(CARD_DATE_FORMAT)`), whose day is
+ * the reader's, on a server render too.
  */
 export function formatCardDate(
 	date: string | null | undefined,
 	now: Date,
 	locale: string,
 	onDate: OnDate = bareDate,
+	dateFormat: Intl.DateTimeFormat = new Intl.DateTimeFormat(
+		locale,
+		CARD_DATE_FORMAT,
+	),
 ): string {
 	const time = date ? new Date(date).getTime() : Number.NaN
 	if (Number.isNaN(time)) return ''
@@ -172,12 +185,7 @@ export function formatCardDate(
 	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)),
-	)
+	return onDate(dateFormat.format(new Date(time)))
 }
 
 /**
@@ -194,12 +202,16 @@ export function formatCardSince(
 	date: string | null | undefined,
 	now: Date,
 	locale: string,
+	dateFormat?: Intl.DateTimeFormat,
 ): 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) }
+		return {
+			kind: 'date',
+			text: formatCardDate(date, now, locale, undefined, dateFormat),
+		}
 	const isHours = elapsed >= MS_PER_HOUR
 	const amount = Math.max(
 		1,

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

@@ -25,11 +25,6 @@ export function minutesSince(
 	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()

package/frontend-vue/i18n/locales/mailing-en-GB.json

@@ -804,7 +804,7 @@
 				},
 				"webhookUrl": {
 					"label": "Webhook URL",
-					"description": "Your provider, or the relay that translates its events, posts them here with the secret below. The module README describes the format."
+					"description": "Your provider, or the relay that translates its events, posts them here with the secret below. The module documentation describes the format."
 				},
 				"webhookStatus": {
 					"label": "Webhook status",

package/frontend-vue/i18n/locales/mailing-fr-FR.json

@@ -804,7 +804,7 @@
 				},
 				"webhookUrl": {
 					"label": "URL du webhook",
-					"description": "Votre fournisseur, ou le relais qui traduit ses événements, les envoie ici avec le secret ci-dessous. Le README du module décrit le format."
+					"description": "Votre fournisseur, ou le relais qui traduit ses événements, les envoie ici avec le secret ci-dessous. La documentation du module décrit le format."
 				},
 				"webhookStatus": {
 					"label": "État du webhook",

package/frontend-vue/package.json

@@ -6,7 +6,7 @@
 	"license": "Apache-2.0",
 	"packageManager": "pnpm@10.2.0",
 	"engines": {
-		"@antelopejs/dms-frontend": ">=0.5.5 <0.6.0"
+		"@antelopejs/dms-frontend": ">=0.6.3 <0.7.0"
 	},
 	"scripts": {
 		"format": "prettier --write .",
@@ -16,8 +16,9 @@
 	},
 	"dependencies": {
 		"@vueuse/core": "^14.3.0",
-		"vue": "^3.5.18",
-		"vuedraggable": "^4.1.0"
+		"@vueuse/integrations": "^14.3.0",
+		"sortablejs": "^1.14.0",
+		"vue": "^3.5.18"
 	},
 	"devDependencies": {
 		"@nuxt/ui": "4.10.0",

package/frontend-vue/pnpm-lock.yaml

@@ -11,12 +11,15 @@ importers:
       '@vueuse/core':
         specifier: ^14.3.0
         version: 14.4.0(vue@3.5.42(typescript@5.9.3))
+      '@vueuse/integrations':
+        specifier: ^14.3.0
+        version: 14.4.0(fuse.js@7.5.0)(sortablejs@1.14.0)(vue@3.5.42(typescript@5.9.3))
+      sortablejs:
+        specifier: ^1.14.0
+        version: 1.14.0
       vue:
         specifier: ^3.5.18
         version: 3.5.42(typescript@5.9.3)
-      vuedraggable:
-        specifier: ^4.1.0
-        version: 4.1.0(vue@3.5.42(typescript@5.9.3))
     devDependencies:
       '@nuxt/ui':
         specifier: 4.10.0
@@ -3154,11 +3157,6 @@ packages:
       typescript:
         optional: true
 
-  vuedraggable@4.1.0:
-    resolution: {integrity: sha512-FU5HCWBmsf20GpP3eudURW3WdWTKIbEIQxh9/8GE806hydR9qZqRRxRE3RjqX7PkuLuMQG/A7n3cfj9rCEchww==}
-    peerDependencies:
-      vue: ^3.0.1
-
   w3c-keyname@2.2.8:
     resolution: {integrity: sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==}
 
@@ -6245,11 +6243,6 @@ snapshots:
     optionalDependencies:
       typescript: 5.9.3
 
-  vuedraggable@4.1.0(vue@3.5.42(typescript@5.9.3)):
-    dependencies:
-      sortablejs: 1.14.0
-      vue: 3.5.42(typescript@5.9.3)
-
   w3c-keyname@2.2.8: {}
 
   w3c-xmlserializer@5.0.0:

package/frontend-vue/tests/categories-input.test.ts

@@ -9,14 +9,9 @@ import {
 	stubNuxtGlobals,
 	type Mounted,
 } from './helpers/nuxt-globals'
+import { stubApiData, type ApiDataStub } from './helpers/api-data'
 import type { TemplateCategory } from '../app/types/mailing'
 
-vi.mock('../app/composables/useMailingApi', () => ({
-	useMailingApi: () => ({
-		categoryUsage: async () => ({ counts: {} }),
-	}),
-}))
-
 vi.mock('../app/composables/useLocalizedDefaults', () => ({
 	useLocalizedDefaults: () => ({
 		categories: (list: TemplateCategory[]) => list,
@@ -70,17 +65,19 @@ const ButtonStub = defineComponent({
 			h('button', { ...attrs, 'data-icon': props.icon }),
 })
 
+const GLOBALS = {
+	UFormField: FormFieldStub,
+	UButton: ButtonStub,
+	UPopover: slotStub('UPopover'),
+	DmsEyebrow: slotStub('DmsEyebrow'),
+	DmsInputText: slotStub('DmsInputText'),
+}
+
 function mountInput(): Mounted {
 	return mount(
 		CategoriesInput,
 		{ modelValue: CATEGORIES, initialValue: CATEGORIES },
-		{
-			UFormField: FormFieldStub,
-			UButton: ButtonStub,
-			UPopover: slotStub('UPopover'),
-			DmsEyebrow: slotStub('DmsEyebrow'),
-			DmsInputText: slotStub('DmsInputText'),
-		},
+		GLOBALS,
 	)
 }
 
@@ -90,10 +87,43 @@ function alerts(host: HTMLElement): HTMLElement[] {
 
 describe('CategoriesInput', () => {
 	let mounted: Mounted | undefined
+	let api: ApiDataStub
 
 	beforeEach(() => {
 		stubNuxtGlobals()
 		formErrors.clear()
+		api = stubApiData()
+		api.respond(() => ({ counts: {} }))
+	})
+
+	it('shows how many templates each category holds, read again once saved', async () => {
+		api.respond(() => ({ counts: { orders: 2 } }))
+		const saved = reactive({ value: CATEGORIES })
+		mounted = mount(
+			defineComponent({
+				setup: () => () =>
+					h(CategoriesInput, {
+						modelValue: saved.value,
+						initialValue: saved.value,
+					}),
+			}),
+			{},
+			GLOBALS,
+		)
+		await flush()
+		expect(mounted.host.textContent).toContain(
+			'dms_mailing.settings.categories.usage count=2',
+		)
+		expect(api.reads).toEqual([
+			{ url: '/api/mailing/settings/category-usage', query: {} },
+		])
+		api.respond(() => ({ counts: { orders: 3 } }))
+		saved.value = [...CATEGORIES]
+		await flush()
+		expect(api.reads).toHaveLength(2)
+		expect(mounted.host.textContent).toContain(
+			'dms_mailing.settings.categories.usage count=3',
+		)
 	})
 
 	afterEach(() => {

package/frontend-vue/tests/editor-block-list.test.ts

@@ -12,6 +12,24 @@ import EditorBlockList from '../app/components/editor/EditorBlockList.vue'
 import type { Block } from '../app/types/mailing'
 
 const editor = vi.hoisted(() => ({ touch: vi.fn(), select: vi.fn() }))
+const sortables = vi.hoisted(
+	() => [] as { el: HTMLElement; options: Record<string, unknown> }[],
+)
+
+// What SortableJS would be handed: the test calls it as SortableJS does.
+vi.mock('@vueuse/integrations/useSortable', async () => {
+	const { onMounted, unref } = await import('vue')
+	return {
+		useSortable: (
+			target: { value: HTMLElement },
+			_list: unknown,
+			options: Record<string, unknown>,
+		) => {
+			onMounted(() => sortables.push({ el: unref(target), options }))
+			return { option: () => {} }
+		},
+	}
+})
 
 vi.mock('../app/composables/useEditorContext', () => ({
 	useEditorContext: () => ({ editor }),
@@ -60,14 +78,36 @@ describe('editor draggable items', () => {
 	})
 	it('selects a block dropped into the list', async () => {
 		vi.stubGlobal('useI18n', () => ({ t: (key: string) => key }))
-		const list = reactive<Block[]>([])
-		const app = createApp(EditorBlockList, { list })
+		sortables.length = 0
+		const source = reactive<Block[]>([
+			{ id: 'dropped', type: 'divider', visibleIf: null },
+		])
+		const target = reactive<Block[]>([])
+		const app = createApp({
+			render: () => [
+				h(EditorBlockList, { list: source }),
+				h(EditorBlockList, { list: target }),
+			],
+		})
 		app.mount(document.createElement('div'))
 		try {
-			const draggable = app._instance?.subTree.props as Record<string, unknown>
-			const onChange = draggable.onChange as (change: unknown) => void
-			onChange({ added: { element: { id: 'dropped' }, newIndex: 0 } })
-			onChange({ moved: { element: { id: 'other' } } })
+			const [from, to] = sortables
+			expect(from!.options).toMatchObject({
+				group: { name: 'mailing-blocks' },
+				handle: '.mailing-drag-handle',
+				draggable: '>[data-drag-item]',
+			})
+			const item = from!.el.querySelector('[data-drag-item]') as HTMLElement
+			const handler = (sortable: typeof from, name: string) =>
+				sortable!.options[name] as (event: unknown) => void
+			handler(from, 'onStart')({ item, oldIndex: 0 })
+			to!.el.prepend(item)
+			handler(to, 'onAdd')({ item, newIndex: 0 })
+			handler(from, 'onRemove')({ item, oldIndex: 0 })
+			handler(from, 'onEnd')({})
+			await nextTick()
+			expect(source).toEqual([])
+			expect(target.map((block) => block.id)).toEqual(['dropped'])
 			expect(editor.touch).toHaveBeenCalledTimes(2)
 			expect(editor.select).toHaveBeenCalledExactlyOnceWith('dropped')
 		} finally {

package/frontend-vue/tests/editor-session.test.ts

@@ -73,6 +73,10 @@ function setup(): Harness {
 			harness.session = useEditorSession({
 				editor: harness.editor,
 				api: api as unknown as MailingApi,
+				reads: {
+					changes: () => api.changes('t1'),
+					performance: async () => null as never,
+				},
 				templateId: 't1',
 				loaded: LOADED,
 				onError: (error) => errors.push(error),

package/frontend-vue/tests/gallery.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import {
 	UNCATEGORISED_GROUP_ID,
 	firstName,
+	CARD_DATE_FORMAT,
 	formatCardDate,
 	formatCardSince,
 	groupByCategory,
@@ -92,6 +93,21 @@ describe('formatCardDate', () => {
 		expect(formatCardDate('2026-09-27T09:00:00Z', now, 'en')).toBe('Sep 27')
 	})
 
+	it("writes the date with the formatter given: a server writes the reader's day", () => {
+		const late = '2026-09-27T02:00:00Z'
+		const inZone = (timeZone: string) =>
+			new Intl.DateTimeFormat('en', { ...CARD_DATE_FORMAT, timeZone })
+		expect(
+			formatCardDate(late, now, 'en', undefined, inZone('Europe/Paris')),
+		).toBe('Sep 27')
+		expect(
+			formatCardDate(late, now, 'en', undefined, inZone('America/New_York')),
+		).toBe('Sep 26')
+		expect(
+			formatCardSince(late, now, 'en', inZone('America/New_York')),
+		).toEqual({ kind: 'date', text: 'Sep 26' })
+	})
+
 	it('answers nothing for an unreadable date', () => {
 		expect(formatCardDate('', now, 'en')).toBe('')
 		expect(formatCardDate('nope', now, 'en')).toBe('')