@quillmark/svelte 0.11.0 → 0.13.0

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

@@ -1,8 +1,19 @@
 import type { Content, PathStep, QuillFieldSchema } from '@quillmark/wasm';
+import { type ArrayLayout } from './structure.js';
+import { type DeepDiagnostic } from './diagnostics.js';
+import type { LandingBox } from './leaves.js';
 import './controls.css';
 interface Props {
     value: unknown[] | undefined;
+    /** The declared `default:`: the rows an unset array draws, which a gesture takes. */
+    fallback?: unknown[];
     items: QuillFieldSchema | undefined;
+    /** How the elements draw: the record list, or the table an `array<object>` of
+     * short cells asks for (`arrayLayout`). */
+    layout?: ArrayLayout;
+    /** The schema's `max:`, past which the add chip disables and Enter stops
+     * inserting; `undefined` is no cap. */
+    max?: number;
     /** Accessible-name prefix for the element controls (`label` + 1-based index). */
     label?: string;
     /** No-default field → a persistent required `*` on the label. */
@@ -28,11 +39,15 @@ interface Props {
      * control has spliced in and whose commit has yet to land, or was refused. */
     contentAt: (path: PathStep[]) => Content | undefined;
     onCommit: (arr: unknown[]) => void;
+    /** The diagnostics routed into this array, each with its steps still to walk: one
+     * naming a row draws under that row — under its head while it is collapsed, under
+     * the cell once it is open — and one naming no row draws at the list's foot. */
+    diagnostics?: readonly DeepDiagnostic[];
 }
 declare const ArrayField: import("svelte").Component<Props, {
     focus: () => void;
     washBox: () => HTMLElement | undefined;
-    focusElement: (k: number, pos?: number) => HTMLElement | undefined;
+    focusPath: (steps: readonly PathStep[], pos?: number) => LandingBox;
 }, "">;
 type ArrayField = ReturnType<typeof ArrayField>;
 export default ArrayField;

package/dist/visual/BooleanField.svelte

@@ -4,6 +4,12 @@
  Styled rather than a native checkbox: the native box's face is UA-owned shadow
  DOM, so no dial reaches it. The a11y comes with the primitive:
  Switch.Root renders `role="switch"` with its checked state and keyboard handling.
+
+ An unset `boolean?` prints `none`, which neither face of a switch says, so it draws a
+ third: the thumb at the track's centre. `role="switch"` admits no third state (a
+ `mixed` there reads as false), so an optional boolean's control is a `checkbox`, the
+ toggle role that does, announcing `mixed` while unset. A press from unset writes
+ `true`; nothing here returns the cell to unset.
 -->
 <script lang="ts">
 	import { Switch } from 'bits-ui';
@@ -13,6 +19,8 @@
 	interface Props {
 		value: boolean | undefined;
 		fallback?: boolean;
+		/** A `boolean?` cell, which has a third state: unset, printing `none`. */
+		optional?: boolean;
 		/** 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. */
@@ -26,29 +34,42 @@
 		describedBy?: string;
 		onCommit: (v: boolean) => void;
 	}
-	let { value, fallback, label, id, describedBy, onCommit }: Props = $props();
+	let { value, fallback, optional = false, label, id, describedBy, onCommit }: Props = $props();
 
 	// 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
 	// 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);
+	// which repeats the reconciliation hazard in miniature. `undefined` is the unset
+	// optional cell, the one state with no default to stand in for it.
+	const local = syncedLocal<boolean | undefined>(
+		() => value ?? fallback ?? (optional ? undefined : false)
+	);
+	const unset = $derived(local.value === undefined);
+	const tristate = $derived(
+		optional ? { role: 'checkbox', 'aria-checked': unset ? ('mixed' as const) : !!local.value } : {}
+	);
 </script>
 
-<span class="qm-switch-wrap">
+<!-- Not `.qm-switch`: that name is the preset's pane band, whose narrow-viewport rule
+ stands every child of it at `--qmh-tap`, so a track wearing it grows a thumb three times
+ its own height over the labels around it (`preset/recipes.css`, held by `check:style`). -->
+<span class="qm-toggle-wrap" data-unset={unset ? '' : undefined}>
 	<Switch.Root
-		class="qm-switch qm-focus-ring qm-tap-floor"
-		checked={local.value}
+		class="qm-toggle qm-focus-ring qm-tap-floor"
+		checked={!!local.value}
 		{id}
 		aria-label={id ? undefined : label}
 		aria-describedby={describedBy}
 		onCheckedChange={(v) => {
+			// From unset the primitive reads the unchecked face, so its toggle is `true`.
 			local.value = v;
 			onCommit(v);
 		}}
 	>
-		<Switch.Thumb class="qm-switch-thumb" />
+		{#snippet child({ props })}
+			<button {...props} {...tristate}><Switch.Thumb class="qm-toggle-thumb" /></button>
+		{/snippet}
 	</Switch.Root>
 </span>
 
@@ -60,7 +81,7 @@
 	 2.5.8's floor is half again that. The `<label for>` beside it forwards a press but
 	 stands at the label rung, so it is no taller: without the floor no region on the
 	 surface reaches this control at the size every other control on it holds. */
-	.qm-switch-wrap :global(.qm-switch) {
+	.qm-toggle-wrap :global(.qm-toggle) {
 		display: inline-flex;
 		align-items: center;
 		width: 1.75rem;
@@ -75,21 +96,25 @@
 		cursor: pointer;
 		transition: background var(--_qm-duration-fast) var(--_qm-ease-reverse);
 	}
-	.qm-switch-wrap :global(.qm-switch[data-state='checked']) {
+	.qm-toggle-wrap :global(.qm-toggle[data-state='checked']) {
 		background: 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
 	 unchecked, and over `--_qm-accent` checked. No edge of its own: a hairline around
 	 a 12px pill is a second box inside the track's. */
-	.qm-switch-wrap :global(.qm-switch-thumb) {
+	.qm-toggle-wrap :global(.qm-toggle-thumb) {
 		width: 0.75rem;
 		height: 0.75rem;
 		border-radius: var(--_qm-radius-pill);
 		background: var(--_qm-surface);
 		transition: translate var(--_qm-duration-fast) var(--_qm-ease-reverse);
 	}
-	.qm-switch-wrap :global(.qm-switch-thumb[data-state='checked']) {
+	.qm-toggle-wrap :global(.qm-toggle-thumb[data-state='checked']) {
 		translate: 0.75rem;
 	}
+	/* Unset, the thumb stands at neither end: halfway along its travel. */
+	.qm-toggle-wrap[data-unset] :global(.qm-toggle-thumb) {
+		translate: 0.375rem;
+	}
 </style>

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

@@ -2,6 +2,8 @@ import './controls.css';
 interface Props {
     value: boolean | undefined;
     fallback?: boolean;
+    /** A `boolean?` cell, which has a third state: unset, printing `none`. */
+    optional?: boolean;
     /** 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. */

package/dist/visual/Card.svelte

@@ -15,7 +15,7 @@
 	import type { EditorErrorHandler } from '../core/errors.js';
 	import type { LeafRegistry } from './leaves.js';
 	import type { CardModel, FieldModel } from './structure.js';
-	import { placeFields, humanize, initialExpandedGroup } from './structure.js';
+	import { placeFields, humanize, initialExpandedGroup, kindTitle, mountKey } from './structure.js';
 	import { holdInView } from './hold.js';
 	import type { FieldDomIds } from './domid.js';
 	import Field from './Field.svelte';
@@ -332,8 +332,8 @@
 </section>
 
 {#snippet sectionFields(fields: FieldModel[])}
-	<div class="qm-fields">
-		{#each placeFields(fields) as { field: f, span } (f.name)}
+	<div class="qm-fields qm-tracks">
+		{#each placeFields(fields) as { field: f, span } (mountKey(f.name, f.schema))}
 			<Field
 				field={f}
 				{span}
@@ -402,7 +402,7 @@
 
 {#snippet kindOptions()}
 	{#each kinds as k (k)}
-		<option value={k}>{humanize(k)}</option>
+		<option value={k}>{kindTitle(quill.schema.card_kinds?.[k], k)}</option>
 	{/each}
 {/snippet}
 
@@ -584,33 +584,14 @@
 	.qm-group-panel-inner {
 		container-type: inline-size;
 	}
-	/* Capacity is the container's, not JavaScript's: nothing measures, so there is no
-	 observer to loop and no re-packing to restructure the DOM under a prose leaf.
-
-	 It steps 1 → 2 → 4, skipping 3: each rung is the width at which a track still clears
-	 the comfortable field minimum, and an even capacity is what lets the half a subform
-	 of one takes (`--cols-half`, `ObjectField`) land on a track boundary. A field ends on
-	 its track's own edge, so a rung is `n * 220px + gaps`. */
+	/* The count is the ladder's (`.qm-tracks`, controls.css), stepped by the container
+	 above; what this block owns is the grid the count fills. */
 	.qm-fields {
-		--cols: 1;
-		--cols-half: 1;
 		display: grid;
 		grid-template-columns: repeat(var(--cols), 1fr);
 		column-gap: var(--_qm-space-2);
 		row-gap: var(--_qm-space-3);
 	}
-	@container (min-width: 28rem) {
-		.qm-fields {
-			--cols: 2;
-			--cols-half: 1;
-		}
-	}
-	@container (min-width: 57rem) {
-		.qm-fields {
-			--cols: 4;
-			--cols-half: 2;
-		}
-	}
 	/* 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

package/dist/visual/DateField.svelte

@@ -23,16 +23,21 @@
  make every reconcile fire and re-render all seven segments on each commit.
 
  The ghost is the default's digits, not a format hint. An unset field
- carrying a `default:` prints the default's digits in the segments, ghost-toned,
- instead of the primitive's `mm`/`dd`/`yyyy` hints, which say "empty" where the
- rung says "will render 2026-01-01". The ghost is painted in the segment snippet,
- over an unset primitive: substituting the default for `value` instead would make
- the field indistinguishable from an authored one to every path that reads it
- (`areAllSegmentsFilled`, Backspace, the hidden input), and the primitive shadows
- a written-back `value` prop it was not `bind:`-ed to, so re-seating the ghost
- after a clear never lands. `placeholder` (the `DateValue` the segments count
- from, never one they display) carries the default too, so arrowing an empty
- segment starts at the render's date rather than today's.
+ carrying a `default:` prints the default's digits in the segments at the default
+ rung (theme.css), instead of the primitive's `mm`/`dd`/`yyyy` hints, which say
+ "empty" where the rung says "will render 2026-01-01". At rest the ghost is painted
+ in the segment snippet, over an unset primitive: a default held as its value reads
+ as filled to every path that reads the primitive (`areAllSegmentsFilled`,
+ Backspace, the hidden input), and whether it stands as the value is the field's to
+ say only once the user enters it. `placeholder`
+ (the `DateValue` the segments count from, never one they display) carries the
+ default too, so arrowing an empty segment starts at the render's date rather than
+ today's.
+
+ Entering an unset field seats the default as the primitive's value, still at the
+ default rung, so an edit to one segment commits a whole date with the others the
+ default's. Leaving without an edit unseats it, and nothing is written; so does
+ clearing a segment.
 -->
 <script lang="ts">
 	import { DateField as BitsDateField } from 'bits-ui';
@@ -85,25 +90,42 @@
 		}
 	}
 
+	const fallbackDate = $derived(toDateValue(fallback?.slice(0, 10) ?? ''));
+	/** The default is the primitive's value: from entering an unset field until an
+	 *  edit, a cleared segment or leaving. Part of the projection, so a reconcile
+	 *  neither drops a seat nor restores one over the segments a clear left. */
+	let seat = $state(false);
 	// Local value synced to `value` as a string (see the identity note above);
 	// own-edits stay local, only an external change reconciles back in. Driven
 	// controlled (`value` + `onValueChange`, never `bind:`) so reconciliation stays
 	// the package's.
-	const local = syncedLocal(() => value?.slice(0, 10) ?? '');
+	const local = syncedLocal(
+		() => value?.slice(0, 10) ?? (seat && fallbackDate ? fallbackDate.toString() : '')
+	);
 	const parsed = $derived(toDateValue(local.value));
 	// The date the empty segments ghost, or undefined when there is nothing to ghost:
 	// the field is unset and the default has a date form. A non-blank local that
 	// fails to parse is AUTHORED-but-malformed, which the empty field states
 	// honestly: the ghost would claim it unset. Held as the parsed value rather than
 	// a boolean so the substitution below narrows on the one fact it needs.
-	const fallbackDate = $derived(toDateValue(fallback?.slice(0, 10) ?? ''));
 	const ghost = $derived(local.value === '' ? fallbackDate : undefined);
+	const seated = $derived(value == null && seat && local.value !== '');
 
-	// What one segment prints, and whether that text is shown-never-written.
+	/** Focus moving between segments is neither an entry nor a leaving. */
+	const within = (e: FocusEvent): boolean => !!wrapEl?.contains(e.relatedTarget as Node | null);
+	function enter(e: FocusEvent): void {
+		if (!within(e) && value == null && fallbackDate) seat = true;
+	}
+	function leave(e: FocusEvent): void {
+		if (!within(e)) seat = false;
+	}
+
+	// What one segment prints, and which rung it takes.
 	//
 	// An unfilled segment is always shown-never-written, whether it prints the
-	// default's digits or the primitive's own `mm`/`dd`/`yyyy` hint: both state
-	// "nothing authored here". Only an unfilled segment ghosts: a half-entered date
+	// default's digits (`default`, the rung of what prints) or the primitive's own
+	// `mm`/`dd`/`yyyy` hint (`hint`, a word about the value): both state "nothing
+	// authored here". Only an unfilled segment ghosts: a half-entered date
 	// holds digits while the value is still undefined (one unfilled segment unsets
 	// the whole field), so ghosting unconditionally would paint over, and dim, the
 	// digits just typed. The segment's own text is the tell: its unfilled hint is
@@ -113,30 +135,36 @@
 	// The separators are `literal` parts, never unfilled; substitution covers the
 	// date parts only, so any time part keeps the primitive's text. Digits are
 	// zero-padded to the segment widths the field displays.
-	function segmentText(part: string, text: string): { text: string; ghosted: boolean } {
-		if (part === 'literal' || /\d/.test(text)) return { text, ghosted: false };
-		if (!ghost) return { text, ghosted: true };
+	type Rung = 'default' | 'hint' | undefined;
+	function segmentText(part: string, text: string): { text: string; ghosted: Rung } {
+		if (part === 'literal' || /\d/.test(text)) return { text, ghosted: undefined };
+		if (!ghost) return { text, ghosted: 'hint' };
 		switch (part) {
 			case 'year':
-				return { text: String(ghost.year).padStart(4, '0'), ghosted: true };
+				return { text: String(ghost.year).padStart(4, '0'), ghosted: 'default' };
 			case 'month':
-				return { text: String(ghost.month).padStart(2, '0'), ghosted: true };
+				return { text: String(ghost.month).padStart(2, '0'), ghosted: 'default' };
 			case 'day':
-				return { text: String(ghost.day).padStart(2, '0'), ghosted: true };
+				return { text: String(ghost.day).padStart(2, '0'), ghosted: 'default' };
 			default:
-				return { text, ghosted: true };
+				return { text, ghosted: 'hint' };
 		}
 	}
 </script>
 
-<span class="qm-date-wrap" bind:this={wrapEl}>
+<span class="qm-date-wrap" bind:this={wrapEl} onfocusin={enter} onfocusout={leave}>
 	<BitsDateField.Root
 		value={parsed}
 		placeholder={fallbackDate}
 		onValueChange={(d) => {
 			// `CalendarDate.toString()` is exactly `YYYY-MM-DD`. A cleared or
-			// half-typed field yields undefined: the unset rung.
-			local.value = d?.toString() ?? '';
+			// half-typed field yields undefined: the unset rung. The primitive reports
+			// its own value again as a segment loses focus, which is no edit, and over a
+			// seated default would write it.
+			const next = d?.toString() ?? '';
+			if (next === local.value) return;
+			local.value = next;
+			if (!d) seat = false;
 			onCommit(d?.toString());
 		}}
 	>
@@ -151,6 +179,7 @@
 			aria-labelledby={labelledBy}
 			aria-describedby={describedBy}
 			data-ghosted={ghost ? '' : undefined}
+			data-default={seated ? '' : undefined}
 		>
 			{#snippet children({ segments })}
 				<!-- Keyed by index: `part` repeats (the `literal` separators between
@@ -160,7 +189,7 @@
 					<BitsDateField.Segment
 						class="qm-date-segment"
 						part={seg.part}
-						data-ghosted={shown.ghosted ? '' : undefined}
+						data-ghosted={shown.ghosted}
 					>
 						{shown.text}
 					</BitsDateField.Segment>
@@ -193,11 +222,17 @@
 	.qm-date-wrap :global(.qm-date-segment:focus) {
 		background: var(--_qm-surface-hover);
 	}
-	/* An unfilled segment is ghost-toned whatever it prints: the resolved `default:`
-	 when there is one to ghost, the `dd`/`mm`/`yyyy` hint when there is not. Shown,
-	 never written, either way. The marker is the component's own (see the snippet):
-	 the date primitive emits no placeholder attribute of its own. */
-	.qm-date-wrap :global(.qm-date-segment[data-ghosted]) {
+	/* An unfilled segment is ghost-toned whatever it prints, at the rung of what it
+	 prints: the resolved `default:`'s digits at the default rung, the `dd`/`mm`/`yyyy`
+	 hint at the label rung. Shown, never written, either way. The marker is the
+	 component's own (see the snippet): the date primitive emits no placeholder
+	 attribute of its own. A seated default is the value and still unwritten, so its
+	 filled segments take the default rung too. */
+	.qm-date-wrap :global(.qm-date-segment[data-ghosted='hint']) {
 		color: var(--_qm-ink-label);
 	}
+	.qm-date-wrap :global(.qm-date-segment[data-ghosted='default']),
+	.qm-date-wrap :global(.qm-date[data-default] .qm-date-segment) {
+		color: var(--_qm-ink-default);
+	}
 </style>

package/dist/visual/EnumField.svelte

@@ -25,6 +25,11 @@
 		value: string | undefined;
 		values: string[];
 		fallback?: string;
+		/** The schema's `ui.blank_title`: what the blank draws as, in place of the em dash. */
+		blankTitle?: string;
+		/** An `enum?` cell, which prints `none` unset rather than its blank, and so ghosts
+		 *  `strings.optionalGhost` there. */
+		optional?: boolean;
 		/** Accessible name for a trigger nothing else names: an object property, whose
 		 * name is the field label plus the property's. A field's own trigger takes `id`
 		 * instead and is named by the `<label for>` beside it (the trigger is a
@@ -47,6 +52,8 @@
 		value,
 		values,
 		fallback,
+		blankTitle,
+		optional = false,
 		label,
 		id,
 		describedBy,
@@ -66,11 +73,15 @@
 	// the package's rather than the primitive's.
 	const local = syncedLocal(() => value ?? UNSET);
 
-	/** An empty enum member has no glyph of its own; an em dash stands in for it. */
-	const dash = (v: string | undefined) => v || '—';
+	/** The blank has no glyph of its own: the quill's `ui.blank_title` stands in for
+	 * it, else an em dash. */
+	const dash = (v: string | undefined) => v || blankTitle || '—';
 
 	const unset = $derived(local.value === UNSET);
-	const ghostText = $derived(dash(fallback));
+	/** The ghost is a member the render prints, rather than a word for the blank or for
+	 *  `none`: it draws at the default rung (theme.css). */
+	const ghostsMember = $derived(!optional && !!fallback);
+	const ghostText = $derived(optional ? t.strings.optionalGhost : dash(fallback));
 	/** What the closed trigger shows: the pick, or the ghosted default while unset. */
 	const shown = $derived(unset ? ghostText : dash(local.value));
 
@@ -102,7 +113,7 @@
 			{id}
 			aria-label={id ? undefined : label}
 			aria-describedby={describedBy}
-			data-ghosted={unset ? '' : undefined}
+			data-ghosted={unset ? (ghostsMember ? 'default' : '') : undefined}
 		>
 			<span class="qm-select-shown">{shown}</span>
 			<Icon name="chevron-down" class="qm-select-chevron" size={14} />
@@ -125,13 +136,17 @@
 						     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. -->
+						<!-- An optional cell's row is untagged: it ghosts no default, and `None`
+						     names no member to tell it from. -->
 						<Select.Item
 							class="qm-menu-item qm-select-item qm-select-unset"
 							value={UNSET}
-							label={`${ghostText} ${t.strings.enumUnsetTag}`}
+							label={optional ? ghostText : `${ghostText} ${t.strings.enumUnsetTag}`}
 						>
 							<span class="qm-select-ghost">{ghostText}</span>
-							<span class="qm-select-tag">{t.strings.enumUnsetTag}</span>
+							{#if !optional}
+								<span class="qm-select-tag">{t.strings.enumUnsetTag}</span>
+							{/if}
 						</Select.Item>
 						<!-- A refused option still draws under `'disable'`, and under either
 						     policy when it is the one selected: a listbox whose selected value
@@ -192,11 +207,14 @@
 		flex-shrink: 0;
 	}
 	/* The focus ring rides `.qm-focus-ring` on the trigger (controls.css). */
-	/* Shown-never-written: the closed control reads muted while unset, matching the
-	   ghosted placeholder the text/number controls show. */
+	/* Shown-never-written: the closed control reads muted while unset, at the rung of
+	   what it shows — the default member the render prints, or a word for the blank. */
 	.qm-select-wrap :global(.qm-select[data-ghosted]) {
 		color: var(--_qm-ink-label);
 	}
+	.qm-select-wrap :global(.qm-select[data-ghosted='default']) {
+		color: var(--_qm-ink-default);
+	}
 	/* The open list is `.qm-menu-surface` and its rows `.qm-menu-item` (controls.css):
 	 the lift, the inset and the highlight are the shared menu recipe. What a listbox
 	 adds over a menu is here: it spans its trigger rather than its own content, it
@@ -229,7 +247,7 @@
 	/* 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"). */
+	   (theme.css, "nothing under the last"). */
 	.qm-select-tag {
 		flex-shrink: 0;
 		font-size: var(--_qm-text-label);

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

@@ -3,6 +3,11 @@ interface Props {
     value: string | undefined;
     values: string[];
     fallback?: string;
+    /** The schema's `ui.blank_title`: what the blank draws as, in place of the em dash. */
+    blankTitle?: string;
+    /** An `enum?` cell, which prints `none` unset rather than its blank, and so ghosts
+     *  `strings.optionalGhost` there. */
+    optional?: boolean;
     /** Accessible name for a trigger nothing else names: an object property, whose
      * name is the field label plus the property's. A field's own trigger takes `id`
      * instead and is named by the `<label for>` beside it (the trigger is a