@antelopejs/dms-mailing 0.3.3 → 0.4.0

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

@@ -1,41 +1,139 @@
 <script setup lang="ts">
+import { useTemplateCategories } from '../composables/useTemplateCategories'
+import { useEventListener } from '@vueuse/core'
+import { useMailingApi } from '../composables/useMailingApi'
+import { useTemplateDrawer } from '../composables/useTemplateDrawer'
+import {
+	groupByCategory,
+	isAttentionView,
+	isNarrowed,
+	searchTermOf,
+	sortKeyOf,
+	userFilterKeys,
+	type CategoryGroup,
+	type GalleryContext,
+} from '../utils/gallery'
+import { attentionReasons } from '../utils/template-attention'
 import { editorRoute } from '../utils/editor-route'
-import { groupByCategory } from '../utils/gallery'
-import type { GalleryDisplayContext } from '../types/component'
-import type { TemplateCategory, TemplateRow } from '../types/mailing'
+import { TEMPLATES_PATH } from '../utils/pages'
+import type {
+	TemplateCategory,
+	TemplateRow,
+	TemplateStats,
+} from '../types/mailing'
 
 interface TemplateGalleryProps {
-	context: GalleryDisplayContext<TemplateRow>
+	context: GalleryContext<TemplateRow>
 }
 
+type GalleryState = 'loading' | 'first_run' | 'empty' | 'no_attention' | 'grid'
+
+type StateRule = [GalleryState, () => boolean]
+
 const FIRST_PAGE = 1
+const PAGES_MODE = 'pages'
+const SKELETON_CARDS = 3
+const NEW_TEMPLATE_KEY = 'n'
+const TYPING_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT'])
+const OPEN_OVERLAY_SELECTOR = '[role="dialog"], [role="menu"]'
+/** The table's default sort: the only one the category groups keep. */
+const DEFAULT_SORT_KEY = 'updatedAt'
+const FLAT_GROUP: TemplateCategory = { id: 'all', label: '', icon: '' }
+/** The tab "Show all templates" leaves the attention tab for. */
+const ALL_TAB = 'all'
 
 const props = defineProps<TemplateGalleryProps>()
 
 const api = useMailingApi()
 const { t } = useI18n()
-const { open: openTemplateDrawer } = useTemplateDrawer()
-const { open: openTestSendModal } = useTestSendModal()
-
-// Fetched, not read from the page options: the tenant edits them in Settings,
-// and a page declaration is serialised once, at registration.
-const categories = ref<TemplateCategory[]>([])
-
-onMounted(async () => {
-	try {
-		const response = await api.listCategories()
-		categories.value = response.categories
-	} catch {
-		categories.value = []
-	}
+const overlays = useTemplateDrawer()
+
+const { categories } = useTemplateCategories()
+const statsById = ref(new Map<string, TemplateStats>())
+const templateCount = ref<number | null>(null)
+
+async function loadStats(): Promise<void> {
+	const response = await api.templatesOverview().catch(() => ({ items: [] }))
+	statsById.value = new Map(response.items.map((entry) => [entry.id, entry]))
+}
+
+async function loadTemplates(): Promise<void> {
+	const response = await api.listTemplates().catch(() => null)
+	templateCount.value = response ? response.total : null
+}
+
+onMounted(() => {
+	void loadStats()
+	void loadTemplates()
 })
 
-const groups = computed(() =>
-	groupByCategory(
-		props.context.items,
-		categories.value,
-		t('dms_mailing.templates.uncategorised'),
-	),
+/** The page of the table on screen: its query and its page index. */
+const viewKeyOf = (): string =>
+	JSON.stringify([props.context.query, props.context.pagination.pageIndex])
+
+/** The view whose rows are on screen; none while the first rows load. */
+let shownViewKey = props.context.loading ? null : viewKeyOf()
+
+/**
+ * New rows for the same page and query come from a refresh (the table's
+ * button, a realtime change): the template count and the figures are reloaded
+ * with them.
+ */
+watch(
+	() => props.context.items,
+	() => {
+		const viewKey = viewKeyOf()
+		const isRefresh = viewKey === shownViewKey
+		shownViewKey = viewKey
+		if (!isRefresh) return
+		void loadStats()
+		void loadTemplates()
+	},
+)
+
+const isAttentionTab = computed(() => isAttentionView(props.context.query))
+
+const isGrouped = computed(
+	() =>
+		(sortKeyOf(props.context.query) ?? DEFAULT_SORT_KEY) === DEFAULT_SORT_KEY,
+)
+
+const groups = computed<CategoryGroup<TemplateRow>[]>(() =>
+	isGrouped.value
+		? groupByCategory(
+				props.context.items,
+				categories.value,
+				t('dms_mailing.templates.uncategorised'),
+			)
+		: [{ category: FLAT_GROUP, items: props.context.items }],
+)
+
+/** The cards in the order drawn, for the drawer's previous / next. */
+const drawnItems = computed(() => groups.value.flatMap((group) => group.items))
+
+const search = computed(() => searchTermOf(props.context.query))
+const narrowed = computed(() => isNarrowed(props.context.query))
+const hasNoItems = computed(() => !props.context.items.length)
+
+const STATE_RULES: StateRule[] = [
+	['loading', () => props.context.loading && hasNoItems.value],
+	[
+		'loading',
+		() => hasNoItems.value && !narrowed.value && templateCount.value === null,
+	],
+	[
+		'first_run',
+		() => hasNoItems.value && !narrowed.value && templateCount.value === 0,
+	],
+	[
+		'no_attention',
+		() => isAttentionTab.value && hasNoItems.value && !narrowed.value,
+	],
+	['empty', () => hasNoItems.value],
+]
+
+const state = computed<GalleryState>(
+	() => STATE_RULES.find(([, matches]) => matches())?.[0] ?? 'grid',
 )
 
 const page = computed({
@@ -43,38 +141,158 @@ const page = computed({
 	set: (value: number) => props.context.pagination.setPage(value - FIRST_PAGE),
 })
 
-function openEditor(template: TemplateRow, locale?: string): void {
-	void navigateDms(editorRoute(template._id, locale))
+const isPaged = computed(
+	() => (props.context.pagination.mode ?? PAGES_MODE) === PAGES_MODE,
+)
+
+const emptyTitle = computed(() =>
+	search.value
+		? t('dms_mailing.templates.empty.no_match_title', { search: search.value })
+		: t('dms_mailing.templates.empty.view_title'),
+)
+
+const emptyDescription = computed(() =>
+	search.value
+		? t('dms_mailing.templates.empty.no_match_description')
+		: t('dms_mailing.templates.empty.view_description'),
+)
+
+function refreshAll(): void {
+	void props.context.refresh()
+	void loadStats()
+	void loadTemplates()
 }
+
+function openRow(row: TemplateRow): void {
+	if (props.context.actions) {
+		props.context.actions.open(row)
+		return
+	}
+	void navigateDms(editorRoute(row._id))
+}
+
+function openLocale(row: TemplateRow, code: string): void {
+	void navigateDms(editorRoute(row._id, code))
+}
+
+function openNewTemplate(initialName?: string): void {
+	overlays.openNewTemplate({ initialName, onDone: refreshAll })
+}
+
+function showAllTemplates(): void {
+	void navigateDms({ path: TEMPLATES_PATH, query: { tab: ALL_TAB } })
+}
+
+function resetFilters(): void {
+	const table = props.context.table
+	table?.setGlobalFilter('')
+	if (!table || userFilterKeys(props.context.query).length) {
+		void navigateDms({ path: TEMPLATES_PATH })
+	}
+}
+
+function isTypingTarget(target: EventTarget | null): boolean {
+	const element = target as HTMLElement | null
+	if (!element) return false
+	return element.isContentEditable || TYPING_TAGS.has(element.tagName)
+}
+
+useEventListener(
+	typeof document === 'undefined' ? undefined : document,
+	'keydown',
+	(event: KeyboardEvent) => {
+		if (event.key.toLowerCase() !== NEW_TEMPLATE_KEY) return
+		if (event.metaKey || event.ctrlKey || event.altKey) return
+		if (isTypingTarget(event.target)) return
+		if (document.querySelector(OPEN_OVERLAY_SELECTOR)) return
+		event.preventDefault()
+		openNewTemplate()
+	},
+)
 </script>
 
 <template>
 	<div class="flex flex-col gap-6 p-4">
-		<USkeleton v-if="context.loading && !groups.length" class="h-64 w-full" />
-
 		<div
-			v-else-if="!groups.length"
-			class="flex flex-col items-center gap-3 py-16 text-center"
+			v-if="state === 'loading'"
+			class="grid grid-cols-[repeat(auto-fill,minmax(272px,1fr))] gap-4"
+			aria-busy="true"
 		>
-			<UIcon name="i-ph-envelope-simple" class="text-dimmed size-8" />
-			<h3 class="text-highlighted text-sm font-semibold">
-				{{ t('dms_mailing.templates.empty.title') }}
-			</h3>
-			<p class="text-muted text-[13px]">
-				{{ t('dms_mailing.templates.empty.hint') }}
-			</p>
-			<UButton
-				color="neutral"
-				variant="ghost"
-				size="sm"
-				:label="t('dms_mailing.templates.empty.reset')"
-				@click="context.refresh()"
-			/>
+			<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-else class="flex flex-col gap-6">
-			<div v-for="group in groups" :key="group.category.id">
-				<div class="mb-3 flex items-center gap-2">
+		<MailingStarterGallery
+			v-else-if="state === 'first_run'"
+			@created="refreshAll"
+		/>
+
+		<DmsEmptyState
+			v-else-if="state === 'empty'"
+			:title="emptyTitle"
+			:description="emptyDescription"
+			variant="no-result"
+			icon="i-ph-magnifying-glass"
+			size="lg"
+			hatched
+		>
+			<template #actions>
+				<UButton
+					v-if="narrowed"
+					icon="i-ph-x"
+					color="neutral"
+					variant="outline"
+					size="sm"
+					:label="t('dms_mailing.templates.empty.reset')"
+					@click="resetFilters"
+				/>
+				<UButton
+					icon="i-ph-plus"
+					size="sm"
+					:label="
+						search
+							? t('dms_mailing.templates.empty.create_named', { name: search })
+							: t('dms_mailing.templates.actions.create')
+					"
+					@click="openNewTemplate(search || undefined)"
+				/>
+			</template>
+		</DmsEmptyState>
+
+		<DmsEmptyState
+			v-else-if="state === 'no_attention'"
+			:title="t('dms_mailing.templates.attention.none_title')"
+			:description="t('dms_mailing.templates.attention.none_description')"
+			icon="i-ph-check-circle"
+			tone="success"
+			size="md"
+			:actions="[
+				{
+					label: t('dms_mailing.templates.attention.show_all'),
+					color: 'neutral',
+					variant: 'outline',
+					onClick: showAllTemplates,
+				},
+			]"
+		/>
+
+		<template v-else>
+			<section
+				v-for="(group, index) in groups"
+				:key="group.category.id"
+				class="flex flex-col gap-3"
+			>
+				<div v-if="isGrouped" class="flex items-center gap-2">
 					<UIcon :name="group.category.icon" class="text-dimmed size-4" />
 					<h2 class="text-highlighted text-[13px] font-semibold">
 						{{ group.category.label }}
@@ -82,24 +300,49 @@ function openEditor(template: TemplateRow, locale?: string): void {
 					<span class="text-dimmed font-mono text-[11.5px]">
 						{{ group.items.length }}
 					</span>
-					<span class="bg-default ml-2 h-px flex-1" />
+					<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">
-					<DmsMailingTemplateCard
+					<MailingTemplateCard
 						v-for="template in group.items"
 						:key="template._id"
 						:template="template"
-						@open="openEditor(template)"
-						@open-locale="(code: string) => openEditor(template, code)"
-						@details="openTemplateDrawer(template._id)"
-						@test-send="openTestSendModal(template._id)"
+						:stats="statsById.get(template._id)"
+						:attention="attentionReasons(template)"
+						@open="openRow(template)"
+						@open-locale="(code: string) => openLocale(template, code)"
+						@details="
+							overlays.openDetails(template, {
+								rows: drawnItems,
+								onDone: refreshAll,
+							})
+						"
+						@test-send="overlays.openTestSend(template._id)"
+						@real-send="
+							overlays.openRealSend(template._id, {
+								rowData: template,
+								onDone: refreshAll,
+							})
+						"
 					/>
+					<button
+						v-if="index === groups.length - 1"
+						type="button"
+						class="border-default text-muted hover:border-primary/60 hover:text-highlighted focus-visible:outline-primary rounded-(--dms-radius-card) flex min-h-[260px] flex-col items-center justify-center gap-2 border border-dashed text-[13px] font-medium transition-colors focus-visible:outline-2"
+						@click="openNewTemplate()"
+					>
+						<DmsIconWell icon="i-ph-plus" size="md" />
+						{{ t('dms_mailing.templates.gallery.new_tile') }}
+						<span class="text-dimmed text-[11.5px] font-normal">
+							{{ t('dms_mailing.templates.gallery.new_tile_hint') }}
+						</span>
+					</button>
 				</div>
-			</div>
-		</div>
+			</section>
+		</template>
 
 		<div
-			v-if="context.pagination.total > context.pagination.pageSize"
+			v-if="isPaged && context.pagination.total > context.pagination.pageSize"
 			class="flex justify-end"
 		>
 			<UPagination
@@ -108,5 +351,18 @@ function openEditor(template: TemplateRow, locale?: string): void {
 				:total="context.pagination.total"
 			/>
 		</div>
+		<div
+			v-else-if="!isPaged && context.pagination.hasMore"
+			class="flex justify-center"
+		>
+			<UButton
+				color="neutral"
+				variant="outline"
+				size="sm"
+				:loading="context.loading"
+				:label="t('dms_mailing.templates.gallery.load_more')"
+				@click="context.pagination.loadMore?.()"
+			/>
+		</div>
 	</div>
 </template>

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

@@ -1,51 +1,120 @@
 <script setup lang="ts">
-import { useDebounceFn } from '@vueuse/core'
-import type { PreviewResponse, TemplateContent } from '../types/mailing'
+import { useDebounceFn, useIntersectionObserver } from '@vueuse/core'
+import { useMailingApi } from '../composables/useMailingApi'
+import type {
+	PreviewResponse,
+	PreviewVersion,
+	TemplateContent,
+} from '../types/mailing'
 
 interface TemplatePreviewFrameProps {
-	templateId: string
-	/** Absent renders the tenant fallback locale, chosen server-side. */
+	/** The template to render; ignored when `html` or `starterId` is given. */
+	templateId?: string
+	/** A starter to render, through its own preview endpoint. */
+	starterId?: string
+	/** Ready-made HTML: nothing is fetched. */
+	html?: string
+	/**
+	 * Absent renders the tenant fallback locale, chosen server-side; a starter
+	 * then renders in the interface's language when it has it.
+	 */
 	locale?: string
+	/** Which saved content to render when `content` is absent. */
+	version?: PreviewVersion
 	content?: TemplateContent
 	data?: Record<string, unknown>
 	width: number
 	scale?: number
 	refreshKey?: number
+	/** Fetches only once the frame scrolls into view (galleries). */
+	lazy?: boolean
+	/** Accessible name of the frame. */
+	label?: string
+	/**
+	 * A thumbnail: out of the accessibility tree and the tab order (the card
+	 * around it names the template).
+	 */
+	decorative?: boolean
 }
 
 const DEBOUNCE_MS = 300
 const FALLBACK_HEIGHT = 480
+const NO_SCROLL_STYLE = '<style>html,body{overflow:hidden}</style>'
+const HEAD_END = /<\/head>/i
 
 const props = withDefaults(defineProps<TemplatePreviewFrameProps>(), {
+	templateId: undefined,
+	starterId: undefined,
+	html: undefined,
 	locale: undefined,
+	version: undefined,
 	content: undefined,
 	data: undefined,
 	scale: 1,
 	refreshKey: 0,
+	lazy: false,
+	label: undefined,
+	decorative: false,
 })
 
 const emit = defineEmits<{ resolved: [PreviewResponse] }>()
 
 const api = useMailingApi()
+const { locale: uiLocale } = useI18n()
 
-const html = ref('')
+const fetchedHtml = ref('')
 const loading = ref(false)
 const height = ref(FALLBACK_HEIGHT)
 const frame = ref<HTMLIFrameElement | null>(null)
+const box = ref<HTMLElement | null>(null)
+const isVisible = ref(!props.lazy)
+
+/**
+ * The HTML with scrolling turned off inside its own document: the frame is
+ * sized to the content, a scrollbar would only eat its width.
+ */
+function withoutScroll(html: string): string {
+	if (!html) return html
+	return HEAD_END.test(html)
+		? html.replace(HEAD_END, `${NO_SCROLL_STYLE}</head>`)
+		: `${NO_SCROLL_STYLE}${html}`
+}
+
+const shownHtml = computed(() => withoutScroll(props.html ?? fetchedHtml.value))
+
+useIntersectionObserver(box, ([entry]) => {
+	if (entry?.isIntersecting) isVisible.value = true
+})
+
+async function fetchStarter(starterId: string): Promise<void> {
+	const preview = await api.starterPreview(
+		starterId,
+		props.locale ?? uiLocale.value,
+	)
+	fetchedHtml.value = preview.html
+}
+
+async function fetchTemplate(templateId: string): Promise<void> {
+	const preview = await api.preview(templateId, {
+		locale: props.locale,
+		version: props.content ? undefined : props.version,
+		content: props.content,
+		data: props.data,
+	})
+	fetchedHtml.value = preview.html
+	emit('resolved', preview)
+}
 
 async function load(): Promise<void> {
-	if (!props.templateId) return
+	if (props.html !== undefined || !isVisible.value) return
+	if (!props.starterId && !props.templateId) return
 	loading.value = true
 	try {
-		const preview = await api.preview(props.templateId, {
-			locale: props.locale,
-			content: props.content,
-			data: props.data,
-		})
-		html.value = preview.html
-		emit('resolved', preview)
+		await (props.starterId
+			? fetchStarter(props.starterId)
+			: fetchTemplate(props.templateId as string))
 	} catch {
-		html.value = ''
+		fetchedHtml.value = ''
 	} finally {
 		loading.value = false
 	}
@@ -53,20 +122,34 @@ async function load(): Promise<void> {
 
 const reload = useDebounceFn(load, DEBOUNCE_MS)
 
-// srcdoc keeps the frame same-origin, so allow-same-origin is what lets the
-// height be measured; scripts stay blocked.
+/**
+ * The content's full height, the body's bottom margin included: its
+ * `scrollHeight` leaves the margins out and the frame would scroll by them.
+ */
 function measure(): void {
 	const body = frame.value?.contentDocument?.body
-	height.value = body?.scrollHeight || FALLBACK_HEIGHT
+	const view = frame.value?.contentWindow
+	if (!body || !view) {
+		height.value = FALLBACK_HEIGHT
+		return
+	}
+	const bottom =
+		body.getBoundingClientRect().bottom +
+		parseFloat(view.getComputedStyle(body).marginBottom)
+	height.value = Math.ceil(bottom) || FALLBACK_HEIGHT
 }
 
 watch(
 	() => [
 		props.templateId,
+		props.starterId,
+		props.starterId ? uiLocale.value : undefined,
 		props.locale,
+		props.version,
 		props.content,
 		props.data,
 		props.refreshKey,
+		isVisible.value,
 	],
 	() => reload(),
 	{ immediate: true, deep: true },
@@ -86,15 +169,22 @@ const frameStyle = computed(() => ({
 </script>
 
 <template>
-	<div class="relative overflow-hidden" :style="boxStyle">
-		<USkeleton v-if="loading && !html" class="absolute inset-0 size-full" />
+	<div ref="box" class="relative overflow-hidden" :style="boxStyle">
+		<USkeleton
+			v-if="!shownHtml && (loading || !isVisible)"
+			class="absolute inset-0 size-full"
+		/>
 		<iframe
-			v-show="html"
+			v-show="shownHtml"
 			ref="frame"
-			:srcdoc="html"
+			:srcdoc="shownHtml"
 			sandbox="allow-same-origin"
 			loading="lazy"
-			title="preview"
+			tabindex="-1"
+			:title="label ?? 'preview'"
+			:aria-hidden="decorative ? 'true' : undefined"
+			:inert="decorative || undefined"
+			scrolling="no"
 			class="block border-0 bg-white"
 			:style="frameStyle"
 			@load="measure"