@quillmark/svelte 0.0.0

package/dist/visual/Field.svelte

@@ -0,0 +1,270 @@
+<!--
+ Type dispatch (VISUAL_EDITOR §"Structure mirrors the schema"). Given one projected
+ {@link FieldModel} and its live value, render the label + the control the type
+ maps to. Array controls own their label (paired with the add affordance in
+ {@link ArrayField}); other types render the label here. Prose leaves take a
+ parent-built LIVE `addr` (its `card` a getter over the stable-id→index map) so
+ a reorder re-targets without a remount; scalars, arrays, and objects commit
+ their value UP through `onCommitScalar`, which the parent lowers to the typed
+ writer.
+
+ `diagnostics` is the routed `Diagnostic[]` for this field (VisualEditor's
+ `diagByKey`, merging `quill.validate`, local commit errors, and the external
+ `diagnostics` prop (VISUAL_EDITOR §Diagnostics)) rendered via the shared
+ `DiagnosticList`, severity-styled, NON-GATING.
+-->
+<script lang="ts">
+	import type { Document, Quill, Addr, Diagnostic, ResolvedField } from '@quillmark/wasm';
+	import type { EditorErrorHandler } from '../core/errors.js';
+	import type { FieldController } from '../core/codec/index.js';
+	import type { FieldModel, FieldSpan } from './structure.js';
+	import { enumValues, ghostDefault, stringifyGhost } from './structure.js';
+	import type { FieldDomIds } from './domid.js';
+	import ProseField from './ProseField.svelte';
+	import TextField from './TextField.svelte';
+	import EnumField from './EnumField.svelte';
+	import NumberField from './NumberField.svelte';
+	import BooleanField from './BooleanField.svelte';
+	import DateField from './DateField.svelte';
+	import ArrayField from './ArrayField.svelte';
+	import ObjectField from './ObjectField.svelte';
+	import DiagnosticList from './DiagnosticList.svelte';
+	import FieldLabel from './FieldLabel.svelte';
+
+	interface Props {
+		field: FieldModel;
+		/** This field's width in the section grid, from `placeFields`. */
+		span: FieldSpan;
+		value: unknown;
+		/** This field's resolved provenance row (FIELD_PROVENANCE): the ghost's
+		 * source. Feeds the placeholder / fallback only, never `value`. */
+		provenance?: ResolvedField;
+		doc: Document;
+		/** The schema a prose leaf reads its content through (`ProseField`). */
+		quill: Quill;
+		/** LIVE prose address (getter-`card`); used only when control === 'prose'. */
+		proseAddr: Addr;
+		leafKey: string;
+		/** This field's three DOM names, derived from `leafKey` (see `domid.ts`): how
+		 * the label and the control find each other. */
+		domIds: FieldDomIds;
+		onCommitScalar: (value: unknown) => void;
+		/** Enum-option policy: `false` disables that option. Only the enum
+		 * control reads it; other controls ignore it. */
+		optionAllowed?: (value: string) => boolean;
+		onFocus?: (addr: Addr) => void;
+		onCaretMove?: (addr: Addr, pos: number) => void;
+		onChange?: (addr: Addr) => void;
+		onError?: EditorErrorHandler;
+		register?: (key: string, controller: FieldController) => void;
+		unregister?: (key: string) => void;
+		diagnostics?: Diagnostic[];
+	}
+	let {
+		field,
+		span,
+		value,
+		provenance,
+		doc,
+		quill,
+		proseAddr,
+		leafKey,
+		domIds,
+		onCommitScalar,
+		optionAllowed,
+		onFocus,
+		onCaretMove,
+		onChange,
+		onError,
+		register,
+		unregister,
+		diagnostics
+	}: Props = $props();
+
+	// The ghost the control shows when unset: the resolved `default:` (provenance,
+	// `source === 'default'`). `ghost` is the raw typed value (enum/number/boolean
+	// fallbacks); `defaultStr` its string form: the text placeholder and the date
+	// control's `YYYY-MM-DD`. An object-valued default does not ghost.
+	const ghost = $derived(ghostDefault(provenance));
+	const defaultStr = $derived(stringifyGhost(ghost));
+
+	// `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.
+	const labelable = $derived(
+		field.control === 'text' ||
+			field.control === 'enum' ||
+			field.control === 'number' ||
+			field.control === 'boolean'
+	);
+	// The parked description node renders only when the schema carries one, so the
+	// reference must vanish with it: `aria-describedby` pointing at nothing describes
+	// nothing, and silently.
+	const describedBy = $derived(field.description ? domIds.description : undefined);
+
+	// Focus handoff for the two controls a label click cannot reach natively. Both
+	// expose their own `focus()` because "focusing" differs: a PM view restores a
+	// selection, a date field lands on its first segment.
+	let proseEl = $state<{ focus: () => void } | undefined>();
+	let dateEl = $state<{ focus: () => void } | undefined>();
+	const onActivate = $derived(
+		field.control === 'prose'
+			? () => proseEl?.focus()
+			: field.control === 'date'
+				? () => dateEl?.focus()
+				: undefined
+	);
+</script>
+
+<div class="qm-field" class:cell={span === 'cell'} class:lone={span === 'lone'}>
+	{#if field.control !== 'array'}
+		<FieldLabel
+			label={field.label}
+			controlId={labelable ? domIds.control : undefined}
+			id={domIds.label}
+			descriptionId={domIds.description}
+			{onActivate}
+			required={field.required}
+			description={field.description}
+		/>
+	{/if}
+	<div class="qm-field-control">
+		{#if field.control === 'prose'}
+			<ProseField
+				{quill}
+				bind:this={proseEl}
+				{doc}
+				addr={proseAddr}
+				inline={field.inline}
+				plaintext={field.plaintext}
+				labelledBy={domIds.label}
+				{describedBy}
+				{leafKey}
+				{onFocus}
+				{onCaretMove}
+				{onChange}
+				{onError}
+				{register}
+				{unregister}
+			/>
+		{:else if field.control === 'enum'}
+			<EnumField
+				value={value as string | undefined}
+				values={enumValues(field.schema) ?? []}
+				fallback={ghost as string | undefined}
+				id={domIds.control}
+				{describedBy}
+				onCommit={onCommitScalar}
+				{optionAllowed}
+			/>
+		{:else if field.control === 'number'}
+			<NumberField
+				value={value as number | undefined}
+				integer={field.schema.type === 'integer'}
+				fallback={ghost as number | undefined}
+				id={domIds.control}
+				{describedBy}
+				onCommit={onCommitScalar}
+			/>
+		{:else if field.control === 'boolean'}
+			<BooleanField
+				value={value as boolean | undefined}
+				fallback={ghost as boolean | undefined}
+				id={domIds.control}
+				{describedBy}
+				onCommit={onCommitScalar}
+			/>
+		{:else if field.control === 'date'}
+			<DateField
+				bind:this={dateEl}
+				value={value as string | undefined}
+				fallback={defaultStr}
+				labelledBy={domIds.label}
+				{describedBy}
+				onCommit={onCommitScalar}
+			/>
+		{:else if field.control === 'array'}
+			<ArrayField
+				value={value as unknown[] | undefined}
+				items={field.schema.items}
+				label={field.label}
+				required={field.required}
+				description={field.description}
+				labelId={domIds.label}
+				descriptionId={domIds.description}
+				onCommit={onCommitScalar}
+				onFocusEl={() => onFocus?.(proseAddr)}
+			/>
+		{:else if field.control === 'object'}
+			<ObjectField
+				value={value as Record<string, unknown> | undefined}
+				properties={field.schema.properties}
+				label={field.label}
+				labelledBy={domIds.label}
+				{describedBy}
+				onCommit={onCommitScalar}
+			/>
+		{:else}
+			<TextField
+				value={value as string | undefined}
+				placeholder={defaultStr}
+				id={domIds.control}
+				{describedBy}
+				onCommit={onCommitScalar}
+			/>
+		{/if}
+	</div>
+
+	<DiagnosticList {diagnostics} />
+</div>
+
+<style>
+	/* The `full` span, and the base every field starts from: its own row, a plain
+	   stack. Nothing shares the row, so there are no internals to align against.
+
+	   THE ACTION COLUMN IS THE FIELD'S INSET, not the section's:
+	   a row action's tap target plus the grid's own column gutter, held clear at the
+	   end of whatever the field spans. On the SECTION it reserves one trailing column
+	   for the whole grid, which reaches only a field that stops short of it. The array
+	   carries the only row action there is, and it always owns its row (structure.ts
+	   `packable`), so it spans that reservation with every other column: the one field
+	   a section could reserve for is the one it would miss. Per field the reservation
+	   travels with the thing that uses it: one right edge per track, every control in a
+	   row ending on it, and an array reaching back across its own to put its remove
+	   past it (ArrayField). Every field pays the width, including one with no action in
+	   it; a right edge that moved with a field's contents is the raggedness this
+	   removes. */
+	.qm-field {
+		display: flex;
+		flex-direction: column;
+		gap: var(--_qm-space);
+		grid-column: 1 / -1;
+		min-width: 0;
+		padding-right: var(--action-col);
+	}
+	/* A row-sharing field subgrids onto the section's row tracks instead of sizing its
+	 own: three tracks (label, control, diagnostics) taken from the parent, so every
+	 control in a visual row starts at the same y however tall a neighbour's label
+	 wrapped, and one field's diagnostic lifts none of the others out of line. Source
+	 order IS track order; `align-items: start` keeps a short control from stretching
+	 to a taller sibling's track. `row-gap` overrides the section's inter-row gutter
+	 for the tracks this field spans: inside a field the rhythm is tighter than
+	 between rows. */
+	.qm-field.cell,
+	.qm-field.lone {
+		display: grid;
+		grid-row: span 3;
+		grid-template-rows: subgrid;
+		row-gap: var(--_qm-space);
+		align-items: start;
+	}
+	.qm-field.cell {
+		grid-column: span 1;
+	}
+	/* A run of one takes half the capacity from column 1: `--cols-half` is the section's
+	 capacity halved, so the edge lands on a track boundary at every capacity. */
+	.qm-field.lone {
+		grid-column: span var(--cols-half);
+	}
+</style>

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

@@ -0,0 +1,37 @@
+import type { Document, Quill, Addr, Diagnostic, ResolvedField } from '@quillmark/wasm';
+import type { EditorErrorHandler } from '../core/errors.js';
+import type { FieldController } from '../core/codec/index.js';
+import type { FieldModel, FieldSpan } from './structure.js';
+import type { FieldDomIds } from './domid.js';
+interface Props {
+    field: FieldModel;
+    /** This field's width in the section grid, from `placeFields`. */
+    span: FieldSpan;
+    value: unknown;
+    /** This field's resolved provenance row (FIELD_PROVENANCE): the ghost's
+     * source. Feeds the placeholder / fallback only, never `value`. */
+    provenance?: ResolvedField;
+    doc: Document;
+    /** The schema a prose leaf reads its content through (`ProseField`). */
+    quill: Quill;
+    /** LIVE prose address (getter-`card`); used only when control === 'prose'. */
+    proseAddr: Addr;
+    leafKey: string;
+    /** This field's three DOM names, derived from `leafKey` (see `domid.ts`): how
+     * the label and the control find each other. */
+    domIds: FieldDomIds;
+    onCommitScalar: (value: unknown) => void;
+    /** Enum-option policy: `false` disables that option. Only the enum
+     * control reads it; other controls ignore it. */
+    optionAllowed?: (value: string) => boolean;
+    onFocus?: (addr: Addr) => void;
+    onCaretMove?: (addr: Addr, pos: number) => void;
+    onChange?: (addr: Addr) => void;
+    onError?: EditorErrorHandler;
+    register?: (key: string, controller: FieldController) => void;
+    unregister?: (key: string) => void;
+    diagnostics?: Diagnostic[];
+}
+declare const Field: import("svelte").Component<Props, {}, "">;
+type Field = ReturnType<typeof Field>;
+export default Field;

package/dist/visual/FieldHint.svelte

@@ -0,0 +1,185 @@
+<!--
+ The schema `description` as a themed floating surface: the second that is READ
+ rather than picked from, so it shares {@link FormatPopover}'s translucent recipe
+ and portals into the nearest `[data-qm-root]` like every
+ other floating surface, so a consumer's dials still reach it.
+
+ It replaces the native `title` tooltip, which reached no dial, waited ~1s, could
+ not be dismissed, and (the part that made it a hole rather than a blemish)
+ DOES NOT EXIST ON TOUCH. Guidance the reference quill puts on nearly every field
+ was, on a tablet, reachable only through a screen reader.
+
+ Floating rather than inline under the label: the reference quill's descriptions run
+ to a median of ~110 characters and past 250 at the tail: permanently in flow that
+ is several wrapped lines under every field, which is the density the card is built
+ to avoid. Measured, not assumed; a quill whose descriptions are all one short line
+ would be better served inline.
+
+ THE POPOVER IS CHROME, NOT THE ANNOUNCEMENT. Its content is `aria-hidden`: the
+ description reaches assistive tech through the always-present parked node
+ {@link FieldLabel} renders and the `aria-describedby` the control carries, which
+ holds whether the surface is open or not. So no reader depends on a hover.
+
+ Three ways in, one per input modality: hover (pointer), focus (keyboard), tap
+ (touch); wired here rather than taken from `Tooltip`, whose trigger returns early
+ on `pointerType === 'touch'` and closes on click (the exact gap being fixed).
+-->
+<script lang="ts">
+	import { Popover } from 'bits-ui';
+	import Icon from './icons/Icon.svelte';
+	import './controls.css';
+
+	interface Props {
+		description: string;
+		/** The field's label: the trigger's own name, so 30 info buttons on a card
+		 * do not all announce alike. */
+		label: string;
+		/** The parked description node; the trigger points at it too, so a reader
+		 * that lands HERE announces the guidance rather than only the field's own. */
+		describedBy?: string;
+	}
+	let { description, label, describedBy }: Props = $props();
+
+	let open = $state(false);
+	let triggerEl = $state<HTMLButtonElement | undefined>(undefined);
+	/** The root to portal INTO: `document.body` would escape the consumer's dials
+	 * along with the editor's subtree. `undefined` falls back to bits-ui's default. */
+	const portalTarget = $derived(triggerEl?.closest<HTMLElement>('[data-qm-root]') ?? undefined);
+</script>
+
+<!-- The trigger is OURS, not `Popover.Trigger`, and the surface anchors to it:
+ the same shape {@link FormatPopover} uses. The primitive's trigger owns a click
+ TOGGLE, which fights every one of the three openings below: a mouse click after
+ a hover-open would close, and on touch the focus that precedes the click opens
+ it just in time for the click to close it again. -->
+<button
+	bind:this={triggerEl}
+	type="button"
+	class="qm-field-hint qm-icon-btn qm-focus-ring"
+	aria-label="{label} guidance"
+	aria-expanded={open}
+	aria-describedby={describedBy}
+	onpointerenter={(e) => {
+		if (e.pointerType !== 'touch') open = true;
+	}}
+	onpointerleave={(e) => {
+		if (e.pointerType !== 'touch') open = false;
+	}}
+	onpointerup={(e) => {
+		// Touch only, and a TOGGLE: the one modality with no hover to leave and no
+		// blur on the way out. A mouse press falls through to hover, which already
+		// has it open and will close it on the way off.
+		if (e.pointerType === 'touch') open = !open;
+	}}
+	onfocus={(e) => {
+		// Keyboard arrival only. A pointer press focuses the button too, and opening
+		// on that would re-open what the tap just toggled shut; `:focus-visible` is
+		// the UA's own answer to which arrival this was.
+		if (e.currentTarget.matches(':focus-visible')) open = true;
+	}}
+	onblur={() => (open = false)}
+	onkeydown={(e) => {
+		if (e.key === 'Escape' && open) {
+			// Dismissable, which the `title` tooltip never was. Stopped here so the
+			// key does not travel on to a card- or editor-level Escape.
+			e.stopPropagation();
+			open = false;
+		}
+	}}><Icon name="info" size={13} /></button
+>
+
+<Popover.Root bind:open>
+	<Popover.Portal to={portalTarget}>
+		<Popover.Content
+			customAnchor={triggerEl ?? null}
+			side="top"
+			align="start"
+			sideOffset={6}
+			trapFocus={false}
+			onOpenAutoFocus={(e: Event) => e.preventDefault()}
+			onCloseAutoFocus={(e: Event) => e.preventDefault()}
+		>
+			<!-- The `child` snippet, the same shape {@link FormatPopover} takes and for
+			 the same reason: the surface is the primitive's own content node, so the
+			 dismissal animation is one the primitive waits on before unmounting.
+			 `data-qm-root` because a portalled subtree is
+			 detached for the derivation's purposes, and the marker is what applies
+			 it; `wrapperProps` is floating-ui's positioning box, spread and never
+			 styled. `inert` is the half of the dismissal the recipe cannot carry: the
+			 surface is still on screen for the length of the fade, and one on its way
+			 out is not a thing to click. -->
+			{#snippet child({ props, wrapperProps, open: raised })}
+				<div {...wrapperProps}>
+					<div
+						{...props}
+						class="qm-hint-popover qm-popover-surface"
+						data-qm-root
+						aria-hidden="true"
+						inert={!raised}
+					>
+						{description}
+					</div>
+				</div>
+			{/snippet}
+		</Popover.Content>
+	</Popover.Portal>
+</Popover.Root>
+
+<style>
+	/* Chrome, type and ring are the glyph-button family's (`.qm-icon-btn` +
+	 `.qm-focus-ring`, controls.css): this trigger is one more glyph button and
+	 assembles none of that itself. What it does NOT take is the family's tap floor
+	 and the fill that floor sizes, because this is the one glyph button that sits in
+	 a LINE OF TEXT rather than in a row of its own: the floor is half again the label
+	 rung's line box, so a target-sized paint box overhangs the line at each end by
+	 most of the field's label-to-control gap: the hover fill landing on the input's
+	 top border, the focus ring crossing it.
+
+	 So the box is the GLYPH and the target is the `::after` below. A target is a
+	 region of the screen, not a paint box, and separating them is what lets both be
+	 correct at once: the row keeps the line box's height and the press keeps the
+	 floor. Every other glyph button has a row to itself and keeps the floor as its
+	 box.
+
+	 It takes no fill either: the ink step below says hover, and the surface itself
+	 opens on it. */
+	.qm-field-hint {
+		/* The marker recedes to the label's ghost tone; the surface carries the text. */
+		color: var(--_qm-ink-ghost);
+		/* Not the family's `pointer`: the glyph raises guidance, it does not act. */
+		cursor: help;
+		position: relative;
+		min-width: 0;
+		min-height: 0;
+		padding: 0;
+		background: none;
+	}
+	/* The tap floor, out of flow and centred on the glyph: WCAG 2.5.8 measures the
+	 target, and this is it. Unpainted, so it enlarges the press and not the mark, and
+	 out of the accessibility tree by construction: a pseudo-element has no node. */
+	.qm-field-hint::after {
+		content: '';
+		position: absolute;
+		top: 50%;
+		left: 50%;
+		width: var(--_qm-tap-min);
+		height: var(--_qm-tap-min);
+		transform: translate(-50%, -50%);
+	}
+	.qm-field-hint:hover,
+	.qm-field-hint:focus-visible {
+		color: var(--_qm-ink-meta);
+	}
+	/* The lift, the translucency, the blur and the scale-in come from
+	 `.qm-popover-surface` (controls.css). This surface's own is a MEASURE: guidance
+	 is prose, and prose past ~40 characters a line stops being scannable; plus the
+	 inset and the meta type rung that keep it a note about a field rather than a
+	 second field. */
+	.qm-hint-popover {
+		max-width: 22rem;
+		padding: var(--_qm-space) var(--_qm-space-2);
+		font-size: var(--_qm-text-meta);
+		line-height: var(--_qm-leading-body);
+		color: var(--_qm-ink-meta);
+	}
+</style>

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

@@ -0,0 +1,13 @@
+import './controls.css';
+interface Props {
+    description: string;
+    /** The field's label: the trigger's own name, so 30 info buttons on a card
+     * do not all announce alike. */
+    label: string;
+    /** The parked description node; the trigger points at it too, so a reader
+     * that lands HERE announces the guidance rather than only the field's own. */
+    describedBy?: string;
+}
+declare const FieldHint: import("svelte").Component<Props, {}, "">;
+type FieldHint = ReturnType<typeof FieldHint>;
+export default FieldHint;

package/dist/visual/FieldLabel.svelte

@@ -0,0 +1,141 @@
+<!--
+ A field's label plus its guidance chrome.
+
+ IT NAMES THE CONTROL. A real `<label>`, so a click lands the caret in the field:
+ the widest, easiest target in a dense row, and the most conventional affordance a
+ form has. `for` reaches a LABELABLE control (the inputs, the enum trigger, the
+ switch) and the browser does the rest; a control `for` cannot reach (the prose
+ leaf's `contenteditable`, the date field's segments, an array's N inputs) leaves
+ `controlId` unset, points `aria-labelledby` back at this label's own `id`, and
+ hands the click to `onActivate`. Both halves are needed: `for` on a non-labelable
+ element is inert AND invalid.
+
+ Two non-gating label decorations:
+ • a persistent required `*` when the field has no `default:`: the
+ "Unendorsed"/must_fill set (DOCUMENT_MODEL: no separate `required` axis). 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;
+
+ • the `description` as an info marker raising a themed popover
+ ({@link FieldHint}).
+
+ THE DESCRIPTION DESCRIBES, IT DOES NOT NAME. It is parked in an always-present
+ visually-hidden node here and the control carries `aria-describedby`: name then
+ role then description, which is the announcement the markup visually implies. In
+ the name it would instead prepend ~110 characters of guidance (the reference
+ quill's median) to every field's label on every focus. Parked rather than read off
+ the popover because the popover exists only while open, and a dangling
+ `aria-describedby` describes nothing.
+
+ Shared by {@link Field} (scalars, object, prose) and {@link ArrayField} so every
+ control's label decorates the same way.
+-->
+<script lang="ts">
+	import { wording } from './strings.js';
+
+	// The surface's words, ambient from the editor root; the package's English
+	// off-tree, so this component renders standalone too.
+	const t = wording();
+	import FieldHint from './FieldHint.svelte';
+
+	interface Props {
+		label: string;
+		/** The labelable control this names: a `for` target. Unset for a control
+		 * `for` cannot reach, which takes `id` + `onActivate` instead. */
+		controlId?: string;
+		/** This label's own id: what such a control's `aria-labelledby` points at. */
+		id?: string;
+		/** Where the description parks for the control's `aria-describedby`. */
+		descriptionId?: string;
+		/** Focus handoff for a control `for` cannot reach; a label click calls it. */
+		onActivate?: () => void;
+		/** No-default field → a persistent required `*`. */
+		required?: boolean;
+		/** Schema `description`, or undefined: the affordance renders only when set. */
+		description?: string;
+	}
+	let { label, controlId, id, descriptionId, onActivate, required, description }: Props = $props();
+</script>
+
+<div class="qm-field-label-row">
+	<!-- svelte-ignore a11y_no_noninteractive_element_interactions, a11y_click_events_have_key_events -->
+	<!-- The handler stands in for exactly what `for` would have done, on the controls
+	     where `for` is inert. It adds no keyboard surface because it needs none: a
+	     label is not a tab stop, and the control it hands focus to is already the
+	     keyboard's own way in. -->
+	<label
+		class="qm-field-label"
+		class:targeted={controlId != null || onActivate != null}
+		{id}
+		for={controlId}
+		onclick={onActivate}
+	>
+		<span>{label}</span>
+		{#if required}
+			<span class="qm-field-required" aria-label={t.strings.fieldRequired}>*</span>
+		{/if}
+	</label>
+	{#if description}
+		<!-- OUTSIDE the `<label>`, both of them: a trigger inside it would put its own
+		 name in the control's, and the parked copy would put all ~110 characters
+		 there. A `<button>` in a label is at least safe from the other hazard:
+		 the spec makes a label's activation behaviour do nothing for a click
+		 targeted at interactive content inside it; but the naming is reason
+		 enough to keep both out. -->
+		<FieldHint {description} {label} describedBy={descriptionId} />
+		<span class="qm-visually-hidden" id={descriptionId}>{description}</span>
+	{/if}
+</div>
+
+<style>
+	/* The row, not the label, is the field's grid child: `Field`'s subgrid counts
+	 three tracks and the hint sits beside the label rather than under it.
+
+	 A rung wider than the label's own gap below, so the two separations rank: the
+	 required glyph is part of the name and sits at the tighter one, the guidance
+	 marker is a second affordance beside it. The marker's box is its glyph
+	 (`FieldHint`), so this gap is the whole of what stands between them. */
+	.qm-field-label-row {
+		display: flex;
+		align-items: center;
+		gap: var(--_qm-space);
+		min-width: 0;
+	}
+	.qm-field-label {
+		display: inline-flex;
+		align-items: center;
+		gap: var(--_qm-space-half);
+		font-size: var(--_qm-text-label);
+		font-weight: var(--_qm-weight-label);
+		line-height: var(--_qm-leading-tight);
+		color: var(--_qm-ink-label);
+		min-width: 0;
+	}
+	/* A label that lands focus says so. Only when it has somewhere to land: an
+	   `ObjectField` property's label names a subform, not one control. */
+	.qm-field-label.targeted {
+		cursor: pointer;
+	}
+	/* Required marker: a quiet accent glyph, not an alarm; required-ness is guidance,
+	 the document still edits and renders unmet. */
+	.qm-field-required {
+		display: inline-flex;
+		align-items: center;
+		color: var(--_qm-danger);
+		line-height: 1;
+	}
+	/* The parked description: in the accessibility tree, out of the layout, and never
+	 a focus stop. Clipped rather than `display: none` / `hidden`, which take a node
+	 out of the tree entirely and would make the `aria-describedby` dangle. Out of
+	 flow, so the classic recipe's `margin: -1px` has nothing left to counteract:
+	 and it would mint a literal off every rung. */
+	.qm-visually-hidden {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+	}
+</style>

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

@@ -0,0 +1,19 @@
+interface Props {
+    label: string;
+    /** The labelable control this names: a `for` target. Unset for a control
+     * `for` cannot reach, which takes `id` + `onActivate` instead. */
+    controlId?: string;
+    /** This label's own id: what such a control's `aria-labelledby` points at. */
+    id?: string;
+    /** Where the description parks for the control's `aria-describedby`. */
+    descriptionId?: string;
+    /** Focus handoff for a control `for` cannot reach; a label click calls it. */
+    onActivate?: () => void;
+    /** No-default field → a persistent required `*`. */
+    required?: boolean;
+    /** Schema `description`, or undefined: the affordance renders only when set. */
+    description?: string;
+}
+declare const FieldLabel: import("svelte").Component<Props, {}, "">;
+type FieldLabel = ReturnType<typeof FieldLabel>;
+export default FieldLabel;