@quillmark/svelte 0.12.0 → 0.13.0

package/dist/visual/DateField.svelte

@@ -23,16 +23,21 @@
  make every reconcile fire and re-render all seven segments on each commit.
 
  The ghost is the default's digits, not a format hint. An unset field
- carrying a `default:` prints the default's digits in the segments, ghost-toned,
- instead of the primitive's `mm`/`dd`/`yyyy` hints, which say "empty" where the
- rung says "will render 2026-01-01". The ghost is painted in the segment snippet,
- over an unset primitive: substituting the default for `value` instead would make
- the field indistinguishable from an authored one to every path that reads it
- (`areAllSegmentsFilled`, Backspace, the hidden input), and the primitive shadows
- a written-back `value` prop it was not `bind:`-ed to, so re-seating the ghost
- after a clear never lands. `placeholder` (the `DateValue` the segments count
- from, never one they display) carries the default too, so arrowing an empty
- segment starts at the render's date rather than today's.
+ carrying a `default:` prints the default's digits in the segments at the default
+ rung (theme.css), instead of the primitive's `mm`/`dd`/`yyyy` hints, which say
+ "empty" where the rung says "will render 2026-01-01". At rest the ghost is painted
+ in the segment snippet, over an unset primitive: a default held as its value reads
+ as filled to every path that reads the primitive (`areAllSegmentsFilled`,
+ Backspace, the hidden input), and whether it stands as the value is the field's to
+ say only once the user enters it. `placeholder`
+ (the `DateValue` the segments count from, never one they display) carries the
+ default too, so arrowing an empty segment starts at the render's date rather than
+ today's.
+
+ Entering an unset field seats the default as the primitive's value, still at the
+ default rung, so an edit to one segment commits a whole date with the others the
+ default's. Leaving without an edit unseats it, and nothing is written; so does
+ clearing a segment.
 -->
 <script lang="ts">
 	import { DateField as BitsDateField } from 'bits-ui';
@@ -85,25 +90,42 @@
 		}
 	}
 
+	const fallbackDate = $derived(toDateValue(fallback?.slice(0, 10) ?? ''));
+	/** The default is the primitive's value: from entering an unset field until an
+	 *  edit, a cleared segment or leaving. Part of the projection, so a reconcile
+	 *  neither drops a seat nor restores one over the segments a clear left. */
+	let seat = $state(false);
 	// Local value synced to `value` as a string (see the identity note above);
 	// own-edits stay local, only an external change reconciles back in. Driven
 	// controlled (`value` + `onValueChange`, never `bind:`) so reconciliation stays
 	// the package's.
-	const local = syncedLocal(() => value?.slice(0, 10) ?? '');
+	const local = syncedLocal(
+		() => value?.slice(0, 10) ?? (seat && fallbackDate ? fallbackDate.toString() : '')
+	);
 	const parsed = $derived(toDateValue(local.value));
 	// The date the empty segments ghost, or undefined when there is nothing to ghost:
 	// the field is unset and the default has a date form. A non-blank local that
 	// fails to parse is AUTHORED-but-malformed, which the empty field states
 	// honestly: the ghost would claim it unset. Held as the parsed value rather than
 	// a boolean so the substitution below narrows on the one fact it needs.
-	const fallbackDate = $derived(toDateValue(fallback?.slice(0, 10) ?? ''));
 	const ghost = $derived(local.value === '' ? fallbackDate : undefined);
+	const seated = $derived(value == null && seat && local.value !== '');
 
-	// What one segment prints, and whether that text is shown-never-written.
+	/** Focus moving between segments is neither an entry nor a leaving. */
+	const within = (e: FocusEvent): boolean => !!wrapEl?.contains(e.relatedTarget as Node | null);
+	function enter(e: FocusEvent): void {
+		if (!within(e) && value == null && fallbackDate) seat = true;
+	}
+	function leave(e: FocusEvent): void {
+		if (!within(e)) seat = false;
+	}
+
+	// What one segment prints, and which rung it takes.
 	//
 	// An unfilled segment is always shown-never-written, whether it prints the
-	// default's digits or the primitive's own `mm`/`dd`/`yyyy` hint: both state
-	// "nothing authored here". Only an unfilled segment ghosts: a half-entered date
+	// default's digits (`default`, the rung of what prints) or the primitive's own
+	// `mm`/`dd`/`yyyy` hint (`hint`, a word about the value): both state "nothing
+	// authored here". Only an unfilled segment ghosts: a half-entered date
 	// holds digits while the value is still undefined (one unfilled segment unsets
 	// the whole field), so ghosting unconditionally would paint over, and dim, the
 	// digits just typed. The segment's own text is the tell: its unfilled hint is
@@ -113,30 +135,36 @@
 	// The separators are `literal` parts, never unfilled; substitution covers the
 	// date parts only, so any time part keeps the primitive's text. Digits are
 	// zero-padded to the segment widths the field displays.
-	function segmentText(part: string, text: string): { text: string; ghosted: boolean } {
-		if (part === 'literal' || /\d/.test(text)) return { text, ghosted: false };
-		if (!ghost) return { text, ghosted: true };
+	type Rung = 'default' | 'hint' | undefined;
+	function segmentText(part: string, text: string): { text: string; ghosted: Rung } {
+		if (part === 'literal' || /\d/.test(text)) return { text, ghosted: undefined };
+		if (!ghost) return { text, ghosted: 'hint' };
 		switch (part) {
 			case 'year':
-				return { text: String(ghost.year).padStart(4, '0'), ghosted: true };
+				return { text: String(ghost.year).padStart(4, '0'), ghosted: 'default' };
 			case 'month':
-				return { text: String(ghost.month).padStart(2, '0'), ghosted: true };
+				return { text: String(ghost.month).padStart(2, '0'), ghosted: 'default' };
 			case 'day':
-				return { text: String(ghost.day).padStart(2, '0'), ghosted: true };
+				return { text: String(ghost.day).padStart(2, '0'), ghosted: 'default' };
 			default:
-				return { text, ghosted: true };
+				return { text, ghosted: 'hint' };
 		}
 	}
 </script>
 
-<span class="qm-date-wrap" bind:this={wrapEl}>
+<span class="qm-date-wrap" bind:this={wrapEl} onfocusin={enter} onfocusout={leave}>
 	<BitsDateField.Root
 		value={parsed}
 		placeholder={fallbackDate}
 		onValueChange={(d) => {
 			// `CalendarDate.toString()` is exactly `YYYY-MM-DD`. A cleared or
-			// half-typed field yields undefined: the unset rung.
-			local.value = d?.toString() ?? '';
+			// half-typed field yields undefined: the unset rung. The primitive reports
+			// its own value again as a segment loses focus, which is no edit, and over a
+			// seated default would write it.
+			const next = d?.toString() ?? '';
+			if (next === local.value) return;
+			local.value = next;
+			if (!d) seat = false;
 			onCommit(d?.toString());
 		}}
 	>
@@ -151,6 +179,7 @@
 			aria-labelledby={labelledBy}
 			aria-describedby={describedBy}
 			data-ghosted={ghost ? '' : undefined}
+			data-default={seated ? '' : undefined}
 		>
 			{#snippet children({ segments })}
 				<!-- Keyed by index: `part` repeats (the `literal` separators between
@@ -160,7 +189,7 @@
 					<BitsDateField.Segment
 						class="qm-date-segment"
 						part={seg.part}
-						data-ghosted={shown.ghosted ? '' : undefined}
+						data-ghosted={shown.ghosted}
 					>
 						{shown.text}
 					</BitsDateField.Segment>
@@ -193,11 +222,17 @@
 	.qm-date-wrap :global(.qm-date-segment:focus) {
 		background: var(--_qm-surface-hover);
 	}
-	/* An unfilled segment is ghost-toned whatever it prints: the resolved `default:`
-	 when there is one to ghost, the `dd`/`mm`/`yyyy` hint when there is not. Shown,
-	 never written, either way. The marker is the component's own (see the snippet):
-	 the date primitive emits no placeholder attribute of its own. */
-	.qm-date-wrap :global(.qm-date-segment[data-ghosted]) {
+	/* An unfilled segment is ghost-toned whatever it prints, at the rung of what it
+	 prints: the resolved `default:`'s digits at the default rung, the `dd`/`mm`/`yyyy`
+	 hint at the label rung. Shown, never written, either way. The marker is the
+	 component's own (see the snippet): the date primitive emits no placeholder
+	 attribute of its own. A seated default is the value and still unwritten, so its
+	 filled segments take the default rung too. */
+	.qm-date-wrap :global(.qm-date-segment[data-ghosted='hint']) {
 		color: var(--_qm-ink-label);
 	}
+	.qm-date-wrap :global(.qm-date-segment[data-ghosted='default']),
+	.qm-date-wrap :global(.qm-date[data-default] .qm-date-segment) {
+		color: var(--_qm-ink-default);
+	}
 </style>

package/dist/visual/EnumField.svelte

@@ -25,6 +25,11 @@
 		value: string | undefined;
 		values: string[];
 		fallback?: string;
+		/** The schema's `ui.blank_title`: what the blank draws as, in place of the em dash. */
+		blankTitle?: string;
+		/** An `enum?` cell, which prints `none` unset rather than its blank, and so ghosts
+		 *  `strings.optionalGhost` there. */
+		optional?: boolean;
 		/** Accessible name for a trigger nothing else names: an object property, whose
 		 * name is the field label plus the property's. A field's own trigger takes `id`
 		 * instead and is named by the `<label for>` beside it (the trigger is a
@@ -47,6 +52,8 @@
 		value,
 		values,
 		fallback,
+		blankTitle,
+		optional = false,
 		label,
 		id,
 		describedBy,
@@ -66,11 +73,15 @@
 	// the package's rather than the primitive's.
 	const local = syncedLocal(() => value ?? UNSET);
 
-	/** An empty enum member has no glyph of its own; an em dash stands in for it. */
-	const dash = (v: string | undefined) => v || '—';
+	/** The blank has no glyph of its own: the quill's `ui.blank_title` stands in for
+	 * it, else an em dash. */
+	const dash = (v: string | undefined) => v || blankTitle || '—';
 
 	const unset = $derived(local.value === UNSET);
-	const ghostText = $derived(dash(fallback));
+	/** The ghost is a member the render prints, rather than a word for the blank or for
+	 *  `none`: it draws at the default rung (theme.css). */
+	const ghostsMember = $derived(!optional && !!fallback);
+	const ghostText = $derived(optional ? t.strings.optionalGhost : dash(fallback));
 	/** What the closed trigger shows: the pick, or the ghosted default while unset. */
 	const shown = $derived(unset ? ghostText : dash(local.value));
 
@@ -102,7 +113,7 @@
 			{id}
 			aria-label={id ? undefined : label}
 			aria-describedby={describedBy}
-			data-ghosted={unset ? '' : undefined}
+			data-ghosted={unset ? (ghostsMember ? 'default' : '') : undefined}
 		>
 			<span class="qm-select-shown">{shown}</span>
 			<Icon name="chevron-down" class="qm-select-chevron" size={14} />
@@ -125,13 +136,17 @@
 						     and while the field is unset this is the selected row, so the weight
 						     step pulls the other way. It rides the accessible name for the same
 						     reason. -->
+						<!-- An optional cell's row is untagged: it ghosts no default, and `None`
+						     names no member to tell it from. -->
 						<Select.Item
 							class="qm-menu-item qm-select-item qm-select-unset"
 							value={UNSET}
-							label={`${ghostText} ${t.strings.enumUnsetTag}`}
+							label={optional ? ghostText : `${ghostText} ${t.strings.enumUnsetTag}`}
 						>
 							<span class="qm-select-ghost">{ghostText}</span>
-							<span class="qm-select-tag">{t.strings.enumUnsetTag}</span>
+							{#if !optional}
+								<span class="qm-select-tag">{t.strings.enumUnsetTag}</span>
+							{/if}
 						</Select.Item>
 						<!-- A refused option still draws under `'disable'`, and under either
 						     policy when it is the one selected: a listbox whose selected value
@@ -192,11 +207,14 @@
 		flex-shrink: 0;
 	}
 	/* The focus ring rides `.qm-focus-ring` on the trigger (controls.css). */
-	/* Shown-never-written: the closed control reads muted while unset, matching the
-	   ghosted placeholder the text/number controls show. */
+	/* Shown-never-written: the closed control reads muted while unset, at the rung of
+	   what it shows — the default member the render prints, or a word for the blank. */
 	.qm-select-wrap :global(.qm-select[data-ghosted]) {
 		color: var(--_qm-ink-label);
 	}
+	.qm-select-wrap :global(.qm-select[data-ghosted='default']) {
+		color: var(--_qm-ink-default);
+	}
 	/* The open list is `.qm-menu-surface` and its rows `.qm-menu-item` (controls.css):
 	 the lift, the inset and the highlight are the shared menu recipe. What a listbox
 	 adds over a menu is here: it spans its trigger rather than its own content, it
@@ -229,7 +247,7 @@
 	/* A step down the size ramp, which is what says this is chrome and the word beside
 	   it is the value. The ink is the ghost's own: a second tone here would rank the
 	   tag against the thing it annotates, and there is no rung under `label` to take
-	   (theme.css, "Two rungs, and there is no third"). */
+	   (theme.css, "nothing under the last"). */
 	.qm-select-tag {
 		flex-shrink: 0;
 		font-size: var(--_qm-text-label);

package/dist/visual/EnumField.svelte.d.ts

@@ -3,6 +3,11 @@ interface Props {
     value: string | undefined;
     values: string[];
     fallback?: string;
+    /** The schema's `ui.blank_title`: what the blank draws as, in place of the em dash. */
+    blankTitle?: string;
+    /** An `enum?` cell, which prints `none` unset rather than its blank, and so ghosts
+     *  `strings.optionalGhost` there. */
+    optional?: boolean;
     /** Accessible name for a trigger nothing else names: an object property, whose
      * name is the field label plus the property's. A field's own trigger takes `id`
      * instead and is named by the `<label for>` beside it (the trigger is a

package/dist/visual/Field.svelte

@@ -13,7 +13,8 @@
  `diagnostics` is the routed `Diagnostic[]` for this field (VisualEditor's
  `diagByKey`, merging `quill.validate`, local commit errors, and the external
  `diagnostics` prop (VISUAL_EDITOR §Diagnostics)) rendered via the shared
- `DiagnosticList`, non-gating.
+ `DiagnosticList`, non-gating; each set also re-evaluates a prose leaf's hold
+ (`ProseField`).
 -->
 <script lang="ts">
 	import type {
@@ -31,10 +32,16 @@
 	import {
 		VARIANT_DISCRIMINANT,
 		arrayLayout,
+		baseType,
+		exampleGhost,
 		ghostDefault,
 		isContainer,
-		stringifyGhost
+		optionalCell,
+		printedText,
+		stringifyGhost,
+		titleText
 	} from './structure.js';
+	import { wording } from './strings.js';
 	import { deepen } from './diagnostics.js';
 	import type { FieldDomIds } from './domid.js';
 	import ProseField from './ProseField.svelte';
@@ -104,12 +111,29 @@
 		diagnostics
 	}: Props = $props();
 
-	// The ghost the control shows when unset: the resolved `default:` (provenance,
+	const t = wording();
+
+	// What an unset field shows of its `default:`: the resolved value (provenance,
 	// `source === 'default'`). `ghost` is the raw typed value (enum/number/boolean
-	// fallbacks); `defaultStr` its string form: the text placeholder and the date
-	// control's `YYYY-MM-DD`. An object-valued default does not ghost.
+	// fallbacks, a content leaf's `Content`), `defaultStr` its string form (the date
+	// control's `YYYY-MM-DD`); an object-valued default has none. An array draws its
+	// declared literal instead, which is what a take writes (`ArrayField`).
+	// A default that prints stands in the control as the value it is, at the default
+	// rung, and the first edit takes it (VISUAL_EDITOR §"The commitment ladder"). Where
+	// nothing prints, a control draws words: the `none` an optional cell prints, and
+	// a free-text field's `example:`.
 	const ghost = $derived(ghostDefault(provenance));
-	const defaultStr = $derived(stringifyGhost(ghost));
+	const defaultStr = $derived(
+		field.control === 'prose' ? titleText(ghost) || undefined : stringifyGhost(ghost)
+	);
+	const printed = $derived(printedText(defaultStr));
+	// A text or number control reads its default off the schema, not the resolved row:
+	// the row stops naming a default once the field is written, and emptying a written
+	// field still has to know that the default prints.
+	const declared = $derived(printedText(field.schema.default));
+	const optional = $derived(optionalCell(field.schema));
+	const none = $derived(optional && value == null ? t.strings.optionalGhost : undefined);
+	const example = $derived(value == null ? exampleGhost(field.schema) : undefined);
 	// A variant resolves as one rung whose value is the whole container, so the
 	// discriminant's ghost is that container's own discriminant cell.
 	const ghostMember = $derived(
@@ -260,7 +284,10 @@
 					{addr}
 					inline={field.inline}
 					plaintext={field.plaintext}
-					placeholder={defaultStr}
+					fallback={printed ? (ghost as Content) : undefined}
+					placeholder={none}
+					placeholderUntilEdit
+					{example}
 					labelledBy={domIds.label}
 					{describedBy}
 					{leafKey}
@@ -269,12 +296,15 @@
 					{onChange}
 					{onError}
 					{leaves}
+					{diagnostics}
 				/>
 			{:else if field.control === 'enum'}
 				<EnumField
 					value={value as string | undefined}
 					values={field.schema.values ?? []}
 					fallback={ghost as string | undefined}
+					blankTitle={field.schema.ui?.blank_title}
+					{optional}
 					id={domIds.control}
 					{describedBy}
 					onCommit={onCommitScalar}
@@ -300,8 +330,9 @@
 			{:else if field.control === 'number'}
 				<NumberField
 					value={value as number | undefined}
-					integer={field.schema.type === 'integer'}
-					fallback={ghost as number | undefined}
+					integer={baseType(field.schema) === 'integer'}
+					fallback={declared}
+					placeholder={none}
 					id={domIds.control}
 					{describedBy}
 					onCommit={onCommitScalar}
@@ -310,6 +341,7 @@
 				<BooleanField
 					value={value as boolean | undefined}
 					fallback={ghost as boolean | undefined}
+					{optional}
 					id={domIds.control}
 					{describedBy}
 					onCommit={onCommitScalar}
@@ -327,6 +359,7 @@
 				<ArrayField
 					bind:this={arrayEl}
 					value={value as unknown[] | undefined}
+					fallback={Array.isArray(field.schema.default) ? field.schema.default : undefined}
 					items={field.schema.items}
 					layout={arrayLayout(field.schema)}
 					max={field.schema.max}
@@ -370,7 +403,9 @@
 			{:else}
 				<TextField
 					value={value as string | undefined}
-					placeholder={defaultStr}
+					fallback={declared}
+					placeholder={none}
+					{example}
 					id={domIds.control}
 					{describedBy}
 					onCommit={onCommitScalar}

package/dist/visual/FormatPopover.svelte

@@ -142,9 +142,10 @@
 		const selection = view?.state.selection;
 		const formattable = selection instanceof TextSelection && !selection.empty;
 		// …in a leaf that has formatting at all. A `plaintext` leaf declares no mark
-		// types (`plaintextSchema`), so this surface withholds itself over one entirely,
-		// the way it never rises over the text input a `string` field draws: the value is
-		// literal text, and a mark on it is a value the boundary refuses to coerce back.
+		// types (`plaintextSchema`, `plainSchema`), so this surface withholds itself over
+		// one entirely, the way it never rises over the text input a `string` field draws:
+		// the value is literal text, and a mark on it is a value the boundary refuses to
+		// coerce back.
 		if (
 			!view ||
 			!view.hasFocus() ||

package/dist/visual/MatrixField.svelte

@@ -17,8 +17,9 @@
  Commit is whole: the sparse map, one `writer.set`. A tick writes the member object
  with an explicit `held`, an untick keeps the columns under `held: false`, and a member
  unheld with no columns leaves the map (`memberWrite`). What is blank per column is the
- engine's rule and not restated: a column control that clears drops its key, so the
- editor drops a member it has emptied rather than deciding skippability for itself.
+ engine's rule and not restated: a column control that clears to unset drops its key,
+ so the editor drops a member it has emptied rather than deciding skippability for
+ itself; one whose default prints clears to the empty answer, which the member holds.
  The read takes both rest forms — a bare tick and `{held?, …columns}`, whose `held` rests
  at `false` where the mapping names none — and the write lands one, on the member edited
  alone; every other member rides through as the document spelled it.

package/dist/visual/NumberField.svelte

@@ -4,10 +4,13 @@
  (`-`, `1.`, `1e`) is never a document state worth a boundary round-trip, and
  committing it live flashes a coercion diagnostic + `console.error` on every
  intermediate prefix, announced by `DiagnosticList`'s `role="status"` live
- region. A blank entry commits `undefined`: the unset rung of the
- commitment ladder: the parent removes the field and the engine renders the
- ghosted `default:`. Settling at `change` also keeps
- select-all-and-retype from flashing the preview through the default mid-keystroke.
+ region.
+
+ An unset field holds its resolved `default:` as its text, at the default rung
+ (theme.css), and an edit that settles writes it as authored, as `TextField` takes
+ its default. A number has no empty answer (canon `SCHEMAS.md` §"Native validation"),
+ so a blank entry commits `undefined`, the unset rung: the parent removes the field,
+ the engine renders the default, and the input holds it again.
 
  `type="text"`, not `type="number"`: a native number input sanitizes an
  invalid string to `""` before the DOM `value` setter even runs (verified:
@@ -26,7 +29,11 @@
 	interface Props {
 		value: number | undefined;
 		integer?: boolean;
-		fallback?: number;
+		/** The resolved `default:` as text: what an unset field holds. */
+		fallback?: string;
+		/** Words at rest about an unset field that holds no text: the `None` an optional
+		 * cell prints. */
+		placeholder?: string;
 		/** Accessible name for an input nothing else names: an object property, whose
 		 * name is the field label plus the property's. A field's own input takes `id`
 		 * instead and is named by the `<label for>` beside it. */
@@ -38,16 +45,25 @@
 		describedBy?: string;
 		onCommit: (v: number | string | undefined) => void;
 	}
-	let { value, integer, fallback, label, id, describedBy, onCommit }: Props = $props();
+	let { value, integer, fallback, placeholder, label, id, describedBy, onCommit }: Props = $props();
 
-	// Local input state synced to `value` (as a string projection); own-typing
-	// stays local, only an external change reconciles back in (see `syncedLocal`).
-	const local = syncedLocal(() => (value != null ? String(value) : ''));
+	// Local input state synced to `value` (as a string projection), or to the default
+	// an unset field holds; own-typing stays local, only an external change reconciles
+	// back in (see `syncedLocal`).
+	const local = syncedLocal(() => (value != null ? String(value) : (fallback ?? '')));
+	const defaulted = $derived(value == null && !!fallback && local.value === fallback);
 
 	// Parse a settled entry and emit it; `local` is owned by `oninput`. Blank →
-	// `undefined` (the unset rung: parent removes the field, default renders).
-	function commit(raw: string): void {
-		if (raw.trim() === '') return void onCommit(undefined);
+	// `undefined`, and the input takes the default back: nothing else reconciles it, the
+	// projection having read the default throughout. Onto the element as well, since the
+	// attribute Svelte last wrote may already be the default, and it writes no repeat.
+	function commit(el: HTMLInputElement): void {
+		const raw = el.value;
+		if (raw.trim() === '') {
+			onCommit(undefined);
+			local.value = el.value = fallback ?? '';
+			return;
+		}
 		// Number(), not parseFloat/parseInt: a prefix parse would silently commit
 		// `14.5` for `14.5x` (and truncate `11.9` → 11 on integer fields) instead
 		// of letting the boundary judge the full entry.
@@ -62,11 +78,12 @@
 	inputmode={integer ? 'numeric' : 'decimal'}
 	value={local.value}
 	{id}
-	placeholder={fallback != null ? String(fallback) : ''}
+	{placeholder}
+	data-default={defaulted ? '' : undefined}
 	aria-label={id ? undefined : label}
 	aria-describedby={describedBy}
 	oninput={(e) => {
 		local.value = (e.currentTarget as HTMLInputElement).value;
 	}}
-	onchange={(e) => commit((e.currentTarget as HTMLInputElement).value)}
+	onchange={(e) => commit(e.currentTarget as HTMLInputElement)}
 />

package/dist/visual/NumberField.svelte.d.ts

@@ -2,7 +2,11 @@ import './controls.css';
 interface Props {
     value: number | undefined;
     integer?: boolean;
-    fallback?: number;
+    /** The resolved `default:` as text: what an unset field holds. */
+    fallback?: string;
+    /** Words at rest about an unset field that holds no text: the `None` an optional
+     * cell prints. */
+    placeholder?: string;
     /** Accessible name for an input nothing else names: an object property, whose
      * name is the field label plus the property's. A field's own input takes `id`
      * instead and is named by the `<label for>` beside it. */