caracms 0.0.0-stage → 0.2.0

package/src/editor/client/inbox/InboxStage.tsx

@@ -0,0 +1,272 @@
+/**
+ * The stage under the inbox (M6 Decision 9; the mockup's #submission, #submission-failed,
+ * #submission-skipped, #submission-unknown): the last page stays, dimmed (shell/Stage.tsx),
+ * and a submission opens over it on a light sheet, with the list kept in the sidebar.
+ *
+ * The sheet: the form and the full time in the site's zone, who sent it and their address,
+ * **Reply by email** (a `mailto:` with the address percent-encoded and the subject
+ * "Re: your enquiry to <brand>"), **Mark unread** (which closes it: staying open would be
+ * reading it again), **Delete…** (after a confirm: documents/dialogs.tsx); then the email's
+ * outcome (sent to whom, failed with Resend's message, skipped and why, or unknown), and
+ * every field by its label, files as downloads with their sizes.
+ *
+ * **Visitor strings are only ever text** (React's escaping): no `dangerouslySetInnerHTML`
+ * on this path. Files always download (`download`, and the route's `Content-Disposition:
+ * attachment`).
+ */
+import { Fragment, useEffect, useRef } from 'react';
+import { senderName, shownFileName } from '../../../forms/rules.ts';
+import { useEditor, useStore } from '../context.tsx';
+import { openDialog } from '../documents/dialogs.tsx';
+import { Icon } from '../shell/Icons.tsx';
+import type { Editor } from '../editor.ts';
+import type { EmailOutcome, StoredSubmission, SubmissionResponse } from '../../types.ts';
+import { ENDPOINTS } from '../../types.ts';
+import { fileLine, fullTime, inboxFor, replyHref, shortTime } from './store.ts';
+
+export function InboxStage({ back, onBack }: { back: string; onBack: () => void }) {
+	const editor = useEditor();
+	const inbox = inboxFor(editor);
+	const openId = useStore(editor.view, (v) => v.inbox?.id ?? null);
+	const open = useStore(inbox.open);
+	const off = useStore(editor.submissions, (s) => s.unread === null);
+	const empty = useStore(inbox.list, (l) => l.rows !== null && l.rows.length === 0);
+	if (openId && open?.id === openId && open.answer) return <Sheet answer={open.answer} />;
+	if (openId && open?.id === openId && open.error) {
+		return (
+			<div className="in">
+				<Icon name="inbox" />
+				<h2>This message can’t be shown</h2>
+				<p>{open.error}</p>
+				<button type="button" className="btn" onClick={() => editor.openInbox(null)}>
+					<Icon name="chev-l" size="sm" />
+					Back to the list
+				</button>
+			</div>
+		);
+	}
+	// Opening one: the last state stays until it's there (no skeleton), so nothing flickers.
+	const h = off ? 'Nothing to show yet' : empty ? 'Nothing to read yet' : 'Choose a message to read it';
+	return (
+		<div className="in">
+			<Icon name="inbox" />
+			<h2>{h}</h2>
+			<button type="button" className="btn" data-act="back-to-page" onClick={onBack}>
+				<Icon name="chev-l" size="sm" />
+				Back to {back}
+			</button>
+		</div>
+	);
+}
+
+/** The form's fields as the sheet lists them: the config's, in order; a form no longer in the config, the stored names. */
+function fieldRows(answer: SubmissionResponse) {
+	const { submission, form } = answer;
+	const values = submission.fields ?? {};
+	if (form) return form.fields.map((f) => ({ name: f.name, label: f.label, type: f.type, options: f.options }));
+	const rows: { name: string; label: string; type: string; options?: { value: string; label: string }[] }[] = Object.keys(values).map((name) => ({ name, label: name, type: 'text' }));
+	if (submission.files?.length) rows.push({ name: 'files', label: 'Files', type: 'files' });
+	return rows;
+}
+
+function Sheet({ answer }: { answer: SubmissionResponse }) {
+	const editor = useEditor();
+	const inbox = inboxFor(editor);
+	const brand = useStore(editor.brand, (b) => b.name);
+	const { submission, form } = answer;
+	const timeZone = editor.timeZone();
+	const values = submission.fields ?? {};
+	const who = senderName(form, values) || 'Someone';
+	const address = typeof values.email === 'string' ? values.email : '';
+	const formLabel = form?.label ?? submission.form;
+	const subject = `Re: your enquiry to ${brand}`;
+	const body = useRef<HTMLDivElement>(null);
+	// Braces: Chromium's scrollTo returns a promise now, and an effect may only return a cleanup.
+	useEffect(() => {
+		body.current?.scrollTo(0, 0);
+	}, [submission.id]);
+
+	const markUnread = async () => {
+		const answer = await inbox.markUnread(submission.id);
+		if (!answer.ok) {
+			editor.toast(answer.error ?? "It couldn't be marked unread.", 'warn');
+			return;
+		}
+		// Only if it's still the one open (another may have been opened meanwhile).
+		if (editor.view.get().inbox?.id === submission.id) editor.openInbox(null);
+		editor.toast('Marked unread', 'unread');
+		requestAnimationFrame(() => document.querySelector<HTMLElement>(`#side .srow[data-id="${CSS.escape(submission.id)}"]`)?.focus());
+	};
+	const close = () => {
+		editor.openInbox(null);
+		requestAnimationFrame(() => document.querySelector<HTMLElement>(`#side .srow[data-id="${CSS.escape(submission.id)}"]`)?.focus());
+	};
+
+	return (
+		<article className="sub-sheet" aria-labelledby="sub-h" data-submission={submission.id}>
+			<header className="sub-head">
+				<div className="sub-meta">
+					<span className="chip">
+						<Icon name="b-form" size="xs" />
+						{formLabel} form
+					</span>
+					<span>{fullTime(submission.receivedAt, timeZone)}</span>
+					<button type="button" className="ib end" style={{ marginLeft: 'auto' }} data-act="sub-close" aria-label="Close" onClick={close}>
+						<Icon name="x" size="sm" />
+					</button>
+				</div>
+				<h2 id="sub-h" tabIndex={-1}>
+					{who}
+				</h2>
+				<p className="from">{address}</p>
+				<div className="sub-acts">
+					{address ? (
+						<a className="btn ink" href={replyHref(address, brand)} data-act="reply" title={`Opens your email, with the subject “${subject}”`}>
+							<Icon name="reply" size="sm" />
+							Reply by email
+						</a>
+					) : null}
+					<button type="button" className="btn" data-act="sub-unread" onClick={() => void markUnread()}>
+						<Icon name="unread" size="sm" />
+						Mark unread
+					</button>
+					<button
+						type="button"
+						className="btn quiet-danger end"
+						data-act="sub-delete"
+						onClick={() => openDialog(editor, { kind: 'sub-delete', id: submission.id, who, files: submission.files?.length ?? 0 })}
+					>
+						<Icon name="trash" size="sm" />
+						Delete…
+					</button>
+				</div>
+			</header>
+			<div className="sub-body" ref={body}>
+				<MailOutcome email={submission.email} formLabel={formLabel} timeZone={timeZone} editor={editor} />
+				<dl className="sub-fields">
+					{fieldRows(answer).map((f) => {
+						if (f.type === 'files') {
+							const files = submission.files ?? [];
+							return [
+								<dt key={`${f.name}:t`}>{f.label}</dt>,
+								files.length ? (
+									<dd key={`${f.name}:d`}>
+										<div className="sub-files">
+											{files.map((file, i) => (
+												<FileRow key={file.key} submission={submission} n={i + 1} name={shownFileName(file.name) || shownFileName(file.key)} size={file.size} keyName={file.key} />
+											))}
+										</div>
+									</dd>
+								) : (
+									<dd key={`${f.name}:d`} className="none">
+										No files
+									</dd>
+								),
+							];
+						}
+						const raw = typeof values[f.name] === 'string' ? values[f.name]! : '';
+						const shown = f.type === 'select' ? (f.options?.find((o) => o.value === raw)?.label ?? raw) : raw;
+						return [
+							<dt key={`${f.name}:t`}>{f.label}</dt>,
+							shown ? (
+								<dd key={`${f.name}:d`} data-value={f.name}>
+									{shown}
+								</dd>
+							) : (
+								<dd key={`${f.name}:d`} className="none">
+									Not given
+								</dd>
+							),
+						];
+					})}
+				</dl>
+			</div>
+		</article>
+	);
+}
+
+function FileRow({ submission, n, name, size, keyName }: { submission: StoredSubmission; n: number; name: string; size: number; keyName: string }) {
+	// The stored key's extension (what the download's type comes from), as the mockup shows it.
+	const ext = (/\.([a-z0-9]+)$/i.exec(keyName)?.[1] ?? '').toUpperCase().replace('JPEG', 'JPG');
+	return (
+		<a className="frow" href={`${ENDPOINTS.submissions}/${encodeURIComponent(submission.id)}/files/${n}`} download={name} title={`Download ${name}`} data-file={n}>
+			<span className="ext">{ext}</span>
+			<span className="t">
+				<b>{name}</b>
+				<small>{fileLine(size, ext)}</small>
+			</span>
+			<Icon name="download" />
+		</a>
+	);
+}
+
+function MailOutcome({ email, formLabel, timeZone, editor }: { email: EmailOutcome | undefined; formLabel: string; timeZone: string; editor: Editor }) {
+	if (!email) {
+		return (
+			<div className="note warn" data-mail="unknown">
+				<Icon name="warn" />
+				<div>
+					<b>It isn’t known whether the email went out</b>
+					<p>Check with whoever gets {formLabel} emails.</p>
+				</div>
+			</div>
+		);
+	}
+	if (email.status === 'sent') {
+		return (
+			<p className="sub-mail sent" data-mail="sent">
+				<Icon name="check" />
+				<span>
+					Emailed to{' '}
+					{email.to.map((a, i) => (
+						<Fragment key={a}>
+							{i === 0 ? '' : i === email.to.length - 1 ? ' and ' : ', '}
+							<span className="mono">{a}</span>
+						</Fragment>
+					))}{' '}
+					at {shortTime(email.at, timeZone)}.
+				</span>
+			</p>
+		);
+	}
+	if (email.status === 'failed') {
+		return (
+			<div className="note danger" data-mail="failed">
+				<Icon name="warn" />
+				<div>
+					<b>The email about it didn’t go out</b>
+					<p>Resend said:</p>
+					<q>{email.error ?? 'No reason was given.'}</q>
+					<p style={{ marginTop: 'var(--space-1-5)' }}>Your developer can fix that.</p>
+				</div>
+			</div>
+		);
+	}
+	// Skipped: no one to email (Site Settings sets who), or not the production server (which alone sends email).
+	const notProduction = (email.error ?? '').startsWith('Not emailed');
+	return (
+		<div className="note" data-mail="skipped">
+			<Icon name="mail" />
+			<div>
+				<b>No email was sent</b>
+				{notProduction ? (
+					<p>{email.error}</p>
+				) : (
+					<>
+						<p>The {formLabel} form had no one to email.</p>
+						<div className="acts">
+							<button
+								type="button"
+								className="btn sm"
+								data-act="open-settings"
+								onClick={() => void editor.openDocument({ collection: 'settings', path: editor.documents.get().find((d) => d.collection === 'settings')?.path ?? 'site-settings' })}
+							>
+								Open Site Settings
+							</button>
+						</div>
+					</>
+				)}
+			</div>
+		</div>
+	);
+}

package/src/editor/client/inbox/store.ts

@@ -0,0 +1,311 @@
+/**
+ * The inbox's data in the browser (M6 Decision 9; forms/inbox.ts has the routes): the
+ * list (newest first, 50 at a time, Older by cursor), the submission open on its sheet,
+ * and the actions. `inboxFor(editor)`, one per editor:
+ *
+ *   inbox.list          { rows, older, loading, olderLoading, error }: last known while it's read again
+ *   inbox.open          the open submission's GET answer (or its error), by id
+ *   inbox.load()        the first page (on opening the level, and on intent: hovering its row)
+ *   inbox.loadOlder()   the next 50 (`?before=`)
+ *   inbox.show(id)      read it, and mark it read with an explicit POST …/read (Decision 9:
+ *                       the GET never does), when it's unread
+ *   inbox.markUnread(id) / inbox.remove(id)   POST …/unread and …/delete (`{ "confirm": true }`)
+ *                       A delete counts as done only on the route's own 204, or its JSON 404
+ *                       (already deleted): anything else, a proxy's 404 included, leaves the
+ *                       row listed and says so (Acceptance 27). One delete per id at a time.
+ *
+ * **The unread count** (`editor.submissions`) is set from every answer: a list's and a
+ * GET's `unread`, a 204's `X-Caracms-Unread`. A 503 (`submissions-unset`: the production
+ * server has no bucket) sets the `submissions-off` state.
+ */
+import { formatBytes } from '../../../forms/rules.ts';
+import { ENDPOINTS, UNREAD_HEADER, type SignedOutError, type SubmissionResponse, type SubmissionRow, type SubmissionsListResponse, type SubmissionsUnset } from '../../types.ts';
+import type { Editor } from '../editor.ts';
+import { createStore, type Store } from '../state/store.ts';
+
+export interface InboxList {
+	/** Null until the first page has been read. */
+	rows: SubmissionRow[] | null;
+	/** The cursor for Older, or null when there's nothing older. */
+	older: string | null;
+	loading: boolean;
+	olderLoading: boolean;
+	error: string | null;
+}
+
+export interface OpenSubmission {
+	id: string;
+	answer: SubmissionResponse | null;
+	error: string | null;
+}
+
+export interface Inbox {
+	list: Store<InboxList>;
+	open: Store<OpenSubmission | null>;
+	load(): Promise<void>;
+	loadOlder(): Promise<void>;
+	show(id: string): Promise<void>;
+	markUnread(id: string): Promise<{ ok: boolean; error?: string }>;
+	remove(id: string): Promise<{ ok: boolean; error?: string }>;
+}
+
+const inboxes = new WeakMap<Editor, Inbox>();
+
+const COULDNT = "The submissions couldn't be read just now. Try again in a moment.";
+const NOT_REACHED = "The server didn't answer just now, so nothing was deleted. Try again in a moment.";
+
+/** An answer from the inbox's own route (forms/inbox.ts: JSON, or a 204), not a proxy's page. */
+/** The count on a 204 (`X-Caracms-Unread`), or null when it's absent. */
+const unreadHeader = (response: Response): number | null => {
+	const v = response.headers.get(UNREAD_HEADER);
+	return v !== null && /^\d+$/.test(v) ? Number(v) : null;
+};
+const fromRoute = (response: Response) => response.status === 204 || (response.headers.get('content-type') ?? '').includes('application/json');
+
+export function inboxFor(editor: Editor): Inbox {
+	let inbox = inboxes.get(editor);
+	if (!inbox) inboxes.set(editor, (inbox = createInbox(editor)));
+	return inbox;
+}
+
+function createInbox(editor: Editor): Inbox {
+	const first = editor.inboxFirst;
+	const list = createStore<InboxList>({ rows: first?.list?.items ?? null, older: first?.list?.older ?? null, loading: false, olderLoading: false, error: null });
+	const open = createStore<OpenSubmission | null>(first?.open ? { id: first.open.submission.id, answer: first.open, error: null } : null);
+	const base = ENDPOINTS.submissions;
+	const route = (id: string, action?: string) => `${base}/${encodeURIComponent(id)}${action ? `/${action}` : ''}`;
+
+	const setUnread = (n: unknown) => {
+		if (typeof n === 'number' && Number.isInteger(n) && n >= 0) editor.submissions.set({ unread: n });
+	};
+	/** An answer that isn't the data: signed out (live mode), not set up (503), or a sentence to show. */
+	async function trouble(response: Response): Promise<string> {
+		const body = (await response.json().catch(() => null)) as (Partial<SubmissionsUnset> & { error?: string }) | null;
+		if (response.status === 401 && editor.liveSession) editor.liveState.update({ signedOut: body as unknown as SignedOutError });
+		if (response.status === 503 && body?.code === 'submissions-unset') {
+			editor.submissions.set({ unread: null, error: body.error ?? '', code: 'submissions-unset', missing: body.missing ?? [] });
+		}
+		return body?.error ?? COULDNT;
+	}
+	const post = (url: string, body?: unknown) =>
+		fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body ?? {}) });
+
+	/** The latest first-page read wins. */
+	let loads = 0;
+	/** Deletes on their way, by id. */
+	const removing = new Map<string, Promise<{ ok: boolean; error?: string }>>();
+
+	const inbox: Inbox = {
+		list,
+		open,
+
+		async load() {
+			const ticket = ++loads;
+			list.update({ loading: true });
+			try {
+				const response = await fetch(base, { headers: { Accept: 'application/json' } });
+				if (ticket !== loads) return;
+				if (!response.ok) {
+					list.update({ loading: false, error: await trouble(response) });
+					return;
+				}
+				const body = (await response.json()) as SubmissionsListResponse;
+				if (ticket !== loads) return;
+				setUnread(body.unread);
+				list.set({ rows: body.items, older: body.older, loading: false, olderLoading: false, error: null });
+			} catch {
+				if (ticket === loads) list.update({ loading: false, error: COULDNT });
+			}
+		},
+
+		async loadOlder() {
+			const { older, olderLoading } = list.get();
+			if (!older || olderLoading) return;
+			list.update({ olderLoading: true });
+			try {
+				const response = await fetch(`${base}?before=${encodeURIComponent(older)}`, { headers: { Accept: 'application/json' } });
+				if (!response.ok) {
+					list.update({ olderLoading: false, error: await trouble(response) });
+					return;
+				}
+				const body = (await response.json()) as SubmissionsListResponse;
+				setUnread(body.unread);
+				list.set((l) => {
+					const have = new Set((l.rows ?? []).map((r) => r.id));
+					return { ...l, rows: [...(l.rows ?? []), ...body.items.filter((r) => !have.has(r.id))], older: body.older, olderLoading: false, error: null };
+				});
+			} catch {
+				list.update({ olderLoading: false, error: COULDNT });
+			}
+		},
+
+		async show(id) {
+			const known = open.get();
+			// The same one again keeps what's on the sheet while it's read again.
+			open.set(known?.id === id ? { ...known, error: null } : { id, answer: null, error: null });
+			let answer: SubmissionResponse;
+			try {
+				const response = await fetch(route(id), { headers: { Accept: 'application/json' } });
+				if (!response.ok) {
+					const error = response.status === 404 ? "There's no such submission. It may have been deleted." : await trouble(response);
+					if (open.get()?.id === id) open.set({ id, answer: null, error });
+					return;
+				}
+				answer = (await response.json()) as SubmissionResponse;
+			} catch {
+				if (open.get()?.id === id) open.set({ id, answer: null, error: COULDNT });
+				return;
+			}
+			setUnread(answer.unread);
+			if (open.get()?.id !== id) return;
+			open.set({ id, answer, error: null });
+			// Decision 9: opening it marks it read, an explicit write (the GET changed nothing).
+			if (answer.submission.readAt === null) {
+				const now = new Date().toISOString();
+				const shown = { ...answer, submission: { ...answer.submission, readAt: now } };
+				open.set({ id, answer: shown, error: null });
+				patchRow(id, { readAt: now });
+				try {
+					const response = await post(route(id, 'read'));
+					if (response.ok) setUnread(unreadHeader(response));
+					else await trouble(response);
+				} catch {
+					/* it stays unread on the server; the next list says so */
+				}
+			}
+		},
+
+		async markUnread(id) {
+			try {
+				const response = await post(route(id, 'unread'));
+				if (response.status !== 204) return { ok: false, error: await trouble(response) };
+				setUnread(unreadHeader(response));
+			} catch {
+				return { ok: false, error: COULDNT };
+			}
+			patchRow(id, { readAt: null });
+			if (open.get()?.id === id) open.set(null);
+			return { ok: true };
+		},
+
+		remove(id) {
+			// One delete per submission at a time: a second press (a double click) waits for the first.
+			const running = removing.get(id);
+			if (running) return running;
+			const done = (async (): Promise<{ ok: boolean; error?: string }> => {
+				try {
+					const response = await post(route(id, 'delete'), { confirm: true });
+					// Gone only on the route's own answers: its 204, or its JSON 404 (deleted already, by
+					// someone else). A 404 from anything in between (a proxy, the platform's edge while a
+					// deploy switches) never reached the route: nothing was deleted (Acceptance 27).
+					const gone = response.status === 204 || (response.status === 404 && fromRoute(response));
+					if (!gone) return { ok: false, error: response.status === 404 ? NOT_REACHED : await trouble(response) };
+					if (response.status === 204) setUnread(unreadHeader(response));
+				} catch {
+					return { ok: false, error: COULDNT };
+				}
+				list.set((l) => ({ ...l, rows: l.rows ? l.rows.filter((r) => r.id !== id) : l.rows }));
+				if (open.get()?.id === id) open.set(null);
+				// The list as the server has it now (last known stays meanwhile).
+				void inbox.load();
+				return { ok: true };
+			})();
+			removing.set(id, done);
+			void done.finally(() => removing.delete(id));
+			return done;
+		},
+	};
+
+	function patchRow(id: string, patch: Partial<SubmissionRow>) {
+		list.set((l) => (l.rows?.some((r) => r.id === id) ? { ...l, rows: l.rows.map((r) => (r.id === id ? { ...r, ...patch } : r)) } : l));
+	}
+
+	return inbox;
+}
+
+// ── How the inbox words things ───────────────────────────────────────────────
+
+/** "1 file", "2 files". */
+export const filesLabel = (n: number) => `${n} file${n === 1 ? '' : 's'}`;
+
+/** A file's size and kind: "1.4 MB · PDF". */
+export function fileLine(size: number, ext: string): string {
+	return `${formatBytes(size)} · ${EXT_NAME[ext] ?? ext}`;
+}
+const EXT_NAME: Record<string, string> = {
+	PDF: 'PDF',
+	JPG: 'JPEG image',
+	PNG: 'PNG image',
+	WEBP: 'WebP image',
+	HEIC: 'HEIC image',
+	HEIF: 'HEIF image',
+	DOCX: 'Word document',
+	DOC: 'Word document',
+	XLSX: 'Excel spreadsheet',
+	XLS: 'Excel spreadsheet',
+};
+
+const safeZone = (timeZone: string) => {
+	try {
+		new Intl.DateTimeFormat('en-GB', { timeZone });
+		return timeZone;
+	} catch {
+		return 'UTC';
+	}
+};
+function dayParts(iso: string | Date, timeZone: string) {
+	const f = new Intl.DateTimeFormat('en-GB', { timeZone, year: 'numeric', month: 'short', day: 'numeric', weekday: 'short', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });
+	const out: Record<string, string> = {};
+	for (const p of f.formatToParts(typeof iso === 'string' ? new Date(iso) : iso)) out[p.type] = p.value;
+	return out as { year: string; month: string; day: string; weekday: string; hour: string; minute: string };
+}
+const dayKey = (p: { year: string; month: string; day: string }) => `${p.year}-${p.month}-${p.day}`;
+
+/**
+ * A row's time (the mockup's): "14:12" today, "Yesterday", "Tue 13 Oct", and another
+ * year's "13 Oct 2025". In the site's zone.
+ */
+export function rowTime(iso: string, timeZone: string, now: Date = new Date()): string {
+	const zone = safeZone(timeZone);
+	const p = dayParts(iso, zone);
+	const n = dayParts(now, zone);
+	if (dayKey(p) === dayKey(n)) return `${p.hour}:${p.minute}`;
+	const yesterday = dayParts(new Date(now.getTime() - 86_400_000), zone);
+	if (dayKey(p) === dayKey(yesterday)) return 'Yesterday';
+	return p.year === n.year ? `${p.weekday} ${p.day} ${p.month}` : `${p.day} ${p.month} ${p.year}`;
+}
+
+/** The zone as people say it: "Ireland Time", "New Zealand Time"; UTC as "UTC". */
+export function zoneName(timeZone: string): string {
+	const zone = safeZone(timeZone);
+	if (zone === 'UTC' || zone === 'Etc/UTC') return 'UTC';
+	try {
+		const name = new Intl.DateTimeFormat('en-GB', { timeZone: zone, timeZoneName: 'longGeneric' }).formatToParts(new Date()).find((p) => p.type === 'timeZoneName')?.value;
+		if (name && !/^GMT[+-]/.test(name)) return name;
+	} catch {
+		/* below */
+	}
+	return zone;
+}
+
+/** The sheet's full time: "Thursday 15 October 2026, 14:12 Ireland Time". */
+export function fullTime(iso: string, timeZone: string): string {
+	const zone = safeZone(timeZone);
+	const f = new Intl.DateTimeFormat('en-GB', { timeZone: zone, weekday: 'long', day: 'numeric', month: 'long', year: 'numeric', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });
+	const p: Record<string, string> = {};
+	for (const part of f.formatToParts(new Date(iso))) p[part.type] = part.value;
+	return `${p.weekday} ${p.day} ${p.month} ${p.year}, ${p.hour}:${p.minute} ${zoneName(zone)}`;
+}
+
+/** "14:12" (today) or "15 Oct, 14:12" for the email's line: when it went. */
+export function shortTime(iso: string, timeZone: string, now: Date = new Date()): string {
+	const zone = safeZone(timeZone);
+	const p = dayParts(iso, zone);
+	const n = dayParts(now, zone);
+	return dayKey(p) === dayKey(n) ? `${p.hour}:${p.minute}` : `${p.day} ${p.month}${p.year === n.year ? '' : ` ${p.year}`}, ${p.hour}:${p.minute}`;
+}
+
+/** Reply by email (Decision 9): the visitor's address percent-encoded, so a crafted one can't add recipients or headers. */
+export function replyHref(address: string, brandName: string): string {
+	return `mailto:${encodeURIComponent(address)}?subject=${encodeURIComponent(`Re: your enquiry to ${brandName}`)}`;
+}

package/src/editor/client/live/format.ts

@@ -0,0 +1,77 @@
+/**
+ * People and times as live mode shows them (M4 Decision 16; M2 Decision 18).
+ *
+ * - **Times are absolute, in the site's time zone** (`StatusResponse.timeZone`):
+ *   "14:20", "Today 14:20", "12 Oct, 09:30" (another year adds it). "Today" is the
+ *   server's day (`status.now`), so the server's render and the browser's agree.
+ *   History names the zone once (`zoneLine`).
+ * - **People**: a name is the person's own, else the part of the address before `@`
+ *   (live/messages.ts → displayName); the avatar's colour comes from the address, so
+ *   a person is the same colour everywhere.
+ */
+import { displayName } from '../../../live/messages.ts';
+import type { Person } from '../../types.ts';
+
+export { displayName };
+
+const safeZone = (timeZone: string) => {
+	try {
+		new Intl.DateTimeFormat('en-GB', { timeZone });
+		return timeZone;
+	} catch {
+		return 'UTC';
+	}
+};
+
+function parts(iso: string, timeZone: string) {
+	const f = new Intl.DateTimeFormat('en-GB', { timeZone: safeZone(timeZone), year: 'numeric', month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });
+	const out: Record<string, string> = {};
+	for (const p of f.formatToParts(new Date(iso))) out[p.type] = p.value;
+	return out as { year: string; month: string; day: string; hour: string; minute: string };
+}
+
+/** "14:20" in the site's zone. */
+export function clock(iso: string, timeZone: string): string {
+	const p = parts(iso, timeZone);
+	return `${p.hour}:${p.minute}`;
+}
+
+/** "Today 14:20", "12 Oct, 09:30", "12 Oct 2025, 09:30": absolute, in the site's zone. */
+export function when(iso: string, timeZone: string, now: string): string {
+	const p = parts(iso, timeZone);
+	const n = parts(now, timeZone);
+	if (p.year === n.year && p.month === n.month && p.day === n.day) return `Today ${p.hour}:${p.minute}`;
+	return `${p.day} ${p.month}${p.year === n.year ? '' : ` ${p.year}`}, ${p.hour}:${p.minute}`;
+}
+
+/** History's one line naming the zone: "Times are Ireland Time (Europe/Dublin)." */
+export function zoneLine(timeZone: string): string {
+	const zone = safeZone(timeZone);
+	if (zone === 'UTC') return 'Times are UTC.';
+	try {
+		const name = new Intl.DateTimeFormat('en-GB', { timeZone: zone, timeZoneName: 'longGeneric' }).formatToParts(new Date()).find((p) => p.type === 'timeZoneName')?.value;
+		if (name && name !== zone) return `Times are ${name} (${zone}).`;
+	} catch {
+		/* below */
+	}
+	return `Times are in ${zone}.`;
+}
+
+/** "Home", "Home and About", "Home, About and Contact". */
+export function joinNames(names: readonly string[]): string {
+	if (names.length < 2) return names.join('');
+	return `${names.slice(0, -1).join(', ')} and ${names.at(-1)}`;
+}
+
+const COLOURS = ['var(--p-niamh)', 'var(--p-aoife)', 'var(--p-ciaran)'];
+
+/** A person's avatar colour (one of the mockup's three), the same for them everywhere. */
+export function colourOf(person: Person): string {
+	let h = 0;
+	for (const c of person.email.toLowerCase()) h = (h * 31 + c.charCodeAt(0)) >>> 0;
+	return COLOURS[h % COLOURS.length]!;
+}
+
+export const initialOf = (person: Person) => (displayName(person).trim()[0] ?? '?').toUpperCase();
+
+export const samePerson = (a: Person | null | undefined, b: Person | null | undefined) => !!a && !!b && a.email.toLowerCase() === b.email.toLowerCase();