@quillmark/svelte 0.5.1 → 0.7.0

package/dist/visual/ObjectField.svelte

@@ -4,6 +4,14 @@
  only: a nested prose/array/object property renders a placeholder instead of
  recursing.
 
+ The nesting is a vertical at `--_qm-border`, the ladder's last stroke: the card's edge,
+ an open section's vertical one `--_qm-nest` in where the field is in one, this one a rung
+ further, the properties a rung inside it (ARCHITECTURE §"A plane is a tone").
+
+ One figure wherever it mounts: a variant's cells under their discriminant and an array
+ element's properties under its summary row sit at the depth a field-level subform sits
+ at, and the box above them states position rather than depth.
+
  A property's ghosted `default:` is the static schema `sub.default`, not the
  resolved provenance the top-level ghosts read (FIELD_PROVENANCE): `resolve`
  carries no per-property row (an object field resolves as one row whose value is
@@ -11,7 +19,10 @@
 -->
 <script lang="ts">
 	import type { QuillFieldSchema } from '@quillmark/wasm';
-	import { controlKind, humanize } from './structure.js';
+	import { controlKind, humanize, obliged } from './structure.js';
+	import { wording } from './strings.js';
+	import { propertyDomIds } from './domid.js';
+	import FieldLabel from './FieldLabel.svelte';
 	import TextField from './TextField.svelte';
 	import EnumField from './EnumField.svelte';
 	import NumberField from './NumberField.svelte';
@@ -21,21 +32,42 @@
 	interface Props {
 		value: Record<string, unknown> | undefined;
 		properties: Record<string, QuillFieldSchema> | undefined;
-		/** Accessible-name prefix for the property controls. */
-		label?: string;
 		/** The field label's own id. A subform is a group of controls, not one control
-		 * `for` could reach, so the field's label names the set and each property
-		 * control keeps its own composed `aria-label`. */
+		 * `for` could reach, so the field's label names the set; each property carries
+		 * its own `<label for>` inside it. */
 		labelledBy?: string;
 		/** The parked `description` (FieldLabel): announced on entering the group. */
 		describedBy?: string;
+		/**
+		 * The parent control's DOM id: the base each property's own three names derive
+		 * from ({@link propertyDomIds}). Absent — a subform mounted with no field around
+		 * it — the properties fall back to `aria-label`, which names them without a
+		 * `for` target to click.
+		 */
+		idBase?: string;
+		/** Accessible-name prefix used only on the `aria-label` fallback above. */
+		label?: string;
 		onCommit: (obj: Record<string, unknown>) => void;
 	}
-	let { value, properties, label, labelledBy, describedBy, onCommit }: Props = $props();
+	let { value, properties, labelledBy, describedBy, idBase, label, onCommit }: Props = $props();
 
+	const t = wording();
 	const entries = $derived(Object.entries(properties ?? {}));
 	const obj = $derived((value ?? {}) as Record<string, unknown>);
 
+	/** Obligation, read off the cell exactly as `fieldModels` reads it off a field
+	 *  ({@link obliged}). `validate` anchors it per leaf, so a property with no
+	 *  `default:` is obliged in its own right and the container around it holds none
+	 *  (VISUAL_EDITOR §"Enum variants"). */
+	const required = obliged;
+
+	const title = (key: string, sub: QuillFieldSchema): string => sub.ui?.title ?? humanize(key);
+	/** The `aria-label` fallback, for a subform mounted without a field's id space:
+	 *  the field's name and the property's, since nothing else names the control. */
+	const fallbackName = (key: string, sub: QuillFieldSchema): string =>
+		`${label != null ? `${label} ` : ''}${title(key, sub)}` +
+		(required(sub) ? ` ${t.strings.fieldRequired}` : '');
+
 	/** Take the caret: the first property's control, a subform having no single control
 	 * of its own to land on. Resolved off the DOM rather than a ref per property: every
 	 * property is a scalar control the DOM already knows how to focus (the date field's
@@ -43,10 +75,19 @@
 	 * handle each would be five refs restating document order. An empty or wholly
 	 * unsupported subform lands nothing. */
 	let rootEl = $state<HTMLElement | undefined>();
+	const FOCUSABLE = 'input, select, button, [tabindex]:not([tabindex="-1"])';
 	export function focus(): void {
-		rootEl
-			?.querySelector<HTMLElement>('input, select, button, [tabindex]:not([tabindex="-1"])')
-			?.focus();
+		rootEl?.querySelector<HTMLElement>(FOCUSABLE)?.focus();
+	}
+	/** A label click for the one property `for` cannot reach: the date control, whose
+	 *  focus lives on a segment. Scoped to that property's own cell, so the click lands
+	 *  where the label is rather than on the subform's first control. */
+	function focusProp(key: string): void {
+		// Matched on the dataset: a key is the schema's own string, and spelling one into
+		// a selector needs `CSS.escape`, which the test DOM does not carry.
+		for (const cell of rootEl?.querySelectorAll<HTMLElement>('[data-qm-prop]') ?? []) {
+			if (cell.dataset.qmProp === key) return cell.querySelector<HTMLElement>(FOCUSABLE)?.focus();
+		}
 	}
 
 	function commitProp(key: string, v: unknown): void {
@@ -72,12 +113,31 @@
 >
 	{#each entries as [key, sub] (key)}
 		{@const kind = controlKind(sub)}
-		{@const propLabel = `${label != null ? `${label} ` : ''}${sub.ui?.title ?? humanize(key)}`}
-		<div class="qm-object-prop">
-			<span class="qm-object-label">{sub.ui?.title ?? humanize(key)}</span>
+		{@const ids = idBase ? propertyDomIds(idBase, key) : undefined}
+		{@const named = ids ? undefined : fallbackName(key, sub)}
+		{@const describes = sub.description && ids ? ids.description : undefined}
+		<!-- `for` reaches the four labelable controls; the date field's focus lives on a
+		     segment, so it takes the click handoff instead, exactly as `Field` does one
+		     level up. -->
+		{@const labelable =
+			kind === 'text' || kind === 'enum' || kind === 'number' || kind === 'boolean'}
+		<div class="qm-object-prop" data-qm-prop={key}>
+			{#if ids}
+				<FieldLabel
+					label={title(key, sub)}
+					controlId={labelable ? ids.control : undefined}
+					id={ids.label}
+					descriptionId={describes}
+					onActivate={labelable ? undefined : () => focusProp(key)}
+					required={required(sub)}
+					description={sub.description}
+				/>
+			{/if}
 			{#if kind === 'enum'}
 				<EnumField
-					label={propLabel}
+					label={named}
+					id={ids?.control}
+					describedBy={describes}
 					value={obj[key] as string | undefined}
 					values={sub.values ?? []}
 					fallback={sub.default as string | undefined}
@@ -85,7 +145,9 @@
 				/>
 			{:else if kind === 'number'}
 				<NumberField
-					label={propLabel}
+					label={named}
+					id={ids?.control}
+					describedBy={describes}
 					value={obj[key] as number | undefined}
 					integer={sub.type === 'integer'}
 					fallback={sub.default as number | undefined}
@@ -93,54 +155,85 @@
 				/>
 			{:else if kind === 'boolean'}
 				<BooleanField
-					label={propLabel}
+					label={named}
+					id={ids?.control}
+					describedBy={describes}
 					value={obj[key] as boolean | undefined}
 					fallback={sub.default as boolean | undefined}
 					onCommit={(v) => commitProp(key, v)}
 				/>
 			{:else if kind === 'date'}
 				<DateField
-					label={propLabel}
+					label={named}
+					labelledBy={ids?.label}
+					describedBy={describes}
 					value={obj[key] as string | undefined}
 					onCommit={(v) => commitProp(key, v)}
 				/>
 			{:else if kind === 'text'}
 				<TextField
-					label={propLabel}
+					label={named}
+					id={ids?.control}
+					describedBy={describes}
 					value={obj[key] as string | undefined}
 					placeholder={sub.default != null ? String(sub.default) : undefined}
 					onCommit={(v) => commitProp(key, v)}
 				/>
 			{:else}
-				<span class="qm-unsupported">({kind} property — not editable in V1)</span>
+				<!-- A property the subform does not recurse into. What it says is what the
+				     user can do about it, which is edit the field from the source surface;
+				     a version number is the roadmap talking to somebody filling in a form. -->
+				<span class="qm-unsupported">{t.strings.nestedUnsupported(kind)}</span>
 			{/if}
 		</div>
 	{/each}
 </div>
 
 <style>
+	/* The vertical and the rung between it and the properties, `--_qm-nest` being the step
+	   the card and the section hold too.
+
+	   `--_qm-border` and not `--_qm-border-faint`: this is the stroke that structures
+	   (ARCHITECTURE §"A plane is a tone"), the one the card's edge and the section's
+	   vertical read. `faint` separates without structuring — a table's interior lines
+	   under a frame that is doing the structuring — which is the other job.
+
+	   `padding-block` is the stroke's end caps, the same rung and the same reason as a
+	   section's (`Card.svelte`). A cap and not a leading gap: what stands the subform off
+	   the label or the box above it is still that stacker's own.
+
+	   The tracks are the section's count over the subform's own width — `--cols` inherits,
+	   so the container query stepping the section's capacity steps this with it, and there
+	   is no second query container and nothing measured. The edges are not the section's:
+	   the inset is the nesting, and a cell lining up with the field above it would claim a
+	   depth it is not at. */
 	.qm-object {
-		display: flex;
-		flex-direction: column;
+		display: grid;
+		grid-template-columns: repeat(var(--cols), 1fr);
 		gap: var(--_qm-space-2);
-		border-left: var(--_qm-border-width) solid var(--_qm-border);
-		padding-left: var(--_qm-space-2);
+		border-inline-start: var(--_qm-border-width) solid var(--_qm-border);
+		padding-inline-start: var(--_qm-nest);
+		padding-block: var(--_qm-space);
 	}
+	/* A property measures like a field: two tracks over the subform's own rows, so a
+	   label wrapping in one column leaves its control on the row's baseline rather than a
+	   line below it — `Field.svelte`'s rule for a row-sharing field, one level in. The
+	   tracks are this grid's own; the section's belong to the fields.
+
+	   `min-width: 0` because a property overflowing its `1fr` grows the track, and the
+	   subform with it, past the field that holds it. */
 	.qm-object-prop {
-		display: flex;
-		flex-direction: column;
-		gap: var(--_qm-space-half);
+		display: grid;
+		grid-row: span 2;
+		grid-template-rows: subgrid;
+		row-gap: var(--_qm-space-half);
+		align-items: start;
+		min-width: 0;
 	}
-	.qm-object-label {
-		font-size: var(--_qm-text-label);
-		/* The chrome weight, the same one the field label above it takes: what says
-		   this name is nested is the subform's rule and its inset, so a weight step
-		   here would state it twice and rank two names the ramp does not separate. */
-		font-weight: var(--_qm-weight-mid);
-		/* A label is a line, not a passage, so it overrides the root's reading
-		   rhythm the way every other label rung does. */
-		line-height: var(--_qm-leading-tight);
-		color: var(--_qm-ink-label);
+	/* A subform of one takes half the capacity, the way a packable run of one does
+	   (`.qm-field.lone`): at full capacity a single track reads as truncated. */
+	.qm-object-prop:only-child {
+		grid-column: span var(--cols-half);
 	}
 	.qm-unsupported {
 		font-size: var(--_qm-text-body);

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

@@ -2,14 +2,21 @@ import type { QuillFieldSchema } from '@quillmark/wasm';
 interface Props {
     value: Record<string, unknown> | undefined;
     properties: Record<string, QuillFieldSchema> | undefined;
-    /** Accessible-name prefix for the property controls. */
-    label?: string;
     /** The field label's own id. A subform is a group of controls, not one control
-     * `for` could reach, so the field's label names the set and each property
-     * control keeps its own composed `aria-label`. */
+     * `for` could reach, so the field's label names the set; each property carries
+     * its own `<label for>` inside it. */
     labelledBy?: string;
     /** The parked `description` (FieldLabel): announced on entering the group. */
     describedBy?: string;
+    /**
+     * The parent control's DOM id: the base each property's own three names derive
+     * from ({@link propertyDomIds}). Absent — a subform mounted with no field around
+     * it — the properties fall back to `aria-label`, which names them without a
+     * `for` target to click.
+     */
+    idBase?: string;
+    /** Accessible-name prefix used only on the `aria-label` fallback above. */
+    label?: string;
     onCommit: (obj: Record<string, unknown>) => void;
 }
 declare const ObjectField: import("svelte").Component<Props, {

package/dist/visual/ProseArrayElement.svelte

@@ -17,14 +17,16 @@
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
-	import { EditorState } from 'prosemirror-state';
+	import { EditorState, Selection } from 'prosemirror-state';
 	import { EditorView } from 'prosemirror-view';
 	import {
 		decode,
 		pmToContent,
 		inlineSchema,
 		plaintextSchema,
-		proseLeafPlugins
+		proseLeafPlugins,
+		buildLineIndex,
+		usvToPM
 	} from '../core/codec/index.js';
 	import './controls.css';
 	import type { Content } from '@quillmark/wasm';
@@ -61,6 +63,24 @@
 		view.focus();
 		view.dom.scrollIntoView({ block: 'nearest' });
 	}
+	/** Take the caret to USV `pos` in this element's own content: what a landing on an
+	 * element address resolves to when the compile answered a cluster-exact offset
+	 * (`leaves.ts`). `createField`'s body over the view this component owns.
+	 *
+	 * The index is built here rather than held: a landing is a discrete act, and one
+	 * doc walk per click is cheaper than a cache to invalidate per keystroke. `usvToPM`
+	 * clamps, so an offset past a value the compile has moved on from lands the end.
+	 *
+	 * `Selection.near`, not `TextSelection.create`: the mapped position can be
+	 * non-inline. Focus first, then the caret, flagged for scroll — the order and the
+	 * reasons are `FieldController.setCaret`'s (`codec/field.ts`). */
+	export function setCaret(pos: number): void {
+		if (!view) return;
+		const pm = usvToPM(buildLineIndex(view.state.doc), pos);
+		const sel = Selection.near(view.state.doc.resolve(pm));
+		view.focus();
+		view.dispatch(view.state.tr.setSelection(sel).scrollIntoView());
+	}
 
 	onMount(() => {
 		if (!containerEl) return;

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

@@ -19,6 +19,7 @@ interface Props {
 }
 declare const ProseArrayElement: import("svelte").Component<Props, {
     focus: () => void;
+    setCaret: (pos: number) => void;
 }, "">;
 type ProseArrayElement = ReturnType<typeof ProseArrayElement>;
 export default ProseArrayElement;

package/dist/visual/SlashMenu.svelte

@@ -72,8 +72,15 @@
 		     edge under the character that opened the menu, and stays there as the query is
 		     typed. Zero offset, because a gap reads as a surface floating near the caret
 		     rather than one growing out of it. -->
+		<!-- The boundary is the root the surface portals into, the box that clips it where
+		     the consumer scrolls one ({@link FormatPopover} states it in full). It is also
+		     what keeps the row scroll above inside the list: `nearest` scrolls any ancestor
+		     the row is not visible in, and a surface raised into room the pane clips leaves
+		     the pane one of them — so the scroll moves the pane, and with it the caret this
+		     menu is anchored to. -->
 		<Popover.Content
 			customAnchor={menu?.anchor ?? null}
+			collisionBoundary={portalTarget ?? []}
 			side="bottom"
 			align="start"
 			trapFocus={false}

package/dist/visual/TipsCard.svelte

@@ -97,27 +97,34 @@
 	 paints over the rest. The two read as one block, which is what document-level
 	 guidance is: the main card's, not a card of its own. Still in-flow, no lift.
 
-	 It takes the card's hairline, and the tuck makes the two outlines one: the slip's top
-	 stroke and the tops of its sides run under `main`, so what shows starts at the card's
-	 bottom corners.
+	 No stroke of its own. A tint below the card reads as a slip; the same tint inside an
+	 outline reads as a second card, which is the one thing the tuck exists to deny. What
+	 shows below the seam is fill, and `main`'s hairline is the pair's only edge.
 
 	 The bottom corners take the inner rung where the card above takes the outer: a slip
 	 is cut crisper than the thing it is tucked under, at every setting of the dial.
 
-	 The insets are asymmetric so the ink is not: the top takes the tuck back, and the
-	 bottom gives up a rung to the foot's control, whose box stands on the tap floor
-	 rather than on its own one-line label. The horizontal is the card's inset plus the
-	 body's margin (ProseField), so the tip starts under the prose rather than under the
-	 fields. */
+	 Down, the insets are the document's own rhythm and they are measured to the ink, not
+	 to the boxes. The top is a block gap below the seam, what two of the body's paragraphs
+	 take, so the tip reads as the block after the prose; the bottom is the card's inset
+	 rung; and the foot sits at half of either, being the message's own foot rather than
+	 the next thing after it. The control gives its tap floor back as margin for that to
+	 hold: a box standing on the floor rather than on its one-line label carries a rung of
+	 slack at each edge, and spent inside the gap that is enough to make the tightest space
+	 in the card measure as the widest.
+
+	 Across, the inset is `main`'s stroke and the two nested insets under it, the card's
+	 own and the prose control's, so the tip starts on the prose's edge rather than short
+	 of it. */
 	.qm-tips {
 		margin-top: calc(var(--_qm-radius) * -1);
-		border: var(--_qm-border-width) solid var(--_qm-border);
 		border-radius: 0 0 var(--_qm-radius-inner) var(--_qm-radius-inner);
-		padding: calc(var(--_qm-space-3) + var(--_qm-radius)) var(--_qm-space-5) var(--_qm-space-2);
+		padding: calc(var(--_qm-space-3) + var(--_qm-radius))
+			calc(var(--_qm-border-width) + var(--_qm-space-3) * 2) var(--_qm-space-3);
 		background: var(--_qm-tips-surface);
 		display: flex;
 		flex-direction: column;
-		gap: var(--_qm-space-2);
+		gap: var(--_qm-space);
 		font-family: var(--_qm-tips-font);
 		font-size: var(--_qm-text-body);
 		line-height: var(--_qm-leading-body);
@@ -168,7 +175,11 @@
 	 the spacing one — the foot's button clears the floor and walks the whole set from
 	 the tip the card opens on, so no tip is reachable only by a dot. State is three
 	 steps of one ink on the recede ladder, never a second hue and never a size: a dot
-	 that grew would move the row it sits in. */
+	 that grew would move the row it sits in.
+
+	 `color` is restated because a button takes the UA's and not its parent's, so
+	 `currentColor` is the card's ink only once it is inherited; left to the UA it is
+	 `buttontext`, which is the one neutral on a card that carries no neutrals. */
 	.qm-tips-dot {
 		box-sizing: content-box;
 		width: 5px;
@@ -176,6 +187,7 @@
 		padding: var(--_qm-space-half);
 		border: none;
 		border-radius: var(--_qm-radius-pill);
+		color: inherit;
 		background: currentColor;
 		background-clip: content-box;
 		opacity: var(--_qm-opacity-idle);
@@ -192,8 +204,16 @@
 	   overrides is everything the family sets for a glyph among callers of its own
 	   colour, a labelled control on a warm card wanting none of it. The hover included:
 	   the family's neutral step would read as lent from the document above. Unlayered,
-	   so it beats the base rule without out-specifying it. */
+	   so it beats the base rule without out-specifying it.
+
+	   The box is the tap target and the label is what the rhythm measures, so both axes
+	   give the difference back as margin: the inline rung lands the label on the body's
+	   edge above, and the block rung takes the floor's slack out of the foot's height.
+	   The box, and the hover it paints, still reaches past the label the way a control
+	   does. */
 	.qm-tips-action {
+		margin-block: calc(var(--_qm-space) * -1);
+		margin-right: calc(var(--_qm-space-2) * -1);
 		padding: var(--_qm-space-half) var(--_qm-space-2);
 		font-family: inherit;
 		font-size: inherit;

package/dist/visual/VariantField.svelte

@@ -0,0 +1,95 @@
+<!--
+ An `enum` declaring `variants:` → the discriminant's select, and under it the cells
+ the chosen world brings into play (VISUAL_EDITOR §"Enum variants"). The field rests as
+ a container, `{value: <member>, …that member's fields}`, and commits whole: it is one
+ cell to `Addr`, so there is no per-cell write address.
+
+ The cells are {@link ObjectField}, which already draws a scalar field set keyed by
+ name over a container its parent commits by value. It takes the whole container as its
+ `value` and the world's declaration as its `properties`, so what it hands back is the
+ container with one cell written — and cells outside the drawn world ride through
+ untouched rather than needing to be merged back.
+-->
+<script lang="ts">
+	import type { QuillFieldSchema } from '@quillmark/wasm';
+	import EnumField from './EnumField.svelte';
+	import ObjectField from './ObjectField.svelte';
+	import {
+		VARIANT_DISCRIMINANT,
+		commitDiscriminant,
+		variantCells,
+		variantMember
+	} from './structure.js';
+
+	interface Props {
+		/** The stored container, or undefined while the field is unset. */
+		value: Record<string, unknown> | undefined;
+		schema: QuillFieldSchema;
+		/** The resolved `default:`'s member: what an unset field renders as. */
+		ghostMember: string | undefined;
+		/** Field label, the naming prefix the cells' controls compose with. */
+		label: string;
+		/** `<label for>` target: the discriminant trigger, this control's one labelable
+		 * element. The cells are named by their own composed labels. */
+		id?: string;
+		labelledBy?: string;
+		describedBy?: string;
+		onCommit: (v: Record<string, unknown> | undefined) => void;
+		optionAllowed?: (value: string) => boolean;
+		enumDisallowed?: 'hide' | 'disable';
+	}
+	let {
+		value,
+		schema,
+		ghostMember,
+		label,
+		id,
+		labelledBy,
+		describedBy,
+		onCommit,
+		optionAllowed,
+		enumDisallowed
+	}: Props = $props();
+
+	const member = $derived(variantMember(value, ghostMember));
+	const cells = $derived(variantCells(schema, member));
+	const discriminant = $derived(value?.[VARIANT_DISCRIMINANT] as string | undefined);
+</script>
+
+<div class="qm-variant">
+	<EnumField
+		value={discriminant}
+		values={schema.values ?? []}
+		fallback={ghostMember}
+		{id}
+		{describedBy}
+		onCommit={(v) => onCommit(commitDiscriminant(value, v))}
+		{optionAllowed}
+		{enumDisallowed}
+	/>
+	<!-- Keyed on the member so a flip remounts the cells rather than re-targeting
+	     them: two worlds' cells are different fields that happen to occupy one place,
+	     and a control carrying local state (an unreconciled pick, a caret) across the
+	     flip would carry it between them. -->
+	{#if cells}
+		{#key member}
+			<ObjectField
+				value={value ?? {}}
+				properties={cells}
+				{label}
+				idBase={id}
+				{labelledBy}
+				{describedBy}
+				onCommit={(obj) => onCommit(obj)}
+			/>
+		{/key}
+	{/if}
+</div>
+
+<style>
+	.qm-variant {
+		display: flex;
+		flex-direction: column;
+		gap: var(--_qm-space-2);
+	}
+</style>

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

@@ -0,0 +1,21 @@
+import type { QuillFieldSchema } from '@quillmark/wasm';
+interface Props {
+    /** The stored container, or undefined while the field is unset. */
+    value: Record<string, unknown> | undefined;
+    schema: QuillFieldSchema;
+    /** The resolved `default:`'s member: what an unset field renders as. */
+    ghostMember: string | undefined;
+    /** Field label, the naming prefix the cells' controls compose with. */
+    label: string;
+    /** `<label for>` target: the discriminant trigger, this control's one labelable
+     * element. The cells are named by their own composed labels. */
+    id?: string;
+    labelledBy?: string;
+    describedBy?: string;
+    onCommit: (v: Record<string, unknown> | undefined) => void;
+    optionAllowed?: (value: string) => boolean;
+    enumDisallowed?: 'hide' | 'disable';
+}
+declare const VariantField: import("svelte").Component<Props, {}, "">;
+type VariantField = ReturnType<typeof VariantField>;
+export default VariantField;