@formancy/react 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { Fragment, createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Fragment, createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { cancelUploads, fieldUploads, formatPath, parsePath, thumbnailSize } from "@formancy/core";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
-import { formatPath, parsePath } from "@formancy/core";
-import { LAYOUT_LEAF_KINDS, acceptRemoteOptions, applyRichCommand, capRemoteOptions, datagridColumns, layoutChildren, narrowOptionsByLabel, parseRichText, resolveText } from "@formancy/spec";
+import { LAYOUT_LEAF_KINDS, acceptRemoteOptions, answerFromText, applyRichCommand, capRemoteOptions, datagridColumns, editMasked, formatMasked, isImageSource, layoutChildren, layoutNodeShows, maskIsNumeric, maskPlaceholder, narrowOptionsByLabel, parseRichText, resolveText } from "@formancy/spec";
 import { flushSync } from "react-dom";
 import { encode } from "uqr";
 //#region src/context.tsx
@@ -13,6 +13,7 @@ import { encode } from "uqr";
 */
 const FormancyContext = createContext(null);
 function FormancyProvider({ engine, children }) {
+	useEffect(() => () => cancelUploads(engine), [engine]);
 	return /* @__PURE__ */ jsx(FormancyContext.Provider, {
 		value: engine,
 		children
@@ -124,6 +125,7 @@ function focusControl(control) {
 	if (control === null) return;
 	control.dispatchEvent(new Event("formancy-reveal", { bubbles: true }));
 	control.focus();
+	if (document.activeElement !== control) control.querySelector("input, select, textarea, button")?.focus();
 }
 //#endregion
 //#region src/use-submit.ts
@@ -153,14 +155,16 @@ function useSubmit() {
 }
 //#endregion
 //#region src/layout.tsx
-function LayoutTree({ schema, nodes, locale, renderField, at = [] }) {
+function LayoutTree({ schema, nodes, locale, renderField, at = [], shows }) {
 	return /* @__PURE__ */ jsx(Fragment$1, { children: nodes.map((node, index) => {
+		if (shows !== void 0 && !layoutNodeShows(node, shows)) return null;
 		const view = /* @__PURE__ */ jsx(LayoutNodeView, {
 			schema,
 			node,
 			locale,
 			renderField,
-			at: [...at, index]
+			at: [...at, index],
+			shows
 		}, index);
 		if (node.span === void 0) return view;
 		return /* @__PURE__ */ jsx("div", {
@@ -171,7 +175,7 @@ function LayoutTree({ schema, nodes, locale, renderField, at = [] }) {
 		}, index);
 	}) });
 }
-function LayoutNodeView({ schema, node, locale, renderField, at }) {
+function LayoutNodeView({ schema, node, locale, renderField, at, shows }) {
 	const headingId = useId();
 	if (node.kind === "field") return renderField(node.path);
 	if (node.kind === "qrcode") return /* @__PURE__ */ jsx(CodeNode, {
@@ -186,7 +190,8 @@ function LayoutNodeView({ schema, node, locale, renderField, at }) {
 		nodes: layoutChildren(node),
 		locale,
 		renderField,
-		at
+		at,
+		shows
 	});
 	if (node.kind === "row") return /* @__PURE__ */ jsx("div", {
 		"data-formancy-part": "layout-row",
@@ -205,7 +210,8 @@ function LayoutNodeView({ schema, node, locale, renderField, at }) {
 		locale,
 		renderField,
 		at,
-		here
+		here,
+		shows
 	});
 	if (node.kind === "table") return /* @__PURE__ */ jsxs("div", {
 		"data-formancy-part": "layout-table",
@@ -259,15 +265,20 @@ function LayoutNodeView({ schema, node, locale, renderField, at }) {
 * at all — the reader is told the form has an error and sent nowhere. So the
 * strip handles an explicit reveal request before the control receives focus.
 */
-function Tabs({ schema, node, locale, renderField, at, here }) {
+function Tabs({ schema, node, locale, renderField, at, here, shows }) {
 	const base = useId();
-	const [open, setOpen] = useState(0);
+	const shown = node.children.flatMap((child, index) => shows === void 0 || layoutNodeShows(child, shows) ? [{
+		child,
+		index
+	}] : []);
+	const [chosen, setOpen] = useState(0);
+	const open = Math.min(chosen, shown.length - 1);
 	const strip = useRef(null);
 	const panels = useRef([]);
 	const tabs = useRef([]);
 	/** Set only by a key press, so focus is never taken from elsewhere. */
 	const moveFocus = useRef(false);
-	const names = node.children.map((child) => child.kind === "field" ? void 0 : resolveText(schema, child.label, locale));
+	const names = shown.map(({ child }) => child.kind === "field" ? void 0 : resolveText(schema, child.label, locale));
 	useEffect(() => {
 		if (!moveFocus.current) return;
 		moveFocus.current = false;
@@ -283,9 +294,9 @@ function Tabs({ schema, node, locale, renderField, at, here }) {
 		return () => {
 			for (const off of listeners) off?.();
 		};
-	}, [node.children.length]);
+	}, [shown.length]);
 	const onKeyDown = (event) => {
-		const last = node.children.length - 1;
+		const last = shown.length - 1;
 		const next = event.key === "ArrowRight" ? Math.min(open + 1, last) : event.key === "ArrowLeft" ? Math.max(open - 1, 0) : event.key === "Home" ? 0 : event.key === "End" ? last : void 0;
 		if (next === void 0) return;
 		event.preventDefault();
@@ -302,7 +313,7 @@ function Tabs({ schema, node, locale, renderField, at, here }) {
 			...stripName === void 0 ? {} : { "aria-label": stripName },
 			"data-formancy-part": "tablist",
 			onKeyDown,
-			children: node.children.map((child, index) => /* @__PURE__ */ jsx("button", {
+			children: shown.map(({ index: position }, index) => /* @__PURE__ */ jsx("button", {
 				ref: (element) => {
 					tabs.current[index] = element;
 				},
@@ -315,8 +326,8 @@ function Tabs({ schema, node, locale, renderField, at, here }) {
 				"data-formancy-part": "tab",
 				onClick: () => setOpen(index),
 				children: names[index] ?? `Tab ${String(index + 1)}`
-			}, index))
-		}), node.children.map((child, index) => /* @__PURE__ */ jsx("div", {
+			}, position))
+		}), shown.map(({ child, index: position }, index) => /* @__PURE__ */ jsx("div", {
 			ref: (element) => {
 				panels.current[index] = element;
 			},
@@ -330,9 +341,10 @@ function Tabs({ schema, node, locale, renderField, at, here }) {
 				nodes: LAYOUT_LEAF_KINDS.has(child.kind) ? [child] : layoutChildren(child),
 				locale,
 				renderField,
-				at: [...at, index]
+				at: [...at, position],
+				shows
 			})
-		}, index))]
+		}, position))]
 	});
 }
 /**
@@ -772,15 +784,35 @@ function optionDomId(field, value) {
 /**
 * Option labels resolved to strings, since a label may be a message reference.
 * Falling back to the stored value keeps an untranslated option selectable
-* rather than blank.
+* rather than blank. A picture from somewhere the format does not allow is left
+* out, by the same test the Angular binding makes (0126).
 */
 function useResolvedOptions(field) {
 	const engine = useFormEngine();
 	return (field.def.options ?? []).map((option) => ({
 		value: option.value,
-		label: engine.text(option.label) ?? option.value
+		label: engine.text(option.label) ?? option.value,
+		...option.image !== void 0 && isImageSource(option.image.src) ? { image: {
+			src: option.image.src,
+			alt: engine.text(option.image.alt) ?? ""
+		} } : {}
 	}));
 }
+/**
+* An option's picture, inside its label so that pressing it chooses the option and
+* its text alternative joins the option's name. Lazy, because a long list of
+* pictured options is a page of images the person may never scroll to.
+*/
+function OptionPicture({ option }) {
+	if (option.image === void 0) return null;
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("img", {
+		"data-formancy-part": "option-image",
+		src: option.image.src,
+		alt: option.image.alt,
+		loading: "lazy",
+		decoding: "async"
+	}), " "] });
+}
 //#endregion
 //#region src/fields/typeahead-field.tsx
 /**
@@ -1023,9 +1055,9 @@ function RadioGroupField({ path, label }) {
 						checked: field.value === option.value,
 						onChange: () => field.setValue(option.value),
 						onBlur: () => field.touch()
-					}), /* @__PURE__ */ jsx("label", {
+					}), /* @__PURE__ */ jsxs("label", {
 						htmlFor: optionId,
-						children: option.label
+						children: [/* @__PURE__ */ jsx(OptionPicture, { option }), option.label]
 					})]
 				}, option.value);
 			}),
@@ -1055,13 +1087,19 @@ function RadioGroupField({ path, label }) {
 *
 * Without an uploader the field is read-only and says so, rather than
 * pretending to accept a file it has nowhere to put.
+*
+* **Each file is its own upload** — waiting, sending with how far it has got,
+* cancellable, and refused with a reason and a way to try again. What happens to
+* each is `@formancy/core`'s upload queue, read by both renderers
+* ([0130](../../../../docs/decisions/0130-each-file-is-its-own-upload.md)); this
+* draws it.
 */
 function FileField({ path, label }) {
 	const field = useField(path);
 	const upload = useUploader();
+	const queue = useUploadQueue(path, upload);
+	const pending = useSyncExternalStore(queue.subscribe, queue.pending, queue.pending);
 	const files = Array.isArray(field.value) ? field.value : [];
-	const [busy, setBusy] = useState(false);
-	const [failure, setFailure] = useState(void 0);
 	const [over, setOver] = useState(false);
 	/**
 	* Attachments taken out of the answer but not yet forgotten.
@@ -1073,21 +1111,9 @@ function FileField({ path, label }) {
 	const [removed, setRemoved] = useState([]);
 	const accept = field.def.accept;
 	const multiple = field.def.maxItems === void 0 || field.def.maxItems > 1;
-	const onPick = async (picked) => {
+	const onPick = (picked) => {
 		if (picked === null || picked.length === 0 || upload === void 0) return;
-		setBusy(true);
-		setFailure(void 0);
-		const uploaded = [];
-		const refused = [];
-		for (const file of Array.from(picked)) try {
-			uploaded.push(await upload(file));
-		} catch (error) {
-			refused.push(`${file.name} (${error instanceof Error ? error.message : String(error)})`);
-		}
-		if (uploaded.length > 0) field.setValue([...files, ...uploaded]);
-		if (refused.length > 0) setFailure(refused.length === 1 ? `${refused[0]} was not attached.` : `${String(refused.length)} files were not attached: ${refused.join(", ")}.`);
-		setBusy(false);
-		field.touch();
+		queue.add(Array.from(picked));
 	};
 	return /* @__PURE__ */ jsxs(FieldShell, {
 		path,
@@ -1102,14 +1128,14 @@ function FileField({ path, label }) {
 				...over ? { "data-state": "over" } : {},
 				onDragOver: (event) => {
 					event.preventDefault();
-					if (field.disabled || busy) return;
+					if (field.disabled) return;
 					setOver(true);
 				},
 				onDragLeave: () => setOver(false),
 				onDrop: (event) => {
 					event.preventDefault();
 					setOver(false);
-					if (field.disabled || busy) return;
+					if (field.disabled) return;
 					onPick(event.dataTransfer.files);
 				},
 				children: /* @__PURE__ */ jsx("input", {
@@ -1117,53 +1143,210 @@ function FileField({ path, label }) {
 					type: "file",
 					multiple,
 					...accept === void 0 ? {} : { accept: accept.join(",") },
-					disabled: field.disabled || busy,
+					disabled: field.disabled,
 					onChange: (event) => {
 						onPick(event.target.files);
 						event.target.value = "";
 					}
 				})
 			}),
-			files.length === 0 && removed.length === 0 ? null : /* @__PURE__ */ jsxs("ul", {
+			files.length === 0 && pending.length === 0 && removed.length === 0 ? null : /* @__PURE__ */ jsxs("ul", {
 				"data-formancy-part": "file-list",
-				children: [files.map((file) => /* @__PURE__ */ jsxs("li", {
-					"data-formancy-part": "file-item",
-					children: [/* @__PURE__ */ jsx("span", { children: file.name }), /* @__PURE__ */ jsxs("button", {
-						type: "button",
-						disabled: field.disabled,
-						onClick: () => {
-							setRemoved((before) => [...before, {
-								at: files.findIndex((other) => other.id === file.id),
-								file
-							}]);
-							field.setValue(files.filter((other) => other.id !== file.id));
-						},
-						children: ["Remove ", file.name]
-					})]
-				}, file.id)), removed.map(({ at, file }) => /* @__PURE__ */ jsxs("li", {
-					"data-formancy-part": "file-item",
-					"data-state": "removed",
-					children: [/* @__PURE__ */ jsx("span", { children: file.name }), /* @__PURE__ */ jsxs("button", {
-						type: "button",
-						disabled: field.disabled,
-						onClick: () => {
-							setRemoved((before) => before.filter((other) => other.file.id !== file.id));
-							const next = [...files];
-							next.splice(Math.min(at, next.length), 0, file);
-							field.setValue(next);
-						},
-						children: ["Undo removing ", file.name]
-					})]
-				}, file.id))]
+				children: [
+					files.map((file, index) => /* @__PURE__ */ jsxs("li", {
+						"data-formancy-part": "file-item",
+						children: [
+							/* @__PURE__ */ jsx(FileThumbnail, { source: queue.sourceOf(file.id) }),
+							/* @__PURE__ */ jsx("span", {
+								"data-formancy-part": "file-name",
+								children: file.name
+							}),
+							index > 0 ? /* @__PURE__ */ jsx("button", {
+								type: "button",
+								"data-formancy-part": "file-up",
+								disabled: field.disabled,
+								onClick: () => field.setValue(moved(files, index, index - 1)),
+								children: `Move ${file.name}, ${String(index + 1)} of ${String(files.length)}, up`
+							}) : null,
+							index < files.length - 1 ? /* @__PURE__ */ jsx("button", {
+								type: "button",
+								"data-formancy-part": "file-down",
+								disabled: field.disabled,
+								onClick: () => field.setValue(moved(files, index, index + 1)),
+								children: `Move ${file.name}, ${String(index + 1)} of ${String(files.length)}, down`
+							}) : null,
+							/* @__PURE__ */ jsxs("button", {
+								type: "button",
+								disabled: field.disabled,
+								onClick: () => {
+									setRemoved((before) => [...before, {
+										at: index,
+										file
+									}]);
+									field.setValue(files.filter((other) => other.id !== file.id));
+								},
+								children: ["Remove ", file.name]
+							})
+						]
+					}, file.id)),
+					pending.map((entry) => /* @__PURE__ */ jsx(PendingRow, {
+						entry,
+						queue,
+						disabled: field.disabled
+					}, entry.key)),
+					removed.map(({ at, file }) => /* @__PURE__ */ jsxs("li", {
+						"data-formancy-part": "file-item",
+						"data-state": "removed",
+						children: [/* @__PURE__ */ jsx("span", {
+							"data-formancy-part": "file-name",
+							children: file.name
+						}), /* @__PURE__ */ jsxs("button", {
+							type: "button",
+							disabled: field.disabled,
+							onClick: () => {
+								setRemoved((before) => before.filter((other) => other.file.id !== file.id));
+								const next = [...files];
+								next.splice(Math.min(at, next.length), 0, file);
+								field.setValue(next);
+							},
+							children: ["Undo removing ", file.name]
+						})]
+					}, file.id))
+				]
 			}),
 			/* @__PURE__ */ jsx("p", {
 				role: "status",
 				"data-formancy-part": "file-status",
-				children: busy ? "Uploading…" : failure ?? ""
+				children: statusOf(pending)
 			})
 		]
 	});
 }
+/** The files with one moved a place. */
+function moved(files, from, to) {
+	const next = [...files];
+	next.splice(to, 0, ...next.splice(from, 1));
+	return next;
+}
+/** A file not yet in the answer: waiting, being sent, or refused. */
+function PendingRow({ entry, queue, disabled }) {
+	const failed = entry.state === "failed";
+	return /* @__PURE__ */ jsxs("li", {
+		"data-formancy-part": "file-item",
+		"data-state": entry.state,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"data-formancy-part": "file-name",
+				children: entry.name
+			}),
+			entry.state === "waiting" ? /* @__PURE__ */ jsx("span", {
+				"data-formancy-part": "file-waiting",
+				children: "Waiting"
+			}) : null,
+			entry.state === "uploading" ? /* @__PURE__ */ jsx("progress", {
+				"data-formancy-part": "file-progress",
+				"aria-label": `Uploading ${entry.name}`,
+				...entry.total === void 0 ? {} : {
+					value: entry.sent,
+					max: entry.total
+				}
+			}) : null,
+			failed ? /* @__PURE__ */ jsxs("span", {
+				"data-formancy-part": "file-error",
+				children: ["Not attached: ", entry.reason]
+			}) : null,
+			failed ? /* @__PURE__ */ jsxs("button", {
+				type: "button",
+				disabled,
+				onClick: () => queue.retry(entry.key),
+				children: [
+					"Try ",
+					entry.name,
+					" again"
+				]
+			}) : null,
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				disabled,
+				onClick: () => queue.cancel(entry.key),
+				children: failed ? `Dismiss ${entry.name}` : `Cancel uploading ${entry.name}`
+			})
+		]
+	});
+}
+/** What the status region says: the file being sent, or the files refused, by name. */
+function statusOf(pending) {
+	const sending = pending.find((entry) => entry.state === "uploading");
+	if (sending !== void 0) return `Uploading ${sending.name}…`;
+	const failed = pending.filter((entry) => entry.state === "failed");
+	if (failed.length === 1) return `${failed[0].name} was not attached: ${failed[0].reason ?? ""}`;
+	if (failed.length > 1) return `${String(failed.length)} files were not attached: ${failed.map((entry) => entry.name).join(", ")}.`;
+	return "";
+}
+/**
+* The field's upload queue — the form's, found by the row this control is drawn for,
+* so a row that moves and remounts its controls keeps its uploads (0130).
+*
+* This control supplies only the sending: the host's uploader, given an
+* `AbortSignal` for the queue's cancel, which `@formancy/core` has no type for.
+*/
+function useUploadQueue(wire, upload) {
+	const engine = useFormEngine();
+	const uploads = fieldUploads(engine, wire);
+	useEffect(() => {
+		uploads.sender = upload === void 0 ? void 0 : (file, attempt, field) => {
+			const controller = new AbortController();
+			attempt.onCancel(() => controller.abort());
+			return upload(file, {
+				field,
+				signal: controller.signal,
+				onProgress: (sent, total) => attempt.progress(sent, total)
+			});
+		};
+	}, [uploads, upload]);
+	return uploads.queue;
+}
+/**
+* A picture of an image picked in this session, drawn from its bytes.
+*
+* **On a canvas, not an `<img>` on an object URL.** A URL is subject to the page's
+* `img-src`, and a strict policy without `blob:` shows a broken image — while this
+* product says a form runs under a strict CSP with no configuration. Decoding with
+* `createImageBitmap` and drawing the bitmap involves no URL at all.
+*
+* Only for a file picked here: a file stored before this page has no bytes in the
+* browser, and the renderer knows no address to fetch them from. Decorative — the
+* name beside it is what is read out.
+*/
+function FileThumbnail({ source }) {
+	const canvas = useRef(null);
+	const drawable = source !== void 0 && source.type.startsWith("image/") && typeof createImageBitmap === "function";
+	useEffect(() => {
+		if (!drawable) return;
+		let current = true;
+		createImageBitmap(source).then((bitmap) => {
+			const target = canvas.current;
+			if (current && target !== null) {
+				const { width, height } = thumbnailSize(bitmap.width, bitmap.height);
+				target.width = width;
+				target.height = height;
+				target.getContext("2d")?.drawImage(bitmap, 0, 0, target.width, target.height);
+			}
+			bitmap.close();
+		}, () => void 0);
+		return () => {
+			current = false;
+		};
+	}, [source, drawable]);
+	if (!drawable) return null;
+	return /* @__PURE__ */ jsx("canvas", {
+		ref: canvas,
+		"data-formancy-part": "file-thumbnail",
+		"aria-hidden": "true",
+		width: 0,
+		height: 0
+	});
+}
 //#endregion
 //#region src/fields/rich-text-field.tsx
 /**
@@ -1583,9 +1766,9 @@ function SelectBoxesField({ path, label }) {
 						disabled: field.disabled,
 						onChange: (event) => toggle(option.value, event.target.checked),
 						onBlur: () => field.touch()
-					}), /* @__PURE__ */ jsx("label", {
+					}), /* @__PURE__ */ jsxs("label", {
 						htmlFor: optionId,
-						children: option.label
+						children: [/* @__PURE__ */ jsx(OptionPicture, { option }), option.label]
 					})]
 				}, option.value);
 			}),
@@ -1598,6 +1781,361 @@ function SelectBoxesField({ path, label }) {
 	});
 }
 //#endregion
+//#region src/fields/ranking-field.tsx
+/**
+* Options put in order ([0138](../../../../docs/decisions/0138-a-ranking-stores-the-order-chosen.md)).
+*
+* **Buttons, and no dragging.** A drag must have an equivalent that is not one (WCAG 2.2
+* SC 2.5.7), and once the buttons exist they are the control: a drag surface is a second
+* route a theme or a consumer may add over the same commands, not the first one.
+*
+* Two lists. The order so far, each option with buttons to move it up, move it down and
+* take it out; and the options not ranked yet, each a button that puts it at the end.
+* Every button is named after the option it acts on — "Move Tea up" — because a column of
+* identical "Up" buttons is a column a screen reader cannot tell apart.
+*
+* **It starts with nothing ranked.** The options' written order is the author's, and an
+* answer that began as it would submit the author's preference as the respondent's.
+*
+* **Focus follows the option.** After "Move Tea up" focus is on Tea's up button in its new
+* place, so moving something three places is three presses of one key; after ranking one,
+* focus moves to the next option still to rank, so ranking them all is a run of Enter.
+*/
+function RankingField({ path, label }) {
+	const field = useField(path);
+	const options = useResolvedOptions(field);
+	const showError = field.touched && field.errors.length > 0;
+	const order = Array.isArray(field.value) ? field.value.map(String) : [];
+	const ranked = order.flatMap((value) => options.filter((option) => option.value === value));
+	const unranked = options.filter((option) => !order.includes(option.value));
+	const buttonId = (action, value) => `${field.ids.control}:${action}:${value}`;
+	const focusAfter = useRef(null);
+	useLayoutEffect(() => {
+		const id = focusAfter.current;
+		if (id === null) return;
+		focusAfter.current = null;
+		document.getElementById(id)?.focus();
+	});
+	const reorder = (next, focus) => {
+		focusAfter.current = focus;
+		field.setValue(next);
+	};
+	const move = (value, by) => {
+		const from = order.indexOf(value);
+		const to = from + by;
+		if (from === -1 || to < 0 || to >= order.length) return;
+		const next = [...order];
+		next[from] = next[to];
+		next[to] = value;
+		reorder(next, buttonId(by === -1 ? "up" : "down", value));
+	};
+	const rank = (value) => {
+		const position = unranked.findIndex((option) => option.value === value);
+		const following = unranked[position + 1] ?? unranked[position - 1];
+		reorder([...order, value], following === void 0 ? buttonId("up", value) : buttonId("rank", following.value));
+	};
+	return /* @__PURE__ */ jsxs("fieldset", {
+		id: field.ids.control,
+		"data-formancy-part": "field",
+		"data-formancy-field-path": path,
+		"data-state": showError ? "invalid" : "valid",
+		"aria-describedby": field.controlProps["aria-describedby"],
+		disabled: field.disabled,
+		children: [
+			/* @__PURE__ */ jsx("legend", {
+				"data-formancy-part": "label",
+				children: label
+			}),
+			/* @__PURE__ */ jsx(RequiredHint, { field }),
+			ranked.length === 0 ? null : /* @__PURE__ */ jsx("ol", {
+				"data-formancy-part": "ranking-order",
+				"aria-label": `${label}: your order`,
+				children: ranked.map((option, index) => /* @__PURE__ */ jsxs("li", {
+					"data-formancy-part": "ranking-item",
+					children: [
+						/* @__PURE__ */ jsx("span", {
+							"data-formancy-part": "ranking-label",
+							children: option.label
+						}),
+						/* @__PURE__ */ jsx("button", {
+							type: "button",
+							id: buttonId("up", option.value),
+							"data-formancy-part": "ranking-up",
+							"aria-label": `Move ${option.label} up`,
+							"aria-disabled": index === 0 ? true : void 0,
+							onClick: () => move(option.value, -1),
+							onBlur: () => field.touch(),
+							children: "↑"
+						}),
+						/* @__PURE__ */ jsx("button", {
+							type: "button",
+							id: buttonId("down", option.value),
+							"data-formancy-part": "ranking-down",
+							"aria-label": `Move ${option.label} down`,
+							"aria-disabled": index === ranked.length - 1 ? true : void 0,
+							onClick: () => move(option.value, 1),
+							onBlur: () => field.touch(),
+							children: "↓"
+						}),
+						/* @__PURE__ */ jsx("button", {
+							type: "button",
+							id: buttonId("remove", option.value),
+							"data-formancy-part": "ranking-remove",
+							"aria-label": `Take ${option.label} out of the order`,
+							onClick: () => reorder(order.filter((value) => value !== option.value), buttonId("rank", option.value)),
+							onBlur: () => field.touch(),
+							children: "×"
+						})
+					]
+				}, option.value))
+			}),
+			unranked.length === 0 ? null : /* @__PURE__ */ jsx("ul", {
+				"data-formancy-part": "ranking-pool",
+				"aria-label": `${label}: not ranked yet`,
+				children: unranked.map((option) => /* @__PURE__ */ jsx("li", {
+					"data-formancy-part": "ranking-candidate",
+					children: /* @__PURE__ */ jsx("button", {
+						type: "button",
+						id: buttonId("rank", option.value),
+						"data-formancy-part": "ranking-add",
+						"aria-label": `Rank ${option.label}`,
+						onClick: () => rank(option.value),
+						onBlur: () => field.touch(),
+						children: option.label
+					})
+				}, option.value))
+			}),
+			showError ? /* @__PURE__ */ jsx("p", {
+				"data-formancy-part": "error",
+				...field.errorProps,
+				children: field.errors.join(", ")
+			}) : null
+		]
+	});
+}
+//#endregion
+//#region src/fields/matrix-field.tsx
+/**
+* One question asked of several rows ([0139](../../../../docs/decisions/0139-a-matrix-answers-one-question-per-row.md)).
+*
+* **A group per row.** The matrix is a fieldset named by its label; each row is a fieldset
+* named by its row, holding a radio per column named by its column. That is a radio group
+* per row, which is exactly what each row is: arrow keys move within it, Tab moves to the
+* next, and every answer is reached by role and name. Not a `<table>` — its rows and
+* columns would be announced as data, and each radio would need a name made of two headers.
+* Looking like a grid is the theme's business, through the parts below.
+*
+* Each row's radios share a name of their own, so choosing in one row never clears another.
+*/
+function MatrixField({ path, label }) {
+	const field = useField(path);
+	const engine = useFormEngine();
+	const columns = useResolvedOptions(field);
+	const rows = (field.def?.rows ?? []).map((row) => ({
+		value: row.value,
+		label: engine.text(row.label) ?? row.value
+	}));
+	const showError = field.touched && field.errors.length > 0;
+	const answer = typeof field.value === "object" && field.value !== null && !Array.isArray(field.value) ? field.value : {};
+	const choose = (row, column) => {
+		field.setValue({
+			...answer,
+			[row]: column
+		});
+	};
+	return /* @__PURE__ */ jsxs("fieldset", {
+		id: field.ids.control,
+		"data-formancy-part": "field",
+		"data-formancy-field-path": path,
+		"data-state": showError ? "invalid" : "valid",
+		"aria-describedby": field.controlProps["aria-describedby"],
+		disabled: field.disabled,
+		children: [
+			/* @__PURE__ */ jsx("legend", {
+				"data-formancy-part": "label",
+				children: label
+			}),
+			/* @__PURE__ */ jsx(RequiredHint, { field }),
+			/* @__PURE__ */ jsx("div", {
+				"data-formancy-part": "matrix",
+				"data-columns": String(columns.length),
+				children: rows.map((row) => /* @__PURE__ */ jsxs("fieldset", {
+					"data-formancy-part": "matrix-row",
+					children: [/* @__PURE__ */ jsx("legend", {
+						"data-formancy-part": "matrix-row-label",
+						children: row.label
+					}), columns.map((column) => {
+						const id = `${field.ids.control}:${row.value}:${column.value}`;
+						return /* @__PURE__ */ jsxs("span", {
+							"data-formancy-part": "matrix-option",
+							children: [/* @__PURE__ */ jsx("input", {
+								type: "radio",
+								id,
+								name: `${field.controlProps.name}.${row.value}`,
+								value: column.value,
+								checked: answer[row.value] === column.value,
+								onChange: () => choose(row.value, column.value),
+								onBlur: () => field.touch()
+							}), /* @__PURE__ */ jsx("label", {
+								htmlFor: id,
+								children: column.label
+							})]
+						}, column.value);
+					})]
+				}, row.value))
+			}),
+			showError ? /* @__PURE__ */ jsx("p", {
+				"data-formancy-part": "error",
+				...field.errorProps,
+				children: field.errors.join(", ")
+			}) : null
+		]
+	});
+}
+//#endregion
+//#region src/fields/scale-fields.tsx
+/**
+* A rating and a slider: one number, two controls.
+*
+* Both are widgets on `number` and neither changes the answer
+* ([0104](../../../docs/decisions/0104-spec-4-opens-with-a-widget-not-a-type.md)),
+* so what is interesting here is the two ways a scale control goes wrong.
+*
+* **The keyboard.** Stars drawn as a row of buttons are a row of tab stops that
+* a screen reader announces as unrelated controls, with no sense that they form
+* a scale or that one is chosen. A rating is a **radio group**: one tab stop,
+* arrow keys along the scale, and the chosen value announced as "3 of 11". That
+* is not a concession to accessibility — it is what the control is.
+*
+* **The bounds.** A scale needs both ends, and the format cannot require them:
+* `min` and `max` are optional on every number field, and making them
+* conditional on a widget would mean a document that stops validating when
+* somebody changes presentation. So a field with no bounds falls back to the
+* ordinary number input rather than drawing a scale of 1–5 or 0–100 that the
+* author never wrote. A control that invents its own range is worse than one
+* that is plain.
+*/
+/** Every value on the scale, inclusive of both ends. */
+function scaleOf(min, max, step) {
+	const out = [];
+	for (let value = min; value <= max + step / 2; value += step) out.push(Math.round(value / step) * step);
+	return out;
+}
+/** Both ends, or nothing: the condition for drawing a scale at all. */
+function boundsOf(def) {
+	if (def.min === void 0 || def.max === void 0 || def.max <= def.min) return void 0;
+	return {
+		min: def.min,
+		max: def.max,
+		step: def.step !== void 0 && def.step > 0 ? def.step : 1
+	};
+}
+/**
+* Which control a `number` field gets.
+*
+* The same shape `selectboxes` uses for its tag picker: one switch per type, so
+* the registry keeps one entry and a widget cannot be registered independently
+* of the type it belongs to ([0065](../../../docs/decisions/0065-a-widget-is-authored-not-registered.md)).
+*/
+function NumberSwitch(props) {
+	const field = useField(props.path);
+	if (field.def?.widget === "rating") return /* @__PURE__ */ jsx(RatingField, { ...props });
+	if (field.def?.widget === "slider") return /* @__PURE__ */ jsx(SliderField, { ...props });
+	return /* @__PURE__ */ jsx(NumberFallback, { ...props });
+}
+function RatingField({ path, label }) {
+	const field = useField(path);
+	const bounds = boundsOf(field.def ?? {});
+	if (bounds === void 0) return /* @__PURE__ */ jsx(NumberFallback, {
+		path,
+		label
+	});
+	const { controlProps } = field;
+	const chosen = typeof field.value === "number" ? field.value : void 0;
+	return /* @__PURE__ */ jsx(FieldShell, {
+		path,
+		field,
+		label,
+		children: /* @__PURE__ */ jsx("div", {
+			...controlProps,
+			role: "radiogroup",
+			"aria-labelledby": field.ids.label,
+			"data-formancy-part": "rating",
+			children: scaleOf(bounds.min, bounds.max, bounds.step).map((value) => /* @__PURE__ */ jsxs("label", {
+				"data-formancy-part": "rating-step",
+				"data-chosen": value === chosen ? "true" : void 0,
+				children: [/* @__PURE__ */ jsx("input", {
+					type: "radio",
+					name: controlProps.id,
+					value,
+					checked: value === chosen,
+					onChange: () => field.setValue(value),
+					onBlur: () => field.touch()
+				}), /* @__PURE__ */ jsx("span", {
+					"data-formancy-part": "rating-label",
+					children: value
+				})]
+			}, value))
+		})
+	});
+}
+function SliderField({ path, label }) {
+	const field = useField(path);
+	const bounds = boundsOf(field.def ?? {});
+	if (bounds === void 0) return /* @__PURE__ */ jsx(NumberFallback, {
+		path,
+		label
+	});
+	const midpoint = bounds.min + (bounds.max - bounds.min) / 2;
+	const shown = typeof field.value === "number" ? field.value : midpoint;
+	return /* @__PURE__ */ jsx(FieldShell, {
+		path,
+		field,
+		label,
+		children: /* @__PURE__ */ jsxs("div", {
+			"data-formancy-part": "slider",
+			children: [/* @__PURE__ */ jsx("input", {
+				type: "range",
+				...field.controlProps,
+				min: bounds.min,
+				max: bounds.max,
+				step: bounds.step,
+				value: shown,
+				onChange: (event) => field.setValue(event.target.valueAsNumber),
+				onBlur: () => field.touch()
+			}), /* @__PURE__ */ jsx("span", {
+				"data-formancy-part": "slider-value",
+				"aria-hidden": "true",
+				children: shown
+			})]
+		})
+	});
+}
+/**
+* The ordinary number input, for a field whose bounds a scale cannot be drawn
+* from.
+*
+* A copy of `NumberField` rather than an import, and deliberately: importing it
+* would make `text-fields.tsx` and this file a cycle, and the duplication is six
+* lines of the most stable markup in the package. The thing that must not
+* diverge is what the field *stores*, and that is the engine's.
+*/
+function NumberFallback({ path, label }) {
+	const field = useField(path);
+	return /* @__PURE__ */ jsx(FieldShell, {
+		path,
+		field,
+		label,
+		children: /* @__PURE__ */ jsx("input", {
+			type: "number",
+			...field.controlProps,
+			value: typeof field.value === "number" ? field.value : "",
+			onChange: (event) => field.setValue(event.target.value === "" ? null : event.target.valueAsNumber),
+			onBlur: () => field.touch()
+		})
+	});
+}
+//#endregion
 //#region src/fields/signature-field.tsx
 /**
 * The signature control: a mark drawn, or a name typed.
@@ -1663,6 +2201,20 @@ function SignatureField({ path, label }) {
 	const commit = (strokes) => {
 		field.setValue(strokes.length === 0 ? null : { drawn: strokes });
 	};
+	const preventsScroll = { touchAction: "none" };
+	useEffect(() => {
+		const element = surface.current;
+		if (element === null) return;
+		const swallow = (event) => {
+			if (event.cancelable) event.preventDefault();
+		};
+		element.addEventListener("touchstart", swallow, { passive: false });
+		element.addEventListener("touchmove", swallow, { passive: false });
+		return () => {
+			element.removeEventListener("touchstart", swallow);
+			element.removeEventListener("touchmove", swallow);
+		};
+	}, []);
 	const onPointerDown = (event) => {
 		before.current = drawn;
 		stroke.current = [pointFrom(event)];
@@ -1689,6 +2241,7 @@ function SignatureField({ path, label }) {
 				/* @__PURE__ */ jsx("svg", {
 					ref: surface,
 					"data-formancy-part": "signature-surface",
+					style: preventsScroll,
 					viewBox: `0 0 ${String(width)} ${String(height)}`,
 					role: "img",
 					"aria-label": label,
@@ -1888,6 +2441,9 @@ function TextField({ path, label }) {
 	* it collects ([0065](../../../docs/decisions/0065-a-widget-is-authored-not-registered.md)).
 	*/
 	const commit = (text) => field.setValue(text.replace(/[\r\n]/g, ""));
+	const mask = field.def.mask;
+	const answer = typeof field.value === "string" ? field.value : "";
+	const shown = mask === void 0 ? answer : formatMasked(mask, answer);
 	const read = async () => {
 		if (scan === void 0 || scanning) return;
 		setScanning(true);
@@ -1902,7 +2458,7 @@ function TextField({ path, label }) {
 				setTrouble("Scanning did not work: the scanner did not return text. Type the value instead.");
 				return;
 			}
-			commit(text);
+			commit(mask === void 0 ? text : answerFromText(mask, text));
 			field.touch();
 		} catch (error) {
 			setTrouble(`Scanning did not work: ${error instanceof Error ? error.message : String(error)}. Type the value instead.`);
@@ -1917,8 +2473,24 @@ function TextField({ path, label }) {
 		children: [/* @__PURE__ */ jsx("input", {
 			type: "text",
 			...field.controlProps,
-			value: typeof field.value === "string" ? field.value : "",
-			onChange: (event) => commit(event.target.value),
+			value: shown,
+			placeholder: mask === void 0 ? void 0 : maskPlaceholder(mask),
+			inputMode: mask !== void 0 && maskIsNumeric(mask) ? "numeric" : void 0,
+			onChange: (event) => {
+				if (mask === void 0) {
+					commit(event.target.value);
+					return;
+				}
+				const input = event.target;
+				const forward = event.nativeEvent.inputType === "deleteContentForward";
+				const edit = editMasked(mask, answer, input.value, {
+					caret: input.selectionStart,
+					direction: forward ? "forward" : "backward"
+				});
+				input.value = formatMasked(mask, edit.answer);
+				input.setSelectionRange(edit.caret, edit.caret);
+				commit(edit.answer);
+			},
 			onBlur: () => field.touch()
 		}), field.def.widget === "scanner" && scan !== void 0 ? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs("button", {
 			type: "button",
@@ -1953,21 +2525,6 @@ function TextareaField({ path, label }) {
 		})
 	});
 }
-function NumberField({ path, label }) {
-	const field = useField(path);
-	return /* @__PURE__ */ jsx(FieldShell, {
-		path,
-		field,
-		label,
-		children: /* @__PURE__ */ jsx("input", {
-			type: "number",
-			...field.controlProps,
-			value: typeof field.value === "number" ? field.value : "",
-			onChange: (event) => field.setValue(event.target.value === "" ? null : event.target.valueAsNumber),
-			onBlur: () => field.touch()
-		})
-	});
-}
 //#endregion
 //#region src/form.tsx
 /**
@@ -2068,7 +2625,8 @@ function FieldList({ labels, registry, page, layout }) {
 		return /* @__PURE__ */ jsx(LayoutTree, {
 			schema,
 			nodes: arrangement.nodes,
-			locale: schema.i18n?.defaultLocale ?? "",
+			locale: engine.locale(),
+			shows: page === void 0 ? void 0 : (path) => engine.pageOf(parsePath(path)) === page,
 			renderField: (path) => {
 				if (repeaterWires.includes(path)) return /* @__PURE__ */ jsx(RepeaterSection, {
 					wire: path,
@@ -2254,7 +2812,7 @@ function RepeaterSection({ wire, labels, registry }) {
 const DEFAULT_COMPONENTS = {
 	text: TextField,
 	textarea: TextareaField,
-	number: NumberField,
+	number: NumberSwitch,
 	checkbox: CheckboxField,
 	date: DateField,
 	time: TimeField,
@@ -2262,6 +2820,8 @@ const DEFAULT_COMPONENTS = {
 	select: SelectField,
 	radio: RadioGroupField,
 	selectboxes: SelectBoxesSwitch,
+	ranking: RankingField,
+	matrix: MatrixField,
 	file: FileField,
 	richtext: RichTextField,
 	signature: SignatureField,
@@ -2294,7 +2854,7 @@ function ErrorSummary({ labels }) {
 		previousCount.current = errors.length;
 	}, [errors]);
 	if (errors.length === 0) return null;
-	const labelFor = (path) => labels?.[path] ?? labels?.[path.replace(/\[\d+\]/, "[]")] ?? path;
+	const labelFor = (path) => labels?.[path] ?? labels?.[path.replace(/\[\d+\]/, "[]")] ?? engine.getFieldSnapshot(parsePath(path)).label ?? path;
 	return /* @__PURE__ */ jsxs("div", {
 		"data-formancy-part": "error-summary",
 		tabIndex: -1,