@quillmark/svelte 0.11.0 → 0.13.0

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

@@ -1,4 +1,8 @@
 import type { Content, PathStep, QuillFieldSchema } from '@quillmark/wasm';
+import { type DeepDiagnostic } from './diagnostics.js';
+import type { LandingBox } from './leaves.js';
+import ObjectField from './ObjectField.svelte';
+import './controls.css';
 interface Props {
     value: Record<string, unknown> | undefined;
     properties: Record<string, QuillFieldSchema> | undefined;
@@ -11,8 +15,8 @@ interface Props {
     /**
      * The parent control's DOM id: the base each property's own three names derive
      * from ({@link propertyDomIds}). Absent — a subform mounted with no field around
-     * it — the properties fall back to `aria-label`, which names them without a
-     * `for` target to click.
+     * it, or a table's row — the properties fall back to `aria-label`, which names
+     * them without a `for` target to click.
      */
     idBase?: string;
     /** Accessible-name prefix used only on the `aria-label` fallback above. */
@@ -24,9 +28,20 @@ interface Props {
      * `undefined` for a property the stored value does not reach. */
     contentAt: (path: PathStep[]) => Content | undefined;
     onCommit: (obj: Record<string, unknown>) => void;
+    /** A table's row: the cells alone, on the tracks the table's header names, with
+     * no labels and no vertical of their own. */
+    bare?: boolean;
+    /** Raw keydown off a text or prose cell, for a row whose own keys run through its
+     * cells: the table's Enter and Backspace ({@link ArrayField}). */
+    onCellKey?: (e: KeyboardEvent, key: string) => void;
+    /** The diagnostics routed into this subform, each with its steps still to walk:
+     * one naming a property draws under that property's control, and one naming
+     * nothing this subform holds draws at its foot (`diagnostics.ts`). */
+    diagnostics?: readonly DeepDiagnostic[];
 }
 declare const ObjectField: import("svelte").Component<Props, {
     focus: () => void;
+    focusPath: (steps: readonly PathStep[], pos?: number) => LandingBox;
 }, "">;
 type ObjectField = ReturnType<typeof ObjectField>;
 export default ObjectField;

package/dist/visual/ProseField.svelte

@@ -11,7 +11,7 @@
 	import SlashMenu from './SlashMenu.svelte';
 	import { wording } from './strings.js';
 	import './controls.css';
-	import type { Document, Quill, Addr } from '@quillmark/wasm';
+	import type { Document, Quill, Addr, Content, Diagnostic } from '@quillmark/wasm';
 	import type { EditorErrorHandler } from '../core/errors.js';
 
 	interface Props {
@@ -37,9 +37,18 @@
 		labelledBy?: string;
 		/** The parked `description` (FieldLabel) → `aria-describedby`. */
 		describedBy?: string;
-		/** Ghost shown on the empty leaf: an inline leaf's resolved `default:` or
-		 * nothing, a body's always text (`resolveBodyGhost`). */
+		/** The resolved `default:` where it prints: what an unset field's leaf holds
+		 * until an edit takes it (`createField`). */
+		fallback?: Content;
+		/** Ghost shown on the empty leaf: the `none` an optional field prints unset, or
+		 * nothing, and a body's always text (`resolveBodyGhost`). */
 		placeholder?: string;
+		/** A field's leaf, whose placeholder goes at its first edit (`createField`). */
+		placeholderUntilEdit?: boolean;
+		/** Ghost shown on the empty leaf until its first edit, and in the placeholder's
+		 * stead while the leaf holds the focus: an unset field's `example:`
+		 * (`exampleGhost`). */
+		example?: string;
 		/** Registry identity, stamped on the DOM node so a remount is visible as one. */
 		leafKey: string;
 		onFocus?: (addr: Addr) => void;
@@ -50,6 +59,9 @@
 		/** The editor's leaf registry (`leaves.ts`). Registering the controller is what
 		 *  makes this leaf a caret target and not merely a focus one. */
 		leaves?: LeafRegistry;
+		/** The diagnostics routed to this field: each set re-evaluates a hold
+		 *  (`createField`), a re-validation being what follows an external write. */
+		diagnostics?: Diagnostic[];
 	}
 
 	let {
@@ -62,16 +74,23 @@
 		label,
 		labelledBy,
 		describedBy,
+		fallback,
 		placeholder,
+		placeholderUntilEdit,
+		example,
 		leafKey,
 		onFocus,
 		onCaretMove,
 		onChange,
 		onError,
-		leaves
+		leaves,
+		diagnostics
 	}: Props = $props();
 
 	let containerEl: HTMLDivElement | undefined = $state();
+	let held = $state(false);
+	const uid = $props.id();
+	const heldId = `${uid}-held`;
 
 	// Handed to the codec as a getter: the island chrome redraws on each render, so a
 	// locale swap reaches a mounted table without remounting the leaf and losing the caret.
@@ -82,10 +101,9 @@
 	 * trigger mounting on the block schema alone. */
 	let slash: SlashState | undefined = $state();
 
-	// The codec's own schema predicate (`createField`: `plaintext` implies `inline`), so
-	// the box a leaf draws and the schema it holds cannot disagree. On `inline` alone a
-	// `plaintext` field would take the block floor while holding one paragraph.
-	const block = $derived(!(inline || plaintext));
+	// The codec's own schema predicate (`leafSchema`: `inline` is one textblock at either
+	// type), so the box a leaf draws and the schema it holds cannot disagree.
+	const block = $derived(!inline);
 
 	let controller: FieldController | undefined;
 
@@ -107,7 +125,10 @@
 			label,
 			labelledBy,
 			describedBy,
+			fallback,
 			placeholder,
+			placeholderUntilEdit,
+			example,
 			tableStrings: () => t.strings,
 			onSlash: (next) => {
 				slash = next;
@@ -115,7 +136,11 @@
 			onFocus,
 			onCaretMove,
 			onChange,
-			onError
+			onError,
+			heldNoteId: heldId,
+			onHold: (next) => {
+				held = next;
+			}
 		});
 		leaves?.registerProse(leafKey, controller);
 		return () => {
@@ -126,10 +151,23 @@
 	});
 
 	// A retype does not remount the leaf (its key is the card's session id), so the new
-	// kind's ghost is pushed into the live view rather than paid for with the caret.
+	// kind's ghost and default are pushed into the live view rather than paid for with
+	// the caret.
 	$effect(() => {
 		controller?.setPlaceholder(placeholder);
 	});
+	$effect(() => {
+		controller?.setExample(example);
+	});
+	$effect(() => {
+		controller?.setFallback(fallback);
+	});
+
+	// Only a narrowed or a plain leaf can hold, so only one of them asks.
+	$effect(() => {
+		void diagnostics;
+		if (inline || plaintext) controller?.applyExternal();
+	});
 </script>
 
 <div
@@ -139,7 +177,11 @@
 	class:qm-focus-ring-within={!unframed}
 	class:qm-prose-block={block}
 	data-leaf-key={leafKey}
-></div>
+>
+	{#if held}
+		<span id={heldId} class="qm-prose-held-note">{t.strings.proseHeld}</span>
+	{/if}
+</div>
 <SlashMenu menu={slash} leaf={() => controller} label={t.strings.slashLabel} />
 
 <style>
@@ -179,16 +221,4 @@
 	.qm-prose :global(.ProseMirror) {
 		outline: none;
 	}
-	/* Empty-leaf ghost, at the rung every scalar's placeholder takes: a node decoration's
-	 data attr, so it stays out of the document; `float`/`height: 0` keep it from
-	 displacing the caret. The italic is what a leaf with no written neighbour has
-	 instead of the step to `ink`. */
-	.qm-prose :global(.ProseMirror .qm-prose-placeholder::before) {
-		content: attr(data-placeholder);
-		color: var(--_qm-ink-label);
-		font-style: italic;
-		float: left;
-		height: 0;
-		pointer-events: none;
-	}
 </style>

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

@@ -1,6 +1,6 @@
 import type { LeafRegistry } from './leaves.js';
 import './controls.css';
-import type { Document, Quill, Addr } from '@quillmark/wasm';
+import type { Document, Quill, Addr, Content, Diagnostic } from '@quillmark/wasm';
 import type { EditorErrorHandler } from '../core/errors.js';
 interface Props {
     doc: Document;
@@ -25,9 +25,18 @@ interface Props {
     labelledBy?: string;
     /** The parked `description` (FieldLabel) → `aria-describedby`. */
     describedBy?: string;
-    /** Ghost shown on the empty leaf: an inline leaf's resolved `default:` or
-     * nothing, a body's always text (`resolveBodyGhost`). */
+    /** The resolved `default:` where it prints: what an unset field's leaf holds
+     * until an edit takes it (`createField`). */
+    fallback?: Content;
+    /** Ghost shown on the empty leaf: the `none` an optional field prints unset, or
+     * nothing, and a body's always text (`resolveBodyGhost`). */
     placeholder?: string;
+    /** A field's leaf, whose placeholder goes at its first edit (`createField`). */
+    placeholderUntilEdit?: boolean;
+    /** Ghost shown on the empty leaf until its first edit, and in the placeholder's
+     * stead while the leaf holds the focus: an unset field's `example:`
+     * (`exampleGhost`). */
+    example?: string;
     /** Registry identity, stamped on the DOM node so a remount is visible as one. */
     leafKey: string;
     onFocus?: (addr: Addr) => void;
@@ -38,6 +47,9 @@ interface Props {
     /** The editor's leaf registry (`leaves.ts`). Registering the controller is what
      *  makes this leaf a caret target and not merely a focus one. */
     leaves?: LeafRegistry;
+    /** The diagnostics routed to this field: each set re-evaluates a hold
+     *  (`createField`), a re-validation being what follows an external write. */
+    diagnostics?: Diagnostic[];
 }
 declare const ProseField: import("svelte").Component<Props, {
     focus: () => void;

package/dist/visual/ProseValue.svelte

@@ -4,12 +4,12 @@
  `object`'s property, a variant's cell ({@link ObjectField}). None of them is
  `applyChange`-addressable: `Addr.field` is a flat name, so `keywords[0]` and
  `contact.note` have no op address. So this is not a `createField` leaf: it mounts a
- minimal PM view over the codec's decode/encode + inline schema, and on every edit
+ minimal PM view over the codec's decode/encode and a leaf schema, and on every edit
  hands the re-encoded `Content` up to the parent — {@link ArrayField}, which commits
  the whole array, or {@link ObjectField}, which commits the whole container
- (`writer.set(field, next)`). Anchors inside a value are dropped on that write:
- acceptable for inline refs. Mounts once per stable key (an element's session id, a
- property's name), so the parent's re-derive leaves the caret where it is.
+ (`writer.set(field, next)`). Anchors inside a value are dropped on that write.
+ Mounts once per stable key (an element's session id, a property's name), so the
+ parent's re-derive leaves the caret where it is.
 
  The content is read, not passed: `reader.getContentAt(addr, path)` decodes through
  the codec the leaf's own declared type names, so what it rests as — the content
@@ -17,37 +17,55 @@
  being the row's or the cell's business. Read once, at mount, since that is when this
  leaf takes its state.
 
- One textblock wherever it mounts, no islands and no slash menu. `plaintext` is
- inline at the codec, so that is the declared shape for every plaintext leaf; a block
- `richtext` is held one rung narrower than it declares, having no room for a second
- paragraph in the figure a repeater row and a subform cell draw.
+ The schema is the declared type's where the parent has room for it: a subform cell
+ declaring no `inline` takes the full row ({@link ObjectField}), a `richtext` one on the
+ block schema and a `plaintext` one on the plain schema, paragraphs and hard breaks.
+ An array element is one textblock whatever it declares, since Enter there is the
+ repeater's. There is no slash menu at either width, and an island draws as its
+ placeholder: an atom a keystroke can delete and no view edits.
+
+ A leaf over content its schema cannot hold is held: a narrowed one over anything but
+ one plain paragraph (`fitsInline`), a plain one over anything but plain lines
+ (`fitsPlain`). Its decode would join or drop what is left over, and the first
+ keystroke would write that loss back, so a held leaf draws its content on the block
+ schema, read-only, with a note inside its box, and commits nothing.
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
 	import { EditorState, Selection } from 'prosemirror-state';
 	import { EditorView } from 'prosemirror-view';
 	import {
+		blockSchema,
 		decode,
+		emptyContent,
+		fitsLeaf,
+		heldAttributes,
+		leafSchema,
 		pmToContent,
-		inlineSchema,
-		plaintextSchema,
 		proseAttributes,
 		proseLeafPlugins,
 		buildLineIndex,
 		usvToPM
 	} from '../core/codec/index.js';
+	import { wording } from './strings.js';
 	import './controls.css';
 	import type { Content } from '@quillmark/wasm';
 
 	interface Props {
-		/** This leaf's content, read at mount (the parent's boundary read). A thunk
-		 * rather than a value: the parent re-derives per revision and this leaf takes
-		 * its state once, so a value prop would be a boundary read per leaf per render,
-		 * all but one of them discarded. */
-		content: () => Content;
+		/** This leaf's content, read at mount (the parent's boundary read), `undefined`
+		 * where nothing is stored. A thunk rather than a value: the parent re-derives
+		 * per revision and this leaf takes its state once, so a value prop would be a
+		 * boundary read per leaf per render, all but one of them discarded. */
+		content: () => Content | undefined;
+		/** The default an unset leaf holds, where it prints: drawn at the default rung,
+		 * and handed up whole with the first edit in it, as `createField` takes one. */
+		fallback?: Content;
 		/** The mark-free schema (a `plaintext` leaf): literal text, no formatting,
 		 * exactly as the scalar field of that type mounts. */
 		plaintext?: boolean;
+		/** A multi-block schema, for a cell the parent draws at full width: the block
+		 * schema, or the plain one with `plaintext`. Absent, the leaf is one textblock. */
+		block?: boolean;
 		/** Accessible name for the editable region, where nothing else names it: an
 		 * array has no per-element label. A cell with a label element takes
 		 * `labelledBy`. */
@@ -58,6 +76,12 @@
 		labelledBy?: string;
 		/** The parked `description` (FieldLabel) → `aria-describedby`. */
 		describedBy?: string;
+		/** The empty leaf's ghosts, a subform cell's, until the leaf's first edit: the
+		 *  `none` an optional cell prints unset, and the `example:` drawn where there is no
+		 *  placeholder and in its stead while the leaf holds the focus (`createField`'s
+		 *  pair). Read per decoration pass. */
+		placeholder?: string;
+		example?: string;
 		onChange: (rt: Content) => void;
 		/** Raw keydown, for a container whose own keys run through this leaf: the
 		 * array repeater's Enter/Backspace (`ArrayField`). Fires before the view's own
@@ -66,15 +90,23 @@
 	}
 	let {
 		content,
+		fallback,
 		plaintext = false,
+		block = false,
 		label,
 		labelledBy,
 		describedBy,
+		placeholder,
+		example,
 		onChange,
 		onKey
 	}: Props = $props();
 
-	let containerEl: HTMLDivElement | undefined = $state();
+	const t = wording();
+	const uid = $props.id();
+	const heldId = `${uid}-held`;
+	let editorEl: HTMLDivElement | undefined = $state();
+	let held = $state(false);
 	let view: EditorView | undefined;
 	/** Take the caret: what a parent placing focus on this leaf calls. The view's
 	 * focus, not the element's: a PM view restores its selection, where a bare DOM
@@ -107,39 +139,55 @@
 	}
 
 	onMount(() => {
-		if (!containerEl) return;
-		// An inline, value-by-value leaf: the same keymap and plugin stack a
-		// `createField` leaf mounts (shared `proseLeafPlugins`), minus the
-		// anchor-position plugin (anchors are dropped on the parent's value write, per
-		// the header). Its own `dispatchTransaction` hands `Content` up.
-		//
-		// The schema is the declared type's, as `createField` picks it: `plaintext`
-		// declares no mark types, so there is nothing to toggle, to paste in, or to
-		// mint a shorthand with.
-		const schema = plaintext ? plaintextSchema : inlineSchema;
-		const pmDoc = decode(content(), schema);
+		if (!editorEl) return;
+		// The same keymap and plugin stack a `createField` leaf mounts (shared
+		// `proseLeafPlugins`), minus the anchor-position plugin: anchors are dropped on
+		// the parent's value write, per the header.
+		const inline = !block;
+		const stored = content();
+		const rt = stored ?? fallback ?? emptyContent();
+		let defaulted = stored === undefined && !!fallback;
+		held = !fitsLeaf(rt, { inline, plaintext });
+		const named = held
+			? heldAttributes({ label, labelledBy, describedBy }, heldId)
+			: (proseAttributes({ label, labelledBy, describedBy }) ?? {});
+		const defaultNamed = { ...named, 'data-default': '' };
+		const schema = held ? blockSchema : leafSchema({ plaintext, inline });
 		const state = EditorState.create({
-			doc: pmDoc,
-			plugins: proseLeafPlugins(schema, { inline: true })
+			doc: decode(rt, schema),
+			plugins: held
+				? []
+				: proseLeafPlugins(schema, {
+						inline,
+						placeholder: () => placeholder,
+						placeholderUntilEdit: true,
+						example: () => example
+					})
 		});
-		const mounted = new EditorView(containerEl, {
-			state,
-			// Which of `aria-label` / `aria-labelledby` wins is the codec's one answer
-			// (`proseAttributes`), so a cell carrying a label element and a row carrying
-			// none cannot name their regions by different rules.
-			attributes: proseAttributes({ label, labelledBy, describedBy }),
-			dispatchTransaction(tr) {
-				const next = mounted.state.apply(tr);
-				mounted.updateState(next);
-				if (tr.docChanged) onChange(pmToContent(next.doc));
-			},
-			handleDOMEvents: {
-				keydown: (_v, e) => {
-					onKey?.(e);
-					return false;
+		const mounted = new EditorView(
+			{ mount: editorEl },
+			{
+				state,
+				editable: () => !held,
+				// Which of `aria-label` / `aria-labelledby` wins is the codec's one answer
+				// (`proseAttributes`), so a cell carrying a label element and a row carrying
+				// none cannot name their regions by different rules.
+				attributes: () => (defaulted ? defaultNamed : named),
+				dispatchTransaction(tr) {
+					const next = mounted.state.apply(tr);
+					const edit = tr.docChanged && !held;
+					if (edit) defaulted = false;
+					mounted.updateState(next);
+					if (edit) onChange(pmToContent(next.doc));
+				},
+				handleDOMEvents: {
+					keydown: (_v, e) => {
+						onKey?.(e);
+						return false;
+					}
 				}
 			}
-		});
+		);
 		view = mounted;
 		return () => {
 			view = undefined;
@@ -153,7 +201,15 @@
  like the text cell beside it. No floor: the reset in `core/codec/prose.css` makes one
  line of prose measure one line. Width is the row's or the cell's to give: the leaf
  fills the track it is placed in. -->
-<div bind:this={containerEl} class="qm-prose-value qm-control-box qm-focus-ring-within"></div>
+<div class="qm-prose-value qm-control-box qm-focus-ring-within">
+	<div bind:this={editorEl}></div>
+	<!-- Inside the box, so the cell or row holds one child either way: a subform cell's
+	     subgrid has a row for the label and one for the box, and an array row's slabs
+	     stand the box's height. -->
+	{#if held}
+		<span id={heldId} class="qm-prose-held-note">{t.strings.proseHeld}</span>
+	{/if}
+</div>
 
 <style>
 	/* Caret-primary, matching ProseField: the contenteditable's own outline is

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

@@ -1,14 +1,20 @@
 import './controls.css';
 import type { Content } from '@quillmark/wasm';
 interface Props {
-    /** This leaf's content, read at mount (the parent's boundary read). A thunk
-     * rather than a value: the parent re-derives per revision and this leaf takes
-     * its state once, so a value prop would be a boundary read per leaf per render,
-     * all but one of them discarded. */
-    content: () => Content;
+    /** This leaf's content, read at mount (the parent's boundary read), `undefined`
+     * where nothing is stored. A thunk rather than a value: the parent re-derives
+     * per revision and this leaf takes its state once, so a value prop would be a
+     * boundary read per leaf per render, all but one of them discarded. */
+    content: () => Content | undefined;
+    /** The default an unset leaf holds, where it prints: drawn at the default rung,
+     * and handed up whole with the first edit in it, as `createField` takes one. */
+    fallback?: Content;
     /** The mark-free schema (a `plaintext` leaf): literal text, no formatting,
      * exactly as the scalar field of that type mounts. */
     plaintext?: boolean;
+    /** A multi-block schema, for a cell the parent draws at full width: the block
+     * schema, or the plain one with `plaintext`. Absent, the leaf is one textblock. */
+    block?: boolean;
     /** Accessible name for the editable region, where nothing else names it: an
      * array has no per-element label. A cell with a label element takes
      * `labelledBy`. */
@@ -19,6 +25,12 @@ interface Props {
     labelledBy?: string;
     /** The parked `description` (FieldLabel) → `aria-describedby`. */
     describedBy?: string;
+    /** The empty leaf's ghosts, a subform cell's, until the leaf's first edit: the
+     *  `none` an optional cell prints unset, and the `example:` drawn where there is no
+     *  placeholder and in its stead while the leaf holds the focus (`createField`'s
+     *  pair). Read per decoration pass. */
+    placeholder?: string;
+    example?: string;
     onChange: (rt: Content) => void;
     /** Raw keydown, for a container whose own keys run through this leaf: the
      * array repeater's Enter/Backspace (`ArrayField`). Fires before the view's own

package/dist/visual/TextField.svelte

@@ -1,12 +1,17 @@
 <!--
- A `string` field → text input. Commits a non-empty edit live (on input) via the
- parent's typed `writer.set`, so the preview tracks typing. A cleared field is the
- unset rung of the commitment ladder (VISUAL_EDITOR §"Structure mirrors the schema"): it
- commits `undefined` (the parent removes the field, ghosted `default:` renders):
- but at `change` (blur), not per keystroke, so select-all-and-retype doesn't flash
- the field through its default between the delete and the first typed char.
- Trade-off (recorded in VISUAL_EDITOR): an explicit empty string over a non-empty
- default is inexpressible from the UI: clear and unset collapse to one gesture.
+ A `string` field → text input. Commits every edit live (on input) via the parent's
+ typed `writer.set`, so the preview tracks typing.
+
+ An unset field whose `default:` prints holds that default as its text, at the
+ default rung (theme.css): the value it prints, drawn as one and a step off a written
+ one. Nothing is written until an edit, which writes the whole text as authored: the
+ default taken, whatever the edit left of it. Tabbing through writes nothing; a
+ keystroke typed and removed pins the default.
+
+ An emptied input writes what empty means for this field (VISUAL_EDITOR §"The
+ commitment ladder"): `""` over a default that prints, the only answer that prints empty there;
+ the unset rung elsewhere, where unset already prints nothing and the field stays
+ unanswered, and an optional cell returns to `none`.
 -->
 <script lang="ts">
 	import { syncedLocal } from './synced.svelte.js';
@@ -14,7 +19,14 @@
 
 	interface Props {
 		value: string | undefined;
+		/** The resolved `default:` where it prints: the text 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;
+		/** An unset field's `example:` (`exampleGhost`): drawn wherever the field holds no
+		 * text, and in `placeholder`'s stead while the input holds the focus. */
+		example?: string;
 		/** Accessible name for an input nothing else names: an array element, whose
 		 * name is the field label plus its 1-based index. A field's own input takes
 		 * `id` instead and is named by the `<label for>` beside it. */
@@ -29,11 +41,17 @@
 		 * array repeater's Enter/Backspace (`ArrayField`). */
 		onKey?: (e: KeyboardEvent) => void;
 	}
-	let { value, placeholder, label, id, describedBy, onCommit, onKey }: Props = $props();
+	let { value, fallback, placeholder, example, label, id, describedBy, onCommit, onKey }: Props =
+		$props();
 
-	// Local input state synced to `value`: own-typing stays local, only an external
-	// change reconciles back in (see `syncedLocal`).
-	const local = syncedLocal(() => value ?? '');
+	// Local input state synced to `value`, 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 ?? fallback ?? '');
+	const defaulted = $derived(value == null && !!fallback && local.value === fallback);
+
+	let focused = $state(false);
+	const ghost = $derived(focused ? (example ?? placeholder) : (placeholder ?? example));
 
 	let inputEl: HTMLInputElement | undefined = $state();
 	/** Take the caret: what a parent placing focus on this control calls. */
@@ -48,16 +66,15 @@
 	type="text"
 	value={local.value}
 	{id}
-	{placeholder}
+	placeholder={ghost}
+	data-default={defaulted ? '' : undefined}
 	aria-label={id ? undefined : label}
 	aria-describedby={describedBy}
 	onkeydown={onKey}
+	onfocus={() => (focused = true)}
+	onblur={() => (focused = false)}
 	oninput={(e) => {
 		local.value = (e.currentTarget as HTMLInputElement).value;
-		// Live-commit a non-empty edit; defer a cleared field to `change` (see header).
-		if (local.value !== '') onCommit(local.value);
-	}}
-	onchange={() => {
-		if (local.value === '') onCommit(undefined);
+		onCommit(local.value !== '' ? local.value : fallback ? '' : undefined);
 	}}
 />

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

@@ -1,7 +1,14 @@
 import './controls.css';
 interface Props {
     value: string | undefined;
+    /** The resolved `default:` where it prints: the text 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;
+    /** An unset field's `example:` (`exampleGhost`): drawn wherever the field holds no
+     * text, and in `placeholder`'s stead while the input holds the focus. */
+    example?: string;
     /** Accessible name for an input nothing else names: an array element, whose
      * name is the field label plus its 1-based index. A field's own input takes
      * `id` instead and is named by the `<label for>` beside it. */