@quillmark/svelte 0.5.1 → 0.7.0

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 metadata block
+	// draws nothing while the card's gap still counts it twice, standing a rung of dead
+	// space over the body.
 	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
@@ -140,6 +141,10 @@
 	let expanded = $state<string | null>(initialExpandedGroup(card.sections));
 	let headers = $state<Record<string, HTMLButtonElement | undefined>>({});
 	let panels = $state<Record<string, HTMLElement | undefined>>({});
+	/** Whether the panels animate the move `expanded` is about to make. False for a reveal
+	 *  ({@link revealLeaf}), restored by the header gesture the motion is there for, so its
+	 *  return needs no timer. */
+	let animate = $state(true);
 	/**
 	 * Move to `next` (`null` = all closed). A closing panel goes `inert` with whatever it
 	 * held still focused, and `inert` does not say where focus should go — the browser
@@ -153,8 +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 {
-		setExpanded(expanded === group ? null : group);
+		animate = true;
+		holdInView(headers[group], () => setExpanded(expanded === group ? null : group));
 	}
 
 	/**
@@ -163,13 +171,20 @@
 	 * flush before landing, since `inert` clears when the panel renders open, not when
 	 * `expanded` is assigned.
 	 *
+	 * The move is instant, because that same flush is when the landing measures its target:
+	 * an animating track still reads its start value there, and the trip would be computed
+	 * against a panel that has not moved yet. The motion explains a header click, and a
+	 * click in the preview is not one.
+	 *
 	 * A call, not a prop: a reveal is an event, and modelling it as state needs a
 	 * fresh-identity wrapper to re-fire and an `untrack` to keep the per-keystroke
 	 * re-derive from reopening the accordion under the user.
 	 */
 	export function revealLeaf(key: string): void {
 		const section = grouped.find((s) => s.fields.some((f) => ops.leafKey(f.name) === key));
-		if (section?.group) setExpanded(section.group);
+		if (!section?.group) return;
+		animate = false;
+		setExpanded(section.group);
 	}
 
 	let el = $state<HTMLElement | undefined>(undefined);
@@ -178,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;
@@ -232,16 +250,8 @@
 		{/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"
-					class:qm-meta-top={!card.isMain}
-					class:qm-meta-bottom={card.hasBody}
-				>
+				<div class="qm-card-meta" class:qm-meta-bottom={card.hasBody}>
 					{#each ungrouped as section (section.group ?? '_ungrouped')}
 						<div class="qm-section">
 							{@render sectionFields(section.fields)}
@@ -249,10 +259,9 @@
 					{/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">
+						<div class="qm-groups" class:qm-instant={!animate}>
 							{#each grouped as section (section.group)}
 								{@const group = section.group as string}
 								{@const isOpen = expanded === group}
@@ -397,11 +406,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;
@@ -485,37 +495,44 @@
 	.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`.
-
-	 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. */
-	.qm-meta-top {
-		border-top: var(--_qm-border-width) solid var(--_qm-border);
+	/* 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);
 	}
+	/* The one horizontal the card draws, and it is the one thing a horizontal is for: it
+	 ranks the payload against the body rather than saying what is inside what, which is
+	 the verticals' job (ARCHITECTURE §"A plane is a tone"). Conditional on a body, since
+	 with none it would divide the payload from the card's own edge a rung below it.
+
+	 The inset stands the rule off the last control at the rung the body sits under it by,
+	 taking the section's own end cap into account: `--_qm-space-2` here, plus that cap,
+	 is the `--_qm-space-3` the card spends between its blocks. */
 	.qm-meta-bottom {
 		border-bottom: var(--_qm-border-width) solid var(--_qm-border);
+		padding-bottom: var(--_qm-space-2);
 	}
-	/* 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. */
@@ -550,15 +567,21 @@
 			--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. Its caps are the header's block padding above and the panel's below,
+	 at the rung the ungrouped section spends on both of its own ends. */
 	.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;
 		transition: border-color var(--_qm-duration-slow) var(--_qm-ease-reverse);
 	}
@@ -571,6 +594,9 @@
 	 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.
+	 The rung is the glyph's own and not the nesting step the fields under it take: what
+	 the heading names is the section, so it rides the vertical rather than the column its
+	 fields start on.
 
 	 `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
@@ -618,6 +644,13 @@
 	.qm-group.qm-open .qm-group-panel {
 		grid-template-rows: 1fr;
 	}
+	/* The track is the accordion's only stroke that moves layout, and a reveal's landing
+	 measures its target one flush after asking — where an animating track still reads its
+	 start value. Both panels of the move are inside the group box, so the opening one and
+	 the closing one above it stand still together (`revealLeaf`). */
+	.qm-groups.qm-instant .qm-group-panel {
+		transition: none;
+	}
 	/* Two boxes because the axes clip differently, and the track is the only thing that
 	 animates: a field sits at its open position from the first frame of the reveal.
 
@@ -632,12 +665,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

@@ -16,8 +16,11 @@
 	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';
 
+	const t = wording();
+
 	interface Props {
 		value: string | undefined;
 		values: string[];
@@ -105,17 +108,30 @@
 			<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. -->
 				<div class="qm-menu-surface qm-select-content" data-qm-root>
 					<Select.Viewport>
-						<Select.Item class="qm-menu-item qm-select-item" value={UNSET} label={ghostText}>
+						<!-- The sentinel renders the `default:`'s own text, so a defaulted enum
+						     lists that word twice: this row, and the member below it. The tag has
+						     to be a word rather than a tone — the ghost is already `ink-label`,
+						     and while the field is unset this is the selected row, so the weight
+						     step pulls the other way. It rides the accessible name for the same
+						     reason. -->
+						<Select.Item
+							class="qm-menu-item qm-select-item qm-select-unset"
+							value={UNSET}
+							label={`${ghostText} ${t.strings.enumUnsetTag}`}
+						>
 							<span class="qm-select-ghost">{ghostText}</span>
+							<span class="qm-select-tag">{t.strings.enumUnsetTag}</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
@@ -186,4 +202,22 @@
 	.qm-select-ghost {
 		color: var(--_qm-ink-label);
 	}
+	/* The sentinel's row: the ghost at one end, the tag at the other, so the pair reads
+	   as a value and a note about it rather than as two words. Only this row takes the
+	   split; a member's row is one string and has nothing to distribute. */
+	.qm-select-content :global(.qm-select-unset) {
+		display: flex;
+		align-items: baseline;
+		justify-content: space-between;
+		gap: var(--_qm-space-2);
+	}
+	/* A step down the size ramp, which is what says this is chrome and the word beside
+	   it is the value. The ink is the ghost's own: a second tone here would rank the
+	   tag against the thing it annotates, and there is no rung under `label` to take
+	   (theme.css, "Two rungs, and there is no third"). */
+	.qm-select-tag {
+		flex-shrink: 0;
+		font-size: var(--_qm-text-label);
+		color: var(--_qm-ink-label);
+	}
 </style>

package/dist/visual/Field.svelte

@@ -18,7 +18,7 @@
 	import type { EditorErrorHandler } from '../core/errors.js';
 	import type { LeafRegistry } from './leaves.js';
 	import type { FieldModel, FieldSpan } from './structure.js';
-	import { ghostDefault, stringifyGhost } from './structure.js';
+	import { VARIANT_DISCRIMINANT, ghostDefault, stringifyGhost } from './structure.js';
 	import type { FieldDomIds } from './domid.js';
 	import ProseField from './ProseField.svelte';
 	import TextField from './TextField.svelte';
@@ -28,6 +28,7 @@
 	import DateField from './DateField.svelte';
 	import ArrayField from './ArrayField.svelte';
 	import ObjectField from './ObjectField.svelte';
+	import VariantField from './VariantField.svelte';
 	import DiagnosticList from './DiagnosticList.svelte';
 	import FieldLabel from './FieldLabel.svelte';
 
@@ -91,14 +92,22 @@
 	// control's `YYYY-MM-DD`. An object-valued default does not ghost.
 	const ghost = $derived(ghostDefault(provenance));
 	const defaultStr = $derived(stringifyGhost(ghost));
+	// A variant resolves as one rung whose value is the whole container, so the
+	// discriminant's ghost is that container's own discriminant cell.
+	const ghostMember = $derived(
+		(ghost as Record<string, unknown> | undefined)?.[VARIANT_DISCRIMINANT] as string | undefined
+	);
 
 	// `for` reaches a labelable control and the browser does the rest. The other four
 	// are not labelable (the prose leaf's `contenteditable`, the date field's segment
 	// container, the object subform, an array's N inputs) so `for` there would be
 	// both inert and invalid markup; they take `aria-labelledby` and a click handoff.
+	// A variant is labelable through its discriminant: the select is the one control
+	// the field's label names, and its cells carry composed names of their own.
 	const labelable = $derived(
 		field.control === 'text' ||
 			field.control === 'enum' ||
+			field.control === 'variant' ||
 			field.control === 'number' ||
 			field.control === 'boolean'
 	);
@@ -120,7 +129,7 @@
 	let arrayEl = $state<
 		| {
 				focus: () => void;
-				focusElement: (k: number) => void;
+				focusElement: (k: number, pos?: number) => void;
 				washBox: () => HTMLElement | undefined;
 		  }
 		| undefined
@@ -133,8 +142,8 @@
 	}
 	/** The array's per-ELEMENT landing, for the addresses the preview mints under an
 	 *  array field (`leaves.ts`); read at the call, so it tracks the mounted repeater. */
-	function focusElement(k: number): void {
-		arrayEl?.focusElement(k);
+	function focusElement(k: number, pos?: number): void {
+		arrayEl?.focusElement(k, pos);
 	}
 	// Only where `for` cannot reach; the labelable four are the browser's own, and a
 	// second handler over them would be a focus the label already placed.
@@ -229,6 +238,19 @@
 					{optionAllowed}
 					{enumDisallowed}
 				/>
+			{:else if field.control === 'variant'}
+				<VariantField
+					value={value as Record<string, unknown> | undefined}
+					schema={field.schema}
+					{ghostMember}
+					label={field.label}
+					id={domIds.control}
+					labelledBy={domIds.label}
+					{describedBy}
+					onCommit={onCommitScalar}
+					{optionAllowed}
+					{enumDisallowed}
+				/>
 			{:else if field.control === 'number'}
 				<NumberField
 					value={value as number | undefined}
@@ -265,6 +287,7 @@
 					description={field.description}
 					labelId={domIds.label}
 					descriptionId={domIds.description}
+					idBase={domIds.control}
 					elementContent={(i) => quill.reader(doc).getContentAt(addr, [i])}
 					onCommit={onCommitScalar}
 				/>
@@ -274,6 +297,7 @@
 					value={value as Record<string, unknown> | undefined}
 					properties={field.schema.properties}
 					label={field.label}
+					idBase={domIds.control}
 					labelledBy={domIds.label}
 					{describedBy}
 					onCommit={onCommitScalar}

package/dist/visual/FieldLabel.svelte

@@ -11,8 +11,8 @@
  element is inert and invalid.
 
  Two non-gating label decorations:
- • a persistent required `*` for a field the schema obliges (`must_fill`, which
- derives from a missing `default:`; DOCUMENT_MODEL). Its
+ • a persistent required `*` for a field the schema obliges — one that declares no
+ `default:` (DOCUMENT_MODEL). Its
  accessible name is "required", so a screen reader announces the word, not the
  glyph; inside the `<label>`, so it names the control along with the text
  ("Subject required") rather than announcing as a node adjacent to it;

package/dist/visual/FormatPopover.svelte

@@ -277,6 +277,18 @@
 		sync();
 	}
 
+	/**
+	 * A fresh anchor id: 128 random bits as hex, the id being opaque to the
+	 * boundary and needing only to be unique. `crypto.randomUUID` is
+	 * secure-context-only, and absent on a page served over plain `http` to
+	 * something other than localhost; `getRandomValues` is there either way.
+	 */
+	function mintAnchorId(): string {
+		return [...crypto.getRandomValues(new Uint8Array(16))]
+			.map((b) => b.toString(16).padStart(2, '0'))
+			.join('');
+	}
+
 	/**
 	 * Toggle an identity anchor over the selection: the `anchor`
 	 * button's answer to a formatting toggle. If the selection already covers
@@ -292,7 +304,7 @@
 		const { from, to } = leaf.selectionRange();
 		const covered = leaf.anchorsInRange(from, to);
 		if (covered.length) covered.forEach((id) => leaf.removeAnchor(id));
-		else leaf.insertAnchor(crypto.randomUUID(), from);
+		else leaf.insertAnchor(mintAnchorId(), from);
 		view.focus();
 		sync();
 	}