@quillmark/svelte 0.16.0 → 0.17.0

package/README.md

@@ -46,6 +46,8 @@ const session = await new Engine().open(quill, doc);
 // free() on teardown the handles you MINTED: this quill, this doc, this session.
 ```
 
+`<VisualEditor>` needs no session, and the first `open` loads the render build, so a host that mounts the editor over `doc` and `quill` first shows it without waiting on that load. The session opens behind it: `await engine.load(quill)`, then `engine.open(quill, doc)`, so its first compile reads what was typed meanwhile ([HOSTING.md](prose/canon/HOSTING.md)).
+
 ## The quill resolves from the document
 
 A stored document carries none of its quill's bytes, only a reference: `doc.quillRef` is `name@version`, persisted in the markdown itself. Resolution is **host code**: read the ref, map it to a `Quill`, open. No surface resolves, so one resolution per document holds by construction.
@@ -58,7 +60,7 @@ const session = await new Engine().open(quill, doc);
 
 `@quillmark/quiver` is one such registry, and the quill it hands back is **borrowed**: it is cached per ref and shared with every caller, so freeing it strands the next one.
 
-Opening a document that names a **different** quill is the same sequence, in order: resolve the new ref, `engine.open(quill, next)`, swap the props, then free the replaced handles that were yours to free. `<VisualEditor>` re-keys itself on the new `doc` (see below); `<Preview>` swaps by remount (`{#key session}`).
+Opening a document that names a **different** quill is the same sequence, in order: resolve the new ref, swap the editor's props, free the replaced handles that were yours to free, then open the next session behind the editor. `<VisualEditor>` re-keys itself on the new `doc` (see below); `<Preview>` swaps by remount (`{#key session}`).
 
 ## What a document is trusted to be
 

package/dist/core/theme.css

@@ -316,7 +316,14 @@
 	   for the type half. Asymmetric because the vertical is what leading leaves once
 	   it has taken the line box, and the horizontal is how far in the text starts,
 	   which nothing else fixes. */
-	--_qm-inset-control: var(--_qm-space) var(--_qm-space-3);
+	--_qm-inset-control-block: var(--_qm-space);
+	--_qm-inset-control: var(--_qm-inset-control-block) var(--_qm-space-3);
+	/* A box's first line, drawn: its line box and the inset over and under it. What a
+	   row of boxes lines up on however far one of them wraps, and so what a mark with no
+	   line of its own centres on to stand in that row (`BooleanField`). */
+	--_qm-box-line: calc(
+		var(--_qm-text-body) * var(--_qm-leading-body) + 2 * var(--_qm-inset-control-block)
+	);
 	/* The nesting step: the distance from one structural stroke to the next, and what
 	   makes the depths read as a ladder rather than as indents that happen to look
 	   alike. A rung because the boxes holding that distance are in two components and
@@ -349,6 +356,10 @@
 	   name it and no label of its own to fit. A threshold rather than a rhythm choice,
 	   so it does not move with `--qm-space`. */
 	--_qm-track-min: 7rem;
+	/* A prose column's floor: its cell wraps, and at `--_qm-track-min` a line holds a
+	   word, standing the row many lines tall beside cells one line tall. A multiple of
+	   the floor, so the two move together. */
+	--_qm-track-prose: calc(var(--_qm-track-min) * 2);
 
 	/* ── Type ────────────────────────────────────────────────────────────────
 	   `--qm-font-size` anchors the chrome rung; 1.125 is the ratio between adjacent

package/dist/visual/ArrayField.svelte

@@ -591,7 +591,11 @@
 				     column's rather than any one cell's. -->
 				<div class="qm-array-table-head">
 					{#each columns as [key, sub] (key)}
-						<div class="qm-array-table-col" class:mark={controlKind(sub) === 'boolean'}>
+						<div
+							class="qm-array-table-col"
+							class:mark={controlKind(sub) === 'boolean'}
+							class:prose={controlKind(sub) === 'prose'}
+						>
 							<FieldLabel
 								label={columnTitle(key, sub)}
 								required={obliged(sub)}
@@ -1044,6 +1048,9 @@
 	.qm-array-table-col.mark {
 		min-width: 0;
 	}
+	.qm-array-table-col.prose {
+		min-width: var(--_qm-track-prose);
+	}
 	/* The remove is the row's last track, pinned to the end edge of the box the table
 	 scrolls in: sticky, so it rests in its track while the table fits and rides over
 	 the cells once the box scrolls, on the card's plane so what passes under it is
@@ -1066,8 +1073,12 @@
 		background: var(--_qm-surface);
 		box-shadow: 0 0 0 var(--_qm-ring-reach) var(--_qm-surface);
 	}
+	/* The glyph stands on the row's first line with the cells, however far the slab
+	 stretches under it. */
 	.qm-array-table-row > .qm-remove {
 		align-self: stretch;
+		align-items: start;
+		padding-block-start: calc((var(--_qm-box-line) - var(--_qm-glyph-control)) / 2);
 		height: auto;
 		border-radius: var(--_qm-radius-inner);
 		color: var(--_qm-ink-label);

package/dist/visual/BooleanField.svelte

@@ -74,6 +74,13 @@
 </span>
 
 <style>
+	/* The switch stands on the first line of the boxes beside it: a row of controls tops
+	 out together, and a mark carries no line of its own to sit on. */
+	.qm-toggle-wrap {
+		display: flex;
+		align-items: center;
+		min-height: var(--_qm-box-line);
+	}
 	/* A primitive renders its own element, which a scoped selector cannot reach:
 	 styled through the wrapper with `:global`. */
 	/* The track is the drawn box and the target is `.qm-tap-floor`'s (controls.css): a

package/dist/visual/Card.svelte

@@ -19,6 +19,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';
@@ -270,21 +271,37 @@
 								{@const group = section.group as string}
 								{@const isOpen = expanded === group}
 								{@const panelId = ops.panelId(group)}
+								{@const headIds = section.head ? ops.domIds(section.head.name) : undefined}
+								{@const headHint = section.head?.description}
 								<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>
+									<!-- 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 +312,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 +349,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 +371,7 @@
 				{onError}
 				{leaves}
 				diagnostics={ops.diagFor(f.name)}
+				headed={f === head}
 			/>
 		{/each}
 	</div>
@@ -591,7 +609,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 +699,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/Field.svelte

@@ -33,6 +33,7 @@
 		VARIANT_DISCRIMINANT,
 		arrayLayout,
 		baseType,
+		flatObject,
 		ghostDefault,
 		isContainer,
 		optionalCell,
@@ -88,6 +89,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 +111,8 @@
 		onChange,
 		onError,
 		leaves,
-		diagnostics
+		diagnostics,
+		headed = false
 	}: Props = $props();
 
 	const t = wording();
@@ -157,6 +162,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
@@ -257,7 +263,7 @@
 </script>
 
 <div class="qm-field" class:cell={span === 'cell'}>
-	{#if !ownsLabel}
+	{#if !ownsLabel && !headed}
 		<FieldLabel
 			label={field.label}
 			controlId={labelable ? domIds.control : undefined}
@@ -376,6 +382,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 +401,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/MatrixAdd.svelte

@@ -0,0 +1,211 @@
+<!--
+ An open matrix's add box (VISUAL_EDITOR §"The matrix"): a combobox whose options are
+ what the typed words name across the document's checklists, best first, and last the
+ item they would add to this one. The list stands in flow under the input rather than
+ floating, so a closing group panel clips nothing of it, and it closes while the focus
+ is elsewhere. The input keeps the caret throughout and the active option is
+ `aria-activedescendant`, the combobox pattern: ↑/↓ walk, Enter picks, Escape clears.
+ Unwalked, the active option is the first result the words name outright, else the add
+ option: a result named only by abbreviation, which may stand in another card, is
+ taken by an arrow or a press and never by Enter alone.
+-->
+<script lang="ts">
+	import Icon from './icons/Icon.svelte';
+	import type { AddOption } from './checklists.js';
+	import './controls.css';
+
+	interface Props {
+		/** The input's id, and the base its listbox and options derive theirs from. */
+		id: string;
+		/** The input's accessible name and its words at rest. */
+		placeholder: string;
+		/** The options `query` offers, best first; the add option, where there is one, last. */
+		options: (query: string) => AddOption[];
+		onChoose: (option: AddOption, query: string) => void;
+	}
+	let { id, placeholder, options, onChoose }: Props = $props();
+
+	let query = $state('');
+	/** The walked option, `undefined` until an arrow or the pointer moves it. */
+	let walked = $state<number | undefined>();
+	let focused = $state(false);
+	let inputEl = $state<HTMLInputElement | undefined>();
+	const shown = $derived(query.trim() ? options(query.trim()) : []);
+	const open = $derived(focused && shown.length > 0);
+	const active = $derived.by(() => {
+		if (walked !== undefined) return Math.min(walked, shown.length - 1);
+		const strong = shown.findIndex((o) => o.strong);
+		if (strong >= 0) return strong;
+		const add = shown.findIndex((o) => o.add);
+		return add >= 0 ? add : 0;
+	});
+	const listId = $derived(`${id}-list`);
+	const optionId = (k: number): string => `${id}-opt-${k}`;
+
+	export function focus(): void {
+		inputEl?.focus();
+	}
+
+	function choose(k: number): void {
+		const option = shown[k];
+		if (!option) return;
+		const typed = query.trim();
+		query = '';
+		walked = undefined;
+		onChoose(option, typed);
+	}
+
+	function onkeydown(e: KeyboardEvent): void {
+		if (e.isComposing) return;
+		if (e.key === 'ArrowDown' && open) {
+			e.preventDefault();
+			walked = (active + 1) % shown.length;
+		} else if (e.key === 'ArrowUp' && open) {
+			e.preventDefault();
+			walked = (active - 1 + shown.length) % shown.length;
+		} else if (e.key === 'Enter' && open) {
+			e.preventDefault();
+			choose(active);
+		} else if (e.key === 'Escape' && query) {
+			e.preventDefault();
+			e.stopPropagation();
+			query = '';
+			walked = undefined;
+		}
+	}
+</script>
+
+<div class="qm-matrix-add">
+	<span class="qm-matrix-add-field">
+		<Icon name="plus" class="qm-matrix-add-glyph" />
+		<input
+			bind:this={inputEl}
+			{id}
+			class="qm-input qm-focus-ring"
+			type="text"
+			role="combobox"
+			autocomplete="off"
+			aria-label={placeholder}
+			aria-autocomplete="list"
+			aria-expanded={open}
+			aria-controls={listId}
+			aria-activedescendant={open ? optionId(active) : undefined}
+			{placeholder}
+			value={query}
+			oninput={(e) => {
+				query = e.currentTarget.value;
+				walked = undefined;
+			}}
+			onfocus={() => (focused = true)}
+			onblur={() => (focused = false)}
+			{onkeydown}
+		/>
+	</span>
+	<!-- Always mounted, so `aria-controls` names an element at rest too; empty, it draws
+	     nothing. -->
+	<div
+		class="qm-menu-surface qm-matrix-add-list"
+		role="listbox"
+		id={listId}
+		aria-label={placeholder}
+		hidden={!open}
+	>
+		{#each shown as option, k (option.key)}
+			<!-- The input keeps focus and owns the keys; a press picks without taking it. -->
+			<!-- svelte-ignore a11y_click_events_have_key_events -->
+			<div
+				class="qm-menu-item qm-matrix-add-option"
+				class:add={option.add}
+				role="option"
+				id={optionId(k)}
+				tabindex="-1"
+				aria-selected={k === active}
+				data-highlighted={k === active ? '' : undefined}
+				onpointerdown={(e) => e.preventDefault()}
+				onpointermove={() => (walked = k)}
+				onclick={() => choose(k)}
+			>
+				{#if option.add}<Icon name="plus" class="qm-matrix-add-glyph" />{/if}
+				<span class="qm-matrix-add-title">{option.title}</span>
+				{#if option.note}<span class="qm-matrix-add-note">{option.note}</span>{/if}
+			</div>
+		{/each}
+	</div>
+</div>
+
+<style>
+	/* The box's text, and every option's, starts past the glyph slot at its leading edge,
+	 so a result reads in the column the typed words stand in and the add option's `+`
+	 stands under the box's. */
+	.qm-matrix-add {
+		--_slot: calc(var(--_qm-space-2) * 2 + var(--_qm-glyph-control));
+		display: flex;
+		flex-direction: column;
+		gap: var(--_qm-space-half);
+		min-width: 0;
+	}
+	.qm-matrix-add-field {
+		position: relative;
+		display: flex;
+		align-items: center;
+		min-width: 0;
+	}
+	.qm-matrix-add :global(.qm-matrix-add-glyph) {
+		position: absolute;
+		inset-inline-start: var(--_qm-space-2);
+		width: var(--_qm-glyph-control);
+		height: var(--_qm-glyph-control);
+		color: var(--_qm-ink-label);
+		pointer-events: none;
+	}
+	/* At rest the box is the add chip it stands in for: no well, its words at the label
+	 ink. The well comes up under the pointer, and stays while it holds the focus or
+	 typed words. */
+	.qm-matrix-add-field .qm-input {
+		flex: 1;
+		min-width: 0;
+		padding-inline-start: var(--_slot);
+		transition: background-color var(--_qm-duration-fast) var(--_qm-ease-reverse);
+	}
+	.qm-matrix-add-field .qm-input:placeholder-shown:not(:focus) {
+		background: transparent;
+	}
+	.qm-matrix-add-field .qm-input:placeholder-shown:not(:focus):hover {
+		background: var(--_qm-surface-hover);
+	}
+	/* The list is a menu, raised over the card rather than cut into it, so its options
+	 read as choices and not as a second field. Its edge and inset come off each
+	 option's, which keeps the column. */
+	.qm-matrix-add-list {
+		display: flex;
+		flex-direction: column;
+	}
+	.qm-matrix-add-list[hidden] {
+		display: none;
+	}
+	.qm-matrix-add-option {
+		position: relative;
+		display: flex;
+		align-items: baseline;
+		justify-content: space-between;
+		gap: var(--_qm-space-2);
+		padding-inline-start: calc(var(--_slot) - var(--_qm-space-half) - var(--_qm-border-width));
+		font-size: var(--_qm-text-body);
+		color: var(--_qm-ink);
+	}
+	.qm-matrix-add-option :global(.qm-matrix-add-glyph) {
+		inset-inline-start: calc(var(--_qm-space-2) - var(--_qm-space-half) - var(--_qm-border-width));
+		inset-block-start: 50%;
+		translate: 0 -50%;
+	}
+	/* The add option reads at the label ink: it offers a new item, where a result names
+	 one the document already knows. */
+	.qm-matrix-add-option.add {
+		color: var(--_qm-ink-label);
+	}
+	.qm-matrix-add-note {
+		flex-shrink: 0;
+		font-size: var(--_qm-text-label);
+		color: var(--_qm-ink-label);
+	}
+</style>

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

@@ -0,0 +1,16 @@
+import type { AddOption } from './checklists.js';
+import './controls.css';
+interface Props {
+    /** The input's id, and the base its listbox and options derive theirs from. */
+    id: string;
+    /** The input's accessible name and its words at rest. */
+    placeholder: string;
+    /** The options `query` offers, best first; the add option, where there is one, last. */
+    options: (query: string) => AddOption[];
+    onChoose: (option: AddOption, query: string) => void;
+}
+declare const MatrixAdd: import("svelte").Component<Props, {
+    focus: () => void;
+}, "">;
+type MatrixAdd = ReturnType<typeof MatrixAdd>;
+export default MatrixAdd;