// ─── template-format-editor.jsx ──────────────────────────────────────────────
// "Quiz · gaming" templates by format, part 1: the guided EMAIL editor, a full screen inside
// "Layout library" › "Quiz · gaming" › "Manage templates".
//
// Omar, 2026-11-04: "an Editor creates "Quiz · gaming" templates by format, without writing HTML";
// 2026-11-05: "[431] Part 1's plan approved" · "[432] … Hide "Your own HTML" as a choice for new
// templates for now (hide it, don't remove it)". Prototype 3 is the specification
// (wiki/findings/2026-11-04-quiz-gaming-template-formats.md §9–§12): its blocks in their fixed order,
// each switched on or off, its fields and limits, its samples, and beside them the page itself.
//
// What this screen owns, and what it does not:
// · the form, the preview and the checks. The page is built by template-formats.js, the SAME code
// for the preview and for what is saved, so the preview is the page a learner gets (plan D1);
// · "Create template" / "Save changes" stay unavailable while a check fails or has not run yet:
// a length that was never measured is not a length within the limit;
// · unsaved work (plan D7): leaving the screen or the site asks first (the app's own question,
// through `useScreenWork`), choosing a sample asks before replacing, and nothing closes on a click
// outside, because there is no outside: the editor is the screen.
// The server keeps its own guarantees (routes/templates.ts): the page is validated like any template's,
// and the page and its form are saved together.
//
// Every top-level name starts with `Tf`: every screen file shares one scope in the browser
// (`feedback_the_in_browser_compiler_shares_helper_names_across_files`, plan D8).
// The preview shows the course player's area on a computer: 950 × 480, centred (measured 2026-11-04, finding §3).
// No other screen is offered (Omar, 2026-11-05: "The preview always shows the computer size."); the length check
// still measures every screen it covers, out of sight (`TfLengthProbes`).
const TF_AREA_WIDTH = 950;
const TF_AREA_HEIGHT = 480;
/**
* A page as a blob: address the frame can open. Through `safeFrameSrc` and `sandbox="allow-scripts"` like every
* template preview in the app (`resolveHtmlPreviewUrl`, html-templates.jsx): the page's scripts run, in an OPAQUE
* origin, so they cannot reach this app. Each address is given back once its page is replaced.
*/
function useTfPageUrl(html) {
const url = React.useMemo(() => {
try { return URL.createObjectURL(new Blob([html], { type: 'text/html' })); } catch (_) { return ''; }
}, [html]);
React.useEffect(() => () => { try { if (url) URL.revokeObjectURL(url); } catch (_) { /* gone */ } }, [url]);
return url;
}
/** The value, `ms` after it last changed: the preview and the length check follow typing, not every key. */
function useTfSettled(value, ms) {
const [settled, setSettled] = React.useState(value);
React.useEffect(() => {
const t = setTimeout(() => setSettled(value), ms);
return () => clearTimeout(t);
}, [value, ms]);
return settled;
}
/**
* The guided email editor.
* template — `{ _new: true }` for a new one, or the registry entry being edited (its `formValues`)
* onSave — called with `{ _new, serverId, name, html, format, formValues }`
* onClose — leave the editor (asked first by the caller's screen work when there are changes)
*/
function TfEmailEditor({ template, busy, error, onSave, onClose }) {
const TF = window.DynamoTemplateFormats;
const ConfirmDialog = window.ConfirmDialog;
const isNew = !!template._new;
const [name, setName] = React.useState(isNew ? '' : (template.name || ''));
const [values, setValues] = React.useState(() => (isNew
? TF.normaliseEmail(TF.EMAIL_SAMPLES[TF.DEFAULT_SAMPLE].v)
: TF.normaliseEmail(template.formValues)));
const [open, setOpen] = React.useState(() => new Set(['header']));
const [askSample, setAskSample] = React.useState(null); // a sample key waiting for "Replace"
const [pictureError, setPictureError] = React.useState(null); // { key, message }
// The sample the form last started from: "Start from a sample" shows it, it is saved with the template, and a
// picture's "Sample" puts that sample's picture back. A template saved before 2026-11-05 names none (null).
const [sampleKey, setSampleKey] = React.useState(isNew ? TF.DEFAULT_SAMPLE : TF.sampleOf(template.formValues));
// ★ Unsaved changes, against what was opened. Read at the moment of leaving (`useScreenWork`), never a copy.
// The sample's name is saved with the template, so choosing another one is a change too (review, 2026-11-05).
const baseline = React.useRef(JSON.stringify({ name: isNew ? '' : (template.name || ''), values, sampleKey }));
const dirty = JSON.stringify({ name, values, sampleKey }) !== baseline.current;
window.useScreenWork('template-email-editor', 'the email template', () => dirty, isNew ? 'Create template' : 'Save changes');
const setValue = React.useCallback((k, v) => setValues(prev => ({ ...prev, [k]: v })), []);
// ── what would be saved, and its checks ──
const pageHtml = React.useMemo(() => TF.buildTemplate('email', values), [values]);
const pageBytes = TF.sizeBytes(pageHtml);
const settledValues = useTfSettled(values, 450);
const [measured, setMeasured] = React.useState({ build: -1, metrics: {} });
const build = React.useRef(0);
const probeBuild = React.useMemo(() => { build.current += 1; return build.current; }, [settledValues]);
const lengthPending = measured.build !== probeBuild
|| TF.LIMIT_SCREENS.some(s => !measured.metrics[s.w]);
// While the length is measured again, the last complete measurement stands: otherwise the checks vanished on every
// pause in typing and came back, and the preview jumped with them (review, 2026-11-05). Saving waits either way.
const lastLength = React.useRef({});
if (!lengthPending) lastLength.current = measured.metrics;
const problems = TF.problems(values, lengthPending ? lastLength.current : measured.metrics);
if (!name.trim()) problems.unshift({ key: 'name', where: 'Name', text: 'Give the template a name, so authors can find it in “Pick from samples”.' });
if (pageBytes > TF.MAX_PAGE_BYTES) {
problems.push({ key: 'size', where: 'Too big', text: `the template is ${Math.round(pageBytes / 1024)} KB with its pictures; the limit is 256 KB. Please use smaller pictures.` });
}
const typing = settledValues !== values;
const blocked = busy || problems.length > 0 || lengthPending || typing;
const save = () => {
if (blocked) return;
onSave({
_new: isNew, serverId: template.serverId, name: name.trim(),
html: TF.buildTemplate('email', values), format: 'email', formValues: TF.formValuesFor(values, sampleKey),
});
};
const leave = () => {
if (!dirty || typeof window.dynamoConfirmLeave !== 'function') { onClose(); return; }
window.dynamoConfirmLeave('screen').then(ok => { if (ok) onClose(); });
};
// ── the learner's places: inserted where the cursor was ──
const lastFocus = React.useRef(null); // { kind: 'input', el, set } | { kind: 'rich', el }
const insertPlace = (place) => {
const f = lastFocus.current;
if (!f || !f.el || !document.body.contains(f.el)) return;
if (f.kind === 'rich') {
f.el.focus();
document.execCommand('insertText', false, place);
return;
}
const el = f.el;
const s = el.selectionStart ?? el.value.length, e = el.selectionEnd ?? s;
const next = el.value.slice(0, s) + place + el.value.slice(e);
f.set(next);
requestAnimationFrame(() => { try { el.focus(); el.setSelectionRange(s + place.length, s + place.length); } catch (_) { /* gone */ } });
};
// A field the learner's places can go into: the chips insert where its cursor was. `set` writes the new text.
const track = (set) => ({ onFocus: (e) => { lastFocus.current = { kind: 'input', el: e.currentTarget, set }; } });
const replaceWithSample = (key) => {
setAskSample(null);
setValues(TF.normaliseEmail(TF.sampleFor(key).v, key));
setSampleKey(key);
setPictureError(null);
};
const toggleBlock = (id) => setOpen(prev => { const n = new Set(prev); if (n.has(id)) n.delete(id); else n.add(id); return n; });
return (
{/* Top bar: back, where this is, and the two actions */}
Learner details: click to insert at the cursor. The course player fills them from the
“Learner details form”. The preview shows them for a sample learner, Robin Ashdale.
);
}
function TfLabeled({ label, htmlFor, count, children }) {
return (
{count}
{children}
);
}
/** "n / max", red when over: the limit is the editor saying so, never the field refusing a key ([412]). */
function TfCount({ n, max }) {
if (!max) return null;
const over = n > max;
return (
{n} / {max}
);
}
function TfBlock({ n, block, values, setValue, open, onToggle, track, lastFocus, sampleKey, pictureError, setPictureError }) {
const on = block.always || !!values[block.on];
const hasFields = block.fields.length > 0;
return (