@quillmark/svelte 0.20.0 → 0.21.0

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/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

package/dist/visual/FieldLabel.svelte

@@ -116,12 +116,12 @@
 	.qm-field-label.targeted {
 		cursor: pointer;
 	}
-	/* Required marker: a quiet accent glyph, not an alarm; required-ness is guidance,
-	 the document still edits and renders unmet. */
+	/* Required marker: the label's own ink, not an alarm; required-ness is guidance,
+	 the document still edits and renders unmet, and the danger hue is a diagnostic's. */
 	.qm-field-required {
 		display: inline-flex;
 		align-items: center;
-		color: var(--_qm-danger);
+		color: var(--_qm-ink-label);
 		line-height: 1;
 	}
 	/* The parked description: in the accessibility tree, out of the layout, and never

package/dist/visual/FormatPopover.svelte

@@ -24,7 +24,10 @@
  A press holds it down, which is what makes the surface answer a selection rather
  than a pointer: a drag fires `selectionchange` on every frame, so a surface driven
  by that alone rises on the first character and rides the cursor across the text it
- is covering. Keyboard selection holds nothing, so a Shift-arrow syncs as it fires.
+ is covering. Keyboard selection holds nothing, so it waits instead: a rise with no
+ release behind it comes once the selection has stood still for `SETTLE_MS`, so a
+ Shift-arrow run, or a select-all on its way to a cut, raises nothing until it stops.
+ A lowering never waits, and an open surface follows each step.
 
  Nothing here watches scroll. `sync` decides whether the surface is up, which a
  scroll does not change; where it sits is the anchor's own question, and the anchor
@@ -70,6 +73,7 @@
 	import { hasMarks, rangeAnchor, type RangeAnchor } from '../core/codec/index.js';
 	import type { ActiveProse } from './leaves.js';
 	import { clearLink, hrefInSelection, normalizeHref, setLink } from './links.js';
+	import { spacePx } from '../core/rungs.js';
 	import './controls.css';
 
 	interface Props {
@@ -78,7 +82,7 @@
 	}
 	let { getActiveLeaf }: Props = $props();
 
-	const GLYPH = 15;
+	const SETTLE_MS = 450;
 	/** The six content formatting marks. `anchor` is a seventh, drawn separately below:
 	 *  a decoration toggle rather than a PM `toggleMark`. One string per mark carries both
 	 *  the tooltip and the accessible name; the anchor button spells the two separately. */
@@ -120,7 +124,8 @@
 		return getActiveLeaf()?.views.focusedView();
 	}
 
-	function sync(): void {
+	function sync(wait = false): void {
+		clearTimeout(settling);
 		const insidePopover =
 			!!contentEl && !!document.activeElement && contentEl.contains(document.activeElement);
 		// Interacting with the popover itself (e.g. the link input): leave state as-is.
@@ -151,6 +156,10 @@
 			linkPromptOpen = false;
 			return;
 		}
+		if (wait && !open) {
+			settling = setTimeout(() => sync(), SETTLE_MS);
+			return;
+		}
 		portalTarget = view.dom.closest<HTMLElement>('[data-qm-root]') ?? undefined;
 		const { from, to } = view.state.selection;
 		anchor = rangeAnchor(view, from, to);
@@ -186,12 +195,17 @@
 	// selection. `pending` collapses a burst to a single scheduled callback.
 	let pending = false;
 	let rafHandle = 0;
+	/** The check in flight answers a pointer's release, which raises at once. */
+	let released = false;
+	let settling: ReturnType<typeof setTimeout> | undefined;
 	function deferredSync(): void {
 		if (pending) return;
 		pending = true;
 		rafHandle = requestAnimationFrame(() => {
 			pending = false;
-			sync();
+			const wait = !released;
+			released = false;
+			sync(wait);
 		});
 	}
 
@@ -205,14 +219,16 @@
 	function onPointerUp(): void {
 		if (!pressed) return;
 		pressed = false;
+		released = true;
 		deferredSync();
 	}
 
-	// A burst-coalescing rAF may still be in flight at teardown; cancel it so
-	// `sync()` never runs against the destroyed component.
+	// A burst-coalescing rAF or a settling rise may still be in flight at teardown;
+	// cancel both so `sync()` never runs against the destroyed component.
 	onDestroy(() => {
 		if (pending) cancelAnimationFrame(rafHandle);
 		pending = false;
+		clearTimeout(settling);
 	});
 
 	// Any close path that bypasses `sync` (e.g. Escape while the link input holds
@@ -342,7 +358,7 @@
 			side="top"
 			align="center"
 			trapFocus={false}
-			sideOffset={8}
+			sideOffset={spacePx(portalTarget, 2)}
 			onOpenAutoFocus={(e: Event) => e.preventDefault()}
 			onCloseAutoFocus={(e: Event) => e.preventDefault()}
 		>
@@ -411,7 +427,7 @@
 										title={m.title}
 										aria-label={m.title}
 										onmousedown={keepFocus}
-										onclick={() => toggle(m.name)}><Icon name={m.icon} size={GLYPH} /></button
+										onclick={() => toggle(m.name)}><Icon name={m.icon} /></button
 									>
 								{/each}
 								{#if anchorAvailable}
@@ -421,7 +437,7 @@
 										title={t.strings.formatAnchorTitle}
 										aria-label={t.strings.formatAnchor}
 										onmousedown={keepFocus}
-										onclick={toggleAnchor}><Icon name="hash" size={GLYPH} /></button
+										onclick={toggleAnchor}><Icon name="hash" /></button
 									>
 								{/if}
 							</div>

package/dist/visual/MatrixField.svelte

@@ -525,16 +525,19 @@
 		background: var(--_qm-danger-tint);
 		color: var(--_qm-danger);
 	}
-	.qm-member-remove :global(svg) {
-		width: var(--_qm-glyph-control);
-		height: var(--_qm-glyph-control);
-	}
-	/* The default's set is what prints and nothing written: its titles and every value
-	 its columns draw take the default rung (theme.css), and the first gesture, writing
-	 it, takes it off. */
+	/* The default's set is what prints and nothing written: its titles, its ticks and
+	 every value its columns draw take the default rung (theme.css), and the first
+	 gesture, writing it, takes it off. */
 	.qm-matrix-roster[data-default] :global(:is(.qm-input, .ProseMirror, .qm-date)),
 	.qm-matrix-roster[data-default] :global(.qm-select:not([data-ghosted])),
 	.qm-matrix-roster[data-default] .qm-member.held .qm-member-title {
 		color: var(--_qm-ink-default);
 	}
+	.qm-matrix-roster[data-default] :is(.qm-tick-input:checked, .qm-tick-fixed) {
+		background: var(--_qm-accent-default);
+		border-color: var(--_qm-accent-default);
+	}
+	.qm-matrix-roster[data-default] :global(.qm-toggle[data-state='checked']) {
+		background: var(--_qm-accent-default);
+	}
 </style>

package/dist/visual/ObjectField.svelte

@@ -457,10 +457,8 @@
 	/* The vertical and the rung between it and the properties, `--_qm-nest` being the step
 	   the card and the section hold too.
 
-	   `--_qm-border` and not `--_qm-border-faint`: this is the stroke that structures
-	   (ARCHITECTURE §"A plane is a tone"), the one the card's edge and the section's
-	   vertical read. `faint` separates without structuring — a table's interior lines
-	   under a frame that is doing the structuring — which is the other job.
+	   `--_qm-border`: this is the stroke that structures (ARCHITECTURE §"A plane is a
+	   tone"), the one the card's edge and the section's vertical read.
 
 	   `padding-block` is the stroke's end caps, the same rung and the same reason as a
 	   section's (`Card.svelte`). A cap and not a leading gap: what stands the subform off

package/dist/visual/TipsCard.svelte

@@ -31,9 +31,6 @@
 	}
 	let { tips, onDismiss, onError }: Props = $props();
 
-	/** Control-glyph size: the shared rule, as CardControls. */
-	const GLYPH = 14;
-
 	let cursor = $state(0);
 	// Clamped: the channel is consumer-authored and can be re-seeded shorter while
 	// the card is open, which would otherwise index past the end.
@@ -82,9 +79,9 @@
 		{/if}
 		<button type="button" class="qm-icon-btn qm-tips-action" onclick={advance}>
 			{#if isLast}
-				{t.strings.tipsDismiss} <Icon name="trash-2" size={GLYPH} />
+				{t.strings.tipsDismiss} <Icon name="trash-2" />
 			{:else}
-				{t.strings.tipsNext} <Icon name="arrow-right" size={GLYPH} />
+				{t.strings.tipsNext} <Icon name="arrow-right" />
 			{/if}
 		</button>
 	</div>