@quillmark/svelte 0.6.0 → 0.7.1

package/dist/visual/ArrayField.svelte

@@ -3,7 +3,7 @@
  edit / add / remove rebuilds the whole array and hands it to the parent's typed
  `writer.set(field, wholeArray)` (arrays are not op-addressed). Element control
  by `items.type`: `richtext` / `plaintext` → a prose element
- ({@link ProseArrayElement}), `object` → a summary row that opens onto a subform,
+ ({@link ProseValue}), `object` → a summary row that opens onto a subform,
  everything else → a text input. The
  add affordance sits in the label header row (space-between with the field label);
  {@link Field} skips its own label for array controls and hands this component the
@@ -11,8 +11,8 @@
 
  An `object` element collapses: the row is its own summary — a box, titled by the
  element's first `string` cell — and opens onto {@link ObjectField}, one at a time.
- Stacking the subforms instead would nest a field one level past the depth the band
- draws, once per row. Opening is therefore part of a landing rather than something the
+ Stacking the subforms instead would nest a field one level past the depth the
+ subform's own vertical draws, once per row. Opening is therefore part of a landing rather than something the
  user does first: `focusElement` opens the row it is aimed at before it focuses.
 
  The remove is inside the element: a slab over the end of the element's own box, taking
@@ -38,14 +38,15 @@
 	// off-tree, so this component renders standalone too.
 	const t = wording();
 	import { onDestroy, tick } from 'svelte';
-	import type { Content, QuillFieldSchema } from '@quillmark/wasm';
+	import type { Content, PathStep, QuillFieldSchema } from '@quillmark/wasm';
 	import { emptyContent } from '../core/codec/index.js';
 	import { createLifespan } from '../core/teardown.js';
 	import { IdSeq, controlKind } from './structure.js';
+	import { holdInView } from './hold.js';
 	import Icon from './icons/Icon.svelte';
 	import TextField from './TextField.svelte';
 	import ObjectField from './ObjectField.svelte';
-	import ProseArrayElement from './ProseArrayElement.svelte';
+	import ProseValue from './ProseValue.svelte';
 	import FieldLabel from './FieldLabel.svelte';
 	import './controls.css';
 
@@ -72,12 +73,14 @@
 		 * properties' own names from, one `-e-<element id>` segment down, so each open
 		 * record's cells carry real `<label for>` pairs like every other control. */
 		idBase?: string;
-		/** Element `i`'s content, decoded by the boundary through the codec `items`
-		 * names (`Field`, `reader.getContentAt`). Asked only for a content-typed
-		 * element: on any other the read is not content and throws. `undefined` for a
-		 * row the stored value does not reach — a slot this control has spliced in and
-		 * whose commit has yet to land, or was refused. */
-		elementContent: (i: number) => Content | undefined;
+		/** The boundary's nested content read, rooted at this field: `path` is a
+		 * `PathStep[]` from the field to the leaf, so `[i]` is element `i` and
+		 * `[i, key]` a content cell of an `object` element's subform (`Field`,
+		 * `reader.getContentAt`). The codec is the leaf's own declared type's. Asked
+		 * only for a content-typed leaf: on any other the read is not content and
+		 * throws. `undefined` for a leaf the stored value does not reach — a slot this
+		 * control has spliced in and whose commit has yet to land, or was refused. */
+		contentAt: (path: PathStep[]) => Content | undefined;
 		onCommit: (arr: unknown[]) => void;
 	}
 	let {
@@ -89,13 +92,13 @@
 		labelId,
 		descriptionId,
 		idBase,
-		elementContent,
+		contentAt,
 		onCommit
 	}: Props = $props();
 
 	// The element control is the item schema's own, with no departure: a content-typed
 	// element mounts the prose leaf its scalar field mounts, reading through
-	// `elementContent` whatever the element rests as. An array declaring no `items`
+	// `contentAt` whatever the element rests as. An array declaring no `items`
 	// has text elements.
 	const control = $derived(items ? controlKind(items) : 'text');
 	const arr = $derived((value ?? []) as unknown[]);
@@ -121,7 +124,7 @@
 	// The focus targets, keyed by element ID rather than index: an index goes stale on
 	// the splice that focus is chasing. An element control exposes `focus()` because a
 	// text element and a prose element disagree on what focusing is: the difference
-	// is stated on `ProseArrayElement.focus`, which owns it.
+	// is stated on `ProseValue.focus`, which owns it.
 	//
 	// 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
@@ -166,8 +169,12 @@
 	function untitled(k: number): string {
 		return label != null ? t.strings.elementUntitled(label, k + 1) : String(k + 1);
 	}
-	function toggleRow(id: string): void {
-		openId = openId === id ? undefined : id;
+	/** The summary is the anchor: a row closing above it is what would carry it off the fold,
+	 *  and a row's subform hangs under its own summary (`hold.ts`). */
+	function toggleRow(id: string, summary: HTMLElement): void {
+		holdInView(summary, () => {
+			openId = openId === id ? undefined : id;
+		});
 	}
 
 	// The awaited flush below is the only work that outlives a gesture here, so the
@@ -365,7 +372,7 @@
 							type="button"
 							class="qm-control-box qm-focus-ring qm-element-summary"
 							aria-expanded={open}
-							onclick={() => toggleRow(id)}
+							onclick={(e) => toggleRow(id, e.currentTarget)}
 						>
 							<!-- Leading, and it rotates: trailing is the figure for pushing a new
 							     screen, where this unfolds in place. Same glyph, same rotation and
@@ -391,7 +398,7 @@
 							properties={items?.properties}
 							label={label != null ? `${label} ${k + 1}` : undefined}
 							idBase={idBase != null ? `${idBase}-e-${id}` : undefined}
-							edges="close"
+							contentAt={(path) => contentAt([k, ...path])}
 							onCommit={(obj) => commitElement(k, obj)}
 						/>
 					{/if}
@@ -399,9 +406,9 @@
 			{:else}
 				<div class="qm-array-row">
 					{#if control === 'prose'}
-						<ProseArrayElement
+						<ProseValue
 							bind:this={els[id]}
-							content={() => elementContent(k) ?? emptyContent()}
+							content={() => contentAt([k]) ?? emptyContent()}
 							plaintext={items?.type === 'plaintext'}
 							label={label != null ? `${label} ${k + 1}` : undefined}
 							onChange={(rt) => commitElement(k, rt)}
@@ -517,9 +524,9 @@
 	/* ── An object element ──────────────────────────────────────────────────────
 	 The row is a summary and the subform hangs under it. `row-gap` rather than a
 	 margin on the subform, because the distance between a control and what it has
-	 unfolded belongs to the thing stacking them: the variant field spends its own
-	 `gap` on exactly this and `ObjectField` therefore opens flush, carrying no
-	 leading space of its own for a caller to cancel. */
+	 unfolded belongs to the thing stacking them: the variant field spends its own `gap` on
+	 exactly this, and what `ObjectField` adds is the cap on its own stroke, equal at both
+	 of its ends. */
 	.qm-element {
 		row-gap: var(--_qm-space-2);
 	}

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

@@ -1,4 +1,4 @@
-import type { Content, QuillFieldSchema } from '@quillmark/wasm';
+import type { Content, PathStep, QuillFieldSchema } from '@quillmark/wasm';
 import './controls.css';
 interface Props {
     value: unknown[] | undefined;
@@ -19,12 +19,14 @@ interface Props {
      * properties' own names from, one `-e-<element id>` segment down, so each open
      * record's cells carry real `<label for>` pairs like every other control. */
     idBase?: string;
-    /** Element `i`'s content, decoded by the boundary through the codec `items`
-     * names (`Field`, `reader.getContentAt`). Asked only for a content-typed
-     * element: on any other the read is not content and throws. `undefined` for a
-     * row the stored value does not reach — a slot this control has spliced in and
-     * whose commit has yet to land, or was refused. */
-    elementContent: (i: number) => Content | undefined;
+    /** The boundary's nested content read, rooted at this field: `path` is a
+     * `PathStep[]` from the field to the leaf, so `[i]` is element `i` and
+     * `[i, key]` a content cell of an `object` element's subform (`Field`,
+     * `reader.getContentAt`). The codec is the leaf's own declared type's. Asked
+     * only for a content-typed leaf: on any other the read is not content and
+     * throws. `undefined` for a leaf the stored value does not reach — a slot this
+     * control has spliced in and whose commit has yet to land, or was refused. */
+    contentAt: (path: PathStep[]) => Content | undefined;
     onCommit: (arr: unknown[]) => void;
 }
 declare const ArrayField: import("svelte").Component<Props, {

package/dist/visual/Card.svelte

@@ -16,6 +16,7 @@
 	import type { LeafRegistry } from './leaves.js';
 	import type { CardModel, FieldModel } from './structure.js';
 	import { placeFields, humanize, initialExpandedGroup } from './structure.js';
+	import { holdInView } from './hold.js';
 	import type { FieldDomIds } from './domid.js';
 	import Field from './Field.svelte';
 	import ProseField from './ProseField.svelte';
@@ -127,9 +128,9 @@
 	const ungrouped = $derived(card.sections.filter((s) => s.group == null));
 	const grouped = $derived(card.sections.filter((s) => s.group != null));
 
-	// A schema that declares no fields still gets a body, and a bracket around nothing is
-	// worse than none: with no content between them the two horizontals land on one y and
-	// paint as a single stroke of twice the width.
+	// A schema that declares no fields still gets a body, and an empty payload block is
+	// worse than none: its two rules land on one y and paint as a single stroke of twice
+	// the width, and the card's gap counts the block twice besides.
 	const hasMeta = $derived(ungrouped.length > 0 || grouped.length > 0);
 
 	// Seeded once from the card's shape. Card is keyed by stable id, so this survives the
@@ -157,9 +158,11 @@
 			headers[closing]?.focus();
 		expanded = next;
 	}
+	/** The header is the anchor: a section closing above it is what would carry it off the
+	 *  fold, and a section opens under its own header (`hold.ts`). */
 	function toggleGroup(group: string): void {
 		animate = true;
-		setExpanded(expanded === group ? null : group);
+		holdInView(headers[group], () => setExpanded(expanded === group ? null : group));
 	}
 
 	/**
@@ -190,6 +193,9 @@
 	 * an insert, `nearest` for a reorder. The reduced-motion guard is JS rather than the
 	 * CSS the accordion uses: a scroll's behaviour is an argument, not a transition a
 	 * media query can cancel.
+	 *
+	 * The caller is what waits out a reorder's own trip before asking: the run holds the
+	 * slot this card sits in, and the slot is the stack's (`VisualEditorInner`).
 	 */
 	export function scrollIntoViewCard(block: ScrollLogicalPosition): void {
 		const reduce = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
@@ -244,10 +250,6 @@
 		{/if}
 
 		<div class="qm-card-body">
-			<!-- One element whose top and bottom edges are the bracket's two horizontals.
-		 Anchored here rather than on the header and on the accordion so an open section's
-		 vertical reaches them, and so a card with no groups still terminates above its
-		 body. -->
 			{#if hasMeta}
 				<div
 					class="qm-card-meta"
@@ -261,8 +263,7 @@
 					{/each}
 
 					<!-- One open at a time. Rendered only when a card has groups, so an empty
-				     accordion is not the bracket's last child: the bottom rule's inset belongs
-				     to whichever block abuts it. -->
+				     accordion does not stand a gap under the ungrouped fields. -->
 					{#if grouped.length}
 						<div class="qm-groups" class:qm-instant={!animate}>
 							{#each grouped as section (section.group)}
@@ -409,11 +410,12 @@
 	/* An island: the card is the base plane, the column behind it the sunken one, and the
 	 hairline closes it (ARCHITECTURE §Styling). The inset is the same rung as the gap, so
 	 what separates the header from the fields is what separates the fields from the
-	 card's edge. */
+	 card's edge. The inline half reads `--_qm-nest` at that same number: this edge is the
+	 nesting ladder's first stroke, and its inset the first step. */
 	.qm-card {
 		border: var(--_qm-border-width) solid var(--_qm-border);
 		border-radius: var(--_qm-radius);
-		padding: var(--_qm-space-3);
+		padding: var(--_qm-space-3) var(--_qm-nest);
 		background: var(--_qm-surface);
 		display: flex;
 		flex-direction: column;
@@ -497,37 +499,58 @@
 	.qm-card-title:focus {
 		color: var(--_qm-ink);
 	}
-	.qm-card-body,
-	.qm-card-meta {
+	.qm-card-body {
 		display: flex;
 		flex-direction: column;
 		gap: var(--_qm-space-3);
 	}
-	/* The metadata bracket, in three strokes at one rung: these two horizontals and the
-	 open section's vertical below. A bracket whose sides disagree on width or tone reads
-	 as three unrelated lines rather than one figure, which is why the vertical takes
-	 `--_qm-border` and not `--_qm-accent`.
+	/* Where two sections meet the distance is three of one rung — the cap closing the one
+	 above, this gap, the cap opening the one below — the same whether either side is a
+	 group or the ungrouped block. That total is what the fields inside a section keep
+	 between their rows (`.qm-fields` row-gap), so a section boundary stands no further
+	 apart than a field boundary: what ranks them is the stroke, not the air. */
+	.qm-card-meta,
+	.qm-groups {
+		display: flex;
+		flex-direction: column;
+		gap: var(--_qm-space);
+	}
+	/* One rung in two places: what a rule insets its own edge by, and what a vertical
+	 reaches past the box it is drawn on. `--_qm-nest` is the distance a stroke stands off
+	 the content it holds — the same one the fields keep off the vertical inline — and a
+	 section's box already spends `--_qm-space` of it capping its own ends, so both spend
+	 the difference. That is what squares the corner: the field stands the same rung off
+	 the rule above it as off the vertical beside it. */
+	.qm-card-meta {
+		--stroke-reach: calc(var(--_qm-nest) - var(--_qm-space));
+	}
+	/* The card's two horizontals, and ranking is the one thing a horizontal is for: they
+	 stand the payload against the title above it and the body below it, where saying what
+	 sits inside what is the verticals' (ARCHITECTURE §"A plane is a tone"). Each is
+	 conditional on what it ranks against: `main` is headerless, and a card with no body
+	 has nothing under the payload to divide it from.
 
-	 Each condition is what its stroke means: a top rule is the line under a card title,
-	 so the headerless `main` has none; a bottom rule divides fields from body, so a card
-	 with no body has nothing to divide. Sometimes two strokes and sometimes one — an open
-	 figure, which is what distinguishes it from a second box inside the card. */
+	 The inset is the rule's own, so it goes with it: a card drawing one horizontal insets
+	 that end and not the other. The air outside the pair is the `--_qm-space-3` the card
+	 spends between its blocks. */
 	.qm-meta-top {
 		border-top: var(--_qm-border-width) solid var(--_qm-border);
+		padding-top: var(--stroke-reach);
 	}
 	.qm-meta-bottom {
 		border-bottom: var(--_qm-border-width) solid var(--_qm-border);
+		padding-bottom: var(--stroke-reach);
 	}
-	/* The inset sits on the fields rather than on the block that holds them: an open
-	 section's vertical has to reach the rule to close a corner against it, and padding
-	 between the two is the distance by which it would miss. Unqualified by open — a shut
-	 panel clips it. */
-	.qm-meta-top > .qm-section {
-		padding-top: var(--_qm-space-3);
-	}
-	.qm-meta-bottom > .qm-section:last-child,
-	.qm-meta-bottom .qm-group:last-child .qm-group-panel-inner > .qm-fields {
-		padding-bottom: var(--_qm-space-3);
+	/* A section's share of the boundary between sections: one rung at each end, so two of
+	 them stand three of it apart whichever kind they are (above). The accordion spends the
+	 same rung from its header and its panel, where it also caps the vertical those two
+	 edges hold.
+
+	 No stroke and no inset: fields declaring no `ui.group` are the card's own, at the rank
+	 its body is at, and the card's edge is the only container there is to state. A
+	 vertical here would mark a section a reader has no name for. */
+	.qm-section {
+		padding-block: var(--_qm-space);
 	}
 	/* Two query containers, one per kind of section, so capacity follows the width the
 	 fields actually get: a panel's inset makes that narrower than the card. */
@@ -562,16 +585,32 @@
 			--cols-half: 2;
 		}
 	}
-	.qm-groups,
+	/* 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
+	 not `--_qm-accent`: a card's edge and the verticals inside it are one stroke at three
+	 depths, and a tone that changed as it went in would read as unrelated lines rather
+	 than one figure. A named section is what earns it, which is why the ungrouped block
+	 above draws none.
+
+	 On the group rather than on its panel: what the stroke marks is the section, and a
+	 section is its header and what hangs under it. Drawn transparent when closed rather
+	 than absent, so a toggle moves no text — and closed, there is nothing under the header
+	 for it to gather.
+
+	 The stroke caps at `--_qm-nest`, at both ends and on every section alike. Its box
+	 already spends `--_qm-space` of that — the header's block padding above, the panel's
+	 below, the rung the ungrouped section spends on its own two ends — so the rest is
+	 grown here and handed straight back as margin: the stroke lengthens, and a section
+	 boundary keeps the three rungs it stood at. What the stroke reaches into is the air of
+	 that boundary, or, where the section is the payload's first or last, exactly the inset
+	 its rule took — so it lands on the rule at a corner with nothing drawn longer for it.
+	 One section open at a time, so no two strokes are ever visible to meet in between. */
 	.qm-group {
 		display: flex;
 		flex-direction: column;
-	}
-	/* The bracket's third stroke, on the section rather than on its panel: spanning the
-	 header is what gives it a corner to close into at the block's edge. Drawn transparent
-	 when closed rather than absent, so a toggle moves no text. */
-	.qm-group {
 		border-left: var(--_qm-border-width) solid transparent;
+		padding-block: var(--stroke-reach);
+		margin-block: calc(-1 * var(--stroke-reach));
 		transition: border-color var(--_qm-duration-slow) var(--_qm-ease-reverse);
 	}
 	.qm-group.qm-open {
@@ -579,10 +618,13 @@
 	}
 	/* Symmetric vertical padding at the tightest rung that still clears WCAG 2.5.8's
 	 24×24 floor: the header is the whole row, so adjacent labels share one rhythm with no
-	 dead strip outside the button. Horizontal is one rung left and zero right — left,
-	 because at zero the chevron stands on the section's vertical with only the icon box's
-	 own bearing between them, and the glyph's rotation swaps which bearing faces the
-	 stroke; right, because the row is the target and an inset there is target given back.
+	 dead strip outside the button. Horizontal is the nesting step left and zero right —
+	 left, because the chevron opening the heading starts where the fields under it start,
+	 so everything the section holds stands off its vertical by one rung and the corner the
+	 stroke closes against a rule reads square; right, because the row is the target and an
+	 inset there is target given back. What the glyph gives up by taking the step is the
+	 gutter: at a tighter rung it stands in the clearance itself, with only its own bearing
+	 between ink and stroke, and the rotation swaps which bearing faces which.
 
 	 `font: inherit` because a UA button inherits no face, then the body rung, one step
 	 over the field labels beneath it: at the label rung the two read as one register and
@@ -595,7 +637,7 @@
 		width: 100%;
 		border: none;
 		background: transparent;
-		padding: var(--_qm-space) 0 var(--_qm-space) var(--_qm-space);
+		padding: var(--_qm-space) 0 var(--_qm-space) var(--_qm-nest);
 		font: inherit;
 		font-size: var(--_qm-text-body);
 		font-weight: var(--_qm-weight-mid);
@@ -651,12 +693,13 @@
 	.qm-group-panel-inner {
 		min-height: 0;
 		overflow: hidden;
-		padding-inline-start: var(--_qm-space-4);
+		padding-inline-start: var(--_qm-nest);
 		padding-inline-end: var(--_qm-ring-reach);
 		margin-inline-end: calc(-1 * var(--_qm-ring-reach));
 	}
+	/* The lower of the two caps an open section's vertical takes (`.qm-group`). */
 	.qm-group-panel-inner > .qm-fields {
-		padding-block: var(--_qm-space-2);
+		padding-block: var(--_qm-space);
 	}
 	.qm-body-leaf {
 		display: flex;

package/dist/visual/EnumField.svelte

@@ -108,10 +108,12 @@
 			<Icon name="chevron-down" size={14} />
 		</Select.Trigger>
 		<Select.Portal to={portalTarget}>
-			<Select.Content sideOffset={4}>
+			<Select.Content collisionBoundary={portalTarget ?? []} sideOffset={4}>
 				<!-- The list portals out of the trigger's DOM but into the nearest
 				     `[data-qm-root]`, and carries the marker itself, like FormatPopover.
-				     The pill is this
+				     That root is the boundary a flip is measured against too, being the box
+				     that clips the surface where the consumer scrolls one; the viewport
+				     default knows nothing of that. The pill is this
 				     element (not the primitive's) because scoped CSS keys off which
 				     component owns the markup: a `class` passed to a primitive is a
 				     plain string and never picks up the scoping hash. -->

package/dist/visual/Field.svelte

@@ -14,7 +14,15 @@
  `DiagnosticList`, non-gating.
 -->
 <script lang="ts">
-	import type { Document, Quill, Addr, Diagnostic, ResolvedField } from '@quillmark/wasm';
+	import type {
+		Document,
+		Quill,
+		Addr,
+		Content,
+		Diagnostic,
+		PathStep,
+		ResolvedField
+	} from '@quillmark/wasm';
 	import type { EditorErrorHandler } from '../core/errors.js';
 	import type { LeafRegistry } from './leaves.js';
 	import type { FieldModel, FieldSpan } from './structure.js';
@@ -116,6 +124,16 @@
 	// nothing, and silently.
 	const describedBy = $derived(field.description ? domIds.description : undefined);
 
+	/** The boundary's nested content read with this field's address already bound: an
+	 * array's elements, an object's properties, a variant's cells, and a subform's cells
+	 * under an open element. One door rather than one per depth, since `getContentAt`
+	 * takes the whole path and the walk down is each container prefixing its own step.
+	 * Read per call and never held: a leaf takes its state at mount, and a control asks
+	 * once. */
+	function contentAt(path: PathStep[]): Content | undefined {
+		return quill.reader(doc).getContentAt(addr, path);
+	}
+
 	// ── Focus: one answer, two callers (`leaves.ts`) ─────────────────────────────
 	// A label click and the editor's `focusField`/`setCaret` ask the same question, so
 	// they read the same function and cannot land in different places. The four
@@ -247,6 +265,7 @@
 					id={domIds.control}
 					labelledBy={domIds.label}
 					{describedBy}
+					{contentAt}
 					onCommit={onCommitScalar}
 					{optionAllowed}
 					{enumDisallowed}
@@ -288,7 +307,7 @@
 					labelId={domIds.label}
 					descriptionId={domIds.description}
 					idBase={domIds.control}
-					elementContent={(i) => quill.reader(doc).getContentAt(addr, [i])}
+					{contentAt}
 					onCommit={onCommitScalar}
 				/>
 			{:else if field.control === 'object'}
@@ -300,6 +319,7 @@
 					idBase={domIds.control}
 					labelledBy={domIds.label}
 					{describedBy}
+					{contentAt}
 					onCommit={onCommitScalar}
 				/>
 			{:else}