@quillmark/svelte 0.20.1 → 0.22.0

package/dist/visual/Card.svelte

@@ -10,7 +10,7 @@
 	// component renders standalone too.
 	const t = wording();
 	import Icon from './icons/Icon.svelte';
-	import type { Document, Quill, Addr, Diagnostic } from '@quillmark/wasm';
+	import type { Document, Quill, Addr, Diagnostic, PathStep } from '@quillmark/wasm';
 	import type { EditorErrorHandler } from '../core/errors.js';
 	import type { LeafRegistry } from './leaves.js';
 	import type { CardModel, FieldModel } from './structure.js';
@@ -48,7 +48,7 @@
 		kinds: string[];
 		ops: CardOps;
 		enumDisallowed?: 'hide' | 'disable';
-		onFocus?: (addr: Addr) => void;
+		onFocus?: (addr: Addr, steps?: readonly PathStep[]) => void;
 		onCaretMove?: (addr: Addr, pos: number) => void;
 		onChange?: (addr: Addr) => void;
 		onError?: EditorErrorHandler;
@@ -72,13 +72,23 @@
 		leaves
 	}: Props = $props();
 
-	let localTitle = $derived(card.titleOverride);
+	// The rename in flight, written once on blur or Enter. Held apart from the stored
+	// title because a re-derive mid-edit hands `card` back with the title it stored.
+	let draft = $state<string | undefined>(undefined);
+	const shownTitle = $derived(draft ?? card.titleOverride);
 
-	// The pre-edit value Escape rolls back to; the rename itself stays live on input.
-	let titleAtFocus = '';
+	// A focus the shell hands over (`focusHeader`) is not armed for replacement: the key
+	// that pressed a delete, pressed again, would retitle the card it landed on.
+	let handed = false;
 	function onTitleFocus(e: FocusEvent): void {
-		titleAtFocus = localTitle;
-		(e.currentTarget as HTMLInputElement).select();
+		draft = card.titleOverride;
+		const input = e.currentTarget as HTMLInputElement;
+		if (handed) input.setSelectionRange(input.value.length, input.value.length);
+		else input.select();
+	}
+	function onTitleBlur(): void {
+		if (draft !== undefined && draft !== card.titleOverride) ops.rename(draft);
+		draft = undefined;
 	}
 	// A press on an unfocused title would place a caret on mouseup, collapsing the
 	// focus-time select-all. A press while already focused stays normal, so clicking
@@ -102,13 +112,10 @@
 		const el = e.currentTarget as HTMLInputElement;
 		if (e.key === 'Enter') {
 			e.preventDefault();
-			el.blur(); // commit: the live value already persisted on input
+			el.blur();
 		} else if (e.key === 'Escape') {
 			e.preventDefault();
-			if (localTitle !== titleAtFocus) {
-				localTitle = titleAtFocus;
-				ops.rename(titleAtFocus); // roll back the live edits
-			}
+			draft = undefined;
 			el.blur();
 		}
 	}
@@ -193,6 +200,13 @@
 		const reduce = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
 		el?.scrollIntoView({ behavior: reduce ? 'auto' : 'smooth', block });
 	}
+	/** Focus the title with the caret at its end, or the header's first live control on a
+	 *  recovery shell, which has no title to focus. */
+	export function focusHeader(): void {
+		handed = true;
+		el?.querySelector<HTMLElement>('.qm-card-header :is(input, button:not(:disabled))')?.focus();
+		handed = false;
+	}
 </script>
 
 <!-- `data-qm-card` names the island for a floating surface that has to stay inside one
@@ -210,20 +224,18 @@
 			<header class="qm-card-header">
 				<!-- svelte-ignore a11y_no_static_element_interactions -->
 				<div class="qm-card-rename" onmousedown={onRenameMousedown}>
-					<span class="qm-card-title-sizer" data-value={localTitle || card.titlePlaceholder}>
+					<span class="qm-card-title-sizer" data-value={shownTitle || card.titlePlaceholder}>
 						<input
 							class="qm-card-title qm-focus-ring"
-							value={localTitle}
+							value={shownTitle}
 							placeholder={card.titlePlaceholder}
 							aria-label={t.strings.cardTitle}
 							size="1"
 							onmousedown={onTitleMousedown}
 							onfocus={onTitleFocus}
+							onblur={onTitleBlur}
 							onkeydown={onTitleKeydown}
-							oninput={(e) => {
-								localTitle = (e.currentTarget as HTMLInputElement).value;
-								ops.rename(localTitle);
-							}}
+							oninput={(e) => (draft = (e.currentTarget as HTMLInputElement).value)}
 						/>
 					</span>
 				</div>
@@ -267,7 +279,7 @@
 									<div class="qm-group-head">
 										<button
 											type="button"
-											class="qm-group-header"
+											class="qm-group-header qm-focus-ring"
 											id={headIds?.label}
 											bind:this={headers[group]}
 											aria-expanded={isOpen}
@@ -463,10 +475,10 @@
 		 what crosses the line. */
 		margin-inline-end: calc(-1 * (var(--_qm-tap-min) - var(--_qm-glyph-control)) / 2);
 	}
-	/* Focus as well as hover, so a caret in any leaf, the title, or a chevron holds the
-	 reveal: hover alone would strand the pair on keyboard and touch. */
-	.qm-card:hover :global(.qm-card-reorder),
-	.qm-card:focus-within :global(.qm-card-reorder) {
+	/* Focus as well as hover, so a caret in any leaf, the title, or a control holds the
+	 reveal: hover alone would strand the row on the keyboard. */
+	.qm-card:hover :global(.qm-card-controls),
+	.qm-card:focus-within :global(.qm-card-controls) {
 		opacity: 1;
 	}
 	/* The rename hit region is the header's free width at full height, so a press
@@ -526,6 +538,12 @@
 	.qm-card-title:focus {
 		color: var(--_qm-ink);
 	}
+	/* The automatic title, at the label ink every placeholder takes rather than the UA's
+	 grey, and steady under focus, where a typed title steps to the ink. */
+	.qm-card-title::placeholder {
+		color: var(--_qm-ink-label);
+		opacity: 1;
+	}
 	.qm-card-body {
 		display: flex;
 		flex-direction: column;

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

@@ -1,4 +1,4 @@
-import type { Document, Quill, Addr, Diagnostic } from '@quillmark/wasm';
+import type { Document, Quill, Addr, Diagnostic, PathStep } from '@quillmark/wasm';
 import type { EditorErrorHandler } from '../core/errors.js';
 import type { LeafRegistry } from './leaves.js';
 import type { CardModel } from './structure.js';
@@ -27,7 +27,7 @@ interface Props {
     kinds: string[];
     ops: CardOps;
     enumDisallowed?: 'hide' | 'disable';
-    onFocus?: (addr: Addr) => void;
+    onFocus?: (addr: Addr, steps?: readonly PathStep[]) => void;
     onCaretMove?: (addr: Addr, pos: number) => void;
     onChange?: (addr: Addr) => void;
     onError?: EditorErrorHandler;
@@ -38,6 +38,7 @@ interface Props {
 declare const Card: import("svelte").Component<Props, {
     revealLeaf: (key: string) => void;
     scrollIntoViewCard: (block: ScrollLogicalPosition) => void;
+    focusHeader: () => void;
 }, "">;
 type Card = ReturnType<typeof Card>;
 export default Card;

package/dist/visual/CardControls.svelte

@@ -1,11 +1,11 @@
 <!--
   Card controls, composable cards only.
-  Right-aligned in the header: a move-up/move-down chevron pair revealed while the
-  pointer or the caret is in the card (each disabled at its edge), then delete.
+  Right-aligned in the header: a move-up/move-down chevron pair (each disabled at its
+  edge), then delete, the row revealed while the pointer or the caret is in the card.
   Reorder is buttons, not drag (V1). All three are chips (controls.css): fill arrives
-  on hover, and delete rests faded danger, full under the pointer. The card scopes
-  that reveal, so its condition lives in the parent's CSS; the pair keeps the narrower
-  guarantee here, that a focused chevron is a visible one.
+  on hover, and delete draws faded danger, full under the pointer. The card scopes
+  that reveal, so its condition lives in the parent's CSS; the row keeps the narrower
+  guarantee here, that a focused control is a visible one.
 -->
 <script lang="ts">
 	import { wording } from './strings.js';
@@ -56,21 +56,21 @@
 		display: flex;
 		align-items: center;
 		gap: var(--_qm-space-half);
-		/* One compositor layer for the row. Opacity on the pair otherwise snaps
-		   that box off the header's half-pixel, against delete which never leaves
-		   the document paint. */
+		opacity: 0;
+		transition: opacity var(--_qm-duration-fast) var(--_qm-ease-reverse);
+		/* One compositor layer for the row at rest as well as mid-fade: a box handed
+		   back to the document paint when its fade ends snaps off the header's
+		   half-pixel as it lands. */
 		transform: translateZ(0);
 	}
 	.qm-card-reorder {
 		display: flex;
-		opacity: 0;
-		transition: opacity var(--_qm-duration-fast) var(--_qm-ease-reverse);
 	}
-	/* Opacity hides the pair without taking it out of the tab order, so the
-	   component holds its own floor: a chevron that has focus is drawn, and its ring
-	   with it. The card's reveal already covers this; the rule is here because the
-	   hidden state is. */
-	.qm-card-reorder:focus-within {
+	/* Opacity hides the row without taking it out of the tab order, which keeps
+	   delete the keyboard's way to remove a card, so the component holds its own
+	   floor: a control that has focus is drawn, and its ring with it. The card's
+	   reveal already covers this; the rule is here because the hidden state is. */
+	.qm-card-controls:focus-within {
 		opacity: 1;
 	}
 	/* Squares: the chip's inline pad is for a label. Width and height are one rung

package/dist/visual/DateField.svelte

@@ -1,8 +1,8 @@
 <!--
  A `date` (or `datetime`) field → a styled segmented date field on bits-ui. The
- stored value is a string, `YYYY-MM-DD` or `today`; a cleared control commits
- `undefined` (the unset rung): the parent removes the field, and the quill's
- `default:` applies. The value-object a date field lowers to is a render-time
+ stored value is a string, `YYYY-MM-DD` or `today`; a cleared control commits as the
+ focus leaves it, the blank `""` over a `default:`, which stays blank, and `undefined`
+ (the unset rung) where nothing is declared, the parent removing the field. The value-object a date field lowers to is a render-time
  concern: the editor only sees the stored string.
 
  `today` is the render date rather than a written one (canon `SCHEMAS.md`), so its
@@ -43,8 +43,15 @@
 
  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.
+ default's. Leaving without an edit unseats it, and nothing is written.
+
+ A segment edit that leaves a segment empty empties the primitive's value, which is
+ held rather than committed while the focus stays inside: the first Backspace through
+ a date writes nothing unset, and the empty segment shows its hint, not the default's
+ digits beside the ones still standing. Leaving settles it: blank where every segment
+ is empty, otherwise the stored date back. A field storing no date puts its segments
+ back by remounting the primitive, which re-reads an unchanged empty value as nothing
+ to sync.
 -->
 <script lang="ts">
 	import { DateField as BitsDateField } from 'bits-ui';
@@ -108,13 +115,18 @@
 
 	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 re-derivation
-	 *  neither drops a seat nor restores one over the segments a clear left. */
+	 *  edit or leaving. Part of the projection, so a re-derivation keeps it. */
 	let seat = $state(false);
+	/** An emptied value held while the focus stays inside (see the header). Part of the
+	 *  projection too, so a re-derivation restores neither the stored date nor the seat
+	 *  over the segments it emptied. */
+	let held = $state(false);
+	/** Remounts the primitive when bumped (see the header). */
+	let generation = $state(0);
 	// Driven controlled (`value` + `onValueChange`, never `bind:`) so reconciliation
 	// stays the package's.
 	let local = $derived(
-		value?.slice(0, 10) ?? (seat && fallbackDate ? fallbackDate.toString() : '')
+		held ? '' : (value?.slice(0, 10) ?? (seat && fallbackDate ? fallbackDate.toString() : ''))
 	);
 	const parsed = $derived(toDateValue(local));
 	// The date the empty segments ghost, or undefined when there is nothing to ghost:
@@ -122,7 +134,7 @@
 	// 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 ghost = $derived(local === '' ? fallbackDate : undefined);
+	const ghost = $derived(value == null && local === '' && !held ? fallbackDate : undefined);
 	const seated = $derived(value == null && seat && local !== '');
 	/** Who put `today` here, while the field follows the render date. */
 	const follows = $derived(
@@ -130,6 +142,7 @@
 	);
 
 	function write(next: string): void {
+		held = false;
 		local = next;
 		seat = false;
 		onCommit(next);
@@ -152,7 +165,17 @@
 		if (!within(e) && value == null && fallbackDate) seat = true;
 	}
 	function leave(e: FocusEvent): void {
-		if (!within(e)) seat = false;
+		if (within(e)) return;
+		seat = false;
+		if (!held) return;
+		held = false;
+		const filled = [...(wrapEl?.querySelectorAll('[data-segment]') ?? [])].some(
+			(s) => s.getAttribute('data-segment') !== 'literal' && !s.hasAttribute('data-ghosted')
+		);
+		const blank = fallbackDate ? '' : undefined;
+		if (!filled) {
+			if (value !== blank) onCommit(blank);
+		} else if (!value) generation++;
 	}
 
 	// What one segment prints, and which rung it takes.
@@ -194,61 +217,67 @@
 	onfocusout={leave}
 	onkeydowncapture={shortcut}
 >
-	<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. The primitive reports
-			// its own value again as a segment loses focus, which is no edit, and over a
-			// seated default or `today` would write it.
-			const next = d?.toString() ?? '';
-			if (next === (parsed?.toString() ?? '')) return;
-			local = next;
-			if (!d) seat = false;
-			onCommit(d?.toString());
-		}}
-	>
-		<!-- `data-ghosted` states the rung the way the enum trigger does. The date
-		 primitive emits no per-segment placeholder marker (only bits' `select`
-		 does), so the tone rides the same attribute, set per segment from the
-		 substitution itself; which is also what keeps a half-typed date's own
-		 digits at full ink while the segments around them ghost. -->
-		<BitsDateField.Input
-			class="qm-date qm-control-box qm-focus-ring-within"
-			aria-label={labelledBy ? undefined : label}
-			aria-labelledby={labelledBy}
-			aria-describedby={describedBy}
-			data-ghosted={ghost ? '' : undefined}
-			data-default={seated || follows ? '' : undefined}
+	{#key generation}
+		<BitsDateField.Root
+			value={parsed}
+			placeholder={fallbackDate}
+			onValueChange={(d) => {
+				// `CalendarDate.toString()` is exactly `YYYY-MM-DD`. A cleared or
+				// half-typed field yields undefined, held until the focus leaves. The
+				// primitive reports its own value again as a segment loses focus, which is
+				// no edit, and over a seated default or `today` would write it.
+				const next = d?.toString() ?? '';
+				if (next === (parsed?.toString() ?? '')) return;
+				if (!d) {
+					held = true;
+					return;
+				}
+				held = false;
+				local = next;
+				onCommit(next);
+			}}
 		>
-			{#snippet children({ segments })}
-				<!-- Keyed by index: `part` repeats (the `literal` separators between
-				 segments all carry it) so a part-keyed block collides. -->
-				{#each segments as seg, i (i)}
-					{@const shown = segmentText(seg.part, seg.value)}
-					<BitsDateField.Segment
-						class="qm-date-segment"
-						part={seg.part}
-						data-ghosted={shown.ghosted}
-					>
-						{shown.text}
-					</BitsDateField.Segment>
-				{/each}
-				{#if !datetime}
-					<button
-						type="button"
-						class="qm-chip qm-tap-floor qm-focus-ring qm-date-today"
-						aria-pressed={!!follows}
-						data-default={follows === 'default' ? '' : undefined}
-						onclick={toggle}
-					>
-						<Icon name={follows ? 'calendar-check' : 'calendar'} />{t.strings.dateToday}
-					</button>
-				{/if}
-			{/snippet}
-		</BitsDateField.Input>
-	</BitsDateField.Root>
+			<!-- `data-ghosted` states the rung the way the enum trigger does. The date
+			 primitive emits no per-segment placeholder marker (only bits' `select`
+			 does), so the tone rides the same attribute, set per segment from the
+			 substitution itself; which is also what keeps a half-typed date's own
+			 digits at full ink while the segments around them ghost. -->
+			<BitsDateField.Input
+				class="qm-date qm-control-box qm-focus-ring-within"
+				aria-label={labelledBy ? undefined : label}
+				aria-labelledby={labelledBy}
+				aria-describedby={describedBy}
+				data-ghosted={ghost ? '' : undefined}
+				data-default={seated || follows ? '' : undefined}
+			>
+				{#snippet children({ segments })}
+					<!-- Keyed by index: `part` repeats (the `literal` separators between
+					 segments all carry it) so a part-keyed block collides. -->
+					{#each segments as seg, i (i)}
+						{@const shown = segmentText(seg.part, seg.value)}
+						<BitsDateField.Segment
+							class="qm-date-segment"
+							part={seg.part}
+							data-ghosted={shown.ghosted}
+						>
+							{shown.text}
+						</BitsDateField.Segment>
+					{/each}
+					{#if !datetime}
+						<button
+							type="button"
+							class="qm-chip qm-tap-floor qm-focus-ring qm-date-today"
+							aria-pressed={!!follows}
+							data-default={follows === 'default' ? '' : undefined}
+							onclick={toggle}
+						>
+							<Icon name={follows ? 'calendar-check' : 'calendar'} />{t.strings.dateToday}
+						</button>
+					{/if}
+				{/snippet}
+			</BitsDateField.Input>
+		</BitsDateField.Root>
+	{/key}
 </span>
 
 <style>

package/dist/visual/EnumField.svelte

@@ -16,6 +16,7 @@
 	import { Select } from 'bits-ui';
 	import Icon from './icons/Icon.svelte';
 	import { wording } from './strings.js';
+	import { spacePx } from '../core/rungs.js';
 	import './controls.css';
 
 	const t = wording();
@@ -79,6 +80,8 @@
 	 *  `none`: it draws at the default rung (theme.css). */
 	const ghostsMember = $derived(!optional && !!fallback);
 	const ghostText = $derived(optional ? t.strings.optionalGhost : dash(fallback));
+	/** The sentinel's tag says what picking it does: return to the default, or unset. */
+	const tag = $derived(ghostsMember ? t.strings.enumUnsetTag : t.strings.enumUnsetTagNone);
 	/** What the closed trigger shows: the pick, or the ghosted default while unset. */
 	const shown = $derived(unset ? ghostText : dash(local));
 
@@ -113,10 +116,10 @@
 			data-ghosted={unset ? (ghostsMember ? 'default' : '') : undefined}
 		>
 			<span class="qm-select-shown">{shown}</span>
-			<Icon name="chevron-down" class="qm-select-chevron" size={14} />
+			<Icon name="chevron-down" class="qm-select-chevron" />
 		</Select.Trigger>
 		<Select.Portal to={portalTarget}>
-			<Select.Content collisionBoundary={portalTarget ?? []} sideOffset={4}>
+			<Select.Content collisionBoundary={portalTarget ?? []} sideOffset={spacePx(wrapEl)}>
 				<!-- The list portals out of the trigger's DOM but into the nearest
 				     `[data-qm-root]`, and carries the marker itself, like FormatPopover.
 				     That root is the boundary a flip is measured against too, being the box
@@ -138,11 +141,11 @@
 						<Select.Item
 							class="qm-menu-item qm-select-item qm-select-unset"
 							value={UNSET}
-							label={optional ? ghostText : `${ghostText} ${t.strings.enumUnsetTag}`}
+							label={optional ? ghostText : `${ghostText} ${tag}`}
 						>
 							<span class="qm-select-ghost">{ghostText}</span>
 							{#if !optional}
-								<span class="qm-select-tag">{t.strings.enumUnsetTag}</span>
+								<span class="qm-select-tag">{tag}</span>
 							{/if}
 						</Select.Item>
 						<!-- A refused option still draws under `'disable'`, and under either
@@ -202,6 +205,8 @@
 	}
 	.qm-select-wrap :global(.qm-select-chevron) {
 		flex-shrink: 0;
+		width: var(--_qm-glyph-control);
+		height: var(--_qm-glyph-control);
 	}
 	/* The focus ring rides `.qm-focus-ring` on the trigger (controls.css). */
 	/* Shown-never-written: the closed control reads muted while unset, at the rung of

package/dist/visual/Field.svelte

@@ -27,7 +27,7 @@
 		ResolvedField
 	} from '@quillmark/wasm';
 	import type { EditorErrorHandler } from '../core/errors.js';
-	import { seatValueLeaves, type LandingBox, type LeafRegistry } from './leaves.js';
+	import { seatValueLeaves, stepsTo, type LandingBox, type LeafRegistry } from './leaves.js';
 	import type { FieldModel, FieldSpan } from './structure.js';
 	import {
 		VARIANT_DISCRIMINANT,
@@ -82,7 +82,9 @@
 		optionAllowed?: (value: string) => boolean;
 		/** How a refused option draws: greyed (default) or left out. */
 		enumDisallowed?: 'hide' | 'disable';
-		onFocus?: (addr: Addr) => void;
+		/** A focus inside the field: its address, and the steps down to the cell holding
+		 *  the focus ({@link stepsTo}), `[]` on the field's own control. */
+		onFocus?: (addr: Addr, steps?: readonly PathStep[]) => void;
 		onCaretMove?: (addr: Addr, pos: number) => void;
 		onChange?: (addr: Addr) => void;
 		onError?: EditorErrorHandler;
@@ -221,7 +223,7 @@
 
 	/**
 	 * This field's landing handle. The wrapper is the bloom host rather than the
-	 * control: `bloomInside` appends an inset child and an `<input>` holds none. The
+	 * control: the wash is a box's `::after`, which an `<input>` draws none of. The
 	 * label is outside it, and stays out of the wash: an arrival marks where the caret
 	 * landed, which is the control. A control that owns its label (`ownsLabel`: the array
 	 * and the matrix) holds that row inside itself, so it names its own box
@@ -251,7 +253,8 @@
 	}
 
 	// A by-value prose leaf anywhere inside this field's containers is reached under
-	// this field's key: the active address names the field, never the element or cell.
+	// this field's key: the registry and the active address name the field, never the
+	// element or cell.
 	seatValueLeaves({
 		focus: (leaf) => leaves?.focusValue(leafKey, leaf),
 		release: (leaf) => leaves?.releaseValue(leafKey, leaf)
@@ -261,11 +264,16 @@
 	 * A form control has no controller to report its focus through, so the wrapper
 	 * reports: `focusin` bubbles, so one handler covers a plain input, an array's N
 	 * elements and an object's properties alike, and the active leaf names a scalar
-	 * field the way it names a prose one. A prose leaf reports through its own
+	 * field the way it names a prose one, down to the element or cell the focus is in. A prose leaf reports through its own
 	 * controller — the source that drives its caret signals too — and is excluded here
 	 * rather than counted twice.
 	 */
-	const reportFocus = $derived(field.control === 'prose' ? undefined : () => onFocus?.(addr));
+	const reportFocus = $derived(
+		field.control === 'prose'
+			? undefined
+			: (e: FocusEvent & { currentTarget: HTMLElement }) =>
+					onFocus?.(addr, stepsTo(e.target, e.currentTarget))
+	);
 </script>
 
 <div class={['qm-field', { cell: span === 'cell' }]}>
@@ -276,7 +284,6 @@
 			id={domIds.label}
 			descriptionId={domIds.description}
 			{onActivate}
-			required={field.required}
 			description={field.description}
 		/>
 	{/if}
@@ -285,7 +292,7 @@
 	 rule below holds why). One markup for both spans; a field owning its row nests a
 	 level and measures the same. -->
 	<div class="qm-field-stack">
-		<div class="qm-field-control" {@attach registerControl} onfocusin={reportFocus}>
+		<div class="qm-field-control qm-wash" {@attach registerControl} onfocusin={reportFocus}>
 			{#if field.control === 'prose'}
 				<ProseField
 					{quill}
@@ -296,7 +303,7 @@
 					plaintext={field.plaintext}
 					fallback={printed ? (ghost as Content) : undefined}
 					placeholder={none}
-					placeholderUntilEdit
+					emptyUnsets={optional}
 					labelledBy={domIds.label}
 					{describedBy}
 					{leafKey}
@@ -374,7 +381,6 @@
 					layout={arrayLayout(field.schema)}
 					max={field.schema.max}
 					label={field.label}
-					required={field.required}
 					description={field.description}
 					labelId={domIds.label}
 					descriptionId={domIds.description}
@@ -389,6 +395,7 @@
 					value={value as Record<string, unknown> | undefined}
 					properties={field.schema.properties}
 					{flat}
+					placed
 					label={field.label}
 					idBase={domIds.control}
 					labelledBy={domIds.label}
@@ -476,13 +483,10 @@
 		gap: var(--_qm-space);
 		min-width: 0;
 	}
-	/* Positioned for the arrival wash a landing inserts (`core/bloom.ts`), the way
-	   `.qm-prose` is: an inset child over the control, since an `<input>` takes none.
-	   The radius is the control's own, so the wash's corners are the box's rather than
-	   square over a rounded one; on an array or a subform it bounds a group, where
-	   there is no single box for it to disagree with. */
+	/* The arrival wash's host (`.qm-wash`). The radius is the control's own, so the
+	   wash's corners are the box's rather than square over a rounded one; on an array or
+	   a subform it bounds a group, where there is no single box for it to disagree with. */
 	.qm-field-control {
-		position: relative;
 		border-radius: var(--_qm-radius-inner);
 	}
 </style>

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

@@ -1,4 +1,4 @@
-import type { Document, Quill, Addr, Diagnostic, ResolvedField } from '@quillmark/wasm';
+import type { Document, Quill, Addr, Diagnostic, PathStep, ResolvedField } from '@quillmark/wasm';
 import type { EditorErrorHandler } from '../core/errors.js';
 import { type LeafRegistry } from './leaves.js';
 import type { FieldModel, FieldSpan } from './structure.js';
@@ -27,7 +27,9 @@ interface Props {
     optionAllowed?: (value: string) => boolean;
     /** How a refused option draws: greyed (default) or left out. */
     enumDisallowed?: 'hide' | 'disable';
-    onFocus?: (addr: Addr) => void;
+    /** A focus inside the field: its address, and the steps down to the cell holding
+     *  the focus ({@link stepsTo}), `[]` on the field's own control. */
+    onFocus?: (addr: Addr, steps?: readonly PathStep[]) => void;
     onCaretMove?: (addr: Addr, pos: number) => void;
     onChange?: (addr: Addr) => void;
     onError?: EditorErrorHandler;

package/dist/visual/FieldHint.svelte

@@ -180,7 +180,7 @@
 			e.stopPropagation();
 			open = false;
 		}
-	}}><Icon name="info" size={13} /></button
+	}}><Icon name="info" /></button
 >
 
 <!-- Placement is the description's height. One line rides the label rung beside its own
@@ -249,8 +249,15 @@
 	 So the box is the glyph and the target is `.qm-tap-floor`'s (controls.css), which
 	 carries that split and the giving-up of the family floor together.
 
-	 It takes no fill either: the ink step below says hover, and the surface itself
-	 opens on it. */
+	 It takes no fill either: the surface itself opens on hover.
+
+	 At rest it recedes to the idle rung, a card describing every field otherwise
+	 standing a mark beside each label before anything is touched. It lifts with the
+	 scope that owns its row (the field, the property, the array or matrix, the table
+	 its column heads, the section a lone field is named by), each reached by child
+	 steps so a nested field's marker stays at rest under its container's hover, and
+	 while its surface is open. The keyboard's `Mod-/` and the parked description do not
+	 depend on the lift. */
 	.qm-field-hint {
 		/* The marker recedes to the label rung; the surface carries the text. */
 		color: var(--_qm-ink-label);
@@ -258,10 +265,20 @@
 		cursor: help;
 		padding: 0;
 		background: none;
+		opacity: var(--_qm-opacity-idle);
+		transition: opacity var(--_qm-duration-fast) var(--_qm-ease-reverse);
 	}
+	:global(:is(.qm-field, .qm-object-prop):is(:hover, :focus-within) > .qm-field-label-row)
+		> .qm-field-hint,
+	:global(:is(.qm-array, .qm-matrix):is(:hover, :focus-within) > * > .qm-field-label-row)
+		> .qm-field-hint,
+	:global(.qm-array-table:is(:hover, :focus-within) .qm-array-table-col > .qm-field-label-row)
+		> .qm-field-hint,
+	:global(.qm-group:is(:hover, :focus-within) > .qm-group-head) > .qm-field-hint,
 	.qm-field-hint:hover,
-	.qm-field-hint:focus-visible {
-		color: var(--_qm-ink-label);
+	.qm-field-hint:focus-visible,
+	.qm-field-hint[aria-expanded='true'] {
+		opacity: 1;
 	}
 	/* The lift, the translucency, the blur and the scale-in come from
 	 `.qm-popover-surface` (controls.css). This surface's own is a measure: guidance