@quillmark/svelte 0.1.0 → 0.2.0

package/dist/preview/geometry.js

@@ -1,3 +1,23 @@
+/**
+ * An address's boxes: `fieldBoxes`'s union, else its own `regions()` rects, else the
+ * rects of everything UNDER it. The one rule the overlay and the scroll both read, so
+ * an address `regions()` names never draws nothing (PREVIEW.md §"Three
+ * responsibilities").
+ *
+ * `fieldBoxes` answers `[]` for a scalar reference the plate places without tracking
+ * its content and for a `richtext[]` element; runtime.d.ts says what such a field's
+ * box is, a single `regions()` rect. The third rung is that sentence one granularity
+ * down — an array's ink is its elements' — and is a fallback, not a union, so an
+ * address with rects of its own never also draws its children's. The `.` keeps the
+ * prefix a path boundary: `main.references` matches `main.references.0`, not
+ * `main.references_note`.
+ */
+export function boxesForField(field, boxes, regions) {
+    if (boxes.length)
+        return boxes;
+    const own = regions.filter((r) => r.field === field);
+    return own.length ? own : regions.filter((r) => r.field.startsWith(`${field}.`));
+}
 /**
  * Forward: a PDF-pt rect -> CSS % of the page box. Percent positioning tracks
  * the page's displayed size across DPR and container resize for free; this is

package/dist/preview/index.d.ts

@@ -1,3 +1,4 @@
+import '../core/theme.css';
 export { createPreview } from './controller.js';
 export type { PreviewOptions, PreviewController } from './controller.js';
 export { default as Preview } from './Preview.svelte';

package/dist/preview/index.js

@@ -5,6 +5,13 @@
 // (the codec, the VisualEditor) so a `@quillmark/preview` promotion stays a
 // re-export, not a refactor: it may reach `/core` (the shared WASM boundary) and
 // nothing else. Enforced by `check:deps`, which walks the subpath's import graph.
+// The theme derivation, which the page slots and the overlay read through `var()`.
+// Imported at the BARREL because a subpath is what a consumer gets: this surface
+// reaches modules inside `core/` and never its entry, so a sheet hanging off that
+// entry arrives only for a consumer importing `/core` for some other reason. The
+// sheet rather than the entry, because the barrel needs the derivation and not
+// `init`. `check:deps` (rule 4) walks this file's own graph and holds the reach.
+import '../core/theme.css';
 export { createPreview } from './controller.js';
 export { default as Preview } from './Preview.svelte';
 // What the preview SAYS when there is nothing to paint. Keyed and partial; the

package/dist/preview/overlay.d.ts

@@ -3,7 +3,8 @@ import type { PageSlot } from './paint.js';
 export interface OverlayController {
     /** Re-read geometry and rebuild every box; call after a layout-affecting refresh. */
     refresh(): void;
-    /** Bloom `field`'s boxes: transient, and a no-op when `field` is already the marked one. */
+    /** Bloom the boxes at `field` AND under it: transient, and a no-op when `field`
+     *  is already the marked one. */
     flashField(field: string): void;
     destroy(): void;
 }

package/dist/preview/overlay.js

@@ -1,5 +1,5 @@
 import { bloom, bloomTiming, primeWash } from '../core/bloom.js';
-import { rectToPercent, applyPercentRect } from './geometry.js';
+import { boxesForField, rectToPercent, applyPercentRect } from './geometry.js';
 const FIELD_ATTR = 'data-qm-field';
 export function createOverlay(session, slots) {
     const layers = slots.map((slot) => {
@@ -20,32 +20,47 @@ export function createOverlay(session, slots) {
     let flash;
     /** field → its boxes, rebuilt with them. The bloom's only lookup. */
     let byField = new Map();
+    // The boxes a flash covers: the address's own, plus every one UNDER it, since the
+    // boxes are keyed as `regions()` names them (`main.references.0`) and an
+    // editor-side signal names the declared field (`main.references`). Resolved per
+    // apply rather than at `flashField`, so a rebuild picks up boxes the recompile
+    // moved or added.
+    function flashed(field) {
+        const els = [];
+        for (const [key, group] of byField) {
+            if (key === field || key.startsWith(`${field}.`))
+                els.push(...group);
+        }
+        return els;
+    }
     // Start or RESUME the bloom on whatever boxes exist for it now: one path, because
     // starting is resuming at ~0. A field surfaces several boxes and they share
     // `startedAt`, so they bloom in step rather than shimmering unevenly.
     function applyFlash() {
-        const els = flash && byField.get(flash.field);
-        if (!flash || !els?.length)
+        if (!flash)
+            return;
+        const els = flashed(flash.field);
+        if (!els.length)
             return;
         const elapsed = performance.now() - flash.startedAt;
         const timing = bloomTiming(els[0]);
         for (const el of els)
             bloom(el, elapsed, timing);
     }
-    // Field names come from `regions()` (the only session query that enumerates
-    // them; Preview carries no schema); the boxes themselves come from
-    // `fieldBoxes(field)`, which is content-only and `[]` for a scalar-reference
-    // or widget field, so a nameless-of-content field contributes no boxes.
+    // Field names come from `regions()` (the only session query that enumerates them;
+    // Preview carries no schema); the rects from `boxesForField`, whose fallback is
+    // what makes every address `regions()` names draw.
     function build() {
         for (const layer of layers)
             layer.replaceChildren();
         byField = new Map();
+        const regions = session.regions();
         const fields = new Set();
-        for (const region of session.regions())
+        for (const region of regions)
             fields.add(region.field);
         for (const field of fields) {
             const els = [];
-            for (const box of session.fieldBoxes(field)) {
+            for (const box of boxesForField(field, session.fieldBoxes(field), regions)) {
                 const layer = layers[box.page];
                 const slot = slots[box.page];
                 if (!layer || !slot)

package/dist/preview/paint.js

@@ -43,6 +43,10 @@ onPaintError) {
         // the paper.
         const el = document.createElement('div');
         el.className = 'qm-page';
+        // The page's index, in the DOM. `pageByEl` is this module's and a consumer
+        // drawing an overlay of its own needs the number: position among siblings is
+        // the only handle without it, which is right today and is not a contract.
+        el.dataset.page = String(page);
         Object.assign(el.style, {
             position: 'relative',
             boxSizing: 'border-box',

package/dist/visual/ArrayField.svelte

@@ -55,20 +55,9 @@
 		/** Where the description parks, for the group's `aria-describedby`. */
 		descriptionId?: string;
 		onCommit: (arr: unknown[]) => void;
-		/** A prose element gained focus: joins the field in the focus federation. */
-		onFocusEl?: () => void;
 	}
-	let {
-		value,
-		items,
-		label,
-		required,
-		description,
-		labelId,
-		descriptionId,
-		onCommit,
-		onFocusEl
-	}: Props = $props();
+	let { value, items, label, required, description, labelId, descriptionId, onCommit }: Props =
+		$props();
 
 	// The ELEMENT control is the item schema's own; an array declaring no `items`
 	// has text elements.
@@ -102,7 +91,14 @@
 	// Every path that drops an id deletes its entry: `bind:this` teardown nulls the
 	// VALUE on unmount and leaves the key, so a card that outlives its elements
 	// accumulates one dead key per element ever created.
-	const els: Record<string, { focus: () => void } | undefined> = {};
+	//
+	// `$state` for the BINDING's sake, not this component's: nothing here reads `els`
+	// reactively (every read is inside an event handler or a post-flush focus hop), but
+	// `bind:this` into a property of a plain object is a write Svelte cannot track, and
+	// it says so once per element per render. Thirteen lines on one memo's first paint,
+	// in the console a consumer is reading to find its own defects. Same shape
+	// {@link Card} keeps its header/panel refs in.
+	const els: Record<string, { focus: () => void } | undefined> = $state({});
 	let addEl: HTMLButtonElement | undefined = $state();
 	let rootEl: HTMLElement | undefined = $state();
 
@@ -151,10 +147,11 @@
 		// key does: the button under the pointer is part of what it destroys.
 		focusAfterFlush(next[Math.max(k - 1, 0)]);
 	}
-	/** A label click on an array, resolved rather than left to dangle: the FIRST
-	 * element, or the add affordance when the list is empty; which is then the only
-	 * thing there is to land on, and the next thing the user wants anyway. */
-	function activate(): void {
+	/** Take the caret: the FIRST element, or the add affordance when the list is empty;
+	 * which is then the only thing there is to land on, and the next thing the user
+	 * wants anyway. Reached by a label click and by the editor's landing verbs, which
+	 * ask one function so they cannot disagree (`Field`, `leaves.ts`). */
+	export function focus(): void {
 		if (ids.length === 0) return void addEl?.focus();
 		const first = els[ids[0]];
 		if (first) return first.focus();
@@ -162,6 +159,16 @@
 		// nothing about focusing it that the DOM does not already know.
 		rootEl?.querySelector<HTMLTextAreaElement>('.qm-array-row textarea')?.focus();
 	}
+	/** Take the caret to element `k`: what a landing on an element ADDRESS resolves to
+	 * (`leaves.ts`). The index resolves to the element's session id here, at the call,
+	 * never carried as one — an index is stale the moment anything above it splices.
+	 * Past the live list it falls back to {@link focus}: the field is right and the row
+	 * is gone, which is a landing off a compile the document has moved past. */
+	export function focusElement(k: number): void {
+		const el = els[ids[k]];
+		if (el) el.focus();
+		else focus();
+	}
 	/** Focus element `id` after the flush, never in the same tick: a mutation commits
 	 * the array BY VALUE, so the parent re-derives and the row does not exist until
 	 * then. `undefined` is the empty list: the add affordance.
@@ -216,7 +223,7 @@
 				{label}
 				id={labelId}
 				{descriptionId}
-				onActivate={activate}
+				onActivate={focus}
 				{required}
 				{description}
 			/>
@@ -237,7 +244,6 @@
 					label={label != null ? `${label} ${k + 1}` : undefined}
 					onChange={(rt) => commitElement(k, rt)}
 					onKey={(e) => onElementKey(e, k)}
-					{onFocusEl}
 				/>
 			{:else if control === 'object'}
 				<textarea

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

@@ -16,9 +16,10 @@ interface Props {
     /** Where the description parks, for the group's `aria-describedby`. */
     descriptionId?: string;
     onCommit: (arr: unknown[]) => void;
-    /** A prose element gained focus: joins the field in the focus federation. */
-    onFocusEl?: () => void;
 }
-declare const ArrayField: import("svelte").Component<Props, {}, "">;
+declare const ArrayField: import("svelte").Component<Props, {
+    focus: () => void;
+    focusElement: (k: number) => void;
+}, "">;
 type ArrayField = ReturnType<typeof ArrayField>;
 export default ArrayField;

package/dist/visual/Card.svelte

@@ -16,7 +16,7 @@
 	import Icon from './icons/Icon.svelte';
 	import type { Document, Quill, Addr, Diagnostic } from '@quillmark/wasm';
 	import type { EditorErrorHandler } from '../core/errors.js';
-	import type { FieldController } from '../core/codec/index.js';
+	import type { LeafRegistry } from './leaves.js';
 	import type { CardModel, FieldModel } from './structure.js';
 	import { placeFields, humanize, initialExpandedGroup } from './structure.js';
 	import type { FieldDomIds } from './domid.js';
@@ -51,12 +51,17 @@
 		isLast: boolean;
 		kinds: string[];
 		ops: CardOps;
+		/** How an option `ops.enumAllowed` refuses draws. Nothing about it is per-card,
+		 *  so it sits beside the bundle rather than in it. */
+		enumDisallowed?: 'hide' | 'disable';
 		onFocus?: (addr: Addr) => void;
 		onCaretMove?: (addr: Addr, pos: number) => void;
 		onChange?: (addr: Addr) => void;
 		onError?: EditorErrorHandler;
-		register?: (key: string, controller: FieldController) => void;
-		unregister?: (key: string) => void;
+		/** The editor's leaf registry (`leaves.ts`): every field in this card registers
+		 *  its landing handle, which is what the editor's `focusField`/`setCaret`
+		 *  resolve a `DocPath` to. */
+		leaves?: LeafRegistry;
 	}
 	let {
 		card,
@@ -67,12 +72,12 @@
 		isLast,
 		kinds,
 		ops,
+		enumDisallowed,
 		onFocus,
 		onCaretMove,
 		onChange,
 		onError,
-		register,
-		unregister
+		leaves
 	}: Props = $props();
 
 	// Local title reconcile (external change only), like the scalar controls.
@@ -229,10 +234,9 @@
 				     not a persistent box. `data-value` falls back to the
 				     placeholder so an empty title still reserves its resolved-title width. -->
 					<span class="qm-card-title-sizer" data-value={localTitle || card.titlePlaceholder}>
-						<!-- `qm-focus-ring` is what the box used to do: it was this control's ONLY
-					     focus indicator, and the ink step that replaced it cannot be one, since
-					     hover already takes that step. `:focus-visible`, so a press enters the
-					     edit unringed while a tab into it draws one. -->
+						<!-- `qm-focus-ring` is this control's ONLY focus indicator: the ink step
+					     cannot be one, since hover already takes that step. `:focus-visible`, so
+					     a press enters the edit unringed while a tab into it draws one. -->
 						<input
 							class="qm-card-title qm-focus-ring"
 							value={localTitle}
@@ -361,8 +365,7 @@
 						{onCaretMove}
 						{onChange}
 						{onError}
-						{register}
-						{unregister}
+						{leaves}
 					/>
 					<DiagnosticList diagnostics={ops.diagFor(undefined)} />
 				</div>
@@ -385,17 +388,17 @@
 				provenance={card.provenance[f.name]}
 				{doc}
 				{quill}
-				proseAddr={ops.makeAddr(f.name)}
+				addr={ops.makeAddr(f.name)}
 				leafKey={ops.leafKey(f.name)}
 				domIds={ops.domIds(f.name)}
 				onCommitScalar={(v) => ops.commit(f.name, v)}
 				optionAllowed={(v) => ops.enumAllowed(f.name, v)}
+				{enumDisallowed}
 				{onFocus}
 				{onCaretMove}
 				{onChange}
 				{onError}
-				{register}
-				{unregister}
+				{leaves}
 				diagnostics={ops.diagFor(f.name)}
 			/>
 		{/each}
@@ -636,9 +639,8 @@
 	 The ACTION COLUMN is minted here and spent one level down, on the field
 	 (`Field.svelte` holds why it is the field's inset and not this container's). It
 	 is declared on the query container because both of its consumers hang off one:
-	 the fields inside, and the capacity ramp below, which has to carry the column in
-	 its own arithmetic now that the query no longer reads a content box the
-	 reservation already narrowed. */
+	 the fields inside, and the capacity ramp below, which carries the column in its
+	 own arithmetic because the query reads a box the reservation has not narrowed. */
 	.qm-section,
 	.qm-group-panel-inner {
 		--action-col: calc(var(--_qm-tap-min) + var(--_qm-space-2));
@@ -741,10 +743,10 @@
 		padding: var(--_qm-space) 0 var(--_qm-space) var(--_qm-space);
 		font: inherit;
 		font-size: var(--_qm-text-label);
-		font-weight: var(--_qm-weight-soft);
+		font-weight: var(--_qm-weight-label);
 		line-height: var(--_qm-leading-tight);
 		cursor: pointer;
-		color: var(--_qm-ink-meta);
+		color: var(--_qm-ink-label);
 		text-align: left;
 		transition: color var(--_qm-duration-fast) var(--_qm-ease-reverse);
 	}

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

@@ -1,6 +1,6 @@
 import type { Document, Quill, Addr, Diagnostic } from '@quillmark/wasm';
 import type { EditorErrorHandler } from '../core/errors.js';
-import type { FieldController } from '../core/codec/index.js';
+import type { LeafRegistry } from './leaves.js';
 import type { CardModel } from './structure.js';
 import type { FieldDomIds } from './domid.js';
 /** The per-card operation bundle the VisualEditor builds (all resolve id→index lazily). */
@@ -28,12 +28,17 @@ interface Props {
     isLast: boolean;
     kinds: string[];
     ops: CardOps;
+    /** How an option `ops.enumAllowed` refuses draws. Nothing about it is per-card,
+     *  so it sits beside the bundle rather than in it. */
+    enumDisallowed?: 'hide' | 'disable';
     onFocus?: (addr: Addr) => void;
     onCaretMove?: (addr: Addr, pos: number) => void;
     onChange?: (addr: Addr) => void;
     onError?: EditorErrorHandler;
-    register?: (key: string, controller: FieldController) => void;
-    unregister?: (key: string) => void;
+    /** The editor's leaf registry (`leaves.ts`): every field in this card registers
+     *  its landing handle, which is what the editor's `focusField`/`setCaret`
+     *  resolve a `DocPath` to. */
+    leaves?: LeafRegistry;
 }
 declare const Card: import("svelte").Component<Props, {
     revealLeaf: (key: string) => void;

package/dist/visual/DiagnosticList.svelte

@@ -41,7 +41,7 @@
 		gap: var(--_qm-space-half);
 	}
 	.qm-diag-line {
-		font-size: var(--_qm-text-meta);
+		font-size: var(--_qm-text-label);
 		color: var(--_qm-warning);
 	}
 	.qm-diag-line[data-severity='error'] {

package/dist/visual/EnumField.svelte

@@ -34,13 +34,23 @@
 		/** The parked `description` (FieldLabel): announced after the name. */
 		describedBy?: string;
 		onCommit: (v: string | undefined) => void;
-		/** Consumer policy: `false` disables an option so it can't be picked.
-		 * A disallowed value already authored stays SELECTED and visible (disabled), never
-		 * stripped or mutated. The UNSET sentinel is exempt: clear-to-default always works. */
+		/** Consumer policy: `false` marks an option unavailable, so it can't be picked.
+		 * The UNSET sentinel is exempt: clear-to-default always works. */
 		optionAllowed?: (value: string) => boolean;
+		/** How a refused option draws: greyed and unpickable, or left out of the list. */
+		enumDisallowed?: 'hide' | 'disable';
 	}
-	let { value, values, fallback, label, id, describedBy, onCommit, optionAllowed }: Props =
-		$props();
+	let {
+		value,
+		values,
+		fallback,
+		label,
+		id,
+		describedBy,
+		onCommit,
+		optionAllowed,
+		enumDisallowed = 'disable'
+	}: Props = $props();
 
 	// The sentinel's option value: a namespaced marker that no schema-authored
 	// enum member would ever be (`values` are classification markings, seal ids, and
@@ -107,15 +117,25 @@
 						<Select.Item class="qm-menu-item qm-select-item" value={UNSET} label={ghostText}>
 							<span class="qm-select-ghost">{ghostText}</span>
 						</Select.Item>
+						<!-- A refused option still draws under `'disable'`, and under EITHER
+						     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
+						     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)}
-							<Select.Item
-								class="qm-menu-item qm-select-item"
-								value={v}
-								label={dash(v)}
-								disabled={optionAllowed?.(v) === false}
-							>
-								{dash(v)}
-							</Select.Item>
+							{@const allowed = optionAllowed?.(v) !== false}
+							{#if allowed || enumDisallowed === 'disable' || v === local.value}
+								<Select.Item
+									class="qm-menu-item qm-select-item"
+									value={v}
+									label={dash(v)}
+									disabled={!allowed}
+								>
+									{dash(v)}
+								</Select.Item>
+							{/if}
 						{/each}
 					</Select.Viewport>
 				</div>
@@ -158,7 +178,7 @@
 	.qm-select-content :global(.qm-select-item[data-selected]) {
 		font-weight: var(--_qm-weight-label);
 	}
-	/* Consumer policy: offered but unpickable, never hidden. */
+	/* Consumer policy, for a refused option the list still draws: offered, unpickable. */
 	.qm-select-content :global(.qm-select-item[data-disabled]) {
 		opacity: var(--_qm-opacity-muted);
 		cursor: default;

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

@@ -15,10 +15,11 @@ interface Props {
     /** The parked `description` (FieldLabel): announced after the name. */
     describedBy?: string;
     onCommit: (v: string | undefined) => void;
-    /** Consumer policy: `false` disables an option so it can't be picked.
-     * A disallowed value already authored stays SELECTED and visible (disabled), never
-     * stripped or mutated. The UNSET sentinel is exempt: clear-to-default always works. */
+    /** Consumer policy: `false` marks an option unavailable, so it can't be picked.
+     * The UNSET sentinel is exempt: clear-to-default always works. */
     optionAllowed?: (value: string) => boolean;
+    /** How a refused option draws: greyed and unpickable, or left out of the list. */
+    enumDisallowed?: 'hide' | 'disable';
 }
 declare const EnumField: import("svelte").Component<Props, {}, "">;
 type EnumField = ReturnType<typeof EnumField>;