@quillmark/svelte 0.16.0 → 0.18.0

package/dist/visual/Card.svelte

@@ -9,7 +9,6 @@
 	// Ambient from the editor root, with the package's English off-tree, so this
 	// component renders standalone too.
 	const t = wording();
-	import { untrack } from 'svelte';
 	import Icon from './icons/Icon.svelte';
 	import type { Document, Quill, Addr, Diagnostic } from '@quillmark/wasm';
 	import type { EditorErrorHandler } from '../core/errors.js';
@@ -19,6 +18,7 @@
 	import { holdInView } from './hold.js';
 	import type { FieldDomIds } from './domid.js';
 	import Field from './Field.svelte';
+	import FieldHint from './FieldHint.svelte';
 	import ProseField from './ProseField.svelte';
 	import CardControls from './CardControls.svelte';
 	import DiagnosticList from './DiagnosticList.svelte';
@@ -72,15 +72,7 @@
 		leaves
 	}: Props = $props();
 
-	// Local title reconcile (external change only), like the scalar controls.
-	// svelte-ignore state_referenced_locally
-	let localTitle = $state(card.titleOverride);
-	$effect(() => {
-		const incoming = card.titleOverride;
-		untrack(() => {
-			if (incoming !== localTitle) localTitle = incoming;
-		});
-	});
+	let localTitle = $derived(card.titleOverride);
 
 	// The pre-edit value Escape rolls back to; the rename itself stays live on input.
 	let titleAtFocus = '';
@@ -208,10 +200,8 @@
  ancestor and nothing else marks the box its guidance belongs in. -->
 <section
 	bind:this={el}
-	class="qm-card"
+	class={['qm-card', { 'qm-main': card.isMain, 'qm-unschemable': card.unschemable }]}
 	data-qm-card
-	class:qm-main={card.isMain}
-	class:qm-unschemable={card.unschemable}
 >
 	{#if card.unschemable}
 		{@render recoveryShell()}
@@ -252,9 +242,7 @@
 		<div class="qm-card-body">
 			{#if hasMeta}
 				<div
-					class="qm-card-meta"
-					class:qm-meta-top={!card.isMain}
-					class:qm-meta-bottom={card.hasBody}
+					class={['qm-card-meta', { 'qm-meta-top': !card.isMain, 'qm-meta-bottom': card.hasBody }]}
 				>
 					{#each ungrouped as section (section.group ?? '_ungrouped')}
 						<div class="qm-section">
@@ -265,26 +253,42 @@
 					<!-- One open at a time. Rendered only when a card has groups, so an empty
 				     accordion does not stand a gap under the ungrouped fields. -->
 					{#if grouped.length}
-						<div class="qm-groups" class:qm-instant={!animate}>
+						<div class={['qm-groups', { 'qm-instant': !animate }]}>
 							{#each grouped as section (section.group)}
 								{@const group = section.group as string}
 								{@const isOpen = expanded === group}
 								{@const panelId = ops.panelId(group)}
-								<div class="qm-group" class:qm-open={isOpen}>
-									<button
-										type="button"
-										class="qm-group-header"
-										bind:this={headers[group]}
-										aria-expanded={isOpen}
-										aria-controls={panelId}
-										onclick={() => toggleGroup(group)}
-									>
-										<Icon
-											name="chevron-right"
-											class="qm-group-chevron"
-											size={CHEVRON}
-										/>{section.label}
-									</button>
+								{@const headIds = section.head ? ops.domIds(section.head.name) : undefined}
+								{@const headHint = section.head?.description}
+								<div class={['qm-group', { 'qm-open': isOpen }]}>
+									<!-- A flat field alone in its section is named by the header, which
+								     takes its label id and parks its description: the field draws no
+								     label of its own to say the section's name twice. -->
+									<div class="qm-group-head">
+										<button
+											type="button"
+											class="qm-group-header"
+											id={headIds?.label}
+											bind:this={headers[group]}
+											aria-expanded={isOpen}
+											aria-controls={panelId}
+											onclick={() => toggleGroup(group)}
+										>
+											<Icon
+												name="chevron-right"
+												class="qm-group-chevron"
+												size={CHEVRON}
+											/>{section.label}
+										</button>
+										{#if headIds && headHint}
+											<FieldHint
+												description={headHint}
+												label={section.label}
+												describedBy={headIds.description}
+											/>
+											<span class="qm-visually-hidden" id={headIds.description}>{headHint}</span>
+										{/if}
+									</div>
 									<!-- The panel is clipped, not unmounted, so without `inert` every field
 								     in a hidden section keeps its place in the tab order and in the a11y
 								     tree, under a header announcing `aria-expanded="false"`. -->
@@ -295,7 +299,7 @@
 										bind:this={panels[group]}
 									>
 										<div class="qm-group-panel-inner">
-											{@render sectionFields(section.fields)}
+											{@render sectionFields(section.fields, section.head)}
 										</div>
 									</div>
 								</div>
@@ -332,7 +336,7 @@
 	{/if}
 </section>
 
-{#snippet sectionFields(fields: FieldModel[])}
+{#snippet sectionFields(fields: FieldModel[], head?: FieldModel)}
 	<div class="qm-fields qm-tracks">
 		{#each placeFields(fields) as { field: f, span } (mountKey(f.name, f.schema))}
 			<Field
@@ -354,6 +358,7 @@
 				{onError}
 				{leaves}
 				diagnostics={ops.diagFor(f.name)}
+				headed={f === head}
 			/>
 		{/each}
 	</div>
@@ -591,7 +596,8 @@
 		display: grid;
 		grid-template-columns: repeat(var(--cols), 1fr);
 		column-gap: var(--_qm-space-2);
-		row-gap: var(--_qm-space-3);
+		--row-gap: var(--_qm-space-3);
+		row-gap: var(--row-gap);
 	}
 	/* The nesting vertical, one `--_qm-nest` in from the card's edge with the panel's
 	 fields the same rung off it (ARCHITECTURE §"A plane is a tone"). `--_qm-border` and
@@ -680,6 +686,30 @@
 		text-align: left;
 		transition: color var(--_qm-duration-fast) var(--_qm-ease-reverse);
 	}
+	/* The header row: the press target, and beside it the guidance marker a headed
+	 section carries (`FieldHint`), which is its own control and so not inside the
+	 button. Positioned for the reason the header is, the row being the box that
+	 stands in the band. */
+	.qm-group-head {
+		position: relative;
+		display: flex;
+		align-items: center;
+		gap: var(--_qm-space);
+	}
+	.qm-group-head > .qm-group-header {
+		flex: 1;
+		min-width: 0;
+	}
+	/* The parked description: `FieldLabel`'s recipe, for the one description a
+	 header rather than a label parks. */
+	.qm-visually-hidden {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+	}
 	.qm-group-header :global(.qm-group-chevron) {
 		flex-shrink: 0;
 		display: block;

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

@@ -1,4 +1,3 @@
-import './controls.css';
 interface Props {
     isFirst: boolean;
     isLast: boolean;

package/dist/visual/DateField.svelte

@@ -25,9 +25,9 @@
  values are data, not input: `parseDate` throws on anything malformed, so a bad
  string degrades to an empty field rather than taking the editor down with it.
 
- `syncedLocal` reconciles by identity, so the local must hold the string, not the
- parsed value: a fresh `CalendarDate` is never `===` the last one, which would
- make every reconcile fire and re-render all seven segments on each commit.
+ The local is a `$derived`, which compares by identity, so it holds the string, not
+ the parsed value: a fresh `CalendarDate` is never `===` the last one, so the
+ re-derivation each commit causes would re-render all seven segments.
 
  The ghost is the default's digits, not a format hint. An unset field
  carrying a `default:` prints the default's digits in the segments at the default
@@ -51,7 +51,6 @@
 	import { getLocalTimeZone, parseDate, today, type DateValue } from '@internationalized/date';
 	import Icon from './icons/Icon.svelte';
 	import { wording } from './strings.js';
-	import { syncedLocal } from './synced.svelte.js';
 	import './controls.css';
 
 	const t = wording();
@@ -109,31 +108,29 @@
 
 	const fallbackDate = $derived(toDateValue(fallback?.slice(0, 10) ?? ''));
 	/** The default is the primitive's value: from entering an unset field until an
-	 *  edit, a cleared segment or leaving. Part of the projection, so a reconcile
+	 *  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. */
 	let seat = $state(false);
-	// Local value synced to `value` as a string (see the identity note above);
-	// own-edits stay local, only an external change reconciles back in. Driven
-	// controlled (`value` + `onValueChange`, never `bind:`) so reconciliation stays
-	// the package's.
-	const local = syncedLocal(
-		() => value?.slice(0, 10) ?? (seat && fallbackDate ? fallbackDate.toString() : '')
+	// Driven controlled (`value` + `onValueChange`, never `bind:`) so reconciliation
+	// stays the package's.
+	let local = $derived(
+		value?.slice(0, 10) ?? (seat && fallbackDate ? fallbackDate.toString() : '')
 	);
-	const parsed = $derived(toDateValue(local.value));
+	const parsed = $derived(toDateValue(local));
 	// The date the empty segments ghost, or undefined when there is nothing to ghost:
 	// the field is unset and the default has a date form. A non-blank local that
 	// fails to parse is AUTHORED-but-malformed, which the empty field states
 	// honestly: the ghost would claim it unset. Held as the parsed value rather than
 	// a boolean so the substitution below narrows on the one fact it needs.
-	const ghost = $derived(local.value === '' ? fallbackDate : undefined);
-	const seated = $derived(value == null && seat && local.value !== '');
+	const ghost = $derived(local === '' ? fallbackDate : undefined);
+	const seated = $derived(value == null && seat && local !== '');
 	/** Who put `today` here, while the field follows the render date. */
 	const follows = $derived(
-		local.value === TODAY ? 'authored' : value == null && fallback === TODAY ? 'default' : undefined
+		local === TODAY ? 'authored' : value == null && fallback === TODAY ? 'default' : undefined
 	);
 
 	function write(next: string): void {
-		local.value = next;
+		local = next;
 		seat = false;
 		onCommit(next);
 	}
@@ -207,7 +204,7 @@
 			// seated default or `today` would write it.
 			const next = d?.toString() ?? '';
 			if (next === (parsed?.toString() ?? '')) return;
-			local.value = next;
+			local = next;
 			if (!d) seat = false;
 			onCommit(d?.toString());
 		}}

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

@@ -1,4 +1,3 @@
-import './controls.css';
 interface Props {
     value: string | undefined;
     /** The declared `default:` (`YYYY-MM-DD` or `today`): parsed for display only,

package/dist/visual/EnumField.svelte

@@ -15,7 +15,6 @@
 <script lang="ts">
 	import { Select } from 'bits-ui';
 	import Icon from './icons/Icon.svelte';
-	import { syncedLocal } from './synced.svelte.js';
 	import { wording } from './strings.js';
 	import './controls.css';
 
@@ -67,23 +66,21 @@
 	// the like), so it never collides with a real option.
 	const UNSET = '__qm_unset__';
 
-	// Local selection synced to `value` (sentinel when unauthored); own-picks stay
-	// local, only an external change reconciles back in (see `syncedLocal`). Driven
-	// controlled (`value` + `onValueChange`, never `bind:`) so reconciliation stays
-	// the package's rather than the primitive's.
-	const local = syncedLocal(() => value ?? UNSET);
+	// Driven controlled (`value` + `onValueChange`, never `bind:`) so reconciliation
+	// stays the package's rather than the primitive's.
+	let local = $derived(value ?? UNSET);
 
 	/** The blank has no glyph of its own: the quill's `ui.blank_title` stands in for
 	 * it, else an em dash. */
 	const dash = (v: string | undefined) => v || blankTitle || '—';
 
-	const unset = $derived(local.value === UNSET);
+	const unset = $derived(local === UNSET);
 	/** The ghost is a member the render prints, rather than a word for the blank or for
 	 *  `none`: it draws at the default rung (theme.css). */
 	const ghostsMember = $derived(!optional && !!fallback);
 	const ghostText = $derived(optional ? t.strings.optionalGhost : dash(fallback));
 	/** What the closed trigger shows: the pick, or the ghosted default while unset. */
-	const shown = $derived(unset ? ghostText : dash(local.value));
+	const shown = $derived(unset ? ghostText : dash(local));
 
 	/** The root to portal into: `document.body` would escape the consumer's dials
 	 * along with the editor's subtree. `undefined` falls back to bits-ui's default. */
@@ -99,10 +96,10 @@
 	<Select.Root
 		type="single"
 		allowDeselect={false}
-		value={local.value}
+		value={local}
 		onValueChange={(v) => {
 			if (v == null) return;
-			local.value = v;
+			local = v;
 			// Sentinel → unset (parent `removeField`, default renders); any real pick
 			// (incl. the default value) → a genuine write.
 			onCommit(v === UNSET ? undefined : v);
@@ -152,12 +149,12 @@
 						     policy when it is the one selected: a listbox whose selected value
 						     has no row shows nothing for what the document says, and offers none
 						     for the primitive to mark, type-ahead to, or key onto
-						     (VISUAL_EDITOR §"Enum policy"). Off `local.value`, not `value`: the
+						     (VISUAL_EDITOR §"Enum policy"). Off `local`, not `value`: the
 						     row that exists is the row the control has selected, through the
 						     window where an own pick has not reconciled back. -->
 						{#each values as v (v)}
 							{@const allowed = optionAllowed?.(v) !== false}
-							{#if allowed || enumDisallowed === 'disable' || v === local.value}
+							{#if allowed || enumDisallowed === 'disable' || v === local}
 								<Select.Item
 									class="qm-menu-item qm-select-item"
 									value={v}

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

@@ -1,4 +1,3 @@
-import './controls.css';
 interface Props {
     value: string | undefined;
     values: string[];

package/dist/visual/Field.svelte

@@ -33,10 +33,12 @@
 		VARIANT_DISCRIMINANT,
 		arrayLayout,
 		baseType,
+		flatObject,
 		ghostDefault,
 		isContainer,
 		optionalCell,
 		printedText,
+		renderedBoolean,
 		stringifyGhost,
 		titleText
 	} from './structure.js';
@@ -88,6 +90,9 @@
 		 *  landing handle here, a prose leaf its controller from inside `ProseField`. */
 		leaves?: LeafRegistry;
 		diagnostics?: Diagnostic[];
+		/** The section's header names this field and parks its description, under this
+		 * field's own label and description ids ({@link GroupSection.head}). */
+		headed?: boolean;
 	}
 	let {
 		field,
@@ -107,7 +112,8 @@
 		onChange,
 		onError,
 		leaves,
-		diagnostics
+		diagnostics,
+		headed = false
 	}: Props = $props();
 
 	const t = wording();
@@ -157,6 +163,7 @@
 	const describedBy = $derived(field.description ? domIds.description : undefined);
 	// Two controls own their label row, the add chip and the held count sharing it.
 	const ownsLabel = $derived(field.control === 'array' || field.control === 'matrix');
+	const flat = $derived(flatObject(field.schema));
 
 	// A container walks its diagnostics down to the cell each names and draws the rest
 	// at its own foot (`diagnostics.ts`); every other control draws them here, under
@@ -229,12 +236,10 @@
 	 * an address to name. `el` is the field-wide box, which a landing at depth does not
 	 * wash: that lane hands back its own row (`leaves.ts`).
 	 */
-	let controlEl = $state<HTMLElement | undefined>();
-	$effect(() => {
-		if (field.control === 'prose' || !controlEl || !leaves) return;
+	function registerControl(wrapper: HTMLElement): (() => void) | undefined {
+		if (field.control === 'prose' || !leaves) return;
 		const key = leafKey;
 		const registry = leaves;
-		const wrapper = controlEl;
 		registry.registerControl(key, {
 			focus: focusControl,
 			focusPath: isContainer(field.control) ? focusPath : undefined,
@@ -243,7 +248,7 @@
 			}
 		});
 		return () => registry.unregisterControl(key);
-	});
+	}
 
 	/**
 	 * A form control has no controller to report its focus through, so the wrapper
@@ -256,8 +261,8 @@
 	const reportFocus = $derived(field.control === 'prose' ? undefined : () => onFocus?.(addr));
 </script>
 
-<div class="qm-field" class:cell={span === 'cell'}>
-	{#if !ownsLabel}
+<div class={['qm-field', { cell: span === 'cell' }]}>
+	{#if !ownsLabel && !headed}
 		<FieldLabel
 			label={field.label}
 			controlId={labelable ? domIds.control : undefined}
@@ -273,7 +278,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" bind:this={controlEl} onfocusin={reportFocus}>
+		<div class="qm-field-control" {@attach registerControl} onfocusin={reportFocus}>
 			{#if field.control === 'prose'}
 				<ProseField
 					{quill}
@@ -336,7 +341,7 @@
 				/>
 			{:else if field.control === 'boolean'}
 				<BooleanField
-					value={value as boolean | undefined}
+					value={renderedBoolean(value)}
 					fallback={ghost as boolean | undefined}
 					{optional}
 					id={domIds.control}
@@ -376,6 +381,7 @@
 					bind:this={objectEl}
 					value={value as Record<string, unknown> | undefined}
 					properties={field.schema.properties}
+					{flat}
 					label={field.label}
 					idBase={domIds.control}
 					labelledBy={domIds.label}
@@ -394,6 +400,7 @@
 					labelId={domIds.label}
 					descriptionId={domIds.description}
 					idBase={domIds.control}
+					listKey={leafKey}
 					{contentAt}
 					onCommit={onCommitScalar}
 					diagnostics={deep}

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

@@ -35,6 +35,9 @@ interface Props {
      *  landing handle here, a prose leaf its controller from inside `ProseField`. */
     leaves?: LeafRegistry;
     diagnostics?: Diagnostic[];
+    /** The section's header names this field and parks its description, under this
+     * field's own label and description ids ({@link GroupSection.head}). */
+    headed?: boolean;
 }
 declare const Field: import("svelte").Component<Props, {}, "">;
 type Field = ReturnType<typeof Field>;

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

@@ -1,4 +1,3 @@
-import './controls.css';
 interface Props {
     description: string;
     /** The field's label: the trigger's own name, so 30 info buttons on a card

package/dist/visual/FieldLabel.svelte

@@ -65,8 +65,7 @@
 	     label is not a tab stop, and the control it hands focus to is already the
 	     keyboard's own way in. -->
 	<label
-		class="qm-field-label"
-		class:targeted={controlId != null || onActivate != null}
+		class={['qm-field-label', { targeted: controlId != null || onActivate != null }]}
 		{id}
 		for={controlId}
 		onclick={onActivate}

package/dist/visual/FormatPopover.svelte

@@ -52,6 +52,7 @@
  selection the command is supposed to act on.
 -->
 <script lang="ts">
+	import { onDestroy } from 'svelte';
 	import { wording } from './strings.js';
 
 	// The surface's words, ambient from the editor root; the package's English
@@ -105,7 +106,6 @@
 	/** Whether the selection carried a link when the prompt was raised. */
 	let linkPresent = $state(false);
 	let linkValue = $state('');
-	let linkInputEl = $state<HTMLInputElement | undefined>(undefined);
 	let contentEl = $state<HTMLElement | undefined>(undefined);
 	/** The root to portal into: `document.body` escapes the editor's subtree and
 	 * the consumer's dials with it, so a pane-scoped palette misses this surface.
@@ -212,25 +212,11 @@
 		deferredSync();
 	}
 
-	$effect(() => {
-		document.addEventListener('selectionchange', deferredSync);
-		document.addEventListener('focusout', deferredSync);
-		// Capture, so the gesture is seen whatever a view in the middle of it does with
-		// the event. `pointercancel` is the release a gesture the browser takes over gets.
-		document.addEventListener('pointerdown', onPointerDown, true);
-		document.addEventListener('pointerup', onPointerUp, true);
-		document.addEventListener('pointercancel', onPointerUp, true);
-		return () => {
-			document.removeEventListener('selectionchange', deferredSync);
-			document.removeEventListener('focusout', deferredSync);
-			document.removeEventListener('pointerdown', onPointerDown, true);
-			document.removeEventListener('pointerup', onPointerUp, true);
-			document.removeEventListener('pointercancel', onPointerUp, true);
-			// A burst-coalescing rAF may still be in flight at teardown; cancel it so
-			// `sync()` never runs against the destroyed component.
-			if (pending) cancelAnimationFrame(rafHandle);
-			pending = false;
-		};
+	// A burst-coalescing rAF may still be in flight at teardown; cancel it so
+	// `sync()` never runs against the destroyed component.
+	onDestroy(() => {
+		if (pending) cancelAnimationFrame(rafHandle);
+		pending = false;
 	});
 
 	// Any close path that bypasses `sync` (e.g. Escape while the link input holds
@@ -245,12 +231,10 @@
 	// surface already open, so without this the URL is typed into the document.
 	// Selected rather than merely focused, the input arriving seeded and replacing
 	// that value being what the prompt is usually raised for.
-	$effect(() => {
-		if (linkPromptOpen && linkInputEl) {
-			linkInputEl.focus();
-			linkInputEl.select();
-		}
-	});
+	function focusPrompt(input: HTMLInputElement): void {
+		input.focus();
+		input.select();
+	}
 
 	/** Swallow the button's mousedown so focus/selection never leave the leaf. */
 	function keepFocus(e: MouseEvent): void {
@@ -338,6 +322,17 @@
 	}
 </script>
 
+<!-- The pointer handlers capture, so the gesture is seen whatever a view in the middle of
+     it does with the event. `pointercancel` is the release a gesture the browser takes
+     over gets. -->
+<svelte:document
+	onselectionchange={deferredSync}
+	onfocusout={deferredSync}
+	onpointerdowncapture={onPointerDown}
+	onpointerupcapture={onPointerUp}
+	onpointercancelcapture={onPointerUp}
+/>
+
 <Popover.Root bind:open>
 	<Popover.Portal to={portalTarget}>
 		<!-- A flip is measured against the root the surface portals into, which is the box
@@ -383,7 +378,7 @@
 								}}
 							>
 								<input
-									bind:this={linkInputEl}
+									{@attach focusPrompt}
 									class="qm-link-input"
 									type="text"
 									placeholder={t.strings.linkPlaceholder}

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

@@ -1,5 +1,4 @@
 import { type FieldController } from '../core/codec/index.js';
-import './controls.css';
 interface Props {
     /** The observation seam VisualEditor exposes over its `leaves` registry. */
     getActiveLeaf: () => FieldController | undefined;