@quillmark/svelte 0.12.0 → 0.14.0

package/dist/visual/NumberField.svelte

@@ -1,23 +1,32 @@
 <!--
  A `number` / `integer` field → numeric input (fixture `font_size` = 11.5).
  Commits at `change` (blur/Enter), not per keystroke: a partial numeric entry
- (`-`, `1.`, `1e`) is never a document state worth a boundary round-trip, and
+ (`-`, `1.`) 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.
 
- `type="text"`, not `type="number"`: a native number input sanitizes an
- invalid string to `""` before the DOM `value` setter even runs (verified:
- `.value = "abc"` on `type="number"` never lands), which would make a
- genuinely bad entry untypeable. The commit-time coercion diagnostic
- (VISUAL_EDITOR §Diagnostics) needs exactly that path reachable through the
- UI, so a non-blank entry that fails to parse forwards the raw string to
- `onCommit` unchanged: the boundary's own `writer.set` coercion is the judge
- (throws a `QuillmarkError` the parent turns into a field diagnostic), not a
- client-side guess. `inputmode` keeps the numeric mobile keyboard.
+ 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.
+
+ The entry grammar is plain decimal: an optional sign and digits, and for a `number`
+ a `.` and an exponent, the form `String()` gives a value too small or large for
+ digits. A keystroke that leaves the text outside a prefix of it does not land, and in
+ a `number` a `,` lands as `.`, the decimal key of a comma locale's keypad. A deletion
+ always lands, so a stored value outside the grammar (`abc`) can be cleared, and a
+ paste, a drop or an IME composition lands as it comes, judged when it settles.
+ `type="text"`, not `type="number"`: a native number input sanitizes an invalid
+ string to `""` rather than showing it, and steps on a scroll-wheel. `inputmode`
+ keeps the numeric mobile keyboard.
+
+ A settled entry in the grammar commits as a number. Anything else forwards the raw
+ string to `onCommit`: the boundary's `writer.set` coercion is the judge (throws a
+ `QuillmarkError` the parent turns into a field diagnostic, VISUAL_EDITOR
+ §Diagnostics). `Number()` alone is no gate: it reads `0x1F` and `Infinity` as
+ numbers, and `1.000` as a whole one.
 -->
 <script lang="ts">
 	import { syncedLocal } from './synced.svelte.js';
@@ -26,7 +35,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,21 +51,50 @@
 		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), 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);
 
-	// 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) : ''));
+	const partial = $derived(
+		integer ? /^\s*[+-]?\d*\s*$/ : /^\s*[+-]?\d*\.?\d*(?:[eE][+-]?\d*)?\s*$/
+	);
+	const whole = $derived(integer ? /^[+-]?\d+$/ : /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/);
+
+	function filter(e: InputEvent): void {
+		if (e.inputType !== 'insertText' || e.data == null) return;
+		const el = e.currentTarget as HTMLInputElement;
+		const from = el.selectionStart ?? el.value.length;
+		const to = el.selectionEnd ?? el.value.length;
+		const data = !integer && e.data === ',' ? '.' : e.data;
+		const next = el.value.slice(0, from) + data + el.value.slice(to);
+		if (!partial.test(next)) return e.preventDefault();
+		if (data === e.data) return;
+		e.preventDefault();
+		// `insertText` lands on the undo stack and fires `input`; `setRangeText` does neither.
+		if (document.execCommand?.('insertText', false, data)) return;
+		el.setRangeText(data, from, to, 'end');
+		local.value = el.value;
+	}
 
 	// 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);
-		// 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.
-		const n = Number(raw);
-		onCommit(Number.isNaN(n) ? raw : n);
+	// `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;
+		const entry = raw.trim();
+		if (entry === '') {
+			onCommit(undefined);
+			local.value = el.value = fallback ?? '';
+			return;
+		}
+		// Finite as well: a digit run past `Number.MAX_VALUE` reads as `Infinity`.
+		const n = whole.test(entry) ? Number(entry) : NaN;
+		onCommit(Number.isFinite(n) ? n : raw);
 	}
 </script>
 
@@ -62,11 +104,13 @@
 	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}
+	onbeforeinput={filter}
 	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. */

package/dist/visual/ObjectField.svelte

@@ -19,10 +19,10 @@
  An array element's properties hang a rung further in ({@link ArrayField}), the summary
  above them standing for the whole row.
 
- A property's ghosted `default:` is the static schema `sub.default`, not the
- resolved provenance the top-level ghosts read (FIELD_PROVENANCE): `resolve`
- carries no per-property row (an object field resolves as one row whose value is
- the whole object).
+ A property's `default:`, which an unset cell holds until an edit takes it, is the
+ static schema `sub.default`, not the resolved provenance a field reads
+ (FIELD_PROVENANCE): `resolve` carries no per-property row (an object field resolves
+ as one row whose value is the whole object).
 
  Every caller hands down `contentAt`, which is `reader.getContentAt` with the field
  already bound: a field-level subform passes the property key through untouched, a
@@ -34,8 +34,20 @@
 -->
 <script lang="ts">
 	import type { Content, PathStep, QuillFieldSchema } from '@quillmark/wasm';
-	import { emptyContent } from '../core/codec/index.js';
-	import { arrayLayout, controlKind, humanize, isContainer, obliged } from './structure.js';
+	import {
+		arrayLayout,
+		baseType,
+		controlKind,
+		declaredContent,
+		exampleGhost,
+		humanize,
+		isContainer,
+		mountKey,
+		obliged,
+		optionalCell,
+		printedText,
+		shortCell
+	} from './structure.js';
 	import { splitDeep, unrouted, type DeepDiagnostic } from './diagnostics.js';
 	import type { LandingBox } from './leaves.js';
 	import { wording } from './strings.js';
@@ -117,7 +129,19 @@
 	 *  (VISUAL_EDITOR §"Enum variants"). */
 	const required = obliged;
 
-	const title = (key: string, sub: QuillFieldSchema): string => sub.ui?.title ?? humanize(key);
+	const title = (key: string, sub: QuillFieldSchema): string => sub.title ?? humanize(key);
+	/** What an unset optional cell ghosts, which is what it prints: `none`. An answered
+	 *  cell ghosts nothing, an empty answer printing empty. */
+	const noneOf = (key: string, sub: QuillFieldSchema): string | undefined =>
+		obj[key] == null && optionalCell(sub) ? t.strings.optionalGhost : undefined;
+	/** What an unset free-text cell ghosts where nothing prints ({@link exampleGhost}). */
+	const exampleOf = (key: string, sub: QuillFieldSchema): string | undefined =>
+		obj[key] == null ? exampleGhost(sub) : undefined;
+	/** A scalar cell's `default:` as the text an unset cell holds, where it prints. */
+	const textDefault = (sub: QuillFieldSchema): string | undefined => printedText(sub.default);
+	/** A content cell's `default:` as the content an unset leaf holds, where it prints. */
+	const contentDefault = (sub: QuillFieldSchema): Content | undefined =>
+		declaredContent(sub.default, baseType(sub) === 'richtext');
 	/** The `aria-label` fallback, for a subform mounted without a field's id space:
 	 *  the field's name and the property's, since nothing else names the control. */
 	const fallbackName = (key: string, sub: QuillFieldSchema): string =>
@@ -237,7 +261,7 @@
 	<!-- The grid is one box in, so the wrapper can be the query container it reads its
 	     capacity from: a container cannot query itself. -->
 	<div class="qm-object-grid qm-tracks">
-		{#each entries as [key, sub] (key)}
+		{#each entries as [key, sub] (mountKey(key, sub))}
 			{@const kind = controlKind(sub)}
 			{@const ids = idBase && !bare ? propertyDomIds(idBase, key) : undefined}
 			{@const named = ids ? undefined : fallbackName(key, sub)}
@@ -255,8 +279,14 @@
 				kind === 'boolean'}
 			<!-- A container takes the full span at every depth: its rows are the document's
 			     to count, and a track beside it would stand in a column of whitespace
-			     (`packable`). -->
-			<div class="qm-object-prop" class:qm-prop-full={isContainer(kind)} data-qm-prop={key}>
+			     (`packable`). A block prose cell spans it too, and keeps its label row. -->
+			{@const block = kind === 'prose' && !shortCell(sub)}
+			<div
+				class="qm-object-prop"
+				class:qm-prop-full={isContainer(kind)}
+				class:qm-prop-wide={block}
+				data-qm-prop={key}
+			>
 				{#if ids && kind !== 'array' && kind !== 'matrix'}
 					<FieldLabel
 						label={title(key, sub)}
@@ -276,6 +306,8 @@
 						value={obj[key] as string | undefined}
 						values={sub.values ?? []}
 						fallback={sub.default as string | undefined}
+						blankTitle={sub.ui?.blank_title}
+						optional={optionalCell(sub)}
 						onCommit={(v) => commitProp(key, v)}
 					/>
 				{:else if kind === 'number'}
@@ -284,8 +316,9 @@
 						id={ids?.control}
 						describedBy={describes}
 						value={obj[key] as number | undefined}
-						integer={sub.type === 'integer'}
-						fallback={sub.default as number | undefined}
+						integer={baseType(sub) === 'integer'}
+						fallback={textDefault(sub)}
+						placeholder={noneOf(key, sub)}
 						onCommit={(v) => commitProp(key, v)}
 					/>
 				{:else if kind === 'boolean'}
@@ -295,6 +328,7 @@
 						describedBy={describes}
 						value={obj[key] as boolean | undefined}
 						fallback={sub.default as boolean | undefined}
+						optional={optionalCell(sub)}
 						onCommit={(v) => commitProp(key, v)}
 					/>
 				{:else if kind === 'date'}
@@ -304,6 +338,7 @@
 						describedBy={describes}
 						value={obj[key] as string | undefined}
 						fallback={sub.default != null ? String(sub.default) : undefined}
+						datetime={baseType(sub) === 'datetime'}
 						onCommit={(v) => commitProp(key, v)}
 					/>
 				{:else if kind === 'text'}
@@ -312,7 +347,9 @@
 						id={ids?.control}
 						describedBy={describes}
 						value={obj[key] as string | undefined}
-						placeholder={sub.default != null ? String(sub.default) : undefined}
+						fallback={textDefault(sub)}
+						placeholder={noneOf(key, sub)}
+						example={exampleOf(key, sub)}
 						onCommit={(v) => commitProp(key, v)}
 						onKey={onCellKey ? (e) => onCellKey(e, key) : undefined}
 					/>
@@ -321,8 +358,12 @@
 					     leaves the leaf mounted and the caret in it. -->
 					<ProseValue
 						bind:this={proseEls[key]}
-						content={() => contentAt([key]) ?? emptyContent()}
-						plaintext={sub.type === 'plaintext'}
+						content={() => contentAt([key])}
+						fallback={contentDefault(sub)}
+						plaintext={baseType(sub) === 'plaintext'}
+						placeholder={noneOf(key, sub)}
+						example={exampleOf(key, sub)}
+						{block}
 						label={named}
 						labelledBy={ids?.label}
 						describedBy={describes}
@@ -338,6 +379,7 @@
 					<ArrayField
 						bind:this={nestedEls[key]}
 						value={obj[key] as unknown[] | undefined}
+						fallback={Array.isArray(sub.default) ? sub.default : undefined}
 						items={sub.items}
 						layout={arrayLayout(sub)}
 						max={sub.max}
@@ -469,6 +511,12 @@
 	.qm-object-prop:only-child {
 		grid-column: span var(--cols-half);
 	}
+	/* A block prose property holds paragraphs, so a track beside it stands in whitespace
+	   once it grows (`packable`); its label still rides the row above it. */
+	.qm-object-prop.qm-prop-wide,
+	.qm-object-prop.qm-prop-wide:only-child {
+		grid-column: 1 / -1;
+	}
 	/* A container property takes the whole row and its own rows: its label rides inside
 	   the control it draws (a repeater's header, a matrix's) or above a subform of its
 	   own, and neither is a track a scalar's label shares. */

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;
+		/** The placeholder goes at the leaf's 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;
+    /** The placeholder goes at the leaf's 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;