@quillmark/svelte 0.1.1 → 0.3.0

package/dist/preview/paint.js

@@ -33,23 +33,25 @@ onPaintError) {
     }, { root: container, threshold: 0 });
     function makeSlot(page) {
         const size = session.pageSize(page);
-        // The sheet's own edge, and the only thing separating it from the desk: the
-        // page is at `--_qm-surface`, and the tone behind it is the host's, which
-        // THEMING permits to be plain `--qm-bg` (the same value). A hairline holds at
-        // both poles where a shadow's offset does not, and the
-        // boundary of the paper is not a mark on it, so the overlay's no-ink-at-rest
-        // rule is untouched (PREVIEW §Overlay). `border-box`, so the stroke lands
-        // inside the width the container gives and `clientWidth` below still measures
-        // the paper.
+        // The sheet is a plane and the desk is the one under it: paper sits at
+        // `--_qm-surface` and the container paints `--_qm-surface-sunken`, so the
+        // edge is where two tones meet and no stroke is drawn around it
+        // (ARCHITECTURE §Styling). It leaves the overlay's no-ink-at-rest rule
+        // untouched, since a boundary that is not painted is not a mark on the page
+        // (PREVIEW §Overlay). `border-box` costs nothing here and keeps a slot a
+        // consumer insets from measuring wider than its 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',
             width: '100%',
             aspectRatio: `${size.widthPt} / ${size.heightPt}`,
-            background: 'var(--_qm-surface)',
-            border: 'var(--_qm-border-width) solid var(--_qm-border)'
+            background: 'var(--_qm-surface)'
         });
         if (page > 0)
             el.style.marginTop = PAGE_GAP;
@@ -59,7 +61,7 @@ onPaintError) {
         return { page, size, el };
     }
     // Rasterize `slot` into its canvas (creating the canvas if this is its first
-    // paint since mounting). `layoutScale` is derived from the slot's OWN current
+    // paint since mounting). `layoutScale` is derived from the slot's own current
     // CSS width, so layout width tracks the container per the zoom settled
     // decision; `canvas.style.*` is then set from the authoritative PaintResult,
     // never guessed.
@@ -70,7 +72,7 @@ onPaintError) {
             canvas.className = 'qm-page-canvas';
             Object.assign(canvas.style, { position: 'absolute', inset: '0', display: 'block' });
         }
-        // Contextless canvas: bail BEFORE registering, so `updateBand` still sees
+        // Contextless canvas: bail before registering, so `updateBand` still sees
         // the page as unmounted and retries instead of keeping a blank page.
         const ctx = canvas.getContext('2d');
         if (!ctx)
@@ -104,7 +106,7 @@ onPaintError) {
         canvases.delete(page);
     }
     // Mount pages newly inside [min(visible)-margin, max(visible)+margin], unmount
-    // pages that fell outside it. Only touches pages CHANGING band membership;
+    // pages that fell outside it. Only touches pages changing band membership;
     // an already-mounted page in the band is left alone (paint contract: an idle
     // canvas keeps its pixels for free; repainting it here would be pure waste).
     function updateBand() {
@@ -154,13 +156,13 @@ onPaintError) {
         }
     }
     // Slots are built on the first `refresh` (the controller calls it immediately),
-    // NOT here: reconcile → `session.pageSize` must run AFTER the controller's
+    // not here: reconcile → `session.pageSize` must run after the controller's
     // `supportsCanvas`/`pageCount` gate, since a `supportsCanvas: false` compile with
     // pages would throw on `pageSize` (runtime.d.ts: it succeeds iff `supportsCanvas`)
     // before the controller can surface its "unsupported" message.
     // ── Keep mounted rasters in step with the display ───────────────────────────
-    // Every paint freezes `canvas.style.width/height` to the box width AT THAT
-    // PAINT (paintSlot). A page that stays mounted while the container's CSS width
+    // Every paint freezes `canvas.style.width/height` to the box width at that
+    // paint (paintSlot). A page that stays mounted while the container's CSS width
     // or `devicePixelRatio` shifts would otherwise keep a stale raster the %-space
     // overlay/click math silently drifts off of: the box tracks the container, the
     // ink does not. Two observers close the gap by repainting mounted pages from
@@ -208,7 +210,7 @@ onPaintError) {
     resizeObserver?.observe(container);
     // `devicePixelRatio` changes (window dragged to a different-DPI monitor, browser
     // zoom) leave CSS-px width untouched, so the ResizeObserver never sees them;
-    // watch DPR directly. A `(resolution: …dppx)` query pins the CURRENT ratio and
+    // watch DPR directly. A `(resolution: …dppx)` query pins the current ratio and
     // is therefore one-shot: re-arm it against the new ratio on each change. Guarded
     // for environments (jsdom) without `matchMedia`.
     let dprQuery;

package/dist/visual/ArrayField.svelte

@@ -1,5 +1,5 @@
 <!--
- An `array` field → an add/remove repeater. Elements commit by VALUE: every
+ An `array` field → an add/remove repeater. Elements commit by value: every
  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`: `string` → text input, `richtext` → a prose element
@@ -8,19 +8,19 @@
  label header row (space-between with the field label); {@link Field} skips its
  own label for array controls and hands this component the label track with it.
 
- A row ends in the reserved action column (`--action-col`), which the field insets
- and this reaches back across: the element controls stop where a scalar's does and
- the remove sits beyond them, on the right edge the field's track keeps.
+ The remove is inside the element: a slab over the end of the element's own box, taking
+ its two end-side corners. So a row's box is the element's box, and an array's rows end
+ where every other field's control does.
 
  Keys carry the list without the mouse: Enter inserts a
- sibling below and takes the caret there, Backspace on an EMPTY element removes it
+ sibling below and takes the caret there, Backspace on an empty element removes it
  and hands focus back up the list.
 
  No reorder: an array's order is fixed at declaration/entry order. Elements
  carry a parallel session-id list, spliced with the values as one operation at
  whatever index a mutation names; so an element holds its id for life and the
  surviving order never permutes, which is what lets a keyed prose element survive an
- insert or a remove ABOVE it rather than remounting.
+ insert or a remove above it rather than remounting.
 -->
 <script lang="ts">
 	import { wording } from './strings.js';
@@ -48,36 +48,25 @@
 		required?: boolean;
 		/** Schema `description`: the label's help affordance. */
 		description?: string;
-		/** The label's own DOM id. An array is a GROUP (N inputs, no single `for`
+		/** The label's own DOM id. An array is a group (N inputs, no single `for`
 		 * target) so the label names the set and each element keeps its indexed
 		 * `aria-label`. */
 		labelId?: string;
 		/** 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`
+	// The element control is the item schema's own; an array declaring no `items`
 	// has text elements.
 	const control = $derived(items ? controlKind(items) : 'text');
 	const plaintext = $derived(items?.type === 'plaintext');
 	const arr = $derived((value ?? []) as unknown[]);
 
 	// Parallel stable ids, one per element, kept in lockstep with the data below.
-	// Seeded eagerly so a non-empty array renders its rows on the FIRST pass:
+	// Seeded eagerly so a non-empty array renders its rows on the first pass:
 	// an effect-only seed mounts every element editor in a second render.
 	const seq = new IdSeq();
 	// svelte-ignore state_referenced_locally
@@ -100,9 +89,16 @@
 	// is stated on `ProseArrayElement.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
+	// 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,11 +159,21 @@
 		// 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
+	 * 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.
 	 *
-	 * The commit that schedules this can also remove the CARD holding the field, which
+	 * The commit that schedules this can also remove the card holding the field, which
 	 * unmounts this component inside the window (core/teardown.ts). */
 	async function focusAfterFlush(id: string | undefined): Promise<void> {
 		if (!(await span.resumes(tick()))) return;
@@ -174,7 +181,7 @@
 		else els[id]?.focus();
 	}
 	/** Whether element `k` reads empty to the user. A text element's committed value
-	 * LAGS the input: a cleared field commits at `change`, not per keystroke
+	 * lags the input: a cleared field commits at `change`, not per keystroke
 	 * ({@link TextField}); so the input's own value is the truth; a prose element
 	 * commits every edit, so the committed `Content` is. */
 	function elementEmpty(k: number, target: EventTarget | null): boolean {
@@ -195,7 +202,7 @@
 		} else if (e.key === 'Backspace' && !e.repeat && elementEmpty(k, e.target)) {
 			// Destructive with nothing to undo it, so it takes a deliberate press:
 			// `repeat` is a held key running on past the character it just cleared, and
-			// the emptiness test reads the state BEFORE this keystroke applies; so the
+			// the emptiness test reads the state before this keystroke applies; so the
 			// press that empties an element never also removes it.
 			e.preventDefault();
 			remove(k);
@@ -216,15 +223,18 @@
 				{label}
 				id={labelId}
 				{descriptionId}
-				onActivate={activate}
+				onActivate={focus}
 				{required}
 				{description}
 			/>
 		{:else}
 			<span></span>
 		{/if}
-		<button type="button" class="qm-add-el qm-add-affordance" bind:this={addEl} onclick={add}
-			>{t.strings.arrayAdd}</button
+		<button
+			type="button"
+			class="qm-add-el qm-add-affordance qm-tap-floor"
+			bind:this={addEl}
+			onclick={add}>{t.strings.arrayAdd}</button
 		>
 	</div>
 	{#each ids as id, k (id)}
@@ -237,7 +247,6 @@
 					label={label != null ? `${label} ${k + 1}` : undefined}
 					onChange={(rt) => commitElement(k, rt)}
 					onKey={(e) => onElementKey(e, k)}
-					{onFocusEl}
 				/>
 			{:else if control === 'object'}
 				<textarea
@@ -263,9 +272,9 @@
 			{/if}
 			<button
 				type="button"
-				class="qm-icon-btn qm-remove"
+				class="qm-icon-btn qm-remove qm-focus-ring"
 				title={t.strings.arrayRemove}
-				onclick={() => remove(k)}><Icon name="x" size={14} /></button
+				onclick={() => remove(k)}><Icon name="minus" /></button
 			>
 		</div>
 	{/each}
@@ -276,14 +285,8 @@
 		display: flex;
 		flex-direction: column;
 		gap: var(--_qm-space);
-		/* The one field that reaches across the reserved action column: its rows END in
-		   that column, so an element control stops exactly where the scalar beside it
-		   does and the remove never sits over a long value. The reservation is the
-		   FIELD's inset (Field.svelte), so this cancels it wherever the field landed:
-		   its own row, or one track of a shared one. */
-		margin-right: calc(-1 * var(--action-col));
 	}
-	/* The array's first line IS the row's label line: this component owns the label
+	/* The array's first line is the row's label line: this component owns the label
 	 track (Field.svelte), so the header has to measure what a `.qm-field-label-row`
 	 measures or an array shares a row with a scalar and their labels sit apart. The
 	 label is the same component; what had to give was the add affordance's height,
@@ -294,19 +297,56 @@
 		justify-content: space-between;
 		gap: var(--_qm-space-2);
 	}
-	/* The element takes the section's tracks, the remove takes the action column, and
-	 the gutter between them is the section's own: the row is that column's only
-	 occupant, so it reads as one more column of the grid rather than a nested layout.
-	 `minmax(0, …)` because an element control must be allowed to be narrower than its
-	 content: a long unbroken value grows the track otherwise, and the edge with it. */
+	/* A grid rather than a block: an `<input>` and a `<textarea>` are inline-level and
+	 would sit on a baseline, standing the row a descender taller than the box the slab
+	 measures itself against. `minmax(0, …)` because a long unbroken value grows an `auto`
+	 track, and the edge with it. */
 	.qm-array-row {
+		position: relative;
 		display: grid;
-		grid-template-columns: minmax(0, 1fr) var(--_qm-tap-min);
-		column-gap: var(--_qm-space-2);
-		align-items: start;
+		grid-template-columns: minmax(0, 1fr);
+	}
+	/* The end inset the slab stands in, taken off whichever box the element drew:
+	 `.qm-input` is the text element and the JSON textarea, `.qm-control-box` the prose
+	 one. `:global`, because the box belongs to the child component's markup and the scope
+	 class stops at this component's. The longhand beats the family's `padding` shorthand
+	 without a specificity fight: this block is unlayered and `controls.css` is not. */
+	.qm-array-row :global(.qm-input),
+	.qm-array-row :global(.qm-control-box) {
+		padding-inline-end: var(--_qm-tap-min);
 	}
+	/* The box's end wall, floor to ceiling: a height of its own would leave a sliver of
+	 well above or below, and the corners it takes are the box's — the end-side pair keeps
+	 `.qm-icon-btn`'s radius, which is the same rung the box draws.
+
+	 It comes up on its own row rather than on the field: a destructive control is offered
+	 by the row the pointer is on, not by every row at once. Hover is where it says
+	 destructive, ink with fill, a tint alone being a wash under a label-toned glyph. */
 	.qm-remove {
-		align-self: center;
+		position: absolute;
+		inset-block: 0;
+		inset-inline-end: 0;
+		width: var(--_qm-tap-min);
+		color: var(--_qm-ink-label);
+		opacity: var(--_qm-opacity-idle);
+		border-start-start-radius: 0;
+		border-end-start-radius: 0;
+		transition:
+			opacity var(--_qm-duration-fast) var(--_qm-ease-reverse),
+			background-color var(--_qm-duration-fast) var(--_qm-ease-reverse),
+			color var(--_qm-duration-fast) var(--_qm-ease-reverse);
+	}
+	.qm-remove :global(svg) {
+		width: var(--_qm-glyph-control);
+		height: var(--_qm-glyph-control);
+	}
+	.qm-array-row:hover .qm-remove,
+	.qm-array-row:focus-within .qm-remove {
+		opacity: 1;
+	}
+	.qm-remove:hover {
+		background: var(--_qm-danger-tint);
+		color: var(--_qm-danger);
 	}
 	/* The JSON element is a `.qm-input` (controls.css): box, focus ring, and all;
 	 what a textarea adds over an input is the face and a floor on its height. */
@@ -314,48 +354,28 @@
 		font-family: var(--_qm-font-mono);
 		min-height: 2.5rem;
 	}
-	/* Chrome, hover fill and target come from `.qm-add-affordance` (controls.css);
-	 what is here is this trigger's own type, box and recede ladder. It rests dim like
-	 the card stack's gap triggers and comes up on hover of the FIELD or on focus: one
-	 trigger at the head of a row of controls is found by looking at the array, not by
-	 grazing its first line.
+	/* It rests dim and comes up on hover of the field rather than of itself: one trigger
+	 at the head of a row of controls is found by looking at the array, not by grazing its
+	 first line.
 
-	 THE BOX IS THE LABEL'S LINE BOX, and the target is the `::after`: the same split
-	 the field label's guidance marker takes, for the same reason and one row over.
-	 This is the other affordance that sits IN a line of text rather than in a row of
-	 its own, and the line is a label's, so a
+	 The box is the label's line box and the target is `.qm-tap-floor`'s (controls.css): a
 	 target-sized box would stand the header 8px taller than the `.qm-field-label-row`
-	 beside it in a shared row and put the two labels on different lines. So the family's
-	 floor comes off the box and goes out of flow, unpainted and centred on it: the row
-	 keeps the label's line box, the press keeps the floor. The horizontal edges are the
-	 button's own, the word being already wider than the threshold.
+	 beside it in a shared row and put the two labels on different lines.
 
-	 The type is the LABEL rung in place of the family's body rung, which the family
-	 invites (controls.css: a caller whose button carries a label restates the rung it
-	 wants). It reads as one more thing on the label line rather than as a control that
-	 wandered up from the row below. */
+	 The label rung in place of the family's body rung, which the family invites: it reads
+	 as one more thing on the label line rather than as a control from the row below. */
 	.qm-add-el {
-		position: relative;
-		min-height: 0;
 		padding: 0 var(--_qm-space);
 		font-size: var(--_qm-text-label);
 		opacity: var(--_qm-opacity-idle);
 	}
-	.qm-add-el::after {
-		content: '';
-		position: absolute;
-		inset-inline: 0;
-		top: 50%;
-		height: var(--_qm-tap-min);
-		transform: translateY(-50%);
-	}
 	.qm-array:hover .qm-add-el,
 	.qm-add-el:focus-visible {
 		opacity: 1;
 	}
-	/* Touch has no hover: keep a faint always-on affordance so add stays reachable. */
 	@media (hover: none) {
-		.qm-add-el {
+		.qm-add-el,
+		.qm-remove {
 			opacity: var(--_qm-opacity-muted);
 		}
 	}

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

@@ -9,16 +9,17 @@ interface Props {
     required?: boolean;
     /** Schema `description`: the label's help affordance. */
     description?: string;
-    /** The label's own DOM id. An array is a GROUP (N inputs, no single `for`
+    /** The label's own DOM id. An array is a group (N inputs, no single `for`
      * target) so the label names the set and each element keeps its indexed
      * `aria-label`. */
     labelId?: string;
     /** 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/BooleanField.svelte

@@ -13,11 +13,11 @@
 	interface Props {
 		value: boolean | undefined;
 		fallback?: boolean;
-		/** Accessible name for a switch NOTHING else names: an object property, whose
+		/** Accessible name for a switch nothing else names: an object property, whose
 		 * name is the field label plus the property's. A field's own switch takes `id`
 		 * instead and is named by the `<label for>` beside it. */
 		label?: string;
-		/** `<label for>` target. `Switch.Root` renders a `<button>`, which IS labelable,
+		/** `<label for>` target. `Switch.Root` renders a `<button>`, which is labelable,
 		 * so the click a label forwards toggles the switch: correct for this control,
 		 * and single-fire: the label is a sibling, not a wrapper, so there is no second
 		 * click bubbling back up to be re-dispatched. */
@@ -30,7 +30,7 @@
 
 	// Local toggle state synced to `value`; own-toggles stay local, only an external
 	// change reconciles back in (see `syncedLocal`). The primitive is driven
-	// CONTROLLED (`checked` + `onCheckedChange`, never `bind:`) so reconciliation
+	// controlled (`checked` + `onCheckedChange`, never `bind:`) so reconciliation
 	// stays the package's: a two-way bind hands the primitive a lane around it,
 	// which repeats the reconciliation hazard in miniature.
 	const local = syncedLocal(() => value ?? fallback ?? false);
@@ -53,7 +53,7 @@
 </span>
 
 <style>
-	/* A primitive renders its OWN element, which a scoped selector cannot reach:
+	/* A primitive renders its own element, which a scoped selector cannot reach:
 	 styled through the wrapper with `:global`. */
 	.qm-switch-wrap :global(.qm-switch) {
 		display: inline-flex;
@@ -61,15 +61,17 @@
 		width: 1.75rem;
 		height: 1rem;
 		padding: var(--_qm-space-half);
-		border: var(--_qm-border-width) solid var(--_qm-border);
+		border: none;
 		border-radius: var(--_qm-radius-pill);
+		/* The track is a fill and nothing else: an edge around it would be a second
+		 statement of a shape the tone already draws, and the checked state swaps that
+		 one fill for the accent (ARCHITECTURE §Styling). */
 		background: var(--_qm-surface-hover);
 		cursor: pointer;
 		transition: background var(--_qm-duration-fast) var(--_qm-ease-reverse);
 	}
 	.qm-switch-wrap :global(.qm-switch[data-state='checked']) {
 		background: var(--_qm-accent);
-		border-color: var(--_qm-accent);
 	}
 	/* The focus ring rides `.qm-focus-ring` on the switch (controls.css). */
 	/* The thumb reads on tone alone: the base surface over the track's `hover` rung

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

@@ -2,11 +2,11 @@ import './controls.css';
 interface Props {
     value: boolean | undefined;
     fallback?: boolean;
-    /** Accessible name for a switch NOTHING else names: an object property, whose
+    /** Accessible name for a switch nothing else names: an object property, whose
      * name is the field label plus the property's. A field's own switch takes `id`
      * instead and is named by the `<label for>` beside it. */
     label?: string;
-    /** `<label for>` target. `Switch.Root` renders a `<button>`, which IS labelable,
+    /** `<label for>` target. `Switch.Root` renders a `<button>`, which is labelable,
      * so the click a label forwards toggles the switch: correct for this control,
      * and single-fire: the label is a sibling, not a wrapper, so there is no second
      * click bubbling back up to be re-dispatched. */