@formancy/react 0.6.0 → 0.8.0

package/dist/index.mjs

@@ -1,22 +1,12 @@
 import { Fragment, createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { cancelUploads, fieldUploads, formatPath, parsePath, placedGroup, placedPage, thumbnailSize } from "@formancy/core";
-import { createFormText, optionsStatus } from "@formancy/core/words";
+import { cancelUploads, fieldUploads, formatPath, inOptionOrder, parsePath, placedGroup, placedPage, thumbnailSize, ticked } from "@formancy/core";
+import { answersToReview, countSentence, createFormText, errorSentence, optionsStatus } from "@formancy/core/words";
 import { LAYOUT_LEAF_KINDS, acceptRemoteAnswer, answerFromText, applyRichCommand, capRemoteAnswer, datagridColumns, editMasked, formatMasked, isImageSource, layoutChildren, layoutNodeShows, maskIsNumeric, maskPlaceholder, narrowOptionsByLabel, parseRichText, resolveText, resolvedLocale } from "@formancy/spec";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { flushSync } from "react-dom";
 import { encode } from "uqr";
 //#region src/context.tsx
-/**
-* The engine reaches components through context, never through props drilling:
-* a form is one engine instance, and every hook resolves against it. Kept in
-* its own module so tree-shaking can drop the provider for consumers that only
-* use prop getters.
-*/
 const FormancyContext = createContext(null);
-/**
-* The form's own words, in the language its questions are read in (0171). Beside the engine
-* rather than on it, because the engine has no buttons — the server runs the same one.
-*/
 const FormancyTextContext = createContext(null);
 function FormancyProvider({ engine, words, children }) {
 	useEffect(() => () => cancelUploads(engine), [engine]);
@@ -38,14 +28,6 @@ function useFormEngine() {
 	return engine;
 }
 let english;
-/**
-* The form's words, in the language the reader chose for it.
-*
-* English outside a `FormancyProvider`, which has no engine to take a language from — a
-* resume notice a host draws beside the form rather than inside its provider. Never the
-* browser's language: the form's is the one the reader chose, and the browser's is the
-* one their machine came with.
-*/
 function useFormText() {
 	const text = useContext(FormancyTextContext);
 	if (text !== null) return text;
@@ -54,16 +36,6 @@ function useFormText() {
 }
 //#endregion
 //#region src/use-field.ts
-/**
-* One field's live state, re-rendering exactly when that field's snapshot
-* changes and never for its siblings.
-*
-* useSyncExternalStore is the honest way to bind an external store in React:
-* the engine's snapshots are identity-stable, so getSnapshot needs no
-* memoisation and concurrent rendering gets a consistent tearing guard for
-* free. The third argument makes SSR render from the same snapshot the client
-* will hydrate with — ids are deterministic, so markup matches.
-*/
 function useField(path) {
 	const engine = useFormEngine();
 	const wire = typeof path === "string" ? path : formatPath(path);
@@ -91,11 +63,6 @@ function useField(path) {
 }
 //#endregion
 //#region src/use-repeater.ts
-/**
-* A repeater's live row list. Renders exactly when rows are added, removed or
-* edited — the engine treats the repeater path as subscribable in its own
-* right, so this hook needs no polling and no array identity tricks.
-*/
 function useRepeater(path) {
 	const engine = useFormEngine();
 	const wire = typeof path === "string" ? path : formatPath(path);
@@ -133,11 +100,6 @@ function useRepeater(path) {
 }
 //#endregion
 //#region src/use-wizard.ts
-/**
-* The wizard's live position. Throws on an unpaged form rather than degrading
-* to a one-page pseudo-wizard: a stepper rendered over a flat form is a bug in
-* the caller, and a loud error at mount beats a mute component.
-*/
 function useWizard() {
 	const wizard = useFormEngine().wizard();
 	if (wizard === void 0) throw new Error("useWizard needs a schema with pages; this form has none");
@@ -156,7 +118,6 @@ function useWizard() {
 }
 //#endregion
 //#region src/focus-control.ts
-/** Reveal enclosing tabs before focusing: hidden controls cannot emit focusin. */
 function focusControl(control) {
 	if (control === null) return;
 	control.dispatchEvent(new Event("formancy-reveal", { bubbles: true }));
@@ -165,14 +126,6 @@ function focusControl(control) {
 }
 //#endregion
 //#region src/use-submit.ts
-/**
-* Submit the form: touch everything, validate everything, and on failure move
-* focus to the first invalid control — the WCAG-required behaviour that every
-* consumer would otherwise have to hand-roll, and most would forget.
-*
-* Focus lives in the binding, not the engine, because it needs the DOM after
-* the commit; the engine only names the field (firstInvalid) and mints the id.
-*/
 function useSubmit() {
 	const engine = useFormEngine();
 	return useCallback(() => {
@@ -280,27 +233,6 @@ function LayoutNodeView({ schema, node, locale, renderField, at, shows }) {
 		}), children]
 	});
 }
-/**
-* One panel at a time, behind a row of tabs.
-*
-* The ARIA tabs pattern, and the reason it is written out rather than reached
-* for from a library: the keyboard behaviour is the specification. Arrows move
-* between tabs, Home and End reach the ends, and the tab strip is ONE tab stop
-* — a roving tabindex — so a form with twelve tabs does not cost twelve
-* presses to get past.
-*
-* **Every panel stays in the DOM.** A closed tab is hidden, not unmounted,
-* which is the decision the rest of this component follows from. Tabs are
-* presentation, unlike pages: a field in a closed tab is still validated and
-* still submitted, so it has to exist to be validated, and the browser's own
-* find-in-page finds it. Unmounting would also throw away what somebody had
-* typed the moment they looked at another tab.
-*
-* **A tab opens when an error is in it.** An error summary focuses the first
-* invalid control, and focusing something inside a hidden panel does nothing
-* 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, shows }) {
 	const base = useId();
 	const text = useFormText();
@@ -313,7 +245,6 @@ function Tabs({ schema, node, locale, renderField, at, here, shows }) {
 	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 = shown.map(({ child }) => child.kind === "field" ? void 0 : resolveText(schema, child.label, locale));
 	useEffect(() => {
@@ -384,19 +315,6 @@ function Tabs({ schema, node, locale, renderField, at, here, shows }) {
 		}, position))]
 	});
 }
-/**
-* A machine-readable code drawn from an answer the form already holds.
-*
-* **The accessible content is the value, not the picture.** The value is real text in
-* the document; a drawing, when a consumer registers one, is decorative — a screen
-* reader needs the value it encodes, which somebody can read, copy or dictate.
-*
-* **Out of the box a `qrcode` node shows the value as text and no code.** Encoding one
-* is roughly 10 kB and a SOUP row for every consumer, in a package budgeted at 4 kB, to
-* draw something a design system may want to draw its own way. A consumer who wants the
-* picture registers a component for it
-* ([0070](../../../docs/decisions/0070-a-code-is-an-arrangement-not-a-field.md)).
-*/
 function CodeNode({ schema, node, locale }) {
 	const label = resolveText(schema, node.label, locale);
 	const labelId = useId();
@@ -420,17 +338,6 @@ function CodeNode({ schema, node, locale }) {
 		]
 	});
 }
-/**
-* The modules of a QR code as one SVG.
-*
-* `viewBox` in module units with a one-module quiet zone — four is the specification's
-* recommendation and is drawn by the theme's padding instead, because a quiet zone baked
-* into the picture is whitespace a design system cannot remove.
-*
-* One `<rect>` per dark module rather than one path: a rect carries its own `fill`, so a
-* theme can address them, and the node count is bounded by the version (a version 1 code is
-* 23×23).
-*/
 function CodeDrawing({ value }) {
 	const { size, data } = encode(value);
 	const modules = [];
@@ -453,31 +360,120 @@ function CodeDrawing({ value }) {
 		children: modules
 	});
 }
-/** Every data path a layout places, in the order it places them. */
 function placedPaths(nodes, into = []) {
 	for (const node of nodes) if (node.kind === "field") into.push(node.path);
 	else placedPaths(layoutChildren(node), into);
 	return into;
 }
 //#endregion
+//#region src/review.tsx
+function SubmitButton({ submitLabel, onSubmit, onFailedNavigate }) {
+	const engine = useFormEngine();
+	const text = useFormText();
+	const submit = useSubmit();
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		"data-formancy-part": "submit",
+		onClick: () => {
+			const outcome = submit();
+			if (!outcome.ok && onFailedNavigate !== void 0) {
+				const firstInvalid = engine.firstInvalid();
+				if (firstInvalid !== null) onFailedNavigate(engine.pageOf(parsePath(firstInvalid)));
+			}
+			onSubmit?.(outcome.ok ? {
+				ok: true,
+				errors: outcome.errors,
+				data: engine.value()
+			} : {
+				ok: false,
+				errors: outcome.errors
+			});
+		},
+		children: submitLabel ?? text("form.submit")
+	});
+}
+function useReview(goTo) {
+	const engine = useFormEngine();
+	const submit = useSubmit();
+	const [reviewing, setReviewing] = useState(false);
+	const [focusing, setFocusing] = useState(void 0);
+	useEffect(() => {
+		if (focusing === void 0) return;
+		focusControl(document.getElementById(focusing));
+		setFocusing(void 0);
+	}, [focusing]);
+	return {
+		reviewing,
+		check() {
+			if (submit().ok) return setReviewing(true);
+			const firstInvalid = engine.firstInvalid();
+			if (firstInvalid !== null) goTo?.(engine.pageOf(parsePath(firstInvalid)));
+		},
+		change(answer) {
+			setReviewing(false);
+			goTo?.(answer.page);
+			setFocusing(answer.controlId);
+		}
+	};
+}
+function CheckAnswersButton({ onCheck }) {
+	const text = useFormText();
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		"data-formancy-part": "check-answers",
+		onClick: onCheck,
+		children: text("review.open")
+	});
+}
+function Review({ onChange, children }) {
+	const engine = useFormEngine();
+	const text = useFormText();
+	const headingId = useId();
+	const heading = useRef(null);
+	const answers = answersToReview(engine, text);
+	useEffect(() => heading.current?.focus(), []);
+	return /* @__PURE__ */ jsxs("section", {
+		"data-formancy-part": "review",
+		"aria-labelledby": headingId,
+		children: [
+			/* @__PURE__ */ jsx("h2", {
+				id: headingId,
+				ref: heading,
+				tabIndex: -1,
+				"data-formancy-part": "review-heading",
+				children: text("review.heading")
+			}),
+			answers.length === 0 ? /* @__PURE__ */ jsx("p", {
+				"data-formancy-part": "review-empty",
+				children: text("review.empty")
+			}) : /* @__PURE__ */ jsx("dl", {
+				"data-formancy-part": "review-answers",
+				children: answers.map((answer) => /* @__PURE__ */ jsxs("div", {
+					"data-formancy-part": "review-answer",
+					children: [
+						/* @__PURE__ */ jsx("dt", { children: answer.label }),
+						/* @__PURE__ */ jsx("dd", { children: answer.said }),
+						/* @__PURE__ */ jsx("dd", { children: /* @__PURE__ */ jsxs("button", {
+							type: "button",
+							onClick: () => onChange(answer),
+							children: [
+								text("review.change"),
+								" ",
+								/* @__PURE__ */ jsx("span", {
+									"data-formancy-part": "visually-hidden",
+									children: answer.label
+								})
+							]
+						}) })
+					]
+				}, answer.path))
+			}),
+			children
+		]
+	});
+}
+//#endregion
 //#region src/rich-text.tsx
-/**
-* Showing a `richtext` answer.
-*
-* Every element here is created by React from a typed tree. The stored answer
-* never reaches `dangerouslySetInnerHTML`, and there is no sanitiser, because
-* there is nothing to sanitise: the parser in `@formancy/spec` has already
-* turned the characters somebody typed into `{ kind: 'text' }` nodes, and a
-* text node cannot be an element however it is spelled.
-*
-* That is the whole reason the grammar exists rather than storing HTML. A form
-* answer is written by anyone who can reach the form and read later by an
-* administrator, which is the exact shape of a stored cross-site scripting
-* bug ([0052](../../../docs/decisions/0052-richtext-is-not-html.md)).
-*
-* The Angular renderer builds the same tree into the same elements, from the
-* same parser, so the two cannot disagree about what an answer says.
-*/
 function RichText({ source }) {
 	const blocks = parseRichText(source);
 	if (blocks.length === 0) return null;
@@ -510,14 +506,6 @@ function Inline({ node }) {
 //#region src/rich-text-editor.ts
 const RichTextEditorContext = createContext(void 0);
 const RichTextEditorProvider = RichTextEditorContext.Provider;
-/**
-* The host's editor factory, or undefined when there is none.
-*
-* Undefined is a supported state and the default one. Unlike the uploader — where
-* its absence makes a file field read-only, because there is nowhere to put the
-* bytes — its absence here costs nothing but the WYSIWYG surface: the answer is
-* still editable, still valid, and still the same grammar.
-*/
 function useRichTextEditorFactory() {
 	return useContext(RichTextEditorContext);
 }
@@ -525,13 +513,6 @@ function useRichTextEditorFactory() {
 //#region src/scanning.ts
 const ScannerContext = createContext(void 0);
 const ScannerProvider = ScannerContext.Provider;
-/**
-* The host's scanner, or undefined when there is none.
-*
-* Undefined is a supported state. A `scanner` widget with no scanner behind it renders
-* the ordinary text input and no button — typing was always the field's primary route,
-* so there is nothing to disable and a Scan button that opened nothing would be worse.
-*/
 function useScanner() {
 	return useContext(ScannerContext);
 }
@@ -539,14 +520,6 @@ function useScanner() {
 //#region src/options-source.ts
 const OptionsSourcesContext = createContext(void 0);
 const OptionsSourcesProvider = OptionsSourcesContext.Provider;
-/**
-* The host's sources, or undefined when there are none.
-*
-* Undefined is a supported state and not a misconfiguration — a form with no sourced
-* field never needs one. What it costs, when a document DOES name a source, is the
-* whole field: it renders a message where the chooser would be, exactly as the file
-* field does without an uploader.
-*/
 function useOptionsSources() {
 	return useContext(OptionsSourcesContext);
 }
@@ -555,10 +528,6 @@ function useOptionsSources() {
 const DEBOUNCE_MS = 250;
 const MIN_QUERY = 0;
 const MAX_ROWS = 50;
-/**
-* Nothing left out, as one value: a reset that stores it again is the same state, so
-* React bails out of the render rather than repeating one.
-*/
 const COMPLETE = { kind: "complete" };
 function useSourcedOptions(field, query, enabled = true) {
 	const engine = useFormEngine();
@@ -707,21 +676,22 @@ function useSourcedOptions(field, query, enabled = true) {
 //#region src/uploads.ts
 const UploaderContext = createContext(void 0);
 const UploaderProvider = UploaderContext.Provider;
-/**
-* The host's uploader, or undefined when there is none.
-*
-* Undefined is a supported state, not a misconfiguration: a form with no file
-* fields needs no uploader, and a file field without one renders read-only and
-* says why. The alternative — throwing — would turn a form that mostly works
-* into a blank page.
-*/
 function useUploader() {
 	return useContext(UploaderContext);
 }
 //#endregion
 //#region src/fields/internals.tsx
-/** Shared unstyled shell: real label, control, error text as the describedby
-*  target. Zero CSS; `data-formancy-part` is the styling hook. */
+function ErrorText({ field }) {
+	const text = useFormText();
+	return /* @__PURE__ */ jsx("p", {
+		"data-formancy-part": "error",
+		...field.errorProps,
+		children: field.errors.map((code, index) => /* @__PURE__ */ jsxs(Fragment, { children: [index > 0 ? " " : null, /* @__PURE__ */ jsx("span", {
+			"data-formancy-code": code,
+			children: errorSentence(text, field.def, code, field.messages)
+		})] }, code))
+	});
+}
 function FieldShell({ path, field, label, children }) {
 	return /* @__PURE__ */ jsxs("div", {
 		"data-formancy-part": "field",
@@ -733,56 +703,12 @@ function FieldShell({ path, field, label, children }) {
 				...field.labelProps,
 				children: label
 			}),
+			/* @__PURE__ */ jsx(Description, { field }),
 			children,
-			field.touched && field.errors.length > 0 ? /* @__PURE__ */ jsx("p", {
-				"data-formancy-part": "error",
-				...field.errorProps,
-				children: field.errors.join(", ")
-			}) : null
+			field.touched && field.errors.length > 0 ? /* @__PURE__ */ jsx(ErrorText, { field }) : null
 		]
 	});
 }
-/**
-* `widget: "typeahead"` - the same select, narrowed by typing.
-*
-* An ARIA 1.2 editable combobox over a listbox popup: a text box with
-* `role="combobox"` and a `<ul role="listbox">` of `<li role="option">`. DOM focus
-* never leaves the text box, so the arrowed-over option is named by
-* `aria-activedescendant` - which is the only thing that says where somebody is
-* when what they are moving through does not hold focus.
-*
-* **The list element exists while the popup is collapsed.** `aria-expanded` and
-* `aria-controls` are required properties of the role, and an `aria-controls`
-* pointing at an element that is not there is an unresolvable IDREF - so the
-* listbox is rendered and `hidden` rather than mounted when it opens.
-*
-* `aria-autocomplete="list"`, never `"both"`: nothing is ever written into the box
-* on the person's behalf, and `"both"` announces an inline completion that does
-* not exist. No `aria-haspopup`: `listbox` is the role's implicit popup, so the
-* attribute either repeats it or lies.
-*
-* `aria-selected` is on the CHOSEN option and on nothing else. Following the arrow
-* keys with it - the commonest defect in this pattern - tells a screen reader the
-* answer changed every time somebody pressed Down to read the next row.
-*
-* **It cannot store what somebody typed.** `setValue` is reached from exactly two
-* places here, with an option's own value or with `null`, and the text goes nowhere
-* but the filter. That is what makes
-* [0065](../../../docs/decisions/0065-a-widget-is-authored-not-registered.md)
-* structural rather than remembered: there is no path from this input to a stored
-* string a plain select could not have produced. So leaving the field with a query
-* that matches nothing stores nothing, and the box goes back to showing the answer.
-*
-* `null` is the other half of that: a select's empty first option means
-* un-answering is always available, and a widget may not take it away. Clearing the
-* box and leaving clears the answer.
-*/
-/**
-* What the status region is saying, as a word a theme can select on.
-*
-* Not the text: a theme that keyed off English prose would break in every other
-* language the form is offered in.
-*/
 function statusState({ sourced, said, open, matches }) {
 	if (sourced.remote === null) return open && matches === 0 ? "empty" : void 0;
 	if (sourced.remote.busy) return "busy";
@@ -790,17 +716,6 @@ function statusState({ sourced, said, open, matches }) {
 	if (said !== "") return "hint";
 	return open && matches === 0 ? "empty" : void 0;
 }
-/**
-* How a grouped field says it is required.
-*
-* A real element rather than an attribute, because the attribute that would
-* mean this — `aria-required` — is not supported on `role="group"`. The
-* engine puts this element's id into the group's `aria-describedby`, so it is
-* announced after the legend; rendering it is all a renderer has to do.
-*
-* Visible as well as announced: WCAG 1.4.1 means a requirement carried only by
-* a red asterisk is a requirement some people cannot perceive.
-*/
 function RequiredHint({ field }) {
 	const text = useFormText();
 	if (!field.required) return null;
@@ -810,33 +725,31 @@ function RequiredHint({ field }) {
 		children: text("form.required")
 	});
 }
-/** One option's element id, in the shape the radio group already uses, so a
-*  reader of the DOM meets one convention rather than two. */
+function Description({ field }) {
+	if (field.description === void 0) return null;
+	return /* @__PURE__ */ jsx("p", {
+		"data-formancy-part": "description",
+		id: field.props.description.id,
+		children: field.description
+	});
+}
+function usePlaceholder(field) {
+	return useFormEngine().text(field.def.placeholder);
+}
 function optionDomId(field, value) {
 	return `${field.ids.control}:option:${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. 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) => ({
+	return inOptionOrder((field.def.options ?? []).map((option) => ({
 		value: 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) ?? ""
 		} } : {}
-	}));
+	})), field.optionOrder);
 }
-/**
-* 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", {
@@ -849,30 +762,11 @@ function OptionPicture({ option }) {
 }
 //#endregion
 //#region src/fields/typeahead-field.tsx
-/**
-* A combobox over the same answer a select holds.
-*
-* One file per control, because a control changes for its own reasons.
-* These were one 2,154-line file — the largest in the repository.
-*/
 function TypeaheadSelectField({ path, label, field }) {
 	const text = useFormText();
-	/**
-	* What is in the box while somebody types, or null when the box is simply
-	* showing the answer.
-	*
-	* Two states rather than one string, because "empty because they cleared it"
-	* and "empty because there is no answer" are different facts, and only the
-	* first clears the answer on the way out.
-	*/
 	const [query, setQuery] = useState(null);
 	const [opened, setOpen] = useState(false);
-	/** A field disabled by a rule while its list was showing has no list: nobody can
-	*  choose from it, and its region would say "no options match" under a read-only
-	*  answer. */
 	const open = opened && !field.disabled;
-	/** The arrowed-over option by VALUE, not by index: the filtered list changes on
-	*  every keystroke and an index would point at a different row after one. */
 	const [activeValue, setActiveValue] = useState(null);
 	const sourced = useSourcedOptions({
 		...field,
@@ -891,8 +785,6 @@ function TypeaheadSelectField({ path, label, field }) {
 	});
 	const chosen = options.find((option) => option.value === field.value);
 	const matches = sourced.remote === null ? narrowOptionsByLabel(options, query ?? "") : options;
-	/** Collapsed whenever there is nothing on the screen, so `aria-expanded` never
-	*  claims a popup a person cannot see. */
 	const expanded = open && matches.length > 0;
 	const activeIndex = matches.findIndex((option) => option.value === activeValue);
 	const activeId = expanded && activeIndex !== -1 ? optionDomId(field, matches[activeIndex].value) : void 0;
@@ -1016,12 +908,6 @@ function TypeaheadSelectField({ path, label, field }) {
 }
 //#endregion
 //#region src/fields/choice-fields.tsx
-/**
-* One answer from a set: a tick, a list, or a group of radios.
-*
-* One file per control, because a control changes for its own reasons.
-* These were one 2,154-line file — the largest in the repository.
-*/
 function CheckboxField({ path, label }) {
 	const field = useField(path);
 	return /* @__PURE__ */ jsx(FieldShell, {
@@ -1077,6 +963,7 @@ function SelectField({ path, label }) {
 		label,
 		children: [/* @__PURE__ */ jsxs("select", {
 			...field.controlProps,
+			autoComplete: field.def.autocomplete,
 			value: typeof field.value === "string" ? field.value : "",
 			onChange: (event) => field.setValue(event.target.value === "" ? null : event.target.value),
 			onFocus: () => {
@@ -1099,6 +986,7 @@ function RadioGroupField({ path, label }) {
 	const options = useResolvedOptions(field);
 	const showError = field.touched && field.errors.length > 0;
 	return /* @__PURE__ */ jsxs("fieldset", {
+		id: field.ids.control,
 		"data-formancy-part": "field",
 		"data-formancy-field-path": path,
 		"data-state": showError ? "invalid" : "valid",
@@ -1109,6 +997,7 @@ function RadioGroupField({ path, label }) {
 				children: label
 			}),
 			/* @__PURE__ */ jsx(RequiredHint, { field }),
+			/* @__PURE__ */ jsx(Description, { field }),
 			options.map((option) => {
 				const optionId = `${field.ids.control}:${option.value}`;
 				return /* @__PURE__ */ jsxs("span", {
@@ -1127,39 +1016,12 @@ function RadioGroupField({ path, label }) {
 					})]
 				}, option.value);
 			}),
-			showError ? /* @__PURE__ */ jsx("p", {
-				"data-formancy-part": "error",
-				...field.errorProps,
-				children: field.errors.join(", ")
-			}) : null
+			showError ? /* @__PURE__ */ jsx(ErrorText, { field }) : null
 		]
 	});
 }
 //#endregion
 //#region src/fields/file-field.tsx
-/**
-* The file control, over an uploader the host supplies.
-*
-* One file per control, because a control changes for its own reasons.
-* These were one 2,154-line file — the largest in the repository.
-*/
-/**
-* Attached files.
-*
-* The control picks files; something else uploads them and reports back what
-* was stored. That split is the whole design: this package has no opinion
-* about where bytes go, which is what lets the same field work against local
-* disk, S3 or a customer's own service.
-*
-* 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 text = useFormText();
@@ -1168,13 +1030,6 @@ function FileField({ path, label }) {
 	const pending = useSyncExternalStore(queue.subscribe, queue.pending, queue.pending);
 	const files = Array.isArray(field.value) ? field.value : [];
 	const [over, setOver] = useState(false);
-	/**
-	* Attachments taken out of the answer but not yet forgotten.
-	*
-	* Held with the position they came from, so undoing puts a file BACK where it
-	* was rather than on the end — the order matters to somebody who numbered
-	* their attachments in a covering note.
-	*/
 	const [removed, setRemoved] = useState([]);
 	const accept = field.def.accept;
 	const multiple = field.def.maxItems === void 0 || field.def.maxItems > 1;
@@ -1298,13 +1153,11 @@ function FileField({ path, label }) {
 		]
 	});
 }
-/** 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, text }) {
 	const failed = entry.state === "failed";
 	return /* @__PURE__ */ jsxs("li", {
@@ -1346,7 +1199,6 @@ function PendingRow({ entry, queue, disabled, text }) {
 		]
 	});
 }
-/** What the status region says: the file being sent, or the files refused, by name. */
 function statusOf(pending, text) {
 	const sending = pending.find((entry) => entry.state === "uploading");
 	if (sending !== void 0) return text("file.status.uploading", { name: sending.name });
@@ -1364,13 +1216,6 @@ function statusOf(pending, text) {
 	}
 	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);
@@ -1387,18 +1232,6 @@ function useUploadQueue(wire, upload) {
 	}, [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";
@@ -1430,38 +1263,6 @@ function FileThumbnail({ source }) {
 }
 //#endregion
 //#region src/fields/rich-text-field.tsx
-/**
-* The rich text control, over a stored grammar rather than HTML.
-*
-* One file per control, because a control changes for its own reasons.
-* These were one 2,154-line file — the largest in the repository.
-*/
-/**
-* Formatted text, written as the restricted markup the spec defines.
-*
-* A textarea, not a contenteditable surface. That is a deliberate v1 cut and
-* not laziness: a WYSIWYG editor is a large accessibility surface of its own
-* — keyboard shortcuts, an announced selection model, focus management
-* inside a rich region — and shipping a half-built one is worse than
-* shipping a textarea that works with every assistive technology already.
-*
-* What the reader types is never treated as markup by anything. It is parsed
-* into a typed tree and rendered as elements, so there is no path from an
-* answer to `innerHTML` and no sanitiser to keep correct forever.
-*/
-/**
-* The rich text toolbar.
-*
-* A row of buttons over a textarea, not a contenteditable surface. That is the
-* deliberate choice — see `@formancy/spec`'s `richtext-edit` for why — and
-* it is what makes this editor cheap to make correct: the control is a plain
-* `<textarea>` that every assistive technology already knows, and the buttons
-* are ordinary buttons that do string arithmetic.
-*
-* The ARIA toolbar pattern, which means ONE tab stop for the whole row and
-* arrow keys within it. Five buttons that each take a tab press would put five
-* stops between a keyboard user and the box they came to type in.
-*/
 function RichTextToolbar({ disabled, label, onCommand }) {
 	const buttons = useRef([]);
 	const [active, setActive] = useState(0);
@@ -1540,17 +1341,6 @@ function RichTextToolbar({ disabled, label, onCommand }) {
 		}, entry.command))
 	});
 }
-/**
-* The host's editor, mounted over the same value the textarea would have edited.
-*
-* Mounted once and fed afterwards, rather than re-created when the value
-* changes: a contenteditable rebuilt on every keystroke loses the caret, the
-* selection and the undo stack, which is the difference between an editor and a
-* box that fights you.
-*
-* What crosses the boundary is the stored grammar in both directions, never
-* markup ([0061](../../../docs/decisions/0061-tiptap-over-the-closed-grammar.md)).
-*/
 function MountedRichText({ field, value, make, onReady }) {
 	const host = useRef(null);
 	const handle = useRef(void 0);
@@ -1601,15 +1391,6 @@ function RichTextField({ path, label }) {
 	const box = useRef(null);
 	const make = useRichTextEditorFactory();
 	const [editor, setEditor] = useState(void 0);
-	/**
-	* Run a toolbar command against the live selection and put the caret back.
-	*
-	* The selection is restored in an effect-free way {@link queueMicrotask}
-	* would not guarantee: React has to have written the new value first, so
-	* the box is updated on the next frame rather than immediately. An editor
-	* that drops the caret to the end after every button is one nobody can use
-	* for a second word.
-	*/
 	const run = (command, href) => {
 		const element = box.current;
 		if (element === null) return;
@@ -1674,51 +1455,9 @@ function RichTextField({ path, label }) {
 }
 //#endregion
 //#region src/fields/selectboxes-field.tsx
-/**
-* Many answers from a set, as checkboxes or as a tag picker.
-*
-* One file per control, because a control changes for its own reasons.
-* These were one 2,154-line file — the largest in the repository.
-*/
-/**
-* Several answers from a list, every option visible at once.
-*
-* A `fieldset` with a `legend`, exactly like the radio group, because the
-* relationship is the same one: several controls that answer a single
-* question. What differs is only that more than one may be chosen, which is
-* `type="checkbox"` and an array — not a different structure and not a
-* different way of being announced.
-*
-* Requiring "at least one" is a property of the QUESTION, not of any one box,
-* so it belongs to the group — but not as `aria-required`, which
-* `role="group"` does not support and assistive technology therefore ignores.
-* It is announced through the group's description instead, which the engine
-* composes. Putting it on every box would announce each one as required,
-* which is the opposite of what it means.
-*/
-/** A `selectboxes` is chips when the author asked for them, tick boxes otherwise. */
 function SelectBoxesSwitch(props) {
 	return useField(props.path).def?.widget === "tagpicker" ? /* @__PURE__ */ jsx(TagPickerField, { ...props }) : /* @__PURE__ */ jsx(SelectBoxesField, { ...props });
 }
-/**
-* `widget: "tagpicker"` — several answers, narrowed by typing, shown as chips.
-*
-* A widget rather than a field type because the answer does not change: an array
-* of offered option values in the options' own order, which is what a
-* `selectboxes` stores without it. What changes is that a list too long to tick
-* through becomes usable, and that the list may come from the deployment.
-*
-* **The chips are a list, and each carries its own remove button named after the
-* answer it removes.** "Remove" three times over tells a screen reader user which
-* nothing, and a chip a pointer can add and only a pointer can take away is
-* WCAG 2.1.1 — the failure this pattern ships with more often than any other.
-*
-* The combobox half is the typeahead's, deliberately: the same roles, the same
-* keys and the same `narrowOptionsByLabel` from `@formancy/spec`, so the two
-* cannot come to fold case differently. What differs is that choosing does not
-* fill the box — it adds a chip and clears it, because the next answer is the
-* common case.
-*/
 function TagPickerField({ path, label }) {
 	const field = useField(path);
 	const text = useFormText();
@@ -1731,8 +1470,7 @@ function TagPickerField({ path, label }) {
 	const matches = narrowOptionsByLabel(remaining, query);
 	const expanded = open && !field.disabled && matches.length > 0;
 	const add = (value) => {
-		const next = options.map((option) => option.value).filter((candidate) => candidate === value || chosen.includes(candidate));
-		field.setValue(next);
+		field.setValue(ticked(field.def, chosen, value, true));
 		setQuery("");
 		setOpen(false);
 	};
@@ -1818,10 +1556,10 @@ function SelectBoxesField({ path, label }) {
 	const showError = field.touched && field.errors.length > 0;
 	const chosen = Array.isArray(field.value) ? field.value : [];
 	const toggle = (value, on) => {
-		const next = options.map((option) => option.value).filter((candidate) => candidate === value ? on : chosen.includes(candidate));
-		field.setValue(next);
+		field.setValue(ticked(field.def, chosen, value, on));
 	};
 	return /* @__PURE__ */ jsxs("fieldset", {
+		id: field.ids.control,
 		"data-formancy-part": "field",
 		"data-formancy-field-path": path,
 		"data-state": showError ? "invalid" : "valid",
@@ -1832,6 +1570,7 @@ function SelectBoxesField({ path, label }) {
 				children: label
 			}),
 			/* @__PURE__ */ jsx(RequiredHint, { field }),
+			/* @__PURE__ */ jsx(Description, { field }),
 			options.map((option) => {
 				const optionId = `${field.ids.control}:${option.value}`;
 				return /* @__PURE__ */ jsxs("span", {
@@ -1851,35 +1590,12 @@ function SelectBoxesField({ path, label }) {
 					})]
 				}, option.value);
 			}),
-			showError ? /* @__PURE__ */ jsx("p", {
-				"data-formancy-part": "error",
-				...field.errorProps,
-				children: field.errors.join(", ")
-			}) : null
+			showError ? /* @__PURE__ */ jsx(ErrorText, { field }) : null
 		]
 	});
 }
 //#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 text = useFormText();
@@ -1927,6 +1643,7 @@ function RankingField({ path, label }) {
 				children: label
 			}),
 			/* @__PURE__ */ jsx(RequiredHint, { field }),
+			/* @__PURE__ */ jsx(Description, { field }),
 			ranked.length === 0 ? null : /* @__PURE__ */ jsx("ol", {
 				"data-formancy-part": "ranking-order",
 				"aria-label": text("ranking.order", { label }),
@@ -1985,28 +1702,12 @@ function RankingField({ path, label }) {
 					})
 				}, option.value))
 			}),
-			showError ? /* @__PURE__ */ jsx("p", {
-				"data-formancy-part": "error",
-				...field.errorProps,
-				children: field.errors.join(", ")
-			}) : null
+			showError ? /* @__PURE__ */ jsx(ErrorText, { field }) : 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();
@@ -2036,6 +1737,7 @@ function MatrixField({ path, label }) {
 				children: label
 			}),
 			/* @__PURE__ */ jsx(RequiredHint, { field }),
+			/* @__PURE__ */ jsx(Description, { field }),
 			/* @__PURE__ */ jsx("div", {
 				"data-formancy-part": "matrix",
 				"data-columns": String(columns.length),
@@ -2064,44 +1766,17 @@ function MatrixField({ path, label }) {
 					})]
 				}, row.value))
 			}),
-			showError ? /* @__PURE__ */ jsx("p", {
-				"data-formancy-part": "error",
-				...field.errorProps,
-				children: field.errors.join(", ")
-			}) : null
+			showError ? /* @__PURE__ */ jsx(ErrorText, { field }) : 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 {
@@ -2110,13 +1785,6 @@ function boundsOf(def) {
 		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 });
@@ -2191,17 +1859,9 @@ function SliderField({ path, label }) {
 		})
 	});
 }
-/**
-* 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);
+	const placeholder = usePlaceholder(field);
 	return /* @__PURE__ */ jsx(FieldShell, {
 		path,
 		field,
@@ -2209,6 +1869,8 @@ function NumberFallback({ path, label }) {
 		children: /* @__PURE__ */ jsx("input", {
 			type: "number",
 			...field.controlProps,
+			placeholder,
+			autoComplete: field.def.autocomplete,
 			readOnly: field.readOnly,
 			value: typeof field.value === "number" ? field.value : "",
 			onChange: (event) => field.setValue(event.target.value === "" ? null : event.target.valueAsNumber),
@@ -2218,33 +1880,6 @@ function NumberFallback({ path, label }) {
 }
 //#endregion
 //#region src/fields/signature-field.tsx
-/**
-* The signature control: a mark drawn, or a name typed.
-*
-* One file per control, because a control changes for its own reasons.
-* These were one 2,154-line file — the largest in the repository.
-*/
-/**
-* Sign here: draw a mark, or type your name.
-*
-* **Both routes are the feature, not a fallback and its apology.** Typing your
-* name is how most people sign most things, and it is the only route a keyboard
-* has — a field that offered drawing alone would be a WCAG 2.1.1 failure with a
-* legal signature attached to it. So the two sit side by side and the last one
-* used is the answer; they are never both present, because a reader choosing
-* between them is a signed document that renders differently depending on the
-* choice.
-*
-* **SVG, not canvas.** A canvas answer would be pixels, and this stores points
-* ([0083](../../../docs/decisions/0083-a-signature-is-points-or-a-name.md)):
-* points scale, diff, survive a re-render and mean something to a reader that is
-* not a browser. Drawing them as an SVG path costs nothing extra and makes the
-* mark visible to anything that can read the DOM, including a test.
-*
-* **No stroke timing.** Velocity is what makes a signature biometric, and
-* biometric data is a category (GDPR Article 9) nothing here is equipped to
-* hold.
-*/
 function SignatureField({ path, label }) {
 	const field = useField(path);
 	const text = useFormText();
@@ -2253,25 +1888,7 @@ function SignatureField({ path, label }) {
 	const [width, height] = field.def?.box ?? [600, 200];
 	const surface = useRef(null);
 	const stroke = useRef(null);
-	/**
-	* The strokes finished before this one started.
-	*
-	* Held rather than read back from the value, which is what the first version
-	* did — and the value already contains the stroke in progress, so every move
-	* appended another one. A signature drawn in the playground came out as forty
-	* strokes of a single point each; the unit tests moved once per stroke, which
-	* is the one shape that cannot show it.
-	*/
 	const before = useRef([]);
-	/**
-	* A client point in the field's own coordinate space, rounded to whole numbers.
-	*
-	* Whole numbers because the canonical hash a submission is bound to must not
-	* depend on how a browser rounded a pointer event. Clamped, because a pointer
-	* that leaves the box mid-stroke would otherwise record a point the engine
-	* refuses — the answer being invalid is the right outcome for a hand-written
-	* payload and the wrong one for somebody whose hand went past the edge.
-	*/
 	const pointFrom = (event) => {
 		const rect = surface.current?.getBoundingClientRect();
 		const scaleX = rect === void 0 || rect.width === 0 ? 1 : width / rect.width;
@@ -2338,6 +1955,7 @@ function SignatureField({ path, label }) {
 					}, at))
 				}),
 				/* @__PURE__ */ jsx("input", {
+					id: field.ids.control,
 					"data-formancy-part": "signature-typed",
 					type: "text",
 					value: answer.typed ?? "",
@@ -2364,21 +1982,6 @@ function SignatureField({ path, label }) {
 }
 //#endregion
 //#region src/fields/static-field.tsx
-/**
-* Text the reader sees that collects nothing.
-*
-* One file per control, because a control changes for its own reasons.
-* These were one 2,154-line file — the largest in the repository.
-*/
-/**
-* Text the reader sees that collects nothing — a heading, an explanation, a
-* notice.
-*
-* Not a `<label>`, because there is no control for one to label, and a label
-* pointing at nothing is a label a screen reader announces as an orphan. Not a
-* heading element either: the spec does not say what level it would be, and
-* guessing produces a document outline that skips levels.
-*/
 function StaticField({ path, label }) {
 	return /* @__PURE__ */ jsx("p", {
 		"data-formancy-part": "static",
@@ -2388,12 +1991,6 @@ function StaticField({ path, label }) {
 }
 //#endregion
 //#region src/fields/temporal-fields.tsx
-/**
-* The temporal controls, each holding one canonical fixed-width string.
-*
-* One file per control, because a control changes for its own reasons.
-* These were one 2,154-line file — the largest in the repository.
-*/
 function DateField({ path, label }) {
 	const field = useField(path);
 	return /* @__PURE__ */ jsx(FieldShell, {
@@ -2403,6 +2000,7 @@ function DateField({ path, label }) {
 		children: /* @__PURE__ */ jsx("input", {
 			type: "date",
 			...field.controlProps,
+			autoComplete: field.def.autocomplete,
 			readOnly: field.readOnly,
 			value: typeof field.value === "string" ? field.value : "",
 			onChange: (event) => field.setValue(event.target.value === "" ? null : event.target.value),
@@ -2410,19 +2008,6 @@ function DateField({ path, label }) {
 		})
 	});
 }
-/**
-* A time of day, as `HH:MM`.
-*
-* `<input type="time">` gives the platform's own picker, its own keyboard handling
-* and its own locale display — a 12-hour clock where the reader expects one — while
-* its `value` is always `HH:MM` on a 24-hour clock. That is exactly the split the
-* format wants: the reader sees their convention, the answer records one canonical
-* shape.
-*
-* `step` is not set, so the browser offers no seconds. A time answer has none, and a
-* control offering a precision the format discards is a control that loses what
-* somebody typed.
-*/
 function TimeField({ path, label }) {
 	const field = useField(path);
 	return /* @__PURE__ */ jsx(FieldShell, {
@@ -2441,27 +2026,6 @@ function TimeField({ path, label }) {
 		})
 	});
 }
-/**
-* An instant, stored as `YYYY-MM-DDTHH:MM:SSZ`.
-*
-* `<input type="datetime-local">` because there is no zoned datetime input in any
-* browser — so the control shows the reader a local wall clock and this converts.
-* The conversion is the whole reason this component exists rather than reusing
-* `DateField`:
-*
-* - **In:** the control gives `YYYY-MM-DDTHH:MM` in the reader's own zone. `new
-*   Date(local).toISOString()` interprets a zoneless string as local time, which is
-*   what is wanted here and is exactly what `bindTimestamp` refuses for a stored
-*   value — the difference is that the reader's zone is known at the moment they
-*   type, and is not knowable later.
-* - **Out:** the stored instant is rendered back into local time for the control,
-*   sliced to minutes because the input rejects a seconds component it was not asked
-*   for.
-*
-* Seconds are therefore always `00` in an answer a person typed. The format keeps
-* them because a machine-supplied answer has them and a fixed width is what makes
-* ordering work.
-*/
 function DateTimeField({ path, label }) {
 	const field = useField(path);
 	const stored = typeof field.value === "string" ? field.value : "";
@@ -2495,41 +2059,39 @@ function DateTimeField({ path, label }) {
 	});
 }
 //#endregion
+//#region src/fields/character-count.tsx
+const PAUSE_MS = 1e3;
+function CharacterCount({ field }) {
+	const text = useFormText();
+	const said = countSentence(text, field.def, field.value);
+	const [spoken, setSpoken] = useState("");
+	const first = useRef(said);
+	useEffect(() => {
+		if (said === void 0 || said === first.current) return;
+		first.current = void 0;
+		const timer = setTimeout(() => setSpoken(said), PAUSE_MS);
+		return () => clearTimeout(timer);
+	}, [said]);
+	if (said === void 0) return null;
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("p", {
+		id: field.props.count.id,
+		"data-formancy-part": "count",
+		children: said
+	}), /* @__PURE__ */ jsx("p", {
+		role: "status",
+		"data-formancy-part": "visually-hidden",
+		children: spoken
+	})] });
+}
+//#endregion
 //#region src/fields/text-fields.tsx
-/**
-* The controls that take typed text, and the widgets over them.
-*
-* One file per control, because a control changes for its own reasons.
-* These were one 2,154-line file — the largest in the repository.
-*/
-/**
-* A single-line answer, and — with `widget: "scanner"` — a camera route to the same
-* string.
-*
-* The input is the control in both cases, never a second one beside it: typing is
-* the accessibility floor and the fallback at once, so it is what is always there
-* and the scan button is what is sometimes added. With no scanner supplied the
-* markup is the default control exactly, because a Scan button that opens nothing is
-* worse than no button ([0071](../../../docs/decisions/0071-a-scanner-is-supplied-not-built.md)).
-*/
 function TextField({ path, label }) {
 	const field = useField(path);
+	const placeholder = usePlaceholder(field);
 	const scan = useScanner();
 	const words = useFormText();
 	const [scanning, setScanning] = useState(false);
-	/**
-	* A device failure, held here rather than in the field's errors. See below. What went
-	* wrong rather than a sentence about it, so the sentence is the form's language's.
-	*/
 	const [trouble, setTrouble] = useState(void 0);
-	/**
-	* The ONE place a text field's answer is written, typed or scanned.
-	*
-	* Structural rather than careful: the parameter is a `string`, so there is no path
-	* from the camera to `setValue` that could store something typing could not. That
-	* is the line a widget may never cross — it changes how a field looks, never what
-	* 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 : "";
@@ -2560,129 +2122,112 @@ function TextField({ path, label }) {
 		path,
 		field,
 		label,
-		children: [/* @__PURE__ */ jsx("input", {
-			type: "text",
-			...field.controlProps,
-			readOnly: field.readOnly,
-			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",
-			"data-formancy-part": "scanner-button",
-			disabled: field.disabled,
-			"aria-busy": scanning ? true : void 0,
-			onClick: () => {
-				read();
-			},
-			children: [
-				words("scanner.scan"),
-				" ",
-				/* @__PURE__ */ jsx("span", {
-					"data-formancy-part": "visually-hidden",
-					children: label
-				})
-			]
-		}), /* @__PURE__ */ jsx("p", {
-			role: "status",
-			"data-formancy-part": "scanner-status",
-			children: scanning ? words("scanner.scanning") : trouble === void 0 ? "" : trouble.reason === void 0 ? words("scanner.noText") : words("scanner.failed", { reason: trouble.reason })
-		})] }) : null]
+		children: [
+			/* @__PURE__ */ jsx("input", {
+				type: "text",
+				...field.controlProps,
+				autoComplete: field.def.autocomplete,
+				readOnly: field.readOnly,
+				value: shown,
+				placeholder: 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",
+				"data-formancy-part": "scanner-button",
+				disabled: field.disabled,
+				"aria-busy": scanning ? true : void 0,
+				onClick: () => {
+					read();
+				},
+				children: [
+					words("scanner.scan"),
+					" ",
+					/* @__PURE__ */ jsx("span", {
+						"data-formancy-part": "visually-hidden",
+						children: label
+					})
+				]
+			}), /* @__PURE__ */ jsx("p", {
+				role: "status",
+				"data-formancy-part": "scanner-status",
+				children: scanning ? words("scanner.scanning") : trouble === void 0 ? "" : trouble.reason === void 0 ? words("scanner.noText") : words("scanner.failed", { reason: trouble.reason })
+			})] }) : null,
+			/* @__PURE__ */ jsx(CharacterCount, { field })
+		]
 	});
 }
 function TextareaField({ path, label }) {
 	const field = useField(path);
-	return /* @__PURE__ */ jsx(FieldShell, {
+	const placeholder = usePlaceholder(field);
+	return /* @__PURE__ */ jsxs(FieldShell, {
 		path,
 		field,
 		label,
-		children: /* @__PURE__ */ jsx("textarea", {
+		children: [/* @__PURE__ */ jsx("textarea", {
 			...field.controlProps,
+			placeholder,
+			autoComplete: field.def.autocomplete,
 			readOnly: field.readOnly,
 			value: typeof field.value === "string" ? field.value : "",
 			onChange: (event) => field.setValue(event.target.value),
 			onBlur: () => field.touch()
-		})
+		}), /* @__PURE__ */ jsx(CharacterCount, { field })]
 	});
 }
 //#endregion
 //#region src/form.tsx
-/**
-* The form, the list that walks it, and which component renders which type.
-*
-* What is left after the controls moved into `fields/`: 2,154 lines that had
-* become the place things went. Three subjects remain here and they are one —
-* a form renders a list, a list renders a slot, a slot may render a repeater,
-* and a repeater renders a list. Mutual recursion is not a seam.
-*
-* `null` in the map is not an omission. `hidden` renders nothing by design, and
-* `group`, `page` and `repeater` are containers the list itself walks rather
-* than controls.
-*/
-/**
-* Renders the whole form from the engine: one slot per field, resolved through
-* the registry. Slots subscribe individually, so a keystroke re-renders one
-* field and a visibility flip mounts or unmounts exactly the fields it hit.
-* A paged schema renders a stepper, one page at a time, navigation, and the
-* submit control on the last page — a failed submit navigates to the first
-* page with a problem instead of leaving the user on a clean review page
-* staring at a rejection.
-*/
 function FormancyForm(props) {
 	return useFormEngine().wizard() === void 0 ? /* @__PURE__ */ jsx(FlatForm, { ...props }) : /* @__PURE__ */ jsx(PagedForm, { ...props });
 }
-function SubmitButton({ submitLabel, onSubmit, onFailedNavigate }) {
-	const engine = useFormEngine();
-	const text = useFormText();
-	const submit = useSubmit();
-	return /* @__PURE__ */ jsx("button", {
-		type: "button",
-		"data-formancy-part": "submit",
-		onClick: () => {
-			const outcome = submit();
-			if (!outcome.ok && onFailedNavigate !== void 0) {
-				const firstInvalid = engine.firstInvalid();
-				if (firstInvalid !== null) onFailedNavigate(engine.pageOf(parsePath(firstInvalid)));
-			}
-			onSubmit?.(outcome.ok ? {
-				ok: true,
-				errors: outcome.errors,
-				data: engine.value()
-			} : {
-				ok: false,
-				errors: outcome.errors
-			});
-		},
-		children: submitLabel ?? text("form.submit")
+function FlatForm(props) {
+	const review = useReview();
+	if (review.reviewing) return /* @__PURE__ */ jsx(Review, {
+		onChange: review.change,
+		children: /* @__PURE__ */ jsx(SubmitButton, { ...props })
 	});
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(FieldList, { ...props }), props.review === true ? /* @__PURE__ */ jsx(CheckAnswersButton, { onCheck: review.check }) : /* @__PURE__ */ jsx(SubmitButton, { ...props })] });
 }
-function FlatForm(props) {
-	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(FieldList, { ...props }), /* @__PURE__ */ jsx(SubmitButton, { ...props })] });
+function PageDescription({ page }) {
+	const engine = useFormEngine();
+	const description = engine.text(engine.pages()[page]?.def.description);
+	return description === void 0 ? null : /* @__PURE__ */ jsx("p", {
+		"data-formancy-part": "description",
+		children: description
+	});
 }
 function PagedForm(props) {
 	const engine = useFormEngine();
 	const text = useFormText();
 	const wizard = useWizard();
+	const review = useReview((page) => wizard.goTo(page));
 	const pages = engine.pages().map((page, index) => ({
 		...page,
 		index
 	})).filter((page) => !page.skipped);
+	if (review.reviewing) return /* @__PURE__ */ jsx(Review, {
+		onChange: review.change,
+		children: /* @__PURE__ */ jsx(SubmitButton, {
+			...props,
+			onFailedNavigate: (page) => wizard.goTo(page)
+		})
+	});
 	return /* @__PURE__ */ jsxs(Fragment$1, { children: [
 		/* @__PURE__ */ jsx("nav", {
 			"data-formancy-part": "stepper",
@@ -2692,6 +2237,7 @@ function PagedForm(props) {
 				children: engine.text(page.def.label) ?? page.key
 			}, page.key)) })
 		}),
+		/* @__PURE__ */ jsx(PageDescription, { page: wizard.page }),
 		/* @__PURE__ */ jsx(FieldList, {
 			...props,
 			page: wizard.page
@@ -2706,7 +2252,7 @@ function PagedForm(props) {
 				type: "button",
 				onClick: () => void wizard.next(),
 				children: text("form.next")
-			}) : /* @__PURE__ */ jsx(SubmitButton, {
+			}) : props.review === true ? /* @__PURE__ */ jsx(CheckAnswersButton, { onCheck: review.check }) : /* @__PURE__ */ jsx(SubmitButton, {
 				...props,
 				onFailedNavigate: (page) => wizard.goTo(page)
 			})]
@@ -2769,15 +2315,12 @@ function FieldSlot({ path, fallbackLabel, registry }) {
 		label
 	});
 }
-/**
-* A group an arrangement places whole: its fields, under its label, the way a labelled
-* section is drawn — a real group when it has a name, a box when it has none. What it holds
-* and in which order is `@formancy/core`'s, shared with the Angular renderer (0151).
-*/
 function GroupSection({ path, group, labels, registry }) {
 	const engine = useFormEngine();
 	const headingId = useId();
+	const descriptionId = useId();
 	const label = resolveText(engine.schema(), group.def.label, engine.locale());
+	const description = engine.text(group.def.description);
 	return /* @__PURE__ */ jsxs("div", {
 		"data-formancy-part": "group",
 		"data-formancy-field-path": path,
@@ -2785,12 +2328,18 @@ function GroupSection({ path, group, labels, registry }) {
 			role: "group",
 			"aria-labelledby": headingId
 		},
+		...description === void 0 ? {} : { "aria-describedby": descriptionId },
 		children: [
 			label === void 0 ? null : /* @__PURE__ */ jsx("p", {
 				id: headingId,
 				"data-formancy-part": "group-heading",
 				children: label
 			}),
+			description === void 0 ? null : /* @__PURE__ */ jsx("p", {
+				id: descriptionId,
+				"data-formancy-part": "description",
+				children: description
+			}),
 			group.fields.map((wire) => /* @__PURE__ */ jsx(FieldSlot, {
 				path: wire,
 				fallbackLabel: labels?.[wire],
@@ -2821,44 +2370,11 @@ function RepeaterSection({ wire, labels, registry }) {
 	const declaredColumns = def?.columns ?? [];
 	const plan = grid ? datagridColumns(def, declaredColumns) : [];
 	const tracks = declaredColumns.some((column) => column.width !== void 0) ? plan.map(({ column }) => column?.width === void 0 ? "1fr" : `${String(column.width)}fr`).join(" ") : void 0;
-	/** The control in one cell: the leaf the column's child field collects into.
-	*
-	*  One leaf, because a grid's rows are FLAT -- a child holding fields of its own is
-	*  refused when the document is saved
-	*  ([0078](../../../docs/decisions/0078-a-grid-row-is-flat.md)). This walked the whole
-	*  subtree under the child while a group could be a column, and every clause that made
-	*  that walk safe is gone with the arrangement it served.
-	*
-	*  Still a filter over the paths that EXIST rather than the path the column implies, so
-	*  a document nobody validated renders an empty cell instead of asking the engine about
-	*  a field it does not have. */
 	const leavesOf = (index, key) => {
 		const wanted = `${wire}[${String(index)}].${key}`;
 		return engine.fieldPaths().filter((leaf) => leaf === wanted);
 	};
-	/** A column's visible heading: the author's shortening, else the child's own label,
-	*  else the labels prop, else the key.
-	*
-	*  Visible text and NOTHING else -- never an `id` target, never an `aria-label`.
-	*  Measured against the accessible-name implementation this repository installs: a
-	*  column heading contributes nothing to the name of a control in its column, whether
-	*  it is a `<th scope="col">` or a `headers=` target. So the heading cannot replace a
-	*  cell's label, and pointing a control at it would only ADD the heading to the name --
-	*  which is the failure 0066 separates `header` from `label` to prevent. */
 	const headingOf = (entry) => engine.text(entry.column?.header) ?? engine.text(entry.child?.label) ?? fallbackFor(`${wire}[0].${entry.key}`) ?? entry.key;
-	/** A row's own controls, identical in both arrangements down to the names, because
-	*  0068 put the row's position in those names and a grid does not change where a person
-	*  is.
-	*
-	*  The text sits in its own element so a THEME can clip it and draw a mark instead,
-	*  which is what a grid wants -- "Remove recipient 1 of 1" on three wrapped lines took
-	*  more room than the answers beside it, measured in the playground. Clipped and never
-	*  removed: `display: none` and `visibility: hidden` both compute the button's name to
-	*  the empty string, and a button called nothing is worse than a wide one.
-	*
-	*  The renderer draws no mark of its own. An icon is appearance, appearance belongs to
-	*  the consumer ([0004](../../../docs/decisions/0004-headless-core.md)), and a renderer
-	*  that shipped a glyph would be choosing one for every design system at once. */
 	const rowButtons = (index) => /* @__PURE__ */ jsxs(Fragment$1, { children: [
 		repeater.canRemove ? /* @__PURE__ */ jsx("button", {
 			type: "button",
@@ -2903,16 +2419,6 @@ function RepeaterSection({ wire, labels, registry }) {
 			})
 		}) : null
 	] });
-	/** One control in a row.
-	*
-	*  Keyed by the POSITIONAL WIRE, so every control in a row is remounted when the row
-	*  moves and focus is lost on a reorder. Keying by the field's key within the row fixes
-	*  that here, and was reverted to keep the two renderers identical: the same change in
-	*  Angular lets it REUSE a component whose path is read once in ngOnInit, so after a
-	*  removal it binds to the old wire and shows the wrong row's answer -- caught by a
-	*  conformance fixture. One renderer keeping focus and the other not is the
-	*  framework-specific divergence this architecture exists to prevent, so both wait for
-	*  reactive path binding in Angular. */
 	const slot = (instanceWire) => /* @__PURE__ */ jsx(FieldSlot, {
 		path: instanceWire,
 		fallbackLabel: fallbackFor(instanceWire),
@@ -2946,6 +2452,7 @@ function RepeaterSection({ wire, labels, registry }) {
 				children: label
 			}),
 			/* @__PURE__ */ jsx(RequiredHint, { field }),
+			/* @__PURE__ */ jsx(Description, { field }),
 			grid ? /* @__PURE__ */ jsxs("div", {
 				"data-formancy-part": "datagrid",
 				"data-columns": String(plan.length),
@@ -2959,11 +2466,7 @@ function RepeaterSection({ wire, labels, registry }) {
 					}, entry.key))
 				}) : null, rows]
 			}) : rows,
-			showError ? /* @__PURE__ */ jsx("p", {
-				"data-formancy-part": "error",
-				...field.errorProps,
-				children: field.errors.join(", ")
-			}) : null,
+			showError ? /* @__PURE__ */ jsx(ErrorText, { field }) : null,
 			repeater.canAdd ? /* @__PURE__ */ jsx("button", {
 				type: "button",
 				disabled: field.disabled,
@@ -2973,12 +2476,6 @@ function RepeaterSection({ wire, labels, registry }) {
 		]
 	});
 }
-/**
-* The built-in unstyled components. `null` means the type renders nothing here:
-* a hidden field is carried in the submission and never shown, and the
-* container types are laid out by their own machinery rather than by a leaf
-* slot.
-*/
 const DEFAULT_COMPONENTS = {
 	text: TextField,
 	textarea: TextareaField,
@@ -3003,15 +2500,6 @@ const DEFAULT_COMPONENTS = {
 };
 //#endregion
 //#region src/error-summary.tsx
-/**
-* The error summary a failed submit focuses.
-*
-* The semantics are deliberate and easy to get wrong: the container takes
-* focus via tabindex="-1" — focusing it already makes screen readers announce
-* it, so role="alert" would announce it TWICE. Each entry is a real in-page
-* link to the offending control, because links are what "take me to the
-* problem" already means to assistive tech.
-*/
 function ErrorSummary({ labels }) {
 	const engine = useFormEngine();
 	const text = useFormText();
@@ -3020,6 +2508,12 @@ function ErrorSummary({ labels }) {
 	const errors = useSyncExternalStore(subscribe, getErrors, getErrors);
 	const region = useRef(null);
 	const previousCount = useRef(0);
+	const [focusing, setFocusing] = useState(void 0);
+	useEffect(() => {
+		if (focusing === void 0) return;
+		focusControl(document.getElementById(focusing));
+		setFocusing(void 0);
+	}, [focusing]);
 	useEffect(() => {
 		if (errors.length > 0 && previousCount.current === 0) region.current?.focus();
 		previousCount.current = errors.length;
@@ -3034,15 +2528,20 @@ function ErrorSummary({ labels }) {
 			"data-formancy-part": "error-summary-heading",
 			children: text("errors.heading", { count: errors.length })
 		}), /* @__PURE__ */ jsx("ul", { children: errors.map(({ path, codes }) => {
-			const controlId = engine.getFieldSnapshot(parsePath(path)).ids.control;
+			const snapshot = engine.getFieldSnapshot(parsePath(path));
+			const controlId = snapshot.ids.control;
 			return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx("a", {
 				href: `#${controlId}`,
 				onClick: (event) => {
 					event.preventDefault();
-					focusControl(document.getElementById(controlId));
+					const wizard = engine.wizard();
+					const page = engine.pageOf(parsePath(path));
+					if (wizard !== void 0 && wizard.page() !== page) wizard.goTo(page);
+					setFocusing(controlId);
 				},
 				children: text("errors.entry", {
 					label: labelFor(path),
+					problems: codes.map((code) => errorSentence(text, snapshot.def, code, snapshot.messages)).join(" "),
 					codes: codes.join(", ")
 				})
 			}) }, path);