@websline/cms-view-utils 1.10.2 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@websline/cms-view-utils",
-  "version": "1.10.2",
+  "version": "1.14.0",
   "type": "module",
   "files": [
     "src",
@@ -18,21 +18,22 @@
     "./dist/*": "./dist/*"
   },
   "dependencies": {
+    "altcha-lib": "2.6.0",
     "jsonwebtoken": "^9.0.3",
     "tailwind-merge": "^3.7.0"
   },
   "devDependencies": {
     "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.11.0",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-svelte": "^3.23.0",
-    "globals": "^17.12.0",
-    "prettier": "^3.9.8",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.9",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.1",
     "tsup": "^8.5.1",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.3"
   },
   "peerDependencies": {
     "astro": ">=5",

package/src/ads/createAdRunner.js

@@ -108,6 +108,7 @@ const createAdRunner = ({
 	const occupied = new Map();
 	const teardowns = [];
 	const counted = new Set();
+	const sent = new Set();
 	const shown = [];
 
 	/**
@@ -218,11 +219,24 @@ const createAdRunner = ({
 			if (!ad.persistent) release(ad);
 		},
 
+		/**
+		 * The ad's form was sent: its click, suppressed like one, but it stays on
+		 * screen with the thanks until the visitor closes it.
+		 */
+		sent(ad) {
+			if (!ad || sent.has(ad.uuid)) return;
+
+			sent.add(ad.uuid);
+			track(ad.uuid, "click");
+			dismissals.record(ad.uuid, Date.now());
+		},
+
 		/** An ad that is not closable has no close button, so nothing to dismiss. */
 		dismiss(ad) {
 			if (!ad || ad.closable === false) return;
 
-			track(ad.uuid, "close");
+			// Closing the thanks of a sent form turns nothing down.
+			if (!sent.has(ad.uuid)) track(ad.uuid, "close");
 			release(ad);
 		},
 

package/src/client/fetchFormChallenge.js

@@ -0,0 +1,21 @@
+/**
+ * Fetch a fresh ALTCHA spam challenge for one form; needed while the form's `spam.captcha` is `true`.
+ *
+ * @param {object} options
+ * @param {string} options.uuid - UUID of the form.
+ * @returns {Promise<object>} The challenge, to solve and send as `altcha` with the submit. It expires after ten minutes, names its form and stores one entry only.
+ */
+const fetchFormChallenge = async ({ uuid }) => {
+	const response = await fetch(`/api/cms/api/public/forms/${uuid}/challenge`, {
+		method: "GET",
+		cache: "no-store",
+	});
+
+	if (!response.ok) {
+		throw new Error(`Challenge failed with ${response.status}`);
+	}
+
+	return response.json();
+};
+
+export { fetchFormChallenge };

package/src/client/submitForm.js

@@ -0,0 +1,32 @@
+/**
+ * Submit a form's values; the CMS checks them against the live form and stores the entry.
+ *
+ * @param {object} options
+ * @param {string} options.uuid - UUID of the form.
+ * @param {string} options.locale - Language the visitor filled the form in; decides the texts of the answer and of the confirmation mail.
+ * @param {Record<string, unknown>} options.values - Keyed by field `name`: text, textarea, email, phone, select → string; checkbox → array of option values, or boolean without options; date → `YYYY-MM-DD`; daterange → `{ from, to }`; persons → `{ adults, children: [age] }`; room, package → the option `value`.
+ * @param {string} [options.honeypot] - Content of the hidden honeypot input; empty for a real visitor.
+ * @param {boolean} [options.consent] - `true` once the guest agreed to the privacy policy; required while the form has `consent`.
+ * @param {{ challenge: object, solution: object }} [options.altcha] - A solved challenge from `fetchFormChallenge`; required while the form's `spam.captcha` is `true`. Missing, wrong, expired or already used, the answer is `422` with the error field `altcha`.
+ * @param {{ path?: string, adUuid?: string }} [options.source] - Where the form was sent from: the page path without leading slash and language segment, and the ad that opened the form.
+ * @returns {Promise<{ status: number, data: object }>} `201` with `{ mode: "redirect", url }` or `{ mode: "message", message }`; `422` with `errors: [{ field, code }]`; `429` once the visitor sent too many; `404` for a form that is gone or inactive.
+ */
+const submitForm = async ({
+	uuid,
+	locale,
+	values,
+	honeypot,
+	consent,
+	altcha,
+	source,
+}) => {
+	const response = await fetch(`/api/cms/api/public/forms/${uuid}/submissions`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ locale, values, honeypot, consent, altcha, source }),
+	});
+
+	return { status: response.status, data: await response.json().catch(() => ({})) };
+};
+
+export { submitForm };

package/src/cms/fetchPage.js

@@ -19,7 +19,11 @@ const fetchPage = async (context) => {
 	const draftUuid = resolveDraftUuidFromToken(editorToken);
 	const isCMSEditRoute = editorToken && draftUuid;
 
-	const cmsUrl = buildCmsPageUrl({ draftUuid, path });
+	const cmsUrl = buildCmsPageUrl({
+		draftUuid,
+		path,
+		searchParams: url.searchParams,
+	});
 
 	const response = await fetch(cmsUrl, {
 		method: "GET",

package/src/cms/proxyToCms.js

@@ -4,6 +4,30 @@ import { HttpError } from "../shared/errors.js";
 /** The events endpoint answers this, and a Response with a body on it throws. */
 const NO_CONTENT = 204;
 
+/**
+ * The visitor's IP, behind nginx or behind CloudFront. nginx always overwrites
+ * `X-Real-IP`, so it wins; CloudFront names the viewer as `ip:port` and must not
+ * pass a viewer-sent `X-Real-IP` through.
+ */
+const visitorIpOf = (headers) => {
+	const realIp = headers.get("x-real-ip");
+	if (realIp) return realIp;
+
+	const viewer = headers.get("cloudfront-viewer-address") ?? "";
+	const portAt = viewer.lastIndexOf(":");
+
+	return portAt > 0 ? viewer.slice(0, portAt) : viewer;
+};
+
+/**
+ * A path the allowlist can judge as it will be requested. `fetch` turns `\` into
+ * `/` and resolves dot segments, so `forms/..\..\x/submissions` would match the
+ * list and still reach another route.
+ */
+const isPlainPath = (path) =>
+	!/[\\%]/.test(path) &&
+	!path.split("/").some((segment) => segment === "." || segment === "..");
+
 const proxyToCms = async (context, { allow } = {}) => {
 	const cmsBase = import.meta.env.CMS_URL;
 
@@ -17,7 +41,7 @@ const proxyToCms = async (context, { allow } = {}) => {
 	// A write forwards the site's CMS token, and that token may carry scopes far
 	// beyond page delivery. Writes therefore reach only the paths named by the
 	// route that opened them, and everything else looks like it is not there.
-	if (allow && !allow(path)) {
+	if (allow && (!isPlainPath(path) || !allow(path))) {
 		throw new HttpError(404, "Not Found");
 	}
 	const url = new URL(request.url);
@@ -33,12 +57,17 @@ const proxyToCms = async (context, { allow } = {}) => {
 			? {
 					...buildCmsHeaders(request),
 					"content-type": request.headers.get("content-type") ?? "application/json",
+					"cms-visitor-ip": visitorIpOf(request.headers),
 				}
 			: buildCmsHeaders(request),
 		...(hasBody ? { body: await request.text() } : {}),
 	});
 
-	if (!response.ok) {
+	// A rejected write answers the visitor directly — a form shows the field errors
+	// of a 422 — so its body has to reach the browser.
+	const isRejectedWrite = hasBody && response.status >= 400 && response.status < 500;
+
+	if (!response.ok && !isRejectedWrite) {
 		throw new HttpError(response.status, "CMS Error");
 	}
 
@@ -47,11 +76,15 @@ const proxyToCms = async (context, { allow } = {}) => {
 	}
 
 	const data = await response.text();
+	// nginx caches every GET for minutes unless told not to; a spam challenge,
+	// for one, must reach each visitor fresh.
+	const noStore = /no-store/i.test(response.headers.get("cache-control") ?? "");
 
 	return new Response(data, {
 		status: response.status,
 		headers: {
 			"content-type": response.headers.get("content-type") ?? "application/json",
+			...(noStore ? { "cache-control": "no-store" } : {}),
 		},
 	});
 };

package/src/cms/urlResolver.js

@@ -1,13 +1,26 @@
 const CMS_BASE_URL = import.meta.env.CMS_URL;
 
-const buildCmsPageUrl = ({ draftUuid, path }) => {
+// The editor's own parameters say nothing about the page.
+const EDITOR_PARAMS = ["editorToken", "cmsLocale"];
+
+/**
+ * The page's own query string goes along, so forms on the page come pre-filled
+ * from the link, e.g. the quick bar's `?arrival=…&departure=…`.
+ *
+ * @param {{ draftUuid?: string, path: string, searchParams?: URLSearchParams }} options
+ */
+const buildCmsPageUrl = ({ draftUuid, path, searchParams }) => {
+	const query = new URLSearchParams(searchParams);
+	EDITOR_PARAMS.forEach((name) => query.delete(name));
+	const search = query.size ? `?${query}` : "";
+
 	if (draftUuid) {
-		return `${CMS_BASE_URL}/api/public/pages/preview/${draftUuid}`;
+		return `${CMS_BASE_URL}/api/public/pages/preview/${draftUuid}${search}`;
 	}
 
 	const normalizedPath = path.startsWith("/") ? path : `/${path}`;
 
-	return `${CMS_BASE_URL}/api/public/pages${normalizedPath}`;
+	return `${CMS_BASE_URL}/api/public/pages${normalizedPath}${search}`;
 };
 
 const buildCmsAdsUrl = ({ locale, path }) => {

package/src/forms/createFormController.js

@@ -0,0 +1,326 @@
+import { toAdPath } from "../ads/adPath.js";
+import { submitForm } from "../client/submitForm.js";
+import { createFieldStates } from "./fieldStates.js";
+import { createFormTexts } from "./formTexts.js";
+import { createSpamChallenge } from "./spamChallenge.js";
+import {
+	fieldsOf,
+	initialValues,
+	submissionValues,
+	validateValues,
+} from "./formValues.js";
+
+/**
+ * Runs one form on the website: values, the check per page, the honeypot,
+ * sending, and what follows. Rendering stays with the template, which reads the
+ * state through the store contract (`$form` in Svelte) and calls the actions.
+ *
+ * Everything the guest or the CMS wrote — labels, pre-filled values, the
+ * thank-you message — is plain text. Print it escaped, never as HTML.
+ */
+
+const CONSENT_FIELD = "consent";
+const CHALLENGE_FIELD = "altcha";
+
+/** Only these are followed after a submit; anything else could run script here. */
+const SAFE_REDIRECT = /^(https?:\/\/|\/(?!\/))/i;
+
+/**
+ * The honeypot input's attributes. Kept off-screen rather than hidden, which
+ * bots recognise; out of the tab order, so people never land in it.
+ */
+const HONEYPOT_ATTRIBUTES = {
+	type: "text",
+	name: "wl_hp",
+	autocomplete: "off",
+	tabindex: -1,
+	"aria-hidden": "true",
+	style: "position:absolute;left:-9999px;width:1px;height:1px;overflow:hidden",
+};
+
+const ERROR_TEXT_KEYS = {
+	INVALID: "errorInvalid",
+	PAST_DATE: "errorPastDate",
+	REQUIRED: "errorRequired",
+	TOO_LONG: "errorTooLong",
+};
+
+/**
+ * @typedef {object} FormState
+ * @property {number} step - 0-based index of the page shown.
+ * @property {Record<string, unknown>} values - Keyed by field name.
+ * @property {boolean} consent
+ * @property {string} honeypot - Bind to a hidden input people leave empty.
+ * @property {Record<string, string>} errors - Error code per field name; `consent` for the consent checkbox.
+ * @property {"idle" | "sending" | "sent"} status
+ * @property {"tooManyRequests" | "sendFailed" | null} notice - A problem that belongs to no single field; a text key.
+ * @property {string | null} message - The thank-you message, once sent; `null` while a redirect is under way.
+ */
+
+/**
+ * What a template draws from the state, computed on every change.
+ *
+ * @typedef {object} FormViewParts
+ * @property {object} page - The page shown, from `form.pages`.
+ * @property {boolean} isFirst
+ * @property {boolean} isLast
+ * @property {{ number: number, label: string | null, current: boolean, done: boolean }[]} steps - For a progress display; one entry per page.
+ * @property {string} submitLabel - The main button's text: next page, sending, or send.
+ * @property {Record<string, object>} fields - Per field name: `control` (see `FORM_CONTROLS`), `field`, `id`, `name`, `value`, `set`, `error`, `errorMessage`, `invalid`, `helpId`, `errorId`, `describedBy`, and what the control needs, see `fieldStates.js`.
+ * @property {object | null} consentField - The consent checkbox: `id`, `text`, `privacyUrl`, `checked`, `set` and the error parts of a field; `null` without one.
+ */
+
+/** What the store hands out. @typedef {FormState & FormViewParts} FormView */
+
+/**
+ * @param {object} options
+ * @param {object} options.form - The form as the page delivers it, e.g. a form block's `form`.
+ * @param {string} [options.adUuid] - The ad showing the form: sent along as the entry's source, and part of every element id.
+ * @param {() => void} [options.onSent] - Called once the CMS stored the entry, before the thanks or the redirect; an ad reports its `click` here.
+ * @param {Record<string, Record<string, string>>} [options.texts] - Texts the project words differently, see `createFormTexts`.
+ * @param {Pick<Location, "pathname" | "assign">} [options.location] - Where the form sits and where a redirect goes; the browser's by default.
+ * @param {() => Date} [options.now] - For tests.
+ */
+const createFormController = ({
+	form,
+	adUuid,
+	onSent,
+	texts,
+	location = globalThis.location,
+	now = () => new Date(),
+}) => {
+	const text = createFormTexts(form.locale, texts);
+	const lastStep = form.pages.length - 1;
+	const pageFields = form.pages.map((page) => fieldsOf(page.layouts));
+	const fieldNames = new Set([
+		CONSENT_FIELD,
+		...pageFields.flat().map((field) => field.name),
+	]);
+	// Solving starts with the guest's first input, so it is done before they send.
+	let spam = form.spam?.captcha ? createSpamChallenge(form.uuid) : null;
+
+	/** @type {FormState} */
+	let state = {
+		step: 0,
+		values: initialValues(form),
+		consent: false,
+		honeypot: "",
+		errors: {},
+		status: "idle",
+		notice: null,
+		message: null,
+	};
+	const listeners = new Set();
+
+	const errorText = (code) => text(ERROR_TEXT_KEYS[code] ?? ERROR_TEXT_KEYS.INVALID);
+
+	const withoutError = (name) => {
+		const errors = { ...state.errors };
+		delete errors[name];
+		return errors;
+	};
+
+	const setValue = (name, value) => {
+		spam?.start();
+		update({
+			values: { ...state.values, [name]: value },
+			errors: withoutError(name),
+		});
+	};
+
+	const setConsent = (consent) => {
+		spam?.start();
+		update({ consent, errors: withoutError(CONSENT_FIELD) });
+	};
+
+	const fieldStatesOf = createFieldStates({
+		form,
+		adUuid,
+		fields: pageFields.flat(),
+		text,
+		errorText,
+		valueOf: (name) => state.values[name],
+		setValue,
+		setConsent,
+		now,
+	});
+
+	const submitLabelOf = ({ step, status }) => {
+		if (step < lastStep) return text("next");
+		return text(status === "sending" ? "sending" : "submit");
+	};
+
+	/** @returns {FormView} */
+	const viewOf = (base) => ({
+		...base,
+		page: form.pages[base.step],
+		isFirst: base.step === 0,
+		isLast: base.step === lastStep,
+		steps: form.pages.map((page, index) => ({
+			number: index + 1,
+			label: page.label ?? null,
+			current: index === base.step,
+			done: index < base.step,
+		})),
+		submitLabel: submitLabelOf(base),
+		...fieldStatesOf(base),
+	});
+
+	let view = viewOf(state);
+
+	const update = (changes) => {
+		state = { ...state, ...changes };
+		view = viewOf(state);
+		for (const listener of listeners) listener(view);
+	};
+
+	const consentErrors = () =>
+		form.consent && !state.consent ? { [CONSENT_FIELD]: "REQUIRED" } : {};
+
+	const errorsOfStep = (step) => ({
+		...validateValues(pageFields[step], state.values),
+		...(step === lastStep ? consentErrors() : {}),
+	});
+
+	// The consent checkbox sits on the last page, so its error points there too.
+	const stepOfField = (name) => {
+		if (name === CONSENT_FIELD) return lastStep;
+		const step = pageFields.findIndex((fields) =>
+			fields.some((field) => field.name === name),
+		);
+		return step < 0 ? state.step : step;
+	};
+
+	const next = () => {
+		const errors = errorsOfStep(state.step);
+		update(
+			Object.keys(errors).length
+				? { errors }
+				: { errors: {}, step: Math.min(state.step + 1, lastStep) },
+		);
+	};
+
+	const isRefusedChallenge = ({ status, data }) =>
+		status === 422 && data.errors?.some(({ field }) => field === CHALLENGE_FIELD);
+
+	const send = (altcha) =>
+		submitForm({
+			uuid: form.uuid,
+			locale: form.locale,
+			values: submissionValues(pageFields.flat(), state.values),
+			honeypot: state.honeypot || undefined,
+			consent: form.consent ? state.consent : undefined,
+			altcha,
+			source: {
+				path: toAdPath(location.pathname, form.locale),
+				...(adUuid ? { adUuid } : {}),
+			},
+		});
+
+	const showAnswer = ({ status, data }) => {
+		if (status === 201) {
+			// The entry is stored: a failing callback must not tell the guest to send again.
+			try {
+				onSent?.();
+			} catch {
+				// The website's own problem; the guest still gets the thanks.
+			}
+		}
+
+		if (status === 201 && data.mode === "redirect" && SAFE_REDIRECT.test(data.url)) {
+			location.assign(data.url);
+			update({ status: "sent" });
+			return;
+		}
+
+		// No message, e.g. a thank-you page missing in this language: never an empty box.
+		if (status === 201) {
+			update({ status: "sent", message: data.message || text("thanks") });
+			return;
+		}
+
+		// An error without a field here, like the challenge, has nowhere to show.
+		const fieldErrors = (data.errors ?? []).filter(({ field }) =>
+			fieldNames.has(field),
+		);
+
+		if (status === 422 && fieldErrors.length) {
+			const errors = Object.fromEntries(
+				fieldErrors.map(({ field, code }) => [field, code]),
+			);
+			const step = Math.min(...fieldErrors.map(({ field }) => stepOfField(field)));
+			update({ status: "idle", errors, step });
+			return;
+		}
+
+		update({
+			status: "idle",
+			notice: status === 429 ? "tooManyRequests" : "sendFailed",
+		});
+	};
+
+	return {
+		/** Svelte store contract: called now and on every change. */
+		subscribe(listener) {
+			listeners.add(listener);
+			listener(view);
+			return () => listeners.delete(listener);
+		},
+
+		/** @param {string} key @param {Record<string, string | number>} [params] */
+		text,
+
+		/** The message for an error code, e.g. from `errors[name]`. */
+		errorText,
+
+		/** Spread onto the honeypot input; send its content through `setHoneypot`. */
+		honeypotAttributes: HONEYPOT_ATTRIBUTES,
+
+		setValue,
+
+		setConsent,
+
+		setHoneypot(honeypot) {
+			update({ honeypot });
+		},
+
+		/** On to the next page, once this one is filled in correctly. */
+		next,
+
+		back() {
+			update({ errors: {}, step: Math.max(state.step - 1, 0) });
+		},
+
+		/**
+		 * Checks the last page and sends the values of all pages at once. Before the
+		 * last page — Enter in a field — it turns the page instead.
+		 */
+		async submit() {
+			if (state.status !== "idle") return;
+			if (state.step < lastStep) return next();
+
+			const errors = errorsOfStep(state.step);
+			if (Object.keys(errors).length) {
+				update({ errors });
+				return;
+			}
+
+			update({ errors: {}, notice: null, status: "sending" });
+
+			try {
+				let answer = await send(await spam?.payload());
+				// Expired or spent meanwhile, or the captcha was switched on after this
+				// page was cached: one attempt with a fresh challenge.
+				if (isRefusedChallenge(answer)) {
+					spam ??= createSpamChallenge(form.uuid);
+					answer = await send(await spam.renew());
+				}
+				showAnswer(answer);
+			} catch {
+				update({ status: "idle", notice: "sendFailed" });
+			}
+		},
+	};
+};
+
+export { createFormController };

package/src/forms/fieldStates.js

@@ -0,0 +1,175 @@
+import { controlOf } from "./formControls.js";
+import { withChildCount } from "./formValues.js";
+
+/**
+ * Everything a website needs to draw one field, besides its look: the ids that
+ * tie label, help and error together, the current value and error, the options
+ * to offer and the setters. Built once per field; only what changes with the
+ * values is recomputed on every update.
+ */
+
+/** The CMS's oldest child age. */
+const MAX_CHILD_AGE = 17;
+/** For a CMS that does not send `maxAdults` yet; its own default. */
+const DEFAULT_MAX_ADULTS = 10;
+
+const numberOptions = (from, to, label = String) =>
+	Array.from({ length: to - from + 1 }, (_, index) => ({
+		value: from + index,
+		label: label(from + index),
+	}));
+
+const pad = (number) => String(number).padStart(2, "0");
+
+/** The guest's today, as a date input reads it. */
+const localDay = (date) =>
+	`${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+
+/** What one control adds on top of every field's state; `current` reads the field's value now. */
+const CONTROL_PARTS = {
+	dropdown: ({ field, text }) => ({
+		options: field.options ?? [],
+		placeholder: field.placeholder || text("choose"),
+	}),
+	radio: ({ field }) => ({ options: field.options }),
+	buttons: ({ field }) => ({ options: field.options }),
+	checkboxes: ({ field, set, current }) => ({
+		options: field.options,
+		toggle: (option, checked) =>
+			set(
+				checked
+					? [...current(), option]
+					: current().filter((entry) => entry !== option),
+			),
+	}),
+	daterange: ({ set, current }) => ({
+		setFrom: (from) => set({ ...current(), from }),
+		setTo: (to) => set({ ...current(), to }),
+	}),
+	persons: ({ field, text, set, current }) => ({
+		adultOptions: numberOptions(1, field.maxAdults ?? DEFAULT_MAX_ADULTS),
+		childOptions: field.children ? numberOptions(0, field.maxChildren) : null,
+		ageOptions: numberOptions(0, MAX_CHILD_AGE, (count) => text("years", { count })),
+		setAdults: (adults) => set({ ...current(), adults: Number(adults) }),
+		setChildren: (count) => set(withChildCount(current(), Number(count))),
+		setChildAge: (index, age) =>
+			set({
+				...current(),
+				children: current().children.map((entry, i) =>
+					i === index ? (age === "" || age == null ? null : Number(age)) : entry,
+				),
+			}),
+	}),
+};
+
+/** What changes with value and error, per control. */
+const LIVE_PARTS = {
+	date: ({ field, today }) => ({ min: field.allowPast ? undefined : today }),
+	daterange: ({ field, today, value }) => {
+		const min = field.allowPast ? undefined : today;
+		return { min, minTo: value.from || min };
+	},
+	// Only an age still missing is marked, not the whole field.
+	persons: ({ invalid, value }) => ({
+		ageInvalid: value.children.map((age) => invalid && age == null),
+	}),
+};
+
+const messagesOf = ({ id, help, error, errorText }) => {
+	const helpId = `${id}-help`;
+	const errorId = `${id}-error`;
+
+	return {
+		error,
+		errorMessage: error ? errorText(error) : null,
+		invalid: Boolean(error),
+		helpId,
+		errorId,
+		describedBy:
+			[help && helpId, error && errorId].filter(Boolean).join(" ") || undefined,
+	};
+};
+
+/**
+ * @param {object} options
+ * @param {object} options.form
+ * @param {string} [options.adUuid] - The ad showing the form; part of every id, since the same form may also sit on the page.
+ * @param {object[]} options.fields - All fields of the form.
+ * @param {(key: string, params?: object) => string} options.text
+ * @param {(code: string) => string} options.errorText
+ * @param {(name: string) => unknown} options.valueOf
+ * @param {(name: string, value: unknown) => void} options.setValue
+ * @param {(consent: boolean) => void} options.setConsent
+ * @param {() => Date} options.now
+ */
+const createFieldStates = ({
+	form,
+	adUuid,
+	fields,
+	text,
+	errorText,
+	valueOf,
+	setValue,
+	setConsent,
+	now,
+}) => {
+	const scope = adUuid ? `${form.uuid}-ad-${adUuid}` : form.uuid;
+	const idOf = (key) => `form-${scope}-${key}`;
+
+	const fixed = fields.map((field) => {
+		const control = controlOf(field);
+		const set = (value) => setValue(field.name, value);
+		const current = () => valueOf(field.name);
+
+		return {
+			field,
+			control,
+			id: idOf(field.id),
+			name: field.name,
+			set,
+			...CONTROL_PARTS[control]?.({ field, text, set, current }),
+		};
+	});
+
+	const consentId = idOf("consent");
+
+	/** Keyed by field name, plus the consent checkbox or `null` without one. */
+	return (state) => {
+		const today = localDay(now());
+
+		const fieldStates = Object.fromEntries(
+			fixed.map((entry) => {
+				const value = state.values[entry.name];
+				const messages = messagesOf({
+					id: entry.id,
+					help: entry.field.help,
+					error: state.errors[entry.name],
+					errorText,
+				});
+				const live = LIVE_PARTS[entry.control]?.({
+					field: entry.field,
+					today,
+					value,
+					invalid: messages.invalid,
+				});
+
+				return [entry.name, { ...entry, ...messages, ...live, value }];
+			}),
+		);
+
+		const consentField = form.consent
+			? {
+					id: consentId,
+					text: form.consent.text,
+					privacyUrl: form.privacyUrl ?? null,
+					checked: state.consent,
+					set: setConsent,
+					...messagesOf({ id: consentId, error: state.errors.consent, errorText }),
+				}
+			: null;
+
+		return { fields: fieldStates, consentField };
+	};
+};
+
+export { createFieldStates };

package/src/forms/formControls.js

@@ -0,0 +1,58 @@
+/**
+ * The controls a website draws for a form's fields. The field types are the
+ * CMS's; which control each one gets is decided here, so a website only draws
+ * one component per control. A new field type in the CMS lands here, and every
+ * website then needs a component for any control it adds.
+ *
+ * - `text`, `email`, `tel` — a single-line input; the name is its `type`.
+ * - `textarea` — multi-line text.
+ * - `dropdown` — one choice from `options`, with a `placeholder` first.
+ * - `radio` — one choice from `options`, as a list.
+ * - `buttons` — one choice from `options`, as a row of buttons.
+ * - `checkbox` — a single checkbox; its label is the sentence the guest agrees to.
+ * - `checkboxes` — any number of `options`, ticked through `toggle`.
+ * - `date` — a day, no earlier than `min`.
+ * - `daterange` — arrival and departure through `setFrom` and `setTo`.
+ * - `persons` — adults, and children with an age each.
+ */
+const FORM_CONTROLS = [
+	"text",
+	"email",
+	"tel",
+	"textarea",
+	"dropdown",
+	"radio",
+	"buttons",
+	"checkbox",
+	"checkboxes",
+	"date",
+	"daterange",
+	"persons",
+];
+
+const CONTROL_BY_TYPE = {
+	date: "date",
+	daterange: "daterange",
+	email: "email",
+	package: "dropdown",
+	persons: "persons",
+	phone: "tel",
+	room: "dropdown",
+	text: "text",
+	textarea: "textarea",
+};
+
+/** The control for a field, or `null` for a type this package does not know yet. */
+const controlOf = (field) => {
+	if (field.type === "select") {
+		return field.display === "radio" || field.display === "buttons"
+			? field.display
+			: "dropdown";
+	}
+	if (field.type === "checkbox") {
+		return field.options?.length ? "checkboxes" : "checkbox";
+	}
+	return CONTROL_BY_TYPE[field.type] ?? null;
+};
+
+export { controlOf, FORM_CONTROLS };

package/src/forms/formTexts.js

@@ -0,0 +1,173 @@
+/**
+ * The words a form brings along itself — buttons, captions, error messages —
+ * as opposed to the labels the editor wrote, which arrive with the form. Every
+ * language here works out of the box; a project replaces single texts through
+ * `overrides` without copying the rest.
+ */
+
+const TEXTS = {
+	de: {
+		adults: "Erwachsene",
+		arrival: "Anreise",
+		back: "Zurück",
+		childAge: "Alter Kind {number}",
+		children: "Kinder",
+		choose: "Bitte wählen",
+		departure: "Abreise",
+		errorInvalid: "Bitte prüfen Sie diese Angabe.",
+		errorPastDate: "Dieses Datum liegt in der Vergangenheit.",
+		errorRequired: "Bitte füllen Sie dieses Feld aus.",
+		errorTooLong: "Dieser Text ist zu lang.",
+		next: "Weiter",
+		privacy: "Datenschutzerklärung",
+		required: "Pflichtfeld",
+		sendFailed:
+			"Das Formular konnte nicht gesendet werden. Bitte versuchen Sie es erneut.",
+		sending: "Wird gesendet …",
+		step: "Schritt {current} von {total}",
+		submit: "Absenden",
+		thanks: "Vielen Dank! Ihre Nachricht ist bei uns eingegangen.",
+		tooManyRequests:
+			"Zu viele Anfragen. Bitte versuchen Sie es in einer Minute erneut.",
+		years: "{count} Jahre",
+	},
+	en: {
+		adults: "Adults",
+		arrival: "Arrival",
+		back: "Back",
+		childAge: "Age of child {number}",
+		children: "Children",
+		choose: "Please choose",
+		departure: "Departure",
+		errorInvalid: "Please check this entry.",
+		errorPastDate: "This date is in the past.",
+		errorRequired: "Please fill in this field.",
+		errorTooLong: "This text is too long.",
+		next: "Next",
+		privacy: "Privacy policy",
+		required: "Required",
+		sendFailed: "The form could not be sent. Please try again.",
+		sending: "Sending …",
+		step: "Step {current} of {total}",
+		submit: "Send",
+		thanks: "Thank you! We have received your message.",
+		tooManyRequests: "Too many requests. Please try again in a minute.",
+		years: "{count} years",
+	},
+	it: {
+		adults: "Adulti",
+		arrival: "Arrivo",
+		back: "Indietro",
+		childAge: "Età bambino {number}",
+		children: "Bambini",
+		choose: "Si prega di scegliere",
+		departure: "Partenza",
+		errorInvalid: "Si prega di verificare questo dato.",
+		errorPastDate: "Questa data è nel passato.",
+		errorRequired: "Si prega di compilare questo campo.",
+		errorTooLong: "Questo testo è troppo lungo.",
+		next: "Avanti",
+		privacy: "Informativa sulla privacy",
+		required: "Campo obbligatorio",
+		sendFailed: "Non è stato possibile inviare il modulo. Si prega di riprovare.",
+		sending: "Invio in corso …",
+		step: "Passo {current} di {total}",
+		submit: "Invia",
+		thanks: "Grazie! Abbiamo ricevuto il suo messaggio.",
+		tooManyRequests: "Troppe richieste. Si prega di riprovare tra un minuto.",
+		years: "{count} anni",
+	},
+	fr: {
+		adults: "Adultes",
+		arrival: "Arrivée",
+		back: "Retour",
+		childAge: "Âge de l'enfant {number}",
+		children: "Enfants",
+		choose: "Veuillez choisir",
+		departure: "Départ",
+		errorInvalid: "Veuillez vérifier cette donnée.",
+		errorPastDate: "Cette date est dans le passé.",
+		errorRequired: "Veuillez remplir ce champ.",
+		errorTooLong: "Ce texte est trop long.",
+		next: "Suivant",
+		privacy: "Politique de confidentialité",
+		required: "Champ obligatoire",
+		sendFailed: "Le formulaire n'a pas pu être envoyé. Veuillez réessayer.",
+		sending: "Envoi en cours …",
+		step: "Étape {current} sur {total}",
+		submit: "Envoyer",
+		thanks: "Merci ! Nous avons bien reçu votre message.",
+		tooManyRequests: "Trop de demandes. Veuillez réessayer dans une minute.",
+		years: "{count} ans",
+	},
+	es: {
+		adults: "Adultos",
+		arrival: "Llegada",
+		back: "Atrás",
+		childAge: "Edad del niño {number}",
+		children: "Niños",
+		choose: "Por favor, elija",
+		departure: "Salida",
+		errorInvalid: "Por favor, compruebe este dato.",
+		errorPastDate: "Esta fecha está en el pasado.",
+		errorRequired: "Por favor, rellene este campo.",
+		errorTooLong: "Este texto es demasiado largo.",
+		next: "Siguiente",
+		privacy: "Política de privacidad",
+		required: "Campo obligatorio",
+		sendFailed:
+			"No se ha podido enviar el formulario. Por favor, inténtelo de nuevo.",
+		sending: "Enviando …",
+		step: "Paso {current} de {total}",
+		submit: "Enviar",
+		thanks: "¡Gracias! Hemos recibido su mensaje.",
+		tooManyRequests:
+			"Demasiadas solicitudes. Por favor, inténtelo de nuevo en un minuto.",
+		years: "{count} años",
+	},
+	nl: {
+		adults: "Volwassenen",
+		arrival: "Aankomst",
+		back: "Terug",
+		childAge: "Leeftijd kind {number}",
+		children: "Kinderen",
+		choose: "Maak een keuze",
+		departure: "Vertrek",
+		errorInvalid: "Controleer dit gegeven.",
+		errorPastDate: "Deze datum ligt in het verleden.",
+		errorRequired: "Vul dit veld in.",
+		errorTooLong: "Deze tekst is te lang.",
+		next: "Volgende",
+		privacy: "Privacybeleid",
+		required: "Verplicht veld",
+		sendFailed: "Het formulier kon niet worden verzonden. Probeer het opnieuw.",
+		sending: "Wordt verzonden …",
+		step: "Stap {current} van {total}",
+		submit: "Verzenden",
+		thanks: "Dank u! Wij hebben uw bericht ontvangen.",
+		tooManyRequests: "Te veel aanvragen. Probeer het over een minuut opnieuw.",
+		years: "{count} jaar",
+	},
+};
+
+const FALLBACK_LOCALE = "en";
+
+/**
+ * The form's texts in one language. A text is looked up in the project's
+ * overrides for that language, then in the built-in one, then in English.
+ *
+ * @param {string} locale - Language of the form, e.g. `"de"`.
+ * @param {Record<string, Record<string, string>>} [overrides] - Texts the project words differently, per language, e.g. `{ de: { next: "Fortfahren" } }`. Keep the `{placeholders}` of the original.
+ * @returns {(key: string, params?: Record<string, string | number>) => string} Unknown keys come back as the key itself.
+ */
+const createFormTexts = (locale, overrides = {}) => {
+	const sources = [overrides[locale], TEXTS[locale], TEXTS[FALLBACK_LOCALE]];
+
+	return (key, params = {}) => {
+		const template = sources.find((texts) => texts?.[key] != null)?.[key] ?? key;
+
+		return template.replace(/\{(\w+)\}/g, (_, name) => String(params[name] ?? ""));
+	};
+};
+
+export { createFormTexts, TEXTS as FORM_TEXTS };

package/src/forms/formValues.js

@@ -0,0 +1,101 @@
+/**
+ * What a form's values look like in the browser and what of them is sent. The
+ * browser checks only type and `required` — the same patterns the CMS uses, so
+ * a value that passes here is not turned down for its format there. Whether a
+ * date has passed, an option exists or a text is too long stays with the CMS.
+ */
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PHONE_PATTERN = /^\+?[0-9 ()/.-]{3,40}$/;
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+const DEFAULT_ADULTS = 2;
+
+const isValidDate = (value) => {
+	if (typeof value !== "string" || !DATE_PATTERN.test(value)) return false;
+	const date = new Date(`${value}T00:00:00Z`);
+	return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
+};
+
+/** The fields of some layouts, top to bottom, without empty columns. */
+const fieldsOf = (layouts) =>
+	layouts.flatMap((layout) => layout.columns ?? []).filter(Boolean);
+
+const emptyValueOf = (field) => {
+	if (field.type === "checkbox") return field.options?.length ? [] : false;
+	if (field.type === "daterange") return { from: "", to: "" };
+	if (field.type === "persons") return { adults: DEFAULT_ADULTS, children: [] };
+	return "";
+};
+
+/** Every field's starting value: what the URL pre-filled, else an empty one of its type. */
+const initialValues = (form) =>
+	Object.fromEntries(
+		form.pages
+			.flatMap((page) => fieldsOf(page.layouts))
+			.map((field) => [field.name, field.value ?? emptyValueOf(field)]),
+	);
+
+const isEmpty = (field, value) => {
+	if (value == null || value === false || value === "") return true;
+	if (Array.isArray(value)) return value.length === 0;
+	if (field.type === "daterange") return !value.from && !value.to;
+	return typeof value === "string" && value.trim() === "";
+};
+
+const CHECKERS = {
+	email: (value) => EMAIL_PATTERN.test(value.trim()),
+	phone: (value) => PHONE_PATTERN.test(value.trim()),
+	date: isValidDate,
+	daterange: ({ from, to }) => isValidDate(from) && isValidDate(to) && to >= from,
+	persons: ({ adults, children }) =>
+		adults >= 1 && children.every((age) => Number.isInteger(age)),
+};
+
+/**
+ * The errors of some fields, as the CMS would name them.
+ *
+ * @param {object[]} fields
+ * @param {Record<string, unknown>} values - Keyed by field name.
+ * @returns {Record<string, "REQUIRED" | "INVALID">} Keyed by field name; empty when all is well.
+ */
+const validateValues = (fields, values) => {
+	const errors = {};
+
+	for (const field of fields) {
+		const value = values[field.name];
+
+		if (isEmpty(field, value)) {
+			if (field.required) errors[field.name] = "REQUIRED";
+			continue;
+		}
+
+		if (CHECKERS[field.type] && !CHECKERS[field.type](value)) {
+			errors[field.name] = "INVALID";
+		}
+	}
+
+	return errors;
+};
+
+/** The values to send: empty ones left out, as the CMS does not store them anyway. */
+const submissionValues = (fields, values) =>
+	Object.fromEntries(
+		fields
+			.filter((field) => !isEmpty(field, values[field.name]))
+			.map((field) => [field.name, values[field.name]]),
+	);
+
+/**
+ * A persons value with `count` children. Ages already chosen stay; a new child
+ * starts without one, so the guest has to pick it.
+ */
+const withChildCount = (value, count) => ({
+	...value,
+	children: Array.from(
+		{ length: count },
+		(_, index) => value.children[index] ?? null,
+	),
+});
+
+export { fieldsOf, initialValues, submissionValues, validateValues, withChildCount };

package/src/forms/spamChallenge.js

@@ -0,0 +1,61 @@
+import { solveChallenge } from "altcha-lib";
+import { deriveKey } from "altcha-lib/algorithms/web/pbkdf2";
+import { fetchFormChallenge } from "../client/fetchFormChallenge.js";
+
+/**
+ * The form's ALTCHA proof of work, solved in the background. WebCrypto derives
+ * the keys off the main thread and the solver yields regularly, so the page
+ * stays responsive without a worker a website would have to bundle.
+ */
+
+/** A challenge this close to its end is replaced before it is sent. */
+const EXPIRY_MARGIN_S = 30;
+const solve = async (uuid) => {
+	const challenge = await fetchFormChallenge({ uuid });
+	const solution = await solveChallenge({ challenge, deriveKey });
+
+	if (!solution) throw new Error("Challenge not solved");
+
+	return { challenge, solution };
+};
+
+/**
+ * @param {string} uuid - The form's UUID.
+ * @param {() => number} [now] - Milliseconds; for tests.
+ */
+const createSpamChallenge = (uuid, now = () => Date.now()) => {
+	let pending = null;
+
+	const isFresh = (payload) =>
+		payload.challenge.parameters.expiresAt - EXPIRY_MARGIN_S > now() / 1_000;
+
+	const restart = () => {
+		const attempt = solve(uuid);
+		pending = attempt;
+		// A failed attempt is retried at the next call instead of failing forever.
+		attempt.catch(() => {
+			if (pending === attempt) pending = null;
+		});
+		return attempt;
+	};
+
+	return {
+		/** Starts solving, once; later calls change nothing. */
+		start() {
+			if (!pending) restart();
+		},
+
+		/** A solved, unexpired payload, solving or replacing one as needed. */
+		async payload() {
+			const payload = await (pending ?? restart());
+			return isFresh(payload) ? payload : restart();
+		},
+
+		/** Throws the current one away, after the CMS refused it. */
+		renew() {
+			return restart();
+		},
+	};
+};
+
+export { createSpamChallenge };

package/src/index.js

@@ -10,11 +10,17 @@ export { fetchRatings } from "./client/fetchRatings.js";
 export { fetchAds } from "./client/fetchAds.js";
 
 export { recordAdEvent } from "./client/recordAdEvent.js";
+export { submitForm } from "./client/submitForm.js";
+export { fetchFormChallenge } from "./client/fetchFormChallenge.js";
 
 export { createAdRunner } from "./ads/createAdRunner.js";
 export { slotOf } from "./ads/slots.js";
 export { toAdPath } from "./ads/adPath.js";
 
+export { createFormController } from "./forms/createFormController.js";
+export { createFormTexts } from "./forms/formTexts.js";
+export { FORM_CONTROLS } from "./forms/formControls.js";
+
 export { default as AddBlockPlaceholder } from "./components/AddBlockPlaceholder.svelte";
 export { default as BlockWrapper } from "./components/BlockWrapper.svelte";
 export { default as EditableBlock } from "./components/EditableBlock.svelte";

package/src/routes/cmsProxy.js

@@ -2,14 +2,17 @@ import { createCmsProxyHandler } from "../cms/proxyToCms.js";
 
 export const prerender = false;
 
-/** The only write a browser has any business making through this proxy. */
-const AD_EVENT_PATH = /^api\/public\/ads\/[^/]+\/events$/;
+/** The only writes a browser has any business making through this proxy. */
+const WRITE_PATHS = [
+	/^api\/public\/ads\/[^/]+\/events$/,
+	/^api\/public\/forms\/[^/]+\/submissions$/,
+];
 
 export const GET = createCmsProxyHandler();
 
-// Ad events are reported from the browser, which can only reach the CMS through
-// this proxy. Narrowed to that one path on purpose: the forwarded token may hold
-// management scopes, and an open POST would hand them to every visitor.
+// Ad events and form entries come from the browser, which can only reach the CMS
+// through this proxy. Narrowed to those paths on purpose: the forwarded token may
+// hold management scopes, and an open POST would hand them to every visitor.
 export const POST = createCmsProxyHandler({
-	allow: (path) => AD_EVENT_PATH.test(path),
+	allow: (path) => WRITE_PATHS.some((pattern) => pattern.test(path)),
 });