@antelopejs/dms-mailing 0.4.1 → 0.5.1

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

@@ -1,5 +1,6 @@
 <script setup lang="ts">
-import draggable from 'vuedraggable'
+import { ref } from 'vue'
+import { useSortableList } from '../../composables/useSortableList'
 import {
 	PALETTE_GROUP,
 	cloneFromPalette,
@@ -23,23 +24,22 @@ const emit = defineEmits<{ add: [PaletteEntry] }>()
 
 const { t } = useI18n()
 
-const clone = (entry: PaletteEntry) =>
-	cloneFromPalette(entry, props.blockContext())
+const root = ref<HTMLElement | null>(null)
+
+// A tile stays in the palette: the canvas receives the block it stands for.
+useSortableList(root, () => props.entries, {
+	group: PALETTE_GROUP,
+	sort: false,
+	disabled: () => props.disabled,
+	clone: (entry) => cloneFromPalette(entry, props.blockContext()),
+})
 </script>
 
 <template>
 	<section>
 		<DmsEyebrow :label="title" class="mb-2 block" />
-		<draggable
-			:list="entries"
-			:group="PALETTE_GROUP"
-			:clone="clone"
-			:sort="false"
-			:disabled="disabled"
-			item-key="type"
-			class="grid grid-cols-2 gap-1.5"
-		>
-			<template #item="{ element }">
+		<div ref="root" class="grid grid-cols-2 gap-1.5">
+			<template v-for="element in entries" :key="element.type">
 				<button
 					type="button"
 					class="border-default bg-default text-toned hover:border-primary/60 hover:text-highlighted group flex min-h-9 cursor-grab items-center gap-2 rounded-md border px-2.5 py-1 text-left text-xs transition disabled:cursor-not-allowed disabled:opacity-50"
@@ -61,6 +61,6 @@ const clone = (entry: PaletteEntry) =>
 					</span>
 				</button>
 			</template>
-		</draggable>
+		</div>
 	</section>
 </template>

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

@@ -2,6 +2,7 @@
 import { onMounted, watch } from 'vue'
 import type { TemplateContentResponse } from '../../types/mailing'
 import { useMailingApi } from '../../composables/useMailingApi'
+import { useEditorReads } from '../../composables/useMailingReads'
 import { provideEditorContext } from '../../composables/useEditorContext'
 import { useEditorActions } from '../../composables/useEditorActions'
 import { useEditorSession } from '../../composables/useEditorSession'
@@ -49,9 +50,12 @@ function reportFailure(error: unknown): void {
 	})
 }
 
+const reads = useEditorReads(props.templateId)
+
 const session = useEditorSession({
 	editor,
 	api,
+	reads,
 	templateId: props.templateId,
 	loaded: props.loaded,
 	onError: reportFailure,
@@ -61,6 +65,7 @@ const actions = useEditorActions({
 	editor,
 	session,
 	api,
+	reads,
 	templateId: props.templateId,
 	reload: props.reload,
 	onError: reportFailure,

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

@@ -1,5 +1,6 @@
 import type { Component } from 'vue'
 import type { MailingApi } from './useMailingApi'
+import type { EditorReads } from './useMailingReads'
 import type { EditorSession } from './useEditorSession'
 import { isDraftConflict } from './useEditorSession'
 import type { EditorState } from './useTemplateEditor'
@@ -34,6 +35,7 @@ export interface ActionDeps {
 	editor: EditorState
 	session: EditorSession
 	api: MailingApi
+	reads: EditorReads
 	templateId: string
 	reload: () => Promise<void>
 	onError: (error: unknown) => void
@@ -163,7 +165,7 @@ async function runPublish(deps: ActionDeps, tools: ActionTools): Promise<void> {
  * editor's last write is a conflict: the review would not show what ships.
  */
 async function refreshChanges(deps: ActionDeps): Promise<boolean> {
-	const response = await deps.api.changes(deps.templateId).catch(() => null)
+	const response = await deps.reads.changes().catch(() => null)
 	if (!response) return true
 	const { state } = deps.session
 	if (response.revision !== state.revision) {

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

@@ -8,6 +8,7 @@ import type {
 	TemplateRow,
 } from '../types/mailing'
 import type { MailingApi, TemplateDetails } from './useMailingApi'
+import type { EditorReads } from './useMailingReads'
 import type { EditorState } from './useTemplateEditor'
 import type { TokenFieldHandle } from './useEditorContext'
 import { deepClone } from '../utils/clone'
@@ -64,6 +65,7 @@ export interface SessionState {
 export interface SessionDeps {
 	editor: EditorState
 	api: MailingApi
+	reads: EditorReads
 	templateId: string
 	loaded: TemplateContentResponse
 	onError: (error: unknown) => void
@@ -142,7 +144,7 @@ export function retryDelay(failures: number): number {
 }
 
 function createSaver(deps: SessionDeps, state: SessionState) {
-	const { editor, api, templateId, onError } = deps
+	const { editor, api, reads, templateId, onError } = deps
 	let timer: ReturnType<typeof setTimeout> | null = null
 	let inFlight: Promise<boolean> | null = null
 	let failures = 0
@@ -207,7 +209,7 @@ function createSaver(deps: SessionDeps, state: SessionState) {
 	async function overwrite(): Promise<boolean> {
 		cancel()
 		if (inFlight) await inFlight
-		const latest = await api.changes(templateId).catch(() => null)
+		const latest = await reads.changes().catch(() => null)
 		if (!latest) return false
 		state.revision = latest.revision
 		return run()
@@ -249,7 +251,7 @@ function createSaver(deps: SessionDeps, state: SessionState) {
 }
 
 function createRecordActions(
-	{ api, templateId }: SessionDeps,
+	{ api, reads, templateId }: SessionDeps,
 	state: SessionState,
 ) {
 	return {
@@ -274,7 +276,7 @@ function createRecordActions(
 			state.testDataSource = state.savedTestDataSource
 		},
 		async loadPerformance(): Promise<void> {
-			state.performance = await api.performance(templateId).catch(() => null)
+			state.performance = await reads.performance().catch(() => null)
 		},
 	}
 }

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

@@ -2,29 +2,22 @@ import type {
 	FunnelStep,
 	PreviewResponse,
 	PreviewVersion,
-	ProviderInfo,
-	RetentionPreview,
-	SendDetailResponse,
-	SendHtmlResponse,
 	StarterSummary,
 	SuppressionSummary,
 	TemplateChange,
 	TemplateContent,
 	TemplateCategory,
-	TemplateContentResponse,
-	TemplatePerformance,
 	TemplateRow,
 	TemplateStats,
 	TemplateVersionSummary,
 	VariableDefinition,
 } from '../types/mailing'
-import type { SetupFacts } from '../utils/overview-setup'
-import type { WebhookStatus, WebhookTestResult } from '../utils/webhook-status'
+import type { WebhookTestResult } from '../utils/webhook-status'
 
 const BASE = '/api/mailing'
 
 /** Far above any real tenant's template count; the data-api caps at 100. */
-const TEMPLATE_LIST_LIMIT = '100'
+export const TEMPLATE_LIST_LIMIT = '100'
 
 /**
  * Joins the module's API segments. Exported on its own so the path shape stays
@@ -187,8 +180,9 @@ export interface StarterPreviewResponse {
 }
 
 /**
- * The single place that knows the mailing endpoints; every component reads
- * through it so a route change is a one-file edit.
+ * The mailing endpoints a component writes to, and the previews it renders
+ * from a draft it sends. Every read goes through `useMailingReads`, with the
+ * same paths.
  */
 export function useMailingApi() {
 	const { $authFetch } = useAuthFetch()
@@ -196,29 +190,14 @@ export function useMailingApi() {
 		$authFetch<T>(path, { method: 'POST', body })
 
 	return {
-		provider: () => $authFetch<ProviderInfo>(mailingPath('provider')),
-		setupFacts: () => $authFetch<SetupFacts>(mailingPath('metrics', 'setup')),
-		webhookStatus: () =>
-			$authFetch<WebhookStatus>(mailingPath('settings', 'webhook-status')),
 		webhookTest: () =>
 			post<WebhookTestResult>(mailingPath('settings', 'webhook-test'), {}),
-		templateContent: (id: string) =>
-			$authFetch<TemplateContentResponse>(
-				mailingPath('templates', id, 'content'),
-			),
 		saveTemplateDetails: (id: string, details: TemplateDetails) =>
 			$authFetch<unknown>(mailingPath('tables', 'templates', 'edit'), {
 				method: 'PUT',
 				query: { id },
 				body: details,
 			}),
-		listCategories: () =>
-			$authFetch<CategoriesResponse>(mailingPath('templates', 'categories')),
-		listTemplates: () =>
-			$authFetch<TemplateListResponse>(
-				mailingPath('tables', 'templates', 'list'),
-				{ query: { limit: TEMPLATE_LIST_LIMIT, sortKey: 'name' } },
-			),
 		createTemplate: (input: CreateTemplateInput) =>
 			post<string[]>(mailingPath('tables', 'templates', 'new'), input),
 		saveContent: (id: string, input: SaveContentInput) =>
@@ -231,30 +210,11 @@ export function useMailingApi() {
 				},
 				keepalive: input.keepalive,
 			}),
-		changes: (id: string) =>
-			$authFetch<ChangesResponse>(mailingPath('templates', id, 'changes')),
-		versions: (id: string) =>
-			$authFetch<VersionsResponse>(mailingPath('templates', id, 'versions')),
 		restoreVersion: (id: string, version: number, revision?: number) =>
 			post<RestoreVersionResponse>(
 				mailingPath('templates', id, 'versions', String(version), 'restore'),
 				{ revision },
 			),
-		performance: (id: string) =>
-			$authFetch<TemplatePerformance>(
-				mailingPath('templates', id, 'performance'),
-			),
-		templatesOverview: () =>
-			$authFetch<TemplateOverviewResponse>(
-				mailingPath('templates', 'overview'),
-			),
-		starters: () =>
-			$authFetch<StartersResponse>(mailingPath('templates', 'starters')),
-		starterPreview: (starterId: string, locale?: string) =>
-			$authFetch<StarterPreviewResponse>(
-				mailingPath('templates', 'starters', starterId, 'preview'),
-				{ query: locale ? { locale } : {} },
-			),
 		publish: (id: string, revision?: number) =>
 			post<PublishResponse>(mailingPath('templates', id, 'publish'), {
 				revision,
@@ -291,21 +251,8 @@ export function useMailingApi() {
 			post<TestSendResponse>(mailingPath('templates', id, 'send'), input),
 		testSend: (id: string, input: TestSendInput) =>
 			post<TestSendResponse>(mailingPath('templates', id, 'test-send'), input),
-		send: (id: string) =>
-			$authFetch<SendDetailResponse>(mailingPath('sends', id)),
-		sendHtml: (id: string) =>
-			$authFetch<SendHtmlResponse>(mailingPath('sends', id, 'html')),
 		replay: (id: string, to?: string) =>
 			post<SendResult>(mailingPath('sends', id, 'replay'), to ? { to } : {}),
-		retentionPreview: (days: number) =>
-			$authFetch<RetentionPreview>(
-				mailingPath('settings', 'retention-preview'),
-				{ query: { days: String(days) } },
-			),
-		categoryUsage: () =>
-			$authFetch<CategoryUsageResponse>(
-				mailingPath('settings', 'category-usage'),
-			),
 	}
 }
 

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

@@ -0,0 +1,229 @@
+import { toValue, type MaybeRefOrGetter } from 'vue'
+import {
+	mailingPath,
+	TEMPLATE_LIST_LIMIT,
+	type CategoriesResponse,
+	type CategoryUsageResponse,
+	type ChangesResponse,
+	type StarterPreviewResponse,
+	type StartersResponse,
+	type TemplateListResponse,
+	type TemplateOverviewResponse,
+	type VersionsResponse,
+} from './useMailingApi'
+import type { SetupFacts } from '../utils/overview-setup'
+import type { WebhookStatus } from '../utils/webhook-status'
+import type {
+	ProviderInfo,
+	RetentionPreview,
+	SendDetailResponse,
+	SendHtmlResponse,
+	TemplateContentResponse,
+	TemplatePerformance,
+} from '../types/mailing'
+
+/**
+ * The module's reads, through `useApiData`. The ones a page renders: a server
+ * render reads them and hands them to the browser with the page, and the
+ * components showing one request share it. The ones a drawer, a dialog or the
+ * editor makes when it opens or asks: `ReadOnDemand`. Writes go through
+ * `useMailingApi`.
+ */
+
+/** The e-mail provider the page header names; nothing read while `enabled` is false. */
+export function useProviderInfo(
+	enabled: MaybeRefOrGetter<boolean>,
+): ApiDataResult<ProviderInfo> {
+	return useApiData<ProviderInfo>(() =>
+		toValue(enabled) ? mailingPath('provider') : null,
+	)
+}
+
+/** What the overview's setup checklist is made of. */
+export function useSetupFacts(): ApiDataResult<SetupFacts> {
+	return useApiData<SetupFacts>(mailingPath('metrics', 'setup'))
+}
+
+/** The webhook's last event and last refused call. */
+export function useWebhookStatus(): ApiDataResult<WebhookStatus> {
+	return useApiData<WebhookStatus>(mailingPath('settings', 'webhook-status'))
+}
+
+/** What a retention of `days` deletes, and when; nothing read without days. */
+export function useRetentionPreview(
+	days: MaybeRefOrGetter<number | null>,
+): ApiDataResult<RetentionPreview> {
+	return useApiData<RetentionPreview>(
+		() => (toValue(days) ? mailingPath('settings', 'retention-preview') : null),
+		{ query: () => ({ days: String(toValue(days)) }) },
+	)
+}
+
+/** How many templates each category holds. */
+export function useCategoryUsage(): ApiDataResult<CategoryUsageResponse> {
+	return useApiData<CategoryUsageResponse>(
+		mailingPath('settings', 'category-usage'),
+	)
+}
+
+/** The tenant's template categories, as stored. */
+export function useStoredCategories(): ApiDataResult<CategoriesResponse> {
+	return useApiData<CategoriesResponse>(mailingPath('templates', 'categories'))
+}
+
+/**
+ * Each template's sends and rates, for the gallery's cards: read again with
+ * the gallery's rows, rather than with the page.
+ */
+export function useTemplatesOverview(): ApiDataResult<TemplateOverviewResponse> {
+	return useApiData<TemplateOverviewResponse>(
+		mailingPath('templates', 'overview'),
+		{ refreshOnPageRefresh: false },
+	)
+}
+
+/**
+ * How many templates the tenant has, whatever the gallery's filters: the
+ * list route's total, without its rows. Read again with the gallery's rows.
+ */
+export function useTemplateTotal(): ApiDataResult<
+	Pick<TemplateListResponse, 'total'>
+> {
+	return useApiData<Pick<TemplateListResponse, 'total'>>(
+		mailingPath('tables', 'templates', 'list'),
+		{ query: { limit: '1' }, pick: ['total'], refreshOnPageRefresh: false },
+	)
+}
+
+/** The starter templates the module ships. */
+export function useStarters(): ApiDataResult<StartersResponse> {
+	return useApiData<StartersResponse>(mailingPath('templates', 'starters'))
+}
+
+/** The query of a read made on demand. */
+type ReadQuery = MaybeRefOrGetter<Record<string, string> | undefined>
+
+/**
+ * A read a drawer, a dialog, a preview frame or the editor makes when it
+ * opens or asks, through `useApiData` with `immediate: false`: the call reads
+ * the current URL and resolves with its answer, or rejects with what the read
+ * failed with. The caller keeps the answer, so the page's refreshes leave it.
+ */
+export type ReadOnDemand<T> = () => Promise<T>
+
+function useReadOnDemand<T>(
+	url: MaybeRefOrGetter<string | null>,
+	query?: ReadQuery,
+): ReadOnDemand<T> {
+	const read = useApiData<T>(url, {
+		query,
+		immediate: false,
+		refreshOnPageRefresh: false,
+	})
+	return async () => {
+		await read.execute({ dedupe: 'defer' })
+		if (read.error.value) throw read.error.value
+		return read.data.value as T
+	}
+}
+
+/** A template's path below `/templates/<id>`; none without an id. */
+const templatePath =
+	(id: MaybeRefOrGetter<string>, segment: string) => (): string | null =>
+		toValue(id) ? mailingPath('templates', toValue(id), segment) : null
+
+/** The template's record, its draft and published content, for a drawer or the editor. */
+export function useTemplateContentRead(
+	id: MaybeRefOrGetter<string>,
+): ReadOnDemand<TemplateContentResponse> {
+	return useReadOnDemand(templatePath(id, 'content'))
+}
+
+/** The template's sends and rates. */
+export function useTemplatePerformanceRead(
+	id: MaybeRefOrGetter<string>,
+): ReadOnDemand<TemplatePerformance> {
+	return useReadOnDemand(templatePath(id, 'performance'))
+}
+
+/** What publishing the template's draft would change. */
+export function useTemplateChangesRead(
+	id: MaybeRefOrGetter<string>,
+): ReadOnDemand<ChangesResponse> {
+	return useReadOnDemand(templatePath(id, 'changes'))
+}
+
+/** The template's published versions. */
+export function useTemplateVersionsRead(
+	id: MaybeRefOrGetter<string>,
+): ReadOnDemand<VersionsResponse> {
+	return useReadOnDemand(templatePath(id, 'versions'))
+}
+
+/** Every template of the tenant, by name, for the slugs a new one must avoid. */
+export function useTemplateListRead(): ReadOnDemand<TemplateListResponse> {
+	return useReadOnDemand(mailingPath('tables', 'templates', 'list'), {
+		limit: TEMPLATE_LIST_LIMIT,
+		sortKey: 'name',
+	})
+}
+
+/** The starter templates, for a dialog. */
+export function useStartersRead(): ReadOnDemand<StartersResponse> {
+	return useReadOnDemand(mailingPath('templates', 'starters'))
+}
+
+/** A starter's preview, in `locale` when given. */
+export function useStarterPreviewRead(
+	starterId: MaybeRefOrGetter<string | undefined>,
+	locale: MaybeRefOrGetter<string | undefined>,
+): ReadOnDemand<StarterPreviewResponse> {
+	return useReadOnDemand(
+		() => {
+			const id = toValue(starterId)
+			return id ? mailingPath('templates', 'starters', id, 'preview') : null
+		},
+		() => {
+			const value = toValue(locale)
+			return value ? { locale: value } : undefined
+		},
+	)
+}
+
+/** A send's path below `/sends`; none without an id. */
+const sendPath =
+	(id: MaybeRefOrGetter<string>, ...segments: string[]) =>
+	(): string | null =>
+		toValue(id) ? mailingPath('sends', toValue(id), ...segments) : null
+
+/** A send with its events and the template it used. */
+export function useSendRead(
+	id: MaybeRefOrGetter<string>,
+): ReadOnDemand<SendDetailResponse> {
+	return useReadOnDemand(sendPath(id))
+}
+
+/** The e-mail a send rendered. */
+export function useSendHtmlRead(
+	id: MaybeRefOrGetter<string>,
+): ReadOnDemand<SendHtmlResponse> {
+	return useReadOnDemand(sendPath(id, 'html'))
+}
+
+/** The e-mail provider and the tracking it reports, for a drawer. */
+export function useProviderRead(): ReadOnDemand<ProviderInfo> {
+	return useReadOnDemand(mailingPath('provider'))
+}
+
+/** The reads the editor makes when it asks: what publishing would change, and the template's figures. */
+export interface EditorReads {
+	changes: ReadOnDemand<ChangesResponse>
+	performance: ReadOnDemand<TemplatePerformance>
+}
+
+export function useEditorReads(id: MaybeRefOrGetter<string>): EditorReads {
+	return {
+		changes: useTemplateChangesRead(id),
+		performance: useTemplatePerformanceRead(id),
+	}
+}

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

@@ -1,13 +1,21 @@
-import type { Ref } from 'vue'
+import { computed, type ComputedRef } from 'vue'
+import { useSetupFacts } from './useMailingReads'
+import { needsSetup } from '../utils/overview-setup'
 
-const HIDES_PERIOD_KEY = 'mailing-setup-hides-period:'
+/** The period scope of the Overview page, whose dashboard the setup gates. */
+const OVERVIEW_PERIOD_SCOPE = 'mailing-overview'
 
 /**
  * Whether the page header should hold its period selector back for `scope`:
- * the setup card stands in for the dashboard, so there is no figure for a
- * period to filter. Shared between the Overview gate, which sets it, and the
- * page header, which reads it.
+ * on the Overview, while the setup card stands in for the dashboard, there is
+ * no figure for a period to filter. Read from the setup facts the Overview
+ * gate shows (one request for both), so a server render hides it as the
+ * browser does.
  */
-export function useSetupHidesPeriod(scope: string | undefined): Ref<boolean> {
-	return useDmsState<boolean>(`${HIDES_PERIOD_KEY}${scope ?? ''}`, () => false)
+export function useSetupHidesPeriod(
+	scope: string | undefined,
+): ComputedRef<boolean> {
+	if (scope !== OVERVIEW_PERIOD_SCOPE) return computed(() => false)
+	const { data } = useSetupFacts()
+	return computed(() => !!data.value && needsSetup(data.value))
 }