feat(admin): mail preview field with sandboxed HTML and test send

- Add MailPreviewField (POST /mail/preview + /mail/test-send, empty sandbox iframe)
- Register mailpreview as valueless/group-labelled; SettingsFormView FORM_VALUES/FORM_LOCALE
- Smoke tests for srcdoc, sequence guard, 422 keep-last, and 429 Retry-After

Plan 35-03, task 1

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-11-13 13:14:22 +01:00
parent 9ea3159ba2
commit 52204e171d
9 changed files with 603 additions and 8 deletions

View File

@@ -0,0 +1,350 @@
<script setup lang="ts">
import { computed, inject, onBeforeUnmount, onMounted, ref, watch } from 'vue'
import { Send } from '@lucide/vue'
import { api } from '../../../api/client'
import type { AdminRecord } from '../../../api/types'
import { t } from '../../../app/i18n'
import { currentUser } from '../../../state/useAuth'
import { showToast } from '../../../state/useToasts'
import Button from '../../ui/Button.vue'
import type { FieldControlProps } from '../control'
import { FORM_VALUES } from '../formContext'
// Live mail preview (D-16) and test send (D-17). The iframe's srcdoc is only
// the server's rendered HTML from a 2xx answer; the SPA never builds mail
// markup. Test send posts the same draft with no recipient; the server sends
// to the signed-in administrator only.
const props = defineProps<FieldControlProps>()
const PREVIEW_DEBOUNCE_MS = 500
const emptyValues = ref<AdminRecord>({})
const formValues = inject(FORM_VALUES, emptyValues)
const mode = computed(() => {
const value = props.field.mode
return typeof value === 'string' && value !== '' ? value : 'template'
})
const branding = computed(() => mode.value === 'branding')
const adminEmail = computed(() => currentUser.value?.email ?? '')
const format = ref<'html' | 'text'>('html')
const subject = ref('')
const html = ref('')
const text = ref('')
const hasRender = ref(false)
const loading = ref(false)
const previewError = ref('')
const testError = ref('')
const testBusy = ref(false)
const testBlockedUntil = ref(0)
const now = ref(Date.now())
let sequence = 0
let previewTimer: ReturnType<typeof setTimeout> | null = null
let blockTimer: ReturnType<typeof setTimeout> | null = null
let clockTimer: ReturnType<typeof setInterval> | null = null
const contentKey = computed(() => {
switch (mode.value) {
case 'layout':
case 'partial':
return 'content_html'
case 'branding':
return ''
default:
return 'body'
}
})
const draftEmpty = computed(() => {
const key = contentKey.value
if (key === '') {
return false
}
const raw = formValues.value[key]
return raw === null || raw === undefined || String(raw).trim() === ''
})
const testDisabled = computed(() => testBusy.value || testBlockedUntil.value > now.value)
const sampleNote = computed(() =>
mode.value === 'template'
? t('backend::lang.mail.preview.sample_note')
: t('backend::lang.mail.preview.sample_content_note'),
)
function cancelTimer() {
if (previewTimer !== null) {
clearTimeout(previewTimer)
previewTimer = null
}
}
function refusalMessage(error: unknown): string {
const details = (error as { error?: { details?: Record<string, unknown>; message?: string } } | undefined)?.error
?.details
const fromDetails = details?.message
if (typeof fromDetails === 'string' && fromDetails !== '') {
return fromDetails
}
const top = (error as { error?: { message?: string } } | undefined)?.error?.message
if (typeof top === 'string' && top !== '') {
return top
}
return ''
}
function schedulePreview() {
cancelTimer()
previewTimer = setTimeout(() => {
previewTimer = null
void renderPreview()
}, PREVIEW_DEBOUNCE_MS)
}
async function renderPreview() {
if (draftEmpty.value) {
sequence++
loading.value = false
previewError.value = ''
return
}
const current = ++sequence
loading.value = true
try {
const { data, error, response } = await api.POST('/mail/preview', {
body: {
mode: mode.value,
id: props.recordId ?? 0,
values: { ...formValues.value },
},
})
if (current !== sequence) {
return
}
if (data) {
subject.value = data.data.subject
html.value = data.data.html
text.value = data.data.text
hasRender.value = true
previewError.value = ''
return
}
if (response.status === 422) {
const message = refusalMessage(error)
previewError.value = hasRender.value
? t('backend::lang.mail.preview.failed', { message })
: t('backend::lang.mail.preview.failed_first', { message })
return
}
previewError.value = t('backend::lang.mail.preview.unavailable')
} catch {
if (current !== sequence) {
return
}
previewError.value = t('backend::lang.mail.preview.unavailable')
} finally {
if (current === sequence) {
loading.value = false
}
}
}
function retryAfterSeconds(response: Response): number {
const raw = response.headers.get('Retry-After')
const parsed = raw ? Number.parseInt(raw, 10) : NaN
return Number.isFinite(parsed) && parsed > 0 ? parsed : 60
}
function armTestBlock(seconds: number) {
testBlockedUntil.value = Date.now() + seconds * 1000
now.value = Date.now()
if (blockTimer !== null) {
clearTimeout(blockTimer)
}
blockTimer = setTimeout(() => {
blockTimer = null
testBlockedUntil.value = 0
now.value = Date.now()
}, seconds * 1000)
if (clockTimer === null) {
clockTimer = setInterval(() => {
now.value = Date.now()
if (testBlockedUntil.value <= now.value && clockTimer !== null) {
clearInterval(clockTimer)
clockTimer = null
}
}, 250)
}
}
async function onTestSend() {
if (branding.value || testDisabled.value || draftEmpty.value) {
return
}
testBusy.value = true
testError.value = ''
try {
const { data, error, response } = await api.POST('/mail/test-send', {
body: {
mode: mode.value,
id: props.recordId ?? 0,
values: { ...formValues.value },
},
})
if (data) {
showToast(t('backend::lang.mail.preview.test_sent', { email: data.data.email }))
return
}
const status = response.status
if (status === 429) {
const seconds = retryAfterSeconds(response)
armTestBlock(seconds)
testError.value = t('backend::lang.mail.preview.test_limited', { seconds })
return
}
if (status === 422) {
testError.value = t('backend::lang.mail.preview.test_invalid', { message: refusalMessage(error) })
return
}
if (status === 403) {
showToast(error?.error.message || t('backend::lang.form.forbidden'), 'danger')
return
}
if (status >= 500) {
showToast(t('backend::lang.mail.preview.test_failed'), 'danger')
return
}
showToast(error?.error.message || t('backend::lang.mail.preview.test_failed'), 'danger')
} catch {
showToast(t('backend::lang.mail.preview.test_failed'), 'danger')
} finally {
testBusy.value = false
}
}
watch(
() => formValues.value,
() => {
if (draftEmpty.value) {
cancelTimer()
sequence++
loading.value = false
previewError.value = ''
return
}
schedulePreview()
},
{ deep: true },
)
onMounted(() => {
void renderPreview()
})
onBeforeUnmount(() => {
cancelTimer()
sequence++
if (blockTimer !== null) {
clearTimeout(blockTimer)
}
if (clockTimer !== null) {
clearInterval(clockTimer)
}
})
</script>
<template>
<div class="flex flex-col gap-2" data-mail-preview>
<div class="overflow-hidden rounded-inner border border-border">
<div class="flex flex-wrap items-center gap-2 border-b border-border bg-subtle p-1">
<div role="tablist" class="inline-flex gap-1 rounded-inner border border-border bg-subtle p-1">
<button
type="button"
role="tab"
data-mail-preview-format="html"
:aria-selected="format === 'html' ? 'true' : 'false'"
:class="format === 'html' ? 'bg-surface text-text shadow-tab' : 'text-muted hover:text-text'"
class="inline-flex h-[34px] items-center gap-2 rounded-tab px-4 font-semibold transition-colors duration-150 ease-out"
@click="format = 'html'"
>
{{ t('backend::lang.mail.preview.html') }}
</button>
<button
type="button"
role="tab"
data-mail-preview-format="text"
:aria-selected="format === 'text' ? 'true' : 'false'"
:class="format === 'text' ? 'bg-surface text-text shadow-tab' : 'text-muted hover:text-text'"
class="inline-flex h-[34px] items-center gap-2 rounded-tab px-4 font-semibold transition-colors duration-150 ease-out"
@click="format = 'text'"
>
{{ t('backend::lang.mail.preview.text') }}
</button>
</div>
<p role="status" class="ml-auto px-2 text-[13px] text-muted" data-mail-preview-status>
{{ loading ? t('backend::lang.mail.preview.rendering') : '' }}
</p>
</div>
<p
v-if="previewError"
role="alert"
data-mail-preview-error
class="border-b border-border px-4 py-2 text-[13px] text-danger"
>
{{ previewError }}
</p>
<div
v-if="!branding && (hasRender || !draftEmpty)"
class="flex gap-2 border-b border-border px-4 py-3"
data-mail-preview-subject
>
<span class="font-semibold">{{ t('backend::lang.mail.preview.subject') }}</span>
<span class="min-w-0 break-words">{{ subject }}</span>
</div>
<div v-if="draftEmpty" class="px-4 py-3 text-center text-[13px] text-muted" data-mail-preview-empty>
{{ t('backend::lang.mail.preview.empty') }}
</div>
<iframe
v-else-if="format === 'html'"
sandbox=""
referrerpolicy="no-referrer"
:srcdoc="html"
:title="t('backend::lang.mail.preview.frame_title')"
class="block h-[640px] w-full border-0 bg-white"
data-mail-preview-frame
/>
<pre
v-else
class="m-0 max-h-[640px] overflow-auto bg-surface px-4 py-3 font-mono text-[13px] whitespace-pre-wrap"
data-mail-preview-text
>{{ text }}</pre
>
</div>
<p class="text-[13px] text-muted" data-mail-preview-note>{{ sampleNote }}</p>
<p v-if="field.comment" class="text-[13px] text-muted" data-mail-preview-comment>{{ field.comment }}</p>
<div v-if="!branding" class="flex flex-wrap items-center gap-2" data-mail-preview-test>
<Button
variant="outline"
size="sm"
:icon="Send"
:disabled="testDisabled || draftEmpty"
data-mail-preview-test-send
@click="onTestSend"
>
{{ testBusy ? t('backend::lang.mail.preview.test_sending') : t('backend::lang.mail.preview.test_send') }}
</Button>
<p class="text-[13px] text-muted" data-mail-preview-test-hint>
{{ t('backend::lang.mail.preview.test_hint', { email: adminEmail }) }}
</p>
<p v-if="testError" role="alert" class="basis-full text-[13px] text-danger" data-mail-preview-test-error>
{{ testError }}
</p>
</div>
</div>
</template>

View File

@@ -33,6 +33,9 @@
// Phase 18.1 adds the taglist control (D-17): tags edited as chips with an
// input that adds a tag on Enter or a comma, the field's options offered as
// suggestions; the value is a list of strings (array mode).
// Phase 35 adds the mail editor controls: mailpreview is valueless and
// group-labelled (live postcard HTML in a sandboxed iframe plus test send);
// codeeditor, colorpicker and mailimage follow in the same phase.
import type { Component } from 'vue'
import type { FormField } from '../../api/types'
import CheckboxField from './fields/CheckboxField.vue'
@@ -53,6 +56,7 @@ import SwitchField from './fields/SwitchField.vue'
import TextField from './fields/TextField.vue'
import TextareaField from './fields/TextareaField.vue'
import MarkdownField from './fields/MarkdownField.vue'
import MailPreviewField from './fields/MailPreviewField.vue'
import MoneyField from './fields/MoneyField.vue'
import TaglistField from './fields/TaglistField.vue'
import MLTextField from './fields/MLTextField.vue'
@@ -98,6 +102,7 @@ const renderers = new Map<string, Component>([
['repeater', RepeaterField],
['money', MoneyField],
['taglist', TaglistField],
['mailpreview', MailPreviewField],
])
/** Types whose control shows the label itself (toggle cards, relation manager). */
@@ -111,7 +116,7 @@ const selfLabelled = new Set<string>(['switch', 'checkbox', RELATION_MANAGER])
const recordBound = new Set<string>([RELATION_MANAGER])
/** Types that hold no form value: never part of the save body (D-09). */
const valueless = new Set<string>([RELATION_MANAGER, 'widget', 'partial', 'fileupload'])
const valueless = new Set<string>([RELATION_MANAGER, 'widget', 'partial', 'fileupload', 'mailpreview'])
/**
* Types whose control is a group rather than one focusable element: the
@@ -126,6 +131,7 @@ const groupLabelledTypes = new Set<string>([
'mltextarea',
'mlmarkdown',
'repeater',
'mailpreview',
])
export function rendererFor(type: string): Component {