@websline/cms-view-utils 1.10.2 → 1.15.0

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 };